Candidate, active, saved — the three configurations every VyOS box has

A VyOS router always has three configurations: the candidate (under construction in configure mode), the active (running) configuration that drives every daemon, and the saved configuration on disk that survives reboot. Each moves only on specific commands; mixing them up is the source of the most common post-incident surprise on a VyOS box.

stateDiagram-v2
  [*] --> Empty: fresh install
  Empty --> Saved: install image\n--no-default-configuration
  Saved --> Candidate: configure
  Candidate --> Candidate: set / delete / edit
  Candidate --> Active: commit
  Candidate --> Empty: discard
  Active --> Saved: save
  Saved --> Active: reboot
  Active --> Candidate: configure

The three configurations and the commands that move them

configure     # enter candidate
  set / delete   # edit candidate
  commit       # candidate -> active
exit          # leave candidate (candidate survives)
save          # active -> saved
discard       # candidate -> empty
reboot        # saved -> active

Reading /config/config.boot

vyos@vyos:~$ cat /config/config.boot
system {
    host-name router-core-01
    login {
        user vyos {
            authentication {
                plaintext-password "$6$xxxx$yyyy"
                public-keys operator@laptop {
                    key "ssh-ed25519 AAAA..."
                    type ssh-ed25519
                }
            }
        }
    }
    name-server 1.1.1.1
    ntp {
        server 0.pool.ntp.org
    }
    syslog {
        host 10.99.0.50 {
            facility all {
                level info
            }
        }
    }
}
interfaces {
    ethernet eth0 {
        address 192.0.2.1/24
    }
}
protocols {
    bgp 64512 {
        neighbor 192.0.2.2 {
            remote-as 64512
        }
    }
}

The file is human-readable VyOS config-file syntax. Operators can diff two saved configurations with diff, edit them in a text editor during recovery, and copy them between boxes.

Saving to a backup file

vyos@vyos:~$ save /config/backups/before-upgrade.boot
Saving configuration to '/config/backups/before-upgrade.boot'...
Done

save without an argument writes to /config/config.boot. With an argument, it writes to the given path. The /config directory is persistent across reboots; operators can stash snapshots there.

Restoring from a saved file

vyos@vyos:~$ configure
[edit]
vyos@vyos# load /config/backups/before-upgrade.boot
Loading configuration from '/config/backups/before-upgrade.boot'...
[edit]
vyos@vyos# compare
[edit]
vyos@vyos# commit
[edit]
vyos@vyos# save

load replaces the candidate with the contents of the file. The operator reviews the diff with compare before committing. This is the standard recovery path from a bad save or a corrupted candidate.

Configuration revision history

Every commit writes a snapshot to /config/archive/:

vyos@vyos:~$ ls -la /config/archive/
-rw-r--r-- 1 root root  4521 Aug 14 14:23 config.20260814-142300.boot
-rw-r--r-- 1 root root  4538 Aug 15 11:42 config.20260815-114200.boot
-rw-r--r-- 1 root root  4559 Aug 15 14:01 config.20260815-140100.boot

The snapshots are immutable; operators can load from any of them:

[edit]
vyos@vyos# load /config/archive/config.20260815-114200.boot

The rollback N command (covered in lesson vi-04) does the same load from a numbered archive slot.

How the result is validated

show configuration
show configuration commands | match "system host-name"
diff /config/config.boot <(show configuration commands)

The third command diffs the running config against the on-disk config.boot. If they differ, the operator forgot save.

How it fails

The production failure modes the engineer must recognise:

• commit without save. A box that reboots comes up with the last saved configuration. The committed-but-not-saved change is gone.
• Save written to a different file. save /config/backups/... writes to the backup; the live /config/config.boot is unchanged. The operator reboots and the change is gone.
• /config on a tmpfs. Some image-builder flows put /config on tmpfs; the saved configuration vanishes on reboot. The operator must persist /config to a real disk.
• Saved file from an older release train. A configuration saved on 1.5.1 may contain directives that 1.5.0 does not understand. Loading the file across release trains can fail validators.
• Edit-and-save cycle with the candidate not committed. A box whose candidate has changes that were never committed and never saved survives reboot with the last saved state; the candidate itself is lost on the next entry to configure mode.

Rollback

The candidate/active/saved model gives the operator multiple recovery paths:

• From a bad active configuration: configure; load /config/archive/config.<date>.boot; save; reload.
• From a bad save: reboot the ISO live session, mount the root, edit /config/config.boot directly.
• From a corrupted /config: reboot the ISO live session, copy a known-good backup from off-box.

The recovery path is always through one of the three configurations. There is no fourth configuration to corrupt.

Production discipline

Cross-course references

The Linux course’s II-Linux-Install covers the underlying filesystem and /config mount. The Ansible course’s XLII-Ansible-BeyondLinux covers how to drive the three- configuration model from an Ansible playbook across a fleet.

Quiz