Device detection
DeviceAtlas
Available since
- HAProxy Enterprise 1.7r2
The DeviceAtlas module provides device detection services using the DeviceAtlas database.
Install the DeviceAtlas module Jump to heading
-
Log into your account at the DeviceAtlas website and download the Enterprise API C library. Copy it as
libda.so.2
to your HAProxy Enterprise server into the directory/lib/x86_64-linux-gnu/
on Ubuntu/Debian or/lib/lib64
on RedHat Enterprise Linux. -
From your DeviceAtlas account, download the Device Data (JSON) file. Copy it to your HAProxy Enterprise server (for example
/etc/hapee-2.9/deviceatlas.json
). -
Install the DeviceAtlas module according to your platform:
nixsudo apt-get install hapee-2.9r1-lb-danixsudo apt-get install hapee-2.9r1-lb-danixsudo yum install hapee-2.9r1-lb-danixsudo yum install hapee-2.9r1-lb-danixsudo zypper install hapee-2.9r1-lb-danixsudo zypper install hapee-2.9r1-lb-danixsudo pkg install hapee-2.9r1-lb-danixsudo pkg install hapee-2.9r1-lb-da -
In the
global
section of your configuration, add the following lines:haproxyglobalmodule-load hapee-lb-da.sodeviceatlas-json-file /etc/hapee-2.9/deviceatlas.jsonhaproxyglobalmodule-load hapee-lb-da.sodeviceatlas-json-file /etc/hapee-2.9/deviceatlas.jsonThe
deviceatlas-json-file
directive loads a DeviceAtlas database. -
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 (|
).haproxyglobalmodule-load hapee-lb-da.sodeviceatlas-json-file /etc/hapee-2.9/deviceatlas.jsondeviceatlas-property-separator :haproxyglobalmodule-load hapee-lb-da.sodeviceatlas-json-file /etc/hapee-2.9/deviceatlas.jsondeviceatlas-property-separator : -
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.
haproxyglobalmodule-load hapee-lb-da.sodeviceatlas-json-file /etc/hapee-2.9/deviceatlas.jsondeviceatlas-log-level 3haproxyglobalmodule-load hapee-lb-da.sodeviceatlas-json-file /etc/hapee-2.9/deviceatlas.jsondeviceatlas-log-level 3 -
Optional: Change the name of the DeviceAtlas Client-side Component cookie, if using client-side properties. It defaults to
DAPROPS
.haproxyglobalmodule-load hapee-lb-da.sodeviceatlas-json-file /etc/hapee-2.9/deviceatlas.jsondeviceatlas-properties-cookie mycookienamehaproxyglobalmodule-load hapee-lb-da.sodeviceatlas-json-file /etc/hapee-2.9/deviceatlas.jsondeviceatlas-properties-cookie mycookiename -
Reload the configuration to apply the changes.
nixsudo systemctl reload hapee-2.9-lbnixsudo systemctl reload hapee-2.9-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 wwwbind :80mode httphttp-request set-header X-DeviceInfo %[da-csv-fetch(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]
haproxy
frontend wwwbind :80mode httphttp-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 wwwbind :80mode httpacl is_mobile da-csv-fetch(mobileDevice) 1use_backend mobile_site if is_mobiledefault_backend desktop_site
haproxy
frontend wwwbind :80mode httpacl is_mobile da-csv-fetch(mobileDevice) 1use_backend mobile_site if is_mobiledefault_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 wwwbind :80mode httphttp-request set-header X-DeviceInfo %[req.hdr(user-agent),da-csv-conv(primaryHardwareType,osName,osVersion,browserName,browserVersion,browserRenderingEngine)]
haproxy
frontend wwwbind :80mode httphttp-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
Available since
- HAProxy Enterprise 1.9r1
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.
-
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
. -
Install the package
hapee-2.9r1-lb-da-update
:nixsudo apt-get install hapee-2.9r1-lb-da-updatenixsudo apt-get install hapee-2.9r1-lb-da-updatenixsudo yum install hapee-2.9r1-lb-da-updatenixsudo yum install hapee-2.9r1-lb-da-updatenixsudo zypper install hapee-2.9r1-lb-da-updatenixsudo zypper install hapee-2.9r1-lb-da-updatenixsudo pkg install hapee-2.9r1-lb-da-updatenixsudo pkg install hapee-2.9r1-lb-da-update -
Add the following lines to the
global
section of your configuration file:haproxyglobalmodule-load hapee-lb-da-update.sodeviceatlas-update url http://192.168.0.1:8000/deviceatlas.json delay 24h loghaproxyglobalmodule-load hapee-lb-da-update.sodeviceatlas-update url http://192.168.0.1:8000/deviceatlas.json delay 24h logBe 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 enablechecksum
and the new and old database contents are identical.Learn more about deviceatlas-update
The directive
deviceatlas-update
supports the following syntax:textdeviceatlas-update url <url> [delay <u> | xdelay <u s b r>] [timeout <t>] [retries <n>] [checksum] [hash] [modified] [source <addr>[:<port>]] [log] [dontlog-normal] [param*]textdeviceatlas-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. ASHA1
checksum file has the extension.sha1
. The typical way of creating aSHA1
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 theIf-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
andmodified
are mutually exclusive. If you define them at the same time, the optionmodified
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
Prerequisites
This command becomes available after you have installed both the DeviceAtlas and DeviceAtlas Update modules.
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-2.9/hapee-lb.sock
nix
echo "da-update update 5m" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
outputtext
DeviceAtlas: forcing update in 5m
outputtext
DeviceAtlas: forcing update in 5m
da-update status Jump to heading
Prerequisites
This command becomes available after you have installed both the DeviceAtlas and DeviceAtlas Update modules.
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-2.9/hapee-lb.sock
nix
echo "da-update status" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
outputtext
DeviceAtlas module status------------------------------------------------------------------------------initialized: yesData updateconfiguration: /etc/hapee-2.7/hapee-lb.cfg:43url: http://192.168.64.1:8000http status count: 0 0 0 0 7 / 0period/delay: 1d / 5s 10s 5suse cksum/hash/mod: no / no / noreload/retry count: 0 0 2 / 7 2reload time: <NEVER> / <NEVER> / 2023-08-08 14:25:37'download time: <NEVER> / <NEVER>currently updating: deviceatlas.jsonstatus/retry: 0 / 2data size: 0 / 0 (0.0%)dur/time left: 8s / 1s
outputtext
DeviceAtlas module status------------------------------------------------------------------------------initialized: yesData updateconfiguration: /etc/hapee-2.7/hapee-lb.cfg:43url: http://192.168.64.1:8000http status count: 0 0 0 0 7 / 0period/delay: 1d / 5s 10s 5suse cksum/hash/mod: no / no / noreload/retry count: 0 0 2 / 7 2reload time: <NEVER> / <NEVER> / 2023-08-08 14:25:37'download time: <NEVER> / <NEVER>currently updating: deviceatlas.jsonstatus/retry: 0 / 2data size: 0 / 0 (0.0%)dur/time left: 8s / 1s
da-update show Jump to heading
Prerequisites
This command becomes available after you have installed both the DeviceAtlas and DeviceAtlas Update modules.
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-2.9/hapee-lb.sock
nix
echo "da-update show" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
outputtext
# da-update configuration# url: next updatehttp://192.168.0.1:8000/deviceatlas.json: 23h58m
outputtext
# da-update configuration# url: next updatehttp://192.168.0.1:8000/deviceatlas.json: 23h58m
Do you have any suggestions on how we can improve the content of this page?