Boot it#

Boot the machine from the stick. Both UEFI and legacy BIOS boot are built into the image, which carries grub-efi-amd64 and grub-pc. After the boot menu there is a stretch of kernel messages, then a screen saying Wheelhouse is starting, and then the installer's welcome menu. Nothing on the machine has been touched at any point on this page.

Secure Boot#

Untested. Assume you have to turn it off. The image contains VyOS' own shim-signed and grub-efi-amd64-signed, but the build passes no signing key and no key material for signing a kernel exists in this project, so the chain Secure Boot needs is not one that is completed here. If the machine refuses to boot the stick, disable Secure Boot in firmware setup and try again. What you need has the detail.

The starting screen#

   Wheelhouse is starting.

   Loading the router configuration and the agent (35 s).
   The installer opens when they are ready.

That screen is waiting for two things: VyOS to finish loading its configuration, and the agent to reach active. It counts up in five-second steps and gives up waiting after five minutes, going on to the menu regardless. On a slow box the whole wait is a couple of minutes. It is not stuck.

The installer waits because it needs the agent: one of the two passwords you are about to choose is set through the agent's own API, and verified by signing in with it. An installer that drew its first question before the agent existed would ask you for a password it could not then use.

The welcome menu#

  Wheelhouse is running from the live image.
  Nothing is written to this machine until you confirm the summary.

     install   Install Wheelhouse to a disk
     live      Keep running the live system
     shell     Open a shell

The promise on that screen is literal: at this point nothing has been written to any disk and the live configuration is unchanged. The first moment that stops being true is recorded, and the installer tells you which part of it stopped being true if something fails — see If the install goes wrong.

Where the installer runs#

On a live boot a systemd generator drops a drop-in on getty@tty1.service so that the login service on the first video console runs wheelhouse-install --auto instead of a login prompt. It is a generator rather than a competing unit because two units that both want tty1 in one boot transaction are resolved in an order that is not ours to choose, and the competing-unit version lost that race on real hardware.

Three consequences worth knowing:

• getty@tty1 keeps its restart-forever semantics. That is why choosing live and then ending the login session brings the installer back.
• Serial consoles keep their login prompt. The generator only touches tty1. On a serial console you log in and run the installer yourself — Serial consoles.
• An installed system is untouched. The generator exits immediately unless /usr/lib/live/mount/medium/live/filesystem.squashfs is present, so a machine booted from its own disk gets the normal login prompt. Running wheelhouse-install on an installed system refuses and says to use add system image instead.

dialog draws in 80 columns, and every screen and banner in the installer is sized for that.

The seed check happens before the menu#

On a live boot the installer looks for an unattended-install seed before it draws anything. If it finds one, the machine installs itself and you never see the welcome menu. Where it looks, and how to stop it, is Installing without a keyboard; the short version is that a labelled USB stick, a URL on the kernel command line, or cloud-init's own seed directory will all be found, and wheelhouse.autoinstall=off on the kernel command line insists on a person.

An unattended install runs at most once per boot, so a seed that fails cannot become a loop that keeps erasing a disk.

The console banner#

Above the login prompt, on every boot, the machine prints a banner with the web UI addresses, how to sign in, and — on a live image — how to install. The live version says:

  Console:   vyos / vyos on the live image; the installer sets yours
  Install:   on the first console; elsewhere run: sudo wheelhouse-install

The banner is rewritten every 20 seconds by a timer, so addresses appear as they arrive. First sign-in covers what it says on the installed system, which is different and more important.

See also#

• Every installer question — the next step.
• Serial consoles — if there is no screen on the machine.
• Installing without a keyboard — if there is nobody at it.
• If the install goes wrong — when the boot itself is the problem.
• Working from the console — the console on a router that is already installed.
• The image flavor — what is in the ISO and how it is built.

Checked against packaging/wheelhouse-install, packaging/wheelhouse-live-installer, packaging/console-banner.sh, packaging/dialogrc, docs/install.md, docs/hardware.md.