Geolocation

MaxMind

On this page

Available since

  • HAProxy Enterprise 1.7r2

Using HAProxy Fusion?

If you’re using HAProxy Fusion, then see the HAProxy Fusion - MaxMind topic instead.

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

Install the MaxMind module Jump to heading

  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-3.0/GeoIP2-City.mmdb, /etc/hapee-3.0/GeoIP2-ISP.mmdb).

  2. Install the MaxMind module according to your platform:

    nix
    sudo apt-get install hapee-<VERSION>-lb-maxmind
    nix
    sudo apt-get install hapee-<VERSION>-lb-maxmind

    Example for HAProxy Enterprise 3.0r1:

    nix
    sudo apt-get install hapee-3.0r1-lb-maxmind
    nix
    sudo apt-get install hapee-3.0r1-lb-maxmind
    nix
    sudo yum install hapee-<VERSION>-lb-maxmind
    nix
    sudo yum install hapee-<VERSION>-lb-maxmind

    Example for HAProxy Enterprise 3.0r1:

    nix
    sudo yum install hapee-3.0r1-lb-maxmind
    nix
    sudo yum install hapee-3.0r1-lb-maxmind
    nix
    sudo zypper install hapee-<VERSION>-lb-maxmind
    nix
    sudo zypper install hapee-<VERSION>-lb-maxmind

    Example for HAProxy Enterprise 3.0r1:

    nix
    sudo zypper install hapee-3.0r1-lb-maxmind
    nix
    sudo zypper install hapee-3.0r1-lb-maxmind
    nix
    sudo pkg install hapee-<VERSION>-lb-maxmind
    nix
    sudo pkg install hapee-<VERSION>-lb-maxmind

    Example for HAProxy Enterprise 3.0r1:

    nix
    sudo pkg install hapee-3.0r1-lb-maxmind
    nix
    sudo pkg install hapee-3.0r1-lb-maxmind

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

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

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

Discover properties Jump to heading

  1. Install the mmdblookup utility. This utility enables you to perform look ups for IP addresses in a MaxMind database file and learn the structure of the data.

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

    nix
    mmdblookup --file /etc/hapee-3.0/GeoIP2-City.mmdb --ip 40.121.152.233
    nix
    mmdblookup --file /etc/hapee-3.0/GeoIP2-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:

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

    Alternatively, use the mmdbinspect utility:

    nix
    mmdbinspect -db /etc/hapee-3.0/GeoIP2-City.mmdb 40.121.152.233
    nix
    mmdbinspect -db /etc/hapee-3.0/GeoIP2-City.mmdb 40.121.152.233

Configure the MaxMind module Jump to heading

The module adds the following global directives:

maxmind-load Jump to heading

Required. Loads a MaxMind database.

Syntax:

text
maxmind-load [mlock_max <number>] <db_type> <db_path> [<db_type> <db_path]>*]
text
maxmind-load [mlock_max <number>] <db_type> <db_path> [<db_type> <db_path]>*]
Argument Description
mlock_max <number> Affects unprivileged HAProxy Enterprise invocations and sets the maximum locked memory in bytes. If you run HAProxy Enterprise in Docker, add the IPC_LOCK Linux capability when calling docker run in addition to setting mlock_max. sudo docker run --cap-add IPC_LOCK ...
<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 Jump to heading

Sets the size of the LRU cache used for lookups, defaults to 0. Setting to 0 disables cache.

Syntax:

text
maxmind-cache-size <number>
text
maxmind-cache-size <number>

Use converters to perform database lookups Jump to heading

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:

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

In this example we set HTTP request headers that contain CITY and ISP properties based on client’s source IP address.

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

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 Enterprise nodes 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: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. Be sure to specify the port number where your file is hosted, for example, 8000 as in the example below.

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

text
maxmind-update url <db_type> <db_url>
  [url <db_type> <db_url>]*
  [delay <number>]
  [timeout <number>]
  [retries <number>]
  [checksum]
  [log]
  [dontlog-normal]
text
maxmind-update url <db_type> <db_url>
  [url <db_type> <db_url>]*
  [delay <number>]
  [timeout <number>]
  [retries <number>]
  [checksum]
  [log]
  [dontlog-normal]
Argument Description
<db_type> Required. Can be any of the following: COUNTRY, CITY, ANONYMOUS, ISP, DOMAIN, CONNTYPE, ANY. 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 Jump to heading

It is possible to manage the MaxMind module via the Runtime API. For general information on using the runtime API, see HAProxy Enterprise Runtime API.

The supported commands are listed below.

maxmind-update cache disable Jump to heading

Disable the MaxMind LRU lookup cache.

If the MaxMind cache is enabled, each lookup is cached so that subsequent requests are loaded from the cache instead of the MaxMind database. The MaxMind module will perform all lookups in its database when the cache is disabled.

Below, we disable the cache:

nix
echo "maxmind-update cache disable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update cache disable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
output
text
MaxMindDb: cache disabled
output
text
MaxMindDb: cache disabled

maxmind-update cache enable Jump to heading

Enable the MaxMind LRU lookup cache.

If the MaxMind cache is enabled, each lookup is cached so that subsequent requests are loaded from the cache instead of the MaxMind database.

Below, we enable the cache:

nix
echo "maxmind-update cache enable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update cache enable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
output
text
MaxMindDb: cache enabled
output
text
MaxMindDb: cache enabled

maxmind-update cache invalidate Jump to heading

Invalidate the MaxMind lookup cache.

If the MaxMind cache is enabled, each lookup is cached so that subsequent requests are loaded from the cache instead of the MaxMind database. Invalidating the cache marks all entries in the cache invalid. After invalidating the cache, the MaxMind module will perform lookups in its database as it rebuilds its cache for subsequent requests.

Below, we invalidate the cache:

nix
echo "maxmind-update cache invalidate" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update cache invalidate" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
output
text
MaxMindDb: LRU cache invalidated
output
text
MaxMindDb: LRU cache invalidated

maxmind-update disable Jump to heading

Disable the MaxMind database lookup engine. When disabled, the MaxMind module does not perform lookups.

Below, we disable MaxMind lookups:

nix
echo "maxmind-update disable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update disable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
output
text
MaxMind: data lookup disabled
output
text
MaxMind: data lookup disabled

maxmind-update enable Jump to heading

Enable the MaxMind database lookup engine.

The MaxMind database lookup engine is enabled automatically upon installation. You may need to re-enable it if you have manually disabled it.

Below, we enable MaxMind lookups:

nix
echo "maxmind-update enable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update enable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
output
text
MaxMind: data lookup enabled
output
text
MaxMind: data lookup enabled

maxmind-update update Jump to heading

Force an update of the MaxMind database.

The MaxMind update module will update the database based on the interval you specified in the configuration. You can also force an update that will run immediately.

In this example, we want to force an update of the database.

nix
echo "maxmind-update force-update" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update force-update" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
output
text
MaxMindDb: forcing update now
output
text
MaxMindDb: forcing update now

You can check the status of the update using the maxmind-update status command. Note that while the update is processing, the status will show the progress.

nix
echo "maxmind-update status" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update status" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
output
text
MaxMindDb module status
------------------------------------------------------------------------------
 initialized:             yes
 
 Database
   configuration:         /etc/hapee-2.7/hapee-lb.cfg:31
   enabled:               yes
   invalid:               no
   CITY:                /etc/hapee-2.7/GeoIP2-City.mmdb
 
 LRU cache
   enabled:               yes
   serial:                0 1
   usage/size:            0/200000
 
 Database update
   configuration:         /etc/hapee-2.7/hapee-lb.cfg:32
     CITY:                http://192.168.64.1/GeoIP2-City.mmdb
       period/next:       1d / 23h59m
       http status count: 0 0 0 1 0 / 0
   use cksum/hash/mod:    yes / yes / no
   period/delay:          1d / 5s 10s 5s
   reload/retry count:    0 0 0 / 1 0
   reload time:           <NEVER> / <NEVER> / <NEVER>
   currently updating:    GeoIP2-City.mmdb
     status/retry:        0 / 0
     data size:           0 / 0 (0.0%)
     dur/time left:       0.837s / 4s
output
text
MaxMindDb module status
------------------------------------------------------------------------------
 initialized:             yes
 
 Database
   configuration:         /etc/hapee-2.7/hapee-lb.cfg:31
   enabled:               yes
   invalid:               no
   CITY:                /etc/hapee-2.7/GeoIP2-City.mmdb
 
 LRU cache
   enabled:               yes
   serial:                0 1
   usage/size:            0/200000
 
 Database update
   configuration:         /etc/hapee-2.7/hapee-lb.cfg:32
     CITY:                http://192.168.64.1/GeoIP2-City.mmdb
       period/next:       1d / 23h59m
       http status count: 0 0 0 1 0 / 0
   use cksum/hash/mod:    yes / yes / no
   period/delay:          1d / 5s 10s 5s
   reload/retry count:    0 0 0 / 1 0
   reload time:           <NEVER> / <NEVER> / <NEVER>
   currently updating:    GeoIP2-City.mmdb
     status/retry:        0 / 0
     data size:           0 / 0 (0.0%)
     dur/time left:       0.837s / 4s

maxmind-update show Jump to heading

Display the configuration of the MaxMind module.

You can dump the configuration for the MaxMind module using the maxmind-update show command. The output of this command includes information about each configured database file and its update status.

Below, we retrieve the status information for our configured databases:

nix
echo "maxmind-update show" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update show" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
output
text
# maxmind-update configuration
# <db_type> url: <configured_url>
"CITY" url: http://192.168.64.1/GeoIP2-City.mmdb
# Next update is "CITY" in 23h42m
output
text
# maxmind-update configuration
# <db_type> url: <configured_url>
"CITY" url: http://192.168.64.1/GeoIP2-City.mmdb
# Next update is "CITY" in 23h42m

maxmind-update status Jump to heading

Display the status of the MaxMind module.

The MaxMind module maintains some statistics about its operations. The maxmind-update status command provides information about its configuration and cache.

The results of the maxmind-update status command show information about the current state of its cache, as well as information about updates to its database.

nix
echo "maxmind-update status" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
nix
echo "maxmind-update status" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock
output
text
MaxMindDb module status
------------------------------------------------------------------------------
 initialized:             yes
 
 Database
   configuration:         /etc/hapee-2.7/hapee-lb.cfg:31
   enabled:               yes
   invalid:               no
    CITY:                /etc/hapee-2.7/GeoIP2-City.mmdb
 
 LRU cache
   enabled:               yes
   serial:                -1 -1
   usage/size:            0/200000
 
 Database update
   configuration:         /etc/hapee-2.7/hapee-lb.cfg:32
     CITY:                http://192.168.64.1:8000/GeoIP2-City.mmdb
   period/next:       1d / 23h58m
   http status count: 0 1 0 0 0 / 0
   use cksum/hash/mod:    no / no / no
   period/delay:          1d / 5s 10s 5s
   reload/retry count:    1 0 0 / 0 0
   reload time:           2023-08-09 10:13:21 / <NEVER> / <NEVER>
output
text
MaxMindDb module status
------------------------------------------------------------------------------
 initialized:             yes
 
 Database
   configuration:         /etc/hapee-2.7/hapee-lb.cfg:31
   enabled:               yes
   invalid:               no
    CITY:                /etc/hapee-2.7/GeoIP2-City.mmdb
 
 LRU cache
   enabled:               yes
   serial:                -1 -1
   usage/size:            0/200000
 
 Database update
   configuration:         /etc/hapee-2.7/hapee-lb.cfg:32
     CITY:                http://192.168.64.1:8000/GeoIP2-City.mmdb
   period/next:       1d / 23h58m
   http status count: 0 1 0 0 0 / 0
   use cksum/hash/mod:    no / no / no
   period/delay:          1d / 5s 10s 5s
   reload/retry count:    1 0 0 / 0 0
   reload time:           2023-08-09 10:13:21 / <NEVER> / <NEVER>

Do you have any suggestions on how we can improve the content of this page?

Previous page Digital Element Next page Global Profiling Engine
© 2024 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences