The GeoIP console

Optional, on port 5413, 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 GEOIP_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 geoip 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.

Updating from a release with a single console password

The compose files take the old console password when GEOIP_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

GEOIP_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 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 databases, lookups
Operator	Everything a viewer may, and start a database refresh or a maintenance job, and record a session trace
Read-only administrator	See every page, the keys, mail settings, accounts and the audit log, and change nothing
Administrator	Everything, including 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 GEOIP_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	Database state, the last refresh, whether the service can reach MaxMind at all	Databases
Databases	The MaxMind account, which editions are kept, and a refresh you start by hand	Databases
Lookup	Ask about an address by hand, and see exactly what the databases hold	Lookups
API keys	The keys that may reach the service	API keys
Options	The rate limit, and the backup archive	API keys
SMTP	Where the one notification goes	below
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

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 MaxMind credential and the mail settings: what you set through the API takes the environment's place entirely and permanently, working or not. The service does not fall back to the environment's: a wrong credential fails on the databases page, in MaxMind's own words.
• The rate limit: also outranks the environment from then on, including across a restart. It is the one setting with a reset, which hands control back to the environment.

Notifications

The service mails exactly two messages: one when the scheduled refresh starts failing, and one when it works again.

A refresh that has stopped is easy to miss: every lookup still answers and the console still looks healthy while the answers go stale. Set a recipient, so the first failure reaches you.

Refreshes you start by hand are never reported, because you are already looking at the result.

Mail goes out only while Send mail is on, on the SMTP page (Smtp__Enabled in the environment, off by default). Leave Send to empty and nothing is sent of its own accord. The test button still works, because it goes to an address you typed.

Saving mail settings does not carry the environment's password across

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 GeoIP 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 database 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.

Related

• Databases and credentials
• Licensing