| 1 | <!--startmeta |
| 2 | custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/integrations/iptoasn.md" |
| 3 | meta_yaml: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/metadata.yaml" |
| 4 | sidebar_label: "IPtoASN" |
| 5 | learn_status: "Published" |
| 6 | learn_rel_path: "Network Flows/Enrichment Methods" |
| 7 | keywords: ['iptoasn', 'asn', 'bgp', 'public asn', 'public domain', 'pddl', 'ip intelligence'] |
| 8 | message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE FLOWS' metadata.yaml FILE" |
| 9 | endmeta--> |
| 10 | |
| 11 | <!-- markdownlint-disable-file --> |
| 12 | |
| 13 | # IPtoASN |
| 14 | |
| 15 | |
| 16 | <img src="https://netdata.cloud/img/network-wired.svg" width="150"/> |
| 17 | |
| 18 | |
| 19 | Plugin: netflow-plugin |
| 20 | Module: iptoasn |
| 21 | |
| 22 | <img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" /> |
| 23 | |
| 24 | ## Overview |
| 25 | |
| 26 | Enrich network flows with public ASN and country context from IPtoASN |
| 27 | BGP-derived datasets. [IPtoASN](https://iptoasn.com/) is a free, public-domain |
| 28 | feed of IP-to-ASN mappings. The upstream publishes its dataset |
| 29 | under the [Public Domain Dedication and License (PDDL)](https://opendatacommons.org/licenses/pddl/) |
| 30 | (see [iptoasn.com](https://iptoasn.com/) -- "Frequently updated, public domain") |
| 31 | and rebuilds it hourly, making it the highest-cadence and lowest-friction public |
| 32 | ASN source available. Use it as a free, open alternative to MaxMind ASN data when |
| 33 | license cost or terms matter. |
| 34 | |
| 35 | IPtoASN's `ip2asn-combined` artifact contains five tab-separated columns: |
| 36 | `range_start`, `range_end`, `AS_number`, `country_code`, and `AS_description` |
| 37 | (see [iptoasn.com](https://iptoasn.com/) for the format reference). So |
| 38 | although IPtoASN is often described as "ASN-only", the feed also carries an |
| 39 | ISO 3166 country code per range and the Netdata downloader exposes both as |
| 40 | ASN + geo MMDBs. Pair with DB-IP or MaxMind when you also need state, city, |
| 41 | or coordinates. |
| 42 | |
| 43 | For the IP-intelligence mechanism (lookup order, MMDB composition, refresh, |
| 44 | provider chains), see |
| 45 | [IP Intelligence](https://learn.netdata.cloud/docs/network-flows/enrichment). |
| 46 | |
| 47 | |
| 48 | The Netdata plugin reads MMDB only. IPtoASN ships gzipped TSV |
| 49 | (`https://iptoasn.com/data/ip2asn-combined.tsv.gz`), so the TSV must be |
| 50 | converted to MMDB before the plugin can use it. |
| 51 | |
| 52 | When available, Netdata provides a converter for this exact purpose: the |
| 53 | `topology-ip-intel-downloader` Go tool fetches the upstream TSV, parses it, |
| 54 | and emits MMDB files the plugin auto-detects. This is |
| 55 | a separate operator step (cron); the plugin itself does no fetching or |
| 56 | conversion. Packaged 32-bit installs ship the stock MMDB payload but do not include |
| 57 | the downloader binary. If you prefer not to use the bundled tool, any third-party |
| 58 | IPtoASN-to-MMDB converter that produces a standard |
| 59 | [MaxMind DB](https://maxmind.github.io/MaxMind-DB/) with `iso_code`, |
| 60 | `autonomous_system_number`, and `autonomous_system_organization` fields |
| 61 | will also work with the Custom MMDB integration. |
| 62 | |
| 63 | |
| 64 | This integration is only supported on the following platforms: |
| 65 | |
| 66 | - Linux |
| 67 | |
| 68 | This integration runs as a single instance per Netdata Agent. |
| 69 | |
| 70 | |
| 71 | ### Default Behavior |
| 72 | |
| 73 | #### Auto-Detection |
| 74 | |
| 75 | Not auto-detected as the default ASN source -- the plugin auto-detects |
| 76 | DB-IP MMDBs in the cache directory at startup |
| 77 | (see [IP Intelligence](https://learn.netdata.cloud/docs/network-flows/enrichment)). |
| 78 | To use IPtoASN, run `topology-ip-intel-downloader` when available to produce IPtoASN-derived |
| 79 | MMDBs (the downloader writes to the same cache paths the plugin scans, |
| 80 | so once present they are picked up automatically on the 30-second |
| 81 | file-signature check). |
| 82 | |
| 83 | |
| 84 | #### Limits |
| 85 | |
| 86 | 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. |
| 87 | |
| 88 | #### Performance Impact |
| 89 | |
| 90 | 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. |
| 91 | |
| 92 | ## Setup |
| 93 | |
| 94 | |
| 95 | ### Prerequisites |
| 96 | |
| 97 | #### Run the downloader with IPtoASN as ASN source |
| 98 | |
| 99 | When available, the downloader knows how to fetch the upstream TSV and convert |
| 100 | it to MMDB. Packaged 32-bit installs do not include this binary: |
| 101 | |
| 102 | ```bash |
| 103 | sudo /usr/sbin/topology-ip-intel-downloader \ |
| 104 | --asn iptoasn:combined \ |
| 105 | --geo iptoasn:combined |
| 106 | ``` |
| 107 | |
| 108 | `iptoasn:combined` is valid for both `--asn` and `--geo` because the |
| 109 | upstream TSV carries both AS data and country. If you |
| 110 | want richer geographic data (state, city, coordinates), pair IPtoASN |
| 111 | ASN with DB-IP or MaxMind geo: |
| 112 | |
| 113 | ```bash |
| 114 | sudo /usr/sbin/topology-ip-intel-downloader \ |
| 115 | --asn iptoasn:combined \ |
| 116 | --geo dbip:city-lite |
| 117 | ``` |
| 118 | |
| 119 | IPtoASN rebuilds hourly upstream, but a daily cron is sufficient for |
| 120 | flow enrichment (ASN ownership rarely changes within a single day). |
| 121 | Do not exceed hourly -- you only get a fresh dataset once an hour |
| 122 | regardless. |
| 123 | |
| 124 | |
| 125 | |
| 126 | ### Configuration |
| 127 | |
| 128 | #### Options |
| 129 | |
| 130 | Once the downloader has produced IPtoASN-derived MMDB files in the cache |
| 131 | directory, the plugin auto-detects them. To pin the path explicitly, set |
| 132 | `enrichment.geoip.asn_database` (and `geo_database` when you also want |
| 133 | the country data IPtoASN provides). |
| 134 | |
| 135 | |
| 136 | <details open><summary>Config options</summary> |
| 137 | |
| 138 | |
| 139 | |
| 140 | | Option | Description | Default | Required | |
| 141 | |:-----|:------------|:--------|:---------:| |
| 142 | | enrichment.geoip.asn_database | Path to the IPtoASN-derived ASN MMDB. Empty = auto-detect from cache directory. | [] | no | |
| 143 | | 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 | |
| 144 | | enrichment.geoip.optional | When true, missing or unreadable MMDBs are warnings, not fatal at startup. | false (true when auto-detected) | no | |
| 145 | |
| 146 | |
| 147 | </details> |
| 148 | |
| 149 | |
| 150 | |
| 151 | #### via File |
| 152 | |
| 153 | The configuration file name for this integration is `netflow.yaml`. |
| 154 | |
| 155 | |
| 156 | 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 |
| 157 | Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory). |
| 158 | |
| 159 | ```bash |
| 160 | cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata |
| 161 | sudo ./edit-config netflow.yaml |
| 162 | ``` |
| 163 | |
| 164 | ##### Examples |
| 165 | |
| 166 | ###### After running the downloader with IPtoASN |
| 167 | |
| 168 | Auto-detection picks up the cache copy. Both ASN and country come from IPtoASN. |
| 169 | |
| 170 | ```yaml |
| 171 | enrichment: |
| 172 | geoip: |
| 173 | asn_database: [] |
| 174 | geo_database: [] |
| 175 | optional: true |
| 176 | |
| 177 | ``` |
| 178 | ###### Explicit IPtoASN paths (ASN + country only) |
| 179 | |
| 180 | Pin the IPtoASN-derived MMDBs explicitly. Country only -- no |
| 181 | state/city. Use the DB-IP or MaxMind integration cards for richer |
| 182 | geographic enrichment. |
| 183 | |
| 184 | |
| 185 | <details open><summary>Config</summary> |
| 186 | |
| 187 | ```yaml |
| 188 | enrichment: |
| 189 | geoip: |
| 190 | asn_database: |
| 191 | - /var/cache/netdata/topology-ip-intel/topology-ip-asn.mmdb |
| 192 | geo_database: |
| 193 | - /var/cache/netdata/topology-ip-intel/topology-ip-geo.mmdb |
| 194 | optional: false |
| 195 | |
| 196 | ``` |
| 197 | </details> |
| 198 | |
| 199 | ###### IPtoASN ASN + DB-IP city-lite geo |
| 200 | |
| 201 | Free, fully public-domain ASN combined with DB-IP city-lite for |
| 202 | state/city/coordinates. Run the downloader as |
| 203 | `topology-ip-intel-downloader --asn iptoasn:combined --geo dbip:city-lite` |
| 204 | and let auto-detection handle the rest. |
| 205 | |
| 206 | |
| 207 | <details open><summary>Config</summary> |
| 208 | |
| 209 | ```yaml |
| 210 | enrichment: |
| 211 | geoip: |
| 212 | asn_database: [] |
| 213 | geo_database: [] |
| 214 | optional: true |
| 215 | |
| 216 | ``` |
| 217 | </details> |
| 218 | |
| 219 | |
| 220 | |
| 221 | ### ASN names not appearing |
| 222 | |
| 223 | IPtoASN's `AS_description` column is sometimes empty for less-common |
| 224 | ASNs (the upstream derives names from RIRs and the chain occasionally |
| 225 | has gaps). When that happens the plugin renders the AS as `AS{n}` with |
| 226 | no organisation. This is data-source-level, not a plugin issue. If richer AS-name |
| 227 | coverage matters, layer a MaxMind GeoLite2-ASN MMDB after IPtoASN in |
| 228 | `asn_database` -- per-field "last database with a non-empty value |
| 229 | wins" composition (see |
| 230 | [IP Intelligence](https://learn.netdata.cloud/docs/network-flows/enrichment)) |
| 231 | means MaxMind names override IPtoASN's empty entries. |
| 232 | |
| 233 | |
| 234 | ### Country empty although IPtoASN was selected |
| 235 | |
| 236 | IPtoASN's combined TSV publishes country only when it is known. Public |
| 237 | IPs that the upstream cannot attribute will have an empty |
| 238 | `*_COUNTRY`. If you need broader country coverage, point |
| 239 | `geo_database` at a DB-IP or MaxMind country MMDB instead -- the |
| 240 | plugin reads any combination. |
| 241 | |
| 242 | |
| 243 | ### Outdated ASN attribution |
| 244 | |
| 245 | IPtoASN rebuilds hourly upstream. A daily cron of the downloader is |
| 246 | the recommended cadence for flow enrichment; weekly is too slow |
| 247 | because BGP-driven prefix re-assignments will land in the dataset |
| 248 | within hours but not in your cache until the next download. The |
| 249 | plugin reloads MMDB files in place every 30 seconds when the file |
| 250 | signature changes, so a fresh file lands without restart. |
| 251 | |
| 252 | |
| 253 |