marcinpsk · marcinpsk · Jul 29, 2026 · Jun 18, 2026 · Jun 18, 2026 · Jun 18, 2026
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -16,6 +16,7 @@
   * [Background Jobs & Caching](librenms_import/background_jobs.md)
 * [Sync & Configuration](usage_tips/virtual_chassis.md)
   * [Virtual Chassis](usage_tips/virtual_chassis.md)
+  * [Out-of-Band Management](usage_tips/oob_management.md)
   * [Interface Mappings](usage_tips/interface_mappings.md)
   * [Module Sync](usage_tips/module_sync.md)
   * [Mapping Rules](usage_tips/mapping_rules.md)

diff --git a/docs/feature_list.md b/docs/feature_list.md
@@ -10,6 +10,15 @@
 * Background job processing for large device sets
 * Duplicate detection to prevent re-importing existing devices
 
+### [Out-of-Band (OOB) Management](usage_tips/oob_management.md)
+
+* Detects when a LibreNMS device (iDRAC/iLO/BMC/IPMI/CIMC) is the OOB controller of an existing NetBox device
+* **Add as OOB** — link the controller to the host and set `oob_ip` on a chosen (or new) interface
+* **Promote to host** — re-point a device currently linked to its OOB controller onto the incoming host device
+* **Merge NetBox devices** — reconcile two devices (hostname-matched vs serial-matched) that represent one physical box
+* Per-server linkage stored in the `librenms_id` custom field as `{"<server_key>": {"id": N, "oob": {"id": M, "type": "drac"}}}`
+* Post-merge **Move to winner** actions to migrate interfaces, IP addresses, and primary/OOB IPs at your own pace
+
 ### [Module / Inventory Sync](usage_tips/module_sync.md)
 
 * Compare LibreNMS ENTITY-MIB inventory to NetBox module bays and installed modules

diff --git a/docs/img/oob/oob-create-new-interface.png b/docs/img/oob/oob-create-new-interface.png
diff --git a/docs/img/oob/oob-detected-validation.png b/docs/img/oob/oob-detected-validation.png
diff --git a/docs/librenms_import/validation.md b/docs/librenms_import/validation.md
@@ -46,6 +46,11 @@ The plugin checks for existing devices using:
 
 If both a VM and Device with the same hostname exist, the plugin cannot determine which to match and allows import. Set the `librenms_id` custom field on the correct existing object to clarify the match.
 
+## Out-of-Band (OOB) Detection
+
+When an incoming LibreNMS device looks like an out-of-band controller (iDRAC, iLO, BMC, …) and matches an existing NetBox device, the validation details show an **OOB Detected** panel instead of a plain import button. Rather than creating a duplicate device, the plugin offers the appropriate reconciliation action — **Add as OOB**, **Promote to host**, or **Merge NetBox devices**. See [Out-of-Band (OOB) Management](../usage_tips/oob_management.md) for the full flow.
+
 ## Next Steps
 
 - [Import Settings](import_settings.md) - Configure device naming and import options
+- [Out-of-Band Management](../usage_tips/oob_management.md) - Reconcile OOB controllers with their host devices
diff --git a/docs/usage_tips/custom_field.md b/docs/usage_tips/custom_field.md
@@ -49,6 +49,13 @@ If the field was not created automatically (fallback): follow these steps to cre
         ```json
         {"production": 42, "staging": 17}
         ```
+      - Out-of-band (OOB) form — when a device is linked to its OOB controller, the per-server value is an object holding the host id and the controller's id/type:
+
+        ```json
+        {"production": {"id": 42, "oob": {"id": 99, "type": "drac"}}}
+        ```
+
+        This shape is written automatically by the OOB flows — see [Out-of-Band Management](oob_management.md). You don't normally edit it by hand.
       - Legacy single-server example (integer) — read-only/deprecated; do not use for new entries:
         ```
         42

diff --git a/docs/usage_tips/oob_management.md b/docs/usage_tips/oob_management.md
@@ -0,0 +1,86 @@
+# Out-of-Band (OOB) Management
+
+Many servers expose a dedicated **out-of-band management controller** — iDRAC, iLO, BMC, IPMI, CIMC, and similar. LibreNMS usually polls that controller as its **own device**, separate from the host it lives in. NetBox models the same relationship differently: the controller is not a separate Device — its address is the host Device's **OOB IP** (`oob_ip`).
+
+This plugin bridges the two models. During import it detects when an incoming LibreNMS device is really the OOB side of a host you already have, and offers the right action to reconcile them instead of creating a duplicate device.
+
+## How the link is stored
+
+OOB linkage is recorded in the `librenms_id` [custom field](custom_field.md) alongside the host's own LibreNMS ID. The per-server value is promoted from a bare integer to a small object:
+
+```json
+{
+  "production": {
+    "id": 42,
+    "oob": { "id": 99, "type": "drac" }
+  }
+}
+```
+
+- `id` — the LibreNMS device ID of the **host**.
+- `oob.id` — the LibreNMS device ID of the **OOB controller**.
+- `oob.type` — a short label for the controller (`idrac`, `drac`, `ilo`, `bmc`, `ipmi`, `cimc`, …), or the generic `oob` when the specific type can't be determined.
+
+Only these identity essentials are stored. The controller's IP and firmware version are intentionally **not** persisted here — the IP's source of truth is the host Device's interface-assigned `oob_ip`, and the version lives in LibreNMS and can be read back any time from `oob.id`.
+
+## OOB detection during import
+
+When a searched LibreNMS device looks like an OOB controller (by its OS/hardware strings, e.g. an iDRAC) and matches an existing NetBox device, the validation details show an **OOB Detected** panel instead of a plain import button. From there one of three resolution flows is offered, depending on what already exists.
+
+![OOB Detected validation panel, showing the OOB attach effect and the Add-as-OOB action](../img/oob/oob-detected-validation.png)
+
+!!! tip "Not seeing the panel?"
+    The panel only appears when **both** conditions hold: the incoming LibreNMS device's `os`/`hardware` (or hostname) matches an OOB pattern (`idrac`, `ilo`, `ipmi`, `bmc`, `drac`, `cimc`), **and** it matches an existing NetBox device by unique **serial** or by **management IP**. If the incoming hostname already matches a NetBox device name it takes the plain hostname-match path instead, and if the device is already linked to LibreNMS no OOB action is offered. (Device identifiers are blurred in these screenshots.)
+
+### Add as OOB
+
+Use when the existing NetBox device is the **host** and the incoming LibreNMS device is its OOB controller.
+
+The **Add as OOB to *device*** action links the controller's LibreNMS ID into the host's `oob.id` slot. NetBox requires `oob_ip` to be assigned to one of the device's interfaces, so the form includes an **OOB IP interface** picker:
+
+- A sensible interface is **pre-selected** (matched by name — `idrac`/`ilo`/`bmc`-style). Because the OOB IP is frequently *not* physically on that interface, the selection is **overridable**.
+- Choose **+ Create new interface…** to create one (default name suggested) to hang the OOB IP on.
+
+![OOB IP interface picker with "+ Create new interface" selected and a suggested name](../img/oob/oob-create-new-interface.png)
+
+The OOB IP is then created (or re-homed) assigned to the chosen interface and set as the device's `oob_ip`. If you make no interface selection, the link is still recorded and the OOB IP is left for you to set later.
+
+!!! note "Permissions"
+    Setting the OOB IP can create an Interface, create an IPAddress, or re-home an existing one. The action requires the matching NetBox `add`/`change` permissions for those models; if you lack them the link is still recorded and the IP step is skipped with a warning. See [Permissions & Access](permissions.md).
+
+### Promote to host
+
+Use when the existing NetBox device is currently linked to the **OOB controller** (its `librenms_id` points at the controller) and the incoming LibreNMS device is the **host** side.
+
+**Promote to host of *device*** re-points the linkage: the incoming host's LibreNMS ID becomes the device's `id`, and the previously-linked controller ID is demoted into the `oob` slot. No new device is created. A pre-promote modal lets you optionally override the device's **name**, **device type**, and **platform** — all default to **Keep current**, so the original promote behaviour is unchanged unless you explicitly choose **Use new**.
+
+### Merge NetBox devices
+
+Use when **two different NetBox devices** turn out to represent one physical box — typically one created from the LibreNMS hostname and another from the chassis serial, where at least one already carries a LibreNMS link.
+
+The validation modal lists both candidates (hostname-matched and serial-matched) with their current linkage, and you pick which one to **keep** (the *winner*) and which to absorb (the *donor*). Merging consolidates the donor's LibreNMS link state under the active server key into the winner, clears the donor's active link, and writes a `_migrated_to` marker on the donor pointing at the winner. Interfaces, cables, and primary/OOB IPs are **not** moved automatically — you re-home those incrementally (see below).
+
+## Migrating a donor device after a merge
+
+A donor device (one with a `_migrated_to` marker) shows a banner on its LibreNMS sync page with **Move to winner** actions, so you can move resources over at your own pace:
+
+- **Move interface to winner** — reassigns an interface (and the cables, IPs, and MACs that hang off it) to the winner. Fails if the winner already has an interface with the same name — rename or remove that one first.
+- **Move IP address to winner** — re-homes an interface-assigned IP to the winner's same-named interface (move the interface first if it doesn't exist on the winner yet).
+- **Transfer primary IPv4 / IPv6 / OOB IP** — points the winner's `primary_ip4` / `primary_ip6` / `oob_ip` foreign key at the donor's value and clears it on the donor. Refuses to overwrite a value already set on the winner — clear it there first.
+
+Each action runs under a row lock and verifies the `_migrated_to` marker before touching anything. Once the donor has nothing left to migrate you can delete it.
+
+## Setting Primary and OOB IPs in general
+
+Outside the OOB import flows, both `primary_ip` and `oob_ip` are driven from interface-assigned addresses:
+
+- **Primary IP** is set on the device's **IP Addresses** sync tab: with **Set Primary IP** enabled, a synced IP that matches the LibreNMS management IP and is interface-assigned becomes the device's primary.
+- **OOB IP** is set through the **Add as OOB** flow above.
+
+This keeps every IP relationship valid against NetBox's requirement that primary/OOB IPs be assigned to one of the device's own interfaces.
+
+## See also
+
+- [Custom Field Setup](custom_field.md) — the `librenms_id` field that stores the linkage.
+- [Validation & Configuration](../librenms_import/validation.md) — where OOB is detected during import.
+- [Permissions & Access](permissions.md) — permissions required for the OOB/IP actions.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -20,6 +20,7 @@ nav:
     - Background Jobs & Caching: librenms_import/background_jobs.md
   - Sync & Configuration:
     - Virtual Chassis: usage_tips/virtual_chassis.md
+    - Out-of-Band Management: usage_tips/oob_management.md
     - Interface Mappings: usage_tips/interface_mappings.md
     - Module Sync: usage_tips/module_sync.md
     - Mapping Rules: usage_tips/mapping_rules.md

diff --git a/netbox_librenms_plugin/constants.py b/netbox_librenms_plugin/constants.py
@@ -1,6 +1,53 @@
+import re
+
 # Plugin permissions (from LibreNMSSettings model)
 PERM_VIEW_PLUGIN = "netbox_librenms_plugin.view_librenmssettings"
 PERM_CHANGE_PLUGIN = "netbox_librenms_plugin.change_librenmssettings"
 
 # LibreNMS VLAN state values
 LIBRENMS_VLAN_STATE_ACTIVE = 1
+
+# OOB management controller detection
+# Trailing \d*\b restricts matches to whole tokens (optionally with a numeric suffix like
+# iDRAC9 / drac9) so a prefix collision inside an unrelated word — e.g. "dracut", "ipmitool"
+# — can't misclassify a normal device as an OOB controller.
+OOB_TYPE_PATTERN = re.compile(r"\b(idrac|ilo|ipmi|bmc|drac|cimc|oob)\d*\b", re.IGNORECASE)
+OOB_TYPES = ("idrac", "ilo", "ipmi", "bmc", "drac", "cimc", "oob")
+
+# Shared "From OOB controller" badge markup (the bare <span>; callers add any leading space).
+# Centralised so a restyle (color/title/text) happens in one place instead of drifting across the
+# cable/module/interface tables and the cable-verify render that each hand-copied it.
+OOB_BADGE_HTML = '<span class="badge bg-purple text-white ms-1" title="From OOB controller">OOB</span>'
+
+
+def normalize_oob_type(os_str: str, hardware_str: str = "") -> str | None:
+    """
+    Extract and normalize the OOB controller type from LibreNMS os/hardware strings.
+
+    A vendor-specific match (idrac/ilo/ipmi/bmc/drac/cimc) always wins over the
+    generic ``oob`` token, even when ``oob`` appears earlier in the text, so e.g.
+    ``normalize_oob_type("oob", "iDRAC9")`` resolves to ``"idrac"`` rather than
+    being masked by the generic token.
+
+    Args:
+        os_str (str): LibreNMS ``os`` field for the device.
+        hardware_str (str): LibreNMS ``hardware`` field for the device.
+
+    Returns:
+        str | None: The canonical lowercase token (one of OOB_TYPES), or None if
+            no token matches.
+
+    Examples:
+        normalize_oob_type("drac9", "iDRAC9") → "drac"
+        normalize_oob_type("oob", "iDRAC9")   → "idrac"
+        normalize_oob_type("ilo", "")         → "ilo"
+        normalize_oob_type("ubuntu", "")      → None
+    """
+    generic = None
+    for text in (os_str or "", hardware_str or ""):
+        for m in OOB_TYPE_PATTERN.finditer(text):
+            token = m.group(1).lower()
+            if token != "oob":
+                return token  # vendor-specific match wins immediately
+            generic = generic or "oob"  # remember the generic fallback, keep scanning
+    return generic