DeviceAtlas

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

Install the DeviceAtlas module Jump to heading #

1. Go to the DeviceAtlas website and sign up for the DeviceAtlas for Web product. Then sign in to access the API data file. Depending on which version of HAProxy Enterprise you’re running, download the compatible data file. You can set this on the DeviceAtlas Data File Options page.

   • For HAProxy Enterprise 3.0r1 and newer, use a 3.x API data file.
   • For HAProxy Enterprise 2.9r1 and older, use a 2.x API data file.

2. Download the API data file as a zip file and extract the zip file to get the .json data file. The file has a name like 72277_20241104.json, but you can rename it to deviceatlas.json. Copy the JSON data file to your HAProxy Enterprise server. Example: /etc/hapee-3.0/deviceatlas.json.

3. Download the Enterprise API for C library as a zip file. You’ll need the 3.x or 2.x library, depending on which version of HAProxy Enterprise you’re using.

   To compile the library, follow the guide on the DeviceAtlas website, DeviceAtlas Device API Usage C. This step requires you to transfer the zip file to Linux, FreeBSD, or Mac, since those operating systems have the necessary build tools. For example, on Debian/Ubuntu, run:

   nix
   sudo apt update
   sudo apt install -y --no-install-recommends build-essential cmake unzip
   unzip deviceatlas-enterprise-c-3.2.3.zip
   cd deviceatlas-enterprise-c-3.2.3
   cmake -DNO_CURL=ON .
   sudo make

   nix
   sudo apt update
   sudo apt install -y --no-install-recommends build-essential cmake unzip
   unzip deviceatlas-enterprise-c-3.2.3.zip
   cd deviceatlas-enterprise-c-3.2.3
   cmake -DNO_CURL=ON .
   sudo make

4. Copy the compiled C library from Src/libda.so.3 to your HAProxy Enterprise server.

   • For the 3.x library, copy it as /lib/x86_64-linux-gnu/libda.so.3 on Ubuntu/Debian or /lib/lib64/libda.so.3 on RedHat Enterprise Linux.
   • For the 2.x library, copy it as /lib/x86_64-linux-gnu/libda.so.2 on Ubuntu/Debian or /lib/lib64/libda.so.2 on RedHat Enterprise Linux.

5. On your HAProxy Enterprise server, install the DeviceAtlas module according to your platform:

   apt yum zypper pkg

   nix
   sudo apt-get install hapee-<VERSION>-lb-da

   nix
   sudo apt-get install hapee-<VERSION>-lb-da

   Example for HAProxy Enterprise 3.0r1:

   nix
   sudo apt-get install hapee-3.0r1-lb-da

   nix
   sudo apt-get install hapee-3.0r1-lb-da

   nix
   sudo yum install hapee-<VERSION>-lb-da

   nix
   sudo yum install hapee-<VERSION>-lb-da

   Example for HAProxy Enterprise 3.0r1:

   nix
   sudo yum install hapee-3.0r1-lb-da

   nix
   sudo yum install hapee-3.0r1-lb-da

   nix
   sudo zypper install hapee-<VERSION>-lb-da

   nix
   sudo zypper install hapee-<VERSION>-lb-da

   Example for HAProxy Enterprise 3.0r1:

   nix
   sudo zypper install hapee-3.0r1-lb-da

   nix
   sudo zypper install hapee-3.0r1-lb-da

   nix
   sudo pkg install hapee-<VERSION>-lb-da

   nix
   sudo pkg install hapee-<VERSION>-lb-da

   Example for HAProxy Enterprise 3.0r1:

   nix
   sudo pkg install hapee-3.0r1-lb-da

   nix
   sudo pkg install hapee-3.0r1-lb-da

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

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

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

   The deviceatlas-json-file directive loads a DeviceAtlas database.

7. Optional: Add the deviceatlas-cache-size directive to set the DeviceAtlas property atlas.config.cache_size, which sets the number of cache entries. It defaults to 0.

   haproxy
   global
     module-load hapee-lb-da.so
     deviceatlas-json-file /etc/hapee-3.0/deviceatlas.json
     deviceatlas-cache-size 10000

   haproxy
   global
     module-load hapee-lb-da.so
     deviceatlas-json-file /etc/hapee-3.0/deviceatlas.json
     deviceatlas-cache-size 10000

8. Optional: Set the deviceatlas-property-separator directive to change the separator to use between values returned from the database. By default, it uses a pipe symbol (|).

   haproxy
   global
     module-load hapee-lb-da.so
     deviceatlas-json-file /etc/hapee-3.0/deviceatlas.json
     deviceatlas-property-separator :

   haproxy
   global
     module-load hapee-lb-da.so
     deviceatlas-json-file /etc/hapee-3.0/deviceatlas.json
     deviceatlas-property-separator :

9. Optional: Change the log level, which you can set to a number between 0 and 3, where 3 is the most verbose. The default is 0.

   haproxy
   global
     module-load hapee-lb-da.so
     deviceatlas-json-file /etc/hapee-3.0/deviceatlas.json
     deviceatlas-log-level 3

   haproxy
   global
     module-load hapee-lb-da.so
     deviceatlas-json-file /etc/hapee-3.0/deviceatlas.json
     deviceatlas-log-level 3

10. Optional: Change the name of the DeviceAtlas Client-side Component cookie, if using client-side properties. It defaults to DAPROPS.

    haproxy
    global
      module-load hapee-lb-da.so
      deviceatlas-json-file /etc/hapee-3.0/deviceatlas.json
      deviceatlas-properties-cookie mycookiename

    haproxy
    global
      module-load hapee-lb-da.so
      deviceatlas-json-file /etc/hapee-3.0/deviceatlas.json
      deviceatlas-properties-cookie mycookiename

11. Reload the configuration to apply the changes.

    nix
    sudo systemctl reload hapee-3.0-lb

    nix
    sudo systemctl reload hapee-3.0-lb

Use DeviceAtlas Jump to heading #

After installing the module, use the following directives to perform database lookups.

da-csv-fetch Jump to heading #

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

Syntax:

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

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

In this example we create an HTTP request header that contains device information:

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

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

In the next example, we define an ACL named is_mobile and then use it when choosing a backend:

haproxy
frontend www
  bind :80
  mode http
  acl is_mobile da-csv-fetch(mobileDevice) 1
  use_backend mobile_site if is_mobile
  default_backend desktop_site

haproxy
frontend www
  bind :80
  mode http
  acl is_mobile da-csv-fetch(mobileDevice) 1
  use_backend mobile_site if is_mobile
  default_backend desktop_site

da-csv-conv Jump to heading #

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:

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

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

In this example we create an HTTP request header that contains device information:

haproxy
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)]

haproxy
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 Jump to heading #

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

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

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

   apt yum zypper pkg

   nix
   sudo apt-get install hapee-<VERSION>-lb-da-update

   nix
   sudo apt-get install hapee-<VERSION>-lb-da-update

   Example for HAProxy Enterprise 3.0r1:

   nix
   sudo apt-get install hapee-3.0r1-lb-da-update

   nix
   sudo apt-get install hapee-3.0r1-lb-da-update

   nix
   sudo yum install hapee-<VERSION>-lb-da-update

   nix
   sudo yum install hapee-<VERSION>-lb-da-update

   Example for HAProxy Enterprise 3.0r1:

   nix
   sudo yum install hapee-3.0r1-lb-da-update

   nix
   sudo yum install hapee-3.0r1-lb-da-update

   nix
   sudo zypper install hapee-<VERSION>-lb-da-update

   nix
   sudo zypper install hapee-<VERSION>-lb-da-update

   Example for HAProxy Enterprise 3.0r1:

   nix
   sudo zypper install hapee-3.0r1-lb-da-update

   nix
   sudo zypper install hapee-3.0r1-lb-da-update

   nix
   sudo pkg install hapee-<VERSION>-lb-da-update

   nix
   sudo pkg install hapee-<VERSION>-lb-da-update

   Example for HAProxy Enterprise 3.0r1:

   nix
   sudo pkg install hapee-3.0r1-lb-da-update

   nix
   sudo pkg install hapee-3.0r1-lb-da-update

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

   haproxy
   global
     module-load hapee-lb-da-update.so
     deviceatlas-update url http://192.168.0.1:8000/deviceatlas.json delay 24h log

   haproxy
   global
     module-load hapee-lb-da-update.so
     deviceatlas-update url http://192.168.0.1:8000/deviceatlas.json delay 24h log

   Be sure to specify the port number where your file is hosted, for example 8000 as in the example above. 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.

   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.

   Learn more about deviceatlas-update

   The directive deviceatlas-update supports the following syntax:

   text
   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*]

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

   Argument	Description
   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).
   hash	If set, enables authentication of the downloaded database. 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.
   source <addr>[:<port>]	Sets the source address for outgoing connection. <addr> is the IPv4 address the load balancer 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.

   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 the load balancer starts.

Runtime API Jump to heading #

It is possible to manage the DeviceAtlas module via the Runtime API.

da-update update Jump to heading #

The DeviceAtlas update module will update its database based on the interval you specifed in the configuration. You can also force an update by specifying the time you would like the update to run, for example, 5 minutes from now. If you don’t specify a time, or set the update delay to zero, the update will run immediately. The delay time you specify cannot exceed the time until the next regular update.

In this example, we want the update to run 5 minutes from now so we specify 5m as the delay time.

nix
echo "da-update update 5m" | sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock

nix
echo "da-update update 5m" | sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock

output
text
DeviceAtlas: forcing update in 5m

output
text
DeviceAtlas: forcing update in 5m

da-update status Jump to heading #

You can check the status of the update using the da-update status command. Note that while the update is processing, the status will show the progress:

nix
echo "da-update status" | sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock

nix
echo "da-update status" | sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock

output
text
DeviceAtlas module status
------------------------------------------------------------------------------
 initialized:          yes
 
 Data update
  configuration:      /etc/hapee-3.0/hapee-lb.cfg:43
  url:                http://192.168.64.1:8000
  http status count:  0 0 0 0 7 / 0
  period/delay:       1d / 5s 10s 5s
  use cksum/hash/mod: no / no / no
  reload/retry count: 0 0 2 / 7 2
  reload time:        <NEVER> / <NEVER> / 2023-08-08 14:25:37'
  download time:      <NEVER> / <NEVER>
  currently updating: deviceatlas.json 
     status/retry:      0 / 2
     data size:         0 / 0 (0.0%)
     dur/time left:     8s / 1s

output
text
DeviceAtlas module status
------------------------------------------------------------------------------
 initialized:          yes
 
 Data update
  configuration:      /etc/hapee-3.0/hapee-lb.cfg:43
  url:                http://192.168.64.1:8000
  http status count:  0 0 0 0 7 / 0
  period/delay:       1d / 5s 10s 5s
  use cksum/hash/mod: no / no / no
  reload/retry count: 0 0 2 / 7 2
  reload time:        <NEVER> / <NEVER> / 2023-08-08 14:25:37'
  download time:      <NEVER> / <NEVER>
  currently updating: deviceatlas.json 
     status/retry:      0 / 2
     data size:         0 / 0 (0.0%)
     dur/time left:     8s / 1s

da-update show Jump to heading #

Use the da-update show command to display the configuration of the DeviceAtlas Update module. The output of this command includes information about the configured database file and its update status.

Below, we retrieve the status information for our configured database file:

nix
echo "da-update show" | sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock

nix
echo "da-update show" | sudo socat stdio unix-connect:/var/run/hapee-3.0/hapee-lb.sock

output
text
# da-update configuration
# url: next update
http://192.168.0.1:8000/deviceatlas.json: 23h58m

output
text
# da-update configuration
# url: next update
http://192.168.0.1:8000/deviceatlas.json: 23h58m