Install the DeviceAtlas module

1. Get the DeviceAtlas database (JSON file) from https://deviceatlas.com/deviceatlas-haproxy-module.

2. After you extract the file, run the following command:

   $ make TARGET=<target> USE_PCRE=1 USE_DEVICEATLAS=1 DEVICEATLAS_SRC=<path to the API root folder>

3. Install the DeviceAtlas module according to your platform:

   apt install hapee-1.9r1-lb-da

   or

   yum install hapee-1.9r1-lb-da

Configure the DeviceAtlas module

• In the global section of the HAProxy configuration file, add the following:

  module-load hapee-lb-da.so
  deviceatlas-json-file <path to json file>

Global parameters

The global section for the hapee-lb-da module supports the following directives:

The global section for the hapee-lb-da-update module supports the following directives:

where:

url <url> required	Specifies the database update URL. The updated data can be either JSON or precompiled JSON.
delay <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 are: u = 5m, s = 5s, b = 10s, and r = 30s
timeout <t>	Specifies the HTTP connection timeout for attempts to download a new database version. The value is set in milliseconds by default, but you can set it to any other unit if you add a unit suffix to the number. Defaults to 5 seconds.
retries <n>	Specifies the number of retries to download a new DeviceAtlas database version. If not set, the global retries value applies (defaults to 3).
checksum	If set, determines the use of the SHA1 control sum to verify that the contents of the recently downloaded database is identical to the current one. If they are identical, then live-reload of the database does not occur, thereby preserving the cached contents (if using caching). See note below.
hash	If set, enables authentication of the downloaded data. Each file undergoing upgrade must have the associated file with SHA1 checksum. A SHA1 checksum file has the extension .sha1. The typical way of creating a SHA1 checksum file is: sha1sum file > file.sha1.
modified	Specifies the use of the time from the Last-Modified response HTTP header. Example: checks whether to update the data using the If-Modified-Since request HTTP header. See note below.
source <addr>[:<port>]	Sets the source address for outgoing connections. <addr> is the IPv4 address HAProxy binds to before it connects to a server The default value is 0.0.0.0 to let the system select the most optimal address to reach its destination <port> is optional The default value of zero means that the system selects a free port Does not support port ranges
log	Specifies whether to log operation errors.
dontlog-normal	Deactivates logging of successful updates.
param*	Lists other server parameters that are useful for configuring SSL features.

Converter

HAProxy uses the converter da-csv-conv converter to perform a lookup in the database and returns the values of the specified properties.

Syntax:

da-csv-conv(<prop>[,<prop>*])

listen DeviceAtlas-module-test
bind *:10080
mode http
server localhost 127.0.0.1:8000
http-request set-header X-DeviceAtlas-Data %[req.hdr(user-agent),da-csv-conv(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]

HAProxy Runtime API

The following Runtime API commands are available:

DeviceAtlas use cases

There are two distinct methods available when using DeviceAtlas: one that leverages all HTTP headers, and one that uses only a single HTTP header for detection. We recommend the "All HTTP headers" method because it's more accurate.