API and settings reference
The API
Everything except /health needs the X-Api-Key header. Every route answers on an unlicensed
installation; what a license changes is described in Licensing.
A call that also carries X-Antelao-Session is made as that account, and is held to its role:
401 when the session has ended, 403 when the role does not allow it. A call with the key alone
has full access. See Accounts.
| Method | Route | What it does |
|---|---|---|
| GET | /health | Liveness. Anonymous |
| GET | /lookup/{address} | Country and continent for one address |
| GET | /details/{address} | Everything the databases hold: ASN, city, network, coordinates |
| POST | /lookup/batch | Addresses and host names, mixed, in one call. Names are resolved and every address they answer with is looked up |
| GET | /status | Database state, build dates, sizes, SHA-256 and entity tag, the last refresh |
| GET | /databases/{edition} | The .mmdb file itself. Conditional (If-None-Match, If-Modified-Since) and resumable. Needs a license |
| POST | /update | Refreshes the databases now. Does nothing without a license, and says why |
| GET | /credentials | The MaxMind credential in force. Never returns the license key |
| PUT | /credentials | Stores a credential and tries it |
| DELETE | /credentials | Removes the stored one, so the environment's applies again |
| POST | /credentials/test | Asks MaxMind whether a credential works, and stores nothing. An empty body checks the one already in force |
| GET, POST | /apikeys | Lists the keys that can reach this API, or issues one |
| DELETE | /apikeys/{id} | Revokes an issued key |
| POST | /apikeys/{id}/delete | Deletes a revoked or expired issued key; a live key is refused |
| GET, POST, DELETE | /license | Shows, installs or removes the license |
| POST | /license/activate | Activates a license key against the license server |
| GET | /options | The service's settings, and where each of them came from |
| PUT, DELETE | /options/ratelimit | Sets the rate limit, or hands control back to the environment |
| GET, PUT, DELETE | /smtp | Outgoing mail settings. The password is never returned |
| POST | /smtp/test | Sends a test message with the settings in force. Saves nothing |
| GET | /backup | The service's database and the license as one archive. Refused to a read-only key |
| POST | /restore | Reads an archive back over them |
The routes behind the console's accounts:
| Method | Route | What it does |
|---|---|---|
| POST | /account/sign-in, /account/sign-in/code | Signs an account in with its password, then its authenticator code, and answers with a session |
| POST | /account/sign-in/passkey/options, /account/sign-in/passkey | Signs an account in with a passkey |
| GET | /account | The signed-in account |
| POST | /account/sign-out | Ends this session |
| PUT | /account/profile | Changes your own display name and e-mail |
| POST | /account/password | Changes your own password |
| POST | /account/totp/setup, /account/totp/confirm, /account/totp/disable, /account/recovery-codes | The authenticator app and its recovery codes |
| GET, POST, DELETE | /account/passkeys | Your passkeys |
| GET, DELETE | /account/sessions | Your sessions; POST /account/sessions/end-others ends all but this one |
| GET, POST, PUT, DELETE | /users | The accounts, with /users/{id}/password, /totp/reset and /sessions/end. Reading needs an administrator or read-only administrator, changing needs an administrator |
| GET | /audit | The audit log, newest first, with a search. Administrators and read-only administrators |
| GET, PUT | /ui-memory | Your console preferences |
Settings
The API container:
| Variable | Default | What it is |
|---|---|---|
Api__Keys__<name> | - | An accepted API key. At least one is required, and it cannot be revoked through the API |
Api__ConsoleKeyName | ui or console | The name of the configured key the console uses. Only a call with that key may name the signed-in person's address for the audit log and the session list |
Api__TrustedProxies__<n> | - | A reverse proxy in front of the API, as an address (172.18.0.1) or a network (172.18.0.0/16). Its forwarded address and scheme are believed, and nobody else's, so the rate limit and the audit log see the caller behind it. See A proxy that is not trusted |
GeoIp__AccountId / GeoIp__LicenseKey | - | The MaxMind account: an account id of digits and a license key of letters, digits and underscores. Overridden by anything set through the API |
GeoIp__EditionIds | GeoLite2-Country GeoLite2-ASN GeoLite2-City | Which databases to keep |
GeoIp__UpdateIntervalHours | 24 | How often they are refreshed |
GeoIp__ResolvePrivateNames | false | Whether a host name in a lookup may answer with private, loopback or link-local addresses. A lookup resolves at most 50 names, within fifteen seconds for all of them |
GeoIp__DataDir | /data/GeoIP | Where the .mmdb files live |
GeoIp__DatabasePath | /data/geoip.db | The service's database: settings, issued keys as digests, accounts and the audit log, mode 600. The settings files of earlier releases are imported into it on the first start and kept beside themselves as .imported |
GEOIP_SEED_ADMIN_PASS | generated | The built-in administrator's password, applied when the account is made and whenever the value changes |
GEOIP_SEED_ADMIN_TOTP | - | The built-in administrator's authenticator secret in base32, at least 26 characters; makes two-factor required for it. Applied when the account is made, whenever the value changes and when the account no longer has it, as after a restore. An invalid value stops the API from starting |
GeoIp__Storage | database | environment takes every setting from these variables and stores nothing; see below |
RateLimit__Enabled | false | Whether callers are rate limited at all |
RateLimit__PermitLimit | 600 | Requests one API key may make inside the window |
RateLimit__WindowSeconds | 60 | The window's length |
RateLimit__QueueLimit | 0 | Requests over the limit that wait rather than being refused |
Smtp__Enabled | false | Whether outgoing mail is sent at all |
Smtp__Host / Smtp__Port | - / 587 | The mail server |
Smtp__Security | StartTls | None, StartTls or SslOnConnect |
Smtp__UserName / Smtp__Password | - | Credentials, or neither to send without authenticating |
Smtp__FromAddress / Smtp__FromName | - / Antelao GeoIP | Who notifications come from |
Smtp__NotifyTo | - | Who they go to, separated by commas, semicolons or new lines |
Smtp__TimeoutSeconds | 30 | How long one send may take |
License__Directory | /data/license | License files and check-in state |
The mail settings are named as this service reads them. Antelao Fail2Ban names three of them
differently (Smtp__Encryption, Smtp__Username, Smtp__Recipients) and has no Smtp__Enabled, so
do not copy a mail block from one product's compose file to the other's.
The console container:
| Variable | Default | What it is |
|---|---|---|
GeoIpApi__BaseUrl / GeoIpApi__ApiKey | - | The API's address and the key the console presents |
Ui__SessionHours | 12 | How long a sign-in lasts at most. A session unused for two hours ends sooner |
Ui__TrustedProxies__<n> | - | The reverse proxy in front of the console, as an address (172.18.0.1) or a network (172.18.0.0/16). Its forwarded address and scheme are believed, and nobody else's. See A proxy that is not trusted |
Ui__AllowPlainHttp | false | true lets the console keep a sign-in over plain HTTP on a name other than localhost. The sign-in cookie can then be read by anyone on the network between the browser and the console, and the console warns about it at every start. Only for a trusted network with no HTTPS in front of the console |
Turnstile__SiteKey | - | The site key of the optional Cloudflare Turnstile check on the sign-in page. The check is on only when this and Turnstile__SecretKey are both set. See Cloudflare Turnstile |
Turnstile__SecretKey | - | Its secret key, used only to verify each answer with Cloudflare. The console then needs outbound HTTPS to challenges.cloudflare.com, and refuses a sign-in when Cloudflare cannot be reached |
Turnstile__Bypass | false | The emergency bypass: true switches the Turnstile check off although both keys are set. The start argument --Turnstile:Bypass=true does the same. Warned about at every start and noted on every sign-in in the audit log |
Turnstile__Hostnames__<n> | - | The hostnames a Turnstile answer may come from, such as the console's public name. Unset skips that check |
DataProtection__KeysPath | - | Where the console keeps the keys its sessions are protected with. Put it on a volume, so a restart does not drop every open page |
Settings from the environment only
With GeoIp__Storage=environment the service takes every setting from the variables above and
keeps nothing of its own on the volume except the GeoLite2 databases and the license. It is meant
for a volume that is a network share, such as Azure Files over SMB, where a database file is not
safe.
- The MaxMind credential, the API keys, the rate limit, the mail settings and the schedules come
from the environment or their defaults. Changing one through the API is refused with
409, naming the variable to set instead. - There are no accounts: the console cannot sign anyone in, and an API key is the only way in.
- A backup holds the license files only, and a restore is refused.
- Settings files of earlier releases on the volume are left as they are and not read.
An unknown value stops the service at start-up rather than falling back to the database.