Backup and restore#

The configuration file is not a backup. A Wheelhouse router keeps its accounts, its API tokens, its two-factor enrolments, its audit log, its licence and its TLS certificate outside config.boot, and the Download config button exports only config.boot. A backup that is one file restores a router nobody can sign in to.

Everything you need is under one directory, so the recipe is one tar. It is manual, because there is no export-everything button — see What does not exist.

What a backup has to contain#

All of /config. That is the whole answer.

The pairing at the top is the one that catches people. The router API key appears in two places and both must come from the same backup, or the agent starts, cannot authenticate to the router, and every page reports the router unreachable while the login screen works perfectly.

Taking one#

The whole thing#

From the console, or over SSH as the router account:

sudo tar -czf /tmp/wheelhouse-$(hostname)-$(date +%F).tgz -C / config

Copy it off and delete it from the router:

scp vyos@<router>:/tmp/wheelhouse-*.tgz .
ssh  vyos@<router> 'sudo rm -f /tmp/wheelhouse-*.tgz'

Check it before you trust it:

tar -tzf wheelhouse-2026-09-02.tgz | grep -E 'config/(config.boot|wheelhouse/state.json|wheelhouse/api-key)$'

Three lines means you have a backup. Fewer means you have a file.

The configuration alone#

Useful for diffing, for version control and for handing to the OPNsense importer. It is not a substitute for the above.

• From the UI: Download config in the System page header. Saves <hostname>-config.boot. Needs the admin role, because the file is unredacted.
• From the API: GET /api/config/raw.
• As set commands: GET /api/config/commands, which is easier to read in a diff. Below the admin role this response is redacted — private keys, pre-shared secrets and password hashes are blanked.
• On the router: POST /api/config/save with a file name writes a copy on the box. That is a snapshot, not a backup: it is on the disk you are protecting against.

On a schedule#

There is no scheduler in the product. Run the tarball command from cron on another machine. Take one before every upgrade and before every large change, on top of whatever runs nightly.

Restoring#

Three procedures, depending on how much is gone.

Undo a change on a running router#

System → History. Each revision has a Diff and a Restore. This needs the router running and its archive intact, and it restores configuration only — accounts and the audit log are not part of a revision.

Restore a configuration from a file#

There is no upload. POST /api/config/load names a file that is already on the router, and the UI has no file picker. So the file goes over first:

scp config.boot vyos@<router>:/tmp/restore.boot

Then, at the console, the path that lets you look before you leap:

configure
load /tmp/restore.boot
compare
commit
save

compare shows what loading the file will change, which is the reason to do it this way. You can also do it through the agent, so that it is audited as config-load — but that path commits immediately and has no preview step.

Rebuild onto new hardware#

This is a manual procedure, roughly twenty minutes, and it is worth rehearsing once before you need it. In outline: install the same version the backup came from, copy the tarball over, stop the agent, replace /config/wheelhouse and /config/archive from the backup, load and commit config.boot, start the agent, and sign in with your old account. The full step-by-step, with the commands, is docs/backup-restore.md.

Two things that catch people on that path:

• Interface names. A different NIC layout means different names. Fix them before you commit; compare shows what you are about to apply.
• The licence fingerprint. It is derived from /etc/machine-id, so a new machine is a new fingerprint and the licence server counts it as an additional activation against your router limit. The key itself comes across in the state file and keeps working; releasing the retired router's activation is done by whoever issued the key. There is no button on the router for it — see Licence.

Rebuild without a keyboard#

If you keep a config.boot with your backups, the unattended installer applies it during the install, before it writes the disk — collapsing the install and the configuration restore into one boot. That restores the router configuration; the accounts and audit log still come from the tarball.

What does not exist#

Stated plainly, because you will find out anyway.

Until those exist, the honest advice is the one that ends the repository's own document: run the tarball command from cron, encrypt what it produces, and test a restore onto a virtual machine once, before you need it. A backup you have never restored is a hypothesis.

See also#

• System — Download config and Save to boot config.
• System — history — the revisions, and what they do not carry.
• Boot images — take a backup before every upgrade.
• Licence — the fingerprint, and what a rebuild does to it.

Checked against docs/backup-restore.md, docs/upgrade.md, agent/store.go, agent/license.go, agent/main.go, agent/opmode.go, ui/src/pages/System.tsx.