From b324e3af29cb14336b27dedff3b5d5b5e136a719 Mon Sep 17 00:00:00 2001 From: Andy Norwood Date: Fri, 5 Jun 2026 14:33:20 +0000 Subject: [PATCH] docs: review and fill gaps for v0.4.7 release - Add Module Sync and Mapping Rules to mkdocs and SUMMARY navigation - Document the opt-in "Set Primary IP" toggle on IP Address Sync (#303) - Add developer Extension Points page for the predict_module_interface_names signal and VC normalization report (#298) - Note module-interface adoption in the Module Sync guide (#296) - Sync root README and docs README feature sections (Module/Inventory Sync, hardware-model filter, Platform Mappings link, multi-server) --- README.md | 18 ++++++++++++++--- docs/README.md | 8 ++++++++ docs/SUMMARY.md | 3 +++ docs/development/README.md | 1 + docs/development/extension_points.md | 30 ++++++++++++++++++++++++++++ docs/feature_list.md | 1 + docs/usage_tips/module_sync.md | 6 ++++++ mkdocs.yml | 3 +++ 8 files changed, 67 insertions(+), 3 deletions(-) create mode 100644 docs/development/extension_points.md diff --git a/README.md b/README.md index 6abcffcb3..3a9402d9d 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ 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, or system name +- 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 @@ -21,13 +21,23 @@ Search and import devices from LibreNMS into NetBox with comprehensive validatio See the [Device Import Guide](docs/librenms_import/overview.md) 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](docs/usage_tips/module_sync.md) and [Mapping Rules Guide](docs/usage_tips/mapping_rules.md) 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 +- Platform (via [Platform Mappings](docs/usage_tips/mapping_rules.md#platform-mappings)) ### Interface Sync Pull interface data from Devices and Virtual Machines from LibreNMS into NetBox. The following interface attributes are synchronized: @@ -49,6 +59,8 @@ Create cable connection 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 @@ -57,7 +69,7 @@ Create IP address in NetBox from LibreNMS device IP data. - Add device to LibreNMS from Netbox device page. SNMP v2c and v3 are supported. -### Site & Location Synchronization +### 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 diff --git a/docs/README.md b/docs/README.md index 216d76f8e..6e4541f20 100644 --- a/docs/README.md +++ b/docs/README.md @@ -65,6 +65,8 @@ Create cable connection in NetBox from LibreNMS links data. 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 @@ -82,6 +84,12 @@ The plugin also supports synchronizing NetBox Sites with LibreNMS locations: * 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 diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 4e4a64952..8f1a38b80 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -17,12 +17,15 @@ * [Sync & Configuration](usage_tips/virtual_chassis.md) * [Virtual Chassis](usage_tips/virtual_chassis.md) * [Interface Mappings](usage_tips/interface_mappings.md) + * [Module Sync](usage_tips/module_sync.md) + * [Mapping Rules](usage_tips/mapping_rules.md) * [Development](development/README.md) * [Overview](development/README.md) * [Project Structure](development/structure.md) * [Views & Inheritance](development/views.md) * [Mixins](development/mixins.md) * [Templates](development/templates.md) + * [Extension Points](development/extension_points.md) * [Testing](development/testing.md) * [Changelog](changelog.md) * [Contributing](contributing.md) diff --git a/docs/development/README.md b/docs/development/README.md index de81c7d02..3a5ffd413 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -8,3 +8,4 @@ This guide is intended for developers and contributors working on the NetBox Lib - [Views & Inheritance](./views.md): How views are organized, inheritance patterns, and extension tips. - [Mixins](./mixins.md): Reusable logic for views, including API access and caching. - [Templates](./templates.md): Template structure, conventions, and customization tips. +- [Extension Points](./extension_points.md): Public signals and hooks other plugins can use to extend behaviour. diff --git a/docs/development/extension_points.md b/docs/development/extension_points.md new file mode 100644 index 000000000..9db072548 --- /dev/null +++ b/docs/development/extension_points.md @@ -0,0 +1,30 @@ +# Extension Points + +The plugin exposes a small number of public hooks so other NetBox plugins can adjust its behaviour without forking the code. These are intentionally stable — internal helpers may change between releases, but the hooks described here are meant to be relied on. + +## Module Interface Name Prediction + +When Module Sync adopts a module, it derives the interface names that module *should* have by instantiating the module type's interface templates against the device. Some vendors use naming conventions this can't capture (for example, breakout ports that expand one physical port into several logical interfaces). The `predict_module_interface_names` signal lets another plugin rewrite those names before they are used for matching. + +The signal is defined in [signals.py](../../netbox_librenms_plugin/signals.py) and fired from `get_module_template_interface_names()` in [utils.py](../../netbox_librenms_plugin/utils.py). Each receiver is called with keyword arguments `sender` (the `Module` class), `device`, `module`, and `names` (the predicted `list[str]`, already rewritten for the VC member position where applicable). Always accept `**kwargs` so future arguments don't break your receiver. + +Return the list of names to use, or `None` to leave the current list unchanged (an empty list is valid and means "no interface names"). When multiple receivers are connected they run in connection order and the **last non-`None` return wins**. The signal is dispatched with Django's `send_robust()`, so a receiver that raises is logged and skipped rather than breaking module adoption. + +```python +from django.dispatch import receiver + +from netbox_librenms_plugin.signals import predict_module_interface_names + + +@receiver(predict_module_interface_names) +def expand_breakout_ports(sender, device, module, names, **kwargs): + """Expand each predicted name into four breakout sub-interfaces.""" + expanded = [] + for name in names: + expanded.extend(f"{name}/{lane}" for lane in range(1, 5)) + return expanded +``` + +Connect the receiver from your plugin's `ready()` method so it is registered when NetBox starts. + +When a module on a Virtual Chassis member has no template names matching the member-position pattern, the Module Sync table offers a pre-filled report (built by `build_vc_normalization_report()` in [utils.py](../../netbox_librenms_plugin/utils.py)) that a user can copy into a GitHub issue to request support for that naming convention. This signal is the recommended way to add such support yourself without waiting for an upstream change. diff --git a/docs/feature_list.md b/docs/feature_list.md index 1c4cb5ff4..c46a70702 100644 --- a/docs/feature_list.md +++ b/docs/feature_list.md @@ -73,6 +73,7 @@ ### IP Address Sync {#ip-address-sync} * Create IP address objects in Netbox from LibreNMS device IP data +* Optionally set the device or VM Primary IP from the LibreNMS management IP (opt-in **Set Primary IP** toggle on the IP Address Sync tab) * Best results when the [custom field](usage_tips/custom_field.md) `librenms_id` is populated on interfaces ### VLAN Sync {#vlan-sync} diff --git a/docs/usage_tips/module_sync.md b/docs/usage_tips/module_sync.md index 247c20226..656714325 100644 --- a/docs/usage_tips/module_sync.md +++ b/docs/usage_tips/module_sync.md @@ -33,6 +33,12 @@ Each row in the table shows: - **Add Mapping** — opens the ModuleBayMapping or ModuleTypeMapping creation modal directly from the row, so you can resolve "No Bay" or "No Type" statuses without leaving the page - **Add Bay Template** — if the device type is missing a module bay template, this button creates it inline +## Module Interfaces + +When a module type defines interface templates, installing the module also reconciles the device's interfaces with those templates. The plugin works out the names the module's interfaces should have (instantiating each interface template against the device, and rewriting names for Virtual Chassis members where needed), then adopts any existing standalone interfaces on the device that match those names into the newly installed module. This keeps interfaces that were created by a previous interface sync from being duplicated, and links them to the module that physically provides them. + +For vendors whose naming conventions cannot be derived from templates alone, the predicted names can be adjusted by another plugin through a signal hook — see [Extension Points](../development/extension_points.md) for details. + ## Carrier Modules Some chassis (e.g. Nokia 7750 SR-s) report child components (CPMs, MDAs) without the intermediate carrier/holder module that must first be installed in NetBox before the children become visible. When a CarrierAutoInstallRule matches, an **Install Carrier** button appears — clicking it installs the carrier module into the appropriate empty bay, after which the children can be synced normally. diff --git a/mkdocs.yml b/mkdocs.yml index 2fd2259ae..e38dd729a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -21,12 +21,15 @@ nav: - Sync & Configuration: - Virtual Chassis: usage_tips/virtual_chassis.md - Interface Mappings: usage_tips/interface_mappings.md + - Module Sync: usage_tips/module_sync.md + - Mapping Rules: usage_tips/mapping_rules.md - Development: - Overview: development/README.md - Project Structure: development/structure.md - Views & Inheritance: development/views.md - Mixins: development/mixins.md - Templates: development/templates.md + - Extension Points: development/extension_points.md - Testing: development/testing.md - Changelog: changelog.md - Contributing: contributing.md