IPtoASN

Plugin: netflow-plugin Module: iptoasn

Overview

Enrich network flows with public ASN and country context from IPtoASN BGP-derived datasets. IPtoASN is a free, public-domain feed of IP-to-ASN mappings. The upstream publishes its dataset under the Public Domain Dedication and License (PDDL) (see 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 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.

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 with iso_code, autonomous_system_number, and autonomous_system_organization fields will also work with the Custom MMDB integration.

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 auto-detected as the default ASN source – the plugin auto-detects DB-IP MMDBs in the cache directory at startup (see IP Intelligence). 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:

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:

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

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

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

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.

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

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.

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

Metrics

Enriches flow records with AS numbers, AS names, and country codes; produces no metrics of its own. Verify on the Network Flows view via *_AS_NAME and *_COUNTRY columns.

Alerts

There are no alerts configured by default for this integration.

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