Skip to main content

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 resolution. Additionally, you'll learn how to create a map with the extracted geo-information.

Setup​

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

On Graylog 3.0, the preferred way of configuring geolocation is by using Lookup Tables, as it provides more flexibility and is compatible with more database types. If you prefer to use the old Message Processor, please check the 2.5 documentation.

Note

Before you get started, we recommend taking a look at some LookupTable concepts in the documentation

Download the database​

Note

As of December 30, 2019, you will need to create an account to obtain a license key to download the database(s). More information is available on MaxMind’sblog post.

To start, download a geolocation database. The Lookup TableGeo IP Data Adapter supports both MaxMind City and Country databases in the MaxMind DB format, as the GeoIP2 Databases or GeoLite2 Databases that MaxMind provides.

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 Lookup Table​

The next step is to configure a Graylog Lookup Table that can use the geolocation database. Follow the Lookup Tables setup documentation to see what you need to do. In most common cases you need to:

  1. Create a Geo IP Data Adapter and point it to the location where you storethe database. You can additionally test the Data Adapter to ensure it allworks as expected.
  2. Create a Cache (if needed) to make your lookups faster.
  3. Create a Lookup Table that uses the Data Adapter and Cache you created inprevious steps.

Use the Lookup Table​

Now you are almost ready to extract geolocation information from IP addresses. All you need to do is to use the Lookup Table you created in the previous stepin a Extractor, Converter, Decorator, or Pipeline Rule. Take a look at the Lookup Tables usage documentation for more information.

Note

Make sure to read The importance of message processor ordering, specially ifyou will use the Lookup Table with a Pipeline, in order to better understandhow Graylog will process messages.

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. The default return value of the Geo IP Data Adapter returns the coordinates in the right format, so you most likely don’t need to do anything special if you are using a Lookup Table for extracting geolocation information.

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, and click on the World Map link. That will show a map with all different points stored in that field.

geolocation7.png

Add map to a dashboard​

You can add the map visualization into any dashboards as you do with other widgets. Once you displayed a mapin the search result page, click on Add to dashboard, and select the dashboard where you want to add the map.

geolocation8.png geolocation9.png

FAQs​

Will Graylog extract IPs from all fields?​

No, you can configure which fields you want to extract data from in the PipelineRule or Extractor using the Lookup Table configured in the setup section.

What geo-information is extracted from IPs?​

Depending on the database you use, the extracted information will be different.By using a Pipeline Rule alongside a Lookup Table, you can extract any informationreturned by the MaxMind Database for the IP in your logs.

Where is the extracted geo-information stored?​

Extracted geo-information is stored in message fields, which you can name asyou wish.

Which geo-points format does Graylog use to store coordinates?​

Graylog returns the geolocation information in the latitude,longitude format.The Map visualization also requires that format to be able to draw the coordinateson a map.

I have a field in my messages with coordinates information already, can I use it in Graylog?​

Yes, you can display a map for coordinates as long as they are in the latitude,longitude format.

Not all fields containing IP addresses are resolved. Why does this happen?​

Most likely it is a misconfiguration issue. It is easier to extract informationif IP addresses are in their own field. You should also make sure your Message Processors are in the right order in the Message Processors Configuration , as explained in The importance of message processor ordering.