nextbox-ui-plugin

Name	nextbox-ui-plugin JSON
Version	1.0.3 JSON
	download
home_page	https://github.com/iDebugAll/nextbox-ui-plugin
Summary	A Next-Gen Topology Visualization Plugin for NetBox Powered by topoSphere SDK.
upload_time	2024-10-28 15:31:38
maintainer	None
docs_url	None
author	Igor Korotchenkov
requires_python	None
license	MIT
keywords	netbox netbox-plugin plugin
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

# NextBox UI Plugin

NextBox UI is a Next Generation topology visualization plugin for [NetBox](https://github.com/netbox-community/netbox) powered by topoSphere SDK.

The Plugin delivers adaptive and scalable network topology maps, featuring advanced auto-layout algorithms, extended Filters, and multiple export options. Designed for efficiency and flexibility, NextBox UI enhances the visualization and management of complex network infrastructures within NetBox, providing users with intuitive tools to customize views, streamline network planning, and facilitate comprehensive data analysis.

![](samples/topology_viewer_light_mode.png)
*Now with Dark Mode!*
![](samples/topology_viewer_dark_mode.png)

# Compatibility

Newest NextBox UI Plugin versions 1.X support NetBox 4.1.

Legacy NextBox UI Plugin version 0.15 supports NetBox 3.5-4.1.

# Installation

General installation steps and considerations follow the [official guidelines](https://netbox.readthedocs.io/en/stable/plugins/).

### Package Installation from PyPi

Assuming you use a Virtual Environment for Netbox:
```
$ source /opt/netbox/venv/bin/activate
(venv) $ pip3 install nextbox-ui-plugin
```

### Package Installation from Source Code
The source code is available on [GitHub](https://github.com/iDebugAll/nextbox-ui-plugin). 
Download and install the package. Assuming you use a Virtual Environment for Netbox:
```
$ git clone https://github.com/iDebugAll/nextbox-ui-plugin
$ cd nextbox-ui-plugin
$ source /opt/netbox/venv/bin/activate
(venv) $ pip3 install .
```

To ensure NextBox UI plugin is automatically re-installed during future upgrades, create a file named `local_requirements.txt` (if not already existing) in the NetBox root directory (alongside `requirements.txt`) and list the `nextbox-ui-plugin` package:

```no-highlight
# echo nextbox-ui-plugin >> local_requirements.txt
```

### Enable the Plugin
In a global Netbox **configuration.py** configuration file, update or add PLUGINS parameter:
```python
PLUGINS = [
'nextbox_ui_plugin',
]
```

Optionally, update a PLUGINS_CONFIG parameter in **configuration.py** to rewrite default plugin behavior:
```python
#PLUGINS_CONFIG = {
# 'nextbox_ui_plugin': {
# 'layers_sort_order': (
# ADD YOUR SETTINGS HERE
# layer_sort_order is a tuple
# ),
# 'icon_model_map': {
# ADD YOUR SETTINGS HERE
# icon_model_map is a dict
# },
# 'icon_role_map': {
# ADD YOUR SETTINGS HERE
# icon_role_map is a dict
# }
# 'INITIAL_LAYOUT': 'auto' # or 'layered'
# }
#}
```
By default, the Plugin orders devices on a visualized topology based their roles in Netbox device attributes. This order may be controlled by 'layers_sort_order' parameter. Default sort order includes most commonly used naming conventions:
```
(
'undefined',
'outside',
'border',
'edge',
'edge-switch',
'edge-router',
'core',
'core-router',
'core-switch',
'distribution',
'distribution-router',
'distribution-switch',
'leaf',
'spine',
'access',
'access-switch',
)
```

By default, the Plugin automatically tries to identify the device icon type based on following logic:
1. 'icon_{icon_type}' tag in the Netbox Device tags.
Assign a tag to the device to manually control the displayed icon type (e.g. 'icon_router' or 'icon_switch').
Supported icon types:
```
{
'switch',
'router',
'firewall',
'wlc',
'unknown',
'server',
'phone',
'nexus5000',
'ipphone',
'host',
'camera',
'accesspoint',
'groups',
'groupm',
'groupl',
'cloud',
'unlinked',
'hostgroup',
'wirelesshost',
}
```
2. If no valid 'icon_{icon_type}' tags found, the Plugin checks the default icon to device_type mapping. You can control this behavior with 'icon_model_map' dict. The Plugin checks for substring in a full device_type attribute. Default mapping:

```
{
'CSR1000V': 'router',
'Nexus': 'switch',
'IOSXRv': 'router',
'IOSv': 'switch',
'2901': 'router',
'2911': 'router',
'2921': 'router',
'2951': 'router',
'4321': 'router',
'4331': 'router',
'4351': 'router',
'4421': 'router',
'4431': 'router',
'4451': 'router',
'2960': 'switch',
'3750': 'switch',
'3850': 'switch',
'ASA': 'firewall',
}
```
Keys are searched substrings. Values should be valid icon types as listed above.

3. If no match found on steps 1-2, the Plugin checks the Device Role slug to Icon mapping. 
This mapping may be defined within 'icon_role_map' dict in Plugin parameters. 
Default mapping already contains some general categories:
```
{
'border': 'router',
'edge-switch': 'switch',
'edge-router': 'router',
'core-router': 'router',
'core-switch': 'switch',
'distribution': 'switch',
'distribution-router': 'router',
'distribution-switch': 'switch',
'leaf': 'switch',
'spine': 'switch',
'access': 'switch',
'access-switch': 'switch',
}
```

4. Default value is 'unknown'.

Device layers are ordered automatically by default. You can control this behavior with INITIAL_LAYOUT plugin parameter. Valid options are 'layered', and 'auto'. 
'auto' layout relies on topoSphere best-effort algorithms. It spreads the Nodes across the view so they would be as distant from each other as possible.

### Collect Static Files
The Plugin contains static files for topology visualization. They should be served directly by the HTTP frontend. In order to collect them from the package to the Netbox static root directory use the following command:
```
(venv) $ cd /opt/netbox/netbox/
(venv) $ python3 manage.py collectstatic
```

### Restart Netbox
Restart the WSGI service to apply changes:
```
sudo systemctl restart netbox
```

# Installation with Docker
The Plugin may be installed in a Netbox Docker deployment.
The package contains a Dockerfile for [Netbox-Community Docker](https://github.com/netbox-community/netbox-docker) extension. Latest-LDAP version is used by default as a source. 
Download the Plugin and build from the source:
```
$ git clone https://github.com/iDebugAll/nextbox-ui-plugin
$ cd nextbox-ui-plugin
$ docker build -t netbox-custom .
```
Update a netbox image name in **docker-compose.yml** in a Netbox Community Docker project root:
```yaml
services:
netbox: &netbox
image: netbox-custom:latest
```
Update a **configuration.py**. It is stored in netbox-docker/configuration/ by default. Update or add PLUGINS parameter and PLUGINS_CONFIG parameter as described above.

Rebuild the running docker containers:
```
$ cd netbox-docker
$ docker-compose down
$ docker-compose up -d
```
Netbox Community Docker setup performs static file collection and database migrations on every startup. No manual actions are required.

# Fixing Common Installation and Post-Upgrade Issues

If you are experiencing some unexpected errors or visual behaviors after the installation or upgrade, please make sure that you execute the following steps first:

1. Clear your browser cache and reload the page.
2. Re-collect static files: `(venv) $ python3 manage.py collectstatic --clear`.
3. Re-apply database migrations: `(venv) $ python3 manage.py migrate`.

# Usage

Once installed and initialized, the Plugin will be available via Topology Viewer main menu item in NetBox.

### Required Netbox User Permissions
The Plugin requires the following user permissions to access the topology view:

# Licensing

Plugin code is published under MIT license. Embedded topoSphere SDK bundle is published under proprietary license special for NextBox UI Plugin and NetBox Community free of charge.

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/iDebugAll/nextbox-ui-plugin",
    "name": "nextbox-ui-plugin",
    "maintainer": null,
    "docs_url": null,
    "requires_python": null,
    "maintainer_email": null,
    "keywords": "netbox, netbox-plugin, plugin",
    "author": "Igor Korotchenkov",
    "author_email": "iDebugAll@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/cf/f1/dd9525ee72fcc7f10a60fec7f5df637f8fae9d4147ee640a2095b640f079/nextbox_ui_plugin-1.0.3.tar.gz",
    "platform": null,
    "description": "# NextBox UI Plugin\n\nNextBox UI is a Next Generation topology visualization plugin for [NetBox](https://github.com/netbox-community/netbox) powered by topoSphere SDK.<br/>\n\nThe Plugin delivers adaptive and scalable network topology maps, featuring advanced auto-layout algorithms, extended Filters, and multiple export options. Designed for efficiency and flexibility, NextBox UI enhances the visualization and management of complex network infrastructures within NetBox, providing users with intuitive tools to customize views, streamline network planning, and facilitate comprehensive data analysis.\n\n![](samples/topology_viewer_light_mode.png)\n*Now with Dark Mode!*\n![](samples/topology_viewer_dark_mode.png)\n\n# Compatibility\n\nNewest NextBox UI Plugin versions 1.X support NetBox 4.1.<br/>\n\nLegacy NextBox UI Plugin version 0.15 supports NetBox 3.5-4.1.\n\n# Installation\n\nGeneral installation steps and considerations follow the [official guidelines](https://netbox.readthedocs.io/en/stable/plugins/).\n\n### Package Installation from PyPi\n\nAssuming you use a Virtual Environment for Netbox:\n```\n$ source /opt/netbox/venv/bin/activate\n(venv) $ pip3 install nextbox-ui-plugin\n```\n\n### Package Installation from Source Code\nThe source code is available on [GitHub](https://github.com/iDebugAll/nextbox-ui-plugin).<br/>\nDownload and install the package. Assuming you use a Virtual Environment for Netbox:\n```\n$ git clone https://github.com/iDebugAll/nextbox-ui-plugin\n$ cd nextbox-ui-plugin\n$ source /opt/netbox/venv/bin/activate\n(venv) $ pip3 install .\n```\n\nTo ensure NextBox UI plugin is automatically re-installed during future upgrades, create a file named `local_requirements.txt` (if not already existing) in the NetBox root directory (alongside `requirements.txt`) and list the `nextbox-ui-plugin` package:\n\n```no-highlight\n# echo nextbox-ui-plugin >> local_requirements.txt\n```\n\n### Enable the Plugin\nIn a global Netbox **configuration.py** configuration file, update or add PLUGINS parameter:\n```python\nPLUGINS = [\n    'nextbox_ui_plugin',\n]\n```\n\nOptionally, update a PLUGINS_CONFIG parameter in **configuration.py** to rewrite default plugin behavior:\n```python\n#PLUGINS_CONFIG = {\n#    'nextbox_ui_plugin': {\n#        'layers_sort_order': (\n#            ADD YOUR SETTINGS HERE\n#            layer_sort_order is a tuple\n#        ),\n#        'icon_model_map': {\n#            ADD YOUR SETTINGS HERE\n#            icon_model_map is a dict\n#        },\n#        'icon_role_map': {\n#            ADD YOUR SETTINGS HERE\n#            icon_role_map is a dict\n#        }\n#        'INITIAL_LAYOUT': 'auto' # or 'layered'\n#    }\n#}\n```\nBy default, the Plugin orders devices on a visualized topology based their roles in Netbox device attributes.<br/> This order may be controlled by 'layers_sort_order' parameter. Default sort order includes most commonly used naming conventions:\n```\n(\n    'undefined',\n    'outside',\n    'border',\n    'edge',\n    'edge-switch',\n    'edge-router',\n    'core',\n    'core-router',\n    'core-switch',\n    'distribution',\n    'distribution-router',\n    'distribution-switch',\n    'leaf',\n    'spine',\n    'access',\n    'access-switch',\n)\n```\n\nBy default, the Plugin automatically tries to identify the device icon type based on following logic:\n1. 'icon_{icon_type}' tag in the Netbox Device tags.\n   Assign a tag to the device to manually control the displayed icon type (e.g. 'icon_router' or 'icon_switch').\n   Supported icon types:\n```\n{\n    'switch',\n    'router',\n    'firewall',\n    'wlc',\n    'unknown',\n    'server',\n    'phone',\n    'nexus5000',\n    'ipphone',\n    'host',\n    'camera',\n    'accesspoint',\n    'groups',\n    'groupm',\n    'groupl',\n    'cloud',\n    'unlinked',\n    'hostgroup',\n    'wirelesshost',\n}\n```\n2. If no valid 'icon_{icon_type}' tags found, the Plugin checks the default icon to device_type mapping. You can control this behavior with 'icon_model_map' dict. The Plugin checks for substring in a full device_type attribute. Default mapping:\n\n```\n{\n    'CSR1000V': 'router',\n    'Nexus': 'switch',\n    'IOSXRv': 'router',\n    'IOSv': 'switch',\n    '2901': 'router',\n    '2911': 'router',\n    '2921': 'router',\n    '2951': 'router',\n    '4321': 'router',\n    '4331': 'router',\n    '4351': 'router',\n    '4421': 'router',\n    '4431': 'router',\n    '4451': 'router',\n    '2960': 'switch',\n    '3750': 'switch',\n    '3850': 'switch',\n    'ASA': 'firewall',\n}\n```\nKeys are searched substrings. Values should be valid icon types as listed above.<br/>\n\n3. If no match found on steps 1-2, the Plugin checks the Device Role slug to Icon mapping.<br/>\nThis mapping may be defined within 'icon_role_map' dict in Plugin parameters.<br/>\nDefault mapping already contains some general categories:\n```\n{\n    'border': 'router',\n    'edge-switch': 'switch',\n    'edge-router': 'router',\n    'core-router': 'router',\n    'core-switch': 'switch',\n    'distribution': 'switch',\n    'distribution-router': 'router',\n    'distribution-switch': 'switch',\n    'leaf': 'switch',\n    'spine': 'switch',\n    'access': 'switch',\n    'access-switch': 'switch',\n}\n```\n\n4. Default value is 'unknown'.\n<br/><br/>\n\n\nDevice layers are ordered automatically by default. You can control this behavior with INITIAL_LAYOUT plugin parameter. Valid options are 'layered', and 'auto'.<br/>\n'auto' layout relies on topoSphere best-effort algorithms. It spreads the Nodes across the view so they would be as distant from each other as possible.\n\n\n### Collect Static Files\nThe Plugin contains static files for topology visualization. They should be served directly by the HTTP frontend. In order to collect them from the package to the Netbox static root directory use the following command:\n```\n(venv) $ cd /opt/netbox/netbox/\n(venv) $ python3 manage.py collectstatic\n```\n\n### Restart Netbox\nRestart the WSGI service to apply changes:\n```\nsudo systemctl restart netbox\n```\n\n# Installation with Docker\nThe Plugin may be installed in a Netbox Docker deployment. \nThe package contains a Dockerfile for [Netbox-Community Docker](https://github.com/netbox-community/netbox-docker) extension. Latest-LDAP version is used by default as a source.<br/>\nDownload the Plugin and build from the source:\n```\n$ git clone https://github.com/iDebugAll/nextbox-ui-plugin\n$ cd nextbox-ui-plugin\n$ docker build -t netbox-custom .\n```\nUpdate a netbox image name in **docker-compose.yml** in a Netbox Community Docker project root:\n```yaml\nservices:\n  netbox: &netbox\n    image: netbox-custom:latest\n```\nUpdate a **configuration.py**. It is stored in netbox-docker/configuration/ by default. Update or add PLUGINS parameter and PLUGINS_CONFIG parameter as described above.\n\nRebuild the running docker containers:\n```\n$ cd netbox-docker\n$ docker-compose down\n$ docker-compose up -d\n```\nNetbox Community Docker setup performs static file collection and database migrations on every startup. No manual actions are required.\n\n# Fixing Common Installation and Post-Upgrade Issues\n\nIf you are experiencing some unexpected errors or visual behaviors after the installation or upgrade, please make sure that you execute the following steps first:\n\n1. Clear your browser cache and reload the page.\n2. Re-collect static files: `(venv) $ python3 manage.py collectstatic --clear`.\n3. Re-apply database migrations: `(venv) $ python3 manage.py migrate`.\n\n# Usage\n\nOnce installed and initialized, the Plugin will be available via Topology Viewer main menu item in NetBox.\n\n\n### Required Netbox User Permissions\nThe Plugin requires the following user permissions to access the topology view:\n\n  - dcim | site   | Can read site\n  - dcim | device | Can view device\n  - dcim | cable  | Can view cable\n\n# Licensing\n\nPlugin code is published under MIT license. Embedded topoSphere SDK bundle is published under proprietary license special for NextBox UI Plugin and NetBox Community free of charge.\n\n\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A Next-Gen Topology Visualization Plugin for NetBox Powered by topoSphere SDK.",
    "version": "1.0.3",
    "project_urls": {
        "Download": "https://github.com/iDebugAll/nextbox-ui-plugin/archive/v1.0.3.tar.gz",
        "Homepage": "https://github.com/iDebugAll/nextbox-ui-plugin"
    },
    "split_keywords": [
        "netbox",
        " netbox-plugin",
        " plugin"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "cff1dd9525ee72fcc7f10a60fec7f5df637f8fae9d4147ee640a2095b640f079",
                "md5": "169391a91ea94c3e7d7566144f608e7a",
                "sha256": "7ed502e08d0c8115ecab4834299ea53ca09845374a080a4801cd4594c7564bc7"
            },
            "downloads": -1,
            "filename": "nextbox_ui_plugin-1.0.3.tar.gz",
            "has_sig": false,
            "md5_digest": "169391a91ea94c3e7d7566144f608e7a",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 96200,
            "upload_time": "2024-10-28T15:31:38",
            "upload_time_iso_8601": "2024-10-28T15:31:38.459639Z",
            "url": "https://files.pythonhosted.org/packages/cf/f1/dd9525ee72fcc7f10a60fec7f5df637f8fae9d4147ee640a2095b640f079/nextbox_ui_plugin-1.0.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-10-28 15:31:38",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "iDebugAll",
    "github_project": "nextbox-ui-plugin",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "nextbox-ui-plugin"
}

Igor Korotchenkov