HAProxy Enterprise Documentation 2.5r1

DeviceAtlas

The DeviceAtlas module provides device detection services using the DeviceAtlas database.

Install the DeviceAtlas module

  1. Log into your account at the DeviceAtlas website and download the Enterprise API C library. Copy libda.so to your HAProxy Enterprise server into the directory /lib/x86_64-linux-gnu/.

  2. From your DeviceAtlas account, download the Device Data (JSON) file. Copy it to your HAProxy Enterprise server (e.g. /etc/hapee-2.5/deviceatlas.json).

  3. Install the DeviceAtlas module according to your platform:

    $ # On Debian/Ubuntu
$ sudo apt-get install hapee-2.5r1-lb-da
    $ # On CentOS/RedHat/Oracle/Photon OS
$ sudo yum install hapee-2.5r1-lb-da
    $ # On SUSE
$ sudo zypper install hapee-2.5r1-lb-da
    $ # On FreeBSD
$ sudo pkg install hapee-2.5r1-lb-da

  4. In the global section of the HAProxy Enterprise configuration file, add the following:

    global
   module-load hapee-lb-da.so
   deviceatlas-json-file /etc/hapee-2.5/deviceatlas.json

  5. Reload the HAProxy Enterprise configuration to apply the changes.

Global directives

The module adds the following global directives:

Directive

Description

deviceatlas-json-file <path> (required)

Loads a DeviceAtlas database.

deviceatlas-property-separator <separator>

Specifies the separator to use within the output. Defaults to a pipe symbol (|).

deviceatlas-log-level <level>

Sets the log level, which can be set to a number between 0 and 3 (defaults to 0):

  • 0: Fatal

  • 1: Errors

  • 2: Warnings

  • 3: Information (most verbose)

deviceatlas-properties-cookie <cookie-name>

The name of the DeviceAtlas Client-side Component cookie, if using client-side properties. Defaults to DAPROPS.

Fetches and Converters

da-csv-fetch

Use the fetch method da-csv-fetch to perform a lookup in the database that returns the values of the specified properties.

Syntax

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

Example: Create an HTTP request header that contains device information

frontend www
   bind :80
   mode http
   http-request set-header X-DeviceInfo %[da-csv-fetch(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]

Example: Define an ACL named is_mobile

frontend www
   bind :80
   mode http
   acl is_mobile da-csv-fetch(mobileDevice) 1

da-csv-conv

Use the converter da-csv-conv to perform a lookup in the database that returns the values of the specified properties. It takes the User-Agent header as an input parameter:

Syntax:

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

Example: Create an HTTP request header that contains device information

frontend www
   bind :80
   mode http
   http-request set-header X-DeviceInfo %[req.hdr(user-agent),da-csv-conv(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]

Update the database during runtime

Use the DeviceAtlas Update module to keep the contents of the device detection database current. This allows you to keep multiple HAProxy Enterprise nodes synced with the latest data.

  1. Install a Web server of your choice and host the database file at a URL where HAProxy Enterprise can access. For example, host the file at http://192.168.122.1/deviceatlas.json.

  2. Install the package hapee-2.5r1-lb-da-update:

    $ # On Debian/Ubuntu
$ sudo apt-get install hapee-2.5r1-lb-da-update
    $ # On CentOS/RedHat/Oracle/Photon OS
$ sudo yum install hapee-2.5r1-lb-da-update
    $ # On SUSE
$ sudo zypper install hapee-2.5r1-lb-da-update
    $ # On FreeBSD
$ sudo pkg install hapee-2.5r1-lb-da-update

  3. Add the following lines to the global section of your configuration file, where the URL hosts an updated version of the file:

    global
   # ... other global settings
   module-load hapee-lb-da-update.so
   deviceatlas-update url http://192.168.122.1/deviceatlas.json delay 24h 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.

deviceatlas-update

The deviceatlas-update directive enables updating the database over HTTP from a specified URL. Updating a database with a newer version invalidates any cached lookups (if caching is used), unless you enable checksum and the new and old database contents are identical.

The directive supports the following syntax:

deviceatlas-update url <url>
   [delay <u> | xdelay <u s b r>]
   [timeout <t>]
   [retries <n>]
   [checksum]
   [hash]
   [modified]
   [source <addr>[:<port>]]
   [log]
   [dontlog-normal]
   [param*]

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 vers - 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 seco

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 d - 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.sh

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 connecti - <addr> is the IPv4 address HAProxy Enterprise 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 ra

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.

Runtime API

The following Runtime API commands are available:

da-update debug [level]

Sets the debug level. The default is 7. Use this command only when the module runs in debug mode; in normal use, it has no significance.

da-update mem-info [iec]

Provides instrumentation describing space usage.

  • If you do not set the iec argument (or set it to 0), the size of memory appears only as a number.

  • If you set this argument to 1, all sizes appear in a human-readable format (e.g. 1023, 16.1K, 768M, 1.2G). Use this command only when the module runs in debug mode; in normal use, it has no significance.

da-update show

Displays the module configuration.

da-update status

Displays the module status.

da-update update [delay]

Runs the update at a time specified with the delay argument.

  • If you don't set the delay (or set it to 0), then the update executes immediately.

  • The delay cannot be greater than the time until the next regular update.

Next up

WURFL InFuze