Command line (tobealertd)
tobealertd is the administration tool shipped inside the backend container. Use it when you cannot reach the UI: create the first administrator, issue an API key, take a backup, or manage a hotfix from a shell.
It runs inside the backend container, with the same settings (/tobealert/config/tobealertd.conf, database, volumes) as the server.
How to run it
Docker Compose
docker exec -it tobealert-backend tobealertd --help
Kubernetes
kubectl exec -it -n <namespace> <backend-pod> -- tobealertd --help
Add -it when a command asks you for something (for example a password). Without it, pass every value as an option.
tobealertd --version # release installed in the image
tobealertd <command> --help # options of any command
Commands connect to the same database as the server and take effect at once. Only hotfix commands need the backend to be restarted afterwards.
Commands
| Command | What it does |
|---|---|
user / users | Create an administrator / list administrators |
passwd | Change, expire or show the password of a local user |
key / keys | Create an admin API key / list admin API keys |
backup create / backup list / backup restore | Back up and restore configuration, tools, license and instructions |
hotfix … | List, verify, stage, apply, roll back, disable and enable hotfix bundles |
user
Creates a local administrator (login and password, BasicAuth only). Useful to get back in when nobody can sign in. The password must meet the password rules. To change the password of an existing user use passwd.
| Option | Meaning |
|---|---|
--email, --username | Login of the new user (required unless --all). If it contains @, it is also stored as the email |
--password | Password. If you omit it you are asked for it, without echo |
--name | Display name (default: the login) |
--text | Free description (default: Created by ToBeAlert CLI) |
--all | Create a local user, with the given password, for every login listed in ADMIN_USERS that does not exist yet |
docker exec -it tobealert-backend tobealertd user --email john.doe@example.com --name "John Doe"
The user gets the administrator roles from ADMIN_ROLES and is active immediately.
users
Lists the administrators (ADMIN_USERS) that exist as users: id - name (status).
passwd
Changes the password of an existing local user, like the Linux command of the same name. It works even when nobody can sign in.
docker exec -it tobealert-backend tobealertd passwd john.doe@example.com
| Option | Meaning |
|---|---|
LOGIN | Login or email of the user (required) |
--password | New password. If you omit it you are asked for it twice, without echo |
--expire, -e | Do not change the password: only force the user to choose a new one at the next login |
--no-force-change | With a new password: do not ask the user to change it at the next login. By default they must, because you now know it |
--status, -S | Show the state of the password (ok, mustChange, expired, expiringSoon), the last change and the expiry date, and exit |
The new password must meet the password rules and cannot be one of the user's last 3 passwords. The user's open sessions are closed. External users (LDAP, SAML, …) are refused: their password lives in their identity provider.
key
Creates an API key owned by an administrator and prints it. Without options that would repeat an existing key, the command reuses the key the user already has with the same permissions.
| Option | Meaning |
|---|---|
--username, -u | Owner. Must be an administrator (required unless --all) |
--key, -K | Use this key value instead of a random one (only with --username) |
--scope | Permission of the key, for example read:alerts. Repeat the option for several. Default: admin, write, read |
--duration | Seconds the key stays valid (default: never expires) |
--text | Description (default: Created by ToBeAlert CLI) |
--all | Create a key for every administrator |
--force | Create a new key even if the user already has one with the same permissions |
# A read-only key for a monitoring integration, valid for 30 days
docker exec tobealert-backend tobealertd key -u j.doe --scope read:alerts --duration 2592000 --text "Grafana"
See API keys for how to use the key and which permissions exist.
keys
Lists the API keys of the administrators.
backup
Backups are tar.gz files in /tobealert/backups (mount that path as a volume to keep them).
| Command | What it does |
|---|---|
tobealertd backup create | Saves /tobealert/config, tools, license and instructions as tobealert_backup_<date>_<time>.tar.gz |
tobealertd backup create --full | The same plus /tobealert/logs |
tobealertd backup list | Lists the backups in the folder |
tobealertd backup restore --file <name> | Extracts the named file (just the file name, not the path) over /tobealert |
A backup does not include the PostgreSQL database. Back it up with pg_dump as well. backup restore overwrites the files in /tobealert, including tobealertd.conf; restart the backend afterwards.
Other commands
tobealertd routes lists the API routes and tobealertd shell opens a Python shell with the application loaded. They are meant for support; tobealertd run starts a development server and must not be used in production (the container already starts the real server).