Restore a configuration#

You will end up with a running router carrying a configuration from a file. This guide covers the case where the router is alive and you want to replace what it is running. If the router is gone, you want Rebuild a dead router onto a new box; if you only want to undo the last change, you want Undo the last commit, which needs no file at all.

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 every restore from off the box begins with scp and a shell.

Before you start#

The config.boot you want to restore.
Shell access — the console, or SSH.
A current backup of what is on the router now. You are about to replace it.

Step 1 — Get the file onto the router#

bash

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

Step 2 — Load it, read the difference, then commit#

This is the path with a preview, and it is the one to use.

bash

ssh wheelhouse@<router>
configure
load /tmp/restore.boot
compare                 # read this before you commit
commit
save

compare prints what loading the file will change against what is running. Read all of it. The lines to look for first:

Interface names. A configuration from a different box will name interfaces that do not exist here, and leave this box's real ones unconfigured.
service ssh. If the file has none and you are on SSH, committing ends your session.
The firewall. A ruleset that admits a LAN you do not have is a closed router.
service https api keys. The API key in the file must match /config/wheelhouse/api-key on this box, or the agent stops being able to read the router. See Take a backup for why those two are a pair.

If the difference is not what you expected, exit discard leaves the router untouched.

save writes the running configuration to /config/config.boot so it survives a reboot. commit alone does not.

Step 3 — Or commit it through the agent, so it is audited#

Once the file is on the box:

bash

R=https://<router>:8443
T=wh_...                                    # an operator or admin token
curl -sk -X POST -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
  -d '{"file":"/tmp/restore.boot"}' "$R/api/config/load"

That records who did it in the audit log, which the console path does not. It also commits immediately — there is no preview step on this path. Use it when you already know what is in the file, and prefer step 2 when you do not.

The endpoint needs the operator role and a licence: it is a write, so an unlicensed router answers 402.

Step 4 — Arm commit-confirm for a risky one#

If the restore touches uplinks, the firewall, NAT or SSH and you are working remotely, do it as a staged change with a confirm window rather than a bare commit, so a mistake costs two minutes instead of a drive:

bash

curl -sk -X POST -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
  -d '{"confirm_minutes":2}' "$R/api/commit"
# ... check you can still reach the router ...
curl -sk -X POST -H "Authorization: Bearer $T" "$R/api/commit/confirm"

If the confirm does not arrive inside the window, the router reboots into the previous configuration. That reboot is how VyOS implements the rollback, and it is the feature working. See Commit-confirm.

That path applies to staged operations, not to config/load. To get a preview and a confirm window for a whole-file restore, use configure / load / compare at the console and commit with commit-confirm 2 there.

Check it worked#

bash

# The running configuration is what you loaded
show configuration commands | head -40

# The agent can still reach the router
curl -sk https://127.0.0.1:8443/health

# And it survives a reboot
grep -c . /config/config.boot

Then sign in to the web UI and look at the Interfaces page: anything the configuration declares that the kernel does not have is flagged there, which is the fastest way to spot an interface-name mismatch.

If the pages report the router unreachable while the login screen works, the API key is the problem. Compare the two copies:

bash

sudo grep -A3 'api' /config/config.boot | grep key
sudo cat /config/wheelhouse/api-key

Undoing it#

The load was a commit, so it is a revision:

bash

configure
rollback 1

or POST /api/rollback with {"revision": 1}, or the Restore button on System → History. Full detail in Undo the last commit.

Restore a configuration#

Before you start#

Step 1 — Get the file onto the router#

Step 2 — Load it, read the difference, then commit#

Step 3 — Or commit it through the agent, so it is audited#

Step 4 — Arm commit-confirm for a risky one#

Check it worked#

Undoing it#

See also#