Docs
You are looking at preliminary documentation for a future release. Not what you want? See the current release documentation.
Elasticsearch Plugins and Integrations [master] » Ingest Plugins » Ingest Geoip Processor Plugin » Using the Geoip Processor in a Pipeline
«  Ingest Geoip Processor Plugin     Ingest user agent processor plugin  »

Using the Geoip Processor in a Pipelineedit

Table 2. Geoip options

Name Required Default Description

field

yes

-

The field to get the ip address from for the geographical lookup.

target_field

no

geoip

The field that will hold the geographical information looked up from the Maxmind database.

database_file

no

GeoLite2-City.mmdb

The database filename in the geoip config directory. The ingest-geoip plugin ships with the GeoLite2-City.mmdb, GeoLite2-Country.mmdb and GeoLite2-ASN.mmdb files.

properties

no

[continent_name, country_iso_code, region_name, city_name, location] *

Controls what properties are added to the target_field based on the geoip lookup.

ignore_missing

no

false

If true and field does not exist, the processor quietly exits without modifying the document


*Depends on what is available in database_field:

  • If the GeoLite2 City database is used, then the following fields may be added under the target_field: ip, country_iso_code, country_name, continent_name, region_name, city_name, timezone, latitude, longitude and location. The fields actually added depend on what has been found and which properties were configured in properties.
  • If the GeoLite2 Country database is used, then the following fields may be added under the target_field: ip, country_iso_code, country_name and continent_name. The fields actually added depend on what has been found and which properties were configured in properties.
  • If the GeoLite2 ASN database is used, then the following fields may be added under the target_field: ip, asn, and organization_name. The fields actually added depend on what has been found and which properties were configured in properties.

Here is an example that uses the default city database and adds the geographical information to the geoip field based on the ip field:

PUT _ingest/pipeline/geoip
{
  "description" : "Add geoip info",
  "processors" : [
    {
      "geoip" : {
        "field" : "ip"
      }
    }
  ]
}
PUT my_index/my_type/my_id?pipeline=geoip
{
  "ip": "8.8.8.8"
}
GET my_index/my_type/my_id

Which returns:

{
  "found": true,
  "_index": "my_index",
  "_type": "my_type",
  "_id": "my_id",
  "_version": 1,
  "_source": {
    "ip": "8.8.8.8",
    "geoip": {
      "continent_name": "North America",
      "country_iso_code": "US",
      "location": { "lat": 37.751, "lon": -97.822 }
    }
  }
}

Here is an example that uses the default country database and adds the geographical information to the geo field based on the ip field`. Note that this database is included in the plugin download. So this:

PUT _ingest/pipeline/geoip
{
  "description" : "Add geoip info",
  "processors" : [
    {
      "geoip" : {
        "field" : "ip",
        "target_field" : "geo",
        "database_file" : "GeoLite2-Country.mmdb"
      }
    }
  ]
}
PUT my_index/my_type/my_id?pipeline=geoip
{
  "ip": "8.8.8.8"
}
GET my_index/my_type/my_id

returns this:

{
  "found": true,
  "_index": "my_index",
  "_type": "my_type",
  "_id": "my_id",
  "_version": 1,
  "_source": {
    "ip": "8.8.8.8",
    "geo": {
      "continent_name": "North America",
      "country_iso_code": "US",
    }
  }
}

Not all IP addresses find geo information from the database, When this occurs, no target_field is inserted into the document.

Here is an example of what documents will be indexed as when information for "80.231.5.0" cannot be found:

PUT _ingest/pipeline/geoip
{
  "description" : "Add geoip info",
  "processors" : [
    {
      "geoip" : {
        "field" : "ip"
      }
    }
  ]
}
PUT my_index/my_type/my_id?pipeline=geoip
{
  "ip": "80.231.5.0"
}
GET my_index/my_type/my_id

Which returns:

{
  "found": true,
  "_index": "my_index",
  "_type": "my_type",
  "_id": "my_id",
  "_version": 1,
  "_source": {
    "ip": "80.231.5.0"
  }
}

Node Settingsedit

The geoip processor supports the following setting:

ingest.geoip.cache_size
The maximum number of results that should be cached. Defaults to 1000.

Note that these settings are node settings and apply to all geoip processors, i.e. there is one cache for all defined geoip processors.

«  Ingest Geoip Processor Plugin     Ingest user agent processor plugin  »