IP2Location LITE IP-Country

Plugin: netflow-plugin Module: ip2location

Overview

Enrich network flows with country codes from the IP2Location LITE IP-Country database. The supported downloader source is the DB1 LITE CSV ZIP (IP2LOCATION-LITE-DB1.CSV.ZIP), whose documented fields are ip_from, ip_to, country_code, and country_name.

IP2Location DB1 is country-only. It does not provide ASN, AS organization, state, city, latitude, or longitude. Pair it with CAIDA, IPtoASN, DB-IP, or MaxMind ASN data when you also need AS fields.

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 IP2Location LITE CSV ZIP, convert the ranges 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. No ASN, AS name, state, city, latitude, or longitude are available from this source.

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 IP2Location LITE 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 ip2location:country-lite

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

IP2Location LITE license

Review the IP2Location LITE terms before redistributing the data or generated derivative files. The plugin consumes only the generated MMDB and does not contact IP2Location during flow decoding.

Configuration

Options

Once the downloader has produced an IP2Location-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.

Config options

Option	Description	Default	Required
enrichment.geoip.asn_database	Optional ASN MMDB paths supplied by another provider.	[]	no
enrichment.geoip.geo_database	Path to the IP2Location-derived geo MMDB. Empty = auto-detect from the cache directory.	[]	no
enrichment.geoip.optional	When true, missing or unreadable MMDBs are warnings, not fatal at startup.	false (true when auto-detected)	no

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

Auto-detection picks up both generated cache files.

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

Explicit IP2Location country path

Pin IP2Location for country and keep a separate ASN source.

Config

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

ASN fields are empty

IP2Location DB1 is country-only. Configure --asn iptoasn:combined, --asn caida:prefix2as, or another ASN provider in the downloader.

City or coordinates are empty

The DB1 LITE source does not include city, state, latitude, or longitude. Use DB-IP city-lite, MaxMind GeoLite2 City, GeoIP2 City, or a custom MMDB when those fields are required.

Stale country data

Check the upstream IP2Location LITE page for the current version and next update date, then schedule the downloader accordingly. The plugin reloads the generated MMDB in place when the file signature changes.