rollback — the in-place revert to a known-good state

rollback N is the operator’s recovery command. It loads the N-th archive entry into the candidate, ready for review and commit. It does not commit by itself — the operator must always compare, then commit, then save. This discipline is what makes rollback a safe operation rather than a foot-gun.

The rollback workflow

flowchart LR
  A[Bad change live] --> B[configure]
  B --> C[rollback 1]
  C --> D[Candidate = previous archive]
  D --> E[compare]
  E --> F{Diff correct?}
  F -->|yes| G[commit]
  F -->|no| H[rollback 2 or load <file>]
  G --> I[Running = reverted]
  I --> J[save]

The basic usage

[edit]
vyos@vyos# rollback 1
Loading rollback from '/config/archive/config.20260815-114200.boot'...
[edit]
vyos@vyos# compare
- system host-name router-core-02
+ system host-name router-core-01
[edit]
vyos@vyos# commit
[edit]
vyos@vyos# save

The workflow: rollback, compare, commit, save. Every step is mandatory.

Rollback numbers

rollback 0 is the running configuration (a no-op for the candidate).

rollback 1 is the most recent archive entry.

rollback 2 is the entry before that.

[edit]
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
[edit]
vyos@vyos# rollback 2

rollback 2 loads config.20260815-114200.boot (the second entry in the archive).

Rollback + commit-confirm for safe remote reverts

For a remote change that has gone wrong, the operator combines rollback with commit-confirm:

[edit]
vyos@vyos# rollback 1
[edit]
vyos@vyos# compare
[edit]
vyos@vyos# commit-confirm 5
Commit will be automatically rolled back in 5 minutes.
[edit]
vyos@vyos# exit
exit
vyos@vyos:~$

# Test the revert from outside
vyos@vyos:~$ show ip route
...

# If the revert is correct:
vyos@vyos:~$ configure
[edit]
vyos@vyos# confirm
[edit]
vyos@vyos# save
[edit]
vyos@vyos# exit

The rollback is applied with commit-confirm; if the revert is wrong (the previous configuration is not appropriate for the current state), the timer fires and the box auto-reverts to the previous state.

rollback N vs load <path>

Both load an archive entry into the candidate:

• rollback N — load the N-th archive entry by number.
• load /config/archive/<file> — load a specific archive entry by filename.
• load /config/backups/<file> — load a backup snapshot.

All three are equivalent in effect; they differ only in syntax. rollback N is convenient when the operator knows the offset; load <path> is convenient when the operator knows the filename or wants to load from a backup.

Rollback to a specific archive entry

[edit]
vyos@vyos# rollback 3

If entry 3 is the known-good state, rollback 3 followed by commit; save returns the running configuration to that state.

How the result is validated

show configuration commit
rollback N
compare
commit
save
diff /config/config.boot <(show configuration commands)

The last command confirms the running and saved configurations match.

How it fails

The production failure modes the engineer must recognise:

• Rollback to an entry from a different release train. A schema change between releases makes the entry invalid; validators reject the load.
• Rollback to an entry that breaks the current network state. The previous entry was correct for last week’s network but not for this week’s. The operator reverts and the network breaks.
• Rollback without compare or commit. The candidate has the entry loaded but the running configuration is unchanged. The operator thinks the revert is live and moves on.
• Rollback to an entry that is corrupted. The archive file has a bad block; the load fails. The operator must use a different entry or restore from backup.

Rollback

The rollback path is itself the recovery tool. If the rollback goes wrong:

• rollback N+1 (the next entry back) to revert again.
• load /config/archive/<known-good-file> if the entries are not in the right order.
• Reboot the rescue ISO if all archive entries are bad.

Production discipline

Cross-course references

The Linux course’s V-Linux-NetConfig covers the underlying configuration model. 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 rollback events.

Quiz