Revisions and rollback#
Every commit on the router is archived. The archive is numbered, newest first: revision 0 is the configuration that is running, revision 1 is the one before it, revision 2 the one before that. You can list them, ask what any one of them changed, and go back to one — and going back is not a restore ritual, it is loading that revision's file and committing it. The commit history is therefore the answer to "what changed my NAT rule and when", which is the question a configuration model exists to answer.
Listing what has happened#
R=https://<router>:8443
T=wh_... # an API token with the viewer role
curl -sk -H "Authorization: Bearer $T" "$R/api/history"{"revisions": [
{"revision": 0, "time": "2026-09-02 14:07:11", "by": "vyos", "via": "vyos-http-api"},
{"revision": 1, "time": "2026-09-02 11:52:04", "by": "vyos", "via": "vyos-http-api"}],
"raw": "…"}That comes from the router's own show system commit, parsed line by line
(agent/opmode.go handleHistoryFixed,
agent/parse.go parseCommits). The raw field is the
unparsed text, so nothing the router printed is lost if a line does not match.
Asking what a revision changed#
curl -sk -H "Authorization: Bearer $T" "$R/api/history/diff?rev=1"The answer is the router's own show system commit diff 1, verbatim, in a diff
field. + lines exist in that revision and - lines exist in the running
configuration. rev must be a non-negative integer or the agent answers 400 before
touching the router (agent/opmode.go handleHistoryDiff).
This read is redacted below the admin role, because a diff of a revision can contain a
pre-shared key or a private key (agent/main.go, the
redactSecrets(RoleAdmin, …) wrapper on the route).
Rolling back#
curl -sk -X POST "$R/api/rollback" -H "Authorization: Bearer $T" -d '{"revision":1}'
# {"success":true,"revision":1,"file":"/config/archive/config.boot.1.gz"}revision defaults to 1, which is "undo the last commit". A negative number is
refused with 400.
Three consequences follow from "load and commit", and all three matter:
- A rollback is a commit. It goes through the same road as any other, so it appears in the commit history and in the audit log, where it is recorded with the archive file it loaded.
- It does not rewind history. Nothing is deleted; the configuration you rolled away from is still in the archive.
- It needs the router to be reachable. If the change you regret is the one that cut you off, rollback cannot help — that is what commit-confirm is for, and it has to be armed before the commit, not after.
A rollback whose archive file is missing answers 502. Check ls /config/archive
on the router; that is the entry docs/deploy.md gives for it
in its troubleshooting table.
Rollback is a write: it needs the operator role and a usable licence.
Two neighbouring operations#
| Endpoint | What it does |
|---|---|
POST /api/config/save | Writes the running configuration to the boot configuration (or to a named file). Committing already persists on this platform; save is for writing a copy elsewhere. |
POST /api/config/load | Loads a configuration file that already exists on the router, and commits it — the same mechanism rollback uses, with a file you name. |
GET /api/config/raw | Downloads the whole configuration in the router's native format, unredacted. Admin only, because it contains every secret. |
What is not here#
There is also no way to name a revision or attach a note to one. The revision list carries the router's four fields and nothing more.
See also#
- The Commit Bar — how a revision gets made.
- Commit-confirm — the undo you arm beforehand.
- The audit log — who, from where, with which commands.
- System — history — the screen.
- Rolling back a change — the task guide.
- Taking a backup and restoring one.
Checked against#
agent/main.go ·
agent/vyos.go ·
agent/opmode.go ·
agent/parse.go ·
docs/deploy.md ·
docs/api-cookbook.md ·
PLAN.md §4