Device detection

51Degrees

Available since

  • HAProxy Enterprise 1.7r2

The 51Degrees module provides device detection services using the 51Degrees database.

Install the 51Degrees module Jump to heading

  1. Log into your account at the 51Degrees website and download the enterprise database in Trie format. Copy the .trie file to your HAProxy Enterprise server (for example /etc/hapee-2.9/51Degrees-LiteV3.4.trie).

  2. Install the 51Degrees module according to your platform:

    nix
    sudo apt-get install hapee-2.9r1-lb-51d
    nix
    sudo apt-get install hapee-2.9r1-lb-51d
    nix
    sudo yum install hapee-2.9r1-lb-51d
    nix
    sudo yum install hapee-2.9r1-lb-51d
    nix
    sudo zypper install hapee-2.9r1-lb-51d
    nix
    sudo zypper install hapee-2.9r1-lb-51d
    nix
    sudo pkg install hapee-2.9r1-lb-51d
    nix
    sudo pkg install hapee-2.9r1-lb-51d
  3. In the global section of your configuration, add the following lines. Change the 51degrees-property-name-list depending on the properties you want to use:

    haproxy
    global
    module-path /opt/hapee-2.9/modules/
    module-load hapee-lb-51d.so
    51degrees-data-file /etc/hapee-2.9/51Degrees-LiteV3.4.trie
    51degrees-property-name-list DeviceType IsMobile IsTablet
    haproxy
    global
    module-path /opt/hapee-2.9/modules/
    module-load hapee-lb-51d.so
    51degrees-data-file /etc/hapee-2.9/51Degrees-LiteV3.4.trie
    51degrees-property-name-list DeviceType IsMobile IsTablet
  4. Reload the configuration to apply the changes.

    nix
    sudo systemctl reload hapee-2.9-lb
    nix
    sudo systemctl reload hapee-2.9-lb

Use 51Degrees Jump to heading

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

51d.all Jump to heading

Use the fetch method 51d.all to perform a lookup in the database that returns the values of the specified properties. The function can be passed up to five property names and if a property name can’t be found, it returns the value NoData.

Syntax

text
51d.all(<prop>[,<prop>*])
text
51d.all(<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 %[51d.all(DeviceType,IsMobile,IsTablet)]
haproxy
frontend www
bind :80
mode http
http-request set-header X-DeviceInfo %[51d.all(DeviceType,IsMobile,IsTablet)]

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 51d.all(IsMobile) "True"
use_backend mobile_site if is_mobile
default_backend desktop_site
haproxy
frontend www
bind :80
mode http
acl is_mobile 51d.all(IsMobile) "True"
use_backend mobile_site if is_mobile
default_backend desktop_site

51d.single Jump to heading

Use the converter 51d.single 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. The function can be passed up to five property names and if a property name can’t be found, it returns the value NoData.

Syntax:

text
51d.single(<prop>[,<prop>*])
text
51d.single(<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),51d.single(DeviceType,IsMobile,IsTablet)]
haproxy
frontend www
bind :80
mode http
http-request set-header X-DeviceInfo %[req.hdr(user-agent),51d.single(DeviceType,IsMobile,IsTablet)]

Update the database during runtime Jump to heading

Use the 51Degrees 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 the load balancer can access. For example, host the file at http://192.168.0.1:8000/51Degrees-LiteV3.4.trie.

  2. Install the package hapee-2.9r1-lb-51d-update.

    nix
    sudo apt-get install hapee-2.9r1-lb-51d-update
    nix
    sudo apt-get install hapee-2.9r1-lb-51d-update
    nix
    sudo yum install hapee-2.9r1-lb-51d-update
    nix
    sudo yum install hapee-2.9r1-lb-51d-update
    nix
    sudo zypper install hapee-2.9r1-lb-51d-update
    nix
    sudo zypper install hapee-2.9r1-lb-51d-update
    nix
    sudo pkg install hapee-2.9r1-lb-51d-update
    nix
    sudo pkg install hapee-2.9r1-lb-51d-update
  3. Add the following lines to the global section of your configuration:

    haproxy
    global
    module-load hapee-lb-51d-update.so
    51degrees-update url http://192.168.0.1:8000/51Degrees-LiteV3.4.trie delay 24h log
    haproxy
    global
    module-load hapee-lb-51d-update.so
    51degrees-update url http://192.168.0.1:8000/51Degrees-LiteV3.4.trie 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 prints a message in the logs when it succeeds or if it encounters errors during the update.

Runtime API Jump to heading

It is possible to manage the 51Degrees module via the Runtime API.

51d-update force-update Jump to heading

Prerequisites

This command becomes available after you have installed both the 51Degrees and 51Degrees Update modules.

The 51Degrees update module will update the database based on the interval you specifed in the configuration. Use the 51d-update force-update command to force an immediate update of the 51Degrees database.

In this example, we force an update of the database.

nix
echo "51d-update force-update" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
nix
echo "51d-update force-update" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
output
text
51Degrees: forcing update now
output
text
51Degrees: forcing update now

51d-update status Jump to heading

Prerequisites

This command becomes available after you have installed both the 51Degrees and 51Degrees Update modules.

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

nix
echo "51d-update status" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
nix
echo "51d-update status" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
output
text
51Degrees module status
------------------------------------------------------------------------------
initialized: yes
Database update
configuration: /etc/hapee-2.7/hapee-lb.cfg:43
url: http://192.168.64.1/51Degrees-LiteV3.4.trie
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
currently updating: 51Degrees-LiteV3.4.trie
status/retry: 0 / 1
data size: 0 / 0 (0.0%)
dur/time left: 1m49s / 3s
output
text
51Degrees module status
------------------------------------------------------------------------------
initialized: yes
Database update
configuration: /etc/hapee-2.7/hapee-lb.cfg:43
url: http://192.168.64.1/51Degrees-LiteV3.4.trie
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
currently updating: 51Degrees-LiteV3.4.trie
status/retry: 0 / 1
data size: 0 / 0 (0.0%)
dur/time left: 1m49s / 3s

51d-update show Jump to heading

Prerequisites

This command becomes available after you have installed both the 51Degrees and 51Degrees Update modules.

Use the 51d-update show command to display the configuration of the 51Degrees update module. The output of this command includes information about each configured database file and its update status.

Below, we retrieve the status information for our configured databases:

nix
echo "51d-update show" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
nix
echo "51d-update show" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
output
text
# 51d-update configuration
# url: next update
http://192.168.0.1/51Degrees-LiteV3.4.trie: 23h58m
output
text
# 51d-update configuration
# url: next update
http://192.168.0.1/51Degrees-LiteV3.4.trie: 23h58m

Do you have any suggestions on how we can improve the content of this page?