Searching HAProxy Enterprise 1.9r1
Performing Geolocation with NetAcuity
The NetAcuity module integrates with HAProxy to provide GeoIP lookups using Digital Element's IP geolocation technology library and databases.
For more information about NetAcuity, see the Digital Element website.
Tip
HAProxy Enterprise only: This module requires an active HAProxy Enterprise subscription. Please contact us if you would like to learn more or begin a free trial.
Prerequisites
Subscription to NetAcuity for databases
Install the NetAcuity module
Get the NetAcuity databases. If this is a .tar.gz file, unzip it and place the files in a directory on your web server.
-
Install the NetAcuity module as follows, depending on your platform:
$ sudo apt install hapee-1.9r1-lb-netacuity
or
$ sudo yum install hapee-1.9r1-lb-netacuity
Configure the NetAcuity module
-
In the
global
section of HAProxy's configuration file/etc/hapee-1.9r1/hapee-lb.conf
, add the following lines: (see the section Global parameters below)global # ... module-load hapee-lb-netacuity.so netacuity-cache-size 2000000 netacuity-debug 7 netacuity-property-separator , netacuity-load 04 /etc/haproxy/netacuity netacuity-update url 04 http://myserver.local:8000/netacuity xdelay 3m 5s 1s 1s timeout 100ms retries 3 checksum hash log netacuity-test-ipv4 /home/zaga/work/data/ipsc.txt 1000000
-
Add the
netacuity-lookup-ipv4
and/ornetacuity-lookup-ipv6
converters to make use of the data: (see the section Converters below)listen NetAcuity-module-test bind *:10080 mode http server localhost 127.0.0.1:8000 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")] 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")]
Global parameters
The NetAcuity module accepts the following directives in the global
section:
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 the feature code to 04.-
netacuity-update url <feature_code url> [delay <u> | xdelay <u s b r>] [timeout <t>] [retries <n>] [checksum] [hash] [log] [dontlog-normal] [param\*]
(required): Enables the module to update databases 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.
We recommend that you host the unzipped file directory at this URL. This directive contains the following settings:
url <feature_code url>
(required)Specifies URL for the database update. 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>
Delay 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: 3checksum
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 checksum.
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.
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: 0netacuity-debug <level>
: Enables logging for unsuccessful IP address lookups, as well as for attempts to read unavailable fields from records of successfully looked up IP addresses.netacuity-test-ipv4 <filename> [rows]
: If used, it allows loading IPv4 addresses from the input file. If you don't specify the number of rows, the module loads the entire file. Use this only when the module runs in debug mode; in normal use it has no significance.
Converters
The netacuity-lookup-ipv4
and netacuity-lookup-ipv6
converters search the IPv4 and IPv6 NetAcuity databases, respectively, for the value of the specified entity.
They can return several properties by specifying each element successively; in that case, the returned values are separated by commas.
The syntax for converters is as follows:
netacuity-lookup-ipv4(<prop>[,<prop>*])
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
# Used in the a frontend, listen, or backend section
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")]
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 Runtime API
The following Runtime API commands are available:
| Deletes the oldest n cache elements. If n is not set, the module deletes the entire cache. Use this only when the module runs in debug mode; in normal use it has no significance. |
| Disables the cache. |
| Shows the first n elements of the cache. If n is not set, it defaults to 5. The maximum value for n is 150. Use this only when the module runs in debug mode; in normal use it has no significance. |
| Enables the cache. |
| Declares the entire cache invalid. |
| Set the debug level. Use this only when the module runs in debug mode; in normal use it has no significance. Default: level 7 |
| Disables the NetAcuity database lookup engine. |
| Enables the NetAcuity database lookup engine. |
| Displays all the data associated with the selected IP address. You can specify the IP address in IPv4 or IPv6 format. The query works whether the lookup engine is enabled or not. The query does not use the cache and does not cache the result. |
| Displays the module status. |
| Runs the update at a time specified in the delay argument. If you don't specify the delay (or the delay is 0), the update executes immediately. The delay cannot exceed the time until the next regular update. |
| Initiates a module operation check and prints database lookup speeds. Use this only when the module runs in debug mode; in normal use it has no significance.
|