NetBox Plugin Installation

This guide provides detailed instructions for installing and configuring the IP Fabric NetBox plugin across different environments. The plugin enables seamless integration between IP Fabric’s network discovery capabilities and NetBox’s infrastructure management platform.

These instructions contain configuration of netbox-branching plugin since it is a hard requirement for this plugin to work.

1. System Requirements

Before installation, ensure:

• You follow requirements for version compatibility between IP Fabric and NetBox
• You have administrative access to your NetBox instance
• Your NetBox installation meets the minimum version requirements
• You have Python and pip available in your environment
• Your system has sufficient resources for additional plugin operations

2. Standard Installation (Bare Metal/VM)

2.1 Install via Package Manager

The plugin is available as a Python package on PyPI and can be installed using pip:

# Activate the NetBox virtual environment
source /opt/netbox/venv/bin/activate

# Install the plugin
(venv) $ pip install ipfabric_netbox

In case you want to install a specific version of the plugin, you can specify the version number:

# Install the plugin with specific version
(venv) $ pip install ipfabric_netbox[$IPFABRIC_VERSION]==$IPFABRIC_NETBOX_VERSION

To ensure the plugin is automatically reinstalled during future NetBox upgrades:

1. Create or edit the local_requirements.txt file in the NetBox root directory:

   (venv) $ echo "ipfabric_netbox" >> /opt/netbox/local_requirements.txt
   

   In case we defined specific version of the plugin:

   (venv) $ echo "ipfabric_netbox[$IPFABRIC_VERSION]==$IPFABRIC_NETBOX_VERSION" >> /opt/netbox/local_requirements.txt
   

2. This ensures the plugin will be reinstalled whenever NetBox is upgraded using the standard upgrade procedures.

2.3 Enable the Plugin in NetBox Configuration

After installing the plugin, enable it in the NetBox configuration:

1. Open the NetBox configuration file:

   (venv) $ nano /opt/netbox/netbox/netbox/configuration.py
   

2. Add the plugins to the PLUGINS list:

   PLUGINS = [
       'ipfabric_netbox',
       # other plugins...
       'netbox_branching',
   ]
   

3. Optionally, configure plugin-specific settings in the PLUGINS_CONFIG dictionary:

   PLUGINS_CONFIG = {
       'ipfabric_netbox': {
           # Plugin-specific settings can be added here
       }
   }
   

4. Additionally, configure plugin-specific logging for debugging purposes, for instance:

   LOGGING = {
       "handlers": {
            "console": {
                "level": "DEBUG",
                "class": "logging.StreamHandler",
                "formatter": "simple",
            },
        },
       "loggers": {
            "ipfabric_netbox": {
                "level": "DEBUG",
                "handlers": ["console"],
            },
            "netbox_branching": {
                "level": "DEBUG",
                "handlers": ["console"],
            },
        },
   }
   

2.4. Configure database router to support branching:

1. Create local_settings.py with following content.

   from netbox_branching.utilities import DynamicSchemaDict
   from .configuration import DATABASE
   
   # Wrap DATABASES with DynamicSchemaDict for dynamic schema support
   DATABASES = DynamicSchemaDict({
       'default': DATABASE,
   })
   
   # Employ our custom database router
   DATABASE_ROUTERS = [
       'netbox_branching.database.BranchAwareRouter',
   ]
   

   2. Place the file to /opt/netbox/netbox/netbox/, same directory that contains settings.py.

2.5 Apply Database Migrations

Run the following commands to apply database migrations and collect static files:

# Activate the virtual environment if not already activated
source /opt/netbox/venv/bin/activate

# Navigate to the NetBox directory
(venv) $ cd /opt/netbox/netbox/

# Apply database migrations
(venv) $ python3 manage.py migrate

Collect static files within venv:

python3 manage.py collectstatic --no-input

2.6 Restart NetBox Services

Restart the NetBox services to apply all changes:

# For systemd-based systems
sudo systemctl restart netbox netbox-rq

3. Docker Installation

3.1 Using Docker Compose Override

For NetBox instances running in Docker, follow these steps:

1. Create or modify the docker-compose.override.yml file in your NetBox Docker directory:

   version: '3'
   services:
     netbox:
       build:
         context: .
         dockerfile: Dockerfile
         args:
           - NETBOX_LOCAL_REQUIREMENTS=ipfabric_netbox
   

2. Update configuration.py as described in the previous section.

3. Rebuild and restart your Docker containers:

   docker-compose build --no-cache netbox
   docker-compose up -d
   

3.2 Using Plugin Mounts (Alternative Method)

For development or testing purposes, you can mount the plugin directly:

1. Clone the plugin repository:

   git clone https://github.com/ipfabric/ipfabric-netbox.git
   

2. Add a volume mount in your docker-compose.override.yml:

   version: '3'
   services:
     netbox:
       volumes:
         - ./ipfabric-netbox:/opt/netbox/netbox/plugins/ipfabric_netbox
   

3. Update configuration.py as described in the previous section.

4. Rebuild and restart your Docker containers.

4. Version-Specific Installations

4.1 Locking IP Fabric Python SDK Version

It’s recommended to use the same SDK version as your IP Fabric API version. To lock the SDK dependency to a specific minor version, install the plugin with the appropriate extras:

# For IP Fabric version 6.10.x
pip install ipfabric_netbox[ipfabric_6_10]

# For IP Fabric version 7.0.x
pip install ipfabric_netbox[ipfabric_7_0]

4.2 Available Version Extras

The following extras are currently available:

Extra Name	Compatible IP Fabric Version	SDK Version
ipfabric_6_6	6.6.x	6.6.x
ipfabric_6_7	6.7.x	6.7.x
ipfabric_6_8	6.8.x	6.8.x
ipfabric_6_9	6.9.x	6.9.x
ipfabric_6_10	6.10.x	6.10.x
ipfabric_7_0	7.0.x	7.0.x

5. Verification

5.1 Verify Plugin Installation

To verify the plugin is installed correctly:

1. Log in to the NetBox web interface
2. Navigate to the Plugins menu
3. Confirm “IP Fabric NetBox” appears in the list of installed plugins
4. Check the plugin version matches your expected version

5.2 Verify Database Migrations

To verify database migrations were applied successfully:

source /opt/netbox/venv/bin/activate
(venv) $ cd /opt/netbox/netbox/
(venv) $ python3 manage.py showmigrations ipfabric_netbox

All migrations should be marked as applied (with [X]).

6. Troubleshooting

6.1 Common Issues

Issue	Possible Cause	Solution
Plugin not appearing in NetBox	Plugin not enabled in configuration	Check PLUGINS list in configuration.py
Database migration errors	Incompatible NetBox version	Verify NetBox version meets requirements
SDK version conflicts	Mismatched IP Fabric and SDK versions	Install with correct version-specific extras
Static files not loading	collectstatic not run	Run python manage.py collectstatic
Permission errors	File system permissions	Check permissions on NetBox directories

6.2 Logs and Debugging

To troubleshoot installation issues:

1. Check the NetBox application logs:

   sudo tail -f /var/log/netbox/netbox.log
   

2. For Docker installations, check container logs:

   docker-compose logs -f netbox
   

3. Enable debug mode in NetBox configuration for more verbose logging:

   DEBUG = True
   

7. Upgrade Procedures

7.1 Standard Upgrade

To upgrade the plugin to a newer version:

source /opt/netbox/venv/bin/activate
(venv) $ pip install --upgrade ipfabric_netbox
(venv) $ cd /opt/netbox/netbox/
(venv) $ python3 manage.py migrate
(venv) $ python3 manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq

7.2 Docker Upgrade

For Docker installations, update your configuration to specify the new version and rebuild:

docker-compose build --no-cache netbox
docker-compose up -d

7.3 Upgrading plugin to v4.0.0 (NetBox v4.3.0+)

For a smooth upgrade to v4.0.0, upgrading must be done at the same time as upgrading to NetBox v4.3.0+. The crucial part is running all migrations from both upgrades at once.

The plugin now depends on netbox-branching plugin and these extra steps are simplified installation instructions of the plugin:

1. Enable the plugin in configuration.py (must be last!)

   PLUGINS = [
       # ...
       'netbox_branching',
   ]
   

2. Create /opt/netbox/netbox/netbox/local_settings.py with the following content. It assumes your configuration.py is in /opt/netbox/netbox/netbox/.

   from netbox_branching.utilities import DynamicSchemaDict
   from .configuration import DATABASE
   
   # Wrap DATABASES with DynamicSchemaDict for dynamic schema support
   DATABASES = DynamicSchemaDict({
       'default': DATABASE,
   })
   
   # Employ our custom database router
   DATABASE_ROUTERS = [
       'netbox_branching.database.BranchAwareRouter',
   ]
   

Warning

If you’ve upgraded NetBox first or run migrations only for NetBox, you’ll see the following error when attempting to upgrade plugin:

django.db.migrations.exceptions.InvalidBasesError: Cannot resolve bases for [<ModelState: 'ipfabric_netbox.IPFabricBranch'>]

Follow Cannot resolve bases for [<ModelState: 'ipfabric_netbox.IPFabricBranch'>] instructions to resolve this issue.

8. Additional Resources

• NetBox Documentation
• NetBox Plugin documentation.