Ship logs off the box#

You will end up with the router's log arriving at a syslog server you already run, and — if you want it — the audit log arriving there too. A copy on another machine can still be read when the router cannot be reached.

These are two separate exports. The router's log is part of the router's configuration: it is set on System → Settings tab → Remote logging and applied like any other change. The audit log is the agent's: it is set on Admin → Agent settings → Audit log export and takes effect when it is saved. Steps 1 and 2 do the first; step 3 does the second.

Before you start#

• The Operator role and a licence, for the router's log. The Admin role for the audit log.
• A syslog server's address, and whether it takes UDP or TCP.

Step 1 — Add the log server#

System → Settings tab → Remote logging → Add log server. With none, the panel says "No remote log servers" and "Logs are kept on the router only."

Add log server adds "Send logs to 192.0.2.60" to the pending changes, with the severity, port and protocol beneath it ("Information and above, TCP").

Informational sends everything except debug messages. Debug on a busy router is a lot of traffic, and All messages includes it.

More than one log server is allowed: add one for each. To change one, click its row; to stop sending to it, click it and choose Delete log server.

Step 2 — Apply#

Apply it from the bar at the bottom of the page with Apply changes. The Remote logging table then lists the server with its port, its protocol and the messages it gets — "Informational and above". Lines start arriving at the server as soon as the change is applied.

Step 3 — Ship the audit log too#

Who changed what through the agent is in /config/wheelhouse/audit.jsonl, not in the router's log, so step 1 does not carry it. The agent has its own export for it, and it is off until you turn it on.

Admin → Agent settings → Audit log export, and turn on Send audit entries to a syslog server:

Then Save changes at the top of the page. This is an agent setting, not router configuration: it is not a pending change, and the export starts, stops or moves to a new server as soon as it is saved. The page will not save a missing server or a port out of range, and the agent checks the whole setting again and refuses one it cannot use, with the reason.

Severity is not yours to set: it comes from the entry, so a refused or failed action arrives as a warning and a successful one as informational. Alert on the difference.

Each message is the audit log's own line, hash included, framed as RFC 5424 from wheelhouse-agent with the message ID audit. An entry for applied changes carries the commands they sent, secrets included — a router account's new password, a pre-shared key — so the server's copy needs the same care as the router's configuration. Over UDP, an entry too large for one datagram (8,000 bytes) is sent without its commands; TCP carries every entry whole.

It is not a spooler: while the server is unreachable, entries are dropped and counted rather than queued on the router's flash, so a gap at the server is a gap in the copy.

The agent's own request log is in the router's log from step 1 — one line per request, with method, path, status, size, duration and client address — so even without step 3, a syslog server sees who is calling the API, if not what they changed.

Checking the export from the API#

The web interface does not show the export's own state; the admin API does:

R=https://<router>:8443
T=wh_...                                    # an admin token
curl -sk -H "Authorization: Bearer $T" "$R/api/audit/verify" | python3 -m json.tool

The export half of the answer is the export's account of itself: whether it is connected, how many entries it has sent, how many it dropped, and the last error with its time. A non-zero drop count is worth an alert of its own. The verification half walks the file's hash chain and says whether the log on the router still adds up.

For a one-off copy rather than a live feed, GET /api/audit/export streams the whole log, both generations, as JSON lines:

curl -sk -OJ -H "Authorization: Bearer $T" "$R/api/audit/export"

Check it worked#

At the server, lines from the router's host name should start arriving at once: the router's log from step 1 and, if you did step 3, audit entries from wheelhouse-agent. Saving the agent settings is itself an audit entry ("Changed the agent settings"), and signing out and in again makes two more.

On the router, Logs shows the router's log; the lines there at or above the minimum severity are the ones that should be arriving. If nothing arrives, check the server's row on Remote logging, the firewall between the router and the server, and that the server listens on that port and protocol.

Turning up the agent's own detail#

The agent takes --log-level debug. There is no setting for it in the web interface: it is set at the router's console with a systemd drop-in, rather than by editing the packaged unit, which an image upgrade replaces.

[Service]
ExecStart=
ExecStart=/usr/bin/wheelhouse-agent … --log-level debug

Repeat every option the packaged unit passes where the … is, leaving out its --log-level info; the empty ExecStart= clears the original. Then sudo systemctl daemon-reload and sudo systemctl restart wheelhouse-agent.

Undoing it#

The router's log: click the server on Remote logging, choose Delete log server — "Stop sending logs to 192.0.2.60" — and apply.

The audit log: Admin → Agent settings, turn off Send audit entries to a syslog server, and Save changes. The copy stops at once. The file on the router is unaffected, and so is its chain.

In Advanced mode#

With Advanced mode on (Account → Preferences), Review changes lists the Remote logging changes as the router's commands, under system syslog remote. The panel writes a port only when one is typed, and a protocol only when it is not UDP.

See also#

• Scrape the agent
• Export flows to a collector
• Logs and System — audit
• Agent settings
• Harden a router that faces the internet