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

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

# IP2Location LITE IP-Country


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


Plugin: netflow-plugin
Module: ip2location

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

## 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](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 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 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. 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:

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


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


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

Auto-detection picks up both generated cache files.

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

```
###### Explicit IP2Location country path

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



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