Geolocation
MaxMind
Available since
- HAProxy Enterprise 1.7r2
Using HAProxy Fusion?
If you’re using HAProxy Fusion, then see the HAProxy Fusion - MaxMind topic instead.
The MaxMind module provides geolocation lookups using MaxMind’s GeoIP2 databases.
Install the MaxMind module Jump to heading
-
Log into your account at the MaxMind website and download the GeoIP databases. Copy them to your HAProxy Enterprise server (e.g.
/etc/hapee-3.0/GeoIP2-City.mmdb
,/etc/hapee-3.0/GeoIP2-ISP.mmdb
). -
Install the MaxMind module according to your platform:
nixsudo apt-get install hapee-<VERSION>-lb-maxmindnixsudo apt-get install hapee-<VERSION>-lb-maxmindExample for HAProxy Enterprise 3.0r1:
nixsudo apt-get install hapee-3.0r1-lb-maxmindnixsudo apt-get install hapee-3.0r1-lb-maxmindnixsudo yum install hapee-<VERSION>-lb-maxmindnixsudo yum install hapee-<VERSION>-lb-maxmindExample for HAProxy Enterprise 3.0r1:
nixsudo yum install hapee-3.0r1-lb-maxmindnixsudo yum install hapee-3.0r1-lb-maxmindnixsudo zypper install hapee-<VERSION>-lb-maxmindnixsudo zypper install hapee-<VERSION>-lb-maxmindExample for HAProxy Enterprise 3.0r1:
nixsudo zypper install hapee-3.0r1-lb-maxmindnixsudo zypper install hapee-3.0r1-lb-maxmindnixsudo pkg install hapee-<VERSION>-lb-maxmindnixsudo pkg install hapee-<VERSION>-lb-maxmindExample for HAProxy Enterprise 3.0r1:
nixsudo pkg install hapee-3.0r1-lb-maxmindnixsudo pkg install hapee-3.0r1-lb-maxmind -
In the
global
section of your configuration, add the following lines:haproxyglobalmodule-load hapee-lb-maxmind.somaxmind-load mlock_max 512000000 CITY /etc/hapee-3.0/GeoIP2-City.mmdb ISP /etc/hapee-3.0/GeoIP2-ISP.mmdbmaxmind-cache-size 200000haproxyglobalmodule-load hapee-lb-maxmind.somaxmind-load mlock_max 512000000 CITY /etc/hapee-3.0/GeoIP2-City.mmdb ISP /etc/hapee-3.0/GeoIP2-ISP.mmdbmaxmind-cache-size 200000 -
Reload the HAProxy Enterprise configuration to apply the changes.
Discover properties Jump to heading
-
Install the mmdblookup utility. This utility enables you to perform look ups for IP addresses in a MaxMind database file and learn the structure of the data.
-
Look up an IP address. For this exercise, the IP value can be any routable address:
nixmmdblookup --file /etc/hapee-3.0/GeoIP2-City.mmdb --ip 40.121.152.233nixmmdblookup --file /etc/hapee-3.0/GeoIP2-City.mmdb --ip 40.121.152.233This returns a JSON document, as shown below. Use the document’s structure to find a property to use with the
maxmind-lookup
converter. For example, to have HAProxy Enterprise look up the English language city name for a client’s IP address, use the keys city, names, and en as represented in the JSON returned frommmdblookup
:json{"city":{"geoname_id": 4792307 <uint32>"names":{"en": "Washington" <utf8_string>}}// data continues...}json{"city":{"geoname_id": 4792307 <uint32>"names":{"en": "Washington" <utf8_string>}}// data continues...}Alternatively, use the mmdbinspect utility:
nixmmdbinspect -db /etc/hapee-3.0/GeoIP2-City.mmdb 40.121.152.233nixmmdbinspect -db /etc/hapee-3.0/GeoIP2-City.mmdb 40.121.152.233
Configure the MaxMind module Jump to heading
The module adds the following global
directives:
maxmind-load Jump to heading
Required. Loads a MaxMind database.
Syntax:
text
maxmind-load [mlock_max <number>] <db_type> <db_path> [<db_type> <db_path]>*]
text
maxmind-load [mlock_max <number>] <db_type> <db_path> [<db_type> <db_path]>*]
Argument | Description |
---|---|
mlock_max <number> |
Affects unprivileged HAProxy Enterprise invocations and sets the maximum locked memory in bytes. If you run HAProxy Enterprise in Docker, add the IPC_LOCK Linux capability when calling docker run in addition to setting mlock_max . sudo docker run --cap-add IPC_LOCK ... |
<db_type> |
It can be one of the following: COUNTRY, CITY, ANONYMOUS, ISP, DOMAIN, CONNTYPE, ANY. |
<db_path> |
Sets a path and filename from which to load the database type of <db_type> . |
maxmind-cache-size Jump to heading
Sets the size of the LRU cache used for lookups, defaults to 0. Setting to 0 disables cache.
Syntax:
text
maxmind-cache-size <number>
text
maxmind-cache-size <number>
Use converters to perform database lookups Jump to heading
Use the converter maxmind-lookup
to perform a lookup in the database that returns the values of the specified property. Properties in the MaxMind database are stored hierarchically. For example, you can find the name of a city in English at city > names > en
.
Syntax:
text
maxmind-lookup(<db_type>,<prop-level1>[,<prop-level2>*])
text
maxmind-lookup(<db_type>,<prop-level1>[,<prop-level2>*])
In this example we set HTTP request headers that contain CITY and ISP properties based on client’s source IP address.
haproxy
frontend wwwbind :80mode httphttp-request add-header X-CityName %[src,maxmind-lookup("CITY","city","names","en")]http-request add-header X-ISOCode %[src,maxmind-lookup("CITY","country","iso_code")]http-request add-header X-ASN %[src,maxmind-lookup("ISP","autonomous_system_number")]http-request add-header X-ASNOrg %[src,maxmind-lookup("ISP","autonomous_system_organization")]
haproxy
frontend wwwbind :80mode httphttp-request add-header X-CityName %[src,maxmind-lookup("CITY","city","names","en")]http-request add-header X-ISOCode %[src,maxmind-lookup("CITY","country","iso_code")]http-request add-header X-ASN %[src,maxmind-lookup("ISP","autonomous_system_number")]http-request add-header X-ASNOrg %[src,maxmind-lookup("ISP","autonomous_system_organization")]
Update the database during runtime Jump to heading
Use the MaxMind Update feature to keep the contents of the geolocation database current. This allows you to keep multiple HAProxy Enterprise nodes synced with the latest data.
-
Install a web server of your choice and host the database file(s) at a URL where HAProxy Enterprise can access. For example, host the files at
http://192.168.122.1:8000/GeoIP2-City.mmdb
andhttp://192.168.122.1:8000/GeoIP2-ISP.mmdb
. -
Add the following lines to the
global
section of your configuration file, where the URL hosts an updated version of the file. Be sure to specify the port number where your file is hosted, for example,8000
as in the example below.haproxyglobal# ... other global settingsmaxmind-update url CITY http://192.168.122.1:8000/GeoIP2-City.mmdb url ISP http://192.168.122.1:8000/GeoIP2-ISP.mmdb delay 24h checksum loghaproxyglobal# ... other global settingsmaxmind-update url CITY http://192.168.122.1:8000/GeoIP2-City.mmdb url ISP http://192.168.122.1:8000/GeoIP2-ISP.mmdb delay 24h checksum log
With this configuration, HAProxy Enterprise downloads the database every 24 hours and displays a message in the logs when it succeeds or if it encountered errors during the update.
maxmind-update Jump to heading
The maxmind-update
directive enables updating the database over HTTP from a specified URL. You can specify multiple database types and their respective URLs. If there are multiple database types specified, they will download sequentially with a delay between each download. Updating a database with a newer version invalidates any cached lookups (if caching is used), unless you enable checksum
and the new and old database contents are identical.
The directive supports the following syntax:
text
maxmind-update url <db_type> <db_url>[url <db_type> <db_url>]*[delay <number>][timeout <number>][retries <number>][checksum][log][dontlog-normal]
text
maxmind-update url <db_type> <db_url>[url <db_type> <db_url>]*[delay <number>][timeout <number>][retries <number>][checksum][log][dontlog-normal]
Argument | Description |
---|---|
<db_type> |
Required. Can be any of the following: COUNTRY, CITY, ANONYMOUS, ISP, DOMAIN, CONNTYPE, ANY. 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. |
Runtime API Jump to heading
It is possible to manage the MaxMind module via the Runtime API. For general information on using the runtime API, see HAProxy Enterprise Runtime API.
The supported commands are listed below.
maxmind-update cache disable Jump to heading
Disable the MaxMind LRU lookup cache.
If the MaxMind cache is enabled, each lookup is cached so that subsequent requests are loaded from the cache instead of the MaxMind database. The MaxMind module will perform all lookups in its database when the cache is disabled.
Below, we disable the cache:
nix
echo "maxmind-update cache disable" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update cache disable" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
outputtext
MaxMindDb: cache disabled
outputtext
MaxMindDb: cache disabled
maxmind-update cache enable Jump to heading
Enable the MaxMind LRU lookup cache.
If the MaxMind cache is enabled, each lookup is cached so that subsequent requests are loaded from the cache instead of the MaxMind database.
Below, we enable the cache:
nix
echo "maxmind-update cache enable" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update cache enable" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
outputtext
MaxMindDb: cache enabled
outputtext
MaxMindDb: cache enabled
maxmind-update cache invalidate Jump to heading
Invalidate the MaxMind lookup cache.
If the MaxMind cache is enabled, each lookup is cached so that subsequent requests are loaded from the cache instead of the MaxMind database. Invalidating the cache marks all entries in the cache invalid. After invalidating the cache, the MaxMind module will perform lookups in its database as it rebuilds its cache for subsequent requests.
Below, we invalidate the cache:
nix
echo "maxmind-update cache invalidate" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update cache invalidate" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
outputtext
MaxMindDb: LRU cache invalidated
outputtext
MaxMindDb: LRU cache invalidated
maxmind-update disable Jump to heading
Disable the MaxMind database lookup engine. When disabled, the MaxMind module does not perform lookups.
Below, we disable MaxMind lookups:
nix
echo "maxmind-update disable" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update disable" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
outputtext
MaxMind: data lookup disabled
outputtext
MaxMind: data lookup disabled
maxmind-update enable Jump to heading
Enable the MaxMind database lookup engine.
The MaxMind database lookup engine is enabled automatically upon installation. You may need to re-enable it if you have manually disabled it.
Below, we enable MaxMind lookups:
nix
echo "maxmind-update enable" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update enable" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
outputtext
MaxMind: data lookup enabled
outputtext
MaxMind: data lookup enabled
maxmind-update update Jump to heading
Force an update of the MaxMind database.
The MaxMind update module will update the database based on the interval you specifed in the configuration. You can also force an update that will run immediately.
In this example, we want to force an update of the database.
nix
echo "maxmind-update force-update" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update force-update" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
outputtext
MaxMindDb: forcing update now
outputtext
MaxMindDb: forcing update now
You can check the status of the update using the maxmind-update status
command. Note that while the update is processing, the status will show the progress.
nix
echo "maxmind-update status" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update status" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
outputtext
MaxMindDb module status------------------------------------------------------------------------------initialized: yesDatabaseconfiguration: /etc/hapee-2.7/hapee-lb.cfg:31enabled: yesinvalid: noCITY: /etc/hapee-2.7/GeoIP2-City.mmdbLRU cacheenabled: yesserial: 0 1usage/size: 0/200000Database updateconfiguration: /etc/hapee-2.7/hapee-lb.cfg:32CITY: http://192.168.64.1/GeoIP2-City.mmdbperiod/next: 1d / 23h59mhttp status count: 0 0 0 1 0 / 0use cksum/hash/mod: yes / yes / noperiod/delay: 1d / 5s 10s 5sreload/retry count: 0 0 0 / 1 0reload time: <NEVER> / <NEVER> / <NEVER>currently updating: GeoIP2-City.mmdbstatus/retry: 0 / 0data size: 0 / 0 (0.0%)dur/time left: 0.837s / 4s
outputtext
MaxMindDb module status------------------------------------------------------------------------------initialized: yesDatabaseconfiguration: /etc/hapee-2.7/hapee-lb.cfg:31enabled: yesinvalid: noCITY: /etc/hapee-2.7/GeoIP2-City.mmdbLRU cacheenabled: yesserial: 0 1usage/size: 0/200000Database updateconfiguration: /etc/hapee-2.7/hapee-lb.cfg:32CITY: http://192.168.64.1/GeoIP2-City.mmdbperiod/next: 1d / 23h59mhttp status count: 0 0 0 1 0 / 0use cksum/hash/mod: yes / yes / noperiod/delay: 1d / 5s 10s 5sreload/retry count: 0 0 0 / 1 0reload time: <NEVER> / <NEVER> / <NEVER>currently updating: GeoIP2-City.mmdbstatus/retry: 0 / 0data size: 0 / 0 (0.0%)dur/time left: 0.837s / 4s
maxmind-update show Jump to heading
Display the configuration of the MaxMind module.
You can dump the configuration for the MaxMind module using the maxmind-update show
command. The output of this command includes information about each configured database file and its update status.
Below, we retrieve the status information for our configured databases:
nix
echo "maxmind-update show" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update show" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
outputtext
# maxmind-update configuration# <db_type> url: <configured_url>"CITY" url: http://192.168.64.1/GeoIP2-City.mmdb# Next update is "CITY" in 23h42m
outputtext
# maxmind-update configuration# <db_type> url: <configured_url>"CITY" url: http://192.168.64.1/GeoIP2-City.mmdb# Next update is "CITY" in 23h42m
maxmind-update status Jump to heading
Display the status of the MaxMind module.
The MaxMind module maintains some statistics about its operations. The maxmind-update status
command provides information about its configuration and cache.
The results of the maxmind-update status
command show information about the current state of its cache, as well as information about updates to its database.
nix
echo "maxmind-update status" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update status" | \sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
outputtext
MaxMindDb module status------------------------------------------------------------------------------initialized: yesDatabaseconfiguration: /etc/hapee-2.7/hapee-lb.cfg:31enabled: yesinvalid: noCITY: /etc/hapee-2.7/GeoIP2-City.mmdbLRU cacheenabled: yesserial: -1 -1usage/size: 0/200000Database updateconfiguration: /etc/hapee-2.7/hapee-lb.cfg:32CITY: http://192.168.64.1:8000/GeoIP2-City.mmdbperiod/next: 1d / 23h58mhttp status count: 0 1 0 0 0 / 0use cksum/hash/mod: no / no / noperiod/delay: 1d / 5s 10s 5sreload/retry count: 1 0 0 / 0 0reload time: 2023-08-09 10:13:21 / <NEVER> / <NEVER>
outputtext
MaxMindDb module status------------------------------------------------------------------------------initialized: yesDatabaseconfiguration: /etc/hapee-2.7/hapee-lb.cfg:31enabled: yesinvalid: noCITY: /etc/hapee-2.7/GeoIP2-City.mmdbLRU cacheenabled: yesserial: -1 -1usage/size: 0/200000Database updateconfiguration: /etc/hapee-2.7/hapee-lb.cfg:32CITY: http://192.168.64.1:8000/GeoIP2-City.mmdbperiod/next: 1d / 23h58mhttp status count: 0 1 0 0 0 / 0use cksum/hash/mod: no / no / noperiod/delay: 1d / 5s 10s 5sreload/retry count: 1 0 0 / 0 0reload time: 2023-08-09 10:13:21 / <NEVER> / <NEVER>
Do you have any suggestions on how we can improve the content of this page?