# The ITSI Command Line Interface (CLI)
## Setup Virtualenv
```
python3 -m venv /path/to/new/virtual/environment
source /path/to/new/virtual/environment/bin/activate
```
For more info about venv, click [here](https://docs.python.org/3/library/venv.html).
## ```itsi-content-pack``` overview
The `itsi-content-pack` command assists in creating and managing ITSI Content Packs. The main functionality is to convert an itsi backup zip file into Splunk App for Content Packs supported format for itsi objects. Supported backup version is 4.9.0
The general end-to-end workflow is as follows with example provided in each step:
## Dependencies
The `itsi-content-pack` command depends on the ```itsimodels``` python module to convert an itsi backup to itsi object jsons used by Splunk App for Content Packs. Here's [source link](https://github.com/splunk/itsi-models) to ```itsimodels```. The packaged ```itsimodule``` is published [here](https://pypi.org/project/itsimodels/) on PyPI, and can be installed via pip (see below).
## Steps to create content pack
- [Clone the repos](#clone-the-repos)
- [Prep your environment](#prep-your-environment)
- [Initialize content pack](#initialize-content-pack)
- [Import itsi backup](#import-itsi-backup)
### Clone the repos
Clone the following repos on your local box. It is recommended that you do this on a linux box.
- [itsi-cli](https://github.com/splunk/itsi-cli) (current repo)
- [itsi-models](https://github.com/splunk/itsi-models)
- [itsi-content](https://github.com/splunk/itsi-content)
### Prep your environment
- Install the latest dependent python packages
```
pip install --upgrade itsicli
pip install --upgrade itsimodels
```
- Update PATH to include `itsi-cli/bin` so we can invoke `itsi-content-pack` command from anywhere:
```export PATH=$PATH:<path to itsi-cli/bin>```
>Example:
>
>export PATH=$PATH:/my/git/itsi-cli/bin
:bulb: If you are a developer working on fixing itsicli or itsimodels and would like to test with unpublished changes in your own environment, then set your PYTHONPATH to include `itsi-models` and `itsi-cli` top level folders to utilize your local changes:
```
export PYTHONPATH=<path to itsi-cli>:<path to itsi-models>
```
>Example:
>
>export PYTHONPATH=/my/git/itsi-cli:/my/git/itsi-models
### Initialize content pack
This step only needs to be done once if you are starting fresh content pack. You can always remove the directory created below and start over if needed. Steps below shows how to create a new content pack in your local clone of ```itsi-content``` repo. You can always create the content pack in some other folder on your system and then copy into [src]((https://github.com/splunk/itsi-content/tree/main/src)) of your ```itsi-content``` folder when you are ready to test/build/push changes.
- Create a new git branch for your changes in your local clone of ```itsi-content```
- Create an empty folder under [src]((https://github.com/splunk/itsi-content/tree/main/src)) of your local clone of itsi-content repo
```mkdir DA-ITSI-CP-<your-cp-name>```
This will be the main folder of your content pack, see other content pack folders [here](https://github.com/splunk/itsi-content/tree/main/src).
- Go into the folder you just created
```cd DA-ITSI-CP-<your-cp-name>```
- Create skeleton files/folders
```itsi-content-pack init```
Follow the prompt to provide a content pack id and title. Please prefix id with `DA-ITSI-CP-`. Once completed, you should see the following folders and files created
```
├── appserver
│ └── static
│ └── screenshots
├── default
│ └── app.conf
└── itsi
├── README.md
├── config.json
└── manifest.json
```
You should update README.md to explain what your content pack is for. See other content packs for inspirations. You should also add thumbnails and screenshots for your content pack.
### Import itsi backup
Once the content pack is initialized, you can create content pack ITSI objects by importing your itsi backup zip file. Perform the command from within your ```DA-ITSI-CP-<your-cp-name>``` directory.
```
itsi-content-pack importbackup <path-to-backup-zip-file>
```
>Example:
>
>itsi-content-pack importbackup /full/path/to/my_cp_itsi_partial_backup490.zip
You will see logging messages and maybe some warnings as well. Take a look at the warnings to see if there are any real issues.
You can rerun this step many times. You may want to first backup your previous ```DA-ITSI-CP-<your-cp-name>\itsi``` folder for comparison/backup before you run ```importbackup``` again.
### Continue to add, remove, or edit content from the Content Pack
You can add or remove objects inside each object type directory, make sure to update manifest.json as part of your changes.
### Add any supporting Splunk knowledge objects
This DA-ITSI-CP-* is a Splunk app, so feel free to add lookups, transforms, props, etc that are Splunk compatible.
### Validate the Content Pack through the `validate` command
Inside DA-ITSI-CP-*, run following command to validate if this content pack is compatible with ITSI.
```
itsi-content-pack validate
```
# Submit content pack
Please follow README in itsi-content repo
### Build content pack app
### Install content pack app
### Install your content pack
### Submit content pack via PR
Submit the Content Pack to either:
- Splunkbase (must first run the `build` command)
- The ITSI Splunk App for Content Packs via a pull request on Github repo: itsi-content
# Build the itsicli distribution archive and upload it to PyPi
For releasing the packages you must have Maintainer access on PyPi
There are two ways:
- [Build and release itsicli packages manually](#build-and-release-itsicli-packages-manually)
- [Build and release itsicli packages automatically](#build-and-release-itsicli-packages-automatically)
## Build and release itsicli packages manually
:exclamation: __Please build the package on linux box__
Install the build dependencies:
```
pip install --upgrade setuptools wheel
```
### Generate the Python package
Clean up distribution:
```
make clean
```
Generate the Python distribution archive:
```
make
```
### Upload to the Python Package Index
Install the dependencies required for uploading to the index:
```
pip install --upgrade twine
```
Upload to PyPI:
```
make upload
```
## Build and release itsicli packages automatically
- On the left sidebar, select CI/CD > Pipelines.
- Select Run Pipeline.
- In the Run for branch name select the branch to run the pipeline for.
- Select Run pipeline.
- base_stage job will run automatically
- sast and whitesource_python are manual jobs that do not need to be triggered if you are trying to release the packages on PyPi.
- After successfully completion of previous job you have to click on the Settings icon of `build` job to fill variables for providing username and password
- Fill the data as follows
```text
Key: username
Value: <username of PYPI>
```
```text
Key: password
Value: <password of PYPI>
```
- Click on `Trigger this manual action` to start the pipeline
- Please wait for the `build` job to complete
## Troubleshooting
Log file name:
```
itsi_contentpacks_itsicli.log
itsi_contentpacks_itsimodels.log
```
If you have $SPLUNK_HOME environment set, then you can find the log file in:
```
$SPLUNK_HOME/var/log/splunk/
```
Otherwise, you will find the log file in ```~/```
Raw data
{
"_id": null,
"home_page": "https://github.com/splunk/itsi-cli",
"name": "itsicli",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Splunk, Inc.",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/35/99/a6551f21d7b128ab50d57d77f0f859b92952aa80c5f0e199b25730e5b26e/itsicli-0.0.38.2.tar.gz",
"platform": null,
"description": "# The ITSI Command Line Interface (CLI)\n\n## Setup Virtualenv\n\n\n```\npython3 -m venv /path/to/new/virtual/environment\n\nsource /path/to/new/virtual/environment/bin/activate\n```\nFor more info about venv, click [here](https://docs.python.org/3/library/venv.html).\n\n## ```itsi-content-pack``` overview\n\nThe `itsi-content-pack` command assists in creating and managing ITSI Content Packs. The main functionality is to convert an itsi backup zip file into Splunk App for Content Packs supported format for itsi objects. Supported backup version is 4.9.0\n\nThe general end-to-end workflow is as follows with example provided in each step:\n\n## Dependencies\nThe `itsi-content-pack` command depends on the ```itsimodels``` python module to convert an itsi backup to itsi object jsons used by Splunk App for Content Packs. Here's [source link](https://github.com/splunk/itsi-models) to ```itsimodels```. The packaged ```itsimodule``` is published [here](https://pypi.org/project/itsimodels/) on PyPI, and can be installed via pip (see below).\n\n## Steps to create content pack\n\n- [Clone the repos](#clone-the-repos)\n- [Prep your environment](#prep-your-environment)\n- [Initialize content pack](#initialize-content-pack)\n- [Import itsi backup](#import-itsi-backup)\n\n### Clone the repos\nClone the following repos on your local box. It is recommended that you do this on a linux box.\n\n- [itsi-cli](https://github.com/splunk/itsi-cli) (current repo)\n- [itsi-models](https://github.com/splunk/itsi-models)\n- [itsi-content](https://github.com/splunk/itsi-content)\n\n\n### Prep your environment\n- Install the latest dependent python packages\n ```\n pip install --upgrade itsicli\n pip install --upgrade itsimodels\n ```\n\n\n- Update PATH to include `itsi-cli/bin` so we can invoke `itsi-content-pack` command from anywhere:\n\n ```export PATH=$PATH:<path to itsi-cli/bin>```\n \n >Example:\n >\n >export PATH=$PATH:/my/git/itsi-cli/bin\n\n\n:bulb: If you are a developer working on fixing itsicli or itsimodels and would like to test with unpublished changes in your own environment, then set your PYTHONPATH to include `itsi-models` and `itsi-cli` top level folders to utilize your local changes:\n```\nexport PYTHONPATH=<path to itsi-cli>:<path to itsi-models>\n```\n>Example:\n>\n>export PYTHONPATH=/my/git/itsi-cli:/my/git/itsi-models\n\n### Initialize content pack\nThis step only needs to be done once if you are starting fresh content pack. You can always remove the directory created below and start over if needed. Steps below shows how to create a new content pack in your local clone of ```itsi-content``` repo. You can always create the content pack in some other folder on your system and then copy into [src]((https://github.com/splunk/itsi-content/tree/main/src)) of your ```itsi-content``` folder when you are ready to test/build/push changes.\n\n- Create a new git branch for your changes in your local clone of ```itsi-content```\n\n- Create an empty folder under [src]((https://github.com/splunk/itsi-content/tree/main/src)) of your local clone of itsi-content repo\n\n ```mkdir DA-ITSI-CP-<your-cp-name>```\n \n This will be the main folder of your content pack, see other content pack folders [here](https://github.com/splunk/itsi-content/tree/main/src). \n \n- Go into the folder you just created\n\n ```cd DA-ITSI-CP-<your-cp-name>```\n \n- Create skeleton files/folders\n\n ```itsi-content-pack init```\n \n Follow the prompt to provide a content pack id and title. Please prefix id with `DA-ITSI-CP-`. Once completed, you should see the following folders and files created \n \n ```\n \u251c\u2500\u2500 appserver\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 static\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 screenshots\n \u251c\u2500\u2500 default\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 app.conf\n \u2514\u2500\u2500 itsi\n \u251c\u2500\u2500 README.md\n \u251c\u2500\u2500 config.json\n \u2514\u2500\u2500 manifest.json\n ```\n You should update README.md to explain what your content pack is for. See other content packs for inspirations. You should also add thumbnails and screenshots for your content pack.\n \n\n\n### Import itsi backup\nOnce the content pack is initialized, you can create content pack ITSI objects by importing your itsi backup zip file. Perform the command from within your ```DA-ITSI-CP-<your-cp-name>``` directory.\n```\nitsi-content-pack importbackup <path-to-backup-zip-file>\n```\n\n>Example:\n>\n>itsi-content-pack importbackup /full/path/to/my_cp_itsi_partial_backup490.zip\n\n\nYou will see logging messages and maybe some warnings as well. Take a look at the warnings to see if there are any real issues.\n\nYou can rerun this step many times. You may want to first backup your previous ```DA-ITSI-CP-<your-cp-name>\\itsi``` folder for comparison/backup before you run ```importbackup``` again. \n\n### Continue to add, remove, or edit content from the Content Pack\nYou can add or remove objects inside each object type directory, make sure to update manifest.json as part of your changes.\n\n\n### Add any supporting Splunk knowledge objects\nThis DA-ITSI-CP-* is a Splunk app, so feel free to add lookups, transforms, props, etc that are Splunk compatible.\n\n\n### Validate the Content Pack through the `validate` command\nInside DA-ITSI-CP-*, run following command to validate if this content pack is compatible with ITSI.\n\n```\nitsi-content-pack validate\n```\n\n# Submit content pack\n\nPlease follow README in itsi-content repo\n### Build content pack app\n### Install content pack app\n### Install your content pack\n### Submit content pack via PR\nSubmit the Content Pack to either:\n - Splunkbase (must first run the `build` command)\n - The ITSI Splunk App for Content Packs via a pull request on Github repo: itsi-content\n\n\n# Build the itsicli distribution archive and upload it to PyPi\nFor releasing the packages you must have Maintainer access on PyPi\n \nThere are two ways:\n- [Build and release itsicli packages manually](#build-and-release-itsicli-packages-manually)\n- [Build and release itsicli packages automatically](#build-and-release-itsicli-packages-automatically)\n## Build and release itsicli packages manually\n\n:exclamation: __Please build the package on linux box__\n\nInstall the build dependencies:\n```\npip install --upgrade setuptools wheel\n```\n\n### Generate the Python package\nClean up distribution:\n```\nmake clean\n```\n\nGenerate the Python distribution archive:\n```\nmake\n```\n\n### Upload to the Python Package Index\n\nInstall the dependencies required for uploading to the index:\n\n```\npip install --upgrade twine\n```\n\nUpload to PyPI:\n\n```\nmake upload\n```\n## Build and release itsicli packages automatically\n- On the left sidebar, select CI/CD > Pipelines. \n- Select Run Pipeline.\n- In the Run for branch name select the branch to run the pipeline for.\n- Select Run pipeline.\n- base_stage job will run automatically\n- sast and whitesource_python are manual jobs that do not need to be triggered if you are trying to release the packages on PyPi.\n- After successfully completion of previous job you have to click on the Settings icon of `build` job to fill variables for providing username and password\n- Fill the data as follows\n ```text\n Key: username\n Value: <username of PYPI> \n ```\n ```text\n Key: password\n Value: <password of PYPI> \n ```\n- Click on `Trigger this manual action` to start the pipeline\n- Please wait for the `build` job to complete\n\n## Troubleshooting\n\nLog file name:\n```\nitsi_contentpacks_itsicli.log\nitsi_contentpacks_itsimodels.log\n```\n\nIf you have $SPLUNK_HOME environment set, then you can find the log file in:\n```\n$SPLUNK_HOME/var/log/splunk/\n```\nOtherwise, you will find the log file in ```~/```\n\n",
"bugtrack_url": null,
"license": "",
"summary": "The ITSI Command Line Interface (CLI)",
"version": "0.0.38.2",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ff7251fdcacf0639870559bad717babdd6b7c496f5ea50b2c7d8556f83059cc5",
"md5": "b374c1ecd13f65aa1e302ef7a2cec903",
"sha256": "c2e3d390c49117ccbf7c1b75ac307fc35df26c88e8c5aa81e3f0e8e20712e390"
},
"downloads": -1,
"filename": "itsicli-0.0.38.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b374c1ecd13f65aa1e302ef7a2cec903",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 37465,
"upload_time": "2023-01-10T03:13:15",
"upload_time_iso_8601": "2023-01-10T03:13:15.949964Z",
"url": "https://files.pythonhosted.org/packages/ff/72/51fdcacf0639870559bad717babdd6b7c496f5ea50b2c7d8556f83059cc5/itsicli-0.0.38.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3599a6551f21d7b128ab50d57d77f0f859b92952aa80c5f0e199b25730e5b26e",
"md5": "957cd3d5a04dbee92bd8e6f8dfc02069",
"sha256": "ef50a4b2a4943bc0b4a414c61adabbcc84f0be64c405432204f5b624e2aa6802"
},
"downloads": -1,
"filename": "itsicli-0.0.38.2.tar.gz",
"has_sig": false,
"md5_digest": "957cd3d5a04dbee92bd8e6f8dfc02069",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 29880,
"upload_time": "2023-01-10T03:13:17",
"upload_time_iso_8601": "2023-01-10T03:13:17.600849Z",
"url": "https://files.pythonhosted.org/packages/35/99/a6551f21d7b128ab50d57d77f0f859b92952aa80c5f0e199b25730e5b26e/itsicli-0.0.38.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-10 03:13:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "splunk",
"github_project": "itsi-cli",
"lcname": "itsicli"
}
JSON
