Skip to main content

MaxMind GeoIP Integration

The MaxMind GeoIP integration enables geographic IP lookups and Autonomous System Number (ASN) enrichment for all NetFlow, sFlow, and VPC flow data collected by Chompy. Once configured, every flow record is automatically enriched with source and destination country, continent, ASN number, and organization name — powering geographic dashboards, country-based filtering, and AS-level traffic analysis.

Overview​

Chompy uses the MaxMind GeoLite2 free-tier databases to perform IP-to-location and IP-to-ASN resolution. The integration downloads two CSV datasets from MaxMind and loads them into ClickHouse dictionaries, which are used at insert time to enrich flow records via materialized columns. This means enrichment happens automatically for all flow sources (NetFlow, sFlow, AWS VPC Flow Logs) without any additional configuration per data source.

Enriched fields added to flow records:

FieldDescription
src_country / dst_countryISO country code (e.g., US, DE, JP)
src_country_name / dst_country_nameFull country name
src_asn / dst_asnAutonomous System Number
src_as_org / dst_as_orgAS organization name (e.g., GOOGLE, AMAZON-02)
No Data Without Configuration

Until MaxMind credentials are configured, all geographic and ASN fields will display as Unknown or 0. The warning banner "ASN and GeoIP data not available" will appear on the Integrations settings page.

Prerequisites​

You need a free MaxMind account to obtain API credentials. No paid subscription is required — the GeoLite2 free-tier databases are sufficient.

  1. Visit https://www.maxmind.com/en/geolite2/signup and create a free account.
  2. After confirming your email and logging in, navigate to Account > Manage License Keys.
  3. Click Generate New License Key. Choose "No" when asked about GeoIP Update — Chompy handles updates internally.
  4. Copy your Account ID (visible on your account page) and the License Key (shown only once at generation time).

Configuration​

Navigate to Settings → Integrations → MaxMind GeoIP to access the configuration panel.

Account ID​

Your numeric MaxMind Account ID. This is displayed on your MaxMind account dashboard and is typically a 6-digit number. Enter this value in the Account ID field.

License Key​

The license key generated from your MaxMind account portal. License keys are only displayed once when created, so if you've lost yours, generate a new one from the MaxMind portal. The key is stored encrypted in the Chompy database using AES-256-CBC encryption. The field includes a visibility toggle (eye icon) to show or hide the key value.

Enable Automatic Weekly Updates​

When checked, Chompy will automatically download fresh GeoLite2 databases once per week. MaxMind updates their GeoLite2 databases on Tuesdays, so enabling this option ensures your geographic and ASN data stays current without manual intervention. IP address allocations and ASN assignments change over time, so periodic updates are recommended for production deployments.

Actions​

The integration panel provides three action buttons:

Save​

Saves the Account ID and License Key to the database. The license key is encrypted before storage. Saving credentials does not automatically download the databases — use Sync Now after saving to perform the initial data load.

Test​

Validates that the entered credentials are accepted by MaxMind's download API. The test performs a lightweight HEAD request against the MaxMind download endpoint and confirms authentication succeeds. Use this to verify your credentials before attempting a full sync. Common failure reasons include an incorrect license key, a deactivated account, or a key that hasn't been fully activated yet (MaxMind keys can take a few minutes to become active after generation).

Sync Now​

Downloads the GeoLite2 ASN and GeoLite2 Country CSV databases from MaxMind, extracts them, and loads the data into ClickHouse. The sync process performs the following steps:

  1. Downloads GeoLite2-ASN-CSV and GeoLite2-Country-CSV ZIP archives from MaxMind's permalink API.
  2. Extracts the CSV files from each archive.
  3. Truncates and reloads the ClickHouse tables: geoip_asn_blocks, geoip_country_blocks, and geoip_locations.
  4. Reloads the ClickHouse IP_TRIE and HASHED dictionaries so new flow records are enriched with the updated data.

The initial sync may take 30–60 seconds depending on network speed. Subsequent syncs replace all existing data. Existing flow records are not retroactively re-enriched — only new flows arriving after the sync will use the updated database. Historical flows retain whatever GeoIP/ASN data was current at the time they were ingested.

Troubleshooting​

"ASN and GeoIP data not available" warning​

This message appears when no MaxMind credentials have been saved. Enter your Account ID and License Key, click Save, then click Sync Now.

Test succeeds but Sync fails​

Verify that the Chompy backend has outbound HTTPS access to download.maxmind.com. The test only performs a HEAD request, while the sync downloads ~15 MB of data. Also check that ClickHouse is running and accessible from the backend service.

Geographic data shows "Unknown" for some IPs​

Private/RFC1918 addresses (10.x.x.x, 172.16-31.x.x, 192.168.x.x) will always show as "Unknown" since they have no public geographic mapping. Some very recently allocated IP ranges may also not yet appear in the GeoLite2 database — enabling weekly updates helps minimize these gaps.

Stale geographic data​

If you notice IPs resolving to incorrect countries or ASNs, your databases may be outdated. Click Sync Now to pull the latest data, or enable automatic weekly updates to keep them current.