netbox-bmc

日本語

Unified out-of-band management plugin for NetBox.
Inventory sync and power control via Redfish & IPMI.

Supported Protocols / Vendors

Protocol is auto-detected: probes /redfish/v1 first, then WS-MAN port 16993 (Intel AMT), falls back to IPMI.

Tested Hardware

Features

• Module Builder: Sync BMC hardware inventory to NetBox Modules
  • Scan via Redfish → preview detected components with diff badges (new / updated / unchanged / removed)
  • Select individual components before applying
  • Auto-create ModuleBays when missing (warned in preview)
  • Detect serial number changes after FRU replacement and apply diff updates
  • Only manages bmc-synced-tagged Modules; never touches manually created Modules
• Collected components: CPU, Memory, Drive, PSU, Fan, Firmware, PCI devices
  • PSU and Fan collected via Chassis link; PCIe via PCIeDevices collection
• Vendor auto-detection: Dispatches to Dell / HPE / Lenovo / AMI subclass drivers based on ServiceRoot Vendor / Oem keys
• Power control: on / off / soft / cycle / reset (both protocols)
• Identify LED: turn the chassis identify light on/off (supports ETag/If-Match preconditions required by strict Redfish implementations)
• BMC network configuration: shows all of the BMC's own network interfaces (not just one), including IPv6 addresses/gateway, DHCP state, VLAN, DNS servers; USB gadget interfaces are excluded
• Sensor telemetry: temperature, fan RPM, voltage, and power consumption readings
• System Event Log (SEL): recent BMC event log entries
• BMC health & firmware: BMC health status and firmware version
• Background sync jobs: Network / Sensors / Event Log / BMC Health are persisted to the database and refreshed via a per-endpoint "Sync" button or an optional scheduled job (see Configure) — pages read from the database instead of querying the BMC on every load. BMC Firmware is refreshed as part of the Inventory scan instead, since it rarely changes.
• Test Connection: validate protocol/credentials before saving a new BMC Endpoint
• Device Role filter: narrow the Device picker by role when adding a BMC Endpoint
• Device page integration: a "View BMC Endpoint" button and status panel appear on the Device page automatically when a BMC Endpoint exists
• REST API: CRUD for BMCEndpoint via /api/plugins/bmc/endpoints/
• English / Japanese UI (i18n)

Install

Standard (non-Docker)

pip install netbox-bmc
python manage.py migrate

Add to configuration.py:

PLUGINS = ["netbox_bmc"]
PLUGINS_CONFIG = {
    "netbox_bmc": {
        "sync_interval_minutes": 0,
        "default_verify_ssl": False,
    },
}

Docker (netbox-docker)

Follow the official plugin installation guide.

plugin_requirements.txt

netbox-bmc

Dockerfile-Plugins

FROM netboxcommunity/netbox:latest

COPY ./plugin_requirements.txt /opt/netbox/
RUN /usr/local/bin/uv pip install -r /opt/netbox/plugin_requirements.txt

docker-compose.override.yml

services:
  netbox:
    image: netbox:latest-plugins
    pull_policy: never
    build:
      context: .
      dockerfile: Dockerfile-Plugins
  netbox-worker:
    image: netbox:latest-plugins
    pull_policy: never

configuration/plugins.py

PLUGINS = ["netbox_bmc"]
PLUGINS_CONFIG = {
    "netbox_bmc": {
        "sync_interval_minutes": 0,
        "default_verify_ssl": False,
    },
}

Build and start:

docker compose build --no-cache
docker compose up -d

Configure

Edit PLUGINS_CONFIG["netbox_bmc"] in configuration.py:

Each *_sync_interval_minutes setting, when greater than 0, schedules a recurring job that syncs that data point for all BMC Endpoints. Independently of these settings, each Endpoint detail page also has a manual "Sync" button per card (Network / Sensors / Event Log / BMC Health) that syncs just that one endpoint on demand.

Use

Inventory Sync

1. Open a Device in NetBox and click BMC Endpoints → Add
2. Enter the BMC address and credentials, then save
3. On the Endpoint detail page, click [Build Modules]
4. Review the component preview (new / updated / unchanged / removed)
5. Check the components to sync and click [Apply Selected]

ModuleBays, ModuleTypes, and Modules are created or updated automatically.

Power Control

From the Endpoint detail page, use the power button group:

Power status is always fetched live (never cached), so it reflects the real state right after a power action.

Network / Sensors / Event Log / BMC Health

Each of these has its own card on the Endpoint detail page with a Sync button:

Clicking a Sync button queues a background job; once it completes, the card's "Last Sync" timestamp updates and the table reflects the new data. BMC Firmware (also shown in the Sync Status card) is refreshed as part of running Build Modules, not via its own Sync button, since it rarely changes.

Module Naming

Vendor-specific names are normalized to a consistent format:

Custom Fields

The following custom fields are set automatically on each Module:

Versions

Vendor Notes

Dell iDRAC

iDRAC 9 (Redfish 1.x) is the primary target. URI traversal starts from ServiceRoot links — no hardcoded paths — so firmware variations should be absorbed automatically.

HPE iLO

iLO 5 and iLO 6 are supported via the HPE subclass driver. iLO 4 (Redfish 1.0 partial compliance) is not tested and may not work correctly.

Lenovo XCC

XCC2 and XCC3 are supported. Some older XCC firmware versions expose non-standard collection URIs; the link-traversal approach handles most variations.

Supermicro

Generic Redfish driver is used. Supermicro BMC firmware varies significantly; behaviour may differ across firmware versions.

AMI (American Megatrends)

AMI Redfish Server (detected via Vendor: "AMI" in ServiceRoot). PCIe devices are exposed under Chassis/PCIeDevices rather than Systems/PCIeDevices; the AMI subclass driver handles this automatically. Hardware inventory (CPU, Memory) populates only when the host is powered on.

Intel AMT (Active Management Technology)

Intel AMT is built into vPro-enabled CPUs (6th gen+). Accessed via WS-MAN (SOAP/XML over HTTPS on port 16993) with HTTP Digest authentication.

Auto-detection: if Redfish is unavailable, detect_and_build() probes port 16993 with a WS-MAN Identify request. If AMT responds, IntelAmtDriver is selected; otherwise falls back to IPMI.

To force AMT: set protocol = "wsman" on the BMCEndpoint.

Collected: CPU (CIM_Processor), Memory (CIM_PhysicalMemory), AMT firmware version (WS-MAN Identity). Storage and PCIe are not available via AMT WS-MAN.

AMT must be provisioned and the management port must be reachable (not firewalled). AMT 5.x and below are not tested.

Development

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

Adding a New Vendor

1. Add a subclass in netbox_bmc/drivers/redfish.py extending RedfishDriver
2. Register it in detect_and_build() in netbox_bmc/drivers/base.py by matching ServiceRoot vendor keys
3. Add unit tests in tests/test_redfish_extensions.py

Adding a New Protocol

Implement BaseDriver (netbox_bmc/drivers/base.py) and return InventoryResult from get_inventory().

Credentials

netbox-bmc resolves BMC credentials in the following order:

1. netbox-secrets (preferred) — Secret with role bmc-credentials assigned to the Device.
   Secret.name = BMC username, Secret.plaintext = BMC password (RSA-encrypted).
2. Plaintext fallback — username / password fields on BMCEndpoint, used when netbox-secrets is not installed or no matching secret is found.

For background jobs (scheduled sync), set service_account and service_private_key_path in PLUGINS_CONFIG so the job can decrypt secrets without an HTTP session.

See docs/NETBOX_SECRETS.md (Japanese) for a full setup walkthrough, including SecretRole/UserKey/service-account setup and the session-unlock flow.

Known Limitations

• REST API only covers BMCEndpoint CRUD; sync triggers and sensor/event-log/network readouts are not exposed via the API
• Multi-node chassis (multiple Systems) not supported
• Scheduled bulk Module inventory sync (ScheduledInventorySyncJob) not yet implemented (Network/Sensors/Event Log/BMC Health scheduled sync is implemented)
• KVM / SOL console not yet ported from the predecessor plugin
• Old BMCs with low Redfish compliance (e.g. HPE iLO 4) not validated

License

Apache License 2.0 — see LICENSE.