The Fail2Ban console

Optional, on port 5423, and shipped as a separate image behind a compose profile.

Accounts

Everyone signs in with their own user name and password. The accounts are kept by the API, in the service's database, so they survive a console that is replaced and travel with a backup.

The built-in administrator

The first account is admin. Its password is FAIL2BAN_SEED_ADMIN_PASS on the API container:

• It is applied when the account is made, and again whenever the value changes. That is the way back in for an administrator who has forgotten the password or locked the account: change the value, restart the API, and sign in with the new one. Every session of the account ends with it.
• Leave it unset and the API generates a password on its first start and writes it to a file only its own user can read. Read it with sudo docker compose exec fail2ban cat /config/first-admin-password. The file goes as soon as the password is changed, and the password never enters the log.
• The account cannot be deleted, demoted or disabled, so there is always one way in. Like every account, it keeps its user name: user names cannot be changed.

Updating from a release with a single console password

The compose files take the old console password when FAIL2BAN_SEED_ADMIN_PASS is not set, so after the update you sign in as admin with the password you already had. Every session ends with the update.

A required authenticator app

FAIL2BAN_SEED_ADMIN_TOTP on the API container, optional, gives admin an authenticator app that the account cannot switch off:

• The value is the app's secret in base32, at least 26 characters; case, spaces, dashes and = padding are ignored. Generate one with openssl rand 20 | base32 and enter it in the authenticator app as a setup key.
• It is applied on the first start and whenever the value changes, and a restore keeps it. Two-factor is then on and required for admin: the password is followed by a code from the app, recovery codes made for an earlier secret stop working, and every session of the account ends.
• A required authenticator app cannot be switched off on My account nor taken away on Users; it changes through the variable. New recovery codes can still be made on My account.
• An invalid value stops the API from starting, and its log names the variable, never the value.
• Emptied, the authenticator app stays on but is no longer required, so it can be switched off again on My account.
• Treat it as a password: anyone who holds it can produce the codes.

Roles

Role	What it may do
Viewer	Read the day-to-day pages: the dashboard, the jails, the bans, the logs
Operator	Everything a viewer may, and ban, unban, restart or reload the daemon, sync the GeoIP mirror and run a maintenance job
Read-only administrator	See every page, the keys, mail settings, accounts and the audit log, and change nothing
Administrator	Everything, including jails, options, accounts, keys, settings, backup and restore

The role is enforced by the API on every call, not by hiding buttons: the console sends the signed-in session with each request, and the API refuses what the role does not allow. A refused action says so, and is written to the audit log.

An API key alone keeps full access. Programs that call the API - the Odoo Host Manager, or your own scripts - use a key and need no account.

Signing in

• Password: at least twelve characters. Five wrong passwords in a row lock the account for fifteen minutes; only somebody who then types the right password is told it is locked. Apart from that, one address may make twenty sign-in attempts in five minutes, and the rest are refused for a few minutes.
• Authenticator app: set up on My account > Security. Once it is on, a password is followed by a six-digit code. Ten recovery codes are shown once when it is set up; each works once, for the day the phone is lost. An app the service's configuration requires, as the built-in administrator's can be, is shown as required and cannot be switched off.
• Passkeys: sign in with a fingerprint, face or device PIN instead of a password, added on My account > Security. A passkey works only over HTTPS, so put a reverse proxy with a certificate in front of the console before relying on one.

A sign-in lasts Ui__SessionHours (twelve hours by default), and ends sooner when it goes unused for two hours. An account keeps at most ten sessions; signing in an eleventh time ends the oldest. My account > Security lists your sessions, and ends any of them.

When a session ends while a page is open - signed out everywhere, a password or role changed, the account disabled, two hours unused - the page goes to the sign-in page and says the session has ended; signing in again brings you back where you were.

The account pages

Page	Who sees it	What it is
My account	Everyone	Profile (display name, e-mail), Interface (theme, compact rows, time zone, date format, clock, start page, list defaults) and Security (password, authenticator app, passkeys, sessions)
Users	Administrators, and read-only administrators without changing anything	Add an account, change its role, disable it, set a new password, take its authenticator app away, sign it out everywhere, delete it
Audit log	Administrators and read-only administrators	Every sign-in, every refusal and every change, with who made it, from which address, and when. Kept for a year

An authenticator app required by the service's configuration cannot be switched off on My account nor taken away on Users; it changes through FAIL2BAN_SEED_ADMIN_TOTP.

Your interface preferences, lists and saved views belong to your account, so they follow you to any browser.

The pages

Page	What it decides	Covered in
Dashboard	The daemon's version, uptime and restarts, and how much is actually being enforced	Bans
Jails	Every stored jail and its definition	Jails
Bans	The bans in force, with the log lines that earned them	Bans
Logs	The daemon's own log	Bans
Options	The global options every jail inherits	Jails
GeoIP	Where banned addresses are, and how that answer is fetched	below
API keys	The keys that may reach the service	API keys
Backup	The archive of everything it keeps	API keys
SMTP	Where notifications go	Bans
License	The edition this service runs at	Licensing
Users	The accounts and their roles	Accounts
Audit log	Who signed in and who changed what	Accounts

Flags on the ban list

Point this service at an Antelao GeoIP service (see Related) and every banned address gains the flag of where it is. Without one they are drawn plainly - no flag, and no error.

Flags need no license.

There are two ways to get that answer, and the GeoIP page chooses between them:

Mode	What it does	What it costs
Cache (default)	Mirrors the GeoIP service's GeoLite2 files onto this volume and reads them in process	Answers are as fresh as the last sync. GeoLite2 is published twice a week
Service	Asks the GeoIP service once per address	A round trip per address, and no answers while it is down

Neither mode falls back to the other

The mode chosen is the mode that runs: when the mirror cannot answer, Cache does not ask the service instead.

A sync is a poll, not a download: GET /status on the GeoIP service carries every edition's SHA-256, so a run that finds nothing new is one small response and no bytes. What does get downloaded is verified against that digest before it replaces anything, and the replacement is atomic.

GeoLite2-Country is all a flag needs. An unlicensed GeoIP service serves no database at all, so every edition comes back refused; that is recorded against the edition on the page rather than treated as a failed sync. Flags simply stop appearing, and nothing else here depends on them.

The console holds no GeoIP address, key or database of its own: the settings are set here and stored by the API. Settings saved here replace the environment's entirely, whether or not they work, until they are removed: a wrong address fails visibly on this page rather than being quietly replaced by another. Saving without a key keeps the key already in force.

Saving and Sync now start the sync and return straight away; the page shows its progress.

What every Antelao console has

The Fail2Ban console is the same console as the others, so it carries the same shared pages:

Page	What it is
Maintenance	The scheduled work, with the GeoIP mirror sync as one of its jobs
Support	Session traces: see Recording what you did
Release notes	What changed in the build this service runs

Every console also shares the way it is driven:

• A search box on every page, which finds menu pages by name and opens from anywhere with Ctrl+K or /
• Lists behave like lists: sorting, filtering, a column picker, paging, copy and export, on the service's own tables as much as anywhere else
• The Release notes page has a filter and a release picker, so a change can be found by its words rather than by scrolling
• A tab strip shows a chevron at whichever end still has tabs behind it, so a strip that does not fit says so
• The console's own name sits under Antelao at the top of the menu, which is how you tell identical-looking consoles apart

The License page names the deciding document behind the status it shows, including why a check-in receipt was set aside. That is the page to open when a service insists it is unlicensed and you believe otherwise.

Your preferences - the sidebar, the appearance, the dashboard, every list - are kept against your account in this service.

Related

• Jails
• Bans
• Antelao GeoIP, in the GeoIP manual