System — history#
The History tab of the System page lists every configuration the router has applied, says what each change did, and restores an earlier one. The Git export panel below the list copies each applied change to a git repository.
The router keeps this history itself. Each time changes are applied, it keeps the configuration as a numbered revision, the last 100 by default. Revision 0 is the configuration running now; revision 1 is the one before it, and the numbers grow older from there.
Configuration history#
The Configuration history panel shows how many revisions there are, and a table:
| Column | Shows |
|---|---|
| Revision | The revision number. |
| Applied | When the router applied it. |
| By | The account the router recorded for it. |
| Through | How the change reached the router: Web interface or API, Console, or Start-up. Anything else the router recorded is shown as it recorded it. |
With no revisions the panel says "No revisions".
What this change did#
Selecting a revision opens its panel: Revision 3, with when it was applied, by which account and through what. What this change did lists the change that made that revision as sentences, grouped by area, in the same words the pending changes use. For example, under Interfaces: "Add VLAN 20 on eth1", with "Address 192.0.2.1/24, description “IoT”" beneath it. Each sentence is marked as something added, changed or removed.
The sentences are read from the router's own record of the change: what it added, changed and removed against the revision before. A revision that changed nothing says "This revision changed nothing."
In Advanced mode the panel also shows Difference, the router's record itself: "Lines
marked + were added by this change; lines marked − were removed." Below the admin role,
the secrets in it are replaced with [redacted].
Restoring a revision#
Every revision except 0 has Restore revision 3 at the foot of its panel. The first press changes it to Restore revision 3?; the second restores. Left for five seconds, the button goes back.
"Restoring applies this revision at once, without auto-revert." A restore does not go through the pending changes and has no window in which to keep or undo it. If the revision you restore cuts off your connection to the router, nothing brings the connection back automatically: the configuration it replaced is still there as revision 1, but reaching it then takes the router's console (Locked out of the UI).
After a successful restore the page says:
Restored revision 3. The configuration it replaced is now revision 1.
with Review revision 1, which opens that revision's panel. It does not restore anything. The restore is recorded in the audit log as "Restored an earlier configuration", concerning Revision 3.
Restoring needs the approver, operator or admin role and a licence, as the agent's route does. For a viewer the button is disabled.
What a restore does not restore#
A revision is the router's configuration. It is not a backup of the router.
| Restored | Not restored |
|---|---|
| Interfaces, firewall, NAT, DHCP, DNS, routing and every other router setting | The web interface's accounts and their passwords |
| The definitions of installed apps, so apps go back with everything else | Two-factor enrolments, API tokens and sessions |
| The audit log | |
| The licence key | |
| App images and the data in their volumes |
An app taken back to a revision that names an older image version gets that version's name, not its contents: the image on the router is whichever was last downloaded.
The accounts, tokens and settings beside the configuration are what a snapshot or a backup carries: see Backup and restore.
Git export#
The Git export panel pushes the router's configuration to a git repository over SSH each time changes are applied, as a commit attributed to the person who applied them. The agent also checks the router's revisions every five minutes, so a change made another way is pushed too. Only an administrator can see and change the export; other roles see "Only an administrator can see and change the git export."
The panel's header says when it last pushed ("Last push 5m ago"), Never pushed, or Off. Push now pushes the current configuration at once. It is disabled while something is missing, with the reason as its tooltip.
Under the header:
- One sentence: "Each applied change is pushed to git@git.example.com:network/router.git, branch main.", or what is missing, such as "The export is switched off." or "This router has no export key yet."
- "The last push failed", with when and why, when it did.
- Last commit, Last push, Pushes, and Skipped, unchanged: the pushes that found nothing new to send.
This router’s key: Generate key creates the router's own SSH key for the export. The public key is then shown, ready to copy: "Add this public key to the repository as a deploy key with write access." The private key is never shown.
Settings:
| Field | Accepts |
|---|---|
| Push applied changes | Turns the export on or off. |
| Remote | "An SSH address, such as git@git.example.com:network/router.git." |
| Branch | The branch to push to; main when empty. |
| Remote host key | "The remote’s SSH host key, as a line of a known_hosts file." Nothing is pushed until it is set, so the router never sends its configuration to a host it has not been told to trust. |
| Author email domain | "Commits are signed user@domain. The router’s host name when empty." |
Save changes saves these at once: they are the agent's settings, not pending changes. Discard changes puts the form back as it was saved.
What is pushed is one file, the router's configuration. The panel's last line says what is left out: "Private keys, pre-shared secrets and password hashes are replaced with [redacted] before the file is committed — the same rule the API applies to configuration text below admin."
Saving the settings, generating the key and every push are recorded in the audit log: "Changed the git export settings", "Generated the git export key", "Pushed the configuration to git".
For automation#
The same history is available to an API token. GET /api/history lists the revisions,
GET /api/history/diff?rev=<n> returns the router's record of what a revision changed
(with secrets redacted below the admin role), and POST /api/rollback restores one:
# restore revision 1, the configuration before the last change
curl -sk -X POST -H "Authorization: Bearer $T" \
-H 'Content-Type: application/json' -d '{"revision":1}' \
https://<router>:8443/api/rollbackAn empty body restores revision 1. The restore is recorded as rollback, successful or
not, with the revision's file as its path.
See also#
- System — Save configuration and Download configuration, in the header.
- System — audit log — who made each of these changes.
- Backup and restore — everything a revision does not contain.
- Undo a change — the same restore, as a procedure.
- One app — why restoring a revision takes the apps with it.