# Redfish

> Reference for the Redfish driver: HTTPS connection to a BMC, resource-path plus JSON-pointer addressing, reads, PATCH writes and types.

The Redfish driver reads and writes **DMTF Redfish** management services: the REST
API exposed by server BMCs (baseboard management controllers), chassis and other
datacenter hardware for out-of-band management. This is an ordinary client-mode
driver (**Ganter Lab connects to the equipment**), and the transport is always
**HTTPS**: hardened BMCs expose nothing else, and the driver never downgrades to
plain HTTP on its own.

Typical points read this way: power state, secure-boot state, chassis and manager
health, firmware version, temperatures and fan readings from the thermal resources.

## Connection fields {#connection-fields}

| Field | What it is | Format | Default |
|---|---|---|---|
| Host | The Redfish service's host name or IP address. | Host name or IP | empty |
| Port | The port the service answers on. Management controllers commonly answer on 443, and a service published elsewhere says so here. An empty box shows 443 in grey and the service is reached on it, which is also how a device saved with 0 reads. | 1 to 65535 | 443 |
| Username | The BMC account used for **HTTP Basic** authentication. Empty leaves the requests anonymous, which a protected service will answer with an authorization error. | Free text | empty |
| Password | The password paired with the username. Protected at rest per Windows user, so the configuration database never holds the clear value; a password entered under another Windows account shows as unreadable and must be re-entered. | Free text | empty |

On connect the driver verifies the service by reading the service root
(`/redfish/v1/`). The BMC's TLS certificate is accepted when Windows trusts it, or when
you approved that very certificate under [Equipment access](#equipment-access) on this
driver's page: the self-signed certificate a BMC ships with needs nothing installed in
Windows. A connection that fails says why on the Events page and in the day's log file,
with the underlying error behind it, so a refused password and a certificate waiting
for approval are told apart.

The poll interval is configurable: the device default (1000 ms) applies to every
tag that does not state its own.

## Tag addressing {#tag-addressing}

A Redfish tag is addressed by a **resource path** plus an optional **JSON
pointer** into the document that resource returns:

| Field | What it does | Values | Default |
|---|---|---|---|
| Resource path | The service-root-relative path of the Redfish resource to GET, e.g. `redfish/v1/Chassis/1/Thermal`. | Free text (required) | empty |
| JSON pointer (blank = whole document) | An RFC 6901 pointer selecting one field of the returned JSON, e.g. `/Temperatures/0/ReadingCelsius`. Array elements are addressed by index; `~1` escapes a `/` inside a field name and `~0` a `~`. A missing leading `/` is added for you. Blank returns the whole document as text. | JSON pointer or blank | blank |

Examples of the assembled address (shown read-only as the wire source preview):

- `redfish/v1/Systems/1#/PowerState`: the system's power state as a string.
- `redfish/v1/Chassis/1/Thermal#/Temperatures/0/ReadingCelsius`: the first
  thermal sensor, as a number.
- `redfish/v1/Systems/1/SecureBoot#/SecureBootEnable`: secure boot, as a boolean.

On a read the driver GETs the resource, parses the JSON, follows the pointer and
converts the result to the tag's declared data type. A pointer that names nothing
in the document, and a field the document carries as JSON `null`, both read as no
value: the tag goes to bad quality and its read-failure policy decides what is
presented, rather than the word `null` arriving as a good reading. A response that
is not JSON is parsed directly as the declared type. A status the service returns
outside the success range is the service refusing the read: the tag goes to bad
quality the same way, and its reason names the status and a short piece of the error
document the service sent with it (`HTTP 404 Not Found: …`). Every other read without a value
says why as well: a tag with no resource path, a pointer that names nothing in the document
and a field held as `null` (each naming the resource and the pointer), and an answer that
does not read as the declared type. A service that does not answer at all is the device's
connection failing: the device reports it and reconnects, and its tags point to it. The tag's red line says such a status in the station's language, with what it means for 401, 403 and 404, and the device's red line says why its connection fails at every attempt, a port that refuses or a status such as 401; the Events page keeps the service's own words.

## Writes {#writes}

Tags with a writable access mode PATCH the addressed field: the driver builds the
smallest JSON document covering only the pointer's path (for
`/Parent/Child`, the body `{"Parent":{"Child":<value>}}`) and sends it to the
resource. Two constraints follow from that:

- A write **requires a JSON pointer**. A whole-document tag (blank pointer) cannot
  be written: the tag panel refuses the combination while you are editing, saying
  the field is missing, and an attempt that reaches the service anyway fails with
  the reason in the journal.
- The BMC decides what is writable; a PATCH the service rejects is refused with the status and a short piece of the error document the service sent with it (`HTTP 400 Bad Request: …`), so whoever wrote the value reads why.

As everywhere else, the value you type in the tag's write box is the engineering
value, and the tag's conversion stages are reversed before the raw value goes on
the wire, as described on the [Connector](connector) page.

## Supported data types {#supported-data-types}

Boolean, Int32, Int64, Float, Double and String. Pick the type matching the JSON
field: booleans for flags such as `SecureBootEnable`, numbers for readings, strings
for states such as `PowerState` or `Health`.

## Commands {#commands}

A Redfish service publishes an action per thing it can be asked to do, each at its own
path under the resource it acts on. The station does not guess those, because only the
hardware's own documentation says which exist: you declare them on the device, in the
**Commands** card of its page. Each command carries a name, the action path
(`redfish/v1/Systems/1/Actions/ComputerSystem.Reset`), and optionally the name of the one
value it takes (`ResetType`); the row's Run verb sends it, and what the service answered
is reported back. A command also becomes a method on the device in this station's own OPC
UA address space, so anything that can call a method can issue it.

The value travels as the request body. A value that is already JSON is sent as written;
anything else is sent as `{"<the name you declared>": "<the value>"}`, which is the shape
Redfish's own reset action expects.

An action the service refuses is answered with the status and a short piece of the error
document the service sent with it (`HTTP 400 Bad Request: …`), in the same words as a
refused write, and nothing else on the device is disturbed by it.

## Discovery {#discovery}

The **Discover** button reads one service: put its address in the driver page's Scan scope
card (`https://bmc-host`, or the address the vendor documents) and the scan walks that
service's first system, manager and chassis, offering the device with those points ready to
add. The scan reads the service over HTTPS and without credentials, because it runs before
the device that would hold them exists, so a service that authenticates every request
answers nothing and is added by hand instead. Redfish's own SSDP discovery needs UDP
multicast, which the in-process driver does not do, so nothing is found by broadcasting: the
scan reads the address you give it.

A Redfish device you already have finds its points from its own page: **Discover tags**, on
the head of its Tags card, walks the same resources signed in with the device's username and
password, so a service that authenticates every request answers too, and offers only the
points the device has no tag for yet (see [Discovering a device's tags](connector-discovery#discovering-a-devices-tags)).

## Equipment access {#equipment-access}

A BMC usually answers with a certificate of its own, self-signed or issued by its maker,
that no root installed in Windows vouches for. That root does not need to be installed on
this computer. The first connection is refused, the device reads **Waiting for certificate
approval** in the tree and on its page, whose **Review certificate** button opens this card
on the certificate, and the certificate waits under **Equipment access** at the end of the
Redfish driver's page, the same card the OPC UA driver's page carries, until you decide:

| Group | What it lists | What you can do |
|---|---|---|
| Waiting for approval | Each refused certificate, under the name it claims: its SHA-256 fingerprint, the address it was met at, when it last tried and how many times, and its details (subject, issuer, domain names, validity dates). The one a device's Review certificate opened is marked Selected for review. | **Approve** accepts the certificate from the device's next connection attempt. **Block** keeps refusing it without listing it here again. **Discard all pending certificates** empties the list without approving or blocking anything. |
| Approved equipment | The certificates you approved or imported, with who decided and when, and the address each was last met at. | **Withdraw approval** closes the device's connection and returns its certificate to the list. **Import certificate** approves a public certificate file you already have (.der, .cer, .crt or .pem) before the first connection. |
| Blocked equipment | The certificates you blocked. A blocked certificate is refused even if Windows trusts it. | **Unblock** returns the certificate to the list, without approving it. |

Check the fingerprint with whoever manages the server before you approve it. An approval
accepts that certificate and no other, and only within its validity dates; it stands in
for the root Windows lacks and for the name the certificate carries, so a BMC dialed by its
IP address connects although its certificate names the BMC, and nothing else about the
certificate is relaxed. When the BMC answers an address whose certificate you approved with
another one (a renewed certificate, a replaced controller), reading stops, the new one waits
here, and the station raises "Certificate changed: `<name>`" with a **Review** button. A
certificate Windows already trusts is accepted as before and never appears here; nothing is
approved automatically.

The driver's own failure says the reason instead of a nameless TLS error: "This equipment's
certificate (the first 16 characters of the fingerprint) is waiting for your approval under
Equipment access on the Redfish driver's page. Reading starts once you approve it." A
blocked one reads "…is blocked at this station. Review it under Equipment access on the
Redfish driver's page." A certificate outside its validity dates, revoked or with a broken
signature is refused with that reason and is never listed, since no approval makes it sound.
A scan of the BMC, from the Scan scope card or from **Discover tags** on the device's page,
meets the same decisions: an unknown certificate ends the scan with that sentence and waits
here.

The decisions are kept in the station's data folder, under `ua\pki\redfish`, and survive a
restart. Only a role that may configure the Connector is drawn the verbs, and they act only
in the station's own window: a browser on another device reads the card without changing it,
and no agent tool approves a certificate (`connector_browse` reports the waiting device with
`awaitingCertificate`). The list holds up to 100 certificates waiting for approval; once it
is full, a new one is still refused but not listed, and the card says so.