Searching HAProxy Enterprise 1.7r2
Performing Geolocation with MaxMind
The MaxMind module provides geolocation lookups using MaxMind's GeoIP2 databases. It also supports the use of multiple MaxMind databases.
In addition, this module provides live updates of databases, similar to HAProxy's Update module for maps/ACLs.
Tip
- HAProxy Enterprise only: This module requires an active HAProxy
-
Enterprise subscription. Please contact us if you would like to learn more or begin a free trial.
Prerequisites
HAProxy Enterprise version 1.7 r2 or later
Subscription to MaxMind for databases
Install the MaxMind module
Get the MaxMind databases.
-
Install the MaxMind module according to your platform:
$ sudo apt install hapee-1.7r2-lb-maxmind
or
$ sudo yum install hapee-1.7r2-lb-maxmind
-
In the
global
section of your configuration, add the following lines:global # ... module-load hapee-lb-maxmind.so maxmind-cache-size 200000 maxmind-debug maxmind-load mlock_max 512000000 CITY /etc/hapee-1.7/GeoIP2-City.mmdb ISP /etc/hapee-1.7/GeoIP2-ISP.mmdb maxmind-update url CITY http://localhost:8000/data/geoip/maxmind_db/GeoIP2-City_20180206/GeoIP2-City.mmdb url ISP http://localhost:8000/data/geoip/maxmind_db/GeoIP2-ISP_20180206/GeoIP2-ISP.mmdb delay 10m checksum hash log
-
In the
frontend
,backend
orlisten
section where you want to enable geolocation, add one or morehttp-request add-header
lines that use thesrc
fetch method andmaxmind-lookup
converter.In the following example, four HTTP request headers x-mmdb1 through x-mmdb4 are assigned values from the MaxMind CITY and ISP database files. They look up the city name, country, autonomous system number, and autonomous system organization for the client's source IP address:
# Used in the a frontend, listen, or backend section http-request add-header x-mmdb1 %[src,maxmind-lookup("CITY","city","names","en")] http-request add-header x-mmdb2 %[src,maxmind-lookup("CITY","country","iso_code")] http-request add-header x-mmdb3 %[src,maxmind-lookup("ISP","autonomous_system_number")] http-request add-header x-mmdb4 %[src,maxmind-lookup("ISP","autonomous_system_organization")]
Note
If you are hosting HAProxy at localhost, you can still test geolocation by replacing
src
in the previous example with a hardcoded IP address. Use theipv4
fetch method.http-request add-header x-mmdb1 %[ipv4(40.121.152.233),maxmind-lookup("CITY","city","names","en")]
Global parameters
The following directives apply in the global
section:
Directive | Description |
---|---|
| Loads a MaxMind database. |
where:
mlock_max <number>
Affects unprivileged HAProxy invocations and sets the maximum locked memory in bytes.
<db_type>
(required)Can be any of the following:
COUNTRY
CITY
ANONYMOUS
ISP
DOMAIN
CONNTYPE
ANY
Note
Database type identifiers are symbolic and do not undergo any check (i.e. a database containing city data is not checked as a CITY database type).
<db_path>
Sets a path and filename from which to load the database type of <db_type>.
Directive | Description |
---|---|
| Enables updating databases over HTTP from specified URLs:
|
where:
<db_type>
(required)Can be any of
CITY
COUNTRY
ISP
ANONYMOUS
Note
You must have already used the <db_type> with the
maxmind-load
global keyword.
<db_url>
(required)URL to connect to and download a new version of the database of type <db_type>.
delay <time value>
Specifies the delay between each attempt to download a new database version.
timeout <time value>
Specifies the HTTP connect timeout for attempts to download a new database version. The default value is in milliseconds, but you can specify any other unit if you add it as a suffix to the number (default: 5 milliseconds).
retries <number>
Specifies the number of retries to download a new database version. If unspecified, the global retries value applies (default: 3).
checksum
If present, it specifies to use a SHA1 checksum to verify that a newly downloaded database is identical to the current one. If they are identical, then a live-reload of the database does not take place, thereby preserving cache contents (if using caching)..
log
Specifies whether to log operation errors.
dontlog-normal
Deactivates logging for successful updates.
Directive | Description |
---|---|
| The size of the LRU cache used for lookups, defaults to 0. Setting to 0 disables cache. |
| Enables logging of unsuccessful IP address lookups, as well as logging of attempts to read unavailable fields from records of successfully looked up IP addresses. |
Converter
The maxmind-lookup
converter performs a lookup in the database and returns the value of the specified property. You can return nested properties by specifying each path element successively.
-
In the
frontend
,backend
, orlisten
section of the configuration file, add the following:# Used in the a frontend, listen, or backend section maxmind-lookup(<db_type>,<prop>[,<prop>*])
# Used in the a frontend, listen, or backend section
http-request add-header x-mmdb1 %[src,maxmind-lookup("CITY","city","names","en")]
http-request add-header x-mmdb3 %[src,maxmind-lookup("ISP","autonomous_system_number")]
Use the mmdblookup utility to look up an IP address in a MaxMind database file and learn the structure of the data.
-
Install the mmdblookup utility according to your platform:
$ sudo apt install mmdb-bin
or
$ dnf --enablerepo=PowerTools install libmaxminddb-devel
-
Look up an IP address. For this exercise, the IP value can be any routable address:
$ mmdblookup --file /etc/hapee-2.0/GeoLite2-City.mmdb --ip 40.121.152.233
This returns a JSON document, as shown below. Use the keys found here when setting the attributes of the
maxmind-lookup
converter. For example, to have HAProxy look up the English language city name for a client's IP address, use the keys city, names, and en.{ "city": { "geoname_id": 4792307 <uint32> "names": { "en": "Washington" <utf8_string> } } "continent": { "code": "NA" <utf8_string> "geoname_id": 6255149 <uint32> "names": { "de": "Nordamerika" <utf8_string> "en": "North America" <utf8_string> } } "country": { "geoname_id": 6252001 <uint32> "iso_code": "US" <utf8_string> "names": { "de": "USA" <utf8_string> "en": "United States" <utf8_string> } } "location": { "accuracy_radius": 1000 <uint16> "latitude": 38.709500 <double> "longitude": -78.153900 <double> "metro_code": 511 <uint16> "time_zone": "America/New_York" <utf8_string> } "postal": { "code": "22747" <utf8_string> } "registered_country": { "geoname_id": 6252001 <uint32> "iso_code": "US" <utf8_string> "names": { "de": "USA" <utf8_string> "en": "United States" <utf8_string> } } "subdivisions": [ { "geoname_id": 6254928 <uint32> "iso_code": "VA" <utf8_string> "names": { "en": "Virginia" <utf8_string> "fr": "Virginie" <utf8_string> } } ] }
HAProxy Runtime API
The following Runtime API commands are available:
| Disables the LRU cache. |
| Enables the LRU cache. |
| Invalidates the LRU cache. |
| Disables the database lookup engine. |
| Enables the database lookup engine. |
| Dumps the configuration set by the |
| Shows the module status. |
| Initiates the currently scheduled database type to attempt downloading immediately. |