Metadata-Version: 2.4
Name: netbox-bmc
Version: 0.4.30
Summary: Unified out-of-band management for NetBox: Redfish & IPMI inventory sync, power control, console access
Author: Takahiro Nagafuchi
License: Apache-2.0
Project-URL: Documentation, https://github.com/tak-labo/netbox-bmc/blob/main/README.md
Project-URL: Source, https://github.com/tak-labo/netbox-bmc
Project-URL: Tracker, https://github.com/tak-labo/netbox-bmc/issues
Keywords: netbox,netbox-plugin
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Networking
Requires-Python: >=3.12.0
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: requests>=2.31
Requires-Dist: pyghmi>=1.5
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# netbox-bmc

[![NetBox](https://img.shields.io/badge/NetBox-4.5%20|%204.6-blue)](https://github.com/netbox-community/netbox)
[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-Apache%202.0-green)](LICENSE)

[日本語](README_ja.md)

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

## Supported Protocols / Vendors

| Protocol | Vendors |
|---|---|
| Redfish | Dell iDRAC, HPE iLO, Lenovo XCC, Supermicro, AMI, Generic |
| WS-MAN | Intel AMT (vPro) |
| IPMI | Fallback for any IPMI-capable BMC |

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

## Tested Hardware

| Manufacturer | Model Series | BMC | Protocol | Status |
|---|---|---|---|---|
| Dell | PowerEdge | iDRAC 9 | Redfish | Expected to work |
| HPE | ProLiant | iLO 5 | Redfish | Expected to work |
| HPE | ProLiant | iLO 6 | Redfish | Expected to work |
| Lenovo | ThinkSystem | XCC2 / XCC3 | Redfish | Expected to work |
| Supermicro | X12 / X13 | BMC | Redfish | Expected to work |
| AMI | ASMB-based servers | AMI Redfish Server | Redfish | Expected to work |
| Intel | vPro-enabled desktops/workstations | AMT 6.0+ | WS-MAN | Expected to work |
| Generic | — | Any IPMI-capable BMC | IPMI | Expected to work (fallback) |

## 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](#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)

```bash
pip install netbox-bmc
python manage.py migrate
```

Add to `configuration.py`:

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

### Docker (netbox-docker)

Follow the [official plugin installation guide](https://github.com/netbox-community/netbox-docker/wiki/Using-Netbox-Plugins).

**`plugin_requirements.txt`**
```
netbox-bmc
```

**`Dockerfile-Plugins`**
```dockerfile
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`**
```yaml
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`**
```python
PLUGINS = ["netbox_bmc"]
PLUGINS_CONFIG = {
    "netbox_bmc": {
        "sync_interval_minutes": 0,
        "default_verify_ssl": False,
    },
}
```

Build and start:
```bash
docker compose build --no-cache
docker compose up -d
```

## Configure

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

| Key | Default | Description |
|---|---|---|
| `sync_interval_minutes` | `0` | Scheduled bulk Module inventory sync interval in minutes. `0` disables. Not yet implemented (stub job). |
| `network_sync_interval_minutes` | `0` | Scheduled bulk network config sync interval in minutes. `0` disables. |
| `sensors_sync_interval_minutes` | `0` | Scheduled bulk sensor telemetry sync interval in minutes. `0` disables. |
| `event_log_sync_interval_minutes` | `0` | Scheduled bulk event log sync interval in minutes. `0` disables. |
| `manager_health_sync_interval_minutes` | `0` | Scheduled bulk BMC health sync interval in minutes. `0` disables. |
| `default_verify_ssl` | `False` | Default SSL verification for new BMC Endpoints. |
| `service_account` | — | Service account name for background jobs (netbox-secrets). |
| `service_private_key_path` | — | Path to private key for service account (netbox-secrets). |

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:

| Button | Action |
|---|---|
| **On** | Power on |
| **Off** | Hard power off (confirm dialog) |
| **Soft** | ACPI graceful shutdown |
| **Cycle** | Power cycle — off then on (confirm dialog) |
| **Reset** | Hard reset (confirm dialog) |
| **Identify On / Off** | Turn the chassis identify LED on/off |

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:

| Card | Sync button | Shows |
|---|---|---|
| Network | Sync Network | All BMC network interfaces (IPv4/IPv6 address, DHCP, VLAN, MAC, hostname/FQDN, DNS servers, link status) |
| Sensors | Sync Sensors | Temperature, fan RPM, voltage, and power consumption readings |
| Event Log | Sync Event Log | Recent System Event Log (SEL) entries |
| Sync Status → BMC Health | Sync Manager Health | BMC health status |

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:

| Raw name (Redfish) | Normalized |
|---|---|
| `CPU.Socket.1` / `Processor 0` | `CPU 0` |
| `DIMM.A1` / `Memory 0` | `Memory 0` |
| `Disk.Bay.0` | `Drive 0` |
| `NIC.Slot.1` (PCIe) | `PCI 0` |

### Custom Fields

The following custom fields are set automatically on each Module:

| Field | Content |
|---|---|
| `bmc_redfish_path` | Source Redfish URI |
| `bmc_firmware_version` | Firmware version string |

## Versions

| netbox-bmc | NetBox |
|---|---|
| 0.4.x | 4.5, 4.6 |

## 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

```bash
# 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](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](LICENSE).
