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 the databases, similar to HAProxy's Update module for maps/ACLs.

Prerequisites

  • HAProxy Enterprise version 1.7 r2 or later

  • Subscription to MaxMind for databases

Install the MaxMind module

  1. Get the MaxMind databases.

  2. Install the MaxMind module according to your platform:

    apt install hapee-1.5r2-lb-maxmind

    or

    yum install hapee-1.5r2-lb-maxmind

  3. In the global section of your configuration, add the following lines:

    module-load hapee-lb-maxmind.so
maxmind-cache-size 200000
maxmind-debug
maxmind-load mlock_max 512000000  CITY /etc/hapee-1.9/GeoIP2-City.mmdb  ISP /etc/hapee-1.9/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

  4. Configure the module to listen to port 10080 so the converter maxmind-lookup can make use of the data:

    listen MaxMind-module-test
   bind *:10080
   mode http
   server localhost 127.0.0.1:8000
   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")]

Global parameters

The following directives apply in the global section:

Directive

Description

maxmind-load [mlock_max <number>] <db_type> <db_path> [<db_type> <db_path]>*] (required)

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

maxmind-update url <db_type> <db_url> [url <db_type> <db_url>]* [delay <number>] [timeout <number>] [retries <number>] [checksum] [log] [dontlog-normal] (required)

Enables updating databases over HTTP from specified URLs:

  • 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 using caching), unless you enable the checksum parameter, and the new and old database contents are identical.

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

maxmind-cache-size <number>

The size of the LRU cache used for lookups, defaults to 0. Setting to 0 disables cache.

maxmind-debug

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, or listen section of the configuration file, add the following:

    maxmind-lookup(<db_type>,<prop>[,<prop>*])
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")]

HAProxy Runtime API

The following Runtime API commands are available:

maxmind-update cache disable

Disables the LRU cache.

maxmind-update cache enable

Enables the LRU cache.

maxmind-update cache invalidate

Invalidates the LRU cache.

maxmind-update update disable

Disables the database lookup engine.

maxmind-update update enable

Enables the database lookup engine.

maxmind-update show

Dumps the configuration set by the maxmind-update global configuration directive.

maxmind-update status

Shows the module status.

maxmind-update force-update

Initiates the currently scheduled database type to attempt downloading immediately.