Upgrade Playbook: Safe Upgrades, Rollback, and Migration Testing

December 2, 2025 · 7 min read

“Just upgrade to the latest version” sounds simple. Then you discover your config syntax changed, a feature was deprecated, and your BGP peers are down. The router is 200 km away. It’s Friday at 6 PM.

VyOS image-based upgrades are actually quite safe — if you follow a process. The system keeps multiple images. Rollback is one reboot away. But you need to test before production.

Upgrades need a playbook, not improvisation.

VyOS Image System

VyOS runs from images. Multiple images can coexist:

# List installed images
show system image

# Output:
# The system currently has the following image(s) installed:
#   1: 1.4.0 (default boot)
#   2: 1.3.5 (running)
#   3: 1.3.4

Key concepts:

Running image: Currently booted
Default boot: Will boot on next restart
Multiple images: Can have several installed

Pre-Upgrade Checklist

1. Backup Everything

# Full config backup
show configuration commands > /config/backup-pre-upgrade.txt

# Save to local file
save /config/config.boot.backup-$(date +%Y%m%d)

# Copy offsite
scp /config/config.boot admin@backup-server:/backups/

# Also backup if you have custom scripts
tar -czf /tmp/config-backup.tar.gz /config/scripts/ /config/user-data/
scp /tmp/config-backup.tar.gz admin@backup-server:/backups/

2. Document Current State

# Version info
show version

# Running config
show configuration

# Interface status
show interfaces

# Routing state
show ip route
show ip bgp summary
show ip ospf neighbor

# Save all this output!

3. Check Release Notes

Before upgrading, read:

Release notes for target version
Migration notes
Known issues
Deprecated features

# VyOS release notes
# https://docs.vyos.io/en/latest/changelog/

# Check what changed between versions
# Pay attention to:
# - Breaking changes
# - Syntax changes
# - Feature deprecations

4. Verify Disk Space

# Check space for new image
df -h

# Images typically need 1-2 GB
# If low on space, remove old images
delete system image 1.3.3

Download and Add Image

From Release Server

# Add image from URL
add system image https://github.com/vyos/vyos-rolling-nightly-builds/releases/download/1.4-rolling-YYYYMMDD/vyos-1.4-rolling-YYYYMMDD-amd64.iso

# Or from local file
add system image /tmp/vyos-1.4.0-amd64.iso

Verify Download

# VyOS verifies image signature automatically
# Watch for verification messages during add

# After adding:
show system image

Upgrade Process

Step 1: Add New Image

# Download and add
add system image https://path/to/vyos-1.4.0-amd64.iso

# Follow prompts:
# - Confirm image signature
# - Keep or overwrite config
# - Set as default boot

Step 2: Set Default Boot

# If not set during add:
set system image default-boot 1.4.0

# Verify
show system image
# Should show 1.4.0 as default boot

Step 3: Reboot with Confirm Plan

# Before rebooting, ensure you have:
# - Console access (in case new image fails)
# - Rollback plan documented
# - Maintenance window scheduled

# Reboot
reboot

# Or schedule for off-hours
reboot at 02:00

Step 4: Verify After Boot

# Check version
show version

# Verify config loaded
show configuration

# Check critical services
show interfaces
show ip bgp summary
show ip ospf neighbor

# Test connectivity
ping 8.8.8.8

Rollback Procedures

If New Image Fails to Boot

At GRUB menu:

Select previous image from boot menu
System boots with old image
Config is preserved

After Booting Bad Image

# Set old image as default
set system image default-boot 1.3.5

# Reboot to old image
reboot

# After reboot, optionally delete bad image
delete system image 1.4.0

During Upgrade Issues

# If config migration fails
# System usually keeps backup

# Check for backup configs
ls /config/

# Restore backup
cp /config/config.boot.backup-20250108 /config/config.boot
reboot

Testing New Images

Test in Lab First

# Create test VM
# Same hardware profile as production

# Install current production version
# Apply production config (sanitized)
# Upgrade to new version
# Test everything

# Lab testing catches:
# - Config migration issues
# - Feature deprecations
# - Breaking changes

Staged Rollout

Day 1: Upgrade lab
Day 2-3: Test all features in lab
Day 4: Upgrade least critical production router
Day 5-7: Monitor
Day 8: Upgrade remaining routers

Test Checklist

## Upgrade Test Checklist

### Pre-Upgrade
- [ ] Config backup completed
- [ ] Release notes reviewed
- [ ] Lab test passed
- [ ] Maintenance window scheduled
- [ ] Console access verified
- [ ] Team notified

### Post-Upgrade Verification
- [ ] System booted successfully
- [ ] Correct version running
- [ ] All interfaces up
- [ ] BGP sessions established
- [ ] OSPF neighbors formed
- [ ] VPN tunnels up
- [ ] NAT working
- [ ] Firewall rules active
- [ ] DNS resolution working
- [ ] Monitoring connected

### Sign-off
- [ ] All tests passed
- [ ] No errors in logs
- [ ] Performance normal

Version-Specific Migration

1.3.x to 1.4.x Migration

Major syntax changes in VyOS 1.4:

# Firewall syntax changed significantly

# 1.3.x style:
set firewall name WAN-IN rule 10 action accept

# 1.4.x style:
set firewall ipv4 name WAN-IN rule 10 action accept
# Note the 'ipv4' addition

# VyOS migrates automatically, but verify
show firewall

Check Migration Logs

# After upgrade, check for warnings
show log | grep -i migrat
show log | grep -i deprecat
show log | grep -i error

# Migration script output
cat /var/log/vyos-migrate.log

Downgrade Considerations

Can You Downgrade?

Generally yes, but:

Config format may have changed
New features won’t exist in old version
May need manual config adjustment

# Downgrade process:
# 1. Keep old image installed
set system image default-boot 1.3.5

# 2. Reboot
reboot

# 3. Old config should load
# 4. Check for issues
show configuration

Config Compatibility

# Before upgrade, save config in both formats

# As commands (works across versions)
show configuration commands > /config/backup-commands.txt

# As JSON (useful for parsing)
show configuration json > /config/backup-json.txt

Automation

Ansible Upgrade Playbook

---
- name: VyOS Upgrade Playbook
  hosts: vyos_routers
  gather_facts: no

  vars:
    new_image_url: "https://..."
    backup_dir: "/tmp/vyos-backups"

  tasks:
    - name: Backup configuration
      vyos.vyos.vyos_command:
        commands:
          - show configuration commands
      register: config_backup

    - name: Save backup locally
      local_action:
        module: copy
        content: "{{ config_backup.stdout[0] }}"
        dest: "{{ backup_dir }}/{{ inventory_hostname }}-pre-upgrade.txt"

    - name: Download new image
      vyos.vyos.vyos_command:
        commands:
          - "add system image {{ new_image_url }}"
      register: add_result

    - name: Set new image as default
      vyos.vyos.vyos_command:
        commands:
          - "set system image default-boot"

    - name: Reboot (async)
      vyos.vyos.vyos_command:
        commands:
          - reboot now
      async: 1
      poll: 0

    - name: Wait for reboot
      wait_for:
        host: "{{ ansible_host }}"
        port: 22
        delay: 60
        timeout: 300

    - name: Verify new version
      vyos.vyos.vyos_command:
        commands:
          - show version
      register: version_check

    - name: Display version
      debug:
        var: version_check.stdout_lines

Emergency Recovery

Boot from ISO

If all images fail:

Boot from VyOS ISO (USB/CD)
Select “Live” option

Mount existing config:

mount /dev/sda1 /mnt
cp /mnt/config/config.boot /config/

Install fresh image:
Terminal window
```
install image
```

Serial Console Recovery

# Connect via serial console
# Speed: 115200 8N1

# At GRUB, can select any installed image
# Even if network is misconfigured

The Lesson

Upgrades need a playbook, not improvisation.

The playbook:

Backup everything before touching anything
Test in lab with production config
Read release notes for breaking changes
Stage rollout across multiple days
Verify everything after upgrade
Rollback plan ready before you start

What makes VyOS upgrades safe:

Multiple images coexist
Rollback is one reboot
Config usually migrates automatically

What makes upgrades dangerous:

No backup
No testing
No rollback plan
Friday at 5 PM

Treat every upgrade as potentially breaking. Have the rollback plan ready. Test first. Then it’s boring and safe — exactly how maintenance should be.