Geolocation
Digital Element NetAcuity
Available since
- HAProxy Enterprise 1.8r1
The NetAcuity module provides geolocation lookups using Digital Element’s GeoIP databases.
Install the NetAcuity module Jump to heading
-
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-2.9/netacuity/
). -
Install the NetAcuity module according to your platform:
nixsudo apt-get install hapee-2.9r1-b-netacuitynixsudo apt-get install hapee-2.9r1-b-netacuitynixsudo yum install hapee-2.9r1-b-netacuitynixsudo yum install hapee-2.9r1-b-netacuitynixsudo zypper install hapee-2.9r1-b-netacuitynixsudo zypper install hapee-2.9r1-b-netacuitynixsudo pkg install hapee-2.9r1-b-netacuitynixsudo pkg install hapee-2.9r1-b-netacuity -
In the
global
section of HAProxy Enterprise configuration, add the following lines:haproxyglobalmodule-load hapee-lb-netacuity.sonetacuity-load 04 /etc/hapee-2.9/netacuitynetacuity-cache-size 2000000haproxyglobalmodule-load hapee-lb-netacuity.sonetacuity-load 04 /etc/hapee-2.9/netacuitynetacuity-cache-size 2000000 -
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 wwwbind :80mode httphttp-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 wwwbind :80mode httphttp-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 wwwbind :80mode httphttp-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 wwwbind :80mode httphttp-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.
-
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. -
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.haproxyglobal# ... other global settingsnetacuity-update url 04 http://192.168.122.1:8000/netacuity.tar.gz delay 24h timeout 100ms retries 3 checksum hash loghaproxyglobal# ... other global settingsnetacuity-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-2.9/hapee-lb.sock
nix
echo "lb-netacuity cache disable" | \sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
outputtext
NetAcuity: cache disabled
outputtext
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-2.9/hapee-lb.sock
nix
echo "lb-netacuity cache enable" | \sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
outputtext
NetAcuity: cache enabled
outputtext
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-2.9/hapee-lb.sock
nix
echo "lb-netacuity cache invalidate" | \sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
outputtext
NetAcuity: LRU cache invalidated
outputtext
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-2.9/hapee-lb.sock
nix
echo "lb-netacuity disable" | \sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
outputtext
NetAcuity: data lookup disabled
outputtext
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-2.9/hapee-lb.sock
nix
echo "lb-netacuity enable" | \sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
outputtext
NetAcuity: data lookup enabled
outputtext
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-2.9/hapee-lb.sock
nix
echo "lb-netacuity get 192.168.64.1" | \sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
outputtext
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
outputtext
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-2.9/hapee-lb.sock
nix
echo "lb-netacuity status" | \sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
outputtext
NetAcuity module status------------------------------------------------------------------------------initialized: yesDatabaseconfiguration: /etc/hapee-2.7/hapee-lb.cfg:34enabled: yesinvalid: nofeature code: 4directory: /etc/hapee-2.7/netacuitylookup separator: ","LRU cacheenabled: yesserial: 0 1usage/size: 0/2000000Database updateconfiguration: /etc/hapee-2.7/hapee-lb.cfg:37feature code: 4url: http://192.168.122.1:8000http status count: 0 4 0 0 0 / 0period/delay: 1d / 5s 10s 5suse checksum/hash: no / noreload/retry count: 1 0 0 / 0 0reload time: 2023-08-09 09:53:45 / <NEVER> / <NEVER>next update: na_04_01.db in 23h49m
outputtext
NetAcuity module status------------------------------------------------------------------------------initialized: yesDatabaseconfiguration: /etc/hapee-2.7/hapee-lb.cfg:34enabled: yesinvalid: nofeature code: 4directory: /etc/hapee-2.7/netacuitylookup separator: ","LRU cacheenabled: yesserial: 0 1usage/size: 0/2000000Database updateconfiguration: /etc/hapee-2.7/hapee-lb.cfg:37feature code: 4url: http://192.168.122.1:8000http status count: 0 4 0 0 0 / 0period/delay: 1d / 5s 10s 5suse checksum/hash: no / noreload/retry count: 1 0 0 / 0 0reload 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 specifed 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-2.9/hapee-lb.sock
nix
echo "lb-netacuity update 5m" | \sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
outputtext
NetAcuity: forcing update in 5m
outputtext
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-2.9/hapee-lb.sock
nix
echo "lb-netacuity status" | \sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
outputtext
NetAcuity module status------------------------------------------------------------------------------initialized: yesDatabaseconfiguration: /etc/hapee-2.7/hapee-lb.cfg:34enabled: yesinvalid: nofeature code: 4directory: /etc/hapee-2.7/netacuitylookup separator: ","LRU cacheenabled: yesserial: 0 1usage/size: 0/2000000Database updateconfiguration: /etc/hapee-2.7/hapee-lb.cfg:37feature code: 4url: http://192.168.64.1:8000http status count: 0 0 0 2 0 / 0period/delay: 1d / 5s 10s 5suse checksum/hash: yes / yesreload/retry count: 0 0 0 / 2 0reload time: <NEVER> / <NEVER> / <NEVER>currently updating: na_04_01.dbstatus/retry: 0 / 2data size: 0 / 0 (0.0%)dur/time left: 8s / 1s
outputtext
NetAcuity module status------------------------------------------------------------------------------initialized: yesDatabaseconfiguration: /etc/hapee-2.7/hapee-lb.cfg:34enabled: yesinvalid: nofeature code: 4directory: /etc/hapee-2.7/netacuitylookup separator: ","LRU cacheenabled: yesserial: 0 1usage/size: 0/2000000Database updateconfiguration: /etc/hapee-2.7/hapee-lb.cfg:37feature code: 4url: http://192.168.64.1:8000http status count: 0 0 0 2 0 / 0period/delay: 1d / 5s 10s 5suse checksum/hash: yes / yesreload/retry count: 0 0 0 / 2 0reload time: <NEVER> / <NEVER> / <NEVER>currently updating: na_04_01.dbstatus/retry: 0 / 2data 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?