Account#
The Account page opens from your name at the bottom of the navigation, and every role can use all of it. Its subtitle: "Password, single sign-on, two-factor authentication and sessions." It shows who you are signed in as, changes your password, turns Advanced mode on or off, sets up two-factor authentication, and lists your sessions so you can end any of them. None of it is router configuration and nothing here goes to the pending changes: each change takes effect at once and is written to the audit log.
Two notices can appear at the top of the page:
- "Change the password this account was created with." An admin created or reset the account, and it has to choose a password of its own. Do that first.
- "This account signs in with single sign-on only. Set a password before unlinking it." The account exists as the Wheelhouse side of an identity provider's user, and has no password of its own.
Identity#
| Row | What it tells you |
|---|---|
| Signed in as | The account's name. |
| Role | Viewer, Approver, Operator or Admin. |
| Signed in with | Single sign-on when this session came through the identity provider, otherwise Password. |
| Single sign-on | The identity provider's ID for this account, or Not linked. |
| Can change settings | Yes for an operator or an admin, who can prepare changes. An approver's row says No: an approver applies changes others prepare. |
| Can manage users | Yes for an admin. |
| Session expires | When this session ends. The default lifetime is 12 hours; an admin sets it on Agent settings. |
Change password#
Three fields: Current password, New password and Confirm new password. Change password stays disabled until all three are filled in and the two new ones match; when they do not, the page says "The passwords do not match." The note under the button: "Changing your password signs out your other sessions."
A change:
- is refused when the current password is wrong, and the agent checks it, not the page;
- stores the new password as a fresh Argon2id hash with a new salt;
- clears the notice about the password the account was created with;
- removes the first-start password file when you are the admin the agent created when it first started;
- signs out every other session of your account and keeps the one you are using.
Choosing a password#
Any password that is not empty and is at most 1,024 characters is accepted. There is no minimum length and no complexity rule.
What protects the sign-in instead is a limit on failed attempts — 8 failures from one address in 5 minutes, 20 against one account name in 30 minutes, and past 200 failures across the router in 5 minutes every attempt is slowed by a quarter of a second — and, when you turn it on, the second factor below.
Preferences#
One switch, Advanced mode: "Shows the router's configuration commands, the configuration tree and reconcile." Off by default. With it on, the navigation adds Configuration tree and Reconcile, and pages show the configuration commands behind what they display and the commands a pending change becomes. It changes what you see, not what your role lets you do.
Pinned pages are the pages at the top of the sidebar, under Pinned, each with a live count where one number describes it: the firewall's rules, the connections on Sessions. Pin or unpin a page from its entry in the sidebar. Until you pin or unpin anything, Pinned shows Firewall, Sessions and Logs; once you have, it shows exactly what you chose, and an empty list stays empty.
Both belong to your account, not to the browser, so they follow you to another browser. Each account has its own; changing them changes nothing for anyone else.
Single sign-on#
This panel appears only when the router is set up for single sign-on.
| Row | What it shows |
|---|---|
| Provider | The provider's name, as the sign-in screen shows it. |
| Provider status | Answering, or Not answering with the reason under it. |
| This account | The provider's ID for this account, or Not linked. |
When the account is not linked, the panel says "An administrator can link this account to the identity provider." — on Users. When it is, Unlink detaches it. Unlink is disabled for an account with no password of its own, with Set a password first when you hover over it: unlinking the only way in would leave nobody able to sign in as the account. Single sign-on has the rest.
Two-factor authentication#
A code from an authenticator app, on top of the password: six digits that change every 30 seconds, from a 160-bit secret with SHA-1. A code from the step before or after the current one is accepted as well, so a phone whose clock has drifted a little still works.
The panel says "Off. Signing in asks for a password only." or "On. Signing in asks for a code from your authenticator app." Its button is Set up when two-factor authentication is off and Turn off when it is on. Setting it up voluntarily and the full-screen setup that the requirement shows are the same three steps in the same words.
1 — scan this. Setting up starts with a new secret, shown as a QR code. The code is drawn
on the page by the router itself, so nothing about the account leaves the router, and the
screen works on a router with no route to the internet. The page says the entry will appear
in the app as Wheelhouse: <your account>; the code itself names the account as
<your account>@<the router's host name>, so an app that shows the whole name shows the
router too. Cannot scan? Type it in instead shows the secret in four-character groups and
the whole enrolment URI, with "Treat both as a password: anyone who copies them can generate
your codes."
2 — prove it works. Type the current six-digit code into Six-digit code and press Turn on two-factor. A refused code says so and leaves you on the form; the page suggests checking the clock on the phone first, which is the usual cause. Start over with a new secret begins again, and Cancel leaves without changing anything.
The secret from step 1 is only pending, and does nothing at sign-in. Only an accepted code makes it the account's secret and turns two-factor authentication on, so a mis-scanned code cannot lock you out.
3 — keep these. Turning it on ends on a screen of ten single-use recovery codes. Each one signs you in once in place of a code from the app. They are shown exactly once — nothing shows them again — and Done is disabled until you tick "I have saved these codes somewhere I can reach without this router." Put them in a password manager or on paper, somewhere that is not this router.
A code looks like k7m2-pq4r-wxn9: twelve characters in three groups, from letters and
digits that leave out i, l, o, 0 and 1, which are easily misread on a printout.
Capitals, spaces and the hyphens do not matter when you type one back.
Turn off removes the secret, any pending secret, and the recovery codes with them. It is disabled, with Required for every account when you hover over it, while an admin requires two-factor authentication on Agent settings.
Recovery codes#
While two-factor authentication is on, a Recovery codes block in the panel says how many are left — 7 of 10 left, amber at three or fewer — or All used, or None issued for an account that set up two-factor authentication before recovery codes existed. The count is all the page shows: the codes themselves are never shown again.
Issue new codes (Issue recovery codes for an account with none issued) asks for "Authenticator code, or an unused recovery code" first: a printed list is a credential, and an unattended browser should not be able to make one. Issue codes then replaces the whole set — every unused code stops working the moment the new list appears — and shows the new codes once, under New recovery codes, until you tick "I have saved these codes." and press Done.
A code is used up when it signs somebody in, and the audit log
records it as totp-recovery-code-used. Issuing a set is recorded as
totp-recovery-codes-issued.
If you have neither your authenticator nor a code, another admin can clear your two-factor authentication under Admin → Users, and you set it up again. The account does not need to be deleted and re-created. The block says the same, with a link to Locked out of the UI.
When two-factor is mandatory#
When an admin turns on Require two-factor authentication, an account without two-factor authentication still signs in — refusing outright would lock it out for good, because setting it up needs a session — but what it gets is a full-screen Set up two-factor sign-in screen instead of the web interface: no navigation, no other page, and no way past it but finishing the three steps above or signing out.
That session can reach exactly five requests: the two that set up two-factor authentication, the one that says who is signed in, a password change, and signing out. Everything else is refused. The password change is among them because the two requirements stack: an account an admin has just created arrives needing both a new password and a second factor, and would otherwise be able to do neither.
The requirement is checked on every request, against the setting and the account as they are now, so turning it on reaches sessions that were already open, and turning it off releases them. A session opened through single sign-on is not held up — that second factor belongs to the identity provider — and neither is an API token or the break-glass token.
An admin can turn the requirement off again under Admin → Agent settings. The router's own console sign-in is not affected by it either way.
Sessions#
The Sessions panel lists sessions with their count. A viewer, an approver or an operator sees their own; an admin sees every account's.
| Column | What it shows |
|---|---|
| User | The account. The session you are using carries a This browser badge. |
| Role | The role the session was opened with. |
| From | The address the session was opened from. |
| Browser | The browser's own description of itself, shortened. |
| Signed in | How long ago. |
| Expires | The date and time. |
| Sign out. |
Sign out ends that session. On your own session it signs you out; an admin can sign out anyone's.
Sessions also end when they expire, when you sign out, when you change your password (every other session of yours ends), or when an admin changes your role, your password or your identity provider ID (every session ends, including the one you are using).
For automation#
GET /api/auth/me returns who you are signed in as, your role and what it allows.
POST /api/auth/password changes your password and answers 403, not 401, when the current
one is wrong. PATCH /api/auth/preferences turns Advanced mode on or off and sets the pinned
pages ({"pinned": ["/firewall", "/sessions"]}, at most 12). Two-factor
authentication is POST /api/auth/totp/begin, /totp/confirm, /totp/disable and
/totp/recovery, and GET and DELETE /api/auth/sessions list and end sessions.
A session's address is the connection's own, unless the agent was started to trust a proxy in
front of it — then it is the last address in X-Forwarded-For, the one the proxy added.
See also#
- Roles — what Can change settings and Can manage users mean in practice.
- Users — the admin side: adding accounts, resets, and linking an identity.
- API tokens — for anything scripted, instead of your own session.
- Single sign-on — how an identity becomes an account.
- Accounts and sessions — the concept.
- Authenticating — cookies, CSRF and bearer tokens as a reference.
- First sign-in — what this page looks like on a new router.
- Locked out of the UI — when the second factor is gone.