This module provides GeoIP lookups using libmaxminddb patched to use mlock on database files and to support loading from (pre-filled memory). Using multiple MaxMind databases is supported. The module also provides live updates of the databases, similar to our Update module for maps/ACLs.

Install the MaxMind module

  1. Get the MaxMind databases.

  2. Install the MaxMind module: apt install hapee-1.5r2-lb-maxmind (or yum install depending on your platform of choice).

  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. Use the maxmind-lookup converter to 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 are supported in the global section:

Directive

Description

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

Loads a MaxMind database.

mlock_max <number>

Affects unprivileged HAProxy invocations and sets the maximum locked memory in bytes.

<db_type> (required)

Can be any of

  • COUNTRY

  • CITY

  • ANONYMOUS

  • ISP

  • DOMAIN

  • CONNTYPE

  • ANY

Database type identifiers are symbolic and no check is performed to ensure that a database containing i.e. city data is loaded as a CITY database type.

<db_path>

sets a path and filename from which to load the database type of <db_type>.

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. Multiple database types and their respective URLs can be specified. If multiple database types are specified they will be downloaded sequentially with a delay between each one. Updating a database with a newer version invalidates any cached lookups (if caching is used), unless checksum is enabled and new and old database contents are identical.

<db_type> (required)

Can be any of

  • CITY

  • COUNTRY

  • ISP

  • ANONYMOUS

An additional restriction is that the used <db_type> must have been already used 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. If multiple database types are specified to be updated by downloading, this argument will introduce a delay between each database type download attempt. For example, with a delay of 10 minutes and 3 specified database types to update, the first database will be downloaded every 30 minutes. The value is specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit. Default is 5 minutes.

timeout <time value>

Specifies the HTTP connect timeout for attempts to download a new database version. The value is specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit. Default is 5 seconds.

retries <number>

Specifies the number of retries to download a new database version. If unspecified, the global retries value is used (defaults to 3).

checksum

If present specifies to use a SHA1 checksum to verify that a newly downloaded database is identical to the one already used. If they are identical then a live-reload of the database is not performed, preserving cache contents (if caching is used).

log

Specifies whether to log operation errors.

dontlog-normal

Deactivates logging of successful updates.

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 loging 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. Nested properties can be returned by specifying every path element successively.

Syntax:

maxmind-lookup(<db_type>,<prop>[,<prop>*])

Examples:

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.