Image management — upgrades, downgrades, dual-image rollback

VyOS keeps two copies of the system image on disk. The active image is the one GRUB boots by default; the alt image is the previous install, kept as a safety net. Adding a new image writes it to the alt slot and flips the boot order; rolling back swaps them back. The dual-image model is the single most important reason VyOS upgrades are safer than most Linux distros — a failed upgrade is recoverable by a single reboot, not a rescue ISO.

How the dual-image model is laid out on disk

flowchart LR
  subgraph Disk["/dev/sda"]
    A["Partition 1<br/>EFI System Partition<br/>100 MiB"]
    B["Partition 2<br/>ext4 root<br/>32 GiB"]
    C["--- old image ---<br/>active or alt"]
    D["--- alt slot ---<br/>alt or active"]
  end
  A --> E["GRUB<br/>grub.cfg"]
  B --> F["/boot/grub<br/>+ squashfs root"]
  E --> G{"default boot"}
  G --> C
  G --> D

Adding a new image

vyos@vyos:~$ add system image https://downloads.vyos.net/releases/circinus/1.5.2/vyos-1.5.2-iso-amd64.iso
Downloading...
[############################################################]  100%
Installing image...
Update GRUB...
Done.

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

The new image is the default. Reboot to activate:

vyos@vyos:~$ reboot

Rolling back to the previous image

If the new image fails to boot or the routing engine misbehaves after the upgrade, the operator rolls back from the new image:

vyos@vyos:~$ configure
[edit]
vyos@vyos# rollback 1
[edit]
vyos@vyos# commit
[edit]
vyos@vyos# save
[edit]
vyos@vyos# exit
vyos@vyos:~$ reboot

rollback 1 reverts the candidate configuration to the previous saved revision. reboot boots back into the old image (the alt slot is now the default). The new image is preserved as the alt slot for further investigation.

If the new image is so broken that the operator cannot reach the shell, the recovery is from GRUB:

GRUB menu:
  vyOS 1.5.1 (old)        <- this is the alt slot
  vyOS 1.5.2 (new)        <- this is the active slot

Selecting the old image at the GRUB menu boots the box into the known-good state. The operator then delete system image the new slot to reclaim the disk space.

How to delete an image

vyos@vyos:~$ delete system image vyos-1.5.2-amd64
Are you sure you want to delete the image? [y/N]: y
Deleting image...
Update GRUB...
Done.

The image is removed from the alt slot and the GRUB entry is updated.

Corrupted boot recovery

A box that fails to boot — corrupted kernel, missing GRUB, broken filesystem — has a different recovery path:

1. Boot from the rescue ISO (the same ISO that did the original install).
2. Mount the broken root: mount /dev/sda2 /mnt.
3. Inspect the journal: journalctl -b --root=/mnt or look at /var/log/boot.log.
4. If the filesystem is corrupted, run fsck.ext4 /dev/sda2.
5. If the kernel is corrupted, chroot into the broken root and apt install --reinstall linux-image-amd64.
6. Reboot.

The rescue ISO is the operator’s most important tool for image recovery. Always have one on a USB stick in the bag.

How the result is validated

show version
show system image storage
show configuration commands | match "system image"

The running image matches the expected version; the alt slot has the previous version; the configuration has no stray system image directives that would interfere with future upgrades.

How it fails

The production failure modes the engineer must recognise:

• Configuration incompatible with the alt image. A configuration written for 1.5.2 contains directives the 1.5.1 image does not understand. The rollback commit fails or — worse — succeeds but silently ignores the unknown directives.
• Disk space exhausted. Adding a new image copies the alt slot first, doubling the disk usage. A 32 GiB disk with both slots full cannot accept a third image. The operator must delete system image first.
• Failed download. A download that completes but with a corrupted file (checksum mismatch) produces an image that fails to boot. Always verify the checksum after add system image.
• GRUB misconfiguration. A box with an extra disk or with EFI/BIOS mismatch boots but GRUB points at the wrong partition. Recovery is via rescue ISO + GRUB reinstall.
• Image added but not rebooted. A box with the new image in the alt slot but the old image still running has the slot arrangement the operator expects, but the running image is still the old one. The operator reboots to activate the new image.

Rollback

The rollback path is built into the dual-image model. Three scenarios:

• New image boots, behaviour is wrong: rollback the configuration, reboot. The old image runs with the previous configuration.
• New image fails to boot: boot the alt image from GRUB. The old image runs.
• Both images fail to boot: boot from the rescue ISO, mount the broken root, repair or reinstall.

In every scenario the operator recovers without leaving the DC.

Production discipline

Cross-course references

The Linux course’s II-Linux-Install covers the underlying GRUB and dual-boot concepts. The Ansible course’s XLII-Ansible-BeyondLinux covers how to drive add system image from an Ansible playbook across a fleet. The Observability course’s XII-Observability-HostAgents covers how to alert on show version mismatches across the estate.

Quiz