Geolocation

Graylog lets you extract and visualize geolocation information from IP addresses in your logs. In this section, you'll learn how to configure the geolocation processor. Additionally, you'll learn how to create a map with the extracted geo-information.

Setup the Processor

Graylog ships with geolocation capabilities by default but additional configuration is still required. This section explains how to configure the functionality in detail.

Download the Database

To start, download a geolocation database. As of version 4.3, both MaxMind and IPInfo databases are supported by Graylog.

Hint: You will need to create an account to obtain a license key to download the MaxMind database(s). More information is available on MaxMind’s blog post.

The next step is to store the geolocation database on all servers running Graylog. Make sure you grant the right permissions to the file so the user running Graylog can read the database.

Configure the Processor

You will need to configure Graylog to start using the geolocation database to resolve IPs in your logs. To ensure the correct order of operations occurs, verify that the configuration of the Illuminate Processor is executed before the GeoIP Resolver. Navigate to System > Configurations and select the Message Processors setting.

Ensure that the Illuminate Processor is queued before the GeoIP Resolver, as shown. If this is not the case, then select Edit configuration to reorder your processing steps.

Then, on the same page, select Plugins > Geo-Location Processor, then click Edit configuration.

Here, configure your plugin utilizing either MaxMind or IPInfo. In the configuration dialog, you need to select Enable Geo-location processor and enter the paths to both the city and ASN databases you use. When you are all set, click Update configuration to store the configuration changes.

Enforce Graylog Schema Option

If Schema enforcement is disabled: all IP fields that are not reserved IP addresses will be processed and have the following fields added with the field name as a prefix

  • _geolocation

  • _country_code

  • _city_name

An example of the generated fields for the source_ip field might read:

  • source_ip_city_name: Vienna

  • source_ip_country_code: AT

  • source_ip_geolocation: 48.20849, 16.37208

If Schema enforcement is enabled: only the following GIM schema fields that are not reserved IP addresses will be processed:

  • destination_ip

  • destination_nat_ip

  • event_observer_ip

  • host_ip

  • network_forwarded_ip

  • source_ip

  • source_nat_ip

An example of the generated fields for the source_ip field might read:

  • source_as_number: AS1853

  • source_as_organization: ACONET

  • source_geo_city: Vienna

  • source_geo_coordinates: 48.20849, 16.37208

  • source_geo_country_iso: AT

  • source_geo_name: Vienna, AT

  • source_geo_region: Vienna

  • source_go_timezome: Europe/Vienna

Storing Geolocation DB Files in AWS S3

A configuration option for Pull files from S3 bucket at the bottom of the configuration page lets you pull geolocation database files from AWS S3 buckets. Enabling this feature allows for an S3 bucket URL to be added to the Path configuration values.

When enabled, a service will run every refresh interval and poll the files in the S3 buckets provided. If those files have been updated since the last poll, then the new files will be pulled down onto each node. This service relies on the DefaultCredentialsProvider for credentials to the S3 buckets and will not use any configuration values that may or may not be set in the Graylog AWS Plugin configuration settings.

The geolocation database files retrieved from S3 are stored in the Graylog data_dir directory under the geolocation subdirectory. To change where these files are downloaded, set geo_ip_processor_s3_download_location to the desired location on disk in your Graylog server configuration file.

If the pull files from S3 bucket option is left disabled, all Graylog nodes read the files from the path on disk and require manual updating to those files for updates.

Visualize Geolocations in a Map

Graylog can display maps from geolocation stored in any field, as long as the geo-points are using the latitude,longitude format.

Display a Map in the Search Results Page

On any search result page, you can expand the field you want to use to draw a map in the search sidebar. Click the Create button (+) in the left sidebar and select aggregation under the Generic menu.

This will generate an empty aggregation widget. Click Edit and enter your information. Select World Map as the Visualization Type. You will then see a map with all the different points stored in that field.

You may click Update preview to take a peek at your map and make any changes before you click Update widget.

Hint: Adding a metric will affect the size of the dot on the map. If there is no metric defined, every dot will have the same radius.

For additional fields used in Graylog related to different sources of geo coordinates, view the Graylog Schema.

Add a Map to a Dashboard

You can add the map visualization into any dashboards as you do with other widgets. Once you displayed a map in the search result page:

  • Click on the three dots in the upper right corner.

  • Select Export to Dashboard.

  • You may then rename, edit and save the new Dashboard.