Christian Manivong
8dac2e67dd
driver / standard (pull_request) Successful in 13s
driver / lint (pull_request) Successful in 11s
driver / types (pull_request) Successful in 46s
driver / test (3.10) (pull_request) Successful in 51s
driver / test (3.11) (pull_request) Successful in 55s
driver / test (3.12) (pull_request) Successful in 49s
driver / test (3.13) (pull_request) Successful in 43s
driver / lowest (pull_request) Successful in 26s
driver / security (pull_request) Successful in 49s
driver / build (pull_request) Successful in 22s
CI / driver (pull_request) Successful in 6m5s
driver / publish (pull_request) Skipped
- CI arrives in .gitea/workflows/ci.yml and calls the shared driver workflow of NAPALM/driver-standard; the repo had none before. - setuptools>=77 and the SPDX license string PEP 639 wants, without the License classifier; py.typed; Repository, Issues and Changelog links on git.netork.io; napalm-device-types>=4.21.1 from PyPI. - True floors, found by running the tests at them: redfish>=3.4.1 (older releases return no response with max_retry=0) and pyghmi>=1.5.1 (1.5.0 imports python-dateutil without declaring it). - The test extra becomes the dev extra of the standard, plus responses, which the tests mock the BMC with. pytest puts the repo root on the path, so tests.conftest also imports under a bare pytest. - mypy strict; exempt for now (50 errors, most of them getters returning dicts where the role declares TypedDicts): napalm_redfish.bmc, .driver, .ipmi, .transport and parsers.common, .environment, .manager, .system. They are recorded in tests/quality_baseline.json with seven functions over complexity 10. - Coverage floor 94 % (measured 94.27 %). - The README's development steps install from PyPI.
119 lines
5.5 KiB
Markdown
119 lines
5.5 KiB
Markdown
# napalm-redfish
|
|
|
|
NAPALM driver for server **baseboard management controllers (BMCs)** over
|
|
[DMTF Redfish](https://www.dmtf.org/standards/redfish), with an IPMI fallback for
|
|
boards that predate Redfish. Built on
|
|
[napalm-device-types](https://git.netork.io/NAPALM/napalm-device-types). Written for netOrk.
|
|
|
|
**Status: early development.** Two drivers, both `ManagementControllerDriver`s from
|
|
napalm-device-types:
|
|
|
|
- `redfish` (`napalm_redfish.RedfishDriver`) implements the NAPALM getters and the role
|
|
methods in [docs/redfish-map.md](docs/redfish-map.md), tested end to end against DMTF
|
|
mockups. A BMC that refuses Redfish for want of a vendor license (a Supermicro X10
|
|
without SUM, DCMS or OOB) still opens: the driver reports `bmc_license_required` through
|
|
`get_device_warnings` instead of failing.
|
|
- `ipmi` (`napalm_redfish.ipmi.IpmiDriver`) reads over IPMI 2.0: FRU facts and
|
|
inventory, sensors, power state, event log, BMC firmware. It also switches the server's
|
|
power (chassis control), but does not reset the BMC. Tested against recordings of a
|
|
Supermicro X10DRL-i (BMC 3.91), which refuses Redfish without a license.
|
|
|
|
## Why Redfish, and why not one driver per vendor
|
|
|
|
Redfish is the DMTF's REST API for management controllers. Supermicro (X10 with Redfish
|
|
firmware, X11 and later), Dell iDRAC, HPE iLO and Lenovo XCC all implement it. One driver
|
|
with small vendor quirk modules covers all of them; a `napalm-supermicro-ipmi` would cover
|
|
one.
|
|
|
|
IPMI over LAN stays a **fallback** for boards without Redfish. Its IPMI 2.0
|
|
RAKP handshake hands the password hash to anyone who asks (CVE-2013-4786), so netOrk should
|
|
not depend on it. Finding IPMI over LAN enabled is itself worth reporting, see
|
|
[docs/security.md](docs/security.md).
|
|
|
|
## Layout
|
|
|
|
| Entry point | Transport | Scope |
|
|
|---|---|---|
|
|
| `redfish` | HTTPS, Redfish REST (session token or basic auth) | Read, plus power control and BMC reset |
|
|
| `ipmi` | IPMI 2.0 over LAN (UDP 623) via `pyghmi` | Read, plus power control (no graceful restart, no power cycle); no BMC reset |
|
|
| `bmc` | Redfish first, IPMI where Redfish does not answer | Everything `redfish` does; a BMC that refuses Redfish (no license) is read and switched over IPMI, and a getter that fails over Redfish is asked over IPMI |
|
|
|
|
`bmc` is the one to choose when unsure: it follows the BMC's license as it changes. A
|
|
Supermicro X10 without a license is read over IPMI, with SFT-OOB-LIC over Redfish (which then
|
|
reads more than IPMI: CPUs, DIMMs, NICs, power draw, the BIOS version, the SMBIOS UUID), and
|
|
with DCMS also its drives and firmware inventory. `optional_args`: those of `redfish`, plus
|
|
`ipmi_port` (623).
|
|
|
|
`get_licenses()` (`redfish`, `bmc`) reports the licenses the BMC asks for as facts:
|
|
`{"name": "DCMS", "status": "missing", "withholds": ["drives", "firmware inventory"]}`.
|
|
Whether that is worth a warning is the caller's to decide.
|
|
|
|
Vendor quirks (Supermicro, Dell, HPE, Lenovo) live in one module per vendor, selected from
|
|
the service root's `Vendor`/`Oem` data and `Manager.Model`. No separate entry point per
|
|
vendor.
|
|
|
|
## Documents
|
|
|
|
- [docs/role.md](docs/role.md): the role base this needs in napalm-device-types (draft)
|
|
- [docs/redfish-map.md](docs/redfish-map.md): getters mapped to Redfish resources
|
|
- [docs/supermicro-x10.md](docs/supermicro-x10.md): first test device, its Redfish level, IPMI
|
|
- [docs/security.md](docs/security.md): credentials, IPMI over LAN, power control
|
|
- [docs/testing.md](docs/testing.md): DMTF mockups, emulators, fixtures to record
|
|
- [docs/references.md](docs/references.md)
|
|
|
|
## Building without hardware
|
|
|
|
Unlike most drivers in this organisation, much of this one can be built and tested
|
|
without a device: the DMTF publishes complete mockups of Redfish services (DSP2043), and
|
|
both the DMTF Redfish-Mockup-Server and OpenStack's sushy-tools serve them over HTTP.
|
|
Recorded output from the X10DRL-i then covers what the mockups do not: an old Redfish 1.0.x
|
|
implementation and Supermicro's quirks.
|
|
|
|
## Conventions
|
|
|
|
These follow the other drivers in the `NAPALM` organisation:
|
|
|
|
- Role bases declare, they never implement. Generic logic goes into napalm-device-types,
|
|
vendor mechanics stay here.
|
|
- Parsing lives in pure functions, tested on recorded responses under
|
|
`tests/fixtures/<vendor>-<model>-<firmware>/`, with a `COMMANDS.txt` (here: the request
|
|
paths) listing what produced each file.
|
|
|
|
## Usage
|
|
|
|
```python
|
|
import napalm
|
|
|
|
driver = napalm.get_network_driver("redfish")
|
|
with driver(
|
|
"bmc01.example.net", "netork", "secret", optional_args={"verify_ssl": "/etc/netork/bmc-ca.pem"}
|
|
) as bmc:
|
|
bmc.get_facts() # the BMC: firmware as os_version, its ports
|
|
bmc.get_power_state() # the server: {"state": "On", "actions": [...]}
|
|
bmc.get_hardware_inventory()
|
|
```
|
|
|
|
Optional args: `port` (443), `verify_ssl` (`True`, `False` or a CA file path; default
|
|
`True`), `auth` (`auto`, `session` or `basic`; `auto` uses a Redfish session and falls back
|
|
to basic auth only if the service cannot create sessions), `retries` (1).
|
|
|
|
`reboot_host` restarts the BMC, never the server; the server is switched through
|
|
`set_power_state`. `get_config` is not implemented: a BMC has no configuration file.
|
|
|
|
## Development
|
|
|
|
The rules are in [STANDARDS.md](https://git.netork.io/NAPALM/driver-standard/src/branch/main/STANDARDS.md).
|
|
|
|
```bash
|
|
python -m venv .venv && . .venv/bin/activate
|
|
pip install -e '.[dev]'
|
|
pytest --cov
|
|
```
|
|
|
|
Fixtures from the DMTF mockups live under `tests/fixtures/dmtf-<mockup>/`, unmodified, with
|
|
the DMTF license and a `COMMANDS.txt` naming the source commit and request paths.
|
|
|
|
## License
|
|
|
|
Apache License 2.0, see [LICENSE](LICENSE).
|