|
|
@@ -0,0 +1,92 @@
|
|
|
+[[put-ip-location-database-api]]
|
|
|
+=== Create or update IP geolocation database configuration API
|
|
|
+++++
|
|
|
+<titleabbrev>Create or update IP geolocation database configuration</titleabbrev>
|
|
|
+++++
|
|
|
+
|
|
|
+Creates or updates an IP geolocation database configuration.
|
|
|
+
|
|
|
+IMPORTANT: The Maxmind `account_id` shown below requires a license key. Because the license key is sensitive information,
|
|
|
+it is stored as a <<secure-settings,secure setting>> in {es} named `ingest.geoip.downloader.maxmind.license_key`. Only
|
|
|
+one Maxmind license key is currently allowed per {es} cluster. A valid license key must be in the secure settings in order
|
|
|
+to download from Maxmind. The license key setting does not take effect until all nodes are restarted or a
|
|
|
+<<cluster-nodes-reload-secure-settings, `reload_secure_settings`>> request is executed.
|
|
|
+
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+PUT _ingest/ip_location/database/my-database-1
|
|
|
+{
|
|
|
+ "name": "GeoIP2-Domain",
|
|
|
+ "maxmind": {
|
|
|
+ "account_id": "1234567"
|
|
|
+ }
|
|
|
+}
|
|
|
+----
|
|
|
+// TEST[skip:we don't want to leak the enterprise-geoip-downloader task, which touching these APIs would cause. Therefore, skip this test.]
|
|
|
+
|
|
|
+IMPORTANT: The IPinfo configuration shown below requires a token. Because the token is sensitive information,
|
|
|
+it is stored as a <<secure-settings,secure setting>> in {es} named `ingest.ip_location.downloader.ipinfo.token`. Only
|
|
|
+one IPinfo token is currently allowed per {es} cluster. A valid token must be in the secure settings in order
|
|
|
+to download from IPinfo. The token setting does not take effect until all nodes are restarted or a
|
|
|
+<<cluster-nodes-reload-secure-settings, `reload_secure_settings`>> request is executed.
|
|
|
+
|
|
|
+[source,console]
|
|
|
+----
|
|
|
+PUT _ingest/ip_location/database/my-database-2
|
|
|
+{
|
|
|
+ "name": "standard_location",
|
|
|
+ "ipinfo": {
|
|
|
+ }
|
|
|
+}
|
|
|
+----
|
|
|
+// TEST[skip:we don't want to leak the enterprise-geoip-downloader task, which touching these APIs would cause. Therefore, skip this test.]
|
|
|
+
|
|
|
+
|
|
|
+[[put-ip-location-database-api-request]]
|
|
|
+==== {api-request-title}
|
|
|
+
|
|
|
+`PUT /_ingest/ip_location/database/<database>`
|
|
|
+
|
|
|
+[[put-ip-location-database-api-prereqs]]
|
|
|
+==== {api-prereq-title}
|
|
|
+
|
|
|
+* If the {es} {security-features} are enabled, you must have the
|
|
|
+`manage` <<privileges-list-cluster,cluster privilege>> to use this API.
|
|
|
+
|
|
|
+
|
|
|
+[[put-ip-location-database-api-path-params]]
|
|
|
+==== {api-path-parms-title}
|
|
|
+
|
|
|
+`<database>`::
|
|
|
++
|
|
|
+__
|
|
|
+(Required, string) ID of the database configuration to create or update.
|
|
|
+
|
|
|
+[[put-ip-location-database-api-query-params]]
|
|
|
+==== {api-query-parms-title}
|
|
|
+
|
|
|
+include::{es-ref-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
|
|
+
|
|
|
+[[put-ip-location-database-api-request-body]]
|
|
|
+==== {api-request-body-title}
|
|
|
+
|
|
|
+// tag::ip-location-database-object[]
|
|
|
+`name`::
|
|
|
+(Required, string)
|
|
|
+The provider-assigned name of the IP geolocation database to download.
|
|
|
+
|
|
|
+`<provider>`::
|
|
|
+(Required, a provider object and its associated configuration)
|
|
|
+The configuration necessary to identify which IP geolocation provider to use to download
|
|
|
+the database, as well as any provider-specific configuration necessary for such downloading.
|
|
|
++
|
|
|
+At present, the only supported providers are `maxmind` and `ipinfo`. The maxmind provider
|
|
|
+requires that an `account_id` (string) is configured. The ipinfo provider does not require
|
|
|
+additional configuration in the request body.
|
|
|
+// end::ip-location-database-object[]
|
|
|
+
|
|
|
+[[ip-location-database-configuration-licensing]]
|
|
|
+==== Licensing
|
|
|
+
|
|
|
+Downloading databases from third party providers is a commercial feature that requires an
|
|
|
+appropriate license. For more information, refer to https://www.elastic.co/subscriptions.
|
Joe Gallo