HAProxy ALOHA Documentation 15.5


The MaxMind module provides geolocation lookups using MaxMind's GeoIP2 databases. This feature is available for use in layer 7 load balancer configurations.

Install the MaxMind databases

If the MaxMind databases have not already been installed, install them.

  1. Log into your account at the MaxMind website.

  2. Download the GeoIP databases.

  3. If your HAProxy ALOHA host is a virtual host instead of hardware, you need to create an additional partition large enough to contain the GeoIP databases.

  4. Use scp or Winscp to copy the databases to /app/extra on your HAProxy ALOHA server. Example:

    $ scp GeoIP2-City.mmdb admin@

Configure MaxMind on the LB Layer7 tab

  1. From the LB Layer7 tab, add a global section with the following lines:

        module-load maxmind.so
        maxmind-load mlock_max 512000000  CITY /app/extra/GeoIP2-City.mmdb  ISP /app/extra/GeoIP2-ISP.mmdb
        maxmind-cache-size 200000

    In this example:

    • The module-load directive enables the MaxMind feature.

    • The maxmind-load directive defines the geolocation databases to load. Each database file path is preceded by a database type, which can be ANONYMOUS, ANY, CITY, CONNTYPE, COUNTRY, DOMAIN, or ISP. The optional argument mlock_max affects unprivileged HAProxy ALOHA invocations and sets the maximum locked memory in bytes.

    • The maxmind-cache-size directive defines the size of the LRU cache used for lookups. It defaults to 0, which disables the cache.

  2. In frontend sections, add one or more maxmind-lookup directives to perform lookups that fetch geolocation properties. In the example below, we set several HTTP headers using geolocation properties:

    frontend www
       bind :80
       mode http
       http-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")]
  3. Click the LB Layer7 tab to open the layer 7 load balancer configuration.

  4. Add maxmind-lookup converters as needed.

  5. Click OK and then Apply to save the configuration.

  6. Go to the Setup tab and click Save under the Configuration section.

Discover properties

The mmdblookup utility enables you to perform look ups for IP addresses in a MaxMind database file and learn the structure of the data. For details, see mmdblookup.

  1. Look up an IP address. For this exercise, the IP value can be any routable address:

    $ mmdblookup --file /app/extra/GeoLite2-City.mmdb --ip

    This 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 ALOHA 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 from mmdblookup:

          "geoname_id": 4792307 <uint32>
             "en": "Washington" <utf8_string>
      // data continues...

Update the database during runtime

Use the MaxMind Update feature to keep the contents of the geolocation database current. This allows you to keep multiple HAProxy ALOHA nodes synced with the latest data.

  1. Install a web server of your choice and host the database file(s) at a URL that HAProxy ALOHA can access. For example, host the files at and

  2. Add the following lines to the global section of your configuration file, where the URL hosts an updated version of the file:

       # ... other global settings
       maxmind-update url CITY  url ISP  delay 24h  checksum  hash  log

With this configuration, HAProxy ALOHA downloads the database every 24 hours and displays a message in the logs when it succeeds or if it encountered errors during the update.


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:

maxmind-update url <db_type> <db_url>
   [url <db_type> <db_url>]*
   [delay <number>]
   [timeout <number>]
   [retries <number>]




Required. Can be ANONYMOUS, ANY, CITY, CONNTYPE, COUNTRY, DOMAIN, or ISP. You must have already used the <db_type> with the maxmind-load global keyword.


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).


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).


Specifies whether to log operation errors.


Deactivates logging for successful updates.

Next up

Global server load balancing