Aegis documentation

#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:

bash
aegis geoip status     # which databases are present, and whereaegis geoip sources    # every dataset that can be fetched, and its stateaegis geoip update     # download and install

A bare aegis geoip is an argparse error (exit 2); aegis geoip --help lists the commands.

#The files it manages

toml
[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?".

bash
aegis geoip status
Argument / optionDefaultMeaning
——none; the command takes no arguments or options
bash
aegis geoip statusaegis geoip status | grep -v '^ℹ'
text
✔ country: /aegis/data/geoip/GeoLite2-Country.mmdbℹ city: /aegis/data/geoip/GeoLite2-City.mmdbℹ asn: /aegis/data/geoip/GeoLite2-ASN.mmdb

The 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.

bash
aegis geoip sources
Argument / optionDefaultMeaning
——none; the command takes no arguments or options
bash
aegis geoip sourcesaegis geoip sources | column -t
text
dataset           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 EULA

Which rows appear:

ConditionDatasets listed
alwaysdbip-country (the free CSV, republished monthly)
no mirrordbip-country-mmdb
no mirror, key setmaxmind-country, maxmind-city, maxmind-asn
geoip.mirror setmirror-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.

bash
aegis geoip update --edition <name> --source <dataset>
OptionDefaultMeaning
--editioncountrycountry, city or asn; repeatable
--sourcenonea dataset name such as maxmind-city; repeatable, takes precedence over --edition
bash
aegis geoip updateaegis geoip update --edition city --edition asnaegis geoip update --source dbip-country
text
✔ country: /aegis/data/geoip/GeoLite2-Country.mmdb
text
✔ 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.

bash
aegis geoip update --source maxmind-country --source dbip-country
text
✔ maxmind-country: /aegis/data/geoip/maxmind/GeoLite2-Country.tar.gz✔ dbip-country: /aegis/data/geoip/dbip/dbip-country-lite-2026-11.csv.gz

Overwrites 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:

text
✖ geoip.license_key is not configured

A source is reported per dataset, and one failure does not stop the others; the command exits 1 when any of them failed:

text
✔ 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:

text
✖ maxmind-city: unknown dataset: maxmind-city

That 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

  • The payload is downloaded. Edition downloads go through
  • storage/temp/geoip; a source download is written straight to its provider folder (<geoip.dir>/<provider>/).

  • The single .mmdb inside it is extracted, when the dataset carries one.
  • The existing destination is copied to storage/backups/geoip/<edition>/.
  • The new database is written next to the destination as a .tmp file and
  • renamed 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.

    bash
    aegis keeper cronaegis keeper cron-run geoip-refresh
    ArgumentDefaultMeaning
    name (of cron-run)requiredscheduled job name, for example geoip-refresh
    bash
    aegis keeper cronaegis keeper cron-run geoip-refresh
    text
    job            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
    text
    ✔ geoip-refresh: 3 datasets refreshed; 249 countries from DB-IP Lite, 284311 prefixes

    A run with nothing new answers:

    text
    ✔ geoip-refresh: datasets are current

    #Configuration

    KeyDefaultMeaning
    geoip.dirstorage/data/geoiproot 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_hours12refresh 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

    bash
    aegis geoip statusaegis cubes nginx configure     # re-render the geoip2 block if the file changedaegis cubes nginx reload

    nginx 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.