<!--startmeta
custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/integrations/maxmind_geoip_-_geolite2.md"
meta_yaml: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/metadata.yaml"
sidebar_label: "MaxMind GeoIP / GeoLite2"
learn_status: "Published"
learn_rel_path: "Network Performance Monitoring/Network Flows/Enrichment Methods"
keywords: ['maxmind', 'geoip2', 'geolite2', 'geoip', 'asn', 'mmdb', 'ip intelligence', 'flow enrichment']
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE FLOWS' metadata.yaml FILE"
endmeta-->

<!-- markdownlint-disable-file -->

# MaxMind GeoIP / GeoLite2


<img src="https://netdata.cloud/img/network-wired.svg" width="150"/>


Plugin: netflow-plugin
Module: maxmind

<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />

## 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](https://github.com/netdata/netdata/blob/master/docs/npm/network-flows/enrichment.md).


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

```ini
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:

```bash
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](https://github.com/netdata/netdata/blob/master/docs/npm/network-flows/enrichment.md)
page for the per-field "last non-empty wins" composition rule.


<details open><summary>Config options</summary>



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


</details>



#### via File

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


You can edit the configuration file using the [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#edit-configuration-files) script from the
Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory).

```bash
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).

```yaml
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.

<details open><summary>Config</summary>

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

```
</details>

###### 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](https://github.com/netdata/netdata/blob/master/docs/npm/network-flows/enrichment.md) page.

<details open><summary>Config</summary>

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

```
</details>



### 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](https://github.com/netdata/netdata/blob/master/docs/npm/network-flows/enrichment.md)
concept page). Order matters: list the source whose values you want to win
**last**.
