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

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

# IPDeny Country Zones


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


Plugin: netflow-plugin
Module: ipdeny

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

## Overview

Enrich network flows with country codes from IPDeny country zone files.
IPDeny publishes country-specific CIDR lists and an `all-zones.tar.gz`
archive. The Netdata downloader reads the IPv4 country-zone archive and maps
each `<country>.zone` member to that ISO country code.

IPDeny Country Zones are country-only and the current built-in source is IPv4
only. They do not provide ASN, AS organization, state, city, latitude, or
longitude. Pair IPDeny 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 IPDeny's HTTPS country-zone archive,
convert the CIDR lists 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 IPv4 source. No ASN, AS name, IPv6 coverage, state, city, latitude, or longitude are available from this built-in 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 IPDeny 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 ipdeny:country-zones
```

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


#### IPDeny usage policy

IPDeny publishes usage limits and copyright policy on its site. Review
those terms before mirroring, redistributing, or downloading more often
than needed.



### Configuration

#### Options

Once the downloader has produced an IPDeny-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 IPDeny-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 IPDeny country

Auto-detection picks up both generated cache files.

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

```
###### Explicit IPDeny country path

Pin IPDeny 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 current built-in IPDeny downloader source uses the IPv4
`all-zones.tar.gz` archive. Use DB-IP, MaxMind, IP2Location, or a custom
MMDB if IPv6 country enrichment is required.


### ASN fields are empty

IPDeny zone files carry country CIDRs only. Configure a separate ASN
provider in the downloader.


### Download blocked or rate-limited

Check IPDeny's usage limits and retry later. The plugin continues using the
last generated MMDB file until the downloader publishes a replacement.
