HAProxy Enterprise's WURFL module uses the InFuze technology from ScientiaMobile to provide device detection services. This feature can also apply live updates of databases, similar to HAProxy's Update module for maps/ACLs.

Tip

HAProxy Enterprise only: This module requires an active HAProxy Enterprise subscription. Please contact us if you would like to learn more or begin a free trial.

Prerequisites

  • HAProxy Enterprise version 1.7r1 or newer

  • The WURFL Update module requires HAProxy Enterprise version 1.9r1 or newer

  • The HAProxy WURLFL module requires the WURFL InFuze C API to run. You must obtain the WURFL InFuze C API (libwurfl) from ScientiaMobile by registering for an account and subscribing for WURFL InFuze. Follow the installation instructions in the WURFL InFuze for C: User Guide to install the API on the HAProxy server.

  • A copy of the WURFL InFuze device detection database (XML file).

Install the HAProxy WURFL module

  1. Copy the WURFL InFuze device detection database to the HAProxy server.

  2. Install the HAProxy WURFL module using apt or yum depending on your operating system:

    $ sudo apt install hapee-1.9r1-lb-wurfl

Configure the WURFL module

  • Add the following to the global section of the HAProxy configuration file:

    module-load hapee-lb-wurfl.so
wurfl-data-file /path/to/wurfl.xml
wurfl-information-list wurfl_id model_name
wurfl-cache-size 100000

Update the database during runtime

HAProxy can download periodically a new version of the XML database during runtime by using the WURFL Update module. This is especially useful when you are running more than one HAProxy instance.

  1. Install a Web server of your choice and host the WURFL XML database file at a URL where HAProxy can access. For example, host the file at http://localhost:8000/wurfl.xml.gz.

  2. Install the HAProxy WURFL Update module using apt or yum:

    $ sudo apt install hapee-1.9r1-lb-wurfl-update

  3. In the global section of your configuration, add directives similar to the following example:

    module-load hapee-lb-wurfl-update.so
wurfl-update url http://localhost:8000/wurfl.xml.gz delay 24h log

    With this configuration, HAProxy 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.

Global parameters

The global section supports the following directives for the hapee-lb-wurfl module:

Directive

Description

wurfl-data-file <path> (required)

The path to the WURFL data file.

wurfl-information-list <value> [<value>...] (required)

List of WURFL capabilities, virtual capabilities, and property names to use in injected HTTP headers.

You must separate each value with a space. See the WURFL InFuze documentation for values that you can use with HAProxy.

wurfl-information-list-separator <separator>

Separator to add between data returned from the WURFL database. Defaults to ",".

wurfl-patch-file <path> [<path>...]

Lists 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.

wurfl-cache-size <size>

The LRU cache speeds up lookup operations on User-Agent strings that were previously processed. This directive sets the number of entries to keep in the cache.

  • When size is not "0", HAProxy uses the Single LRU cache provider with the specified cache size.

  • "0": HAProxy disables cache.

wurfl-engine-mode <mode>

WURFL engine target (requires WURFL version < 1.9):

  • performance (default)

  • accuracy

wurfl-useragent-priority <priority>

Tells WURFL whether to prioritize the use of the plain user agent (plain) over the default sideloaded browser user agent (sideloaded_browser).

The global section supports the following directives for the hapee-lb-wurfl-update module:

Directive

Description

wurfl-debug <level>

Sets the debug level. The default is 7. Use this only when the module runs in debug mode; in normal use, it has no significance.

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*] (required)

Enables database update over HTTP from specified URL. Updating the database with a newer version invalidates any cached lookups (if using caching), unless you enable checksum and new and old database contents are identical. See parameters below.

where:

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 HAProxy 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.

  • 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). See note below.

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. See note below.

source <addr>[:<port>]

Sets the source address for outgoing connections.

  • <addr> is the IPv4 address HAProxy 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.

Note

When you set parameters for wurfl-update, 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 starts.

Fetches

HAProxy uses fetches to perform a lookup in the database and return the values of the specified properties.

  • The wurfl-get fetch returns the specified properties, which you must declare beforehand with the wurfl-information-list directive. - The wurfl-get-all fetch returns all properties that the wurfl-information-list directive declared.

Syntax:

wurfl-get-all()
wurfl-get(propertyA,propertyB,...)

Example:

# Get all data listed in wurfl-information-list
# Sets a header: 'X-Wurfl-All: firefox_69_0,Firefox'
http-request set-header X-WURFL-All %[wurfl-get-all()]

# Get a subset of data listed in wurfl-information-list
# Sets a header: 'X-Wurfl-Properties: firefox_69_0,Firefox'
http-request set-header X-WURFL-Properties %[wurfl-get(wurfl_id,model_name)]

HAProxy Runtime API

The following HAProxy Runtime API commands are available:

wurfl-update debug [level]

Sets the debug level (default: 7). This command is usable only when you compile the module in debug mode; it has no significance in normal use.

wurfl-update mem-info [iec]

Provides instrumentation to describe memory space usage. If the iec argument is not present, the memory size appears only as a number. If set to 1, all sizes scale to a human readable format such as 1023, 16.1K, 768M, 1.2G. This command is usable only when you compile the module in debug mode; it has no significance in normal use.

wurfl-update show

Shows the WURFL Update configuration.

wurfl-update status

Shows the module status.

wurfl-update force-update

Launches an update manually.