<!--startmeta
custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/integrations/db-ip_ip_intelligence.md"
meta_yaml: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/metadata.yaml"
sidebar_label: "DB-IP IP Intelligence"
learn_status: "Published"
learn_rel_path: "Network Flows/Enrichment Methods"
keywords: ['geoip', 'asn', 'dbip', 'db-ip', '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 -->

# DB-IP IP Intelligence


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


Plugin: netflow-plugin
Module: dbip

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

## Overview

Enrich network flows with ASN and geographic context from DB-IP Lite MMDB
databases. DB-IP IP Intelligence is the default IP intelligence source for the
Netdata netflow plugin: when neither `enrichment.geoip.asn_database` nor
`enrichment.geoip.geo_database` is configured, the plugin auto-detects the
DB-IP-built MMDB files at startup and uses them. Two MMDB files are involved:
an ASN database (`topology-ip-asn.mmdb`) and a geographic database
(`topology-ip-geo.mmdb`). Native packages (DEB, RPM) ship a stock copy under
`/usr/share/netdata/topology-ip-intel/`; the bundled refresh tool fetches updates
into `/var/cache/netdata/topology-ip-intel/`.

DB-IP publishes the Lite databases monthly under a Creative Commons Attribution 4.0
International licence (https://db-ip.com/db/lite.php). The MMDB format is the MaxMind
binary database; lookups are in-process with no per-flow network call.

Populates these flow record fields when a lookup succeeds:

- From the **geo MMDB**: `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`. Country and state survive into all four
  journal tiers; city, latitude, and longitude are kept only in the raw tier so the
  rollups stay cardinality-bounded.
- From the **ASN MMDB**: `SRC_AS_NAME`, `DST_AS_NAME`. The DB-IP-built ASN database also
  tags address ranges as private/reserved (RFC 1918, link-local, RFC 6598, etc.); when
  the resolved AS number is `0` and that flag is set, the plugin renders the AS name as
  `AS0 Private IP Address Space` instead of `AS0 Unknown ASN`. The AS *number* itself
  comes from the wider asn_providers chain, not directly from the MMDB.

For the cross-provider mechanics (lookup pass ordering, the 30-second hot-reload poll,
the auto-detect path order, multi-database composition, IPv4/IPv6 handling, the failure
modes shared by every MMDB provider), see
[IP Intelligence](https://learn.netdata.cloud/docs/network-flows/enrichment).


Files are read on plugin start and reloaded automatically when their mtime or size
changes. Auto-detection scans `${NETDATA_CACHE_DIR}/topology-ip-intel/` first
(typically `/var/cache/netdata/topology-ip-intel/`), falling back to the stock copy
under `${NETDATA_STOCK_DATA_DIR}/topology-ip-intel/` (typically
`/usr/share/netdata/topology-ip-intel/`). When databases are auto-detected they are
treated as optional, so a missing or unreadable file does not abort plugin startup.


This integration is only supported on the following platforms:

- Linux

This integration runs as a single instance per Netdata Agent.


### Default Behavior

#### Auto-Detection

Native packages ship the stock DB-IP MMDB files; the plugin auto-detects them at startup. No configuration required for the default install.

#### Limits

Lookup coverage and freshness depend on the DB-IP Lite files installed on disk. Native packages provide a stock copy; schedule the downloader if you need monthly refreshes.

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

#### DB-IP MMDB files

Native DEB / RPM packages ship the stock DB-IP MMDB files under
`/usr/share/netdata/topology-ip-intel/`. For source builds, or to get a fresher copy
than the one bundled with the package, run `topology-ip-intel-downloader` once when
the binary is available (packaged 32-bit installs do not include it) to populate
`/var/cache/netdata/topology-ip-intel/`:

```bash
sudo /usr/sbin/topology-ip-intel-downloader
```

See the [Enrichment Intel Downloader](https://learn.netdata.cloud/docs/network-flows/enrichment-intel-downloader)
page for downloader options and how to schedule periodic refreshes. DB-IP Lite
data is published monthly, so a monthly cron of the downloader is the right
cadence -- more frequent runs will not produce newer data.


#### Licence acknowledgement

DB-IP Lite databases are distributed under the Creative Commons Attribution 4.0
International licence (https://db-ip.com/db/lite.php). Attribution is required
when redistributing the data or derivative dashboards.



### Configuration

#### Options

Configure DB-IP under `enrichment.geoip` in `netflow.yaml`. Empty `asn_database`
and `geo_database` enable auto-detection.


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



| Option | Description | Default | Required |
|:-----|:------------|:--------|:---------:|
| enrichment.geoip.asn_database | List of MMDB paths providing AS data. Empty = auto-detect under cache/stock dirs. | [] (auto-detect) | no |
| enrichment.geoip.geo_database | List of MMDB paths providing geo data. Empty = auto-detect. | [] (auto-detect) | no |
| enrichment.geoip.optional | When true, missing or unreadable MMDBs are warnings, not fatal. Auto-detected files default to optional. | false (true when auto-detected) | 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

###### Default (auto-detect stock files)

Native package install. No explicit configuration; the plugin finds the stock or cache copy automatically.

```yaml
enrichment:
  geoip:
    asn_database: []
    geo_database: []
    optional: true

```
###### Explicit DB-IP paths

Override auto-detection by pointing to specific DB-IP MMDBs (for example, after running the downloader to a non-standard location).

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

```yaml
enrichment:
  geoip:
    asn_database:
      - /var/cache/netdata/topology-ip-intel/topology-ip-asn.mmdb
    geo_database:
      - /var/cache/netdata/topology-ip-intel/topology-ip-geo.mmdb
    optional: false

```
</details>



### Private IPs have empty GeoIP fields

GeoIP databases normally have no country, city, or coordinate entry for RFC 1918 /
private space. The DB-IP-built ASN database tags private ranges so `*_AS_NAME`
renders as `AS0 Private IP Address Space`, while geographic fields stay empty and
private addresses do not appear on maps. Declare your internal CIDRs under
`enrichment.networks` when you want internal labels -- see
[Static metadata](https://learn.netdata.cloud/docs/network-flows/enrichment).


### Stale databases

The plugin does not alert on staleness. Check file mtime:
`ls -la /var/cache/netdata/topology-ip-intel/`. DB-IP Lite is published monthly,
so a monthly cron of `/usr/sbin/topology-ip-intel-downloader` keeps you on the
upstream cadence when the downloader is installed; running it more often will not
produce fresher data.


### Map renders empty over a long time window

`SRC_GEO_CITY`, `DST_GEO_CITY`, `SRC_GEO_LATITUDE`, `DST_GEO_LATITUDE`,
`SRC_GEO_LONGITUDE`, and `DST_GEO_LONGITUDE` are stored only in the raw journal
tier; the 1-minute, 5-minute, and 1-hour rollups drop them to keep cardinality
bounded. A query that auto-falls back to a rollup tier therefore renders an empty
city map. Narrow the time range so the query fits the raw tier, or use the
country / state map (those survive into rollups).



