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:

   $ sudo apt install hapee-1.7r2-lb-maxmind

   or

   $ sudo yum install hapee-1.7r2-lb-maxmind

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

   global
       # ...
       module-load hapee-lb-maxmind.so
       maxmind-cache-size 200000
       maxmind-debug
       maxmind-load mlock_max 512000000  CITY /etc/hapee-1.7/GeoIP2-City.mmdb  ISP /etc/hapee-1.7/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. In the frontend, backend or listen section where you want to enable geolocation, add one or more http-request add-header lines that use the src fetch method and maxmind-lookup converter.

   In the following example, four HTTP request headers x-mmdb1 through x-mmdb4 are assigned values from the MaxMind CITY and ISP database files. They look up the city name, country, autonomous system number, and autonomous system organization for the client's source IP address:

   # Used in the a frontend, listen, or backend section
       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")]

   Note

   If you are hosting HAProxy at localhost, you can still test geolocation by replacing src in the previous example with a hardcoded IP address. Use the ipv4 fetch method.

   http-request add-header x-mmdb1 %[ipv4(40.121.152.233),maxmind-lookup("CITY","city","names","en")]

Global parameters

The following directives apply in the global section:

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

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.

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:

  # Used in the a frontend, listen, or backend section
      maxmind-lookup(<db_type>,<prop>[,<prop>*])

# Used in the a frontend, listen, or backend section
    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")]

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

• Install the mmdblookup utility according to your platform:

  $ sudo apt install mmdb-bin

  or

  $ dnf --enablerepo=PowerTools install libmaxminddb-devel

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

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

  This returns a JSON document, as shown below. Use the keys found here when setting the attributes of the maxmind-lookup converter. For example, to have HAProxy look up the English language city name for a client's IP address, use the keys city, names, and en.

   {
    "city":
      {
        "geoname_id":
          4792307 <uint32>
        "names":
          {
            "en":
              "Washington" <utf8_string>
          }
      }
    "continent":
      {
        "code":
          "NA" <utf8_string>
        "geoname_id":
          6255149 <uint32>
        "names":
          {
            "de":
              "Nordamerika" <utf8_string>
            "en":
              "North America" <utf8_string>
          }
      }
    "country":
      {
        "geoname_id":
          6252001 <uint32>
        "iso_code":
          "US" <utf8_string>
        "names":
          {
            "de":
              "USA" <utf8_string>
            "en":
              "United States" <utf8_string>
          }
      }
    "location":
      {
        "accuracy_radius":
          1000 <uint16>
        "latitude":
          38.709500 <double>
        "longitude":
          -78.153900 <double>
        "metro_code":
          511 <uint16>
        "time_zone":
          "America/New_York" <utf8_string>
      }
    "postal":
      {
        "code":
          "22747" <utf8_string>
      }
    "registered_country":
      {
        "geoname_id":
          6252001 <uint32>
        "iso_code":
          "US" <utf8_string>
        "names":
          {
            "de":
              "USA" <utf8_string>
            "en":
              "United States" <utf8_string>
          }
      }
    "subdivisions":
      [
        {
          "geoname_id":
            6254928 <uint32>
          "iso_code":
            "VA" <utf8_string>
          "names":
            {
              "en":
                "Virginia" <utf8_string>
              "fr":
                "Virginie" <utf8_string>
            }
        }
      ]
  }

HAProxy Runtime API

The following Runtime API commands are available: