Wheelhouse

Getting onto it#

Three ways in: type the answers, put them on a stick, or bring them from the firewall you are replacing.

The installer#

Boot the image and the first video console runs a dialog walk-through: the disk, a host name, the time zone, the WAN and LAN interfaces (each skippable), a DHCP server, NAT, and the two passwords — the web interface account and the console account. Each password is typed twice and the installer says so when the entries differ.

Then it shows you the set commands your answers produce, before anything is written. Only after you confirm does it commit them to the live configuration, drive VyOS' own install image to write the disk, and reboot.

Two details that came from making mistakes on real hardware:

  • The installer knows what it has already cost you. Its failure screens distinguish nothing has been written, the live configuration was committed, and the target disk has been repartitioned and is no longer what it was. A failure that cannot say which of those happened is worse than the failure.
  • A serial console keeps its login prompt. The installer takes the first video console only, and the banner on the serial console tells you how to start it there. When console=ttyS is on the kernel command line, the installed system gets the serial console as its default, so a headless box stays reachable the way you installed it.

Every boot afterwards prints a banner above the login with the web interface URL on every addressed interface, how to sign in, and — until it is changed — the generated first-boot administrator password. It is redrawn every 20 seconds as addresses change.

You can print the commands for a set of answers without touching anything, which is how you check a seed before booting a machine with it:

bash
wheelhouse-install --answers answers.conf --commands

Installing with nobody at the keyboard#

Give the machine a seed — a cloud-config on a labelled filesystem, a URL on the kernel command line, or cloud-init's own NoCloud seed — and it installs itself.

A seed, in outline
#cloud-config
wheelhouse:
  disk: auto
  hostname: edge
  timezone: America/Los_Angeles
  wan:
    interface: eth1
    addressing: dhcp
  lan:
    interface: eth0
    address: 10.0.0.1/16
    dhcp_server: true
    firewall: true
    nat: true
  passwords:
    admin: "the web UI password"
    console: "the vyos password"
  config:
    commands: config.commands
  reboot: true

The seed can carry a whole configuration, so a replacement box comes up with the addresses, forwards, reservations and firewall of the one it replaces.

Two safety properties are worth naming. An unattended install runs at most once per boot, so a failure cannot loop and erase the disk repeatedly. And a seed will not reinstall a machine that is already installed unless it explicitly says overwrite: true — which is what stops the stick you left plugged in from wiping the router next Tuesday.

tools/wheelhouse-seed.py builds the medium.

Coming from OPNsense#

tools/opnsense-import.py reads an OPNsense config.xml and writes two things: VyOS commands, and a report of what came across, what came across differently, and what could not come at all.

What it handles: the host name and resolvers, interface addresses, static routes through named gateways, outbound NAT and every port forward with host and port aliases resolved, a default-drop firewall admitting exactly those forwards, the DHCP server with its pool and PXE handoff and reservations, DNS forwarding with its static hosts, and the WAN shaper.

The report is the point. A migration tool that silently drops what it did not understand is how you find out three weeks later that a rule is missing.

bash
tools/opnsense-import.py config.xml --map lan=eth0,wan=eth1 --out ./migration/

And the check that makes a migration verifiable rather than hopeful:

bash
tools/opnsense-import.py config.xml --check-against https://<router>:8443

That compares a running router with the configuration it should have.

The seed builder goes from an OPNsense configuration to a bootable stick in one command, so the whole path is: read the old box, build the medium, plug it in, walk away.

What has actually been done#

Installing to a disk in a VM and rebooting into the installed system: yes, twice — keyboard-driven for 0.4.5, and unattended for 0.5.0 from a seed carrying a real router's 214-command configuration, which came back up with the LAN address, 20 DHCP reservations, the port forwards, Kea, CAKE and the agent running.

Booting the live image on physical hardware: yes, and it is where three installer bugs were found and fixed.

Read on#

Updated 2026-09-02

Edit this page