What the installer does#

Pressing Install replaces the questions with one screen: every stage listed, a mark against the ones that are done, and a clock running on the current one. The clock is there because from the outside the difference between a slow commit and a dead box is otherwise invisible. This page says what each stage is doing, how long the quiet parts stay quiet, and what a failure at each point has already changed on the machine.

   [done]  Applying the settings to the router
   [done]  Checking the passwords
   [done]  Restoring the configuration
   [ >> ]  Preparing the disk    1:24
   [    ]  Writing the system image
   [    ]  Installing the bootloader
   [    ]  Copying the Wheelhouse data

The stages#

All seven are always listed. Restoring the configuration is skipped in place — marked done and passed straight through — unless a seed brought a configuration with it.

Stage	What it is
Applying the settings to the router	The commands from the summary's Commands view are run and committed on the live configuration.
Checking the passwords	The console one against `/etc/shadow`, the admin one by signing in to the agent with it.
Restoring the configuration	Only does anything when a seed carried one. See Installing without a keyboard.
Preparing the disk	VyOS' own image installer, driven through a pseudo-terminal.
Writing the system image	The same, copying the squashfs. This is the long, quiet stretch.
Installing the bootloader	The same, finishing.
Copying the Wheelhouse data	`/config/wheelhouse` onto the new disk.

Applying the settings#

The generated command file is run inside one configure session on the live system and committed as one transaction. The installer takes the status from commit itself rather than from the script's exit code — a configure session ends on exit whatever happened, so a refused commit would otherwise leave a script that succeeded while the router changed nothing. It also reads the output: a commit that returns success while saying in words that it failed is treated as a failure.

After this stage the live configuration of the running system has been changed and saved, and the installer knows it. Nothing has been written to the target disk.

Checking the passwords#

The console password is hashed against the vyos entry in /etc/shadow — through libcrypt if the image has it, otherwise mkpasswd — and compared. If neither is available the install continues, because the router did accept the command, but nobody is told the login was verified: a screen at the end says the password was set and accepted but could not be confirmed, and to check it at the console after the first boot.

The admin password is set through the agent's own API using the first-boot password, and then verified by signing in with the new one. Both the login body and the change body are written to files under /run with umask 077 and passed to curl as @file, so neither password appears in anyone's process listing.

If a second attempt is needed, the installer remembers that it already changed the admin password in this live session and authenticates with the new one, so coming back for another go does not lock you out.

Preparing the disk, writing the image, installing the bootloader#

These three are VyOS' own install image, run in a pseudo-terminal and answered prompt by prompt. The driver knows fifteen prompts and answers them from your answers: the image name, the console password, whether the console should default to serial, every RAID-1 question (always no), which disk, whether to use all the free space, the destructive confirmation, whether to copy data from the previous image, and whether to make the new image the default for boot.

A prompt the driver does not recognise stops the install rather than being guessed at. So does a prompt it has answered three times without the base installer accepting it. When that happens the installer prints the base installer's own text so you can finish by hand with install image.

Writing the system image is quiet for minutes while the squashfs copies. The driver treats a long silence as normal — it only gives up after 15 minutes with no output at all — but a silence that begins right after something that looks like a question is treated as a stuck prompt after 20 seconds, because that is the installer waiting for an answer nobody is going to give.

RAID-1 is answered no in every form the question takes. If you want a mirror, install from the console with install image by hand instead.

Copying the Wheelhouse data#

The base installer copies config.boot but not the rest of /config, and the agent's accounts, VyOS API key, audit log, licence and certificate all live in /config/wheelhouse. This stage mounts each ext4 partition on the new disk and copies that directory into the installed image's config directory, so the installed system starts with the account you just created rather than a fresh one.

The generated command file is copied alongside it as /config/wheelhouse/install.commands, mode 600 — a record of how this box was built, on the box.

If the copy fails, the install still succeeds and a warning goes in the log. The consequence shows up at first sign-in: the agent starts fresh, generates a one-time admin password, and the console banner prints it. First sign-in covers what to do about that.

Then the installer offers to reboot.

Where the log is#

/var/log/wheelhouse-install.log, on the live system. It contains the full list of commands the install ran, the router's own output for each stage, and the base installer's entire transcript.

It lives on a live system, so it survives only until the machine is powered off. Read it before you reboot. The installer offers to show it to you at the time.

What a failure has already cost you#

If anything fails you get an Installation stopped box with the reason, a plain statement of what has already changed, and a menu offering the log, a shell, or a return to the welcome menu. The statement is derived from how far the install got:

What it says	What it means
Nothing was written to any disk, and the live configuration is unchanged.	The failure was before the first commit. Literally true.
The live configuration of this running system was changed and committed. Nothing has been written to the disk.	The settings applied; something later failed. Your target disk is untouched.
The live configuration … was being changed when this failed, and part of it may have been applied.	The commit itself did not complete cleanly.
`/dev/sdX` has been partitioned and is partly written: whatever was on it is gone.	The base installer was past its destructive confirmation. Run the installer again and choose that disk, or choose another.

That last line is not a guess. The driver touches a marker file the moment it answers the base installer's Installation will delete all data on the drive prompt, and everything after that point reports honestly.

Two screens you may see at the end#

Console password not checked — the image had no way to hash a password, so the router's acceptance of the command could not be confirmed as a working login. Check it at the console after the first boot.

No IPv6 firewall — this image has no firewall ipv6 configuration node, so the IPv6 ruleset was not written and the IPv4 one was. Write the v6 filter before you turn IPv6 on.

Then remove the stick#

Remove the installation medium before the machine comes back up. On a machine that was installed from a seed this matters twice over: a seed left plugged in is found again on the next boot. The installer refuses to reinstall over a disk that already holds a system unless the seed asked for it, so the second boot is safe — but the first thing you want after an install is a normal boot, not a second look at the installer.