Device detection

ScientiaMobile WURFL InFuze

Available since

  • HAProxy Enterprise 1.7r2

The WURFL module provides device detection services using the ScientiaMobile InFuze database.

Install the WURFL InFuze module Jump to heading

  1. Log into your account at the ScientiaMobile website and subscribe to WURFL InFuze. Follow the installation instructions in the WURFL InFuze for C: User Guide to install the API on your HAProxy Enterprise server.

  2. Copy the WURFL InFuze device detection database (XML file) to your HAProxy Enterprise server (for example /etc/hapee-2.9/wurfl.xml).

  3. Install the WURFL module according to your platform:

    nix
    sudo apt-get install hapee-2.9r1-lb-wurfl
    nix
    sudo apt-get install hapee-2.9r1-lb-wurfl
    nix
    sudo yum install hapee-2.9r1-lb-wurfl
    nix
    sudo yum install hapee-2.9r1-lb-wurfl
    nix
    sudo zypper install hapee-2.9r1-lb-wurfl
    nix
    sudo zypper install hapee-2.9r1-lb-wurfl
    nix
    sudo pkg install hapee-2.9r1-lb-wurfl
    nix
    sudo pkg install hapee-2.9r1-lb-wurfl
  4. In the global section of your configuration, add the following lines:

    haproxy
    global
    module-load hapee-lb-wurfl.so
    wurfl-data-file /etc/hapee-2.9/wurfl.xml
    wurfl-information-list wurfl_id model_name
    wurfl-cache-size 100000
    haproxy
    global
    module-load hapee-lb-wurfl.so
    wurfl-data-file /etc/hapee-2.9/wurfl.xml
    wurfl-information-list wurfl_id model_name
    wurfl-cache-size 100000

    In this example:

    • wurfl-data-file sets the path to the WURFL data file.
    • wurfl-information-list list of WURFL capabilities, virtual capabilities, and property names to use in injected HTTP headers. Separate each value with a space. See the WURFL InFuze documentation for values that you can use.
    • wurfl-cache-size sets the number of entries to keep in the LRU (least recently used) cache. The LRU cache speeds up lookup operations on User-Agent strings by storing previously processed lookups.
  5. Optional: Set the wurfl-information-list-separator directive to change the separator to use between values returned from the database. By default, it uses a comma (,).

    haproxy
    global
    module-load hapee-lb-wurfl.so
    wurfl-data-file /etc/hapee-2.9/wurfl.xml
    wurfl-information-list wurfl_id model_name
    wurfl-cache-size 100000
    wurfl-information-list-separator :
    haproxy
    global
    module-load hapee-lb-wurfl.so
    wurfl-data-file /etc/hapee-2.9/wurfl.xml
    wurfl-information-list wurfl_id model_name
    wurfl-cache-size 100000
    wurfl-information-list-separator :
  6. Optional: Set the wurfl-patch-file directive to the file paths to WURFL patch definitions. You can have as many as necessary, and the API applies them in the order they appear in the configuration file. Separate each value with a space.

  7. Optional: Set the wurfl-engine-mode directive to target a WURFL engine. It can be either performance, which is the default, or accuracy.

  8. Optional: Set the wurfl-useragent-priority directive to either plain to prioritize using the plain User-Agent or sideloaded_browser to prioritize the sideloaded browser User-Agent. The default is sideloaded_browser.

  9. Reload the configuration to apply the changes.

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

Use WURFL InFuze Jump to heading

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

wurfl-get Jump to heading

Use the fetch method wurfl-get to perform a lookup in the database that returns the values of the specified properties. You must declare these properties beforehand with the wurfl-information-list global directive.

Syntax:

text
wurfl-get(<prop>[,<prop>*])
text
wurfl-get(<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-WURFL-Properties %[wurfl-get(wurfl_id,model_name)]
haproxy
frontend www
bind :80
mode http
http-request set-header X-WURFL-Properties %[wurfl-get(wurfl_id,model_name)]

wurfl-get-all Jump to heading

Use the fetch method wurfl-get-all to perform a lookup in the database that returns values for all properties that the wurfl-information-list directive declared.

Syntax:

text
wurfl-get-all()
text
wurfl-get-all()

In this example we create an HTTP request header that contains all the device properties.

haproxy
frontend www
bind :80
mode http
http-request set-header X-WURFL-All %[wurfl-get-all()]
haproxy
frontend www
bind :80
mode http
http-request set-header X-WURFL-All %[wurfl-get-all()]

Update the database during runtime Jump to heading

Available since

  • HAProxy Enterprise 1.9r1

Use the WURFL Update module to keep 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/wurfl.xml.gz.

  2. Install the package hapee-2.9r1-lb-wurfl-update:

    nix
    sudo apt-get install hapee-2.9r1-lb-wurfl-update
    nix
    sudo apt-get install hapee-2.9r1-lb-wurfl-update
    nix
    sudo yum install hapee-2.9r1-lb-wurfl-update
    nix
    sudo yum install hapee-2.9r1-lb-wurfl-update
    nix
    sudo zypper install hapee-2.9r1-lb-wurfl-update
    nix
    sudo zypper install hapee-2.9r1-lb-wurfl-update
    nix
    sudo pkg install hapee-2.9r1-lb-wurfl-update
    nix
    sudo pkg install hapee-2.9r1-lb-wurfl-update
  3. In the global section of your configuration, add the following directives:

    haproxy
    global
    module-load hapee-lb-wurfl-update.so
    wurfl-update url http://192.168.0.1:8000/wurfl.xml.gz delay 24h log
    haproxy
    global
    module-load hapee-lb-wurfl-update.so
    wurfl-update url http://192.168.0.1:8000/wurfl.xml.gz 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 when it encounters an error during the update.

    Learn more about wurfl-update

    The directive wurfl-update supports the following syntax:

    text
    wurfl-update url <url> [delay <u> | xdelay <u s b r>] [timeout <t>] [retries <n>] [checksum | modified] [hash] [source <addr>[:<port>]] [log] [dontlog-normal] [param*]
    text
    wurfl-update url <url> [delay <u> | xdelay <u s b r>] [timeout <t>] [retries <n>] [checksum | modified] [hash] [source <addr>[:<port>]] [log] [dontlog-normal] [param*]

    where:

    Argument Description
    url <url> Required. Specifies the database update URL.
    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; If the load balancer cannot download the new version after three attempts, it cancels and discards the download until the next time interval defined by <u>.
    timeout <t> Specifies the HTTP connection timeout in milliseconds (default) for attempts to download a new database version. The value can be any other unit if you add a unit suffix. It defaults to 5000 milliseconds.
    retries <n> Specifies the number of retries to download a new WURFL database version. If not set, the global retries value applies (defaults to 3).
    checksum If set, this determines the use of the SHA1 control sum to verify that the recently downloaded database is identical to the current one. If it is, 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 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.
    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 connections. <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; It 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 HAProxy Enterprise starts.

Runtime API Jump to heading

It is possible to manage the WURFL InFuze module via the Runtime API.

wurfl-update force-update Jump to heading

Prerequisites

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

The WURFL InFuze update module will update its database based on the interval you specifed in the configuration. Use wurfl-update force-update to force an immediate update of the WURFL InFuze database.

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

nix
echo "wurfl-update force-update" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
nix
echo "wurfl-update force-update" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
output
text
WURFL: forcing update in 5m
output
text
WURFL: forcing update in 5m

wurfl-update status Jump to heading

Prerequisites

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

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

nix
echo "wurfl-update status" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
nix
echo "wurfl-update status" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
output
text
WURFL InFuze module status
------------------------------------------------------------------------------
initialized: yes
Data update
configuration: /etc/hapee-2.7/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
currently updating: wurfl.xml.gz
status/retry: 0 / 2
data size: 0 / 0 (0.0%)
dur/time left: 8s / 1s
output
text
WURFL InFuze module status
------------------------------------------------------------------------------
initialized: yes
Data update
configuration: /etc/hapee-2.7/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
currently updating: wurfl.xml.gz
status/retry: 0 / 2
data size: 0 / 0 (0.0%)
dur/time left: 8s / 1s

wurfl-update show Jump to heading

Prerequisites

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

Use the wurfl-update show command to display the configuration of the WURFL 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 "wurfl-update show" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
nix
echo "wurfl-update show" | sudo socat stdio unix-connect:/var/run/hapee-2.9/hapee-lb.sock
output
text
# wurfl-update configuration
# url: next update
http://192.168.0.1:8000/wurfl.xml.gz: 23h58m
output
text
# wurfl-update configuration
# url: next update
http://192.168.0.1:8000/wurfl.xml.gz: 23h58m

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