Logstash geoip Filter Plugin

The Logstash geoip filter resolves an IP address in a source field to geographic attributes (country, city, ASN, coordinates) using a MaxMind DB-format database. Logstash 7.13+ bundles GeoLite2-City and GeoLite2-ASN and auto-updates them every 30 days when started with xpack.geoip.downloader.enabled: true. Self-managed databases or paid GeoIP2 databases require setting database to a local .mmdb file path.

Syntax

filter {
  geoip {
    source        => "client_ip"
    target        => "geoip"
    database      => "/etc/logstash/GeoLite2-City.mmdb"
    fields        => [ "country_name", "city_name", "location" ]
    cache_size    => 1000
    tag_on_failure => [ "_geoip_lookup_failure" ]
  }
}

Since MaxMind's December 2019 license change, GeoLite2 downloads from MaxMind directly require a free license key. Logstash's auto-downloader handles licensing internally for the bundled GeoLite2-City and GeoLite2-ASN databases through Elastic's CDN; no MaxMind account is needed for the bundled path.

Parameters

Examples

Enrich web access logs with city-level data, keeping only the fields you actually visualize:

filter {
  geoip {
    source => "clientip"
    target => "geoip"
    fields => [ "country_name", "country_code2", "city_name", "location" ]
  }
}

Use a paid MaxMind GeoIP2-ISP database for ASN and ISP enrichment:

filter {
  geoip {
    source   => "[source][ip]"
    database => "/etc/logstash/GeoIP2-ISP.mmdb"
    target   => "[source][as]"
  }
}

Run two lookups in sequence to populate both city and ASN data:

filter {
  geoip {
    source                => "clientip"
    target                => "geoip"
    default_database_type => "City"
  }
  geoip {
    source                => "clientip"
    target                => "asn"
    default_database_type => "ASN"
  }
}

Common Issues

Private and reserved IP ranges (RFC 1918, loopback, link-local) are not in the database and produce a _geoip_lookup_failure tag. Filter or skip those addresses before the geoip stage to avoid noise:

filter {
  if [clientip] !~ "^(10\.|192\.168\.|172\.(1[6-9]|2[0-9]|3[01])\.|127\.|::1|fe80:)" {
    geoip { source => "clientip" }
  }
}

The bundled GeoLite2 databases are best-effort and lower accuracy than the paid GeoIP2 databases - city-level accuracy is roughly 60-80% within a 50 km radius. Do not use GeoLite2 for fraud detection or compliance.

The location field is returned as { "lat": ..., "lon": ... }, which matches Elasticsearch geo_point mapping. If the index template maps it differently, Elasticsearch silently drops it. Always pair geoip with an explicit mapping for the target index.

Performance Notes

The MaxMind reader keeps the entire database memory-mapped, so RAM usage is roughly the file size (50-100 MB for GeoLite2-City). The cache_size LRU sits on top of that and caches resolved IPs; raise it to 10000+ for web-scale traffic where the same IPs appear thousands of times per minute. Trimming fields to only what's used downstream cuts event size by 50-80% and is the single biggest throughput win.

Monitoring Logstash GeoIP Enrichment with Pulse

Pulse is the only tool built specifically for monitoring and optimizing Logstash pipelines. The geoip auto-downloader silently disables enrichment if Elastic's CDN is unreachable (air-gapped clusters, firewall changes, expired root certificates), and the failure mode is often "all events tagged _geoip_lookup_failure" rather than a clean error. Pulse tracks the rate of geoip failure tags per pipeline, validates that the bundled database is fresh, and alerts when enrichment regresses so you do not discover the gap in next quarter's security dashboard.

Frequently Asked Questions

Q: Does the Logstash geoip filter need a MaxMind license key?
A: For the bundled GeoLite2-City and GeoLite2-ASN databases shipped with Logstash 7.13+, no. Elastic ships these through its own CDN with licensing handled internally. To download GeoLite2 directly from MaxMind or use paid GeoIP2 databases, you need a free or paid MaxMind license key set up on the host.

Q: How often does the Logstash geoip database auto-update?
A: When xpack.geoip.downloader.enabled is true (default), Logstash checks for a new database every 24 hours and downloads it if a newer one is available. MaxMind ships new GeoLite2 builds weekly.

Q: What fields does the Logstash geoip filter add by default?
A: With GeoLite2-City and no fields override: ip, country_code2, country_code3, country_name, continent_code, region_name, region_code, city_name, postal_code, timezone, location (as geo_point), latitude, longitude. In ECS modes (ecs_compatibility => v8), names map to [geo][country_name], [geo][city_name], etc.

Q: Does the Logstash geoip filter support IPv6?
A: Yes, GeoLite2 and GeoIP2 City databases include IPv6 records. The filter resolves both v4 and v6 from the same source field.

Q: Why are some IP lookups tagged _geoip_lookup_failure?
A: The IP is either private/reserved (RFC 1918, CGNAT, loopback) or genuinely absent from the database. Pre-filter private ranges with a conditional, and accept that GeoLite2 misses some legitimate public IPs - the paid GeoIP2 databases have better coverage.

Q: Can I use a paid MaxMind database with the Logstash geoip filter?
A: Yes. Download the .mmdb file from MaxMind, place it on each Logstash host, and set database => "/path/to/GeoIP2-City.mmdb". The plugin auto-detects the database type from the file metadata.

Related Reading

• Logstash Grok Filter Plugin: extract IP addresses from raw log lines before enrichment.
• Logstash DNS Filter Plugin: reverse-DNS enrichment alongside geoip.
• Logstash CIDR Filter Plugin: tag events by network range, useful for skipping internal IPs.
• Logstash Date Filter Plugin: align event timestamps before geoip enrichment.
• Logstash Pipeline is Blocked Error: geoip is a common pipeline hotspot.