# NetBox Script Manager
Improved custom script support for netbox. Netbox version 3.5 removed several features related to custom scripts. This plugin attempts to undo these changes and add other improvements to scripts in netbox.
The plugin can be used in addition to the built-in script support and does not disable any netbox features.
## Features
* Scripts can be stored in nested modules.
* Scripts can rely on non-script module files.
* Scripts are loaded from a file-system folder.
* It's possible to sync scripts by pulling any git repo located in the `SCRIPT_ROOT`
* Name, group, description, task queues, comments and tags are editable in the UI.
* Task queue is selectable in the UI.
* Exceptions caused by errors in script files are displayed in the UI.
* Log messages are saved and displayed when the script is running allowing live output for long running scripts.
* It's possible to filter log lines by message and/or log level.
* Changelog entries are listed in a tab when viewing a finished script execution.
* It's possible to save script artifacts during the execution of a script. These artifacts will show up as downloadable files.
* It's possible to re-run scripts.
## What is not supported
* Reports
* DataSource/DataFile
* `load_json` and `load_yaml` convenience methods
* `script_order` - the ordering of scripts is instead based on `group` and `weight`
## Compatibility
| NetBox Version | Plugin Version |
|----------------|----------------|
| 3.5 | 0.1.0 |
| 4.1 | 1.0.0 |
## Installing
Add the plugin to `local_requirements.txt` or `plugin_requirements.txt` (netbox-docker):
```
netbox-script-manager
```
Enable the plugin in `/opt/netbox/netbox/netbox/configuration.py`,
or if you use netbox-docker, your `/configuration/plugins.py` file:
```python
PLUGINS = [
'netbox_script_manager'
]
PLUGINS_CONFIG = {
"netbox_script_manager": {
"SCRIPT_ROOT": "/path/to/script/folder/",
"DEFAULT_QUEUE": "high"
},
}
```
## Configuration
The following options are required:
* `SCRIPT_ROOT`: Path to the script folder containing the customscripts module.
The following options are optional:
* `DEFAULT_QUEUE`: Specifies what queue scripts are run in by default. Defaults to the `default` queue.
## Migrating scripts
The most important change is to change the import and name of the base `Script` class.
Netbox Script:
```python
from extras.scripts import Script
class MyCustomScript(Script):
...
```
Netbox Script Manager Script:
```python
from netbox_script_manager.scripts import CustomScript
class MyCustomScript(CustomScript):
...
```
It is strongly recommended to do relative imports in your scripts, when using a nested structure or utility code.
```python
from .util import my_utility_method
from ..subfolder import myCustomScript
```
The alternative is to do an absolute import:
```python
from customscripts.nested_folder.util import my_utility_method
from customscripts.subfolder import myCustomScript
```
Please see the `Script folder` section for instructions regarding folder structure.
## Script folder
The loading of scripts is a little different with netbox-script-manager. The `SCRIPT_ROOT` plugin setting must be set to define the path of the custom scripts, however the scripts must be located in a folder named `customscripts` in this path.
A folder structure like this is required (`SCRIPT_ROOT` pointing to the `netboxscripts` folder):
```bash
├── netboxscripts # SCRIPT_ROOT
│ ├── customscripts # Scripts will be discovered in this module, must be present
│ │ ├── __init__.py
│ │ ├── nestedmodule
│ │ ├── root_script.py
│ │ └── util
│ └── __init__.py
```
The reason for requiring this layout with a `customscripts` folder is to avoid name collisions when dynamically loading scripts. It also makes it easier to clear the internal python module cache which is needed for reloading scripts.
Loading scripts is done either through the UI by pressing the `Load Scripts` button on the script view, or by calling the API endpoint `/api/plugins/script-manager/script-instances/load/`. Both of these require that the user has the `Can Add` action for the `Script Instance` object permission.
## Git Sync
> :grey_exclamation: git must be installed on the system.
> :grey_exclamation: The netbox user must have the `sync` additional action for the `Script Instance` object permission.
> :warning: git recurses parent directories until finding a git directory. Make sure the `SCRIPT_ROOT` is a git directory.
Netbox Script Manager has basic support for pulling down changes for git repositories. The Sync button is located on the script list and simply calls `git pull` on in the `SCRIPT_ROOT/customscripts` folder. If the git reposity requires authentication, it's recommended to setup SSH auth for the repo and provide the key in the users `$HOME/.ssh` folder.
If more advanced syncing is required, its recommended to handle this outside of netbox or alternatively use a custom script to do the sync.
## Screenshots
TODO
Raw data
{
"_id": null,
"home_page": "https://github.com/kkthxbye-code/netbox_script_manager",
"name": "netbox-script-manager",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "netbox, netbox-plugin",
"author": "kkthxbye-code",
"author_email": "festll234@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fc/86/14df81b2bda73be3bf5e1bb2ee03e8350a39c2421a047a51e2db3f710bdc/netbox_script_manager-1.0.1.tar.gz",
"platform": null,
"description": "# NetBox Script Manager\n\nImproved custom script support for netbox. Netbox version 3.5 removed several features related to custom scripts. This plugin attempts to undo these changes and add other improvements to scripts in netbox.\n\nThe plugin can be used in addition to the built-in script support and does not disable any netbox features.\n\n## Features\n\n* Scripts can be stored in nested modules.\n* Scripts can rely on non-script module files.\n* Scripts are loaded from a file-system folder.\n* It's possible to sync scripts by pulling any git repo located in the `SCRIPT_ROOT`\n* Name, group, description, task queues, comments and tags are editable in the UI.\n* Task queue is selectable in the UI.\n* Exceptions caused by errors in script files are displayed in the UI.\n* Log messages are saved and displayed when the script is running allowing live output for long running scripts.\n* It's possible to filter log lines by message and/or log level.\n* Changelog entries are listed in a tab when viewing a finished script execution.\n* It's possible to save script artifacts during the execution of a script. These artifacts will show up as downloadable files.\n* It's possible to re-run scripts.\n\n## What is not supported\n\n* Reports\n* DataSource/DataFile\n* `load_json` and `load_yaml` convenience methods\n* `script_order` - the ordering of scripts is instead based on `group` and `weight`\n\n## Compatibility\n\n| NetBox Version | Plugin Version |\n|----------------|----------------|\n| 3.5 | 0.1.0 |\n| 4.1 | 1.0.0 |\n\n\n## Installing\n\nAdd the plugin to `local_requirements.txt` or `plugin_requirements.txt` (netbox-docker):\n\n```\nnetbox-script-manager\n```\n\nEnable the plugin in `/opt/netbox/netbox/netbox/configuration.py`,\n or if you use netbox-docker, your `/configuration/plugins.py` file:\n\n```python\nPLUGINS = [\n 'netbox_script_manager'\n]\n\nPLUGINS_CONFIG = {\n \"netbox_script_manager\": {\n \"SCRIPT_ROOT\": \"/path/to/script/folder/\",\n \"DEFAULT_QUEUE\": \"high\"\n },\n}\n```\n\n## Configuration\n\nThe following options are required:\n\n* `SCRIPT_ROOT`: Path to the script folder containing the customscripts module. \n\nThe following options are optional:\n\n* `DEFAULT_QUEUE`: Specifies what queue scripts are run in by default. Defaults to the `default` queue.\n\n\n## Migrating scripts\n\nThe most important change is to change the import and name of the base `Script` class.\n\nNetbox Script:\n\n```python\nfrom extras.scripts import Script\n\nclass MyCustomScript(Script):\n...\n```\n\nNetbox Script Manager Script:\n\n```python\nfrom netbox_script_manager.scripts import CustomScript\n\nclass MyCustomScript(CustomScript):\n...\n```\n\nIt is strongly recommended to do relative imports in your scripts, when using a nested structure or utility code.\n\n```python\nfrom .util import my_utility_method\nfrom ..subfolder import myCustomScript\n```\n\nThe alternative is to do an absolute import:\n\n```python\nfrom customscripts.nested_folder.util import my_utility_method\nfrom customscripts.subfolder import myCustomScript\n```\n\nPlease see the `Script folder` section for instructions regarding folder structure.\n\n## Script folder\n\nThe loading of scripts is a little different with netbox-script-manager. The `SCRIPT_ROOT` plugin setting must be set to define the path of the custom scripts, however the scripts must be located in a folder named `customscripts` in this path.\n\nA folder structure like this is required (`SCRIPT_ROOT` pointing to the `netboxscripts` folder):\n\n```bash\n\u251c\u2500\u2500 netboxscripts # SCRIPT_ROOT\n\u2502 \u251c\u2500\u2500 customscripts # Scripts will be discovered in this module, must be present\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 nestedmodule\n\u2502 \u2502 \u251c\u2500\u2500 root_script.py\n\u2502 \u2502 \u2514\u2500\u2500 util\n\u2502 \u2514\u2500\u2500 __init__.py\n```\n\nThe reason for requiring this layout with a `customscripts` folder is to avoid name collisions when dynamically loading scripts. It also makes it easier to clear the internal python module cache which is needed for reloading scripts.\n\nLoading scripts is done either through the UI by pressing the `Load Scripts` button on the script view, or by calling the API endpoint `/api/plugins/script-manager/script-instances/load/`. Both of these require that the user has the `Can Add` action for the `Script Instance` object permission.\n\n## Git Sync\n\n> :grey_exclamation: git must be installed on the system.\n\n> :grey_exclamation: The netbox user must have the `sync` additional action for the `Script Instance` object permission.\n\n> :warning: git recurses parent directories until finding a git directory. Make sure the `SCRIPT_ROOT` is a git directory.\n\nNetbox Script Manager has basic support for pulling down changes for git repositories. The Sync button is located on the script list and simply calls `git pull` on in the `SCRIPT_ROOT/customscripts` folder. If the git reposity requires authentication, it's recommended to setup SSH auth for the repo and provide the key in the users `$HOME/.ssh` folder.\n\nIf more advanced syncing is required, its recommended to handle this outside of netbox or alternatively use a custom script to do the sync.\n\n## Screenshots\n\nTODO\n",
"bugtrack_url": null,
"license": null,
"summary": "Improved custom script support for netbox",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/kkthxbye-code/netbox_script_manager"
},
"split_keywords": [
"netbox",
" netbox-plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "304175b8c76923b0c2b0b7ce8ab8de425a4f48838faf7e4d361b3014fc29140b",
"md5": "0c7a9102298afb1c9ee7c9c9d68d72d2",
"sha256": "9f23fac42004aa8699723365cf8a57b4154a740945d1ce5479a496b1cab07133"
},
"downloads": -1,
"filename": "netbox_script_manager-1.0.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "0c7a9102298afb1c9ee7c9c9d68d72d2",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.8",
"size": 49088,
"upload_time": "2024-11-01T07:49:08",
"upload_time_iso_8601": "2024-11-01T07:49:08.606626Z",
"url": "https://files.pythonhosted.org/packages/30/41/75b8c76923b0c2b0b7ce8ab8de425a4f48838faf7e4d361b3014fc29140b/netbox_script_manager-1.0.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fc8614df81b2bda73be3bf5e1bb2ee03e8350a39c2421a047a51e2db3f710bdc",
"md5": "fb67d3d3235ee89062778d04f89c28ae",
"sha256": "f4c325aabb14b8e5c5057afccde1f7f63e9fb896be19aecf73033e598006e329"
},
"downloads": -1,
"filename": "netbox_script_manager-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "fb67d3d3235ee89062778d04f89c28ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 41448,
"upload_time": "2024-11-01T07:49:10",
"upload_time_iso_8601": "2024-11-01T07:49:10.800551Z",
"url": "https://files.pythonhosted.org/packages/fc/86/14df81b2bda73be3bf5e1bb2ee03e8350a39c2421a047a51e2db3f710bdc/netbox_script_manager-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-01 07:49:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kkthxbye-code",
"github_project": "netbox_script_manager",
"github_not_found": true,
"lcname": "netbox-script-manager"
}
JSON
