Skip to main content
Version: 1.4 (Current)

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
note

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​

CommandWhat it does
user / usersCreate an administrator / list administrators
passwdChange, expire or show the password of a local user
key / keysCreate an admin API key / list admin API keys
backup create / backup list / backup restoreBack 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.

OptionMeaning
--email, --usernameLogin of the new user (required unless --all). If it contains @, it is also stored as the email
--passwordPassword. If you omit it you are asked for it, without echo
--nameDisplay name (default: the login)
--textFree description (default: Created by ToBeAlert CLI)
--allCreate 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
OptionMeaning
LOGINLogin or email of the user (required)
--passwordNew password. If you omit it you are asked for it twice, without echo
--expire, -eDo not change the password: only force the user to choose a new one at the next login
--no-force-changeWith 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, -SShow 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.

OptionMeaning
--username, -uOwner. Must be an administrator (required unless --all)
--key, -KUse this key value instead of a random one (only with --username)
--scopePermission of the key, for example read:alerts. Repeat the option for several. Default: admin, write, read
--durationSeconds the key stays valid (default: never expires)
--textDescription (default: Created by ToBeAlert CLI)
--allCreate a key for every administrator
--forceCreate 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).

CommandWhat it does
tobealertd backup createSaves /tobealert/config, tools, license and instructions as tobealert_backup_<date>_<time>.tar.gz
tobealertd backup create --fullThe same plus /tobealert/logs
tobealertd backup listLists the backups in the folder
tobealertd backup restore --file <name>Extracts the named file (just the file name, not the path) over /tobealert
warning

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).