If the install goes wrong#

The installer stops on a failure rather than carrying on, tells you what has already changed on the machine, and offers you the log. The log is /var/log/wheelhouse-install.log on the live system, and it holds 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 read it before you power the machine off.

The failure box#

  Installation stopped

  The router did not accept the settings. Its own message is in the log.

  The live configuration of this running system was changed and committed.
  Nothing has been written to /dev/sda.

     log     Show the installer log (/var/log/wheelhouse-install.log)
     shell   Open a shell to look around
     menu    Back to the Wheelhouse menu

The second paragraph is derived, not boilerplate. It says exactly how far the install got:

It says	What is true
Nothing was written to any disk, and the live configuration is unchanged.	The failure was before the first commit.
The live configuration of this running system was changed and committed. Nothing has been written to `/dev/sdX`.	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.

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

Choosing menu returns you to the welcome screen and you can try again. Your previous answers are still the defaults.

Symptoms#

Symptom	Where to look
The install stopped with a message	`/var/log/wheelhouse-install.log`, offered to you at the time
The installer never appeared, just a login prompt	You are on a serial console, or the machine booted an installed system rather than the stick. See below.
It sat on "Wheelhouse is starting" for minutes	Normal on a slow box. It waits up to five minutes for VyOS' configuration and the agent, then goes on regardless.
The banner says the agent is not active	`journalctl -u wheelhouse-agent`
No `Web UI:` line on the banner	The machine has no address. `ip -4 addr` from the console.
Browser cannot reach 8443	Firewall, wrong interface, or the agent is down. From the console: `curl -k https://127.0.0.1:8443/health`
Signed in, but every change is refused with 402	No licence. Administration → Licence — Enter a licence.
The banner says `admin / <some string>` after an install	The installer could not copy the agent's data onto the disk. First sign-in

The failures that actually happen#

The machine will not boot the stick#

Turn Secure Boot off in firmware setup. The image is self-built and nothing in the build signs the kernel with a key your firmware trusts, so the chain Secure Boot needs is not one this project completes. Both UEFI and legacy BIOS boot are otherwise built in.

If it still will not boot, the next likeliest cause is the stick: an ISO written through a wizard that repacks the filesystem loses the hybrid boot layout. Write the stick has the way to check what actually landed on it.

"This system is already installed"#

wheelhouse-install refuses to run on an installed system and says so. The check is VyOS' own is_live_boot(), with the presence of a mounted live medium as a fallback — an installed system boots through live-boot too, so the mounted medium is what tells them apart. To move to a newer image, use add system image from the System page's boot images, not the installer.

The router did not accept the settings#

The commit was refused. The router's own message is in the log, immediately after the list of commands. The commonest cause is an address or prefix the router will not take.

Nothing was written to the disk when this happens.

A prompt this version of Wheelhouse does not know#

The base installer asked something the driver's table does not cover, so the install stopped rather than guessing. The base installer's own text is printed. You can finish the install by hand from a shell with install image.

The same message appears if the base installer rejected the same answer three times over.

The console password could not be checked#

The image had no libcrypt and no mkpasswd, so the installer could not confirm that the password it set actually logs in. The install still finishes — the router did accept the command — and a screen at the end says so. Check it at the console after the first boot.

No IPv6 firewall#

The image has no firewall ipv6 configuration node, so the IPv6 ruleset was not written and the IPv4 one was. A screen at the end says so. Write the v6 filter before you turn IPv6 on.

An unattended install stopped#

It says the install did not finish and where the log is, then does what the seed's on_error says: halt by default for a seeded install, exit by default for a hand-run --answers install. It does not retry: an unattended install runs at most once per boot, so the next start of the installer shows the menu rather than erasing a disk again.

The other unattended stop that is not a failure at all: "already holds an installed system, and the seed did not ask to overwrite it". That is the guard working. Remove the seed medium, or set overwrite: true in it if you really do mean to reinstall.

Getting a shell#

From the welcome menu, shell. From the failure box, shell. Both give you a root shell on the live system, and exit returns you to where you were. The live system is a full VyOS box: ip, lsblk, journalctl and configure all work.

What to keep if you need to ask for help#

There is no support-bundle command. Keep these, from the live system before you power it off:

bash

cp /var/log/wheelhouse-install.log /mnt/somewhere/
lsblk -o NAME,SIZE,MODEL,TRAN,TYPE
ip -br link
lspci -nn | grep -i net

Where to send them: <TODO: owner>.