Restore a backup#

You will end up with the router running what a backup file or a snapshot holds: its configuration, its accounts, its settings, its licence and its web certificate. This guide is for a router that is running. If the router is gone, you want Rebuild a dead router onto a new box; if you only want to undo a change, you want Undo a change, which needs no file at all.

Before you start#

• The admin role and a licence.
• The .whbk file and its passphrase, or a snapshot in the Backup page's list.
• The password of an account in the backup. A restore replaces the accounts: once it finishes, only the accounts in the backup can sign in, and the ones on the router a moment earlier are gone.

Step 1 — Choose the file and what to restore#

System → Backup, panel Restore from a backup file, marked Replaces this router.

Router configuration and Web interface data are both ticked to begin with. Restore them together unless you have a reason not to: each holds a copy of the key the agent uses to reach the router, and the two copies must match.

Step 2 — Restore#

Press Restore backup. The button changes to Replace host name and sign out?; press it to go ahead, or Cancel.

The restore runs in this order, and the order is what makes it safe:

1. The file is decrypted and every file in it is checked against the checksums it carries. A wrong passphrase and a damaged file are refused with the same answer.
2. A backup taken by a newer agent is refused: update this router first. A backup taken from a router with a different host name is refused unless Allow a backup taken from another router is ticked.
3. A snapshot is taken, marked Before a restore.
4. The configuration goes through the router's own load, apply and save. If the router refuses it, nothing else is restored, and the page shows the router's reason.
5. The web interface data is written.
6. The agent restarts.

The page then shows Restore complete: what was restored, which router and date the backup came from, the snapshot taken before, and whether the web certificate came across. Under it: The agent is restarting. When it comes back, sign in with the accounts from the backup — the ones on this router a moment ago are gone.

Only one restore runs at a time.

Restore a snapshot#

System → Backup → Snapshots: press Restore on the snapshot's row, then Restore this snapshot? to go ahead. It follows the same order as a backup file, with a snapshot taken first, and puts back both the configuration and the web interface data. Sign in afterwards with an account the snapshot holds.

A snapshot is the way back from a mistake in the accounts, tokens or settings: a deleted user, or a settings change that shut a role out. A mistake in the configuration alone is quicker to undo from the History tab: Undo a change.

Check it worked#

• Sign in with an account from the backup.
• The System page's Audit log tab records the restore as Restored a backup or Restored a snapshot. A restore never replaces the audit log itself.
• The History tab shows the restored configuration as a new revision.
• Open the pages that matter most on this router, such as Interfaces and Firewall, and check they describe this hardware. A configuration from another router names that router's interfaces.

If every page reports the router unreachable while the sign-in page works, the agent's copy of the router's key no longer matches the router's. The port does not answer covers it: wheelhouse-rescue diagnose at the console finds it, and wheelhouse-rescue firstboot fixes it.

Undoing it#

The snapshot taken before the restore holds the router as it was a moment earlier. Restore it from Snapshots, where its row is marked Before a restore; the Restore complete panel names it too. For the configuration alone, Restore revision 1 on the History tab puts back the configuration the restore replaced: Undo a change.

A configuration file that is not a backup#

The Backup page takes .whbk files only, and the web interface has no upload for a config.boot or a file of commands. Putting one on the router is console work, or automation.

At the console, with a preview and an audit entry. Copy the file onto the router, then:

sudo wheelhouse-rescue restore /tmp/restore.boot

It says whether the file replaces the whole configuration (a config.boot) or merges into it (a file of set commands), prints the difference against what is running, copies the present configuration to /config/wheelhouse/config.boot.before-rescue, applies the file in one transaction so a rejected configuration is rejected whole, saves it, and records rescue-config-restore in the audit log. It runs only at a real console, never over SSH.

In a configuration session, with a preview. At the console, or over SSH:

configure
load /tmp/restore.boot
compare                 # what loading the file changes
commit-confirm 2        # apply, with a two-minute window
confirm                 # once you can still reach the router
save

exit discard instead of commit-confirm leaves without changing anything. If the window runs out without confirm, the router restarts and starts with its saved configuration, so do not save until you have confirmed.

For automation. Once the file is on the router, POST /api/config/load applies it at once, with no preview, and records Loaded a configuration file in the audit log. It needs an operator token and a licence, and it does not save: press Save configuration afterwards, or call POST /api/config/save.

curl -sk -X POST -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
  -d '{"file":"/tmp/restore.boot"}' "https://<router>:8443/api/config/load"

See also#

• Take a backup that is actually complete
• Rebuild a dead router onto a new box
• Undo a change
• Revisions and rollback
• System — backup
• Build a seed — a seed can carry a backup and restore it during an install