Markdown

Redfish (modern OOB API)¶

Scope: DMTF Redfish, the REST/JSON-over-HTTPS out-of-band management API exposed by a server's BMC. What the resource model is, how to drive power/thermal/firmware/eventing with curl, and why it supersedes IPMI for fleet automation. The transport runs on the same BMC and OOB network as everything else under Out-of-Band Management and BMC; this page is the API, not the controller or the wire.

What it is¶

Redfish is a DMTF standard (DSP0266) for an "interoperable, multivendor, remote, and out-of-band capable interface" to platform hardware.¹ It is a RESTful API: resources are JSON documents addressed by URI, manipulated with standard HTTP verbs (GET, POST, PATCH, DELETE), served over HTTPS by the BMC. The data model is OData-flavoured: every resource carries @odata.id (its own URI), @odata.type (its schema/version), and links to related resources, and it is backed by versioned, machine-readable schemas published by DMTF.¹³

The tree is self-describing and entered from one well-known point. A GET on /redfish returns only the protocol version:¹

{
    "v1": "/redfish/v1/"
}

GET /redfish/v1/ returns the ServiceRoot, the hypermedia entry point that links to every top-level collection (Systems, Chassis, Managers, SessionService, AccountService, UpdateService, EventService) and reports RedfishVersion.³ A client discovers the rest of the tree by following links from there, rather than hardcoding paths. The three collections that carry most operational weight:

/redfish/v1/Systems/<id> is ComputerSystem: host power state and the reset action.⁴
/redfish/v1/Chassis/<id> is Chassis: physical enclosure, thermal and power subsystems, sensors.⁶
/redfish/v1/Managers/<id> is Manager: the BMC itself (network config, the management controller).³

The latest published specification is DSP0266 v1.23.1 (2025-12-04); the normative text quoted here is v1.23.0 (2025-09-05).²¹ Schema versions cited below (ComputerSystem 1.26.0, Chassis 1.28.0, UpdateService 1.17.0, EventService 1.11.0) are from the DMTF Resource and Schema Guide and move independently of the protocol version.³

Why it's needed (and when)¶

Redfish exists to replace IPMI as the OOB management interface. The case is structural, not cosmetic:

Encrypted by mandate, not by bolt-on. The spec requires TLS: "Implementations shall support the Transport Layer Security (TLS) protocol v1.2 with RFC7525 recommendations or later," and explicitly deprecates the TLS v1.1 that earlier revisions allowed.¹ IPMI/RMCP+ ships its own session crypto with a long history of weaknesses (see IPMI); Redfish rides ordinary HTTPS that the rest of your tooling already speaks.
Schema'd and self-describing. Resources validate against published JSON schemas, so a client can discover capabilities and decode responses generically instead of parsing vendor-specific byte offsets out of ipmitool raw output.¹³
Automation-native. JSON over HTTP is directly consumable by Ansible, Python, Go, and curl. Power, firmware, telemetry, and eventing are uniform REST operations rather than a mix of ipmitool subcommands and OEM tools.

When to reach for it: any greenfield fleet, anything where you want config-as-code against the BMC, and anything needing firmware push or push-style telemetry. Modern server BMCs implement it: Dell iDRAC, HPE iLO, Lenovo XCC, Supermicro, and the OpenBMC stack all expose a Redfish service.¹⁰¹¹

When IPMI still matters: heterogeneous fleets with older nodes, a one-off chassis power from a shell, or PXE-era tooling not yet ported. Coverage and OEM extensions vary by vendor and firmware, so capabilities are discovered at runtime from the service, never assumed. In practice both interfaces are often enabled during a transition; the direction of travel is Redfish-first. See Out-of-Band Management and BMC for where the API sits relative to the controller and Provisioning Tooling for how provisioners consume it.

How it's set up & managed¶

There is nothing to install on the host; the Redfish service runs inside BMC firmware and is reached over the OOB network. Operational setup is: confirm the service answers, manage credentials/sessions, and decide auth mode.

Reference template, not hardware-tested. <bmc> is the BMC IP/hostname on the OOB network; <id> is the system or chassis identifier discovered from the relevant collection (commonly 1, System.Embedded.1, or self). -k/--insecure skips certificate validation and is shown only for first-contact against a factory self-signed certificate; install a trusted BMC certificate and drop -k for anything real.

Discover the service root and the System/Chassis IDs:

curl -sk https://<bmc>/redfish/v1/ | jq '.RedfishVersion, ."@odata.type"'
curl -sk -u <user>:<pass> https://<bmc>/redfish/v1/Systems | jq '.Members'
curl -sk -u <user>:<pass> https://<bmc>/redfish/v1/Chassis | jq '.Members'

Members is an array of {"@odata.id": "..."} links; the trailing path segment is the <id> used below.³

Authentication. The spec requires services to "support both HTTP Basic authentication and Redfish session login authentication," and a Basic-auth client "shall not" be forced to create a session.¹ Two modes:

Basic auth sends credentials on every request and is fine for a single ad-hoc call:¹⁰¹¹

curl -sk -u <user>:<pass> https://<bmc>/redfish/v1/Systems/<id> | jq .

Session login is preferred for scripted/repeated access. POST credentials to the Sessions collection; the spec states this "POST to create a session shall only be supported with HTTPS," and the response "shall include" an X-Auth-Token header plus a Location header naming the new session resource:¹¹¹

# Create a session; capture response headers.
curl -sk -D - -o /dev/null \
  -H "Content-Type: application/json" \
  -X POST https://<bmc>/redfish/v1/SessionService/Sessions \
  -d '{"UserName": "<user>", "Password": "<pass>"}'

Read X-Auth-Token and Location from the printed headers. Use the token on every subsequent request, then DELETE the Location URI to log out:¹⁰¹¹

TOKEN="<x-auth-token-value>"
SESSION="<location-uri>"   # e.g. /redfish/v1/SessionService/Sessions/<n>

curl -sk -H "X-Auth-Token: $TOKEN" https://<bmc>/redfish/v1/Systems/<id> | jq .
curl -sk -H "X-Auth-Token: $TOKEN" -X DELETE "https://<bmc>${SESSION}"

Power control. ComputerSystem exposes PowerState (read-only: On, Off, PoweringOn, PoweringOff, Paused) and the #ComputerSystem.Reset action.⁴⁵ The action's ResetType enumeration includes On, ForceOff, GracefulShutdown, GracefulRestart, ForceRestart, Nmi, ForceOn, PushPowerButton, and PowerCycle.⁵ Resolve the action target from the resource (Actions["#ComputerSystem.Reset"].target), conventionally /redfish/v1/Systems/<id>/Actions/ComputerSystem.Reset:¹⁰

# Graceful shutdown.
curl -sk -H "X-Auth-Token: $TOKEN" -H "Content-Type: application/json" \
  -X POST https://<bmc>/redfish/v1/Systems/<id>/Actions/ComputerSystem.Reset \
  -d '{"ResetType": "GracefulShutdown"}'

# Power on.
curl -sk -H "X-Auth-Token: $TOKEN" -H "Content-Type: application/json" \
  -X POST https://<bmc>/redfish/v1/Systems/<id>/Actions/ComputerSystem.Reset \
  -d '{"ResetType": "On"}'

Not every implementation supports every ResetType; read the resource's [email protected] (or the ActionInfo) before relying on a value.⁴

Thermal and power telemetry. Chassis links to a ThermalSubsystem and a PowerSubsystem (both added in schema v1.15.0), which replace the now-deprecated Thermal and Power resources; individual readings live in the Sensors collection.⁶ Because vendor firmware lags the schema, probe what the chassis actually links before fetching:

curl -sk -H "X-Auth-Token: $TOKEN" https://<bmc>/redfish/v1/Chassis/<id> \
  | jq '{ThermalSubsystem, PowerSubsystem, Sensors, Thermal, Power}'

# Newer model: enumerate sensors.
curl -sk -H "X-Auth-Token: $TOKEN" \
  https://<bmc>/redfish/v1/Chassis/<id>/Sensors | jq '.Members'

Firmware update. UpdateService (/redfish/v1/UpdateService) offers two paths.⁷ The #UpdateService.SimpleUpdate action pulls an image from a URI: ImageURI is required, with optional TransferProtocol, Targets, Username, and Password. The TransferProtocolType enumeration is HTTP, HTTPS, SCP, SFTP, TFTP, FTP, CIFS, NFS, OEM.⁷

curl -sk -H "X-Auth-Token: $TOKEN" -H "Content-Type: application/json" \
  -X POST https://<bmc>/redfish/v1/UpdateService/Actions/UpdateService.SimpleUpdate \
  -d '{"ImageURI": "https://repo.internal/fw/bmc-1.2.3.bin", "TransferProtocol": "HTTPS"}'

For a local file, push it to the MultipartHttpPushUri advertised by the service (the older single-part HttpPushUri was deprecated in schema v1.15.0).⁷ Updates run as background Task resources; poll the returned Location for completion. See Image and Config Management for firmware-image governance and GPU Firmware and GSP for the GPU-side firmware that Redfish does not touch.

Eventing (subscriptions). EventService (/redfish/v1/EventService) drives both push and streaming delivery.⁸ For push, POST an EventDestination to the Subscriptions collection (/redfish/v1/EventService/Subscriptions). On create, Destination and Protocol are required; Protocol is Redfish; filtering is by RegistryPrefixes and ResourceTypes (the older EventTypes array was deprecated in schema v1.5.0); Context is opaque client data echoed back in events.⁹

curl -sk -H "X-Auth-Token: $TOKEN" -H "Content-Type: application/json" \
  -X POST https://<bmc>/redfish/v1/EventService/Subscriptions \
  -d '{
        "Destination": "https://collector.internal/redfish-events",
        "Protocol": "Redfish",
        "Context": "rack-a7-node12",
        "RegistryPrefixes": ["Base"]
      }'

For streaming instead of push, open a GET to the URI in the service's ServerSentEventUri and read the text/event-stream.¹⁸ #EventService.SubmitTestEvent generates a synthetic event to validate the path end-to-end without waiting for real hardware to fault.⁸

Hold credentials in the secrets layer, not in scripts; treat the BMC as a privileged endpoint reachable only from the management plane (OOB Network Infrastructure).

Validated usage & tests¶

Reference template, not hardware-tested. Run against a real BMC on the OOB network. The descriptions below are the expected shape of healthy output; no values here were measured on hardware.

Service reachable and answering JSON. The cheapest liveness probe is the unauthenticated version document:

curl -sk -o /dev/null -w '%{http_code}\n' https://<bmc>/redfish

Expect 200 and, on a GET of the body, the {"v1": "/redfish/v1/"} object.¹ A connection refused or TLS handshake failure means the OOB path or the BMC, not Redfish, is the problem; cross to OOB / BMC Unreachable.

Auth works and is enforced. A request with no credentials to a protected resource should be rejected; the same request with valid credentials should return the resource:

curl -sk -o /dev/null -w 'no-auth: %{http_code}\n' https://<bmc>/redfish/v1/Systems/<id>
curl -sk -u <user>:<pass> -o /dev/null -w 'basic:   %{http_code}\n' \
  https://<bmc>/redfish/v1/Systems/<id>

Expect 401 (Unauthorized) for the first and 200 for the second. A protected resource returning 200 unauthenticated is a misconfiguration; protected resources should require auth.¹

Power state reads back correctly. Read PowerState before and after an action; the action returns 204 No Content (or 200) and the state transitions:

curl -sk -H "X-Auth-Token: $TOKEN" https://<bmc>/redfish/v1/Systems/<id> \
  | jq -r '.PowerState'

Expect one of the documented enum values (On, Off, PoweringOn, PoweringOff, Paused).⁵ After a GracefulShutdown the value should move toward Off; after On, toward On. A 400/405 on the action usually means the chosen ResetType is not in [email protected] for that platform; read the allowable set and retry.⁴

Eventing path proven without a real fault. Create a subscription, fire a test event, confirm the collector received it, then delete the subscription:

curl -sk -H "X-Auth-Token: $TOKEN" -H "Content-Type: application/json" \
  -X POST https://<bmc>/redfish/v1/EventService/Actions/EventService.SubmitTestEvent \
  -d '{"MessageId": "Base.1.0.TestMessage"}'

Expect the action accepted and the synthetic event to arrive at the subscribed Destination carrying your Context.⁸ MessageId must match a message in a registry the service supports; pull the service's registries if the exact ID is rejected. (Description of expected behaviour, not a captured payload.)

Failure modes¶

Brief; each links the matching runbook.

BMC/API unreachable. Connection refused, TLS failure, or timeout on /redfish. Almost always the OOB path, BMC health, or firewall, not the API. See OOB / BMC Unreachable and OOB Network Infrastructure.
401/403. Wrong credentials, expired/deleted X-Auth-Token, or insufficient account privilege. Re-create the session; verify the account role on the BMC. Auth requirements are normative in DSP0266 §13.3.¹
Stale TLS / weak ciphers. Old firmware negotiating TLS below the v1.2 floor or non-Recommended cipher suites fails modern clients and policy scanners. The fix is a BMC firmware/cert update, governed under Image and Config Management; the spec mandates TLS v1.2+.¹
Action rejected (400/405). A ResetType or other value not in that platform's allowable set, or an action attempted on a resource that does not expose it. Read @Redfish.AllowableValues/ActionInfo first; coverage is per-vendor.⁴
Schema/coverage drift across the fleet. Chassis exposing deprecated Thermal/Power on one model and ThermalSubsystem/Sensors on another, or OEM-only extensions. Probe links per node; do not assume a uniform tree. Firmware skew is tracked in Image Drift Across Fleet and Image and Config Management.
Firmware update stuck. SimpleUpdate/multipart push that never completes; inspect the Task resource at the returned Location for the message and percent-complete. See Image and Config Management.

References¶

DMTF Redfish Specification (DSP0266), v1.23.0 — protocol, ServiceRoot, /redfish version object, auth (§13.3), TLS (§13.1), SSE: https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.23.0.pdf
DMTF — All Published Versions of DSP0266 (v1.23.1 latest, 2025-12-04): https://www.dmtf.org/dsp/DSP0266
DMTF Redfish Resource and Schema Guide (DSP2046, 2025.3): https://redfish.dmtf.org/schemas/v1/DSP2046_2025.3.html
DMTF Redfish-Publications (read-only JSON schemas) — Resource, ComputerSystem, Chassis, UpdateService, EventService, EventDestination: https://github.com/DMTF/Redfish-Publications
OpenBMC Redfish cheatsheet (curl flows: ServiceRoot, session login, X-Auth-Token, Systems, ComputerSystem.Reset): https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md
HPE — Redfish authentication and sessions (session POST, X-Auth-Token, Location, Basic auth): https://servermanagementportal.ext.hpe.com/docs/concepts/redfishauthentication

DMTF Redfish Specification DSP0266 v1.23.0 — purpose statement; GET /redfish returns {"v1": "/redfish/v1/"}; §13.1.1 "Implementations shall support the Transport Layer Security (TLS) protocol v1.2 with RFC7525 recommendations or later" and TLS v1.1 deprecation; §13.3.1 "Shall support both HTTP Basic authentication and Redfish session login authentication" and Basic-auth clients "shall not" be required to create a session; §13.3.4.2 session-create POST to /redfish/v1/SessionService/Sessions is HTTPS-only and the response "shall include" the X-Auth-Token header; §12.5 SSE via ServerSentEventUri. https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.23.0.pdf ↩↩↩↩↩↩↩↩↩↩↩↩↩
DMTF — All Published Versions of DSP0266; v1.23.1 published 2025-12-04 (latest), v1.23.0 published 2025-09-05. https://www.dmtf.org/dsp/DSP0266 ↩
DMTF Redfish Resource and Schema Guide (DSP2046, 2025.3) — ServiceRoot navigation properties; OData @odata.id/@odata.type; collection Members arrays; schema versions ComputerSystem 1.26.0, Chassis 1.28.0, UpdateService 1.17.0, EventService 1.11.0. https://redfish.dmtf.org/schemas/v1/DSP2046_2025.3.html ↩↩↩↩↩↩
DMTF Redfish-Publications, ComputerSystem schema (v1.26.0) — PowerState property and #ComputerSystem.Reset action with ResetType parameter and [email protected]. https://github.com/DMTF/Redfish-Publications ↩↩↩↩↩
DMTF Redfish-Publications, Resource.json — PowerState enum (On, Off, PoweringOn, PoweringOff, Paused) and ResetType enum (On, ForceOff, GracefulShutdown, GracefulRestart, ForceRestart, Nmi, ForceOn, PushPowerButton, PowerCycle, and others). https://github.com/DMTF/Redfish-Publications ↩↩↩
DMTF Redfish-Publications, Chassis schema (v1.28.0) — ThermalSubsystem and PowerSubsystem links added v1.15.0 superseding the deprecated Thermal and Power links; Sensors collection; PowerState. https://github.com/DMTF/Redfish-Publications ↩↩
DMTF Redfish-Publications, UpdateService schema (v1.17.0) — #UpdateService.SimpleUpdate (required ImageURI; optional TransferProtocol, Targets, Username, Password); TransferProtocolType enum (HTTP, HTTPS, SCP, SFTP, TFTP, FTP, CIFS, NFS, OEM); MultipartHttpPushUri; HttpPushUri deprecated v1.15.0. https://github.com/DMTF/Redfish-Publications ↩↩↩
DMTF Redfish-Publications, EventService schema (v1.11.0) — Subscriptions collection (EventDestinationCollection), ServerSentEventUri, #EventService.SubmitTestEvent, DeliveryRetryAttempts/DeliveryRetryIntervalSeconds. https://github.com/DMTF/Redfish-Publications ↩↩↩↩
DMTF Redfish-Publications, EventDestination schema (v1.15.1) — create requires Destination and Protocol (Redfish); Context; SubscriptionType (RedfishEvent, SSE, ...); filtering by RegistryPrefixes/ResourceTypes; EventTypes deprecated v1.5.0. https://github.com/DMTF/Redfish-Publications ↩
OpenBMC Redfish cheatsheet — curl ServiceRoot GET /redfish/v1; session login POST to /redfish/v1/SessionService/Sessions capturing X-Auth-Token; authenticated requests via -H "X-Auth-Token: $token"; GET /redfish/v1/Systems; POST ComputerSystem.Reset with ResetType. https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md ↩↩↩↩
HPE — Redfish authentication and sessions — session POST returns HTTP 201 with X-Auth-Token and Location headers; token used on subsequent requests; DELETE on Location to log out; HTTP Basic authentication also supported. https://servermanagementportal.ext.hpe.com/docs/concepts/redfishauthentication ↩↩↩↩