Flows

The three end-to-end paths bty supports. Pick by what infrastructure you have:

  • Direct flash - one-off provisioning, no server, USB live stick.

  • Interactive PXE flash - server is up, operator picks an image from the TUI on first PXE contact (default for unknown MACs).

  • Server-driven PXE flash - fleet provisioning, machines reflash themselves on schedule / on demand / on failure.

Direct flash (CLI / TUI)

Used for ad-hoc provisioning of a single box, with no infrastructure on the network.

  1. Operator boots the target machine from the bty USB live image (built by bty-media).

  2. The live environment auto-logins as root on tty1. The operator runs bty-tui for an interactive flow, or invokes bty directly from the shell.

  3. Operator selects an image (sourced from the USB stick itself), a target disk (block device on the booted machine), and a provisioning mode.

  4. bty flash writes the image, applies the provisioning mode, and reports success.

  5. Operator removes the USB stick and reboots; the target boots into the freshly-flashed image.

The whole flow runs offline. No network, no server, no MAC registration.

Interactive PXE flash (boot_policy=tui)

The “bty-on-a-USB but over the network” path. Default behaviour for any MAC the server has never seen, so onboarding a new box needs zero per-MAC configuration.

  1. Operator stands up the bty server image (dd to disk, boot). Default credentials are bty / bty (web UI) and odus / odus (SSH); rotate with passwd and activate the dnsmasq proxy-DHCP block from the Settings page.

  2. A target machine PXE-boots on the same segment for the first time. bty-web auto-discovers the MAC, creates a Machine record with boot_policy=tui, and serves the iPXE-tui template (ipxe_tui.j2).

  3. The target chains into the bty live env with bty.mode=interactive bty.server=URL bty.mac=MAC on the kernel cmdline. bty-flash-on-boot.service sees the interactive flag and short-circuits; bty-tui-on-tty1.service takes over tty1 in place of the agetty and launches bty-tui --server URL --mac MAC.

  4. The TUI fetches the catalog from GET /images, the operator picks an image and a target disk, and confirms the flash. Image bytes stream from GET /images/{name} straight through zstd -d | dd to the target disk - no temp file, no intermediate download.

  5. On success the TUI POSTs /pxe/{mac}/done so last_flashed_at updates server-side. The next reboot chains the TUI again unless the operator flips boot_policy (typically to local once the target is happy with what it’s running).

This flow is also useful for the operator who just wants a one-off remote flash without standing up a USB stick: any unknown MAC on the segment becomes a TUI session reachable via IPMI / serial console.

Server-driven PXE flash (boot_policy=flash)

Used for fleet-managed provisioning, where targets are reflashed on schedule, on demand, or on failure.

  1. Server appliance is already up (same setup as the interactive flow above).

  2. Operator assigns MAC -> image + provisioning mode + boot policy in the web UI. boot_policy=flash arms the auto-flash; boot_policy=local lets the target PXE-boot through to its own disk untouched.

  3. Target machine PXE-boots; iPXE chains into the bty live environment served over HTTP by bty-web.

  4. The live env’s bty-flash-on-boot.service fetches the assigned image from GET /images/{name}, runs bty flash, applies the provisioning mode, and POSTs /pxe/{mac}/done to update last_flashed_at. Then it reboots automatically.

  5. The next reboot still chains the live env unless the operator flips the machine to boot_policy=local. Per-job CI cadences that want every boot to reflash leave the policy on flash.

  6. If the assigned provisioning mode is cijoe-online, bty-web triggers the CIJOE workflow against the booted target and records the post-workflow state as the machine’s known-good baseline.

Both BIOS and UEFI clients are supported via iPXE.