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 download the MaxMind MMDB files yourself using geoipupdate (MaxMind's official downloader, configured with your account ID + license key) or via direct HTTPS download with the same credentials. MaxMind requires authentication for all downloads -- there is no anonymous access. The bundled topology-ip-intel-downloader shipped by Netdata does not know how to fetch MaxMind databases (it supports DB-IP and IPtoASN only); use geoipupdate and schedule it via cron or systemd-timer.

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 only supported on the following platforms:

• Linux

This integration runs as a single instance per Netdata Agent.

Default Behavior

Auto-Detection

Not auto-detected. The plugin auto-detects the bundled DB-IP files; to use MaxMind you must configure the database paths explicitly. Set enrichment.geoip.asn_database and enrichment.geoip.geo_database to the MaxMind file paths.

Limits

Lookup coverage, fields, license terms, and refresh cadence depend on the MaxMind database edition you configure. Netdata does not fetch MaxMind databases automatically.

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.

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.

Config options

Option	Description	Default	Required
enrichment.geoip.asn_database	Paths to MaxMind ASN MMDB files (typically GeoLite2-ASN.mmdb for the free tier or GeoIP2-ISP.mmdb for the paid tier; the dual-stack file covers IPv4 and IPv6).	[]	yes
enrichment.geoip.geo_database	Paths to MaxMind geographic MMDB files (typically GeoLite2-City.mmdb for the free tier or GeoIP2-City.mmdb for the paid tier; the dual-stack file covers IPv4 and IPv6).	[]	yes
enrichment.geoip.optional	When true, missing or unreadable MMDBs are warnings, not fatal at startup. Useful while geoipupdate is being set up for the first time.	false	no

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.

Config

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.

Config

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.