Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Doc] GeoIP database service #177

Merged
merged 5 commits into from
Mar 11, 2021
Merged

[Doc] GeoIP database service #177

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
bdeaae9
[Doc] GeoIP database service
kaisecheng Feb 19, 2021
849095a
update doc
kaisecheng Mar 10, 2021
fe2fac2
Merge branch 'master' of github.com:logstash-plugins/logstash-filter-…
kaisecheng Mar 10, 2021
45053cc
dump version
kaisecheng Mar 10, 2021
c46436e
update doc
kaisecheng Mar 11, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
## 7.0.1
- [DOC] Add documentation for MaxMind database license change [#177](https://github.com/logstash-plugins/logstash-filter-geoip/pull/177)

## 7.0.0
- Changed the plugin to use EULA GeoIP2 Database with auto-update [#176](https://github.com/logstash-plugins/logstash-filter-geoip/pull/176)
Available in Logstash 7.13+ Elastic license
Expand Down Expand Up @@ -39,11 +42,11 @@
- Add default_database_type configuration option to allow selection between the GeoLite2-City and GeoLote2-ASN databases.

## 4.2.0
- Add support for GeoLite2-ASN database from Maxmind for ASN data.
- Add support for GeoLite2-ASN database from MaxMind for ASN data.
- Update Java dependencies to 2.9.0 to support the new ASN database.

## 4.1.1
- Add support for commercial databases from Maxmind.
- Add support for commercial databases from MaxMind.
- Add ASN data support via GeoIP2-ISP database.

## 4.1.0
Expand Down
40 changes: 30 additions & 10 deletions docs/index.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,22 +21,41 @@ include::{include_path}/plugin_header.asciidoc[]
==== Description

The GeoIP filter adds information about the geographical location of IP addresses,
based on data from the Maxmind GeoLite2 databases.
based on data from the MaxMind GeoLite2 databases.

==== Supported Databases

This plugin is bundled with https://dev.maxmind.com/geoip/geoip2/geolite2[GeoLite2] City database out of the box. From Maxmind's description --
This plugin is bundled with https://dev.maxmind.com/geoip/geoip2/geolite2[GeoLite2] City database out of the box. From MaxMind's description --
"GeoLite2 databases are free IP geolocation databases comparable to, but less accurate than, MaxMind’s
GeoIP2 databases". Please see GeoIP Lite2 license for more details.

https://www.maxmind.com/en/geoip2-databases[Commercial databases] from Maxmind are also supported in this plugin.
https://www.maxmind.com/en/geoip2-databases[Commercial databases] from MaxMind are also supported in this plugin.

If you need to use databases other than the bundled GeoLite2 City, you can download them directly
from Maxmind's website and use the `database` option to specify their location. The GeoLite2 databases
from MaxMind's website and use the `database` option to specify their location. The GeoLite2 databases
can be https://dev.maxmind.com/geoip/geoip2/geolite2[downloaded from here].

If you would like to get Autonomous System Number(ASN) information, you can use the GeoLite2-ASN database.

[id="plugins-{type}s-{plugin}-database_license"]
==== Database License

https://www.maxmind.com[MaxMind] changed from releasing the GeoIP database under
a Creative Commons (CC) license to a proprietary end-user license agreement
(EULA). The MaxMind EULA requires Logstash to update the MaxMind database
within 30 days of a database update. If Logstash fails to download the database
for 30 days, it will stop the pipeline in order to maintain compliance.

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

==== Details

A `[geoip][location]` field is created if
Expand Down Expand Up @@ -109,14 +128,15 @@ number of cache misses and waste memory.
===== `database`

* Value type is <<path,path>>
* There is no default value for this setting.
* If not specified, the database defaults to the GeoLite2 City database that ships with Logstash.

The path to Maxmind's database file that Logstash should use. The default database is GeoLite2-City.
GeoLite2-City, GeoLite2-Country, GeoLite2-ASN are the free databases from Maxmind that are supported.
GeoIP2-City, GeoIP2-ISP, GeoIP2-Country are the commercial databases from Maxmind that are supported.
The path to MaxMind's database file that Logstash should use. The default database is GeoLite2-City.
GeoLite2-City, GeoLite2-Country, GeoLite2-ASN are the free databases from MaxMind that are supported.
GeoIP2-City, GeoIP2-ISP, GeoIP2-Country are the commercial databases from MaxMind that are supported.

If not specified, this will default to the GeoLite2 City database that ships
with Logstash.
Database auto-update applies to default distribution. When `database` point to user's database path,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Database auto-update applies to default distribution. When `database` point to user's database path,
Database auto-update applies to default distribution. When `database` points to user's database path,

auto-update will be disabled
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Be more explicit here to emphasize no auto-update if database is set

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
auto-update will be disabled
auto-update will be disabled.

{logstash-ref}/plugins-filters-geoip.html#plugins-filters-geoip-database_license[see also database license]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
{logstash-ref}/plugins-filters-geoip.html#plugins-filters-geoip-database_license[see also database license]
See
<<plugins-{type}s-{plugin}-database_license,Database License>> for more information.


[id="plugins-{type}s-{plugin}-default_database_type"]
===== `default_database_type`
Expand Down
2 changes: 1 addition & 1 deletion lib/logstash/filters/geoip.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@


# The GeoIP filter adds information about the geographical location of IP addresses,
# based on data from the Maxmind GeoLite2 database.
# based on data from the MaxMind GeoLite2 database.
#
# A `[geoip][location]` field is created if
# the GeoIP lookup returns a latitude and longitude. The field is stored in
Expand Down
2 changes: 1 addition & 1 deletion logstash-filter-geoip.gemspec
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Gem::Specification.new do |s|

s.name = 'logstash-filter-geoip'
s.version = '7.0.0'
s.version = '7.0.1'
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"
Expand Down