The Blocklist console
Optional, on port 5443, 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 BLOCKLIST_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 blocklist cat /data/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.
A required authenticator app
BLOCKLIST_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 withopenssl rand 20 | base32and enter it in the authenticator app as a setup key. - It is applied on the first start and whenever the value changes, and again after a restore. 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 Blocklists page with its entries and lists, the Maintenance page and the jobs |
| Operator | Everything a viewer may, and add and remove your own entries and the lists' exceptions, and record a session trace |
| Read-only administrator | See every page, the keys, the firewall rules and its log, threat protection, the mail settings, the accounts and the audit log, and change nothing |
| Administrator | Everything, including refreshing a public list by hand, its schedule, the firewall, threat protection, 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 BLOCKLIST_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 | How many checks were answered each day and how many of them were listed, which lists answered them, the license and the API keys at a glance | The dashboard |
| Blocklists | Your own entries and the lists' exceptions, and a card per public list with its source, terms, credit and state | Lists and entries |
| Maintenance | Each public list's scheduled refresh: on or off, when, and a run you start by hand | Schedules |
| Jobs | Every change and every refresh, who asked for it and how it ended | Every change is a job |
| API keys | The keys that may reach the service | API keys |
| SMTP | Where the service's mail goes | |
| Options | The rate limit of the checks, and the backup archive | Rate limits, Backup and restore |
| License | What the license covers, list by list | Licensing |
| Users | The accounts and their roles | Accounts |
| Audit log | Who signed in and who changed what | Accounts |
| Security > Firewall | Who may reach the console, the management API and the checks | Firewall |
| Security > Threat protection | Who is banned for failing too often, and the settings that decide it | Threat protection |
| Support | Session traces: what you did, recorded for a bug report | Recording what you did |
| Release notes | What changed in the build this service runs | Release notes |
The Users, Audit log and Security pages are offered to administrators and read-only administrators only.
The dashboard
The cards can be added, removed and reordered with Customize, and the layout is kept with your account.
- Checks: the checks answered over the last days and how many of them were listed, with a line per day.
- Hits per list: how often each source listed what it was asked about - Your own entries, or a public list by its name.
- License and API keys: the license in force and how many keys can call the service.
The service keeps counts only: how many checks a day, and how many hits per list. The
addresses, domains and IPs that were checked are never stored. The counts behind the cards are
GET /api/v1/dashboard?days=7 (or 30, or 90).
While the service runs without a license, the dashboard says so at the top: every card can look healthy while no public list is in use.
Every page names where a setting came from
A setting can come from the container's environment or from the API, and each page says which it is showing.
- The mail settings: what you save on the SMTP page takes the environment's place entirely
and permanently, working or not. The service does not fall back to the environment's.
DELETE /smtpremoves the saved set and hands control back to the environment. - The rate limit: also outranks the environment from then on, including across a restart. Reset to the environment on the Options page hands control back.
- Threat protection's settings: what the page saves is laid over the deployment's, and a reset hands them back. See Threat protection.
Mail
Mail goes out only while Send mail is on, on the SMTP page (Smtp__Enabled in the
environment, off by default). The service mails:
- A ban by threat protection, one message per automatic ban, and a daily summary of the bans, sent with the first ban after a day has passed. Who receives them, and which of them are sent, is set on the Threat protection page; see Threat protection.
- One message the first time a proxy on loopback forwards without being trusted; see A proxy that is not trusted.
Leave Send to empty and nothing goes to that list of recipients. The test button still works, because it goes to an address you typed, and it uses the settings already in force rather than what is typed on the page: save first, then test.
Saving without a password means there is none. A password omitted on a later save keeps the one saved before, which is what lets you correct a host name without retyping a secret the API never returns.
What every Antelao console has
The Blocklist console is the same console as the others, so it carries the same shared pages:
| Page | What it is |
|---|---|
| Maintenance | The scheduled work, with each public list's refresh 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.