Audit entries#

The audit log records what was done through the agent and who did it. It is one JSON object per line in <data-dir>/audit.jsonl, appended and fsynced for every entry, with the actor, their role and their source address on each one, and a hash chain over the whole file. It is not the router's system log, and it is not the configuration history, which is the router's own record of its revisions.

{"timestamp":"2026-09-18T09:14:07Z","actor":"kate","role":"operator","remote_ip":"192.0.2.44","operation":"commit","commands":["set system host-name edge-1"],"success":true,"seq":4187,"prev":"6f1c…","hash":"9ab2…"}
{"timestamp":"2026-09-18T09:15:31Z","actor":"token:terraform","role":"operator","remote_ip":"192.0.2.90","operation":"denied POST /api/admin/users","success":false,"error":"requires admin","seq":4188,"prev":"9ab2…","hash":"c410…"}
{"timestamp":"2026-09-18T09:20:02Z","actor":"admin","role":"admin","remote_ip":"192.0.2.44","operation":"agent-restart","path":["192.0.2.1:8443"],"success":true,"note":"the agent stops, and its service starts it again","seq":4189,"prev":"c410…","hash":"77e0…"}

Fields#

seq, prev and hash are absent only on entries written before the agent kept a chain. The hash is a SHA-256 of prev, a newline, and the entry's own JSON text up to its hash member, which is why that field must stay last and why a field a later agent adds is covered without breaking the entries written before it.

The names admin-token and anything beginning token: are reserved. The agent refuses to create an account with either, so an entry's actor always says which kind of principal acted.

Every operation#

The Action column of the Audit log tab words each operation as a sentence. An operation the tab does not know is shown as its code, with hyphens as spaces and a capital first letter. In Advanced mode the tab also shows the code itself.

Signing in#

Accounts#

Agent settings and licence#

Configuration#

The router#

Backup, support and the log itself#

Apps, services and diagnostics#

Fleet#

At the console#

wheelhouse-rescue writes its own entries into the chain, with actor rescue, role admin and remote_ip naming the console. The Audit log tab says each in words: Reset a password at the console, Cleared two-factor authentication at the console, Renewed the router's API key at the console, Restored a configuration at the console, Reset the management address at the console, Erased the Wheelhouse data at the console.

The rescue tool writes those entries itself, so the agent's blanking does not reach them: a configuration restored from a file of commands is recorded as up to 200 of those commands, secrets included. GET /api/audit blanks them on the way out, as it does every older entry; the file keeps them.

Storage#

Appending a line costs the length of the line, so an audited action does not rewrite the state file. A line torn by a power cut is skipped on the next read; the entries either side of it are still good. A state file written by an older agent may still carry audit entries inside it; they are moved into audit.jsonl once, when it is opened.

Retention#

Audit entries kept on Admin → Agent settings (audit_retention, 2000 by default) bounds the in-memory tail, which is what the Audit log tab and GET /api/audit serve.

Older entries stay in the file. Nothing prunes audit.jsonl except rotation. At start-up the tail is filled by reading back retention × 512 bytes from the end of each file.

The hash chain#

Editing an entry breaks its own hash; deleting one breaks the sequence and the link of the entry after it; inserting one breaks the same link. GET /api/audit/verify (admin) re-reads both generations and reports each place the record does not add up — file, line, sequence number and kind — with the head: the last sequence number and its hash. Entries written before the chain existed are covered by a digest in the first chained entry (audit-chain-start) and reported as legacy, not as breaks. A final line the file did not finish writing is reported as an interrupted write, not as an edit.

The chain proves a break; it does not prevent one. Root on the router can rewrite the file and re-chain it. The proof depends on a copy of the hashes held somewhere else.

Copies off the router#

A backup (.whbk) does not carry the log. It carries the most recent 500 entries as agent/audit-tail.jsonl, for reading, and a restore never writes them back.

Reading it#

# Through the API, newest first, 300 unless limit says otherwise:
curl -sk "$R/api/audit?limit=50" -H "Authorization: Bearer $T"

# On the router, oldest first, which is what the file holds:
sudo tail -n 50 /config/wheelhouse/audit.jsonl

# Every failure or refusal still in the current file:
sudo grep '"success":false' /config/wheelhouse/audit.jsonl | tail -50

# Who applied changes, and when:
sudo python3 -c '
import json
for line in open("/config/wheelhouse/audit.jsonl"):
    e = json.loads(line)
    if e["operation"] == "commit":
        print(e["timestamp"], e["actor"], e.get("remote_ip", ""), e["success"])
'

GET /api/audit is a viewer route: everyone who can see the router can see who changed it. No entry carries a secret. The agent blanks secret values in commands, path and error before an entry is written, by the same path rules every other read uses, so the file, the export, the syslog copy and the chain all hold [redacted] in their place and the chain verifies over exactly those bytes. Entries written by an agent older than 0.9.1 kept their secrets; GET /api/audit blanks them for every role, but the file and the export still hold them, so treat an audit.jsonl that goes back that far with the same care as state.json.

In the web UI#

System → Audit log shows the recent entries, newest first: when, who, the action as a sentence and the result, with the changes an entry carries described the way the pending changes are. In Advanced mode it also shows the operation, the path and the commands. See System — audit log.

See also#

• Endpoint index — GET /api/audit, /verify and /export.
• Role matrix — where denied … entries come from.
• Files and directories — audit.jsonl and its rotation.
• What a read hides — the path rules the audit log's blanking uses.
• The desired-state file — the loop's entries.
• Log lines worth alerting on — the system log, which is a different thing.
• The audit log — what the log is for.