| 1 | <!--startmeta |
| 2 | custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/integrations/maxmind_geoip_-_geolite2.md" |
| 3 | meta_yaml: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/metadata.yaml" |
| 4 | sidebar_label: "MaxMind GeoIP / GeoLite2" |
| 5 | learn_status: "Published" |
| 6 | learn_rel_path: "Network Flows/Enrichment Methods" |
| 7 | keywords: ['maxmind', 'geoip2', 'geolite2', 'geoip', 'asn', 'mmdb', 'ip intelligence', 'flow enrichment'] |
| 8 | message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE FLOWS' metadata.yaml FILE" |
| 9 | endmeta--> |
| 10 | |
| 11 | <!-- markdownlint-disable-file --> |
| 12 | |
| 13 | # MaxMind GeoIP / GeoLite2 |
| 14 | |
| 15 | |
| 16 | <img src="https://netdata.cloud/img/network-wired.svg" width="150"/> |
| 17 | |
| 18 | |
| 19 | Plugin: netflow-plugin |
| 20 | Module: maxmind |
| 21 | |
| 22 | <img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" /> |
| 23 | |
| 24 | ## Overview |
| 25 | |
| 26 | Enrich network flows with ASN and geographic context from MaxMind GeoIP / |
| 27 | GeoLite2 MMDB databases. MaxMind is the originator of the MMDB binary format and |
| 28 | the canonical commercial source for geo and ASN data. The netflow plugin reads |
| 29 | MaxMind MMDB files directly; they are interchangeable with other MMDB providers |
| 30 | (DB-IP, custom builds). |
| 31 | |
| 32 | Two product lines are supported: |
| 33 | |
| 34 | - **GeoLite2** (free): requires a free MaxMind account and a license key; users |
| 35 | must accept the GeoLite2 EULA, which includes an attribution requirement. See |
| 36 | <https://dev.maxmind.com/geoip/geolite2-free-geolocation-data>. |
| 37 | - **GeoIP2** (commercial): paid subscription with the same license-key download |
| 38 | mechanism but higher accuracy and more frequent updates. See |
| 39 | <https://www.maxmind.com/en/geoip2-databases>. |
| 40 | |
| 41 | Each lookup populates the same flow-record fields as DB-IP: `SRC_COUNTRY`, |
| 42 | `DST_COUNTRY`, `SRC_GEO_STATE`, `DST_GEO_STATE`, `SRC_GEO_CITY`, `DST_GEO_CITY`, |
| 43 | `SRC_GEO_LATITUDE`, `DST_GEO_LATITUDE`, `SRC_GEO_LONGITUDE`, `DST_GEO_LONGITUDE`, |
| 44 | `SRC_AS_NAME`, and `DST_AS_NAME`. Country and state survive into all rollup tiers; |
| 45 | city and lat/lon are **raw-tier-only**. Rollup tiers keep only the |
| 46 | bounded-cardinality geography columns. |
| 47 | |
| 48 | For the cross-cutting concept (resolver poll loop, multi-database composition, |
| 49 | ASN provider chain, failure-modes table), see |
| 50 | [IP Intelligence](https://learn.netdata.cloud/docs/network-flows/enrichment). |
| 51 | |
| 52 | |
| 53 | You can use MaxMind in two ways: |
| 54 | |
| 55 | - Use `geoipupdate` (MaxMind's official downloader, configured with your account |
| 56 | ID + license key) or direct HTTPS download, then point `asn_database` and |
| 57 | `geo_database` at the resulting MaxMind MMDB files. |
| 58 | - Use Netdata's `topology-ip-intel-downloader` with `MAXMIND_LICENSE_KEY` in |
| 59 | the environment to fetch GeoLite2 ASN and GeoLite2 Country CSV sources and |
| 60 | generate the standard Netdata topology MMDB files. |
| 61 | |
| 62 | MaxMind requires authentication for all downloads -- there is no anonymous |
| 63 | access. Commercial GeoIP2 databases and richer GeoLite2 City files should still |
| 64 | be maintained with `geoipupdate` or direct paths when you want city and |
| 65 | coordinate enrichment. |
| 66 | |
| 67 | Once the files are on disk, point `asn_database` and `geo_database` at their |
| 68 | paths in `netflow.yaml`. The plugin reloads on file change automatically -- a |
| 69 | successful `geoipupdate` run causes the plugin to swap readers within ~30s, no |
| 70 | restart needed. |
| 71 | |
| 72 | |
| 73 | This integration is only supported on the following platforms: |
| 74 | |
| 75 | - Linux |
| 76 | |
| 77 | This integration runs as a single instance per Netdata Agent. |
| 78 | |
| 79 | |
| 80 | ### Default Behavior |
| 81 | |
| 82 | #### Auto-Detection |
| 83 | |
| 84 | 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. |
| 85 | |
| 86 | #### Limits |
| 87 | |
| 88 | 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. |
| 89 | |
| 90 | #### Performance Impact |
| 91 | |
| 92 | 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. |
| 93 | |
| 94 | ## Setup |
| 95 | |
| 96 | |
| 97 | ### Prerequisites |
| 98 | |
| 99 | #### MaxMind account and license key |
| 100 | |
| 101 | MaxMind does not allow anonymous downloads. Required for both GeoLite2 (free) |
| 102 | and GeoIP2 (paid): |
| 103 | |
| 104 | 1. Sign up at <https://www.maxmind.com/en/geolite2/signup> (GeoLite2) or |
| 105 | purchase a GeoIP2 subscription. |
| 106 | 2. Generate a license key under "Account > Manage License Keys". |
| 107 | 3. Note your account ID (visible on the same account page). |
| 108 | |
| 109 | |
| 110 | #### Install and configure geoipupdate |
| 111 | |
| 112 | `geoipupdate` is MaxMind's official downloader. Install it from your distro |
| 113 | (`apt install geoipupdate`, `dnf install geoipupdate`) or download from |
| 114 | <https://github.com/maxmind/geoipupdate/releases>. |
| 115 | |
| 116 | Edit `/etc/GeoIP.conf`: |
| 117 | |
| 118 | ```ini |
| 119 | AccountID YOUR_ACCOUNT_ID |
| 120 | LicenseKey YOUR_LICENSE_KEY |
| 121 | # GeoLite2 (free): |
| 122 | EditionIDs GeoLite2-City GeoLite2-ASN |
| 123 | # ...or for GeoIP2 (paid): |
| 124 | # EditionIDs GeoIP2-City GeoIP2-ISP |
| 125 | DatabaseDirectory /usr/share/GeoIP |
| 126 | ``` |
| 127 | |
| 128 | Run `sudo geoipupdate` to fetch initial files, then schedule it via cron or |
| 129 | the bundled `geoipupdate.timer` systemd unit. Recommended cadences match the |
| 130 | upstream publish frequency: |
| 131 | |
| 132 | - **GeoLite2 City / Country**: published twice weekly (Tuesday and Friday). |
| 133 | - **GeoLite2 ASN**: published every weekday (Mon-Fri). |
| 134 | - **GeoIP2 commercial editions**: published "every weekday, Monday through |
| 135 | Friday" per <https://www.maxmind.com/en/geoip2-databases>. |
| 136 | |
| 137 | Source: <https://support.maxmind.com/hc/en-us/articles/4408216129947>. |
| 138 | |
| 139 | |
| 140 | #### Optional Netdata topology downloader path |
| 141 | |
| 142 | To generate Netdata's auto-detected topology MMDB files from GeoLite2 ASN |
| 143 | and GeoLite2 Country, run: |
| 144 | |
| 145 | ```bash |
| 146 | sudo MAXMIND_LICENSE_KEY="YOUR_LICENSE_KEY" \ |
| 147 | /usr/sbin/topology-ip-intel-downloader \ |
| 148 | --asn maxmind:geolite2-asn \ |
| 149 | --geo maxmind:geolite2-country |
| 150 | ``` |
| 151 | |
| 152 | This produces `/var/cache/netdata/topology-ip-intel/topology-ip-asn.mmdb` |
| 153 | and `/var/cache/netdata/topology-ip-intel/topology-ip-geo.mmdb`. The |
| 154 | generated metadata redacts URL query strings; do not put the license key |
| 155 | directly in committed config files. |
| 156 | |
| 157 | |
| 158 | #### Single MMDB per database type (dual-stack) |
| 159 | |
| 160 | A single MaxMind MMDB file covers both IPv4 and IPv6 in one binary tree -- |
| 161 | you do **not** need separate IPv4 and IPv6 files. Point `asn_database` at one |
| 162 | file and `geo_database` at one file. (The CSV exports MaxMind also publishes |
| 163 | are split per family, but the netflow plugin only reads the binary MMDB |
| 164 | format.) |
| 165 | |
| 166 | |
| 167 | |
| 168 | ### Configuration |
| 169 | |
| 170 | #### Options |
| 171 | |
| 172 | Override the default DB-IP auto-detection by pointing `asn_database` and |
| 173 | `geo_database` at your MaxMind MMDB files. Both keys take a list -- you can |
| 174 | chain MaxMind alongside other MMDB sources; see the |
| 175 | [IP Intelligence](https://learn.netdata.cloud/docs/network-flows/enrichment) |
| 176 | page for the per-field "last non-empty wins" composition rule. |
| 177 | |
| 178 | |
| 179 | <details open><summary>Config options</summary> |
| 180 | |
| 181 | |
| 182 | |
| 183 | | Option | Description | Default | Required | |
| 184 | |:-----|:------------|:--------|:---------:| |
| 185 | | 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 | |
| 186 | | 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 | |
| 187 | | 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 | |
| 188 | |
| 189 | |
| 190 | </details> |
| 191 | |
| 192 | |
| 193 | |
| 194 | #### via File |
| 195 | |
| 196 | The configuration file name for this integration is `netflow.yaml`. |
| 197 | |
| 198 | |
| 199 | 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 |
| 200 | Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory). |
| 201 | |
| 202 | ```bash |
| 203 | cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata |
| 204 | sudo ./edit-config netflow.yaml |
| 205 | ``` |
| 206 | |
| 207 | ##### Examples |
| 208 | |
| 209 | ###### GeoLite2 (free tier) |
| 210 | |
| 211 | Standard `geoipupdate` install path. Free tier requires a MaxMind account and license key; usage is subject to the GeoLite2 EULA (attribution required). |
| 212 | |
| 213 | ```yaml |
| 214 | enrichment: |
| 215 | geoip: |
| 216 | asn_database: |
| 217 | - /usr/share/GeoIP/GeoLite2-ASN.mmdb |
| 218 | geo_database: |
| 219 | - /usr/share/GeoIP/GeoLite2-City.mmdb |
| 220 | optional: false |
| 221 | |
| 222 | ``` |
| 223 | ###### GeoIP2 (paid) |
| 224 | |
| 225 | Commercial subscription. Higher accuracy than GeoLite2 and a weekday update cadence on most editions. |
| 226 | |
| 227 | <details open><summary>Config</summary> |
| 228 | |
| 229 | ```yaml |
| 230 | enrichment: |
| 231 | geoip: |
| 232 | asn_database: |
| 233 | - /usr/share/GeoIP/GeoIP2-ISP.mmdb |
| 234 | geo_database: |
| 235 | - /usr/share/GeoIP/GeoIP2-City.mmdb |
| 236 | optional: false |
| 237 | |
| 238 | ``` |
| 239 | </details> |
| 240 | |
| 241 | ###### MaxMind ASN + DB-IP geo (mixed) |
| 242 | |
| 243 | 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://learn.netdata.cloud/docs/network-flows/enrichment) page. |
| 244 | |
| 245 | <details open><summary>Config</summary> |
| 246 | |
| 247 | ```yaml |
| 248 | enrichment: |
| 249 | geoip: |
| 250 | asn_database: |
| 251 | - /usr/share/GeoIP/GeoLite2-ASN.mmdb |
| 252 | geo_database: |
| 253 | - /var/cache/netdata/topology-ip-intel/topology-ip-geo.mmdb |
| 254 | optional: false |
| 255 | |
| 256 | ``` |
| 257 | </details> |
| 258 | |
| 259 | |
| 260 | |
| 261 | ### License key missing or expired |
| 262 | |
| 263 | `geoipupdate` fails (often silently from the plugin's perspective) and the |
| 264 | MMDB files become stale. Check the `geoipupdate` exit status and its log; |
| 265 | regenerate the key under "Account > Manage License Keys" if needed and |
| 266 | update `/etc/GeoIP.conf`. |
| 267 | |
| 268 | |
| 269 | ### GeoLite2 attribution requirement |
| 270 | |
| 271 | The GeoLite2 EULA requires attribution to MaxMind. If you redistribute |
| 272 | dashboards or screenshots that include GeoLite2-derived data, follow the |
| 273 | upstream guidance at <https://dev.maxmind.com/geoip/geolite2-free-geolocation-data>. |
| 274 | GeoIP2 (commercial) does not have the same attribution requirement. |
| 275 | |
| 276 | |
| 277 | ### Schema differences between GeoLite2 and GeoIP2 |
| 278 | |
| 279 | Both share the standard MMDB structure for the fields the plugin reads |
| 280 | (country, subdivisions, city, location, autonomous_system_number, |
| 281 | autonomous_system_organization). MaxMind's specialty databases (Anonymous IP, |
| 282 | Connection Type, Domain) carry GeoIP2-only fields the plugin does not consume. |
| 283 | Use `City` for geographic enrichment and `ASN` (GeoLite2) or `ISP` (GeoIP2) for |
| 284 | AS data. |
| 285 | |
| 286 | |
| 287 | ### Mixing MaxMind with the bundled DB-IP files |
| 288 | |
| 289 | The plugin loads every configured MMDB. If you list both, the per-field |
| 290 | "last non-empty wins" rule applies (see the |
| 291 | [IP Intelligence](https://learn.netdata.cloud/docs/network-flows/enrichment) |
| 292 | concept page). Order matters: list the source whose values you want to win |
| 293 | **last**. |
| 294 | |
| 295 | |
| 296 |