Keys and credentials
A server, its console and the services beside it use several keys, and some of them have similar names. This page lists each one once, under the name the console and the command line use.
The keys that reach the server
| Key | What it is and what it unlocks | Where it is created or shown | Where it is kept | How to replace it |
|---|---|---|---|---|
| Console key | The console's own key for the management API. It acts only for a person signed in to the console: on its own, over the network, it reaches the sign-in steps and the console's background reads, and nothing else. ohm run as root on the server uses it for local work. ohm server info lists it as API key | Made by ohm install. Shown on the server with sudo ohm server info --show-secrets | /var/lib/ohm-agent/host-state.json (mode 0600, root only), and its hash in the master database | Security > API keys > Rotate the console key, or ohm server apikey rotate. The old key keeps working for ten minutes. See Rotating the console key |
| API key | A key for a caller that is not a person: a script, a remote ohm, another console's Environments, a developer workstation (ohm dev connect asks for it as the operator API key). Each one is limited to the surfaces (Management API, GeoIP), the level (read-only or not) and the instances chosen when it was issued, and can carry an expiry | Security > API keys > Issue a key, by an Administrator, or ohm apikey create; for another console's Environments, Issue a key for a console that manages this server instead. The key is shown once, when it is issued | Its hash in the master database. The caller keeps the key itself, for example in a stored connection (ohm connection add) | Issue a new key, give it to the caller, then Revoke the old one, or ohm apikey revoke. See API keys for other callers |
| Registration key | An API key that ohm install issues when it writes the hand-off to a file, for a provisioning console to register the new server with. Its description is Provisioning registration, or Provisioned by and the console's name | Written into the hand-off file (--result, or ANTELAO_INSTALL_RESULT). ANTELAO_INSTALL_NO_REGISTRATION_KEY=yes leaves it out | As any API key | As any API key: issue another on Security > API keys, hand it to the console that registered the server, and revoke the old one |
| Operator key (of the agent) | Full authority over the host agent, including reading and rotating the console key and reopening a locked-out server. It is what you sign in to the agent's page on port 5202 with | Made by ohm install and printed in its hand-off. Shown on the server with sudo ohm server agentkey show | /etc/antelao/agent.env (ANTELAO_BOOT_KEY, mode 0600), and nowhere else | sudo ohm server agentkey rotate on the server. ohm install --rotate-secrets replaces it too |
| Consumer key (of the agent) | The scoped key ohm-api presents to the agent, so the console can have work carried out. The agent refuses it its own operator operations | Made by ohm install. Shown on the server with sudo ohm server agentkey show | /etc/antelao/agent.env (ANTELAO_BOOT_API_KEY) | sudo ohm server agentkey rotate --consumer, or --both for both agent keys. ohm install --rotate-secrets replaces it too |
| Service keys | The keys the management API presents to the server's own GeoIP, Fail2Ban and CrowdSec services | Made by the server. The GeoIP ones are listed on the API keys tab of Security > GeoIP | /var/lib/ohm-agent/host-state.json | You do not handle them |
| Access checks for instance ... | A read-only GeoIP key the server issues to an instance's site whose firewall rules ask about a caller: a country, a host name or pre-authentication | Issued by the server, and listed on Security > API keys | Its hash in the master database | The server deletes it when the instance is removed |
The two agent keys are kept across a repair. ohm install replaces them, the console key and the
admin password only when asked to with --rotate-secrets; see Repairing.
Keys for the server's features
| Key | What it is and what it unlocks | Where it is created or shown | Where it is kept | How to replace it |
|---|---|---|---|---|
| License key | Identifies your license at the Antelao license server. With your e-mail address it activates the server and fetches the signed license file (.lic) | Sent to you when you buy at antelao.io. Entered on the License page, or with ohm license activate --key | The license directory on the server, with the license file. See Installing a license | A license key does not change. The license moves to another server with Activate this server, or ohm license activate --move |
| Backup key (the server key) | Locks the server's encrypted backups, and opens them again. A key file holds its secret line (AGE-SECRET-KEY-1...), with its public line (age1...) above it | Backup storage > Encryption > Create server key. You download the key file once | Your copy of the key file, and the server's protected copy for its own restores | Replace server key. The old key moves to Older and imported keys and keeps opening the backups it locked. See Backup encryption |
| Instance key | An optional second key for one instance's encrypted backups, held by the instance's owner. The server keeps only its public half | The instance's Backup tab, under Encryption: Create one for me, or the owner's own public key | The owner's key file | Make a new one the same way, and keep the old file for the backups it locked |
| Turnstile site key and secret key | The Cloudflare Turnstile widget's two keys, which switch the check on the console's sign-in page on | Made in the Cloudflare dashboard. Entered on Security > Threat protection > Turnstile, with ohm server turnstile set, or at install with ANTELAO_INSTALL_TURNSTILE_SITE_KEY and ANTELAO_INSTALL_TURNSTILE_SECRET_KEY | In the server's settings, the secret key encrypted. It is never shown again | Enter new keys on the same page. See Turnstile |
| MaxMind account ID and license key | The MaxMind account the GeoIP service downloads the GeoLite2 databases with, which location rules match against | Made at MaxMind. Entered on Security > GeoIP, in the bootstrap document (geoip), or with ANTELAO_INSTALL_MAXMIND_ACCOUNT and ANTELAO_INSTALL_MAXMIND_KEY | In the server's settings, encrypted | Enter the new one on Security > GeoIP. See Location rules and GeoIP |
| Key rings | The keys the management API encrypts every stored credential with (the console's ring protects its sign-in cookies). Nobody types or reads them | Made by the containers | The Docker volumes ohm-api-keys and ohm-web-keys | Not replaced. Back up ohm-api-keys with the master database: see Backing up the server |
Every other credential you type into the console - backup storage passwords and keys, the SMTP password, git tokens, a DNS provider's token - is stored encrypted under the management API's key ring and is never shown again. It is replaced where it was entered.
GeoIP and Fail2Ban on their own
Run on their own, Antelao GeoIP and Antelao Fail2Ban have keys of their own, set in their compose
files: configured keys (Api__Keys__<name>), issued keys from their consoles, and the
*_SEED_ADMIN_PASS and *_SEED_ADMIN_TOTP values of the built-in administrator. Each product's own
manual describes them: see Related.
Related
- API keys
- Security overview
- Backup encryption
- GeoIP API keys, in the GeoIP manual
- Fail2Ban API keys, in the Fail2Ban manual