Runbook: Restore a VyOS Configuration

1 · Prerequisites

Confirm every item is in place before any state change.

• Saved configuration — /config/config.boot, scp, off-box copy, versioning
• Remote backup — cron + rsync, version control commit, S3 bucket
• Restore onto the same appliance — load saved, verify, commit, save
• Restore onto a different appliance — hardware replacement, configuration migration, IP changes
• Full router loss — RMA, replacement, restore, verify adjacency
• commit-confirm — the rollback safety net for remote changes
• Configuration history — the archive of every successful commit
• save — making the configuration persist
• Out-of-band access — OOB management VRF, console server, IPMI, the lockout safety net

2 · Pre-checks

Read-only diagnostic commands. If any of these don't match expected output, stop and investigate further.

• · The question "is this a restore or a rollback?" has been answered. If the state you want is an entry in show configuration commit, this is the wrong runbook - rollback N needs no file, no transfer and no source-selection decision
• · The source file is named exactly, with its age: an archive entry, /config/backups/<label>.boot, the off-box rsync copy, or a specific commit in the configuration repository. "The backup" is not a source; each of those has a different lag and restoring from the wrong one discards different work
• · The gap between the source and now is understood and accepted by the change owner. Everything committed after the snapshot is about to be discarded, including changes made by people who are not in this incident
• · Out-of-band access is confirmed and tested. A restored configuration replaces the interface addressing, the SSH binding and the firewall in one commit, so it can remove the session running it
• · Whether the target hardware matches the hardware the file was written for is established: same interface names, same hw-id values, same addressing. A configuration is not portable between appliances by default
• · The current configuration has been captured off-box first, even though it is the broken one. load overwrites the candidate, and the broken configuration is the only record of what went wrong
• · A pre-restore snapshot exists on the box: save /config/backups/pre-restore.boot. The archive only records committed states, so an uncommitted or partially repaired candidate has no other way back
• · For a restore that touches the routing plane, the peers or the change owner know it is happening. A restore re-establishes adjacencies from scratch and the reconvergence is visible from other people routers

3 · Procedure

Execute each step in order. Verify the expected output of a step before moving to the next.

1. 1Decide whether this is a restore at all. show configuration commit lists every archived commit with its timestamp, user and source address; if the good state is in that list, stop here and use rollback N instead.
2. 2Choose the source deliberately and write down its age. The local archive is as fresh as the last commit, /config/backups/ as fresh as the last manual snapshot, the off-box rsync copy as fresh as its interval, and the off-site archive as fresh as its daily run.
3. 3Capture the state you are about to destroy: show configuration commands written off-box, plus the operational view - show interfaces, show ip route, show ip bgp summary, show ip ospf neighbor - so the post-restore comparison has a baseline.
4. 4Take a pre-restore snapshot on the box with save /config/backups/pre-restore.boot, so a restore that turns out to be wrong has somewhere to go back to that is not the archive.
5. 5Get the file onto the router by the path most likely to work. load scp://... makes the ROUTER the client and needs its DNS, routing and host keys intact; during an outage those are candidates for the thing that is broken. Pushing the file with scp from the workstation, or pasting it over the console, does not.
6. 6Load it into the candidate: configure, then load /path/to/file. This REPLACES the candidate; it does not merge. The active configuration is untouched until commit.
7. 7Read the whole compare output, not the part you expected. On a restore the diff is every change made since the snapshot was taken, which includes other people work, and it is the only place that becomes visible.
8. 8If the hardware differs from the source, fix the hardware-bound nodes in the candidate BEFORE committing: interface names, hw-id values, and any address that has moved. Committing first and fixing afterwards means the box comes up with no working interface.
9. 9Commit with commit-confirm whenever the restore includes the interface, SSH, VRF or firewall configuration that carries your session - which for a full restore is always. Then verify from OUTSIDE configure mode, and confirm only after the check passes.
10. 10save with no argument. save /config/backups/... writes a snapshot and leaves /config/config.boot untouched, so a restore that ends that way is one reboot away from reverting.
11. 11Verify at the protocol layer, in dependency order: interfaces up, then addresses, then adjacencies, then routes, then traffic. A configuration that matches the file proves the load worked, not that the router does.
12. 12Reconcile the sources of truth: push the restored configuration back to the off-box copy and the repository, or the next scheduled backup captures the restored state as if it were a change nobody made.

4 · Verification

Confirm the procedure actually fixed the problem.

• ✓compare was read in full before the commit, and every line in it was either expected or explicitly accepted as lost work
• ✓show interfaces lists every interface the configuration expects, with the expected addresses and admin state - not merely the same count
• ✓No interface is missing because its hw-id does not exist on this hardware: show configuration commands | match "hw-id" matches what the box actually has
• ✓Routing adjacencies are re-established rather than merely configured: show ip ospf neighbor shows Full, show ip bgp summary shows Established with a plausible prefix count, and any BFD sessions are up
• ✓show ip route contains the expected routes, including the default, and the FIB agrees with the protocol tables
• ✓Traffic passes end to end through the router, tested from a client rather than from the router itself
• ✓The restore persisted: ls -la /config/config.boot shows a current timestamp and diff /config/config.boot <(show configuration commands) returns nothing
• ✓A new archive entry exists for the restore commit in show configuration commit, attributed to the operator who ran it
• ✓The off-box backup and the configuration repository have been updated with the restored state, so the next scheduled run does not report it as unexplained drift

5 · Rollback

If verification fails, undo the procedure in reverse order.

• ↶Before the commit, discard throws the loaded candidate away and leaves the running configuration untouched. This is the free exit and it is available right up to the moment you commit
• ↶While the commit-confirm timer runs, doing nothing restores the pre-restore state automatically. This is the intended path when the verification fails, and it is why a restore of the access path is committed no other way
• ↶After a confirmed restore, the way back is the pre-restore snapshot: load /config/backups/pre-restore.boot, compare, commit, save. This is why Step 4 exists
• ↶rollback 1 also works after a confirmed restore, because the restore itself wrote an archive entry - but read compare first. During an incident the previous entry may be the broken configuration you were escaping
• ↶POINT OF NO RETURN: work committed after the snapshot was taken. A restore discards it silently; nothing in the output names what was lost, which is why the compare output is the record
• ↶POINT OF NO RETURN: an archive entry that has been pruned. commit-revisions defaults to 20 and pruning is irreversible, so an older state exists only in the off-box copy or nowhere
• ↶POINT OF NO RETURN: a restore performed as part of a credential incident. Every pre-incident file contains the compromised secrets, so the restore must be followed by re-applying every rotation
• ↶A reboot is not a rollback. If save has already run, the box comes back on the restored configuration - the pre-restore state is only in the snapshot file and the archive

6 · Escalation

When the runbook isn't enough, contact:

• · Escalate to the change owner before discarding work: the compare output names people whose changes are about to be reverted, and that is their decision as much as yours
• · Escalate to network engineering before restoring a router in a redundant pair. A restore drops and re-establishes every adjacency, so the pair is briefly running on one member
• · Escalate to the platform team if no source is fresh enough to be useful. A backup that predates a major change is a decision about how much to rebuild by hand, not a restore
• · Escalate if the target hardware differs from the source: different interface names, a different port count, or different addressing turn a restore into a migration with its own review
• · Escalate to security if the reason for the restore is suspected compromise. Restoring from a pre-incident file reintroduces whatever was disclosed, and that sequencing is not an on-call decision
• · Escalate if the load fails on a validator. A configuration written by a different VyOS release train can be rejected by the current schema, and the fix is a migration rather than a retry
• · Escalate if the router cannot reach the backup source and the console is the only remaining path - a large configuration pasted over a serial line is slow enough to need its own window

References

1. VyOS documentation - configuration file and load
2. VyOS documentation - basic system configuration
3. VyOS documentation - rollback
4. VyOS documentation - commit-confirm
5. VyOS documentation - CLI fundamentals
6. VyOS documentation - Ethernet interfaces