ISO install — booting VyOS from a long-support image

The ISO is the source of truth for a VyOS box. Whether the operator boots from a USB stick on a remote bare-metal server, mounts the ISO as a virtual CD-ROM in Proxmox, or rescues a router whose flash has gone read-only, every installation path in production ultimately descends from the same ISO file. The routing engineer who understands the installer is the one who can recover a bricked box at 02:00 with nothing but a console cable and a USB stick.

This lesson walks the full path: where to get the ISO, how to verify it, how the installer partitions the disk, what gets written to GRUB, and how the dual-image model lets the operator roll back a bad upgrade without a rescue stick.

Where the ISO comes from

VyOS releases are signed rolling builds from the vyos-1x repository. The LTS line — currently circinus — receives security and bug-fix backports while the rolling stream tracks upstream changes daily. A production routing estate should always pin to a specific LTS release.

vyos@vyos:~$ show version
Version:          VyOS 1.5-rolling-202408020557
Release train:    circinus
Built by:         autobuild@vyos.net
Built on:         Fri 02 Aug 2024 05:57 UTC
Build UUID:       9d3a9c1c-...
Architecture:     x86_64
Boot via:         installed image
System type:      bare metal

$ 

How the installer lays down the disk

The VyOS installer is a Debian live-build descendant. It boots a live squashfs filesystem into RAM, drops the operator at a VyOS shell, and runs install image against the target disk. The installer does not run a wizard — the operator types the command and answers prompts, which keeps the entire install reproducible and scriptable.

flowchart TB
  A[Boot ISO] --> B[Live squashfs loads into RAM]
  B --> C[Operator at vyos login]
  C --> D[Login as vyos / vyos]
  D --> E{install image}
  E --> F[Detect disks<br/>sgdisk --print /dev/sda]
  F --> G[Partition target disk<br/>BIOS boot + root ext4]
  G --> H[rsync squashfs to / partition]
  H --> I[GRUB install<br/>grub-install /dev/sda]
  I --> J[GRUB config with<br/>default + rescue entry]
  J --> K[Reboot into installed image]
  K --> L[Login + initial<br/>vyos@vyos:~$ configure]

Underneath the prompt, the installer does four things worth remembering because they shape every later operational decision:

The interactive install path

vyos@vyos:~$ install image
Welcome to the VyOS install program.
What disk should I use? [/dev/sda]: 
This will destroy all data on /dev/sda, are you sure? [y/N]: y
Looking for pre-existing filesystems on /dev/sda
Creating partitions on /dev/sda
Copying squashfs image...
Installing GRUB...
Installation complete. Reboot now? [y/N]: y

For automation, every prompt can be answered on the command line:

vyos@vyos:~$ install image --yes --disk /dev/sda

The dual-image model

A VyOS router keeps two copies of the system image on disk: the active image and the alt image. New images, downloaded via add system image, are written into the alt slot and the boot order flips. rollback in configure mode swaps them back.

stateDiagram-v2
  [*] --> Active: install image
  Active --> Upgrading: add system image vyos-1.5.2-amd64.iso
  Upgrading --> Dual: alt image present
  Dual --> Rebooting: reboot
  Rebooting --> ActiveNew: GRUB boots alt
  ActiveNew --> Rollback: rollback; commit; reboot
  Rollback --> Active: GRUB boots original

This dual-image model is the central safety net for in-place upgrades. The breakfix lessons in Part XLVII walk the failure paths in detail, but the operator should remember the three commands:

show system image storage
add system image <url-or-path>
delete system image

vyos@vyos:~$ show system image storage
Name                  Default Boot
------------------------------------
vyos-1.5.1-amd64      Yes
vyos-1.5.2-amd64      No

The “Yes” entry is the one GRUB will boot next. To flip the boot order without committing a configuration change, the operator edits the bootloader directly or uses the system’s poweroff/reboot combined with the rescue entry.

Recovery paths from an ISO boot

The same ISO that installs VyOS is also the recovery tool. Boot the ISO on a broken router, mount the existing root filesystem, and the operator can:

• edit /boot/grub/grub.cfg to flip the default boot entry
• edit /config/config.boot to fix a bad configuration
• copy a saved configuration off the disk before re-installing
• chroot into the installed root to run vyos-router operations

vyos@vyos:~$ sudo mount /dev/sda2 /mnt
vyos@vyos:~$ ls /mnt/boot/grub/
grub.cfg  grubenv  unicode.pf2
vyos@vyos:~$ cat /mnt/boot/grub/grub.cfg | grep default
set default="0"

Flipping default="0" to default="1" boots the alt image without touching the broken one. The operator can then recover.

How the result is validated

show version
show system image storage
show configuration commands | match install
show hardware detail

show version confirms the running version; show system image storage confirms both slots and which will be the default; the show configuration commands | match install line confirms no incomplete install image left dangling in the candidate.

How traffic actually flows

After install the box boots into a minimal default configuration:

flowchart LR
  A[eth0] --> C[Linux kernel]
  B[eth1] --> C
  C --> D[DHCP client<br/>on eth0]
  C --> E[VyOS<br/>configd]
  C --> F[FRR<br/>zebra]
  D --> G[Default route<br/>via DHCP]
  E --> H[SSH server<br/>on eth0]
  F --> I[Connected<br/>routes only]

The default boot is intentionally minimal: a single DHCP client on eth0, an SSH daemon, and the routing daemon running with no configuration. The operator’s first production task is to replace the DHCP client with a static address and to delete the default SSH allow rule on the WAN-facing interface before exposing the box.

How it fails

The production failure modes the engineer must recognise:

• ISO mounted from a tampered source. The router boots a tampered kernel and runs tampered binaries. Always verify the signature before writing to boot media.
• Wrong target disk. install image with no argument defaults to /dev/sda, which on a server with multiple disks may not be the intended target. Confirm with lsblk first.
• Booting without serial console configured. A remote box with only VGA console is unrecoverable from a network outage.
• UEFI/BIOS mismatch. A box booted in legacy BIOS with a GPT disk or in UEFI with an MBR disk will fail to boot after install. Check ls /sys/firmware/efi before installing.
• Default configuration leaked to production. An installer that used install image without --no-default-configuration ships the live session’s DHCP lease into the new image. The operator must scrub the configuration before connecting the box to a production network.

Rollback

The installer itself does not need a rollback — it is destructive but idempotent. The recovery path is:

• re-install from the same ISO onto the same disk (data on the existing root is destroyed)
• boot the ISO in rescue mode, mount the existing root, copy /config/config.boot aside, fix grub.cfg, reboot
• if a second image slot is present, flip the boot order in the existing image and reboot back to the old one

Production discipline

Cross-course references

The Proxmox course’s XXVIII-Proxmox-Install covers the equivalent ISO install inside a hypervisor; the bare-metal path here is identical minus the hypervisor step. The Linux course’s V-Linux-NetConfig covers the post-install network configuration in detail, and XL-Ansible-Bootstrap covers how the install is driven from an Ansible playbook when the operator wants zero-touch provisioning.

Quiz