OpenSearch/docs/plugins/ingest-geoip.asciidoc

[[ingest-geoip]]
=== Ingest Geoip Processor Plugin

The GeoIP processor adds information about the geographical location of IP addresses, based on data from the Maxmind databases.
This processor adds this information by default under the `geoip` field. The `geoip` processor can resolve both IPv4 and
IPv6 addresses.

The ingest-geoip plugin ships by default with the GeoLite2 City and GeoLite2 Country geoip2 databases from Maxmind made available
under the CCA-ShareAlike 3.0 license. For more details see, http://dev.maxmind.com/geoip/geoip2/geolite2/

The GeoIP processor can run with other geoip2 databases from Maxmind. The files must be copied into the geoip config directory,
and the `database_file` option should be used to specify the filename of the custom database. Custom database files must be compressed
with gzip. The geoip config directory is located at `$ES_HOME/config/ingest/geoip` and holds the shipped databases too.

[[ingest-geoip-install]]
[float]
==== Installation

This plugin can be installed using the plugin manager:

[source,sh]
----------------------------------------------------------------
sudo bin/elasticsearch-plugin install ingest-geoip
----------------------------------------------------------------

The plugin must be installed on every node in the cluster, and each node must
be restarted after installation.

This plugin can be downloaded for <<plugin-management-custom-url,offline install>> from
{plugin_url}/ingest-geoip/{version}/ingest-geoip-{version}.zip.

[[ingest-geoip-remove]]
[float]
==== Removal

The plugin can be removed with the following command:

[source,sh]
----------------------------------------------------------------
sudo bin/elasticsearch-plugin remove ingest-geoip
----------------------------------------------------------------

The node must be stopped before removing the plugin.

[[using-ingest-geoip]]
==== Using the Geoip Processor in a Pipeline

[[ingest-geoip-options]]
.Geoip options
[options="header"]
|======
| 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.gz and GeoLite2-Country.mmdb.gz 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.
|======

*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`.

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

[source,js]
--------------------------------------------------
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
--------------------------------------------------
// CONSOLE

Which returns:

[source,js]
--------------------------------------------------
{
  "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",
      "region_name": "California",
      "city_name": "Mountain View",
      "location": { "lat": 37.386, "lon": -122.0838 }
    }
  }
}
--------------------------------------------------
// TESTRESPONSE

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:

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

returns this:

[source,js]
--------------------------------------------------
{
  "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",
    }
  }
}
--------------------------------------------------
// TESTRESPONSE


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 "93.114.45.13"
cannot be found:

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

Which returns:

[source,js]
--------------------------------------------------
{
  "found": true,
  "_index": "my_index",
  "_type": "my_type",
  "_id": "my_id",
  "_version": 1,
  "_source": {
    "ip": "93.114.45.13"
  }
}
--------------------------------------------------
// TESTRESPONSE