bonzo81 · bonzo81 · Jun 5, 2026 · Jun 5, 2026
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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