Geolocation

Digital Element NetAcuity

On this page

This page applies to:

  • HAProxy Enterprise 1.8r1 and newer

The NetAcuity module provides geolocation lookups using Digital Element’s GeoIP databases.

Install the NetAcuity module Jump to heading

  1. Log into your account at the Digital Element website and download the NetAcuity database .tar.gz file. Extract the contents of the file and place them in a directory on your HAProxy Enterprise server (e.g. /etc/hapee-3.1/netacuity/).

  2. Install the NetAcuity module according to your platform:

    nix
    sudo apt-get install hapee-<VERSION>-b-netacuity
    nix
    sudo apt-get install hapee-<VERSION>-b-netacuity

    Example for HAProxy Enterprise 3.1r1:

    nix
    sudo apt-get install hapee-3.1r1-b-netacuity
    nix
    sudo apt-get install hapee-3.1r1-b-netacuity
    nix
    sudo yum install hapee-<VERSION>-b-netacuity
    nix
    sudo yum install hapee-<VERSION>-b-netacuity

    Example for HAProxy Enterprise 3.1r1:

    nix
    sudo yum install hapee-3.1r1-b-netacuity
    nix
    sudo yum install hapee-3.1r1-b-netacuity
    nix
    sudo zypper install hapee-<VERSION>-b-netacuity
    nix
    sudo zypper install hapee-<VERSION>-b-netacuity

    Example for HAProxy Enterprise 3.1r1:

    nix
    sudo zypper install hapee-3.1r1-b-netacuity
    nix
    sudo zypper install hapee-3.1r1-b-netacuity
    nix
    sudo pkg install hapee-<VERSION>-b-netacuity
    nix
    sudo pkg install hapee-<VERSION>-b-netacuity

    Example for HAProxy Enterprise 3.1r1:

    nix
    sudo pkg install hapee-3.1r1-b-netacuity
    nix
    sudo pkg install hapee-3.1r1-b-netacuity

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

    haproxy
    global
      module-path /opt/hapee-3.1/modules/
      module-load hapee-lb-netacuity.so
      netacuity-load 04 /etc/hapee-3.1/netacuity
      netacuity-cache-size 2000000
    haproxy
    global
      module-path /opt/hapee-3.1/modules/
      module-load hapee-lb-netacuity.so
      netacuity-load 04 /etc/hapee-3.1/netacuity
      netacuity-cache-size 2000000

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

Configure the NetAcuity module Jump to heading

The module adds the following global directives:

Directive Description
netacuity-load <feature_code> <directory> Required. Specifies the local directory where you store NetAcuity files. The <feature_code> depends on the type of database. For example, if you name your NetAcuity files na_04_01.db, na_04_02.db, etc., then set it to 04.
netacuity-cache-size <number> Specifies the size of the LRU cache used for lookups. The minimum size of 0 disables the cache. The maximum cache size is 10000000. Default: 0

Use converters to perform database lookups Jump to heading

netacuity-lookup-ipv4 Jump to heading

Use the converter netacuity-lookup-ipv4 to perform a lookup in the IPv4 database that returns the values of the specified properties. It can return several properties by specifying each successively; In that case, the returned values are separated by commas.

Syntax:

text
netacuity-lookup-ipv4(<prop>[,<prop>*])
text
netacuity-lookup-ipv4(<prop>[,<prop>*])

The maximum number of properties in one lookup is eight. Valid property types are:

  • src-ip (Note: This property shows the IP address of the client in IPv6 format.)
  • pulse-area-codes
  • pulse-city
  • pulse-city-code
  • pulse-city-conf
  • pulse-conn-speed
  • pulse-conn-type
  • pulse-continent-code
  • pulse-country
  • pulse-country-code
  • pulse-country-conf
  • pulse-gmt-offset
  • pulse-in-dst
  • pulse-internal-code
  • pulse-latitude
  • pulse-longitude
  • pulse-metro-code
  • pulse-postal-code
  • pulse-postal-conf
  • pulse-region
  • pulse-region-code
  • pulse-region-conf
  • pulse-timezone-name
  • pulse-two-letter-country

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

haproxy
frontend www
  bind :80
  mode http
  http-request add-header X-NetAcuity-IPv4-1 %[src,netacuity-lookup-ipv4("src-ip","pulse-area-codes","pulse-city","pulse-city-code","pulse-city-conf","pulse-conn-speed","pulse-conn-type","pulse-continent-code")]
  http-request add-header X-NetAcuity-IPv4-2 %[src,netacuity-lookup-ipv4("pulse-country","pulse-country-code","pulse-country-conf","pulse-gmt-offset","pulse-in-dst","pulse-internal-code","pulse-latitude","pulse-longitude")]
  http-request add-header X-NetAcuity-IPv4-3 %[src,netacuity-lookup-ipv4("pulse-metro-code","pulse-postal-code","pulse-postal-conf","pulse-region","pulse-region-code","pulse-region-conf","pulse-timezone-name","pulse-two-letter-country")]
haproxy
frontend www
  bind :80
  mode http
  http-request add-header X-NetAcuity-IPv4-1 %[src,netacuity-lookup-ipv4("src-ip","pulse-area-codes","pulse-city","pulse-city-code","pulse-city-conf","pulse-conn-speed","pulse-conn-type","pulse-continent-code")]
  http-request add-header X-NetAcuity-IPv4-2 %[src,netacuity-lookup-ipv4("pulse-country","pulse-country-code","pulse-country-conf","pulse-gmt-offset","pulse-in-dst","pulse-internal-code","pulse-latitude","pulse-longitude")]
  http-request add-header X-NetAcuity-IPv4-3 %[src,netacuity-lookup-ipv4("pulse-metro-code","pulse-postal-code","pulse-postal-conf","pulse-region","pulse-region-code","pulse-region-conf","pulse-timezone-name","pulse-two-letter-country")]

netacuity-lookup-ipv6 Jump to heading

Use the converter netacuity-lookup-ipv6 to perform a lookup in the IPv6 database that returns the values of the specified properties. It can return several properties by specifying each successively; In that case, the returned values are separated by commas.

Syntax:

text
netacuity-lookup-ipv6(<prop>[,<prop>*])
text
netacuity-lookup-ipv6(<prop>[,<prop>*])

The maximum number of properties in one lookup is eight. Valid property types are:

  • src-ip (Note: This property shows the IP address of the client in IPv6 format.)
  • pulse-area-codes
  • pulse-city
  • pulse-city-code
  • pulse-city-conf
  • pulse-conn-speed
  • pulse-conn-type
  • pulse-continent-code
  • pulse-country
  • pulse-country-code
  • pulse-country-conf
  • pulse-gmt-offset
  • pulse-in-dst
  • pulse-internal-code
  • pulse-latitude
  • pulse-longitude
  • pulse-metro-code
  • pulse-postal-code
  • pulse-postal-conf
  • pulse-region
  • pulse-region-code
  • pulse-region-conf
  • pulse-timezone-name
  • pulse-two-letter-country

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

haproxy
frontend www
  bind :80
  mode http
  http-request add-header X-NetAcuity-IPv6-1 %[src,netacuity-lookup-ipv6("src-ip","pulse-area-codes","pulse-city","pulse-city-code","pulse-city-conf","pulse-conn-speed","pulse-conn-type","pulse-continent-code")]
  http-request add-header X-NetAcuity-IPv6-2 %[src,netacuity-lookup-ipv6("pulse-country","pulse-country-code","pulse-country-conf","pulse-gmt-offset","pulse-in-dst","pulse-internal-code","pulse-latitude","pulse-longitude")]
  http-request add-header X-NetAcuity-IPv6-3 %[src,netacuity-lookup-ipv6("pulse-metro-code","pulse-postal-code","pulse-postal-conf","pulse-region","pulse-region-code","pulse-region-conf","pulse-timezone-name","pulse-two-letter-country")]
haproxy
frontend www
  bind :80
  mode http
  http-request add-header X-NetAcuity-IPv6-1 %[src,netacuity-lookup-ipv6("src-ip","pulse-area-codes","pulse-city","pulse-city-code","pulse-city-conf","pulse-conn-speed","pulse-conn-type","pulse-continent-code")]
  http-request add-header X-NetAcuity-IPv6-2 %[src,netacuity-lookup-ipv6("pulse-country","pulse-country-code","pulse-country-conf","pulse-gmt-offset","pulse-in-dst","pulse-internal-code","pulse-latitude","pulse-longitude")]
  http-request add-header X-NetAcuity-IPv6-3 %[src,netacuity-lookup-ipv6("pulse-metro-code","pulse-postal-code","pulse-postal-conf","pulse-region","pulse-region-code","pulse-region-conf","pulse-timezone-name","pulse-two-letter-country")]

Update the database during runtime Jump to heading

Use the NetAcuity 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 at a URL where HAProxy Enterprise can access. For example, host the files at http://192.168.122.1:8000/netacuity.tar.gz. We recommend that you host the unzipped file directory at this URL.

  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
      netacuity-update url 04 http://192.168.122.1:8000/netacuity.tar.gz delay 24h  timeout 100ms  retries 3  checksum  hash  log
    haproxy
    global
      # ... other global settings
      netacuity-update url 04 http://192.168.122.1:8000/netacuity.tar.gz delay 24h  timeout 100ms  retries 3  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.

netacuity-update Jump to heading

The netacuity-update directive enables updating the database over HTTP from a specified URL. Updating a database with a newer version invalidates any cached lookups (if using cache), unless you enable the checksum setting and the new and old database contents are identical.

The directive supports the following syntax:

text
netacuity-update url <feature_code url>
  [delay <u> | xdelay <u s b r>]
  [timeout <t>]
  [retries <n>]
  [checksum]
  [hash]
  [log]
  [dontlog-normal]
  [param\*]
text
netacuity-update url <feature_code url>
  [delay <u> | xdelay <u s b r>]
  [timeout <t>]
  [retries <n>]
  [checksum]
  [hash]
  [log]
  [dontlog-normal]
  [param\*]

where:

Argument Description
url <feature_code url> Required. Specifies URL for the database update. We recommend that you host the unzipped file directory at this URL. The feature code depends on the type of database. For example, if you name your NetAcuity files na_04_01.db, na_04_02.db, etc., then set the feature code to 04.
delay <u> <u> specifies the period between each attempt to download a new database version. The delay is a simplified version of the xdelay keyword.
xdelay <u s b r> xdelay settings are defined as follows: <u> specifies the period between each attempt to download a new database version. Default: 5m. <s> specifies the initial (first) download delay. Default: 5s. <b> specifies the delay between the download of each element of the database. Default: 10s. If the download fails, <r> determines the delay for the next attempt. Default: 30s. If the new version of the database fails to download after three attempts, the module cancels the download until the next time interval specified by <u>. In this case, it discards the downloaded data.
timeout <t> Specifies the HTTP connection timeout for attempts to download a new database version. The value is in milliseconds by default, but you can set it to any other unit if you add it as a suffix to the number. Default: 5s.
retries <n> Specifies the number of retries to download a new NetAcuity database version. If unspecified, the global retries value applies. Default: 3
checksum If present, determines the use of the SHA1 control sum to verify that the content of the recently downloaded database is identical to the one already used. If they are identical, the module does not do a live-reload of the database, thereby preserving cache contents (if you use caching).
hash If present, enables authentication of downloaded data. Each upgraded file must have the associated file with a SHA1 check The SHA1 checksum file has the extension .sha1. The typical way to create the SHA1 checksum file is: sha1sum file > file.sha1
log Specifies whether to log operation errors.
dontlog-normal Deactivates logging for successful updates.
param* Lists other server parameters; useful to configure special SSL features.

Runtime API Jump to heading

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

lb-netacuity cache disable Jump to heading

Disable the NetAcuity lookup cache.

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

Below, we disable the cache:

nix
echo "lb-netacuity cache disable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
nix
echo "lb-netacuity cache disable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
output
text
NetAcuity: cache disabled
output
text
NetAcuity: cache disabled

lb-netacuity cache enable Jump to heading

Enable the NetAcuity lookup cache.

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

Below, we enable the cache:

nix
echo "lb-netacuity cache enable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
nix
echo "lb-netacuity cache enable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
output
text
NetAcuity: cache enabled
output
text
NetAcuity: cache enabled

lb-netacuity cache invalidate Jump to heading

Invalidate the NetAcuity lookup cache.

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

Below, we invalidate the cache:

nix
echo "lb-netacuity cache invalidate" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
nix
echo "lb-netacuity cache invalidate" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
output
text
NetAcuity: LRU cache invalidated
output
text
NetAcuity: LRU cache invalidated

lb-netacuity disable Jump to heading

Disable the NetAcuity database lookup engine.

When disabled, the NetAcuity module does not perform lookups.

Below, we disable NetAcuity lookups:

nix
echo "lb-netacuity disable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
nix
echo "lb-netacuity disable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
output
text
NetAcuity: data lookup disabled
output
text
NetAcuity: data lookup disabled

lb-netacuity enable Jump to heading

Enable the NetAcuity database lookup engine.

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

Below, we enable NetAcuity lookups:

nix
echo "lb-netacuity enable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
nix
echo "lb-netacuity enable" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
output
text
NetAcuity: data lookup enabled
output
text
NetAcuity: data lookup enabled

lb-netacuity get Jump to heading

Display all the data associated with the specified IP address.

You can retrieve all of the data associated with a specified IP address. This query works even if the NetAcuity module is disabled and the result of the query is not cached. The query is performed against the database and not the cache. You can specify the IP address in IPv4 or IPv6 format.

Retrieve the NetAcuity database information for the IP address 192.168.64.1 by specifying that IP address with the lb-netacuity get command:

nix
echo "lb-netacuity get 192.168.64.1" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
nix
echo "lb-netacuity get 192.168.64.1" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
output
text
NetAcuity 192.168.64.1 data
-------------------------------------------------------------
edge-area-codes: (null)
edge-city: (null)
edge-city-code: (null)
edge-city-conf: (null)
edge-conn-speed: (null)
edge-continent-code: (null)
edge-country: (null)
edge-country-code: (null)
edge-country-conf: (null)
edge-gmt-offset: (null)
edge-in-dst: (null)
edge-internal-code: (null)
edge-latitude: (null)
edge-longitude: (null)
edge-metro-code: (null)
edge-postal-code: (null)
edge-postal-conf: (null)
edge-region: (null)
edge-region-code: (null)
edge-region-conf: (null)
edge-timezone-name: (null)
edge-two-letter-country: (null)
keys: 22/32 slots, 378/1024 byte(s) used; data: 0/187 byte(s) used
output
text
NetAcuity 192.168.64.1 data
-------------------------------------------------------------
edge-area-codes: (null)
edge-city: (null)
edge-city-code: (null)
edge-city-conf: (null)
edge-conn-speed: (null)
edge-continent-code: (null)
edge-country: (null)
edge-country-code: (null)
edge-country-conf: (null)
edge-gmt-offset: (null)
edge-in-dst: (null)
edge-internal-code: (null)
edge-latitude: (null)
edge-longitude: (null)
edge-metro-code: (null)
edge-postal-code: (null)
edge-postal-conf: (null)
edge-region: (null)
edge-region-code: (null)
edge-region-conf: (null)
edge-timezone-name: (null)
edge-two-letter-country: (null)
keys: 22/32 slots, 378/1024 byte(s) used; data: 0/187 byte(s) used

lb-netacuity status Jump to heading

Display the status of the NetAcuity module.

The NetAcuity module maintains some statistics about its operations. The lb-netacuity status command provides information about its configuration and cache.

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

nix
echo "lb-netacuity status" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
nix
echo "lb-netacuity status" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
output
text
NetAcuity module status
------------------------------------------------------------------------------
 initialized:           yes
 
 Database
   configuration:       /etc/hapee-2.7/hapee-lb.cfg:34
   enabled:             yes
   invalid:             no
   feature code:        4
   directory:           /etc/hapee-2.7/netacuity
   lookup separator:    ","
 
 LRU cache
   enabled:             yes
   serial:              0 1
   usage/size:          0/2000000
 
 Database update
   configuration:       /etc/hapee-2.7/hapee-lb.cfg:37
   feature code:        4
   url:                 http://192.168.122.1:8000
   http status count:   0 4 0 0 0 / 0
   period/delay:        1d / 5s 10s 5s
   use checksum/hash:   no / no
   reload/retry count:  1 0 0 / 0 0
   reload time:         2023-08-09 09:53:45 / <NEVER> / <NEVER>
   next update:         na_04_01.db in 23h49m
output
text
NetAcuity module status
------------------------------------------------------------------------------
 initialized:           yes
 
 Database
   configuration:       /etc/hapee-2.7/hapee-lb.cfg:34
   enabled:             yes
   invalid:             no
   feature code:        4
   directory:           /etc/hapee-2.7/netacuity
   lookup separator:    ","
 
 LRU cache
   enabled:             yes
   serial:              0 1
   usage/size:          0/2000000
 
 Database update
   configuration:       /etc/hapee-2.7/hapee-lb.cfg:37
   feature code:        4
   url:                 http://192.168.122.1:8000
   http status count:   0 4 0 0 0 / 0
   period/delay:        1d / 5s 10s 5s
   use checksum/hash:   no / no
   reload/retry count:  1 0 0 / 0 0
   reload time:         2023-08-09 09:53:45 / <NEVER> / <NEVER>
   next update:         na_04_01.db in 23h49m

lb-netacuity update Jump to heading

Force an update of the NetAcuity database.

The NetAcuity update module will update the database based on the interval you specified in the configuration. You can also force an update by specifying the time you would like the update to run, for example, 5 minutes from now. If you don’t specify a time, or set the update delay to zero, the update will run immediately. The delay time you specify cannot exceed the time until the next regular update, otherwise you will receive an error message similar to “NetAcuity: the specified delay time is further than the time of the next update (3s), cancelling request”.

In this example, we want the update to run 5 minutes from now so we specify 5m as the delay time.

nix
echo "lb-netacuity update 5m" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
nix
echo "lb-netacuity update 5m" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
output
text
NetAcuity: forcing update in 5m
output
text
NetAcuity: forcing update in 5m

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

nix
echo "lb-netacuity status" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
nix
echo "lb-netacuity status" | \
  sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock
output
text
      NetAcuity module status
      ------------------------------------------------------------------------------
      initialized:           yes
      
      Database
        configuration:       /etc/hapee-2.7/hapee-lb.cfg:34
        enabled:             yes
        invalid:             no
        feature code:        4
        directory:           /etc/hapee-2.7/netacuity
        lookup separator:    ","
      
      LRU cache
        enabled:             yes
        serial:              0 1
        usage/size:          0/2000000
       
       Database update
        configuration:       /etc/hapee-2.7/hapee-lb.cfg:37
        feature code:        4
        url:                 http://192.168.64.1:8000
        http status count:   0 0 0 2 0 / 0
        period/delay:        1d / 5s 10s 5s
        use checksum/hash:   yes / yes
        reload/retry count:  0 0 0 / 2 0
        reload time:         <NEVER> / <NEVER> / <NEVER>
        currently updating:  na_04_01.db
            status/retry:      0 / 2
            data size:         0 / 0 (0.0%)
            dur/time left:     8s / 1s
output
text
      NetAcuity module status
      ------------------------------------------------------------------------------
      initialized:           yes
      
      Database
        configuration:       /etc/hapee-2.7/hapee-lb.cfg:34
        enabled:             yes
        invalid:             no
        feature code:        4
        directory:           /etc/hapee-2.7/netacuity
        lookup separator:    ","
      
      LRU cache
        enabled:             yes
        serial:              0 1
        usage/size:          0/2000000
       
       Database update
        configuration:       /etc/hapee-2.7/hapee-lb.cfg:37
        feature code:        4
        url:                 http://192.168.64.1:8000
        http status count:   0 0 0 2 0 / 0
        period/delay:        1d / 5s 10s 5s
        use checksum/hash:   yes / yes
        reload/retry count:  0 0 0 / 2 0
        reload time:         <NEVER> / <NEVER> / <NEVER>
        currently updating:  na_04_01.db
            status/retry:      0 / 2
            data size:         0 / 0 (0.0%)
            dur/time left:     8s / 1s

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

Previous page Geolocation Next page MaxMind
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences