Agent settings#

Admin → Agent settings holds the web interface's own policy: how long a sign-in lasts, whether two-factor authentication is required, the auto-revert window, the audit log, and the address the web interface answers on. None of it is router configuration. The page's own title is Settings. The page is for admins only: other roles do not see it in the navigation, and the agent refuses its requests from them.

Save changes, at the top of the page, saves every panel at once, directly. These settings do not go to the pending changes and are not applied from the bar at the bottom of the page. The button is disabled until something differs from what was loaded, reads Saved when nothing does, and stays disabled while a field shows an error. Every save is written to the audit log.

A saved setting takes effect at once, with two exceptions: a new session lifetime applies to sessions opened after the change, and a new listen address is used after the agent restarts — see Restart agent.

Sign-in#

Require two-factor authentication#

Turning it on does not shut out an account that has not set up two-factor authentication. Such an account still signs in, and sees a full-screen Set up two-factor sign-in screen with no way past it but finishing or signing out — Account. The requirement reaches sessions that are already open as well as new ones. An account that signs in through single sign-on is not asked: its second factor belongs to the identity provider.

The agent refuses to turn the requirement on when no admin account could sign in to set it up: every admin needs a password or a linked single sign-on identity first.

While it is on, nobody can turn off their own two-factor authentication. On the Account page, Turn off is disabled with Required for every account.

Changes and auditing#

Auto-revert window#

The time Apply with auto-revert gives you to press Keep changes in the bar at the bottom of the page. If nobody keeps the changes in that time, the router restarts with its saved configuration — Apply with auto-revert.

The bar shows the window on its button: Apply with auto-revert (2 min) by default. It reads this setting when the person signed in is an admin. Other roles cannot read this page, so for them the bar uses the default of 2 minutes whatever is set here.

Audit entries kept#

How many of the most recent entries the agent keeps ready to show on System → Audit log and to answer the API. It is not how long the log is kept: the log file on the router keeps every entry until it reaches 8 MiB, then starts a new file and keeps one previous file. Whatever the setting says, the agent keeps at most 10,000 entries ready, and writes a warning to its own log when the setting asks for more. To keep the record somewhere else, send it to a syslog server, below.

The audit log syslog export#

The Audit log export panel sends a copy of every audit entry to a syslog server as the entry is written.

The severity is not a setting. An action that was refused or failed arrives as a warning and one that succeeded as informational, so the syslog server can alert on the difference.

Each entry is sent as an RFC 5424 message the moment it is written, before the router's own copy is flushed to disk. Its body is the exact line the audit log file holds, hash and sequence number included, so the copy can be checked against the hash chain. The export holds nothing back for later: while the server cannot be reached, entries are dropped and counted rather than stored on the router's flash to be sent later.

The page checks the server and the port as you type. The agent checks the whole setting again when you save and refuses one it cannot use, with the reason. A saved change takes effect at once; the agent does not need a restart.

Management address#

The address and port the web interface, and the API with it, answer on.

Two warnings can appear under the field. Neither stops you saving.

• When the address belongs to an internet uplink: "… is on …, an internet uplink. The web interface would answer there and not on your local networks."
• When it is the loopback address: "… is this router's loopback address. The web interface would not be reachable from your network."

The field takes an address and a port, not a host name. The agent refuses an address this router does not have, and its refusal lists the addresses the router does have. A saved change of address is recorded in the audit log as its own entry, with the old and the new value; so is a refused one.

After you save a new address, the panel says "The saved address is used after the agent restarts." above Restart agent.

If the saved address cannot be used when the agent starts — the router no longer has it, or something else holds the port — the agent answers on the address its service passes it instead (port 8443 on every IPv4 address, on an installed router), the page shows the reason in red under Listening on, and the audit log records it.

An address saved here takes precedence over the service's own, and it is kept with the agent's data, so an image upgrade does not undo it.

In Advanced mode the panel also shows Chosen by: where the address in use came from.

Restart agent#

The agent reads the listen address when it starts, so a saved address takes effect when the agent restarts. Restart agent, at the foot of the Management address panel, does that from the page.

1. Press Restart agent. The button changes to Restart the agent?; press it again within five seconds to go ahead.
2. The web interface and the API stop answering for a few seconds, for everybody signed in. The page says "Restarting. The web interface is back in a few seconds.", waits for the agent to answer again, then says The agent restarted and reloads the settings.
3. When the agent will answer on an address this page cannot reach at its current one, the page says "Restarting. The web interface will answer at" followed by a link to the new address. Follow it. A browser keeps its sign-in per host name or address, so at a different address you sign in again.

The button is disabled, with the reason under it, while:

• there are pending changes: "Apply or discard the pending changes first." Pending changes are held by the agent and do not survive a restart.
• the bar is counting down an auto-revert window: "Keep or revert the changes applied with auto-revert first."

The agent makes its own checks when it is asked, and refuses with the reason, which the page shows as Could not restart the agent:

Every restart is written to the audit log, with who asked, before the agent stops; a refused one is recorded too, with the reason. Restarting the agent needs the admin role and no licence, because it changes no configuration.

Settings that are not on this page#

The TLS certificate, the address of the router's own API, fleet mode, single sign-on and a few other options belong to the agent's service and are set when the agent is installed. They are not on this page, and changing one needs the router's console. Every flag lists them.

The licence key is not shown here#

The licence key is stored with these settings, and neither this page nor the settings API ever returns it: the Licence page shows the licence, not its key. Saving this page keeps the stored key, so it cannot remove the licence.

For automation#

GET /api/admin/settings returns the settings, PUT /api/admin/settings saves them, and POST /api/admin/agent/restart restarts the agent. All three need the admin role.

curl -sk -H "Authorization: Bearer $T" https://<router>:8443/api/admin/settings

{
  "session_ttl_minutes": 720,
  "require_totp": false,
  "audit_retention": 2000,
  "commit_confirm_minutes": 2,
  "audit_syslog": {
    "enabled": false,
    "host": "",
    "port": 514,
    "protocol": "udp",
    "facility": "local0"
  },
  "listener": {
    "configured": "",
    "resolved": "0.0.0.0:8443",
    "source": "--addr",
    "fell_back": false
  }
}

listen_address appears when an address is saved. listener is what the running agent chose, and is not written by a PUT.

A PUT merges into what is stored: the fields a body leaves out keep their values, so a partial body does not clear them. Out-of-range values are refused with 400 and the rule — "session TTL must be between 5 minutes and 30 days", "commit-confirm window must be between 1 and 60 minutes", "audit syslog is on but no collector host is set" — and requiring two-factor authentication when no admin could sign in to set it up is refused with 409. The API accepts more facility names than the page offers, such as cron, syslog and kern.

Turning the export on in one call:

curl -sk -X PUT -H "Authorization: Bearer $T" -H 'Content-Type: application/json' \
  -d '{"audit_syslog":{"enabled":true,"host":"192.0.2.60","protocol":"tcp"}}' \
  https://<router>:8443/api/admin/settings

GET /api/audit/verify reports whether the copy is leaving the router: connected or not, how many entries have been sent and dropped, and the last error.

POST /api/admin/agent/restart answers 202 with restarting, the address the agent will answer on (listen) and after_seconds, how long to wait before looking for it. It answers 409 with the reason when it refuses.

What this page will not do#

• It does not configure the router. The router's own settings are on System → Settings tab.
• It does not manage accounts. Users, roles, API tokens and your own two-factor authentication are on the Users, API tokens and Account pages.
• It cannot change the agent's service options. Those need the router's console — see Settings that are not on this page.
• It has no per-object permissions. Four roles, enforced on every request, is what exists — Roles.

See also#

• Licence — also under Admin, where the key is entered.
• System — audit — the log these settings bound and export.
• System — settings — the router's own settings.
• Apply with auto-revert — what the auto-revert window times.
• Locked out of the UI — when the web interface does not answer.