<!--startmeta
custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/integrations/iptoasn.md"
meta_yaml: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/metadata.yaml"
sidebar_label: "IPtoASN"
learn_status: "Published"
learn_rel_path: "Network Performance Monitoring/Network Flows/Enrichment Methods"
keywords: ['iptoasn', 'asn', 'bgp', 'public asn', 'public domain', 'pddl', 'ip intelligence']
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE FLOWS' metadata.yaml FILE"
endmeta-->

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

# IPtoASN


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


Plugin: netflow-plugin
Module: iptoasn

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

## Overview

Enrich network flows with public ASN and country context from IPtoASN
BGP-derived datasets. [IPtoASN](https://iptoasn.com/) is a free, public-domain
feed of IP-to-ASN mappings. The upstream publishes its dataset
under the [Public Domain Dedication and License (PDDL)](https://opendatacommons.org/licenses/pddl/)
(see [iptoasn.com](https://iptoasn.com/) -- "Frequently updated, public domain")
and rebuilds it hourly, making it the highest-cadence and lowest-friction public
ASN source available. Use it as a free, open alternative to MaxMind ASN data when
license cost or terms matter.

IPtoASN's `ip2asn-combined` artifact contains five tab-separated columns:
`range_start`, `range_end`, `AS_number`, `country_code`, and `AS_description`
(see [iptoasn.com](https://iptoasn.com/) for the format reference). So
although IPtoASN is often described as "ASN-only", the feed also carries an
ISO 3166 country code per range and the Netdata downloader exposes both as
ASN + geo MMDBs. Pair with DB-IP or MaxMind when you also need state, city,
or coordinates.

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 Netdata plugin reads MMDB only. IPtoASN ships gzipped TSV
(`https://iptoasn.com/data/ip2asn-combined.tsv.gz`), so the TSV must be
converted to MMDB before the plugin can use it.

When available, Netdata provides a converter for this exact purpose: the
`topology-ip-intel-downloader` Go tool fetches the upstream TSV, parses it,
and emits MMDB files the plugin auto-detects. This is
a separate operator step (cron); the plugin itself does no fetching or
conversion. Packaged 32-bit installs ship the stock MMDB payload but do not include
the downloader binary. If you prefer not to use the bundled tool, any third-party
IPtoASN-to-MMDB converter that produces a standard
[MaxMind DB](https://maxmind.github.io/MaxMind-DB/) with `iso_code`,
`autonomous_system_number`, and `autonomous_system_organization` fields
will also work with the Custom MMDB integration.


This integration is supported on all platforms.

This integration runs as a single instance per Netdata Agent.


### Default Behavior

#### Auto-Detection

Not auto-detected as the default ASN source -- the plugin auto-detects
DB-IP MMDBs in the cache directory at startup
(see [IP Intelligence](https://github.com/netdata/netdata/blob/master/docs/npm/network-flows/enrichment.md)).
To use IPtoASN, run `topology-ip-intel-downloader` when available to produce IPtoASN-derived
MMDBs (the downloader writes to the same cache paths the plugin scans,
so once present they are picked up automatically on the 30-second
file-signature check).


#### Limits

IPtoASN provides AS number and country-level data only. It does not provide city, coordinates, or rich organization names unless you layer another MMDB source.

#### Performance Impact

Lookups are local MMDB reads after the downloader converts the TSV feed. Memory use is mostly the mapped database files and the kernel page cache needed to keep active pages hot.

## Setup


### Prerequisites

#### Run the downloader with IPtoASN as ASN source

When available, the downloader knows how to fetch the upstream TSV and convert
it to MMDB. Packaged 32-bit installs do not include this binary:

```bash
sudo /usr/sbin/topology-ip-intel-downloader \
  --asn iptoasn:combined \
  --geo iptoasn:combined
```

`iptoasn:combined` is valid for both `--asn` and `--geo` because the
upstream TSV carries both AS data and country. If you
want richer geographic data (state, city, coordinates), pair IPtoASN
ASN with DB-IP or MaxMind geo:

```bash
sudo /usr/sbin/topology-ip-intel-downloader \
  --asn iptoasn:combined \
  --geo dbip:city-lite
```

IPtoASN rebuilds hourly upstream, but a daily cron is sufficient for
flow enrichment (ASN ownership rarely changes within a single day).
Do not exceed hourly -- you only get a fresh dataset once an hour
regardless.



### Configuration

#### Options

Once the downloader has produced IPtoASN-derived MMDB files in the cache
directory, the plugin auto-detects them. To pin the path explicitly, set
`enrichment.geoip.asn_database` (and `geo_database` when you also want
the country data IPtoASN provides).


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



| Option | Description | Default | Required |
|:-----|:------------|:--------|:---------:|
| enrichment.geoip.asn_database | Path to the IPtoASN-derived ASN MMDB. Empty = auto-detect from cache directory. | [] | no |
| enrichment.geoip.geo_database | Path to the IPtoASN-derived geo MMDB (country only). Empty = auto-detect; or point at a richer DB-IP / MaxMind geo MMDB for state/city/coordinates. | [] | 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

Auto-detection picks up the cache copy. Both ASN and country come from IPtoASN.

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

```
###### Explicit IPtoASN paths (ASN + country only)

Pin the IPtoASN-derived MMDBs explicitly. Country only -- no
state/city. Use the DB-IP or MaxMind integration cards for richer
geographic enrichment.


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

###### IPtoASN ASN + DB-IP city-lite geo

Free, fully public-domain ASN combined with DB-IP city-lite for
state/city/coordinates. Run the downloader as
`topology-ip-intel-downloader --asn iptoasn:combined --geo dbip:city-lite`
and let auto-detection handle the rest.


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

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

```
</details>



### ASN names not appearing

IPtoASN's `AS_description` column is sometimes empty for less-common
ASNs (the upstream derives names from RIRs and the chain occasionally
has gaps). When that happens the plugin renders the AS as `AS{n}` with
no organisation. This is data-source-level, not a plugin issue. If richer AS-name
coverage matters, layer a MaxMind GeoLite2-ASN MMDB after IPtoASN in
`asn_database` -- per-field "last database with a non-empty value
wins" composition (see
[IP Intelligence](https://github.com/netdata/netdata/blob/master/docs/npm/network-flows/enrichment.md))
means MaxMind names override IPtoASN's empty entries.


### Country empty although IPtoASN was selected

IPtoASN's combined TSV publishes country only when it is known. Public
IPs that the upstream cannot attribute will have an empty
`*_COUNTRY`. If you need broader country coverage, point
`geo_database` at a DB-IP or MaxMind country MMDB instead -- the
plugin reads any combination.


### Outdated ASN attribution

IPtoASN rebuilds hourly upstream. A daily cron of the downloader is
the recommended cadence for flow enrichment; weekly is too slow
because BGP-driven prefix re-assignments will land in the dataset
within hours but not in your cache until the next download. The
plugin reloads MMDB files in place every 30 seconds when the file
signature changes, so a fresh file lands without restart.
