IPIP Country Database

Plugin: netflow-plugin Module: ipip

Overview

Enrich network flows with country codes from IPIP’s country database. The supported downloader source fetches IPIP’s country.zip archive and reads the country.txt file, where each line maps a prefix to a country token.

IPIP Country is country-only. The current country.zip source validated during this work contained IPv4 prefixes only. It does not provide ASN, AS organization, state, city, latitude, or longitude. Pair IPIP with another ASN source when you also need AS fields, and use DB-IP, MaxMind, IP2Location, or a custom MMDB when IPv6 country coverage is required.

For the IP-intelligence mechanism (lookup order, MMDB composition, refresh, provider chains), see IP Intelligence.

The netflow plugin reads MMDB files only. Use Netdata’s topology-ip-intel-downloader to fetch the IPIP country ZIP, convert the prefix list to topology-ip-geo.mmdb, and write the file into the standard auto-detected cache directory. The plugin reloads the generated MMDB automatically when the file changes.

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 used by the default install. After the downloader writes topology-ip-geo.mmdb into the standard cache path, the plugin auto-detects the generated file.

Limits

Country-only source. The currently validated country.zip payload is IPv4-only and carries no ASN, AS name, state, city, latitude, or longitude.

Performance Impact

Lookups are local MMDB reads after conversion. Memory use is mostly the mapped database file and the kernel page cache needed to keep active pages hot.

Setup

Prerequisites

Downloader with IPIP support

Run the bundled downloader when available. Packaged 32-bit installs do not include this binary:

sudo /usr/sbin/topology-ip-intel-downloader \
  --asn iptoasn:combined \
  --geo ipip:country

ipip:country is valid only for --geo. The example pairs it with IPtoASN so the resulting cache contains both AS and country fields.

IPIP data terms

Review IPIP’s current terms before redistributing the data or generated derivative files. The plugin consumes only the generated MMDB and does not contact IPIP during flow decoding.

Configuration

Options

Once the downloader has produced an IPIP-derived geo MMDB in the cache directory, the plugin auto-detects it. To pin paths explicitly, set enrichment.geoip.geo_database and keep asn_database pointed at your chosen ASN provider.

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

After running the downloader with IPtoASN ASN and IPIP country

Auto-detection picks up both generated cache files.

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

Explicit IPIP country path

Pin IPIP for country and keep a separate ASN source.

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

Enriches flow records with country codes; produces no metrics of its own. Verify on the Network Flows view via SRC_COUNTRY and DST_COUNTRY.

Alerts

There are no alerts configured by default for this integration.

IPv6 country fields are empty

The currently validated IPIP country.zip source contains IPv4 prefixes. Use DB-IP, MaxMind, IP2Location, or a custom MMDB if IPv6 country enrichment is required.

ASN fields are empty

IPIP country data carries country prefixes only. Configure a separate ASN provider in the downloader.

City or coordinates are empty

The supported IPIP source is country-only. Use DB-IP city-lite, MaxMind GeoLite2 City, GeoIP2 City, or a custom MMDB for richer geo fields.