# Role base draft: `ManagementControllerDriver`

Draft for napalm-device-types. Nothing here is decided; the decisions are tracked in the
netOrk options issue.

## Why a new role

The existing role bases (`SwitchDriver`, `FirewallDriver`, `AccessPointDriver`,
`HypervisorDriver`, `StorageDriver`, `OSDriver`, `PhoneDriver`, `MediaDriver`,
`ResidentialGatewayDriver`) each describe what a device *is*. A BMC is a separate computer
with its own network port, IP and MAC that manages *another* machine: it reads that
machine's sensors and switches its power, whatever OS the machine runs. None of the
existing contracts fits, and borrowing one (e.g. `OSDriver`) would make netOrk offer
package updates and service control for a BMC.

## Sketch

```python
class ManagementControllerDriver(DeviceTypeDriver):
    """Contract, not code."""
    ROLE: str = "management_controller"   # key exposed as device_class
    TYPE_LABEL: str = "Management Controller"
    USES_SSH: bool = False                # Redfish is HTTPS; IPMI is UDP

    if TYPE_CHECKING:
        # The managed machine
        def get_power_state(self) -> PowerStateDict: ...
        def set_power_state(self, action: PowerAction) -> None: ...   # On, GracefulShutdown,
                                                                      # ForceOff, GracefulRestart,
                                                                      # ForceRestart, PowerCycle
        def get_hardware_inventory(self) -> HardwareInventoryDict: ...  # CPUs, DIMMs, drives,
                                                                        # PSUs, NICs, serials
        def get_event_log(self, limit: int = 500) -> List[EventLogEntryDict]: ...  # SEL
        # The controller itself
        def get_firmware_inventory(self) -> List[FirmwareDict]: ...    # BMC, BIOS, others
        def get_management_protocols(self) -> ManagementProtocolsDict: ...  # IPMI, SSH,
                                                                            # HTTP(S), SNMP,
                                                                            # KVM, virtual media
```

Points to settle in napalm-device-types:

- **`reboot_host` means the BMC.** `HostRebootMixin` says a driver restarts its *own*
  host, never one it manages ("a hypervisor restarts the hypervisor, not a VM"). For a BMC
  that is `Manager.Reset`; the managed server goes through `set_power_state`. A driver for
  a BMC must not map `reboot_host` to the server.
- **Sensors.** NAPALM's `get_environment` already has fans, temperatures and power supplies.
  It also requires CPU and memory, which a BMC does not know for the host OS. Either return
  `get_environment` with those empty, or add a `get_sensors` that also carries voltages and
  power draw. Prefer reusing `get_environment` if the empty fields are acceptable.
- **Health metrics.** `HealthMetricsMixin` is SNMP/UCD-MIB. A BMC's health comes from Redfish,
  so this role does **not** mix it in. If netOrk needs `get_health_metrics` for BMCs, the
  driver implements it from Redfish, as `SwitchDriver` drivers do from their own sources.
- **`CommandChannelMixin`** comes with `DeviceTypeDriver` but stays unimplemented: no shell.
- **Write capability by `hasattr`.** `set_power_state` exists only on drivers that can do it,
  so the IPMI fallback (read-only) simply does not define it.
- **Models.** `PowerStateDict`, `HardwareInventoryDict`, `EventLogEntryDict`,
  `FirmwareDict`, `ManagementProtocolsDict` go into `models.py`.
- **Fingerprinting.** An unauthenticated `GET /redfish/v1/` returns the service root
  (`RedfishVersion`, `UUID`, `Vendor` on newer services) on every Redfish BMC. That is a
  vendor-neutral `PORT_SPECS`/`HTTP_FINGERPRINT` rule and can replace the hand-written
  `idrac`/`ilo` platform strings in netOrk's discovery.

## Relation to the managed server

A BMC is its own device in netOrk (own IP, own credentials, own firmware and CVEs), linked
to the host it manages. How to link them (matching the server's serial or system UUID from
`Systems/{id}` against the host's DMI data, or by hand) is a netOrk decision, not part of
this contract. The driver exposes the identifiers needed for matching:
`SerialNumber`, `UUID` and the host's MAC addresses from `Systems/{id}/EthernetInterfaces`.