Backup and restore#

System → Backup takes one encrypted file that holds the whole router, restores this router from such a file, and keeps snapshots on the router itself. The page is titled Backup and restore: "An encrypted file that restores this router, and snapshots kept on the router."

The page is for administrators; it is not in other roles' navigation. Taking or restoring a backup, and taking or restoring a snapshot, also need a licence. Without one the buttons are disabled: "Backups need a licence. Enter a licence key under Admin → Licence."

Take a backup#

The Take a backup panel says what the file holds: "A backup holds the whole router: the configuration with its secrets, the accounts and their passwords, two-factor secrets, API tokens, the licence and the web certificate. It is encrypted with the passphrase below, which is not stored anywhere and cannot be recovered."

Download backup is enabled once both are filled in and match. The router collects the backup, encrypts it and hands it to the browser, which saves it as wheelhouse-<host name>-<date and time>.whbk. The unencrypted contents are never written to the router's disk.

Last backup then records when it was taken and by whom, the file's name and size, and its SHA-256: compare that with the file you keep before you rely on it.

What a backup contains#

The What a backup contains panel lists every file in a backup and why, and What it does not contain lists what is left out and why. In short:

The audit log is left out on purpose: a backup protects it from a failed disk, but not from someone with root on the router. It belongs off the router, through the export on Agent settings — see System — audit log.

Restore from a backup file#

The Restore from a backup file panel is marked Replaces this router, and says so: "Restoring replaces this router’s configuration and the web interface’s data — accounts, tokens, settings, licence and certificate — with those in the file. Then the agent restarts and you sign in with the accounts from the backup. A snapshot is taken first."

Restore backup is enabled once there is a file, a passphrase of at least 12 characters, and at least one of the two parts chosen. It changes to Replace edge-1 and sign out?, with Cancel; the second press restores. In order:

1. The file is decrypted and every part in it checked. A wrong passphrase and a file changed since it was written give the same answer, because the encryption cannot tell them apart.
2. A backup written by a newer agent than this one is refused. Update this router's agent first.
3. A backup taken from a router with a different host name is refused, unless Allow a backup taken from another router is ticked.
4. A snapshot of this router is taken: Before a restore, below.
5. The configuration goes to the router, which checks it. If the router refuses it, nothing else is restored and the page shows the router's reason. Otherwise the router applies it and saves it, so it is the configuration the router starts with.
6. The web interface's data is written.
7. The agent restarts. Sign in with the accounts from the backup: "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."

The page then shows Restore complete: what was Restored, From which router and when the backup was taken, the Snapshot taken before, and Web certificate: Restored, or "Not in the backup; a new one was generated". Any warning follows. Only one restore runs at a time.

A restore does not change the interfaces in the configuration, and each ethernet interface in it is tied to the hardware address of the router it came from. Restoring onto different hardware is covered in Rebuild a dead router onto a new box.

Snapshots#

The Snapshots panel says: "The last 7 snapshots: one a day, one before every restore, and any taken by hand. They are kept on the router and are not encrypted." It adds that the configuration alone already has a history, on System → History, and that a snapshot is for what a revision cannot carry: the accounts, tokens and settings beside the configuration.

Take snapshot takes one now. Restore changes to Restore this snapshot? with Cancel; the second press restores it in the same order as a backup file — a snapshot first, the configuration through the router, then the accounts, tokens and settings, then the agent restarts.

The daily snapshot is taken a few minutes after the agent starts and every 24 hours after that. Seven are kept; the oldest goes first. A snapshot is on the router's own disk, readable by root only, so it is a way back from a mistake, not a backup: it goes with the disk.

Taking and restoring a snapshot, and taking and restoring a backup, are recorded in the audit log — a refused restore too — as "Took a snapshot", "Restored a snapshot", "Downloaded a backup" and "Restored a backup". The daily snapshot is not recorded.

The configuration alone#

Download configuration in the System page header saves the router's configuration as <host name>-config.boot: useful to read, to compare, or to keep in version control, and not a backup. The Git export on the History tab pushes the configuration to a git repository each time changes are applied, with secrets removed.

What the page does not do#

• It does not send a backup anywhere on a schedule. Snapshots are taken daily but stay on the router. A regular backup off the router needs something off the router to ask for one (For automation).
• Its file restore takes .whbk backups only. A single earlier configuration is restored from the History tab. A loose configuration file is restored at the router's console, with wheelhouse-rescue restore (Locked out of the UI).
• It needs a working agent. When the web interface cannot be reached, the backup is a copy of the router's /config directory taken at the console: Take a backup that is actually complete.
• It does not reset the router. That is Factory reset, or wheelhouse-rescue factory-reset at the console. Take a backup before using it: the reset does not.

A seed can carry a .whbk, so that a new machine installs itself as the router the backup was taken from: Build a seed that installs the replacement.

For automation#

Every action on the page is an API call for an admin token; all but the first need a licence:

A nightly backup from another machine:

15 3 * * *  curl -sk -X POST -H "Authorization: Bearer $WH_TOKEN" \
  -H 'Content-Type: application/json' -d "{\"passphrase\":\"$WH_PASSPHRASE\"}" \
  https://edge-1:8443/api/backup > /backups/edge-1-$(date +\%F).whbk

See also#

• System — Download configuration and Save configuration.
• System — history — the revisions, and what they do not carry.
• System images and updates — take a backup before every upgrade.
• Licence — the licence a backup carries.
• Take a backup that is actually complete — the same thing as a checklist.