Configuration history — the archive of every successful commit

Every successful commit writes a timestamped snapshot to /config/archive/. The archive is the operator’s safety net: any previous committed configuration can be loaded as the candidate and re-applied with commit. This lesson covers the archive layout, the commands to inspect and use it, and the recovery patterns when a change has gone wrong.

The archive layout

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

Each file is named config.<YYYYMMDD>-<HHMMSS>.boot. The file is the running configuration at the moment of that commit, written in VyOS config-file syntax. The files are immutable: a load does not modify them, only copies the contents into the candidate.

Listing the archive

vyos@vyos:~$ show configuration commit
1   2026-08-14T14:23:00+01:00   vyos   10.99.0.99   config.20260814-142300.boot
2   2026-08-15T11:42:00+01:00   vyos   10.99.0.99   config.20260815-114200.boot
3   2026-08-15T14:01:00+01:00   vyos   10.99.0.99   config.20260815-140100.boot

show configuration commit lists the archive with the running config as entry 0 (implicit) and the archive entries numbered 1, 2, 3, … from oldest to newest. The columns are commit number, timestamp, user, source address, and filename.

Comparing against an archive entry

[edit]
vyos@vyos# compare 2
- system host-name router-core-02
+ system host-name router-core-01

compare N compares the candidate against the N-th archive entry rather than the running configuration. This is how operators review the diff between the current state and any historical state.

[edit]
vyos@vyos# show configuration commands | compare 2

Same output via show pipe.

Rolling back to an archive entry

[edit]
vyos@vyos# rollback 2
[edit]
vyos@vyos# compare
[edit]
vyos@vyos# commit
[edit]
vyos@vyos# save

rollback N loads the N-th archive entry into the candidate. The operator reviews the diff with compare, commits, and saves.

Loading an archive entry by filename

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

load <path> is the explicit form. rollback N is the shortcut for load /config/archive/config.<N>.boot.

Pruning old archive entries

The archive grows indefinitely. By default, VyOS keeps the last 20 entries; the rest are pruned on commit.

set system config-management commit-revisions '20'
commit
save

To prune immediately:

vyos@vyos:~$ config-management commit-revisions 5

or via the configure mode.

How the result is validated

show configuration commit
ls -la /config/archive/
compare N
load /config/archive/<file>

The first two commands list the archive; the third shows the diff to a specific entry; the fourth loads it.

How it fails

The production failure modes the engineer must recognise:

• Archive pruned before rollback needed. The operator tries to rollback to an entry that was pruned. The load fails; the operator must load from a backup.
• Archive corrupted. A bad block on the disk corrupts one archive entry. The load fails. The operator recovers from a different entry or from /config/backups/.
• Archive from a different release train. Loading an archive from a different VyOS release can fail validators if the schema has changed.
• Operator rolls back to the wrong entry. rollback 3 vs rollback 5 may look similar; the operator must read the archive listing carefully.

Rollback

The archive is the operator’s rollback tool. The patterns:

• Single bad change: rollback 1 (the most recent archive).
• Older bad change: identify the entry by timestamp, load /config/archive/config.<timestamp>.boot.
• All commits bad: load /config/backups/<known-good>.boot.
• Recovery from a rescue ISO: mount the disk, copy an archive file aside, repair the saved file.

Production discipline

Cross-course references

The Linux course’s V-Linux-NetConfig covers the underlying filesystem. The Ansible course’s XLII-Ansible-BeyondLinux covers how to drive rollback from automation. The Observability course’s XII-Observability-HostAgents covers how to alert on archive growth.

Quiz