Skip to content

Commit

Permalink
Improve documentation on GeoIP databases (#10190)
Browse files Browse the repository at this point in the history
As part of my on-call I'm looking through issues that require
documentation. I saw one about GeoIP in #8570 and wrote an overview of
how to set it up and why you would want to use GeoIP.
  • Loading branch information
Artemis Tosini authored Mar 31, 2023
1 parent 879d02c commit 9f908ba
Showing 1 changed file with 29 additions and 2 deletions.
31 changes: 29 additions & 2 deletions docs/Deploying/Configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -2362,17 +2362,44 @@ vulnerabilities:

##### database_path

The path to a valid Maxmind GeoIP database(mmdb). Support exists for the country & city versions of the database. If city database is supplied
The path to a valid Maxmind GeoIP database (mmdb). Support exists for the country & city versions of the database. If city database is supplied
then Fleet will attempt to resolve the location via the city lookup, otherwise it defaults to the country lookup. The IP address used
to determine location is extracted via HTTP headers in the following order: `True-Client-IP`, `X-Real-IP`, and finally `X-FORWARDED-FOR` [headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)
on the Fleet web server.

You can get a copy of the
[Geolite2](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data?lang=en) database for free by
[creating an account](https://www.maxmind.com/en/geolite2/signup?lang=en) on the MaxMind website,
navigating to the [download page](https://www.maxmind.com/en/accounts/current/geoip/downloads),
and downloading the GZIP archive. Decompress it and place the mmdb file somewhere fleet can access.

It is also possible to automatically keep the database up to date, see the
[documentation](https://dev.maxmind.com/geoip/updating-databases?lang=en) from MaxMind.

GeoIP databases can find what general area a device is from, but not the exact location.
They work by collecting which IP addresses ISPs use for different cities and countries and
packaging them up into a list mapping IP address to city.

You've likely seen services use GeoIP databases if they redirect you to a site specific
to your country. e.g. Google will redirect you to [google.ca](https://google.ca) if you visit from Canada
or Mouser will change to your local currency if you view an electronic component.

This can be useful for your fleet install if you want to tell if a device is somewhere it shouldn't
be. If a desktop machine located at a site in New York suddenly appears in London, then you can tell
that something is wrong. It can also help you differentiate machines if they have similar names,
e.g. if you have two computers "John's MacBook Pro".

While it can be a useful tool, an unexpected result could be an error in the database, a user
connecting via a mobile network which uses the same IP address for a wide area, or a user visiting
family. Checking on the location of devices too often could be invasive to employees who are keeping
work devices on them for e.g. oncall responsibilities.

- Default value: none
- Environment variable: `FLEET_GEOIP_DATABASE_PATH`
- Config file format:
```yaml
geoip:
database_path: /some/path
database_path: /some/path/to/geolite2.mmdb
```

#### Sentry
Expand Down

0 comments on commit 9f908ba

Please sign in to comment.