NetBox LibreNMS Plugin

The NetBox LibreNMS Plugin enables integration between NetBox and LibreNMS, allowing you to leverage data from both systems. NetBox remains the Source of Truth (SoT) for your network, but this plugin allows you to easily onboard device objects from existing data in LibreNMS. The plugin does not automatically create objects in NetBox to ensure only verified data is used to populate NetBox.

Features

The plugin offers the following key features:

Device Import

Search and import devices from LibreNMS into NetBox with comprehensive validation and control:

• Filter devices by location, type, OS, hostname, system name, or hardware model
• Validate import prerequisites (Site, Device Type, Device Role)
• Smart matching for Sites, Device Types, and Platforms
• Import as physical Devices or Virtual Machines
• Bulk import multiple devices
• Automatic Virtual Chassis creation for stackable switches
• Background job processing for large device sets

See the Device Import Guide for detailed usage instructions.

Module / Inventory Sync

Synchronize physical inventory data from LibreNMS (via ENTITY-MIB) to NetBox installed modules:

• Compare LibreNMS inventory items (line-cards, transceivers, fans, PSUs) against NetBox module bays
• Install, update, or skip individual modules directly from the sync table
• Rich mapping system: ModuleTypeMapping, ModuleBayMapping (with regex support), NormalizationRules, InventoryIgnoreRules, CarrierAutoInstallRules
• Virtual Chassis aware — inventory rows distributed across correct VC members

See the Module Sync Guide, Mappings Guide, and Rules & Patterns Guide for details.

Device Field Sync

Synchronize device information from LibreNMS to NetBox. The following device fields can be synchronized:

• Device Name (with naming preference support)
• Serial Number (including virtual chassis members)
• Device Type
• Platform (via Platform Mappings)

Interface Sync

Pull interface data from Devices and Virtual Machines from LibreNMS into NetBox. The following interface attributes are synchronized:

• Name
• Description
• Status (Enabled/Disabled)
• Type (with custom mapping support)
• Speed
• MTU
• MAC Address
• VLAN (Tagged and untagged)

Set custom mappings for interface types to ensure that the correct interface type is used when syncing from LibreNMS to NetBox.

Cable Sync

Create cable connections in NetBox from LibreNMS links data.

IP Address Sync

Create IP address in NetBox from LibreNMS device IP data.

An opt-in Set Primary IP toggle on the IP Address Sync tab can also set the device or VM Primary IP.

VLAN Sync

• Create VLAN objects in NetBox from LibreNMS device VLAN data
• Per-VLAN group assignment with scope-aware auto-selection

Add Device to LibreNMS from NetBox

• Add a device to LibreNMS from the NetBox device page. SNMP v2c and v3 are supported.

Site & Location Sync

The plugin also supports synchronizing NetBox Sites with LibreNMS locations:

• Compare NetBox sites to LibreNMS location data
• Create LibreNMS locations to match NetBox sites
• Update existing LibreNMS locations latitude and longitude values based on NetBox data ⚠️ (currently not working due to LibreNMS API issue)
• Sync device site to LibreNMS location

Multi LibreNMS Server Configuration

• Configure multiple LibreNMS instances in your NetBox configuration
• Switch between different LibreNMS servers through the web interface
• Maintain backward compatibility with single-server configurations

Screenshots/GIFs

Screenshots from older plugin version

Site & Location Sync

Sync devices and Interfaces

Virtual Chassis Member Select

Interface Type Mappings

Contributing

There's more to do! Coding is not my day job. Bugs will exist and improvements will be needed. Contributions are very welcome! I've got more ideas for new features and improvements but please contribute if you can!

Development Environment

An easy way to get started with development is to use the included development container:

• Local Development: Open the project in VS Code and choose "Reopen in Container"
• GitHub Codespaces: Click "Code" → "Create codespace" in the GitHub repository
• Ready in 5 minutes: A complete NetBox environment with PostgreSQL, Redis, and the plugin pre-installed

📖 See the Dev Container README for detailed setup instructions, available commands, and troubleshooting.

Alternatively, share your ideas for the plugin over in discussions.

Compatibility

Installing

Standard Installation

Activate your virtual environment and install the plugin:

source /opt/netbox/venv/bin/activate

Install with pip:

(venv) $ pip install netbox-librenms-plugin

Add to your local_requirements.txt to ensure it is automatically reinstalled during future upgrades.

echo "netbox-librenms-plugin" >> /opt/netbox/local_requirements.txt #Check your NetBox install location

Docker

For adding to a NetBox Docker setup see how to create a custom Docker image. the general instructions for using netbox-docker with plugins.

Add the plugin to plugin_requirements.txt (netbox-docker):

# plugin_requirements.txt
netbox-librenms-plugin

Configuration

1. Enable the Plugin

Enable the plugin in /opt/netbox/netbox/netbox/configuration.py, or if you use netbox-docker, your /configuration/plugins.py file :

PLUGINS = [
    'netbox_librenms_plugin'
]

2. Apply the plugin configuration

Multi server example:

PLUGINS_CONFIG = {
    'netbox_librenms_plugin': {
        'servers': {
            'production': {
                'display_name': 'Production LibreNMS',
                'librenms_url': 'https://librenms-prod.example.com',
                'api_token': 'your_production_token',
                'cache_timeout': 300,
                'verify_ssl': True,
                'interface_name_field': 'ifDescr'
            },
            'testing': {
                'display_name': 'Test LibreNMS',
                'librenms_url': 'https://librenms-test.example.com',
                'api_token': 'your_test_token',
                'cache_timeout': 300,
                'verify_ssl': False,
                'interface_name_field': 'ifName'
            },
            'development': {
                'display_name': 'Dev LibreNMS',
                'librenms_url': 'https://librenms-dev.example.com',
                'api_token': 'your_dev_token',
                'cache_timeout': 180,
                'verify_ssl': False,
                'interface_name_field': 'ifDescr'
            }
        }
    }
}

Or use the original single-server configuration example:

PLUGINS_CONFIG = {
    'netbox_librenms_plugin': {
        'librenms_url': 'https://your-librenms-instance.com',
        'api_token': 'your_librenms_api_token',
        'cache_timeout': 300,
        'verify_ssl': True, # Optional: Change to False if needed,
        'interface_name_field': 'ifDescr', # Optional: LibreNMS field used for interface name. ifName used as default
    }
}

3. Apply Database Migrations

Apply database migrations with Netbox manage.py:

(venv) $ python manage.py migrate

4. Collect Static Files

The plugin includes static files that need to be collected by NetBox. Run the following command to collect static files:

(venv) $ python manage.py collectstatic --no-input

5. Restart Netbox

Restart the Netbox service to apply changes:

sudo systemctl restart netbox

6. Custom Field

As of version 0.4.4, the plugin automatically creates the librenms_id custom field (JSON type) when migrations are run. No manual setup is required.

The field is created for Device, Virtual Machine, Interface, and VM Interface objects and stores a per-server mapping (e.g., {"production": 42}).

For more info check out custom field docs

Update

source /opt/netbox/venv/bin/activate
pip install -U netbox-librenms-plugin
python manage.py migrate
python manage.py collectstatic --no-input
systemctl restart netbox

Uninstall

To cleanly uninstall the plugin and reverse its migrations, while the plugin is still installed and enabled, do the following:

source /opt/netbox/venv/bin/activate
python manage.py migrate netbox_librenms_plugin zero

This is the supported way to undo everything the plugin's migrations created: its own tables and migration records, plus any objects it adds to NetBox's own tables (for example indexes on dcim_device). Those cross-app changes are not covered by NetBox's generic removal steps, which only look for tables named netbox_librenms_plugin_*, so reversing the migrations first ensures nothing is left behind.

Then continue with the general removal instructions to disable the plugin, remove its configuration, uninstall the package, and restart NetBox.

If you already removed the plugin without reversing its migrations, reinstall the matching version, run the migrate netbox_librenms_plugin zero command, and then uninstall again.

Credits

Based on the NetBox plugin tutorial and docs:

• demo repository
• tutorial
• docs

This package was created with Cookiecutter. Thanks to the netbox-community/cookiecutter-netbox-plugin for the project template.