This module provides GeoIP lookups using Digital Element's NetAcuity IP geolocation technology library and databases. More information about Digital Element's NetAcuity can be found on the Digital Element web site.

Install the Digital Element NetAcuity module

  1. Get the NetAcuity databases. If this is a .tar.gz file, unzip it and place the files in a directory served by your web server.

  2. Install the Digital Element NetAcuity module: apt install hapee-1.5r2-lb-netacuity (or yum install depending on your platform of choice).

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

    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
  4. Use the netacuity-lookup-ipv4 and/or netacuity-lookup-ipv6 converters to make use of the data:

    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 following directives are supported in the global section:

Directive

Description

netacuity-load <feature_code> <directory>
(required)

Specifies the local directory where the NetAcuity files are stored. Feature code is defined by the type of database.

For example, if your NetAcuity files are named 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)

This option enables updating databases over HTTP from the specified url. Updating a database with a newer version invalidates any cached lookups (if caching is used), unless checksum is enabled and the new and old database contents are identical. You should host the unzipped directory of files at this URL.

url <feature_code url> (required)

This option specifies the database update url. Feature code is defined by the type of database.

For example, if your NetAcuity files are named 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>

<u> specifies the period between each attempt to download a new database version. <s> specifies the initial (first) download delay. <b> specifies the delay between the download of each element of the database. If the download fails, <r> determines the delay for the next attempt.

Default values for <u>, <s>, <b> and <r> are 5m, 5s, 10s and 30s, respectively.

If after three attempts, the new version of the database can not be downloaded, the download is cancelled until the next time interval defined by <u>.

In this case, the downloaded data is discarded.

timeout <t>

Specifies the HTTP connect timeout for attempts to download a new database version. The value is specified in milliseconds by default, but can be in any other unit if the number is suffixed by the unit. Default is 5 seconds.

retries <n>

Specifies the number of retries to download a new NetAcuity database version. If unspecified, the global retries value is used (defaults to 3).

checksum

If present, determine 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 then live-reload of a database is not performed, preserving cache contents (if caching is used).

hash

If present, enables authentication of downloaded data. Each file being upgraded must have the associated file with a SHA1 checksum.

The SHA1 checksum file has the extension '.sha1' (without quotation marks). The typical way of creating the SHA1 checksum file is: sha1sum file > file.sha1

log

Specifies whether to log operation errors.

dontlog-normal

Deactivates logging of successful updates.

param*

A list of other server parameters, useful to configure special SSL features.

netacuity-cache-size <number>

The size of the LRU cache used for lookups, defaults to 0. Setting to 0 disables the cache. The maximum cache size is 10000000.

netacuity-debug <level>

Enables logging of unsuccessful IP address lookups, as well as loging of 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 number of rows is not specified, the entire file is loaded. This option can only be used when the module is compiled in debug mode, and in normal use it has no significance.

Converter

The netacuity-lookup-ipv4 and netacuity-lookup-ipv6 converters search the IPv4 and IPv6 NetAcuity databases, respectively, for the value of the specified entity. Several properties can be returned by specifying each element successively; in that case, the returned values are separated by a commas. There is one special property named src-ip, which shows the IP address of the client in IPv6 format.

The maximum number of properties in one lookup is eight. Valid property types are listed in the na_[feature code]_03.db file. For example, the na_04_03.db lists properties such as edge-country, edge-region, and edge-city.

Syntax:

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

Examples:

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:

lb-netacuity cache delete [n]

Delete the oldest n cache elements. If n is not set, the entire cache is deleted. This command can only be used when the module is compiled in debug mode and in normal use it has no significance.

lb-netacuity cache disable

Disables the cache.

lb-netacuity cache dump [n]

The first n elements of the cache is shown. If n is not set, it defaults to 5. The maximum value for n is 150. This command can only be used when the module is compiled in debug mode and in normal use it has no significance.

lb-netacuity cache enable

Enables the cache.

lb-netacuity cache invalidate

The entire cache is declared invalid.

lb-netacuity debug [level]

Set the debug level. The default debug level is 7. This command can only be used when the module is compiled in debug mode and in normal use it has no significance.

lb-netacuity disable

Disable the NetAcuity database lookup engine.

lb-netacuity enable

Enable the NetAcuity database lookup engine.

lb-netacuity get <ip>

Displays all of the data associated with the selected IP address. The IP address may be specified in IPv4 or IPv6 format. The query works regardless of whether the lookup engine is enabled or not. The query does not use the cache and the result is not cached. Note that only properties that are used in the HAProxy configuration file will have a value.

lb-netacuity status

The module status is displayed.

lb-netacuity update [delay]

Run the update at a time specified with the delay argument. If the delay is not specified (or the delay is 0), the update will be executed immediately. The delay cannot be greater than the time until the next regular update.

lb-netacuity test [count [size [type [threshold]]]]

Initiates a module operation check and prints database lookup speeds. Count is the number of tests to be performed, size is the number of different IPv4 addresses that are used in testing, type is used to select how to generate IPv4 addresses and threshold is a limit value that does not enter the calculation of the speed. Default values for count, size, type and threshold are 1000, 256, 0 and 0, respectively. This command can only be used when the module is compiled in debug mode and in normal use it has no significance.