Command-line administration

The backd binary is also the command-line client for administering a realm. backd user and backd apikey don’t touch MongoDB: they call the realm’s admin API on a running backd, as an administrator. They never need database credentials, and every change they make goes through the same checks as any other admin request, including network restrictions.

Two commands write to MongoDB directly instead: backd bootstrap, which creates a realm’s first administrator, and backd secret rotate-key, which re-encrypts every realm’s secrets under a new master key (see Secrets).

Conventions#

• Every value is a flag. There are no positional arguments: backd user create --realm blog --email ada@example.com. --realm (and --email, --name, …) are required where the command needs them, and --url picks the server (below). backd <command> --help, or backd <command> help, lists a command’s flags; backd help lists the commands.
• Exit codes. 0 on success (and after help); 1 when the command ran and failed (a server error, a wrong password, a missing CONFIG_DIR); 2 when it was invoked wrongly (an unknown command or flag, a missing or invalid flag value). Scripts can tell the two failures apart.
• Output. Help and results go to standard output; warnings, errors and prompts go to standard error, so KEY=$(backd apikey create --realm blog --name ci) captures only the key.

Local and remote commands#

The first administrator#

Administrators are users holding an admin role: a role with admin: true in realm.yaml. The template (backd template realm) declares one, named admin:

roles:
  admin:
    description: Manages users, invitations and API keys
    admin: true

Once the realm is provisioned, create its first administrator where backd runs, with the same CONFIG_DIR and MONGO_URI:

docker compose exec backd /backd bootstrap --realm blog --email ops@example.com
# Password:
# Repeat password:
# created ops@example.com (id d3c9ljp8hc2g00b6s1m0) with the admin role "admin" in realm blog

• If realm.yaml declares several roles with admin: true, choose one with --role. A role that opens only some areas can’t be the first administrator’s: it can’t manage the rest.
• After the first administrator, others are created by an administrator, through the API.

• The password follows the realm’s password policy. It is read from the terminal without echo, or as the first line of standard input.
• To keep the assignment if the realm is ever rebuilt from its config, also list the email under the role’s users in realm.yaml. bootstrap reminds you when it isn’t listed.

At startup, backd warns about each realm that declares no admin role, or whose admin roles nobody holds.

Your own sign-in security#

backd account manages the signed-in user’s own second factor with the session backd login stored (an API key is not a person). Each change asks for a fresh proof: the authenticator code if the user has one, else the password.

backd apikey create asks for the same proof when it runs with a session: an administrator’s key outlives the session and bypasses MFA, so a person confirms it. With BACKD_API_KEY set there is nobody to ask.

Logging in#

backd login --realm blog --url https://api.example.com
# Email: ops@example.com
# Password:
# logged in to realm blog on https://api.example.com as ops@example.com (session expires at … at the latest)

backd whoami --realm blog
# ops@example.com (id d3c9ljp8hc2g00b6s1m0) on realm blog at https://api.example.com; roles: admin

backd login signs in through /_auth/login, like any user, and keeps the session for the following commands. It is an ordinary session: the realm’s idle timeout, maximum lifetime, login throttling and the user’s login_networks all apply, and it shows up in the user’s session list. backd logout --realm blog ends it on the server and forgets it.

• The second step. A user with a second factor is asked for its code after the password (Code from your authenticator app (or a recovery code)); a user in a required role who has none sets one up in the terminal: the command shows a QR code made of block characters, the otpauth:// address and the secret to type in, asks for the first code, and shows the recovery codes once (on a terminal it waits until you have saved them). The code is read from the terminal or from the next line of standard input, after the password.
• --magic-link. backd login --realm blog --email ops@example.com --magic-link asks for a message instead of a password (the realm needs magic_link) and then for the 6-digit code in it.
• Server: --url, else the BACKD_URL environment variable, else the server of the last login.
• Email: --email, or a prompt. When standard input isn’t a terminal, --email is required and the password is the first line of standard input.
• Sessions are stored per server and realm in ~/.config/backd/credentials (or $XDG_CONFIG_HOME/backd/credentials, or the file named by BACKD_CREDENTIALS). The file is created readable only by you, in a directory only you can open. Anyone who can read it can act as you until the sessions expire, so log out on shared machines.
• TLS: backd verifies the server’s certificate against the system’s CAs. For a private CA, such as the local stack’s, point BACKD_CA_CERT at its PEM file. Logging in over plain HTTP to anything but localhost, a loopback address, or a host name without dots (a container on a private network, such as http://backd:8080) prints a warning: the password would travel unencrypted.

Using an API key instead#

When BACKD_API_KEY is set, backd user and backd apikey send that key instead of a stored session. It must be an API key with the admin role. This suits automation that can’t log in interactively:

BACKD_URL=https://api.example.com BACKD_API_KEY=$ADMIN_KEY backd user list --realm blog

Errors#

Commands print the API’s error code and message, with a hint when there’s something to do:

Every command#

backd help lists the same commands in the same groups; backd <command> --help shows one command’s flags.

Develop — for building with backd (see also the quickstart):

Session:

Administer a realm:

Server:

General: backd help, backd version.