Garoshi/netbox-librenms-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit
Some checks failed
ci / deploy (push) Has been cancelled
Details
CodeQL Advanced / Analyze (actions) (push) Has been cancelled
Details
CodeQL Advanced / Analyze (javascript-typescript) (push) Has been cancelled
Details
CodeQL Advanced / Analyze (python) (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Vlastislav Svatek
2026-06-05 10:39:05 +02:00
commit 673e67106e
217 changed files with 76612 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
docs/usage_tips/README.md Normal file
View File

@@ -0,0 +1,94 @@
# Usage Tips
## Initial Setup
1. [Configure Custom Field](custom_field.md)
- Set up the `librenms_id` custom field for optimal device matching
- This ensures reliable device identification between NetBox and LibreNMS
2. [Configure Interface Mappings](interface_mappings.md)
- Review and set up interface type mappings before synchronization
- Create specific mappings for your network equipment types
- Pay attention to speed-based mappings for accurate interface types
3. [Multi Server Configuration](multi_server_configuration.md)
- Configure multiple LibreNMS instances in your NetBox configuration
- Switch between different LibreNMS servers through the web interface
- Maintain backward compatibility with single-server configurations
## Device Import
[Device Import Guide](../librenms_import/overview.md) - Import devices from LibreNMS into NetBox
1. Search for devices using flexible filters (location, type, OS, hostname, sysname)
2. Validate import prerequisites (Site, Device Type, Device Role)
3. Configure missing mappings or select from suggestions
4. Import devices individually or in bulk
5. Automatic Virtual Chassis creation for stackable switches
The Device Import feature automatically sets the `librenms_id` custom field, enabling all other plugin features.
> **Rack Position Assignment:** Imported devices can be assigned to racks without specific rack unit (U) positions. After import, assign U positions through the "Non racked" section of each rack. The [NetBox Reorder Rack plugin](https://github.com/minitriga/netbox-reorder-rack) simplifies this workflow.
## Device Synchronization
### Devices
> **Note:** If you imported devices using the [Device Import feature](../librenms_import/overview.md), the `librenms_id` is already set and will be used automatically. The steps below apply to devices added to NetBox manually.
1. Ensure devices have either:
- Primary IP configured
- Valid DNS name (set on the Primary IP)
- hostname (that matches LibreNMS hostname)
2. The plugin will populate the `librenms_id` custom field if the device is found in LibreNMS
### Virtual Chassis
LibreNMS treats a Virtual Chassis as one logical device. The plugin selects a single "sync device" from your chassis to communicate with LibreNMS using this priority:
1. **Member with `librenms_id` set** (if already configured)
2. **Master device with primary IP** (most common)
3. **Any member with primary IP** (fallback)
4. **Member with lowest position number** (last resort)
Only the selected sync device should have the `librenms_id` custom field populated—leave it empty on all other members.
For best results, align chassis member positions with interface naming patterns. For example, if switch 1 has interfaces like `eth1/0/1` and switch 2 has `eth2/0/1`, the plugin can auto-detect the correct member for each interface. Always verify the member selection before running bulk synchronization.
## Interface Management
1. Verify Before Sync
- Review interface mappings indicated by the icons (🔗 shows a mapping is configured)
- Check speed and type matches
- Confirm member assignments for virtual chassis
2. Exclude columns to exclude from interface sync
- Sync only the values you want to sync
3. Sync VLANs first to ensure that VLANs are created in NetBox before syncing interfaces, allowing for proper VLAN assignments. Use the VLAN tab on the device sync page to create VLANs from LibreNMS data.
## Cable Management
1. Preparation
- Ensure devices are properly identified in both systems
- Open LibreNMS Sync on all devices to populate librenms_id custom field
- Remote Device and Remote interface need to be found in NetBox for cable creation to work
- Check Device and Interface naming
## VLAN Management
1. Preparation
- Configure VLAN Groups in NetBox if you want scoped VLAN assignment (e.g., per-site or per-rack groups)
- The plugin resolves VLAN groups using a scope hierarchy: Rack → Location → Site → SiteGroup → Region → Global
2. Review the VLANs tab on the device sync page
- Select the appropriate VLAN Group for each VLAN, or let the plugin auto-select based on scope
- A warning icon appears when a VID does not exist in the selected VLAN group.
3. Sync selected VLANs to create or update them in NetBox
## Best Practices
1. Regular Maintenance
- Periodically review and update interface mappings
- Keep custom fields current
## Optimization
- DNS lookup time can slow response of the API call to LibreNMS

97
docs/usage_tips/custom_field.md Normal file
View File

@@ -0,0 +1,97 @@
# Using the `librenms_id` Custom Field
## Overview
To enhance device identification and synchronization between NetBox and LibreNMS, this plugin supports using a custom field `librenms_id` on Device, Virtual Machine and Interface objects. While the plugin works without it, using this custom field is recommended for LibreNMS API lookups, and to assist with matching the remote device and remote interfaces for cable creation in Netbox. It can also be entered manually if no primary IP or FQDN is available.
!!! info "Automatic Creation"
As of version 0.4.4, the plugin **automatically creates** the `librenms_id` custom field when migrations are run. You no longer need to create it manually. The field is created for Device, Virtual Machine, Interface, and VM Interface objects with JSON type for per-server device tracking.
For the Device and Virtual Machine objects the plugin will automatically populate the LibreNMS ID custom field when opening the LibreNMS Sync page if the device has been found in LibreNMS.
For the Interface object, the plugin will automatically populate the LibreNMS ID custom field when the interface data is synced from LibreNMS.
## Benefits of Using `librenms_id`
- **Improved Device Matching:** Ensures accurate matching between NetBox and LibreNMS devices.
- **Fallback Identification:** Useful when devices lack a primary IP or FQDN.
- **Efficient Synchronization:** Enhances the reliability of API lookups.
- **Cable creation:** Allows better device identification for the creation of cables between NetBox devices.
## Manual Custom Field Setup
!!! note
On 0.4.4+, rerun migrations first (`manage.py migrate`). If you need to recreate the field manually on current releases, use the JSON schema below. Pre-0.4.2 releases used an Integer field — do not use Integer for new entries.
Follow these steps to create the `librenms_id` custom field in NetBox:
1. **Navigate to Custom Fields:**
- Go to **Customization** in the NetBox sidebar.
- Click on **Custom Fields**.
2. **Add a New Custom Field:**
- Click the **Add a custom field** button.
3. **Configure the Custom Field:**
- **Object Types:**
- Check **dcim > device**
- Check **virtualization > virtual machine**
- Check **dcim > interface**
- Check **virtualization > interfaces (optional)**
- **Name:** `librenms_id`
- **Label:** `LibreNMS ID`
- **Description:** (Optional) Add a description like "LibreNMS Device ID for synchronization".
- **Type:** JSON (object) — stores a per-server mapping.
- Multi-server example:
```json
{"production": 42, "staging": 17}
```
- Legacy single-server example (integer) — read-only/deprecated; do not use for new entries:
```
42
```
> Note: to create new entries manually use the JSON format shown above.
- **Required:** Leave unchecked (optional).
- **Default Value:** Leave blank.
4. **Save the Custom Field:**
- Click **Create** to save the custom field.
### Manually assign a value to `librenms_id`
You can manually assign a value to the `librenms_id` custom field for a device using the following steps:
1. **Edit the Device:**
- Navigate to the device in NetBox.
- Click the **Edit** button.
2. **Set the LibreNMS ID:**
- Scroll to the **Custom Fields** section.
- Enter the `librenms_id` value as a JSON object with your server key(s):
```json
{"production": 42}
```
For multiple servers: `{"production": 42, "staging": 17}`
3. **Save Changes:**
- Click **Update** to save the device.
## Notes
- If `librenms_id` is set, the plugin will prioritize it over other identification methods.
- Ensure the `librenms_id` corresponds to the correct device ID in LibreNMS to prevent mismatches.
- The custom field is optional but recommended for optimal plugin performance.
- Using the custom field on interfaces will greatly improve the interface matching required for cable synchronization.

137
docs/usage_tips/interface_mappings.md Normal file
View File

@@ -0,0 +1,137 @@
# interface\_mappings
### Quick Intro
Interface type mappings control how LibreNMS interface types are translated to NetBox interface types during synchronization.
The mappings can be customized in the plugin settings menu.
A mapping of LibreNMS Type an LibreNMS Speed combine to make a unique group that map to a Netbox interface type. This means multiple mapping for the same LibreNMS Type can be created.
> Note: The LibreNMS Speed is entered as Kbps
Example:
```
* ethernetCsmacd + 10000000 = 10GBASE-T (10GE)
* ethernetCsmacd + 1000000 = 1000BASE-T (1GE)
* ethernetCsmacd + 100000 = 100BASE-TX (10/100ME)
```
### How to Use Interface Mappings
#### Accessing the Page:
![Interface Mappings Page](../img/interface_mappings/interfacemappings_menu.png){ width="250" }
* From the main menu, navigate to the Plugins section
* Under Netbox Librenms Plugin, Select "Interface Mappings"
#### Creating a New Mapping:
![](../img/interface_mappings/addmapping.png){ width="50" }
* Click the green `+` or `Add` button either from the menu or on the Interface Mappings page
* Enter LibreNMS interface type. _You can copy this from plugin's device interface sync page_
* Enter Librenms interface speed as Kbps
* Select the Netbox interface type from the dropdown
* Click `Create` to save the mapping
#### Bulk Importing Mappings:
The plugin supports NetBox's standard bulk import feature for interface mappings. Click the **Import** button on the Interface Mappings page to access the import interface.
**YAML Example:**
```yaml
---
- librenms_type: ethernetCsmacd
librenms_speed: 1000000
netbox_type: 1000base-t
description: "Standard Gigabit Ethernet ports"
- librenms_type: propVirtual
librenms_speed: 1000000
netbox_type: virtual
description: "Virtual interfaces with 1G speed"
- librenms_type: softwareLoopback
librenms_speed: 8000000
netbox_type: virtual
description: "Loopback interfaces"
- librenms_type: ethernetCsmacd
librenms_speed: 10000000
netbox_type: 10gbase-t
description: "10 Gigabit Ethernet copper connections"
- librenms_type: ethernetCsmacd
librenms_speed: 100000
netbox_type: 100base-tx
description: "Fast Ethernet 100Mbps ports"
- librenms_type: ethernetCsmacd
librenms_speed: null
netbox_type: 1000base-t
description: "Default mapping for Ethernet without speed detection"
- librenms_type: ethernetCsmacd
librenms_speed: 40000000
netbox_type: 40gbase-x-qsfpp
description: "40 Gigabit QSFP+ interfaces"
- librenms_type: ethernetCsmacd
librenms_speed: 25000000
netbox_type: 25gbase-x-sfp28
description: "25 Gigabit SFP28 interfaces"
- librenms_type: propVirtual
librenms_speed: null
netbox_type: virtual
description: "Generic virtual interfaces"
- librenms_type: ieee8023adLag
librenms_speed: null
netbox_type: lag
description: "Link aggregation groups (port channels)"
- librenms_type: softwareLoopback
librenms_speed: null
netbox_type: virtual
description: "Software loopback interfaces"
```
**Notes:**
* `librenms_speed` is optional - use `null` or omit for type-only mappings
* `description` is optional - provides context for each mapping
* The combination of `librenms_type` and `librenms_speed` must be unique
* Supports CSV, JSON, and YAML formats
#### Editing Existing Mappings:
![](../img/interface_mappings/editmapping.png){ width="50" }
* On the Mappings page, Locate the desired mapping in the list
* Click the `edit` (pencil icon) button
* Modify the field mappings as needed
* Save the changes
#### Deleting Mappings:
![](../img/interface_mappings/deletemapping.png){ width="150" }
* Find the mapping you wish to remove
* Select the `Delete` button from the drop down
* Confirm the deletion when prompted
#### Applying Mappings:
* Mappings are automatically applied when interface data is synced between LibreNMS and Netbox
* If a mapping exist for an interface, it will show on the interface sync page with the icon :material-link-variant:
* If a mapping does not exist, it will show the icon :material-link-variant-off:
### Best Practices
* Check mappings are correct before performing a sync to avoid data errors
* Regularly review and update your mappings to ensure they remain accurate

92
docs/usage_tips/multi_server_configuration.md Normal file
View File

@@ -0,0 +1,92 @@
# Multi-Server LibreNMS Configuration
## Overview
The NetBox LibreNMS plugin now supports multiple LibreNMS servers. This allows you to:
- Configure multiple LibreNMS instances in your NetBox configuration
- Switch between different LibreNMS servers through the web interface
- Maintain backward compatibility with single-server configurations
## Configuration
### Multi-Server Configuration
Update your NetBox `configuration.py` file:
```python
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'
}
}
}
}
```
### Legacy Single-Server Configuration (Backward Compatible)
The original configuration format is still supported:
```python
PLUGINS_CONFIG = {
'netbox_librenms_plugin': {
'librenms_url': 'https://your-librenms-instance.com',
'api_token': 'your_librenms_api_token',
'cache_timeout': 300,
'verify_ssl': True,
'interface_name_field': 'ifDescr'
}
}
```
## Usage
1. Navigate to **LibreNMS Plugin** > **Settings** > **Server Settings**
2. Select your desired LibreNMS server from the dropdown
3. Click **Save Settings**
All subsequent LibreNMS operations will use the selected server.
## Configuration Options
Each server configuration supports the following options:
- `display_name`: Human-readable name for the server (optional)
- `librenms_url`: URL of the LibreNMS instance (required)
- `api_token`: API token for authentication (required)
- `cache_timeout`: Cache timeout in seconds (optional, default: 300)
- `verify_ssl`: Whether to verify SSL certificates (optional, default: True)
- `interface_name_field`: LibreNMS field for interface names (optional, default: 'ifDescr')
## Migration from Single to Multi-Server
1. Add the `servers` configuration block to your `configuration.py`
2. Move your existing single-server configuration into a server block (e.g., 'default' or 'production')
3. Restart NetBox
4. Select your server in the plugin settings
The plugin will automatically detect and use the new configuration format.

153
docs/usage_tips/permissions.md Normal file
View File

@@ -0,0 +1,153 @@
# Permissions & Access Control
## Overview
The plugin uses a two-tier permission system that works with NetBox's built-in permissions. Both tiers must be satisfied for users to perform actions:
1. **Plugin permissions** control access to plugin pages and features
2. **NetBox object permissions** control what objects users can create or modify
This design ensures the plugin respects your existing NetBox permission structure. A user might have full plugin access but still be restricted to creating certain objects based on their NetBox permissions.
> Superusers have full access to all plugin features and NetBox objects by default. So the following applies only to regular users who can be granted specific permissions as needed.
## Two-Tier Permission Model
### How Do the Tiers Work Together?
A user needs both tiers of permissions to complete an action. For example, to view the Librenms Import page AND import a device:
1. **Tier 1: Plugin permission**: User needs View AND Change permission on **LibreNMS Settings**
- View: allows access to the plugin pages and pulling data from LibreNMS.
- Change: allows performing actions that modify Netbox or Librenms data
The Plugin also enforces Netbox object permissions so the following permission would also be required:
2. **Tier 2: Object permission**: User needs `dcim.add_device` (to create the device in NetBox)
If either permission is missing, the operation fails with an appropriate error message.
## Creating Permissions
All permissions are created using Netbox's standard Object permissions UI.
For details on how NetBox permissions work, see the [NetBox Permissions documentation](https://netboxlabs.com/docs/netbox/administration/permissions/).
### Plugin Permissions
To grant a user or group access to the plugin:
1. Go to **Admin → Permissions**
2. Click **Add**
3. For **Object types**, select "NetBox Librenms Plugin | LibreNMS Settings"
4. Under **Actions**, check the permissions to grant:
- ☑ **Can view** — for read-only access
- ☑ **Can change** — for write access (requires View as well)
5. Assign to specific **Users** or **Groups**
6. Click **Save**
### NetBox Object Permissions
NetBox object permissions are created similarly but for different object types (DCIM, IPAM, VIRTUALIZATION, etc.).
### Interface Type Mapping Permissions
The Interface Type Mapping feature uses its own object permissions in addition to the plugin permissions. To manage interface mappings, users need:
- **Plugin permission**: View permission on LibreNMS Settings (to access the page)
- **Object permissions**: `netbox_librenms_plugin.add_interfacetypemapping`, `netbox_librenms_plugin.change_interfacetypemapping`, or `netbox_librenms_plugin.delete_interfacetypemapping` as needed
These permissions are enforced automatically by NetBox's generic views.
## Example Scenarios
### Read-Only Access
- **Plugin permissions**: Librenms Setting View only (Can view LibreNMS Plugin pages)
- **NetBox permissions**: View permissions for devices, interfaces, etc.
Users can access all plugin pages, refresh data from LibreNMS, and review comparison tables, but cannot import devices or sync data.
### Full Plugin Access
- **Plugin permissions**: View + Change (Can view LibreNMS Plugin Pages and Import and sync devices data)
- **NetBox permissions**: Add/change permissions for devices, interfaces, cables, IP addresses, VLANs
Users have full access to all plugin features and can import devices, sync interfaces, and create cables.
## Further Details
### Tier 1: Plugin Permissions
Plugins permissions use the **LibreNMS Settings** model permissions:
| Permission | NetBox UI Selection | Grants |
|------------|---------------------|--------|
| `view_librenmssettings` | LibreNMS Settings → ☑ Can view | Access all plugin pages, view LibreNMS data |
| `change_librenmssettings` | LibreNMS Settings → ☑ Can change | Import devices, sync data, save settings |
Users without View permission won't see the LibreNMS menu or the LibreNMS Sync tab. Users with **View** but not **Change** can browse all plugin pages but cannot perform import or sync actions that modify Netbox data and Librenms data like Locations and Adding devices.
### Tier 2: NetBox Object Permissions
When the plugin creates or modifies NetBox objects (devices, interfaces, cables, IP addresses, VLANs), NetBox enforces its standard object permissions. The plugin checks these permissions and will block operations if the user lacks the required access.
| Plugin Action | Required Object Permissions |
|---------------|----------------------------|
| Import device | `dcim.add_device`, `dcim.add_interface` |
| Import device with VC | Above + `dcim.add_virtualchassis` |
| Import VM | `virtualization.add_virtualmachine` |
| Sync interfaces | `dcim.add_interface`, `dcim.change_interface` |
| Delete interfaces | `dcim.delete_interface` |
| Sync VM interfaces | `virtualization.add_vminterface`, `virtualization.change_vminterface` |
| Delete VM interfaces | `virtualization.delete_vminterface` |
| Sync cables | `dcim.add_cable`, `dcim.change_cable` |
| Sync IP addresses | `ipam.add_ipaddress`, `ipam.change_ipaddress` |
| Sync VLANs | `ipam.add_vlan`, `ipam.change_vlan` |
| Sync device fields | `dcim.change_device` |
| Create platform | `dcim.add_platform` |
### Why LibreNMS Settings Permissions?
NetBox's permission system is object-based—permissions are tied to specific models like Device, Interface, or Cable. However, the plugin's Import and Sync pages are feature pages that don't have their own dedicated models. They work with LibreNMS data and create or modify existing NetBox objects.
To control access to these pages, the plugin uses the **LibreNMS Settings** model permissions as a gate for all plugin features:
- **No dedicated models for pages** — The Import and Sync pages aren't objects, so we need an existing model to attach permissions to
- **No custom migrations required** — Uses Django's built-in model permissions that NetBox already understands
- **Standard NetBox workflow** — Administrators assign permissions the same way they do for any other NetBox object
- **Single permission per access level** — One "View" permission for read access, one "Change" permission for write access
While using a settings model for access control may seem unconventional, it provides a simple and maintainable way to gate plugin access without introducing custom permission infrastructure.
## Special note: Background Jobs and Superuser Access
The device import page can use background jobs to help support large device sets, and virtual chassis detection. However, NetBox restricts access to background job status APIs to superusers. There is no permission in NetBox for this. This is a core design decision, not a plugin limitation.
| User Type | Background Jobs |
|-----------|-----------------|
| Superuser | Full access to background jobs with real-time status updates |
| Non-superuser | Automatic fallback to synchronous processing |
The plugin automatically detects whether the current user is a superuser and adjusts behavior accordingly. Non-superuser users don't need to change any settings—the plugin simply processes requests synchronously instead of as background jobs. All import and filter operations work correctly regardless of superuser status.
## Troubleshooting
**User can't see the LibreNMS menu**
: The user doesn't have View permission for the plugin. Add an Object Permission for "LibreNMS Settings" with "Can view" checked.
**User sees pages but can't import or sync**
: The user has View permission but not Change permission. Edit their Object Permission to also include "Can change".
**User gets "permission denied" when importing devices**
: The user has plugin permissions but may be missing NetBox object permissions. Check that they have `dcim.add_device` and related permissions.
**Background jobs show 403 errors in console**
: In normal usage, the UI only enables background jobs for users allowed to use them and falls back to synchronous processing otherwise, so 403s from background job APIs should not appear. If you see these errors, it usually means a direct API call or custom integration is hitting background-task endpoints without superuser access; update that integration to use synchronous flows or run it with appropriate permissions.

88
docs/usage_tips/suggested_workflow.md Normal file
View File

@@ -0,0 +1,88 @@
# Suggested Workflow
This guide provides a recommended workflow for using the plugin after installation. Following this order helps ensure smooth operation and avoids common issues.
## 1. Configure Plugin Settings
Navigate to **Plugins → LibreNMS Plugin → Settings** and configure:
- **LibreNMS Server**: Select which server to use (if multi-server setup)
- **Device Naming**: Set your preferred defaults for "Use sysName" and "Strip Domain" - see [Import Settings](../librenms_import/import_settings.md)
- **Virtual Chassis Naming**: Configure the member naming pattern if you plan to import stackable devices
**Why first**: These defaults apply to all imports and save time by reducing per-import configuration.
## 2. Verify Custom Field
As of version 0.4.4, the plugin **automatically creates** the `librenms_id` custom field when migrations are run. No manual setup is required. See the [Custom Field Setup](custom_field.md) guide for details on how the field works and optional manual configuration.
**Why early**: This field enables the most reliable device matching and is required for interface, cable, and IP address synchronization features. It is created automatically during `manage.py migrate`, so just verify it exists before importing.
## 3. Prepare NetBox Data
Ensure NetBox has the basic objects needed for device imports:
- **Sites**: Create Sites that match your LibreNMS locations (exact name matching works best)
- **Device Types**: Add Device Types for your common hardware models
- **Device Roles**: Create appropriate roles (Switch, Router, Firewall, etc.)
- **Platforms**: Add Platforms matching your LibreNMS OS names (optional but helpful)
**Why before importing**: The plugin auto-matches these objects during import. Pre-creating them reduces manual configuration during the import process.
## 4. Configure Interface Mappings
If you have specific interface type mapping requirements, configure them via **Plugins → LibreNMS Plugin → Interface Type Mappings** - see [Interface Mappings](interface_mappings.md).
**Why**: Ensure specific NetBox interface types are used for your LibreNMS interface data.
## 5. Import Devices
Use the [Device Import](../librenms_import/overview.md) feature to bring devices into NetBox:
1. Navigate to **Plugins → LibreNMS Plugin → Import → LibreNMS Import**
2. Apply filters to find devices (start with Location or Type)
3. Review validation status and configure missing fields
4. Import devices individually or in bulk
**Tips**:
- Start with a small set (single location or device type) to verify your setup
- Enable Virtual Chassis detection only when importing stackable switches
## 6. Sync VLAN
- Create VLAN objects in NetBox from LibreNMS device VLAN data
- Per-VLAN group assignment with scope-aware auto-selection
## 7. Sync Interfaces
After devices are imported, sync their interfaces:
1. Navigate to a device in NetBox
2. Use the LibreNMS sync button to pull interface data
3. Review and adjust [Interface Mappings](interface_mappings.md) if needed
**Why after import**: Interfaces require the device to exist in NetBox first. The `librenms_id` field set during import enables accurate synchronization.
## 8. Sync Cables and IP Addresses
Complete your device data by syncing:
- **Cables**: Pull link data from LibreNMS to create cable connections
- **IP Addresses**: Import IP assignments to populate NetBox's IPAM
**Why last**: Both features require that interfaces already exist in NetBox and ideally with the `librenms_id` field set. The `librenms_id` field on interfaces ensures accurate matching.
## 9. Sync Locations (Optional)
If you want to synchronize location latitude/longitude data between NetBox Sites and LibreNMS locations, use the location sync feature.
**Why optional**: Only needed if you maintain geographic coordinates and want bidirectional sync.
## Next Steps
After completing the initial workflow:
- Regular imports: Use the same import process for new devices as they're added to LibreNMS
- Interface updates: Re-sync interfaces periodically to capture configuration changes
- Virtual Chassis: See [Virtual Chassis](virtual_chassis.md) for managing multi-member devices
- Background Jobs: Understand [Background Jobs & Caching](../librenms_import/background_jobs.md) for performance optimization

31
docs/usage_tips/virtual_chassis.md Normal file
View File

@@ -0,0 +1,31 @@
# Virtual Chassis Support
## Overview
The plugin automatically detects Virtual Chassis configurations and displays all VC interfaces on the LibreNMS Sync page of the designated sync device.
**LibreNMS Sync Device Selection Priority:**
1. Member with `librenms_id` custom field (highest priority)
2. Master device with primary IP
3. Any member with primary IP
4. Member with lowest VC position
> **Note:** LibreNMS treats a Virtual Chassis as a single logical device. Only one member (the sync device) should have the `librenms_id` custom field set.
## How It Works
### Member Selection
When viewing a device that is part of a virtual chassis, the plugin will:
1. Detects if the device is part of a virtual chassis and displays 'Virtual Chassis Member' column.
2. Automatically select the VC member by matching the device VC position to the first number in the interface name.
3. Allows selection of specific members if the auto select is not correct.
> Selecting a new member will trigger a new interface details comparison against the newly selected NetBox VC member.
Interfaces data is then synced to the selected VC member in Netbox.
#### Virtual Chassis Member Select
![Virtual Chassis Member Selection](../img/Netbox-librenms-plugin-virtualchassis.gif)