Break-glass on the host

There is nobody above an admin user to ask for help, so the admin app's last resort is the server itself: whoever has a root shell on it can sign in as any admin user with a token from server:login, without that admin user's password, second step or allowed addresses. Root on the host is refused nothing.

elpanctl server:login <username>
elpanctl server:login

The command prints the sign-in page's URL and a token. Open the page, select Server Token, paste the token and select Sign In With Token. The token works once and expires after five minutes. Without a username, the token is for the admin user root, who is created when missing; any other name must already exist.

Why the token is never in a URL

The command prints the token on a line of its own rather than a link to click, and the page sends it in the request body. A token in a URL would land in the shell history, the browser history and the access logs of every proxy on the way.

When to use it

• A fresh server. It has no admin user, and the sign-in page offers only the token form, with a sentence naming the command. A bare server:login signs you in as root; from there, create the admin users you want on Admin Users. See The admin app.
• An admin user locked out. They lost their password and their passkeys, their authenticator app and backup codes are gone, or their own allowed addresses shut them out (see Allowed addresses). The token signs them in; they set new credentials on Password & Security.
• A passwordless admin user without a passkey. The passwordless page names exactly this way back.
• An admin user created before the admin app was set up. There was no page to claim a setup link on, so server:admin-user:create said to use server:login once the panel is up.

For the common cases, another admin user is the first call: they can reset the credentials on Admin Users and hand out a new setup link, without a root shell. See Reset an admin user's credentials.

What the token skips, and what it doesn't

A token sign-in is a sign-in as that admin user, with everything that follows from it. It skips:

• the password and the second step;
• the admin user's allowed addresses.

It does not skip the record. The sign-in is a Signed in row of the Auth Log with the method token, and a refused token (used twice, expired, or forged) is a Sign-in failed row. The admin user's Password & Security page then shows a note that no second step was asked, and why; its Server Token row says the same at all times. A token sign-in is not announced to the admin user's devices; a password or passkey sign-in is.

Minting the token on the host leaves no row: root needs nobody's leave. The API has a form of the same token for a server API key, and that one is recorded as Sign-in token issued on the admin user it signs in as; see API Keys.

The token also stands in when the admin app asks you to confirm your identity (see Confirm your identity): the confirmation page offers Use a server token, and the token form there names the command.

Not for automation

A token is one sign-in for a person. A system that calls the server regularly uses a server API key, which authenticates as its owner on /api/v1; see API Keys.

The other host commands

The rest of the break-glass is the server:admin-user family, which needs no token: server:admin-user:set-password gives a locked-out admin user a password, server:admin-user:reset-credentials removes every credential and prints a new setup link, server:admin-user:set-allowed-ips --clear lets them sign in from anywhere again, and server:admin-user:delete deletes them with none of the screen's refusals. Each takes a username or an id; what each does is on Admin Users.

What the sign-in page tells a locked-out admin user

Can't sign in? under the sign-in form is the admin user's own checklist: sign in with a passkey if they have one and change the password; use a backup code in place of the authenticator app; or ask another admin user to reset their credentials on Admin Users. It names no host command. A fresh server without an admin user is the one exception: there the sign-in page itself says to run server:login.

Who has root has the admin app

Every protection of an admin user's sign-in ends at the root shell. Guard access to the host as you would guard every admin user at once, and make a root shell the rare path: an admin user with a second passkey and a set of backup codes kept outside the panel never needs it.