API and settings reference
The API
Everything except /health needs the X-Api-Key header. Twenty wrong keys from one address in five
minutes are answered 429 for the rest of the window; see API keys. The only
thing a license changes is whether a ban writes a firewall rule; see 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: {"status":"ok"} and nothing else. Anonymous; the version and the daemon's state are on /status |
| GET | /status | The daemon's version, uptime and restarts, how much is being enforced, and whether it is blocking or only detecting |
| GET | /jails, /jails/{name} | Every stored jail, and one with its definition |
| PUT | /jails/{name} | Creates or replaces a jail and applies it. Its log paths must be in the mounted log folders. See Jails |
| DELETE | /jails/{name} | Stops a jail and removes it |
| GET | /jail-templates | Ready-made jails the console offers as a starting point |
| GET | /bans | The bans in force, with the log lines that earned them |
| POST | /bans | Bans an address by hand. Unlicensed, it answers what would have happened and writes no rule |
| DELETE | /bans/{jail}/{address} | Lifts a ban. Never license-gated |
| GET, PUT | /options | The global options every jail inherits. A save applies them |
| GET | /firewall/detect | What the host's firewall looks like, and the options that suit it. Reports only |
| GET | /firewall/choices | The chains and ban actions this host can use, as the Options page lists them |
| POST | /firewall/diagnostics | Proves a rule can be written on this host |
| POST | /firewall/rebuild | Writes fail2ban's chains again and removes orphaned ones. See The firewall |
| GET | /logs | The daemon's recent log. after follows it, limit bounds it, level filters to that level and worse |
| POST | /reload | Re-reads the configuration without stopping anything. A jail or options save already does this |
| POST | /restart | Stops the daemon and starts it again. Bans are kept; nothing is enforced for a second or two |
| GET | /geoip | The GeoIP settings in force and the state of every mirrored database |
| PUT | /geoip | Stores the address, key and mode, and starts a sync. Without apiKey the key in force is kept. A link-local or cloud metadata address is refused |
| DELETE | /geoip | Removes the stored settings, so the environment applies again |
| POST | /geoip/sync | Starts bringing the mirror up to date. Answers 202 |
| GET | /geoip/lookup/{address} | Where one address is, through whichever source the mode names |
| GET | /smtp | The mail settings in force, and what became of the mail sent with them |
| PUT | /smtp | Stores them. password: null keeps the password in force; an empty string means none |
| DELETE | /smtp | Removes the stored set, so the environment applies again |
| POST | /smtp/test | Sends one message with the settings 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 |
| POST | /backup | Everything this service is configured with, as one JSON document, the authenticator apps excepted. See API keys and backup |
| POST | /restore | Puts one back, section by section, and reports each, naming the accounts that set their authenticator app up again |
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 |
Neither PUT /geoip nor POST /geoip/sync waits for the sync to finish, because a City database is
tens of megabytes. Follow it with syncing and lastSync on GET /geoip. A download larger than
256 MiB is stopped and the previous copy kept. The GeoIP address is checked again on every
connection, so the key never goes to a link-local or metadata address however the name resolves,
and the GeoIP calls follow no redirect.
Settings
Many of these are seeds: they are what a fresh installation starts with, and a value saved through the console or the API takes over from then on. There are two kinds, and they differ on purpose:
- The thresholds (ban time, find time, retries, chain, purge age): the saved values outrank the environment, so a restart never puts a ban time back to what a compose file said months ago.
- The GeoIP and mail settings: a stored set wins whether or not it works, and deleting it hands control back to the environment. A wrong stored set fails visibly on its page instead of being silently replaced by another.
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. Name the console's ui |
Api__ConsoleKeyName | ui, console | The configured key the console calls with, when it is named otherwise. Only that key may name a person's address for the audit log and the session list |
Api__TrustedProxies__<n> | - | A reverse proxy in front of the API, by address or network. Its forwarded address and scheme are believed, nobody else's, so the wrong-key limit and the audit log see the caller behind it. See A proxy that is not trusted |
Jails__LogRoots__<n> | the folders mounted into the container | The only folders a jail may read logs in. See Where a jail may read |
Fail2Ban__BanTimeSeconds | 3600 | How long a ban lasts. Seed |
Fail2Ban__FindTimeSeconds | 600 | The window failures are counted in. Seed |
Fail2Ban__MaxRetry | 5 | Failures inside the window that earn a ban. Seed |
Fail2Ban__Chain | DOCKER-USER | Where the ban rules go. INPUT for a service on the host itself. Seed |
Fail2Ban__DatabasePurgeAgeSeconds | 86400 | How long an expired ban stays in the database. Seed |
Fail2Ban__IptablesBackend | auto | auto, nft or legacy. See The firewall |
Fail2Ban__ConfigDir | /config | The service's database (jails, settings, issued keys, accounts, audit log), the ban database and the license. The settings files of earlier releases are imported on the first start and kept beside themselves as .imported |
FAIL2BAN_SEED_ADMIN_PASS | generated | The built-in administrator's password, applied when the account is made and whenever the value changes |
FAIL2BAN_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. A restore keeps it. An invalid value stops the API from starting |
Fail2Ban__SuperviseDaemon | true | False runs the API against a daemon it does not own |
License__Directory | /config/license | License files and check-in state |
Smtp__Host / Smtp__Port | - / 587 | The mail relay for notifications. Seed |
Smtp__Encryption | StartTls | StartTls, SslOnConnect or None. Seed |
Smtp__Username / Smtp__Password | - | Empty means an unauthenticated relay. Seed |
Smtp__FromAddress / Smtp__FromName | - / Antelao Fail2Ban | Who the notifications come from. Seed |
Smtp__Recipients | - | Who they go to, separated by commas, semicolons or spaces. Empty sends nothing. Seed |
Smtp__NotifyOnBan / Smtp__NotifyOnUnban | true / false | What is notified. Seed |
Smtp__DigestSeconds | 300 | How long events are collected before one message is sent. Seed |
GeoIp__BaseUrl / GeoIp__ApiKey | - | An optional Antelao GeoIP service, for the flags. Seed |
GeoIp__Mode | Cache | Cache or Service. Seed |
GeoIp__Editions | the three GeoLite2 files | What the mirror pulls, space-separated |
GeoIp__SyncIntervalHours | 12 | How often the mirror checks for a newer database |
GeoIp__AllowPrivateBaseUrl | true | Whether the GeoIP service may be on a loopback or private address, as it is on a host install. A link-local or cloud metadata address is refused either way |
The mail settings are named as this service reads them. Antelao GeoIP names three of them
differently (Smtp__Security, Smtp__UserName, Smtp__NotifyTo) and also needs 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 |
|---|---|---|
Fail2BanApi__BaseUrl / Fail2BanApi__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 The console behind a reverse proxy and 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 |