NetAcuity
The NetAcuity module provides geolocation lookups using Digital Element's GeoIP databases.
Install the NetAcuity module
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-1.9/netacuity/).
-
Install the NetAcuity module according to your platform:
$ # On Debian/Ubuntu $ sudo apt-get install hapee-1.9r1-lb-netacuity$ # On CentOS/RedHat/Oracle $ sudo yum install hapee-1.9r1-lb-netacuity$ # On SUSE $ sudo zypper install hapee-1.9r1-lb-netacuity$ # On FreeBSD $ sudo pkg install hapee-1.9r1-lb-netacuity -
In the
globalsection of HAProxy Enterprise configuration, add the following lines:global module-load hapee-lb-netacuity.so netacuity-load 04/etc/hapee-1.9/netacuitynetacuity-cache-size 2000000 Reload the HAProxy Enterprise configuration to apply the changes.
Global directives
The module adds the following global directives:
Directive | Description |
|---|---|
| Required. Specifies the local directory where you store NetAcuity files. The |
| 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 |
| Enables logging for unsuccessful IP address lookups, as well as for attempts to read unavailable fields from records of successfully looked up IP addresses. |
| 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
netacuity-lookup-ipv4
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.
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-codespulse-citypulse-city-codepulse-city-confpulse-conn-speedpulse-conn-typepulse-continent-codepulse-countrypulse-country-codepulse-country-confpulse-gmt-offsetpulse-in-dstpulse-internal-codepulse-latitudepulse-longitudepulse-metro-codepulse-postal-codepulse-postal-confpulse-regionpulse-region-codepulse-region-confpulse-timezone-namepulse-two-letter-country
Syntax
netacuity-lookup-ipv4(<prop>[,<prop>*])Example: Set HTTP request headers that contain geolocation properties based on client's source IP address
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
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.
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-codespulse-citypulse-city-codepulse-city-confpulse-conn-speedpulse-conn-typepulse-continent-codepulse-countrypulse-country-codepulse-country-confpulse-gmt-offsetpulse-in-dstpulse-internal-codepulse-latitudepulse-longitudepulse-metro-codepulse-postal-codepulse-postal-confpulse-regionpulse-region-codepulse-region-confpulse-timezone-namepulse-two-letter-country
Syntax
netacuity-lookup-ipv6(<prop>[,<prop>*])Example: Set HTTP request headers that contain geolocation properties based on client's source IP address
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
Use the NetAcuity Update feature to keep the contents of the geolocation database current. This allows you to keep multiple instances of HAProxy Enterprise 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/netacuity.tar.gz. We recommend that you host the unzipped file directory at this URL.
Add the following lines to the
globalsection of your configuration file, where the URL hosts an updated version of the file:
global
# ... other global settings
netacuity-update url 04 http://192.168.122.1/netacuity.tar.gz delay 24h timeout 100ms retries 3 checksum hash logWith 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
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:
netacuity-update url <feature_code url>
[delay <u> | xdelay <u s b r>]
[timeout <t>]
[retries <n>]
[checksum]
[hash]
[log]
[dontlog-normal]
[param\*]where:
| 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. |
|
|
|
|
| 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. |
| Specifies the number of retries to download a new NetAcuity database version. If unspecified, the global |
| 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). |
| 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 |
| Specifies whether to log operation errors. |
| Deactivates logging for successful updates. |
| Lists other server parameters; useful to configure special SSL features. |
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.
|
Next up
Health Checking