DeviceAtlas provides a common device identifier to understand device traffic across all connected environments.

This module enables device identification using HTTP headers to allow administrators to make decisions based on the device type, among other properties. It also provides live updates of databases, similar to HAProxy's Update module for maps/ACLs.


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.

Install the DeviceAtlas module

  1. Get the DeviceAtlas database (JSON file) from

  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:

    $ sudo apt install hapee-1.9r1-lb-da


    $ sudo yum install hapee-1.9r1-lb-da

Configure the DeviceAtlas module

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

        deviceatlas-json-file <path to json file>

Update the database during runtime

  1. Install the package hapee-1.9r1-lb-da-update.

  2. Add following to the global section of your configuration file:

        deviceatlas-update url delay 24h log

With this configuration, HAProxy downloads the database every 24 hours, and displays a message in the logs when it succeeds or if it encountered errors during the update.

Global parameters

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



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.

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



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*] (required)

Enables updating the database over HTTP from the specified URL. Updating a database with a newer version invalidates any cached lookups (if caching is used), unless you enable checksum and new and old database contents are identical. See parameters below.


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).


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.


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.


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


Specifies whether to log operation errors.


Deactivates logging of successful updates.


Lists other server parameters that are useful for configuring SSL features.


When you set parameters for maxmind-update, the options checksum and modified are mutually exclusive. If you define them at the same time, the option modified automatically switches off and a warning message prints when HAProxy starts.


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


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

This creates an HTTP request header that looks like this: X-Deviceatlas-Data: Desktop|Windows 10|NT 10.0|Firefox|68.|Gecko.

HAProxy 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.

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.

Transmit DeviceAtlas data downstream to the target application

  • From all HTTP headers via the sample fetch:

    # Used in the a frontend, listen, or backend section
        http-request set-header X-DeviceAtlas-Data %[da-csv-fetch(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]
  • From a single HTTP header (e.g. User-Agent) via the converter:

    # Used in the a frontend, listen, or backend section
        http-request set-header X-DeviceAtlas-Data %[req.fhdr(User-Agent),da-csv-conv(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]

Switch mobile content with ACL

  • From all HTTP headers via the sample fetch:

    # Used in the a frontend, listen, or backend section
        acl is_mobile da-csv-fetch(mobileDevice) 1
  • From a single HTTP header:

    # Used in the a frontend, listen, or backend section
        acl device_type_tablet req.fhdr(User-Agent),da-csv-conv(primaryHardwareType) "Tablet"