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.

Set Up 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. Graylog supports both MaxMind and IPInfo databases.

Hint: You must create an account to obtain a license key to download the MaxMind databases. 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 need to configure Graylog to start using the geolocation database to resolve IP addresses in your logs.

  1. Navigate to System > Configurations.

  2. Select Plugins > Geo-Location Processor, then click Edit configuration.

  3. Select the Enable Geo-location processor check box.

  4. Choose either MaxMind or IPInfo from the drop-down menu.

  5. Enter the paths to both the city and ASN databases you use. You can also adjust the refresh interval.

  6. Select Update configuration to save the configuration.

Illuminate and Geolocation

Hint: Geolocation configuration is available with Graylog Open. Illuminate is not required to use geolocation data.

If you want geolocation data with Illuminate content, you must ensure that the Illuminate Processor runs before the GeoIP Resolver in Message Processors Configuration. Note that this order should be the default.

To check the configuration in your environment:

  1. Navigate to System > Configurations.

  2. Select Message Processors, then confirm the order in the table.

    If you need to change the order:

    1. Select Edit configuration.

    2. Use drag and drop to reorder the items in the list as required.

    3. Select Update configuration.

Enforce Graylog Schema Option

When you configure the geolocation processor, the Enforce default schema option is selected by default. If you disable schema enforcement, all IP fields that are not reserved IP addresses are 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 are 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 Database 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 runs 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 are pulled down onto each node. This service relies on the Default Credentials Provider for credentials to the S3 buckets and does 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 generates an empty aggregation widget. Click Edit and enter your information. Select World Map as the Visualization Type. You 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 affects the size of the dot on the map. If there is no metric defined, every dot has 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. When you display a map in the search result page:

  1. Click the three dots in the upper right corner.

  2. Select Export to Dashboard.

You can then rename, edit ,and save the new dashboard.