From ef3cf5a4f588a93a01ba6428b225c84efda299df Mon Sep 17 00:00:00 2001 From: edmocosta <11836452+edmocosta@users.noreply.github.com> Date: Fri, 23 Dec 2022 18:23:08 +0100 Subject: [PATCH 1/5] Added disable the auto-update feature section --- docs/index.asciidoc | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 3eb2a89..53ad590 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -72,6 +72,13 @@ Events will be tagged with `_geoip_expired_database` tag to facilitate the handl TIP: When possible, allow Logstash to access the internet to download databases so that they are always up-to-date. +**Disable the auto-update feature** + +If you work in air-gapped environment, and want to disable the auto-update feature from Logstash, you can do so by setting the `xpack.geoip.db.auto_update` +configuration to `false` in `logstash.yml`. + +When disabled, a valid `database` location is required, and you are responsible for <> and <>. + [id="plugins-{type}s-{plugin}-manage_update"] ==== Manage your own database updates From f893aec1c5e6e248c95534998144e41cb8225abb Mon Sep 17 00:00:00 2001 From: edmocosta <11836452+edmocosta@users.noreply.github.com> Date: Tue, 27 Dec 2022 11:19:39 +0100 Subject: [PATCH 2/5] Update changelog and bump version --- CHANGELOG.md | 3 +++ logstash-filter-geoip.gemspec | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c77326..cad098a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,6 @@ +## 7.2.13 + - [DOC] Add documentation for database auto-update configuration [#210](https://github.com/logstash-plugins/logstash-filter-geoip/pull/210) + ## 7.2.12 - [DOC] Add `http_proxy` environment variable for GeoIP service endpoint. The feature is included in 8.1.0, and was back-ported to 7.17.2 [#207](https://github.com/logstash-plugins/logstash-filter-geoip/pull/207) diff --git a/logstash-filter-geoip.gemspec b/logstash-filter-geoip.gemspec index 8ca302d..b20ca7a 100644 --- a/logstash-filter-geoip.gemspec +++ b/logstash-filter-geoip.gemspec @@ -1,7 +1,7 @@ Gem::Specification.new do |s| s.name = 'logstash-filter-geoip' - s.version = '7.2.12' + s.version = '7.2.13' s.licenses = ['Apache License (2.0)'] s.summary = "Adds geographical information about an IP address" s.description = "This gem is a Logstash plugin required to be installed on top of the Logstash core pipeline using $LS_HOME/bin/logstash-plugin install gemname. This gem is not a stand-alone program" From 006196a139b60618ed3bc49011ab0ce29d8c14e2 Mon Sep 17 00:00:00 2001 From: edmocosta <11836452+edmocosta@users.noreply.github.com> Date: Thu, 5 Jan 2023 13:47:17 +0100 Subject: [PATCH 3/5] Changes to reflect the new behavior --- docs/index.asciidoc | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 53ad590..e9d9e5c 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -47,10 +47,9 @@ within 30 days of a database update. The GeoIP filter plugin can manage the database for users running the Logstash default distribution, or you can manage -database updates on your own. The behavior is controlled by the `database` setting. -When you use the default `database` setting, the auto-update feature ensures that the plugin is +the updates on your own, becoming also responsible for maintaining compliance. The behavior is controlled by the `database` setting. +When you use the default `database` setting, and the auto-update feature is enabled, Logstash ensures that the plugin is using the latest version of the database. -Otherwise, you are responsible for maintaining compliance. The Logstash open source distribution uses the MaxMind Creative Commons license database by default. @@ -59,11 +58,8 @@ database by default. ==== Database Auto-update This plugin bundles Creative Commons (CC) license databases. -Logstash checks for database updates every day. It downloads the latest and can replace the old database +By default, Logstash checks for database updates every day and upgrades from the CC database licence to the EULA version automatically. It downloads the latest version and replaces old databases while the plugin is running. -After Logstash downloads EULA license databases, it will not fallback to CC license databases. - -NOTE: If the database has never been updated successfully, as in air-gapped environments, Logstash can use CC license databases indefinitely. After Logstash has switched to a EULA licensed database, the geoip filter will stop enriching events in order to maintain compliance if Logstash fails to @@ -74,10 +70,9 @@ TIP: When possible, allow Logstash to access the internet to download databases **Disable the auto-update feature** -If you work in air-gapped environment, and want to disable the auto-update feature from Logstash, you can do so by setting the `xpack.geoip.db.auto_update` -configuration to `false` in `logstash.yml`. +If you work in air-gapped environment and want to disable the database auto-update feature, set the `xpack.geoip.downloader.enabled` value to `false` in `logstash.yml`. -When disabled, a valid `database` location is required, and you are responsible for <> and <>. +When disabled, Logstash uses the Creative Commons (CC) license databases indefinitely, and any previously downloaded version of the EULA databases will be deleted. [id="plugins-{type}s-{plugin}-manage_update"] ==== Manage your own database updates From 6df33262a39fa63de641f409c5c80fb40fa2c03c Mon Sep 17 00:00:00 2001 From: edmocosta <11836452+edmocosta@users.noreply.github.com> Date: Thu, 19 Jan 2023 11:26:29 +0100 Subject: [PATCH 4/5] Addressing PR suggestions --- docs/index.asciidoc | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index e9d9e5c..eb4ef72 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -47,9 +47,10 @@ within 30 days of a database update. The GeoIP filter plugin can manage the database for users running the Logstash default distribution, or you can manage -the updates on your own, becoming also responsible for maintaining compliance. The behavior is controlled by the `database` setting. -When you use the default `database` setting, and the auto-update feature is enabled, Logstash ensures that the plugin is +database updates on your own. The behavior is controlled by the `database` setting and by the auto-update feature. +When you use the default `database` setting and the auto-update feature is enabled, Logstash ensures that the plugin is using the latest version of the database. +Otherwise, you are responsible for maintaining compliance. The Logstash open source distribution uses the MaxMind Creative Commons license database by default. @@ -58,14 +59,18 @@ database by default. ==== Database Auto-update This plugin bundles Creative Commons (CC) license databases. -By default, Logstash checks for database updates every day and upgrades from the CC database licence to the EULA version automatically. It downloads the latest version and replaces old databases +If the auto-update feature is enabled, Logstash checks for database updates every day. It downloads the latest and can replace the old database while the plugin is running. +NOTE: If the auto-update feature is disabled or the database has never been updated successfully, as in air-gapped environments, Logstash can use CC license databases indefinitely. + After Logstash has switched to a EULA licensed database, the geoip filter will stop enriching events in order to maintain compliance if Logstash fails to check for database updates for 30 days. Events will be tagged with `_geoip_expired_database` tag to facilitate the handling of this situation. +NOTE: If the auto-update feature is enabled, Logstash upgrades from the CC database license to the EULA version on the first download. + TIP: When possible, allow Logstash to access the internet to download databases so that they are always up-to-date. **Disable the auto-update feature** From 2f8e5184444d7b0ef2bc9266adc8b9982c3975e7 Mon Sep 17 00:00:00 2001 From: Edmo Vamerlatti Costa <11836452+edmocosta@users.noreply.github.com> Date: Mon, 23 Jan 2023 10:31:01 +0100 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Karen Metts <35154725+karenzone@users.noreply.github.com> --- docs/index.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.asciidoc b/docs/index.asciidoc index eb4ef72..e6cd508 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -59,7 +59,7 @@ database by default. ==== Database Auto-update This plugin bundles Creative Commons (CC) license databases. -If the auto-update feature is enabled, Logstash checks for database updates every day. It downloads the latest and can replace the old database +If the auto-update feature is enabled in `logstash.yml`(as it is by default), Logstash checks for database updates every day. It downloads the latest and can replace the old database while the plugin is running. NOTE: If the auto-update feature is disabled or the database has never been updated successfully, as in air-gapped environments, Logstash can use CC license databases indefinitely. @@ -77,7 +77,7 @@ TIP: When possible, allow Logstash to access the internet to download databases If you work in air-gapped environment and want to disable the database auto-update feature, set the `xpack.geoip.downloader.enabled` value to `false` in `logstash.yml`. -When disabled, Logstash uses the Creative Commons (CC) license databases indefinitely, and any previously downloaded version of the EULA databases will be deleted. +When the auto-update feature is disabled, Logstash uses the Creative Commons (CC) license databases indefinitely, and any previously downloaded version of the EULA databases will be deleted. [id="plugins-{type}s-{plugin}-manage_update"] ==== Manage your own database updates