HAProxy Enterprise Documentation 1.7r1

MaxMind

The MaxMind module provides geolocation lookups using MaxMind's GeoIP2 databases.

Install the MaxMind module

  1. Log into your account at the MaxMind website and download the GeoIP databases. Copy them to your HAProxy Enterprise server (e.g. /etc/hapee-1.7/GeoIP2-City.mmdb, /etc/hapee-1.7/GeoIP2-ISP.mmdb).

  2. Install the MaxMind module according to your platform:

    $ # On Debian/Ubuntu
$ sudo apt-get install hapee-1.7r1-lb-maxmind
    $ # On CentOS/RedHat/Oracle
$ sudo yum install hapee-1.7r1-lb-maxmind

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

    global
    module-load hapee-lb-maxmind.so
    maxmind-load mlock_max 512000000  CITY /etc/hapee-1.7/GeoIP2-City.mmdb  ISP /etc/hapee-1.7/GeoIP2-ISP.mmdb
    maxmind-cache-size 200000

  4. Reload the HAProxy Enterprise configuration to apply the changes.

Global directives

The module adds the following global directives:

Directive

Description

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

Required. Loads a MaxMind database.

Parameters

Description

mlock_max <number>

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

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

maxmind-lookup

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

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

Set HTTP request headers that contain CITY and ISP properties based on client's source IP address

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")]

Discover properties

Use the mmdblookup utility to look up an IP address in a MaxMind database file and learn the structure of the data.

  1. Install the mmdblookup utility according to your platform:

    $ # On Debian/Ubuntu
$ sudo apt install mmdb-bin

$ # On CentOS/RedHat
$ dnf --enablerepo=PowerTools install libmaxminddb-devel

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

    $ mmdblookup --file /etc/hapee-1.7/GeoLite2-City.mmdb --ip 40.121.152.233

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

    {
   "city":
   {
      "geoname_id": 4792307 <uint32>
      "names":
      {
         "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 instances of HAProxy Enterprise synced with the latest data.

  1. 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/GeoIP2-City.mmdb and http://192.168.122.1/GeoIP2-ISP.mmdb.

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

    global
   # ... other global settings
   maxmind-update url CITY http://192.168.122.1/GeoIP2-City.mmdb  url ISP http://192.168.122.1/GeoIP2-ISP.mmdb  delay 24h  checksum  hash  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

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>]
   [checksum]
   [log]
   [dontlog-normal]

Parameters

Description

<db_type>

Required. Can be any of the following: - CITY - COUNTRY - ISP - ANONYMOUS

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

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.

Next up

Health Checking