Commit-confirm#

Commit-confirm applies a change and starts a timer on the router at the same moment. If a confirmation arrives before the timer runs out, the change is permanent. If it does not, the router reboots into the previous configuration. That reboot is the rollback — it is how the router's own configuration backend implements the feature, and it is what makes a change to a firewall rule, an uplink address or the SSH service survivable when you are the far side of it.

The commit-confirm window: the commit applies at once and starts a timer; confirming inside the window stops the timer and keeps the change; letting the window close reboots the router into the previous configuration

The mechanism#

It is the router's, not the agent's. The agent posts the working set with a confirm_time field, and posts an op: "confirm" to cancel:

bash

R=https://<router>:8443
T=wh_...                                  # an API token with the operator role

curl -sk -X POST "$R/api/commit" -H "Authorization: Bearer $T" \
  -d '{"confirm_minutes":2}'
# {"success":true,"committed":3,"confirm_minutes":2,"awaiting_confirm":true}

curl -sk -X POST "$R/api/commit/confirm" -H "Authorization: Bearer $T"
# {"success":true}

Underneath, those become one request each to the router's /configure endpoint — {"commands": [...], "confirm_time": 2} and {"op": "confirm"} (agent/vyos.go, ConfigureConfirm and Confirm). Both have to travel as a JSON body: the form encoding the router also accepts cannot carry confirm_time, and its form parser rejects an operation with no path, which confirm has. That is recorded, with the date it was verified on the bench, in docs/api-cookbook.md, along with the router's answers — Initialized commit-confirm; 2 minutes to confirm before reboot, then Reboot timer stopped.

The window comes from the agent's settings, commit_confirm_minutes, default 2 (agent/store.go, defaultSettings). An admin can change it under Administration → Agent settings.

What the browser does with it#

When a commit comes back with awaiting_confirm, the Commit Bar is replaced by a countdown that outranks everything else on the screen: a draining progress bar, the time left, and one sentence of reasoning —

If you can still read this page, the change worked. Confirm to keep it — otherwise the router reboots into the previous config.

That sentence is the whole test. You are being asked to prove connectivity by using it. Two buttons sit beside it (ui/src/components/CommitBar.tsx):

Confirm & keep changes posts /api/commit/confirm. A failure — the window already confirmed from a terminal, the router unreachable — is shown in the countdown rather than disappearing.
Dismiss hides the countdown and nothing else.

The countdown in the browser is the browser's arithmetic — the moment the commit returned, plus the window. It is an indicator of the router's timer, not the timer itself. Confirm with time to spare.

What the failure path actually costs#

A reboot, in full. Not a silent revert:

Every session on the router drops, including yours and any SSH.
Containers stop and come back as the restored configuration declares them — see Apps are configuration.
Uptime resets, and the boot takes as long as that hardware takes.
The change is gone. The configuration that comes back is the one that was running before the commit.

That is the trade, and it is worth stating plainly to anyone about to press the button: the safety property is real because the recovery is drastic. A router in a rack recovers by itself; a router you are about to walk away from should be confirmed first.

When to use it#

The Commit Bar offers commit-confirm on every commit, and flags the sets that most warrant it — the rule is on The Commit Bar. Use it whenever the change is in the path between you and the router:

firewall rules and zone policy;
NAT, including the rules that publish a service;
an interface address, especially on the uplink;
the default route, failover, load balancing or policy routing;
service ssh, service https and the router's API service;
anything touching certificates or accounts.

The reconcile loop uses the same mechanism when it is running in commit mode: it commits with a --reconcile-confirm window (default 2 minutes) and confirms only once the router still answers, so a change that cut the agent off is left to roll back on its own — agent/desired.go, applyCommit.

Commit-confirm and rollback are different tools#

	Commit-confirm	Rollback
When you decide	Before the commit	After it
What triggers the undo	A timer expiring	You, deliberately
How the undo happens	The router reboots into the previous configuration	An archived revision is loaded and committed
Needs the router reachable	No — that is the point	Yes
Costs a reboot	Yes, on the failure path	No

Use commit-confirm when the change might cost you the connection. Use rollback when the change worked, was committed, and turned out to be wrong.

Checked against#

agent/main.go · agent/vyos.go · agent/store.go · agent/desired.go · ui/src/components/CommitBar.tsx · ui/src/lib/staging.tsx · docs/api-cookbook.md · docs/deploy.md