BMC Virtual Media

Serve a disk image to a BMC’s virtual media, so the host sees a read-only USB disk. The runner itself is the server; no browser is involved. Where PiKVM emulates a USB drive from an external device, bmc-virtualmedia uses the virtual media that the BMC serves itself.

On OpenBMC, bmcweb offers virtual media in proxy mode as a websocket at /vm/0/0, which is what the web UI uses. When a client opens it, the BMC attaches the disk and exposes it to the host as a USB mass storage device (“Virtual Media Device”). The step serves the image over that websocket with the NBD protocol.

Attribute	Type	Required	Default	Description
`cmd`	`const`	Yes	`bmc-virtualmedia`	Command Name
`name`	`string`	Yes		Name to uniquely identify the teststep. This name will show up in reports, logs and the WebUI
`options`	`OptionsObject`	No		Additional command options
`parameters`	`BMCVirtualMediaOptions`	Yes		Options passed into the `bmc-virtualmedia` cmd

The step uses no transport: the runner itself opens the connection.

BMC Virtual Media Quick start

Boot the host from an image the job provides: attach the image, boot the host from USB with other steps, then detach and check how much the host read.

- cmd: bmc-virtualmedia
  name: Serve the boot image
  parameters:
    mode: attach
    host: "[[attributes.BMC]]"
    auth: { user: root, password: "[[attributes.BMCPassword]]" }
    insecure: true              # BMCs serve self-signed certificates
    image: "[[storage.BootImage]]/boot.img"

# ... set a one-time boot from USB and power on the host (redfish),
#     wait for the kernel on the serial console (ipmi sol) ...

- cmd: bmc-virtualmedia
  name: Stop serving the boot image
  parameters:
    mode: detach
    host: "[[attributes.BMC]]"
    expect:
      read: { ge: 100MiB }      # the host loaded the kernel and initrd

BMC Virtual Media Options

Attribute	Type	Required	Default	Description
`mode`	`string`	Yes		`attach`, `detach` or `run`. See BMC Virtual Media Modes.
`host`	`string`	Yes		BMC host name or address, or an `https://` URL.
`port`	`integer` or `string`	No	`443`	bmcweb’s HTTPS port, when `host` does not carry it. A string such as `"[[attributes.WebPort]]"` works too.
`auth`	`{user, password}`	No		A BMC account, sent as HTTP Basic with the websocket upgrade.
`insecure`	`boolean`	No	`false`	Accept a self-signed certificate.
`path`	`string`	No	`/vm/0/0`	The websocket path.
`image`	`string`	Yes, for `attach` and `run`		The disk image: a file on the runner, such as `"[[input.Image]]"` or a storage path.
`size`	`integer` or `string`	No	the image size	`attach` and `run`: serve a disk of this size; past the image every byte reads as zero, such as `3584MiB`. Lets a test send only the start of a large image, such as its partition table and boot partition.
`duration`	`string`	Yes, for `run`		How long `run` serves the image, such as `2m`.
`expect`	`{read}`	No		`detach` and `run`: a check on the bytes the BMC read: `{ ge: 100MiB }`, `{ le: 1GiB }` or `{ range: 100MiB..2GiB }`.

Sizes take the units B, KiB, MiB, GiB, TiB, KB, MB, GB and TB. The password is masked in the log. Without an options timeout, the step timeout is 2 minutes, plus duration for run. With an options timeout, it must be longer than the duration of a run, or FirmwareCI refuses the test before the job starts.

BMC Virtual Media Modes

Mode	What it does
`attach`	Starts serving and returns when the BMC reads the disk. The session lasts until a `detach` step, or until the job ends.
`detach`	Stops the session that `attach` started for the same `host`, `port` and `path`, reports what it served and checks `expect`.
`run`	`attach`, serve for `duration`, then `detach`, in one step. For checks that need no other step while the disk is attached.

The log shows what the BMC read:

image /tmp/boot.img: 135 MiB, served as a 3.5 GiB disk (zeros past the image), read-only
attempt 1: the BMC reads the disk
attached at wss://bmc/vm/0/0
...
served for 4m12s: 612 reads, 150.2 MiB, largest read 256 KiB, 0 writes refused

  ✓ read ge 100 MiB  got 150.2 MiB

PASS  1 check: 1 passed

The reads include the few the BMC kernel makes when the disk appears, when it reads the partition table.

BMC Virtual Media Behavior

Read-only. The step refuses writes and counts them; OpenBMC also marks the USB disk read-only. An operating system that mounts its root file system read-write cannot run from it.
Retries. After a session ends, the BMC needs about ten seconds to remove the USB disk. An attach in that time, and now and then one without a reason, ends right after the start, or the BMC does not read the disk within 15 seconds. attach then tries again, up to four times with waits of 3, 6 and 12 seconds, and logs each attempt.
A session that ends early fails the detach, for example when the BMC rebooted while the host used the disk.
One session per endpoint. A second attach to the same host, port and path fails until a detach.
Speed. About 7 to 8 MiB/s on an AST2600 BMC: a kernel and initrd of about 150 MB load in about 20 seconds.