Hardware Control

Control and manage hardware devices including DUTs, PiKVM interfaces, and QEMU virtual machines.

DUTCTL

Run DUTCTL for the DUT. This command can power-cycle and flash the DUT as well as read the serial of the DUT.

DUTCTL Options

DUTCTL Expect Options

DUTCTL Example

- cmd: dutctl
  name: Shutdown the DUT.
  parameters:
    host: "[[attributes.Flasher]]"
    command: power
    args: ["off"]

- cmd: dutctl
  name: Flash the provided binary.
  parameters:
    host: "[[attributes.Flasher]]"
    command: flash
    args: [write, "[[input.Binary]]"]

- cmd: dutctl
  name: Turn the DUT on
  parameters:
    host: "[[attributes.Flasher]]"
    command: power
    args: ["hardreset"]
  options:
    timeout: 2m

PiKVM

Manage PiKVM operations.

PiKVM Options

PiKVM Examples

Image mounting:

cmd: pikvm
name: Mount OS Image via PiKVM
parameters:
  command: image
  host: "[[attributes.PiKVMHost]]"
  auth:
    username: root
    password: root
  image:
    path: "[[storage.Image]]/nixos.img"

Screenshot:

cmd: pikvm
name: Capture PiKVM Screenshot
parameters:
  command: screenshot
  host: "[[attributes.PiKVMHost]]"
  auth:
    username: root
    password: root

Keyboard input:

cmd: pikvm
name: Send Keyboard Input via PiKVM
parameters:
  command: keyboard
  host: "[[attributes.PiKVMHost]]"
  auth:
    username: root
    password: root
  keyboard:
    text: "INPUTTEXT"

or

cmd: pikvm
name: Send Keyboard Input via PiKVM
parameters:
  command: keyboard
  host: "[[attributes.PiKVMHost]]"
  auth:
    username: root
    password: root
  keyboard:
    keys: ["CTRL + C", "I", "N", "P", "U", "T", "ENTER"]

Qemu

Manage QEMU virtual machines.

Qemu Options

Behavior and semantics

• The run mode can be used to attach to an already running QEMU instance. In this case, variable must be set to the PID of the QEMU process.
• If variable is not set, the run mode will behave like the start mode, launching a new QEMU instance.
• The stop mode will send a termination signal to the QEMU process identified by variable.

Conditional rules:

• start: requires executable, firmware, and variable. The step launches QEMU and stores its PID in variable. If QEMU prints a PTY path it is stored in <variable>_pty.
• run: if variable is provided the step attaches to the recorded PID/PTY and runs serial steps; if variable is empty, run requires both executable and firmware and will launch QEMU and run serial steps.
• stop: requires variable and must not include executable, args, firmware or serial.

Qemu Serial Options

Qemu Expect Options

BMCTest

Run BMC (Baseboard Management Controller) compliance and functionality tests using the bmc-test-go tool. This command executes automated tests to verify BMC behavior including IPMI, Redfish, and other BMC interfaces.

BMCTest Options

BMCTest Command Details

• single: Run a specific test by name (requires test_name)
• suite: Run a test suite (requires suite_name)
• all: Run all available tests
• run-from-cfg: Run tests defined in the configuration file

BMCTest Examples

Run a complete test suite:

- cmd: bmctest
  name: Run IPMI Test Suite
  parameters:
    command: suite
    config_path: /tmp/storage/bmc_config/device.yaml
    suite_name: ipmi
  options:
    timeout: 30m

Run a single test:

- cmd: bmctest
  name: Test IPMI Power Status
  parameters:
    command: single
    config_path: /tmp/storage/bmc_config/device.yaml
    test_name: testIPMIPowerStatus
  options:
    timeout: 5m

Run all tests with custom log location:

- cmd: bmctest
  name: Run All BMC Tests
  parameters:
    command: all
    config_path: "[[storage.BMCConfig]]/bmc.yaml"
    log_mode: structured
    log_file: /tmp/bmc-results.json
  options:
    timeout: 1h

Run a suite with environment variables (e.g. for configs that reference $IMAGE or $GOLDEN_IMAGE):

- cmd: bmctest
  name: Run Redfish Test Suite
  options:
    timeout: 30m
    env:
      IMAGE: "[[input.Binary]]"
      GOLDEN_IMAGE: "[[storage.BoardImage]]"
      HOST_SSH_KEY: "[[storage.BMCConfig]]/ssh_key"
  parameters:
    command: suite
    config_path: "[[storage.BMCConfig]]/board.yaml"
    suite_name: redfish

Redfish

Run DMTF Redfish conformance testing against a BMC. Wraps the DMTF reference validators — Redfish-Service-Validator (schema, DSP8010), Redfish-Interop-Validator (profiles), and Redfish-Protocol-Validator (protocol behavior, DSP0266) — and adds a native inventory engine for board-specific value checks the validators do not perform. The validators run on the contest runner and connect to the BMC over HTTPS; their full reports (HTML/XLSX/TSV) are attached as downloadable artifacts while a per-check summary is folded into the step log.

Quick start

Run the schema validator against a BMC:

- cmd: redfish
  name: Redfish schema conformance
  parameters:
    host: "[[attributes.BMC]]"
    auth: { user: root, password: "[[attributes.BMCPassword]]" }
    validate: service
  transport: { proto: local }
  options: { timeout: 20m }

Check a few board values with the native inventory engine. Most rules are four fields — a target, a property, a comparison, a value:

- cmd: redfish
  name: Board sanity
  parameters:
    host: "[[attributes.BMC]]"
    auth: { user: root, password: "[[attributes.BMCPassword]]" }
    validate: inventory
    inventory:
      rules:
        - { path: /redfish/v1, prop: RedfishVersion, op: exists }
        - { path: /redfish/v1/Systems/system, prop: PowerState, op: eq, value: "On" }
        - { path: /redfish/v1/Managers/bmc, prop: Status/Health, op: eq, value: OK }
  transport: { proto: local }

That covers most needs. The full inventory rule reference adds counts, ranges, per-component checks (forEach), multi-hop navigation (via), and composition (all/any) — reach for them only when a simple rule can’t express what you want.

Run the interop validator against a profile carried inline (no profile file needs to be staged on the runner):

- cmd: redfish
  name: Redfish interop profile
  parameters:
    host: "[[attributes.BMC]]"
    auth: { user: root, password: "[[attributes.BMCPassword]]" }
    validate: interop
    interop:
      profileDoc:
        SchemaDefinition: RedfishInteroperabilityProfile.v1_0_0
        ProfileName: BaselineManageability
        ProfileVersion: "1.0.0"
        Protocol: { MinVersion: "1.6.0" }
        Resources:
          ComputerSystem:
            PropertyRequirements:
              PowerState: { ReadRequirement: Mandatory }
              BiosVersion: { ReadRequirement: Mandatory }
  transport: { proto: local }

Alternatively set interop.profile to the path of a profile JSON already on the runner.

Redfish Options

Select one engine per step (with options.on-error: continue) to get an independent pass/fail per engine instead of one merged verdict.

Security

• TLS verification is off by default (insecure: true) because lab BMCs ship self-signed certificates. Set insecure: false for any non-lab/production target. Note the wrapped service/interop validators always connect leniently regardless, so rely on the native inventory and protocol engines when strict TLS matters.
• The BMC password is passed to the DMTF validators as a command-line argument, so it is briefly visible in the runner host’s process list (ps, /proc/<pid>/cmdline) while a validator runs. It is redacted from the step log. This is acceptable for lab BMCs with shared credentials; do not use credentials you would not want visible to anything with process-list access on the runner.

Transport

transport is optional and defaults to local — the validators run on the contest runner (where the DMTF tools are installed) and reach the BMC over HTTPS. Omit it for almost every deployment.

Use transport: { proto: ssh, options: { ... } } to run the validator processes on a remote SSH host instead. The cases where you need it:

• The BMC is reachable only from a jump host / bastion, not from the contest runner — a segmented or air-gapped management network. Run the validators on a host that can actually reach the BMC.
• The DMTF validators live on a different machine (an on-prem appliance or pre-provisioned host with BMC access) rather than in the runner image.

For ssh the target must have the DMTF validators on PATH (rf_service_validator, rf_interop_validator, rf_protocol_validator), and the runner needs SSH access to it (set under transport.options).

Caveat: only the service, interop, and protocol engines run over the transport. The native inventory engine is an HTTPS client that always runs on the runner, so ssh does not change where its requests originate — if the BMC is unreachable from the runner, keep inventory off ssh-only targets.

Redfish Auth Options

Redfish Engine Options

The service, interop, and protocol sub-blocks tune the wrapped DMTF validators. All accept extraArgs, an array of raw passthrough flags to the underlying tool.

Redfish Inventory Options

The native engine fetches resources directly and checks board-specific values. Rules come from inline rules and/or an expected file.

Inventory Rule

Each rule names a target (where to look), a value source (what to read), and a comparison (op + value).

Comparison ops:

Numeric ops parse both sides as numbers; a non-numeric operand fails the rule with a clear message rather than crashing.

Member Filter

A forEach inclusion predicate. Only members for which it holds are checked; the rest are skipped. The canonical use is ignoring empty slots, e.g. {prop: Status/State, op: ne, value: Absent}.

Multi-hop navigation and composition

via follows a chain of single-resource links from the base before the check, so a nested target works in one rule while keeping a dynamic chassis id — e.g. chassis: "*" with via: [Power] then forEach: PowerSupplies walks chassis → Power → PowerSupplies.

all / any replace a single prop/op/value with condition groups, evaluated against the target (or against each member under forEach). With both set, the rule passes iff every all condition passes and at least one any condition passes.

Note: The inventory rule grammar is complete and frozen — the fields above cover the intended use cases. Genuinely new needs are better met by a scripted check than by growing this mini-language further.

Redfish Examples

Schema conformance (full tree crawl):

- cmd: redfish
  name: Redfish schema conformance
  parameters:
    host: "[[attributes.BMC]]"
    auth:
      user: root
      password: "[[attributes.BMCPassword]]"
    validate: service
  transport:
    proto: local
  options:
    timeout: 20m

Inventory with fleet-aware checks — counts, per-member (forEach / where / range), multi-hop (via), and composition (all / any):

- cmd: redfish
  name: Redfish inventory
  parameters:
    host: "[[attributes.BMC]]"
    auth:
      user: root
      password: "[[attributes.BMCPassword]]"
    validate: inventory
    inventory:
      rules:
        # ServiceRoot advertises a version; the BMC reports health.
        - path: /redfish/v1
          prop: RedfishVersion
          op: exists
        - path: /redfish/v1/Managers/bmc
          prop: Status/Health
          op: eq
          value: OK
        # At least one DIMM is populated (exact counts vary per SKU).
        - path: /redfish/v1/Systems/system
          collection: Memory
          op: ge
          value: "1"
        # Every populated DIMM has a sane capacity; empty slots are skipped.
        - path: /redfish/v1/Systems/system
          forEach: Memory
          where:
            prop: Status/State
            op: ne
            value: Absent
          prop: CapacityMiB
          op: ge
          value: "1024"
        # Every CPU reports a plausible core count.
        - path: /redfish/v1/Systems/system
          forEach: Processors
          prop: TotalCores
          op: range
          value: "1..256"
        # Multi-hop: chassis -> Power -> every PSU healthy (one rule, dynamic id).
        - chassis: "*"
          via: [Power]
          forEach: PowerSupplies
          prop: Status/Health
          op: eq
          value: OK
        # Composition: System is On AND healthy; accept either BIOS property.
        - path: /redfish/v1/Systems/system
          all:
            - { prop: PowerState, op: eq, value: "On" }
            - { prop: Status/Health, op: eq, value: OK }
        - path: /redfish/v1/Systems/system
          any:
            - { prop: BiosVersion, op: exists }
            - { prop: BiosRevision, op: exists }
  transport:
    proto: local
  options:
    timeout: 5m