GeoIP

Enrich Elastic Compatible

Synopsis

Enriches IP addresses with geographical and network information using MaxMind's GeoIP2 databases.

The processor supports both IPv4 and IPv6 addresses and can extract various location attributes including continent, country, city, coordinates, and autonomous system information.

Schema

geoip:
  - field: <ident>
  - database_file: <string>
  - description: <text>
  - first_only: <boolean>
  - if: <script>
  - ignore_failure: <boolean>
  - ignore_missing: <boolean>
  - on_failure: <processor[]>
  - on_success: <processor[]>
  - properties: <string[]>
  - tag: <string>
  - target_field: <ident>

Configuration

Field	Required	Default	Description
field	Y	-	Field containing the IP address to lookup
database_file	N	GeoLite2-City.mmdb	GeoIP database file to use. Supports City, Country and ASN databases
description	N	-	Documentation note
first_only	N	true	Process only first IP if multiple found
if	N	-	Conditional expression
ignore_failure	N	false	Skip processing errors
ignore_missing	N	false	Skip if input field missing
on_failure	N	-	Error handling processors
on_success	N	-	Success handling processors
properties	N	all	Properties to extract (see Properties section)
tag	N	-	Identifier for logging
target_field	N	geo/as	Output field for location data

Details

The processor can extract different properties depending on the database type used:

• City/Country databases

  continent_name	English name of the continent
  country_name	English name of the country
  country_iso_code	Two-letter country code
  region_name	English name of the region/state
  region_iso_code	Region/state code
  city_name	English name of the city
  location	Object containing latitude and longitude

• ASN databases

  asn	Autonomous System Number
  organization_name	Organization operating the AS

The processor supports three types of MaxMind databases:

• City Database (GeoLite2-City.mmdb) - Most detailed information. Includes all location properties, and default database if none specified

• Country Database (GeoLite2-Country.mmdb) - Country-level information only. Lighter weight than city database, although no city or region information

• ASN Database (GeoLite2-ASN.mmdb) - Network information only. Provides AS number and organization, although without location information

note

The GeoIP database files must be placed in the service's database directory or specified with absolute paths.

warning

The processor caches database handles for performance. Ensure sufficient memory is available when using large databases.

Examples

Basic

Looking up IP address location...	{ "ip": "2.125.160.218" } geoip: - field: ip - properties: - country_name - city_name
adds geographic information:	{ "ip": "2.125.160.218", "geo": { "country_name": "United Kingdom", "city_name": "Boxford" } }

ASN

Looking up network information...	{ "ip": "31.64.0.1" } geoip: - field: ip - database_file: GeoLite2-ASN.mmdb - properties: - asn - organization_name
adds network details:	{ "ip": "31.64.0.1", "as": { "number": 12576, "organization": { "name": "Orange Personal Communications Services" } } }

Full Location

Extracting all location information...	{ "source_ip": "2.125.160.218" } geoip: - field: source_ip - target_field: location - properties: - continent_name - country_name - country_iso_code - region_name - region_iso_code - city_name - location
provides comprehensive details:	{ "source_ip": "2.125.160.218", "location": { "continent_name": "Europe", "country_name": "United Kingdom", "country_iso_code": "GB", "region_name": "England", "region_iso_code": "ENG", "city_name": "Boxford", "location": { "lat": 51.7500, "lon": -1.2500 } } }

Error Handling

Handling invalid IPs gracefully...	{ "ip": "999.999.999.999" } geoip: - field: ip - ignore_failure: true - on_failure: - set: - field: error - value: "Invalid IP address"
captures the error information:	{ "ip": "999.999.999.999", "error": "Invalid IP address" }