Geolocation with MaxMind

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 Jump to heading #

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 appliance instead of hardware, you need to create an additional partition large enough to contain the files.

   • Attach a new hard disk to the virtual machine. It should be 30 GB or larger.

     • Microsoft Hyper-V
     • VMware vSphere

   • Power on your HAProxy ALOHA Virtual Appliance.

   • Log in to your HAProxy ALOHA web UI as an administrator. The web UI runs at port 4444.

   • Select the Tools tab, then edit the file /etc/config.rc through the File Manager. Add the following directives at the end of the service system section, then click Save:

     text
     app_auto_mount
     app_auto_format
     app_device_size 30000000000

     text
     app_auto_mount
     app_auto_format
     app_device_size 30000000000

     where:

     • app_auto_mount automatically mounts the partition on /app.
     • app_auto_format automatically formats the /app partition, if needed.
     • app_device_size <Size in bytes> specifies the size in bytes of the /app partition. Here we set it to 30 GB.

   • Select the Setup tab, then click Save to save your modifications.

   • Restart HAProxy ALOHA.

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

   nix
   scp GeoIP2-City.mmdb admin@192.168.56.50:/app/extra

   nix
   scp GeoIP2-City.mmdb admin@192.168.56.50:/app/extra

Configure MaxMind on the LB Layer7 tab Jump to heading #

To configure MaxMind geolocation:

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

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

   haproxy
   global
     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:

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

   haproxy
   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 Jump to heading #

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:

   nix
   mmdblookup --file /app/extra/GeoLite2-City.mmdb --ip 40.121.152.233

   nix
   mmdblookup --file /app/extra/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 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:

   json
   {
      "city":
      {
         "geoname_id": 4792307 <uint32>
         "names":
         {
            "en": "Washington" <utf8_string>
         }
      }
     // data continues...
   }

   json
   {
      "city":
      {
         "geoname_id": 4792307 <uint32>
         "names":
         {
            "en": "Washington" <utf8_string>
         }
      }
     // data continues...
   }

Update the database during runtime Jump to heading #

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

   haproxy
   global
     # ... other global settings
     maxmind-update url CITY http://192.168.122.1:8000/GeoIP2-City.mmdb  url ISP http://192.168.122.1:8000/GeoIP2-ISP.mmdb  delay 24h  checksum  hash  log

   haproxy
   global
     # ... other global settings
     maxmind-update url CITY http://192.168.122.1:8000/GeoIP2-City.mmdb  url ISP http://192.168.122.1:8000/GeoIP2-ISP.mmdb  delay 24h  checksum  hash  log

   Tip

   Be sure to specify the port number where your file is hosted, for example, 8000 as in the example above.

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.

maxmind-update Jump to heading #

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:

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

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