#geoip — MaxMind databases
The geoip group inspects and refreshes the MaxMind GeoLite2 databases the platform uses for country decisions. nginx reads the same files through its geoip2 module, the panel uses them for address labels, and the collector caches its lookups, so one download serves every consumer.
There are three commands:
aegis geoip status # which databases are present, and whereaegis geoip sources # every dataset that can be fetched, and its stateaegis geoip update # download and installA bare aegis geoip is an argparse error (exit 2); aegis geoip --help lists the commands.
#The files it manages
[geoip]dir = "/aegis/data/geoip"country_db = "/aegis/data/geoip/GeoLite2-Country.mmdb"city_db = "/aegis/data/geoip/GeoLite2-City.mmdb"asn_db = "/aegis/data/geoip/GeoLite2-ASN.mmdb"license_key = "…"The three *_db keys are the destinations: a download writes exactly those paths. dir is where the provider folders and the state.json record live. The country file is the one nginx needs; without it nginx renders no geoip2 block and its JSON log records "geoip_country":"-" instead of failing to start.
#Commands
#aegis geoip status
Print one line per edition — country, city, asn — with the configured path. The marker distinguishes a present file (✔) from a missing one (ℹ); the path is printed either way, so the command also answers "where would this file go?".
aegis geoip status| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments or options |
aegis geoip statusaegis geoip status | grep -v '^ℹ'✔ country: /aegis/data/geoip/GeoLite2-Country.mmdbℹ city: /aegis/data/geoip/GeoLite2-City.mmdbℹ asn: /aegis/data/geoip/GeoLite2-ASN.mmdbThe command always exits 0: a missing database is a state to report, not an error. aegis check looks at the same files from the other side: its geoip row counts the datasets on disk, the installed .mmdb files and the countries in the index, and names the command that fixes a gap.
#aegis geoip sources
Print every dataset that can be fetched with the current configuration, whether its file exists, how many bytes it has, when it was downloaded and which licence covers it. The list is not static: it depends on geoip.mirror and geoip.license_key.
aegis geoip sources| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments or options |
aegis geoip sourcesaegis geoip sources | column -tdataset provider file downloaded licence──────────────── ──────── ──────── ───────────────────────── ─────────────────────dbip-country dbip 9.8 MiB 2026-11-01T03:12:44+00:00 CC BY 4.0 (DB-IP)dbip-country-mmdb dbip missing - CC BY 4.0 (DB-IP)maxmind-country maxmind 61.2 MiB 2026-11-17T04:10:02+00:00 MaxMind GeoLite2 EULAmaxmind-city maxmind 142.7 MiB 2026-11-17T04:10:31+00:00 MaxMind GeoLite2 EULAmaxmind-asn maxmind 9.1 MiB 2026-11-17T04:10:40+00:00 MaxMind GeoLite2 EULAWhich rows appear:
| Condition | Datasets listed |
|---|---|
| always | dbip-country (the free CSV, republished monthly) |
| no mirror | dbip-country-mmdb |
| no mirror, key set | maxmind-country, maxmind-city, maxmind-asn |
geoip.mirror set | mirror-country, mirror-city, mirror-asn (and no MaxMind rows) |
The file column is the size of the downloaded file, or missing. The state comes from <geoip.dir>/state.json, which records one entry per dataset: provider, file, installed mmdb, URL without its query string, bytes, licence and downloaded_at.
#aegis geoip update
Download datasets and install the .mmdb they carry. By default it fetches GeoLite2-Country; --edition selects another edition and --source selects a dataset by the name aegis geoip sources prints.
aegis geoip update --edition <name> --source <dataset>| Option | Default | Meaning |
|---|---|---|
--edition | country | country, city or asn; repeatable |
--source | none | a dataset name such as maxmind-city; repeatable, takes precedence over --edition |
aegis geoip updateaegis geoip update --edition city --edition asnaegis geoip update --source dbip-country✔ country: /aegis/data/geoip/GeoLite2-Country.mmdb✔ city: /aegis/data/geoip/GeoLite2-City.mmdb✔ asn: /aegis/data/geoip/GeoLite2-ASN.mmdb--source and --edition are two modes, not two halves of one call: as soon as a --source is given, every source is downloaded and the editions are ignored.
aegis geoip update --source maxmind-country --source dbip-country✔ maxmind-country: /aegis/data/geoip/maxmind/GeoLite2-Country.tar.gz✔ dbip-country: /aegis/data/geoip/dbip/dbip-country-lite-2026-11.csv.gzOverwrites data. The installed database is replaced. The previous file is copied to
storage/backups/geoip/<edition>/first (the last two copies are kept), and the new one is written to a temporary path and renamed, so nginx never opens a half-written database and a bad download can be rolled back by putting a backup back.
#Errors and exit codes
Without a licence key, an edition download cannot start:
✖ geoip.license_key is not configuredA source is reported per dataset, and one failure does not stop the others; the command exits 1 when any of them failed:
✔ dbip-country: /aegis/data/geoip/dbip/dbip-country-lite-2026-11.csv.gz✖ mirror-city: GeoLite2-City.mmdb: checksum mismatch (expected 9f2c…, got 41ab…)A dataset the current configuration does not offer is refused:
✖ maxmind-city: unknown dataset: maxmind-cityThat is the answer when geoip.license_key is empty (MaxMind rows are only listed with a key) or when a mirror is configured (mirror rows replace them).
#How a file is installed
storage/temp/geoip; a source download is written straight to its provider folder (<geoip.dir>/<provider>/).
.mmdb inside it is extracted, when the dataset carries one.storage/backups/geoip/<edition>/..tmp file andrenamed over it, atomically.
state.json records the source, the installed path and the time.A mirror download is verified against the mirror's SHA256SUMS before step 3; a mismatch is a SourceError and nothing is replaced. Provider datasets are installed from their archive without a separate checksum step.
#Scheduled refresh
The keeper runs geoip-refresh every geoip.refresh_hours hours (12 by default, 0 disables the job). It downloads every dataset that can still change, skips the DB-IP CSV when the current month's file is already on disk, and rebuilds the country index from whatever arrived. A failed provider does not stop the others.
aegis keeper cronaegis keeper cron-run geoip-refresh| Argument | Default | Meaning |
|---|---|---|
name (of cron-run) | required | scheduled job name, for example geoip-refresh |
aegis keeper cronaegis keeper cron-run geoip-refreshjob every last run result───────────── ───── ─────────────────── ──────────────────────────────────────────────────────────geoip-refresh 12h 2026-11-17 04:10:02 5 datasets refreshed; 249 countries from DB-IP Lite, 284311 prefixesssl-renew 6h 2026-11-17 03:00:11 1 certificate renewed✔ geoip-refresh: 3 datasets refreshed; 249 countries from DB-IP Lite, 284311 prefixesA run with nothing new answers:
✔ geoip-refresh: datasets are current#Configuration
| Key | Default | Meaning |
|---|---|---|
geoip.dir | storage/data/geoip | root of every downloaded file |
geoip.country_db | — | installed country database, read by nginx |
geoip.city_db | — | installed city database |
geoip.asn_db | — | installed ASN database |
geoip.license_key | "" | MaxMind licence key; without it only free datasets exist |
geoip.account_id | "" | MaxMind account id, used by the panel's geoipupdate |
geoip.mirror | "" | base URL of a GeoIP mirror; replaces the MaxMind rows |
geoip.refresh_hours | 12 | refresh interval; 0 disables the job |
The paths above are the ones aegis geoip status prints. Keys are optional but country_db is what makes nginx's geoip2 block exist at all; set it before the first aegis cubes nginx configure.
#After an update
aegis geoip statusaegis cubes nginx configure # re-render the geoip2 block if the file changedaegis cubes nginx reloadnginx opens the database when it renders the block, so a replaced file is picked up by the next configure-and-reload, not by the download itself. A missing country database is not an nginx failure: the block is simply not rendered.