Device detection

51Degrees

On this page

This page applies to:

  • HAProxy Enterprise 1.7r2 and newer

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

Install the 51Degrees module Jump to heading

  1. Go to the 51Degrees Downloads page to get the 51Degrees device detection data file.

    • For HAProxy Enterprise 3.0r1 and newer, use the V4 .hash data file.
    • For HAProxy Enterprise 2.9r1 and older, use the V3 .trie data file.

  2. Copy the data file to your HAProxy Enterprise server. For example, /etc/hapee-3.2/51Degrees-LiteV4.1.hash.

  3. Install the 51Degrees module according to your platform.

    nix
    sudo apt-get install hapee-<VERSION>-lb-51d
    nix
    sudo apt-get install hapee-<VERSION>-lb-51d

    Example for HAProxy Enterprise 3.2r1:

    nix
    sudo apt-get install hapee-3.2r1-lb-51d
    nix
    sudo apt-get install hapee-3.2r1-lb-51d
    nix
    sudo yum install hapee-<VERSION>-lb-51d
    nix
    sudo yum install hapee-<VERSION>-lb-51d

    Example for HAProxy Enterprise 3.2r1:

    nix
    sudo yum install hapee-3.2r1-lb-51d
    nix
    sudo yum install hapee-3.2r1-lb-51d
    nix
    sudo zypper install hapee-<VERSION>-lb-51d
    nix
    sudo zypper install hapee-<VERSION>-lb-51d

    Example for HAProxy Enterprise 3.2r1:

    nix
    sudo zypper install hapee-3.2r1-lb-51d
    nix
    sudo zypper install hapee-3.2r1-lb-51d
    nix
    sudo pkg install hapee-<VERSION>-lb-51d
    nix
    sudo pkg install hapee-<VERSION>-lb-51d

    Example for HAProxy Enterprise 3.2r1:

    nix
    sudo pkg install hapee-3.2r1-lb-51d
    nix
    sudo pkg install hapee-3.2r1-lb-51d

  4. In the global section of your configuration, add the following lines. Change the 51degrees-property-name-list depending on the 51Degrees device properties you want to use. Note that some properties become available depending on your 51Degrees pricing tier.

    haproxy
    global
      ...
      module-load hapee-lb-51d.so
      51degrees-data-file /etc/hapee-3.2/51Degrees-LiteV4.1.hash
      51degrees-property-name-list DeviceType IsMobile ScreenPixelsHeight ScreenPixelsWidth
    haproxy
    global
      ...
      module-load hapee-lb-51d.so
      51degrees-data-file /etc/hapee-3.2/51Degrees-LiteV4.1.hash
      51degrees-property-name-list DeviceType IsMobile ScreenPixelsHeight ScreenPixelsWidth

  5. Reload the configuration to apply the changes.

    nix
    sudo systemctl reload hapee-3.2-lb
    nix
    sudo systemctl reload hapee-3.2-lb

Use 51Degrees Jump to heading

After installing the module, use the following directives to manage the database.

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. If a property name can’t be found, it returns the value NoData.

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

In the following 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. If a property name can’t be found, it returns the value NoData.

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

51d-set-property-vars Jump to heading

Available since:

  • HAProxy Enterprise 3.2r1 and newer

Use the http-request directive to set variables based on property names specified with the 51degrees-property-name-list global option. If a property name can’t be found, it returns the value NoData.

Syntax
text
51d-set-property-vars(<scope>,<prefix>) [ { if | unless } <condition> ]
Syntax
text
51d-set-property-vars(<scope>,<prefix>) [ { if | unless } <condition> ]

<scope> must be set to proc, sess, txn, or req. <prefix> must be a string containing up to 64 characters of a-z, A-Z, 0-9, ., and _.

Each variable name is generated using the <scope>, the <prefix>, and the property name, separated by periods (.) like so:

text
<scope>.<prefix>.<property_name>
text
<scope>.<prefix>.<property_name>

For example, consider the following configuration:

haproxy
global
   ...
   51degrees-property-name-list BrowserName
frontend www
  ...
  http-request 51d-set-property-vars(txn,51degrees)
haproxy
global
   ...
   51degrees-property-name-list BrowserName
frontend www
  ...
  http-request 51d-set-property-vars(txn,51degrees)
A generated variable example
text
txn.51degrees.Android
A generated variable example
text
txn.51degrees.Android

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-LiteV4.1.hash.

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

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

    Example for HAProxy Enterprise 3.2r1:

    nix
    sudo apt-get install hapee-3.2r1-lb-51d-update
    nix
    sudo apt-get install hapee-3.2r1-lb-51d-update
    nix
    sudo yum install hapee-<VERSION>-lb-51d-update
    nix
    sudo yum install hapee-<VERSION>-lb-51d-update

    Example for HAProxy Enterprise 3.2r1:

    nix
    sudo yum install hapee-3.2r1-lb-51d-update
    nix
    sudo yum install hapee-3.2r1-lb-51d-update
    nix
    sudo zypper install hapee-<VERSION>-lb-51d-update
    nix
    sudo zypper install hapee-<VERSION>-lb-51d-update

    Example for HAProxy Enterprise 3.2r1:

    nix
    sudo zypper install hapee-3.2r1-lb-51d-update
    nix
    sudo zypper install hapee-3.2r1-lb-51d-update
    nix
    sudo pkg install hapee-<VERSION>-lb-51d-update
    nix
    sudo pkg install hapee-<VERSION>-lb-51d-update

    Example for HAProxy Enterprise 3.2r1:

    nix
    sudo pkg install hapee-3.2r1-lb-51d-update
    nix
    sudo pkg install hapee-3.2r1-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-LiteV4.1.hash delay 24h log
    haproxy
    global
      ...
      module-load hapee-lb-51d-update.so
      51degrees-update url http://192.168.0.1:8000/51Degrees-LiteV4.1.hash delay 24h log

    Be sure to specify the port number where your file is hosted. The example above specifies port 8000.

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 HAProxy 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 specified 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-3.2/hapee-lb.sock
nix
echo "51d-update force-update" | sudo socat stdio unix-connect:/var/run/hapee-3.2/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-3.2/hapee-lb.sock
nix
echo "51d-update status" | sudo socat stdio unix-connect:/var/run/hapee-3.2/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-LiteV4.1.hash
  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-LiteV4.1.hash
    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-LiteV4.1.hash
  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-LiteV4.1.hash
    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-3.2/hapee-lb.sock
nix
echo "51d-update show" | sudo socat stdio unix-connect:/var/run/hapee-3.2/hapee-lb.sock
output
text
# 51d-update configuration
# url: next update
http://192.168.0.1/51Degrees-LiteV4.1.hash: 23h58m
output
text
# 51d-update configuration
# url: next update
http://192.168.0.1/51Degrees-LiteV4.1.hash: 23h58m

Troubleshooting Jump to heading

This section covers troubleshooting steps.

Error reading 51Degrees data file Jump to heading

You get the following error during startup:

text
51Degrees Setup - Error reading 51Degrees data file. The data (file: '/etc/hapee-3.2/51Degrees-EnterpriseV3.4.trie') is an unsupported version. Check you have the latest data and API.
text
51Degrees Setup - Error reading 51Degrees data file. The data (file: '/etc/hapee-3.2/51Degrees-EnterpriseV3.4.trie') is an unsupported version. Check you have the latest data and API.

The data file you are trying to load isn’t compatible with the version of the HAProxy Enterprise 51Degrees module. For example, you tried to load a .trie data file, but the module expects a .hash data file.

  • For HAProxy Enterprise 3.0r1 and newer, use the V4 .hash data file.
  • For HAProxy Enterprise 2.9r1 and older, use the V3 .trie data file.

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

Previous page Device detection Next page DeviceAtlas
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences