openZro

Management Geolocation

Traditionally, openZro's management system has relied on Geolocation databases. In version 0.26.0, we introduced support for posture checks. From this version onwards, openZro uses the GeoLite2 City database from MaxMind to identify a peer's geographical location based on its IP address.

Even though we distribute the databases, MaxMind retains ownership. Please refer to the license agreement details on MaxMind's website for specifics.

This guide outlines the steps to configure Management with the GeoLite2 database

Downloading the databases

Upon openZro Application startup, our management checks if the GeoLite2 databases exist in its data directory. If not present, the databases will be downloaded from the openzro/geolocation-dbs mirror:

After downloading, the management system prepares the databases for use. If the databases already exist, the system will load and utilize the existing ones.

Bypassing the openZro mirror

Operators with stricter compliance requirements ("no third-party mirrors") can pass a MaxMind GeoLite2 license key, in which case the management server fetches the archives directly from download.maxmind.com and the openZro mirror is never contacted:

# Sign up for a free key at https://www.maxmind.com/en/geolite2/signup
openzro-mgmt --maxmind-license-key="$MAXMIND_LICENSE_KEY"

Or via the combined config file:

maxmindLicenseKey: "<your-key-here>"

Either path produces the same on-disk database; only the source endpoint differs.

Updating the GeoLite2 Database

The GeoLite2 databases are updated twice a week to reflect changes in geolocation data. It's crucial to keep your local GeoLite2 databases updated. When the management service is started, the service will query the Download URLs to check if the current database is outdated. If the database is outdated or does not exist, the files will be downloaded and loaded automatically. Restarting the management service will trigger the update check.

This behavior can be disabled by passing the --disable-geolite-update flag to the management command or by setting disableGeoliteUpdate: true in the combined configuration file:

disableGeoliteUpdate: true

When disabled, the service will download the geolite databases only if there is no file in the data directory. The database with the most recent date will be loaded if more than one exists. If a database does not exist, it will be downloaded and loaded, but it will not be updated on subsequent restarts of the management service.

Disabling geolocation entirely

The management binary disables geolocation by default when the GeoLite2 database isn't available locally and auto-update is turned off. There's no dedicated "disable" toggle — you opt out by not configuring the database. Two ways:

# Pass the flag (or its env equivalent OZ_DISABLE_GEOLITE_UPDATE=true):
openzro-mgmt --disable-geolite-update=true

Combined with no GeoLite2-City_*.mmdb staged in the management datadir, the daemon logs

geolocation service not initialized (running without geolocation support): ...

at startup and serves all subsequent geo posture-check API calls with empty results. The dashboard's geo posture-check modal shows a banner explaining the database isn't configured, so admins don't fall into the "empty dropdown" trap.

Troubleshooting: GeoLite2 download fails in restricted networks

In some network environments, the automatic download of the GeoLite2 database from github.com/openzro/geolocation-dbs may fail. This commonly happens when:

  • Corporate firewalls perform deep packet inspection (DPI), intercepting HTTPS traffic and re-signing certificates with internal certificate authorities. The management server cannot verify these intercepted certificates, causing TLS errors during the download.
  • Outbound access to github.com (or its release-asset CDN, objects.githubusercontent.com) is blocked by firewall rules or proxy restrictions.
  • The server has no internet access at all (air-gapped environments).

If you are affected, you can manually provide the GeoLite2 database file instead of relying on the automatic download:

  1. Disable automatic updates by passing the --disable-geolite-update flag or setting disableGeoliteUpdate: true in the config to prevent the server from attempting to download or overwrite the database.

  2. Download the GeoLite2 City database from MaxMind's GeoLite2 page. You will need a free MaxMind account to download the MMDB file.

  3. Place the file in the management data directory with the naming convention GeoLite2-City_YYYYMMDD.mmdb (e.g., GeoLite2-City_20260127.mmdb).

Locating the data directory

For Docker-based self-hosted deployments, the management data is stored in a Docker volume. You can find it at:

/var/lib/docker/volumes/openzro_data/_data/

The directory contents look something like this:

root@selfhosted-1:/var/lib/docker/volumes/openzro_data/_data# ls -l
total 72452
-rw-r--r-- 1 root root 63524357 Feb 13 23:00 GeoLite2-City_20260127.mmdb
-rw-r--r-- 1 root root   425984 Feb 17 19:31 events.db
-rw-r--r-- 1 root root  7307264 Feb 13 23:00 geonames_20260127.db
-rw-r--r-- 1 root root    98304 Feb 18 14:07 idp.db
-rw-r--r-- 1 root root  2826240 Feb 18 14:07 store.db

Copy your downloaded GeoLite2 MMDB file into this directory, then restart the management service. The server will detect and load the existing database file without attempting a download.