DB-IP IP Intelligence

Plugin: netflow-plugin Module: dbip

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.

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

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

See the 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.

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

Default (auto-detect stock files)

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

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

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

Metrics

IP intelligence enriches existing flow records; it does not produce metrics of its own. Verify enrichment is working by querying SRC_COUNTRY / DST_COUNTRY on the Network Flows view and confirming non-empty values for public IPs.

Alerts

There are no alerts configured by default for this integration.

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.

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