Need help with nextbox-ui-plugin?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

iDebugAll
259 Stars 28 Forks MIT License 69 Commits 26 Opened issues

Description

A topology visualization plugin for Netbox powered by NextUI Toolkit

Services available

!
?

Need anything else?

Contributors list

NextBox UI Plugin

A topology visualization plugin for NetBox powered by NextUI Toolkit. Netbox v2.8.0+ is required.

Installation

General installation steps and considerations follow the official guidelines.

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.
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:
# 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 = {

'nextboxuiplugin': {

'layerssortorder': (

ADD YOUR SETTINGS HERE

layersortorder is a tuple

),

'iconmodelmap': {

ADD YOUR SETTINGS HERE

iconmodelmap is a dict

},

'iconrolemap': {

ADD YOUR SETTINGS HERE

iconrolemap is a dict

}

'undisplayeddevicerole_slugs': (

# ADD YOUR SETTINGS HERE

undisplayeddevicerole_slugs value is a list or a tuple

Listed device role slugs are hidden on initial view load,

you may then hide/display any layer with a control button.

),

'undisplayeddevicetags': (

ADD YOUR SETTINGS HERE

undisplayeddevicetags value is a list or a tuple of regex strings.

Devices with tags matching any of listed regular expressions are hidden

on initial view load, you may then hide/display any layer with a control button.

),

'selectlayerslistincludedevice_tags': (

ADD YOUR SETTINGS HERE

selectlayerslistincludedevice_tags value is a list or a tuple of regex strings.

Use this parameter to control tags listed in Select Layers menu.

If specified, it works as allow list.

),

'selectlayerslistexcludedevice_tags': (

ADD YOUR SETTINGS HERE

selectlayerslistexcludedevice_tags value is a list or a tuple of regex strings.

Use this parameter to control tags listed in Select Layers menu.

If specified, it filters out matched tags from the list, except ones mathcing 'undisplayeddevicetags'.

),

'DISPLAYPASSIVEDEVICES': True|False,

'DISPLAYLOGICALMULTICABLE_LINKS': True|False,

'DISPLAY_UNCONNECTED': True|False,

'INITIAL_LAYOUT': 'vertical'|'horizontal'|'auto'

}

}

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{icontype}' tag in the Netbox Device tags. Assign a tag to the device to manually control the displayed icon type (e.g. 'iconrouter' or 'iconswitch'). 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{icontype}' tags found, the Plugin checks the default icon to devicetype mapping. You can control this behavior with 'iconmodelmap' dict. The Plugin checks for substring in a full devicetype 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.

  1. If no match found on steps 1-2, the Plugin checks the Device Role slug to Icon mapping.
    This mapping may be defined within 'iconrolemap' 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',
    }
    
  2. Default value is 'unknown' (renders as a question mark icon).

The Plugin can control the visibility of the layers and/or specific nodes on the topology view.
The visibility control is currently implemented for specific device roles, device tags, unconnected devices, and passive devices:

  • Initial visibility behavior for specific device roles is controlled by 'undisplayeddevicerole_slugs' plugin parameter. Listed device role slugs are hidden on initial view load, you may then hide/display any layer with a control button on the topology view page.

  • Initial visibility behavior for specific device tags is controlled by 'undisplayeddevicetags' plugin parameter. Devices with tags matching listed tag regular expressions are hidden on initial view load, you may then hide/display any layer with a control button on the topology view page.
    By default, the plugin lists all discovered device tags in Select Layers menu. You can use 'selectlayerslistincludedevicetags' and 'selectlayerslistexcludedevicetags' plugin parameters to filter the included tags.
    All three tag visibility control parameters are optional lists of regular expressions. Tags matching 'undisplayeddevicetags' are always listed in Select Layers menu. Empty or unset 'selectlayerslistincludedevicetags' allows all discovered tags to be listed in Select layers menu. If set, 'selectlayerslistincludedevicetags' works as an allow list for matched tags. 'selectlayerslistexcludedevicetags' filters out matched tags from the list, excpept for ones matching 'undisplayeddevice_tags'.

  • Initial visibility behavior for unconnected nodes is controlled by DISPLAYUNCONNECTED boolean plugin parameter.
    By default, unconnected nodes are being displayed. Set DISPLAY
    UNCONNECTED to False to hide them on initial topology view load.
    A separate 'Hide/Display Unconnected' button may then be used to hide or display those nodes.

  • Initial visibility for passive devices (patch panels, PDUs) is controlled by DISPLAYPASSIVEDEVICES boolean plugin parameter. A device is considered passive if it has cables connected to Front and Rear Ports only and not to Interfaces.
    Passive devices are hidden by default. You can display them with 'Display Passive Devices' button on the topology view page.
    Actual multi-cable connections between the end-devices a replaced by the direct logical connection once the passive devices are hidden. This logical direct link may be displayed regardless of the passive device visibility in addition to the cabling across patch panels if you set DISPLAYLOGICALMULTICABLELINKS plugin parameter to True. DISPLAYLOGICALMULTICABLELINKS is set to False by default. This parameter only affects the initial logical link visibility. With hidden passive devices, it is always being displayed.

Device layers are ordered automatically by default. You can control this behavior with INITIAL_LAYOUT plugin parameter. Valid options are 'vertical', 'horizontal', and 'auto'.
'auto' layout relies on NeXt UI dataprocessor best-effort algorithms. It spreads the Nodes across the view so they would be as distant from each other as possible. You may use it if the vertical and horizontal initial layout does not work properly in your browser (this is the issue to be fixed).

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

Apply Database Migrations

For plugin version 0.8.0 and above.

Apply database migrations with Django

manage.py
:
(venv) $ python3 manage.py migrate

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 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 runs on a backend.
The Plugin supports a topology visualization of arbitrary sets of Sites and Regions.

You can access Topology visualizations in different ways: 1. By clicking a custom plugin Topology button on a Site page. The Site topology visualization will open in a pop-up window:
Nodes are draggable and clickable:
You can switch between vertical and horizontal layers sort order back and forth. Default is vertical.

  1. Using Plugins dropdown menu item: Plugins -> NextBox UI -> Topology Viewer.
    Use Search form controls to pick desired Sites, Regions, or Devices.

Visibility control

You can display or hide any specific device roles on the topology view with 'Select Layer' button:
The list of available device roles is generated automatically based on discovered devices for a visualized site.

'Display/Hide Unconnected' button hides or displays the devices with no links attached.

'Display/Hide Passive Devices' buttons hides or displays the passive devices (patch pannels, PDUs, etc).

In a samples below, edge-sw01 is connected with core-rtr01 and core-rtr02 through Patch Panel A and Patch Panel B with multiple cable hops:

Once you hide the passive devices (default state), a logical direct link shows up between the edge switch and the core routers:

If DISPLAYLOGICALMULTICABLE_LINKS is set to True (default is False) this logical link is displayed initially:

Required Netbox User Permissions

The Plugin requires the following user permissions to access the topology view:

  • dcim | site | Can read site
  • dcim | device | Can view device
  • dcim | cable | Can view cable

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.