› › ›

Процессор GeoIP

Процессор geoip добавляет информацию о географическом расположении IPv4 или IPv6 адреса. Он совместим с базами данных геолокации IP GeoIP2 и GeoLite2, доступными от MaxMind.

По умолчанию процессор использует базы данных геолокации IP GeoLite2 City, GeoLite2 Country и GeoLite2 ASN от MaxMind, распространяемые под лицензией CC BY-SA 4.0. Он автоматически загружает эти базы данных, если узлы могут подключиться к домену storage.googleapis.com и при выполнении одного из следующих условий:

ingest.geoip.downloader.eager.download имеет значение true
в вашем кластере есть хотя бы один трубопровод с процессором geoip или ip_location

Elasticsearch автоматически загружает обновления этих баз данных с помощью конечной точки Elastic GeoIP: https://geoip.elastic.co/v1/database. Для получения статистики загрузок этих обновлений используйте API статистики GeoIP.

Если ваш кластер не может подключиться к конечной точке Elastic GeoIP или вы хотите управлять своими обновлениями, см. Управление собственными обновлениями базы данных геолокации IP.

Если вы хотите, чтобы Elasticsearch загружал файлы баз данных напрямую из MaxMind с помощью своего лицензионного ключа, см. API создания или обновления конфигурации базы данных геолокации IP.

Если Elasticsearch не может подключиться к конечной точке в течение 30 дней, все обновленные базы данных станут недействительными. Elasticsearch перестанет обогащать документы данными о местоположении IP и добавит поле tags: ["_geoip_expired_database"] вместо него.

Использование процессора `geoip` в конвейере

Таблица 22. Опции geoip

Имя	Обязательно	По умолчанию	Описание
`field`	да	-	Поле для получения IP-адреса для геолокационного поиска.
`target_field`	нет	geoip	Поле, которое будет содержать геолокационную информацию, полученную из базы данных.
`database_file`	нет	GeoLite2-City.mmdb	Имя файла базы данных, относящееся к одной из автоматически загруженных баз данных GeoLite2 (GeoLite2-City.mmdb, GeoLite2-Country.mmdb или GeoLite2-ASN.mmdb), или имя поддерживаемого файла базы данных в каталоге конфигурации `ingest-geoip`, или имя настроенной базы данных (с добавленным `.mmdb` расширением).
`properties`	нет	[`continent_name`, `country_iso_code`, `country_name`, `region_iso_code`, `region_name`, `city_name`, `location`] *	Управляет тем, какие свойства добавляются к `target_field` на основе геолокационного поиска IP.
`ignore_missing`	нет	`false`	Если `true` и `field` не существуют, процессор тихо завершается, не изменяя документ.
`first_only`	нет	`true`	Если `true` найдёт только первую геолокационную информацию IP, то она будет возвращена, даже если `field` содержит массив.
`download_database_on_pipeline_creation`	нет	`true`	Если `true` (и если `ingest.geoip.downloader.eager.download` равно `false`), отсутствующая база данных загружается при создании конвейера. В противном случае загрузка запускается при использовании конвейера как `default_pipeline` или `final_pipeline` в индексе.

*Зависит от того, что доступно в database_file:

Если используется база данных GeoLite2 City или GeoIP2 City, то следующие поля могут быть добавлены под target_field: ip, country_iso_code, country_name, country_in_european_union, registered_country_iso_code, registered_country_name, registered_country_in_european_union, continent_code, continent_name, region_iso_code, region_name, city_name, postal_code, timezone, location и accuracy_radius. Фактически добавленные поля зависят от того, что найдено и какие свойства были настроены в properties.
Если используется база данных GeoLite2 Country или GeoIP2 Country, то следующие поля могут быть добавлены под target_field: ip, country_iso_code, country_name, country_in_european_union, registered_country_iso_code, registered_country_name, registered_country_in_european_union, continent_code и continent_name. Фактически добавленные поля зависят от того, что найдено и какие свойства были настроены в properties.
Если используется база данных GeoLite2 ASN, то следующие поля могут быть добавлены под target_field: ip, asn, organization_name и network. Фактически добавленные поля зависят от того, что найдено и какие свойства были настроены в properties.
Если используется база данных GeoIP2 Anonymous IP, то следующие поля могут быть добавлены под target_field: ip, hosting_provider, tor_exit_node, anonymous_vpn, anonymous, public_proxy и residential_proxy. Фактически добавленные поля зависят от того, что найдено и какие свойства были настроены в properties.
Если используется база данных GeoIP2 Connection Type, то следующие поля могут быть добавлены под target_field: ip и connection_type. Фактически добавленные поля зависят от того, что найдено и какие свойства были настроены в properties.
Если используется база данных GeoIP2 Domain, то следующие поля могут быть добавлены под target_field: ip и domain. Фактически добавленные поля зависят от того, что найдено и какие свойства были настроены в properties.
Если используется база данных GeoIP2 ISP, то следующие поля могут быть добавлены под target_field: ip, asn, organization_name, network, isp, isp_organization_name, mobile_country_code и mobile_network_code. Фактически добавленные поля зависят от того, что найдено и какие свойства были настроены в properties.
Если используется база данных GeoIP2 Enterprise, то следующие поля могут быть добавлены под target_field: ip, country_iso_code, country_name, country_in_european_union, registered_country_iso_code, registered_country_name, registered_country_in_european_union, continent_code, continent_name, region_iso_code, region_name, city_name, postal_code, timezone, location, accuracy_radius, country_confidence, city_confidence, postal_confidence, asn, organization_name, network, hosting_provider, tor_exit_node, anonymous_vpn, anonymous, public_proxy, residential_proxy, domain, isp, isp_organization_name, mobile_country_code, mobile_network_code, user_type и connection_type. Фактически добавленные поля зависят от того, что найдено и какие свойства были настроены в properties.

Вот пример, который использует базу данных по умолчанию для городов и добавляет геолокационную информацию в поле geoip на основе поля ip:

resp = client.ingest.put_pipeline(
    id="geoip",
    description="Add ip geolocation info",
    processors=[
        {
            "geoip": {
                "field": "ip"
            }
        }
    ],
)
print(resp)

resp1 = client.index(
    index="my-index-000001",
    id="my_id",
    pipeline="geoip",
    document={
        "ip": "89.160.20.128"
    },
)
print(resp1)

resp2 = client.get(
    index="my-index-000001",
    id="my_id",
)
print(resp2)

const response = await client.ingest.putPipeline({
  id: "geoip",
  description: "Add ip geolocation info",
  processors: [
    {
      geoip: {
        field: "ip",
      },
    },
  ],
});
console.log(response);

const response1 = await client.index({
  index: "my-index-000001",
  id: "my_id",
  pipeline: "geoip",
  document: {
    ip: "89.160.20.128",
  },
});
console.log(response1);

const response2 = await client.get({
  index: "my-index-000001",
  id: "my_id",
});
console.log(response2);

PUT _ingest/pipeline/geoip
{
  "description" : "Add ip geolocation info",
  "processors" : [
    {
      "geoip" : {
        "field" : "ip"
      }
    }
  ]
}
PUT my-index-000001/_doc/my_id?pipeline=geoip
{
  "ip": "89.160.20.128"
}
GET my-index-000001/_doc/my_id

Что возвращает:

{
  "found": true,
  "_index": "my-index-000001",
  "_id": "my_id",
  "_version": 1,
  "_seq_no": 55,
  "_primary_term": 1,
  "_source": {
    "ip": "89.160.20.128",
    "geoip": {
      "continent_name": "Europe",
      "country_name": "Sweden",
      "country_iso_code": "SE",
      "city_name" : "Linköping",
      "region_iso_code" : "SE-E",
      "region_name" : "Östergötland County",
      "location": { "lat": 58.4167, "lon": 15.6167 }
    }
  }
}

Вот пример, который использует базу данных по умолчанию для стран и добавляет геолокационную информацию в поле geo на основе поля ip. Обратите внимание, что эта база данных загружается автоматически. Таким образом:

resp = client.ingest.put_pipeline(
    id="geoip",
    description="Add ip geolocation info",
    processors=[
        {
            "geoip": {
                "field": "ip",
                "target_field": "geo",
                "database_file": "GeoLite2-Country.mmdb"
            }
        }
    ],
)
print(resp)

resp1 = client.index(
    index="my-index-000001",
    id="my_id",
    pipeline="geoip",
    document={
        "ip": "89.160.20.128"
    },
)
print(resp1)

resp2 = client.get(
    index="my-index-000001",
    id="my_id",
)
print(resp2)

const response = await client.ingest.putPipeline({
  id: "geoip",
  description: "Add ip geolocation info",
  processors: [
    {
      geoip: {
        field: "ip",
        target_field: "geo",
        database_file: "GeoLite2-Country.mmdb",
      },
    },
  ],
});
console.log(response);

const response1 = await client.index({
  index: "my-index-000001",
  id: "my_id",
  pipeline: "geoip",
  document: {
    ip: "89.160.20.128",
  },
});
console.log(response1);

const response2 = await client.get({
  index: "my-index-000001",
  id: "my_id",
});
console.log(response2);

PUT _ingest/pipeline/geoip
{
  "description" : "Add ip geolocation info",
  "processors" : [
    {
      "geoip" : {
        "field" : "ip",
        "target_field" : "geo",
        "database_file" : "GeoLite2-Country.mmdb"
      }
    }
  ]
}
PUT my-index-000001/_doc/my_id?pipeline=geoip
{
  "ip": "89.160.20.128"
}
GET my-index-000001/_doc/my_id

возвращает это:

{
  "found": true,
  "_index": "my-index-000001",
  "_id": "my_id",
  "_version": 1,
  "_seq_no": 65,
  "_primary_term": 1,
  "_source": {
    "ip": "89.160.20.128",
    "geo": {
      "continent_name": "Europe",
      "country_name": "Sweden",
      "country_iso_code": "SE"
    }
  }
}

Не все IP-адреса находят геолокационную информацию в базе данных. В таких случаях, в документ не вставляется target_field.

Вот пример того, как будут индексироваться документы, когда информация для "80.231.5.0" не найдена:

resp = client.ingest.put_pipeline(
    id="geoip",
    description="Add ip geolocation info",
    processors=[
        {
            "geoip": {
                "field": "ip"
            }
        }
    ],
)
print(resp)

resp1 = client.index(
    index="my-index-000001",
    id="my_id",
    pipeline="geoip",
    document={
        "ip": "80.231.5.0"
    },
)
print(resp1)

resp2 = client.get(
    index="my-index-000001",
    id="my_id",
)
print(resp2)

const response = await client.ingest.putPipeline({
  id: "geoip",
  description: "Add ip geolocation info",
  processors: [
    {
      geoip: {
        field: "ip",
      },
    },
  ],
});
console.log(response);

const response1 = await client.index({
  index: "my-index-000001",
  id: "my_id",
  pipeline: "geoip",
  document: {
    ip: "80.231.5.0",
  },
});
console.log(response1);

const response2 = await client.get({
  index: "my-index-000001",
  id: "my_id",
});
console.log(response2);

PUT _ingest/pipeline/geoip
{
  "description" : "Add ip geolocation info",
  "processors" : [
    {
      "geoip" : {
        "field" : "ip"
      }
    }
  ]
}

PUT my-index-000001/_doc/my_id?pipeline=geoip
{
  "ip": "80.231.5.0"
}

GET my-index-000001/_doc/my_id

Что возвращает:

{
  "_index" : "my-index-000001",
  "_id" : "my_id",
  "_version" : 1,
  "_seq_no" : 71,
  "_primary_term": 1,
  "found" : true,
  "_source" : {
    "ip" : "80.231.5.0"
  }
}

Распознавание местоположения как геокоординаты

Хотя этот процессор обогащает ваш документ полем location, содержащим приблизительные широту и долготу IP-адреса, это поле не будет индексироваться как тип geo_point в Elasticsearch без явного определения его как такового в схеме.

Вы можете использовать следующую схему для указанного выше примера индекса:

resp = client.indices.create(
    index="my_ip_locations",
    mappings={
        "properties": {
            "geoip": {
                "properties": {
                    "location": {
                        "type": "geo_point"
                    }
                }
            }
        }
    },
)
print(resp)

response = client.indices.create(
  index: 'my_ip_locations',
  body: {
    mappings: {
      properties: {
        geoip: {
          properties: {
            location: {
              type: 'geo_point'
            }
          }
        }
      }
    }
  }
)
puts response

const response = await client.indices.create({
  index: "my_ip_locations",
  mappings: {
    properties: {
      geoip: {
        properties: {
          location: {
            type: "geo_point",
          },
        },
      },
    },
  },
});
console.log(response);

PUT my_ip_locations
{
  "mappings": {
    "properties": {
      "geoip": {
        "properties": {
          "location": { "type": "geo_point" }
        }
      }
    }
  }
}

Управление обновлениями вашей собственной базы данных геолокации IP

Если вы не можете автоматически обновлять свои базы данных геолокации IP из конечной точки Elastic, у вас есть несколько других вариантов:

Использование прокси-конечной точки

Если вы не можете подключиться напрямую к конечной точке Elastic GeoIP, рассмотрите возможность настройки защищённого прокси-сервера. Затем вы можете указать URL прокси-конечной точки в параметре ingest.geoip.downloader.endpoint каждого файла узла elasticsearch.yml.

В строгой настройке, возможно, потребуется добавить следующие домены в список разрешённых доменов:

geoip.elastic.co
storage.googleapis.com

Использование пользовательской конечной точки

Вы можете создать сервис, имитирующий конечную точку Elastic GeoIP. Затем вы сможете получать автоматические обновления из этого сервиса.

Загрузите файлы базы данных .mmdb с сайта MaxMind.
Скопируйте файлы базы данных в одну директорию.
Из вашей директории Elasticsearch выполните:
```
./bin/elasticsearch-geoip -s my/source/dir [-t target/directory]
```
Оказайте доступ к статическим файлам базы данных из вашей директории. Например, вы можете использовать Docker для предоставления файлов с помощью сервера nginx:
```
docker run -v my/source/dir:/usr/share/nginx/html:ro nginx
```
Укажите URL конечной точки сервиса в настройке ingest.geoip.downloader.endpoint каждого файла узла elasticsearch.yml.

По умолчанию Elasticsearch проверяет конечную точку на наличие обновлений каждые три дня. Для использования другого интервала опроса используйте API настроек кластера для установки ingest.geoip.downloader.poll.interval.

Ручное обновление баз данных геолокации IP

Используйте API настроек кластера, чтобы установить ingest.geoip.downloader.enabled на значение false. Это отключит автоматические обновления, которые могут перезаписать ваши изменения в базе данных. Это также удалит все загруженные базы данных.
Загрузите файлы базы данных .mmdb с сайта MaxMind.

Вы также можете использовать пользовательские файлы для городов, стран и ASN .mmdb. Эти файлы должны быть разархивированы. Тип (город, страна или ASN) будет извлечён из метаданных файла, поэтому имя файла не имеет значения.
На развертываниях Elasticsearch Service загрузите базу данных с помощью пользовательского пакета.
На самодостаточных развертываниях скопируйте файлы базы данных в $ES_CONFIG/ingest-geoip.
В ваших обработчиках geoip настройте параметр database_file для использования пользовательского файла базы данных.

Настройки узла

Обработчик geoip поддерживает следующие настройки:

ingest.geoip.cache_size: Максимальное количество результатов, которое должно быть кэшировано. По умолчанию 1000.

Обратите внимание, что эти настройки являются настройками узла и применяются ко всем обработчикам geoip и ip_location, т.е. существует один кэш для всех таких обработчиков.

Настройки кластера

ingest.geoip.downloader.enabled: (Динамический, Булево) Если true, Elasticsearch автоматически загружает и управляет обновлениями баз данных геолокации IP из ingest.geoip.downloader.endpoint. Если false, Elasticsearch не загружает обновления и удаляет все загруженные базы данных. По умолчанию true.

ingest.geoip.downloader.eager.download: (Динамический, Булево) Если true, Elasticsearch загружает базы данных геолокации IP немедленно, независимо от того, существует ли конвейер с обработчиком geoip. Если false, Elasticsearch начинает загрузку баз данных только если существует или добавлен конвейер с обработчиком geoip. По умолчанию false.

ingest.geoip.downloader.endpoint: (Статический, строка) URL конечной точки, используемой для загрузки обновлений баз данных геолокации IP. Например, https://myDomain.com/overview.json. По умолчанию https://geoip.elastic.co/v1/database. Elasticsearch хранит загруженные файлы базы данных в временной директории каждого узла временной директории по адресу $ES_TMPDIR/geoip-databases/<node_id>. Обратите внимание, что Elasticsearch отправит GET-запрос на ${ingest.geoip.downloader.endpoint}?elastic_geoip_service_tos=agree, ожидая список метаданных о базах данных, обычно находящихся в overview.json.

Загрузчик использует встроенный cacerts JDK. Если вы используете пользовательскую конечную точку, добавьте пользовательский https конечный cacert(s) в хранилище доверенных сертификатов JDK.

ingest.geoip.downloader.poll.interval: (Динамический, временная величина) С какой периодичностью Elasticsearch проверяет наличие обновлений баз данных геолокации IP в ingest.geoip.downloader.endpoint. Должно быть больше, чем 1d (один день). По умолчанию 3d (три дня).

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/geoip-processor.html