Image management — dual-image model, add system image, alt slot

VyOS 1.5 LTS uses a dual-image model: the router has two boot slots, each holding a complete system image. The primary slot is the one that boots by default; the alternate slot is the one that boots if the primary fails. The dual-image model is the operator’s defence against a failed upgrade: if the new image does not boot, the router falls back to the old image.

This lesson covers the dual-image model, the add system image command, the boot behaviour, and the production failure modes where the dual-image rollback does not fire.

The dual-image model

The router has two boot slots:

• Primary slot — the boot slot that is selected by default. Contains the currently-running image.
• Alternate slot — the boot slot that is selected if the primary fails. Contains the previously-running image (after an upgrade) or is empty (before an upgrade).

flowchart LR
  SLOT1[Primary slot\ncurrent image] -->|boot| BOOT[Router boots]
  SLOT2[Alternate slot\nprevious image] -.->|fallback if primary fails| BOOT
  BOOT -->|primary boots| RUN[Router running]
  BOOT -.->|primary fails| SLOT2

The diagram shows the dual-image model. The primary slot boots by default. If the primary slot fails to boot (kernel panic, missing image, corrupted filesystem), the bootloader falls back to the alternate slot. The router boots the previous image; the operator can investigate the failed image.

Showing the image slots

The operator views the current image slots with show system image:

vyos@vyos:~$ show system image
The system currently has the following image installed:

   1: 1.5-rolling-202408020557 (default boot) (running)

   2: 1.4-rolling-202403010512

Use the `set system image` command to set the default
boot image.

The output shows:

• Image 1 (1.5-rolling) is the default boot and is currently running.
• Image 2 (1.4-rolling) is the alternate.

The dual-image model means the router has two installations available; the operator can switch between them with set system image.

Adding a new image

The operator adds a new system image with add system image:

# Add a new image from a URL
add system image https://vyos.net/downloads/circinus/1.5.1/vyos-1.5.1-iso-amd64.iso

# Add a new image from a local file
add system image /tmp/vyos-1.5.1-iso-amd64.iso

# Add a new image from an scp URL
add system image scp://backup@backup.internal/srv/images/vyos-1.5.1.iso

The command downloads the image (if remote), verifies the GPG signature and sha256 checksum, and installs the image into the alternate slot. The primary slot is not touched.

sequenceDiagram
  participant OP as Operator
  participant R1 as Router
  participant W as Web
  OP->>R1: add system image URL
  R1->>W: GET URL
  W->>R1: ISO image
  R1->>R1: verify GPG signature
  R1->>R1: verify sha256 checksum
  R1->>R1: install to alternate slot
  R1->>OP: image installed

The diagram shows the installation procedure. The operator initiates the install; the router downloads the image; the router verifies the signature and checksum; the router installs the image into the alternate slot; the router reports success.

Switching the boot slot

After the new image is installed, the operator switches the boot slot to the new image:

# Set the default boot image to the new image
set system image 1.5.1

The router updates the bootloader configuration to boot from the new image by default. The alternate slot retains the previous image; the dual-image model is preserved.

# Reboot into the new image
reboot

After reboot, the router is running the new image. If the new image boots successfully, the operator proceeds with the upgrade validation. If the new image fails to boot, the bootloader falls back to the alternate slot (the previous image); the operator can investigate.

Failure modes

Image fails to boot

The new image fails to boot (kernel panic, missing drivers, configuration incompatible). The bootloader falls back to the alternate slot; the router boots the previous image.

Diagnostic: the router comes up with the previous image; the operator sees the previous image’s banner; the operator investigates the new image.

Fix: investigate the new image’s failure. The defensive idiom: keep the new image installed; investigate; fix the issue; retry.

GPG signature verification fails

The image is not signed with the VyOS build system’s key. The add system image command rejects the image; the alternate slot is unchanged.

Diagnostic: the add system image command reports a signature verification error.

Fix: download the image from the official source. Do not install unsigned images.

sha256 checksum mismatch

The image is corrupted in transit (or the operator downloaded the wrong file). The add system image command rejects the image; the alternate slot is unchanged.

Diagnostic: the add system image command reports a checksum mismatch.

Fix: re-download the image; verify the checksum out- of-band; retry the installation.

Alternate slot not empty

The alternate slot already has an image (from a previous upgrade). The operator adds a new image; the router asks whether to overwrite the alternate slot.

Diagnostic: the add system image command asks for confirmation.

Fix: confirm the overwrite. The previous image in the alternate slot is replaced with the new image. The defensive idiom: if the operator wants to keep the previous image as a fallback, do not overwrite the alternate slot; boot the new image, verify, then upgrade.

Rollback

The dual-image model is the rollback mechanism. If the new image fails, the router boots the alternate slot (the previous image). The operator sets the default boot back to the previous image and continues operating.

# Set the default boot back to the previous image
set system image 1.4
reboot

The VyOS commit validator does not run during the image rollback; the rollback is a bootloader-level operation.

Production discipline

Cross-course references

• IV-VyOS-Install (vyos-iv-06-image-management) covers the image management that this lesson extends with the dual-image model.
• LVI-VyOS-Upgrades (vyos-lvi-05-upgrade-rollback, the next lessons) covers the upgrade rollback procedure that the dual-image model enables.
• LVI-VyOS-Upgrades (vyos-lvi-02-rolling-upgrade) covers the rolling upgrade procedure that uses the dual-image model.

Quiz