bmc-health#

dpsctl verify bmc-health Usage Guide#

Run and inspect deep BMC pre-requisite health checks across a topology.

DPS 0.9 requires the topology to be active before you run dpsctl verify bmc-health start. Activate the intended topology through Managing Topologies, then confirm it appears in dpsctl topology list --active before starting the check.

Without an active topology, starting a check can return INVALID_OPERATION with no agent configuration available. For the complete operator procedure, refer to Run a BMC Health Check.

The bmc-health command also has the alias bmc:

dpsctl verify bmc start --topology my-topology

Overview#

dpsctl verify bmc-health probes the BMCs in a topology. Device plugins with deep BMC health support collect their supported firmware, power, EDPp, telemetry, and WPPS evidence. They also compare in-band and out-of-band power-limit values where supported. If the selected device plugin does not support the deep BMC health check, DPS checks only BMC reachability and firmware. The server screens available results against built-in latency and WPPS criteria and the default or requested EDPp floor.

For a quick surface-level reachability check, use dpsctl check connection instead.

The BMC health probe can take many minutes on large clusters, especially when deep telemetry and write-cycle checks are enabled. It is asynchronous:

  • start submits the check and returns a task_id.

  • status <task-id> shows live progress.

  • report <task-id> fetches the final cluster-level result.

Only one BMC health check may run at a time on the server. This gate is server-wide, not per topology or per node set. If a second start is attempted while another run is active, it is rejected. The public error does not expose the in-flight task_id. Reattach only when you retained the ID from the original start; otherwise, coordinate with the operator who started the task or wait for it to finish.

Usage#

dpsctl verify bmc-health start --topology <topology-name> [options]
dpsctl verify bmc-health status <task-id>
dpsctl verify bmc-health report <task-id> [options]

Start#

Submit a BMC health check and print the task handle.

dpsctl verify bmc-health start --topology <topology-name>

Flags#

Includes global dpsctl options.

   --topology value                 (required) topology name to probe
   --nodes value [ --nodes value ]  (optional) comma separated names of nodes to probe; defaults to all nodes in topology
   --samples-per-telemetry value    Number of telemetry reads per node (default: 0; 0 uses server default of 10; maximum: 2500)
   --telemetry-interval value       Sleep between consecutive telemetry reads on each node (default: 500ms; server-side cap: 60s)
   --write-resolution-timeout value Per-PATCH readback window for the write-cycle probe (default: 1s; server-side cap: 60s)
   --per-node-timeout value         Complete per-node task timeout (default: 0; 0 uses server default of 5m; allowed: 5m..48h)
   --concurrency value              Per-cluster fan-out concurrency (default: 0; 0 uses server default of 16; maximum: 1024)
   --skip-writes                    Skip power-limit write/read-back/restore and WPPS remediation (read-only mode)
   --force-writes                   Request power-limit write/read-back/restore and WPPS remediation from a supporting device plug-in
   --expected-edpp-pct value        Expected steady-state EDPp current value, in percent (default: 0; 0 uses server default of 100; allowed: 1..200)
   --wait                           Poll status until the task completes, then print the final report
   --poll-interval value            Status polling interval for --wait (default: 5s; ignored without --wait)
   --summary-only                   With --wait, strip per-node detail from the printed report and keep only Status, ClusterSummary, and Issues (ignored without --wait)
   --prs-bmc-latency-check          With --wait, run the BMC latency acceptance check for Power Reservation Steering (PRS) after BMC health
   --prs-metrics-url value          Optional PRS controller Prometheus metrics URL for the PRS latency check
   --prs-metrics-step value         PRS histogram operation step (default: cluster_apply)
   --actuation-p99-max value        Inclusive PRS p99 latency ceiling (default: 1s)
   --prs-latency-window value       PRS latency observation window (default: 5m)
   --prs-latency-min-samples value  Minimum PRS histogram sample count (default: 1200)
   --prs-interval-override value    Temporarily set and restore the PRS scheduler interval during the check
   --help, -h                       show help

Start Behavior#

Without --wait, start returns immediately with a task handle containing the task_id, task name, initial status, and start time.

With --wait, start blocks after submission. It polls status, writes one-line progress updates to stderr, and prints the final report to stdout when the task finishes. Progress updates use the format:

bmc-health <task-id>: <status> (<nodes-completed>/<nodes-total> nodes)

If the final report contains a failed status.ok, the command exits with status code 1.

On start, --poll-interval and --summary-only are only used by the --wait shortcut. Without --wait, they are silently ignored because the command returns only the task handle.

--skip-writes and --force-writes are mutually exclusive. If neither flag is provided, the request leaves write behavior unset and the current server default is read-only. If --skip-writes is provided, power-limit write cycles and WPPS remediation are disabled. If --force-writes is provided, a device plugin that supports write-enabled deep checks can run power-limit write/readback/restore cycles and can disable active WPPS profiles. The flag does not override a plugin’s safety policy.

--prs-bmc-latency-check requires --wait. The optional --prs-interval-override changes the PRS scheduler interval during the task and attempts to restore the original interval afterward. When the PRS latency check is enabled, the CLI prints the BMC report followed by the PRS artifact, and its final exit decision is based on the PRS artifact. Inspect the BMC report’s status.ok value separately.

Status#

Show live status and progress for a previously started check.

dpsctl verify bmc-health status <task-id>

Flags#

Includes global dpsctl options.

   --help, -h  show help

Status Output#

status prints the task ID, task name, task-manager status string, timestamps, diagnostic message, progress counters, completion flag, and terminal error message when present.

The status string can be Init, Started, Done, or Failed. The progress counters report how many nodes have completed out of the total in-scope nodes.

Server-side status snapshots are coalesced for about 500ms, so very fast polling does not provide fresher task state.

Report#

Fetch the final report for a BMC health check.

dpsctl verify bmc-health report <task-id>

Flags#

Includes global dpsctl options.

   --wait                 Block until the task finishes, then print the report
   --poll-interval value  Status polling interval for --wait (default: 5s; ignored without --wait)
   --summary-only         Strip per-node NodeReport detail server-side and return only Status, ClusterSummary, and Issues
   --help, -h             show help

Report Behavior#

Without --wait, report performs a single lookup. If the task is still running, it prints a structured response with done=false and no report payload. Run status and retry later, or use report --wait.

With --wait, report polls status until the task reaches a terminal state, then fetches and prints the final report. Progress updates are written to stderr so stdout remains clean for --output json or --output yaml.

When --summary-only is set, the server omits per-node NodeReport entries from the returned report and keeps only cluster-level Status, ClusterSummary, and Issues. The underlying task result is not modified; until the task expires, a later report call without --summary-only can still retrieve the full report.

If the report response contains an error_message, the CLI returns an error instead of printing an empty report.

If the final report contains a failed status.ok, the command exits with status code 1.

Polling and Re-Attach#

The default --poll-interval for --wait is 5s. Non-positive values fall back to 5s. Values below the client-side minimum of 1s are clamped to 1s and the CLI prints a stderr notice explaining the clamp.

Canceling a local --wait command, such as with Ctrl-C, stops only local polling. It does not cancel the server-side BMC health check. Re-attach with:

dpsctl verify bmc-health status <task-id>
dpsctl verify bmc-health report <task-id> --wait

Completed task state remains queryable for the server --zombie-lifetime window, which defaults to 10m. After that window expires, status and report can no longer re-attach to the completed task.

There is no dpsctl verify bmc-health cancel subcommand.

Examples#

Start a check and poll later#

$ dpsctl verify bmc-health start --topology rack-a
{
  "task_id": "task-abc123",
  "name": "bmc_health_check",
  "status": "Started",
  "started_at": "2026-05-21T14:30:00Z"
}

Check progress#

$ dpsctl verify bmc-health status task-abc123
{
  "task_id": "task-abc123",
  "name": "bmc_health_check",
  "status": "Started",
  "started_at": "2026-05-21T14:30:00Z",
  "progress": {
    "nodes_total": 128,
    "nodes_completed": 47
  },
  "done": false
}

Wait for a summary report#

dpsctl verify bmc-health report task-abc123 --wait --summary-only

Run a scoped, read-only check#

dpsctl verify bmc-health start --topology rack-a --nodes node001,node002 --skip-writes --wait

Run approved write-enabled checks with slower telemetry sampling#

dpsctl verify bmc-health start --topology rack-a --force-writes --telemetry-interval 2s --write-resolution-timeout 5s --wait