MaxMind GeoIP / GeoLite2

Plugin: netflow-plugin Module: maxmind

Overview

Enrich network flows with ASN and geographic context from MaxMind GeoIP / GeoLite2 MMDB databases. MaxMind is the originator of the MMDB binary format and the canonical commercial source for geo and ASN data. The netflow plugin reads MaxMind MMDB files directly; they are interchangeable with other MMDB providers (DB-IP, custom builds).

Two product lines are supported:

• GeoLite2 (free): requires a free MaxMind account and a license key; users must accept the GeoLite2 EULA, which includes an attribution requirement. See https://dev.maxmind.com/geoip/geolite2-free-geolocation-data.
• GeoIP2 (commercial): paid subscription with the same license-key download mechanism but higher accuracy and more frequent updates. See https://www.maxmind.com/en/geoip2-databases.

Each lookup populates the same flow-record fields as DB-IP: SRC_COUNTRY, DST_COUNTRY, SRC_GEO_STATE, DST_GEO_STATE, SRC_GEO_CITY, DST_GEO_CITY, SRC_GEO_LATITUDE, DST_GEO_LATITUDE, SRC_GEO_LONGITUDE, DST_GEO_LONGITUDE, SRC_AS_NAME, and DST_AS_NAME. Country and state survive into all rollup tiers; city and lat/lon are raw-tier-only. Rollup tiers keep only the bounded-cardinality geography columns.

For the cross-cutting concept (resolver poll loop, multi-database composition, ASN provider chain, failure-modes table), see IP Intelligence.

You can use MaxMind in two ways:

• Use geoipupdate (MaxMind's official downloader, configured with your account ID + license key) or direct HTTPS download, then point asn_database and geo_database at the resulting MaxMind MMDB files.
• Use Netdata's topology-ip-intel-downloader with MAXMIND_LICENSE_KEY in the environment to fetch GeoLite2 ASN and GeoLite2 Country CSV sources and generate the standard Netdata topology MMDB files.

MaxMind requires authentication for all downloads -- there is no anonymous access. Commercial GeoIP2 databases and richer GeoLite2 City files should still be maintained with geoipupdate or direct paths when you want city and coordinate enrichment.

Once the files are on disk, point asn_database and geo_database at their paths in netflow.yaml. The plugin reloads on file change automatically -- a successful geoipupdate run causes the plugin to swap readers within ~30s, no restart needed.

This integration is supported on all platforms.

This integration runs as a single instance per Netdata Agent.

Default Behavior

Auto-Detection

Arbitrary MaxMind paths are not auto-detected; configure enrichment.geoip.asn_database and enrichment.geoip.geo_database for those. MaxMind-derived topology MMDB files generated by topology-ip-intel-downloader are auto-detected because they use the standard Netdata cache paths.

Limits

Lookup coverage, fields, license terms, and refresh cadence depend on the MaxMind database edition you configure. The plugin itself does no network fetching; the downloader is an operator-run refresh step.

Performance Impact

Lookups are local MMDB reads with no per-flow network call. Memory use is mostly the mapped database files and the kernel page cache needed to keep active pages hot.

Setup

Prerequisites

MaxMind account and license key

MaxMind does not allow anonymous downloads. Required for both GeoLite2 (free) and GeoIP2 (paid):

1. Sign up at https://www.maxmind.com/en/geolite2/signup (GeoLite2) or purchase a GeoIP2 subscription.
2. Generate a license key under "Account > Manage License Keys".
3. Note your account ID (visible on the same account page).

Install and configure geoipupdate

geoipupdate is MaxMind's official downloader. Install it from your distro (apt install geoipupdate, dnf install geoipupdate) or download from https://github.com/maxmind/geoipupdate/releases.

Edit /etc/GeoIP.conf:

AccountID YOUR_ACCOUNT_ID
LicenseKey YOUR_LICENSE_KEY
# GeoLite2 (free):
EditionIDs GeoLite2-City GeoLite2-ASN
# ...or for GeoIP2 (paid):
# EditionIDs GeoIP2-City GeoIP2-ISP
DatabaseDirectory /usr/share/GeoIP

Run sudo geoipupdate to fetch initial files, then schedule it via cron or the bundled geoipupdate.timer systemd unit. Recommended cadences match the upstream publish frequency:

• GeoLite2 City / Country: published twice weekly (Tuesday and Friday).
• GeoLite2 ASN: published every weekday (Mon-Fri).
• GeoIP2 commercial editions: published "every weekday, Monday through Friday" per https://www.maxmind.com/en/geoip2-databases.

Source: https://support.maxmind.com/hc/en-us/articles/4408216129947.

Optional Netdata topology downloader path

To generate Netdata's auto-detected topology MMDB files from GeoLite2 ASN and GeoLite2 Country, run:

sudo MAXMIND_LICENSE_KEY="YOUR_LICENSE_KEY" \
  /usr/sbin/topology-ip-intel-downloader \
    --asn maxmind:geolite2-asn \
    --geo maxmind:geolite2-country

This produces /var/cache/netdata/topology-ip-intel/topology-ip-asn.mmdb and /var/cache/netdata/topology-ip-intel/topology-ip-geo.mmdb. The generated metadata redacts URL query strings; do not put the license key directly in committed config files.

Single MMDB per database type (dual-stack)

A single MaxMind MMDB file covers both IPv4 and IPv6 in one binary tree -- you do not need separate IPv4 and IPv6 files. Point asn_database at one file and geo_database at one file. (The CSV exports MaxMind also publishes are split per family, but the netflow plugin only reads the binary MMDB format.)

Configuration

Options

Override the default DB-IP auto-detection by pointing asn_database and geo_database at your MaxMind MMDB files. Both keys take a list -- you can chain MaxMind alongside other MMDB sources; see the IP Intelligence page for the per-field "last non-empty wins" composition rule.

via File

The configuration file name for this integration is netflow.yaml.

You can edit the configuration file using the edit-config script from the Netdata config directory.

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config netflow.yaml

Examples

GeoLite2 (free tier)

Standard geoipupdate install path. Free tier requires a MaxMind account and license key; usage is subject to the GeoLite2 EULA (attribution required).

enrichment:
  geoip:
    asn_database:
      - /usr/share/GeoIP/GeoLite2-ASN.mmdb
    geo_database:
      - /usr/share/GeoIP/GeoLite2-City.mmdb
    optional: false

GeoIP2 (paid)

Commercial subscription. Higher accuracy than GeoLite2 and a weekday update cadence on most editions.

enrichment:
  geoip:
    asn_database:
      - /usr/share/GeoIP/GeoIP2-ISP.mmdb
    geo_database:
      - /usr/share/GeoIP/GeoIP2-City.mmdb
    optional: false

MaxMind ASN + DB-IP geo (mixed)

Use MaxMind for ASN richness and keep the bundled DB-IP geo file. Both lookups run; the multi-DB composition rule is documented on the IP Intelligence page.

enrichment:
  geoip:
    asn_database:
      - /usr/share/GeoIP/GeoLite2-ASN.mmdb
    geo_database:
      - /var/cache/netdata/topology-ip-intel/topology-ip-geo.mmdb
    optional: false

License key missing or expired

geoipupdate fails (often silently from the plugin's perspective) and the MMDB files become stale. Check the geoipupdate exit status and its log; regenerate the key under "Account > Manage License Keys" if needed and update /etc/GeoIP.conf.

GeoLite2 attribution requirement

The GeoLite2 EULA requires attribution to MaxMind. If you redistribute dashboards or screenshots that include GeoLite2-derived data, follow the upstream guidance at https://dev.maxmind.com/geoip/geolite2-free-geolocation-data. GeoIP2 (commercial) does not have the same attribution requirement.

Schema differences between GeoLite2 and GeoIP2

Both share the standard MMDB structure for the fields the plugin reads (country, subdivisions, city, location, autonomous_system_number, autonomous_system_organization). MaxMind's specialty databases (Anonymous IP, Connection Type, Domain) carry GeoIP2-only fields the plugin does not consume. Use City for geographic enrichment and ASN (GeoLite2) or ISP (GeoIP2) for AS data.

Mixing MaxMind with the bundled DB-IP files

The plugin loads every configured MMDB. If you list both, the per-field "last non-empty wins" rule applies (see the IP Intelligence concept page). Order matters: list the source whose values you want to win last.