<!--startmeta
custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/integrations/ipip_country_database.md"
meta_yaml: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/metadata.yaml"
sidebar_label: "IPIP Country Database"
learn_status: "Published"
learn_rel_path: "Network Performance Monitoring/Network Flows/Enrichment Methods"
keywords: ['ipip', '17mon', 'geoip', 'country', 'ip intelligence', 'flow enrichment']
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE FLOWS' metadata.yaml FILE"
endmeta-->

<!-- markdownlint-disable-file -->

# IPIP Country Database


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


Plugin: netflow-plugin
Module: ipip

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

## 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](https://github.com/netdata/netdata/blob/master/docs/npm/network-flows/enrichment.md).


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 supported on all platforms.

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:

```bash
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.


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



| Option | Description | Default | Required |
|:-----|:------------|:--------|:---------:|
| enrichment.geoip.asn_database | Optional ASN MMDB paths supplied by another provider. | [] | no |
| enrichment.geoip.geo_database | Path to the IPIP-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 |


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

###### After running the downloader with IPtoASN ASN and IPIP country

Auto-detection picks up both generated cache files.

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

```
###### Explicit IPIP country path

Pin IPIP for country and keep a separate ASN source.

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



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