ScientiaMobile WURFL InFuze

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-3.1/wurfl.xml).

3. Install the WURFL module according to your platform:

   apt yum zypper pkg

   nix
   sudo apt-get install hapee-<VERSION>-lb-wurfl

   nix
   sudo apt-get install hapee-<VERSION>-lb-wurfl

   Example for HAProxy Enterprise 3.1r1:

   nix
   sudo apt-get install hapee-3.1r1-lb-wurfl

   nix
   sudo apt-get install hapee-3.1r1-lb-wurfl

   nix
   sudo yum install hapee-<VERSION>-lb-wurfl

   nix
   sudo yum install hapee-<VERSION>-lb-wurfl

   Example for HAProxy Enterprise 3.1r1:

   nix
   sudo yum install hapee-3.1r1-lb-wurfl

   nix
   sudo yum install hapee-3.1r1-lb-wurfl

   nix
   sudo zypper install hapee-<VERSION>-lb-wurfl

   nix
   sudo zypper install hapee-<VERSION>-lb-wurfl

   Example for HAProxy Enterprise 3.1r1:

   nix
   sudo zypper install hapee-3.1r1-lb-wurfl

   nix
   sudo zypper install hapee-3.1r1-lb-wurfl

   nix
   sudo pkg install hapee-<VERSION>-lb-wurfl

   nix
   sudo pkg install hapee-<VERSION>-lb-wurfl

   Example for HAProxy Enterprise 3.1r1:

   nix
   sudo pkg install hapee-3.1r1-lb-wurfl

   nix
   sudo pkg install hapee-3.1r1-lb-wurfl

4. In the global section of your configuration, add the following lines:

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

   haproxy
   global
     module-path /opt/hapee-3.1/modules/
     module-load hapee-lb-wurfl.so
     wurfl-data-file /etc/hapee-3.1/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-path /opt/hapee-3.1/modules/
     module-load hapee-lb-wurfl.so
     wurfl-data-file /etc/hapee-3.1/wurfl.xml
     wurfl-information-list wurfl_id model_name
     wurfl-cache-size 100000
     wurfl-information-list-separator :

   haproxy
   global
     module-path /opt/hapee-3.1/modules/
     module-load hapee-lb-wurfl.so
     wurfl-data-file /etc/hapee-3.1/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-3.1-lb

   nix
   sudo systemctl reload hapee-3.1-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 #

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-3.1r1-lb-wurfl-update:

   apt yum zypper pkg

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

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

   Example for HAProxy Enterprise 3.1r1:

   nix
   sudo apt-get install hapee-3.1r1-lb-wurfl-update

   nix
   sudo apt-get install hapee-3.1r1-lb-wurfl-update

   nix
   sudo yum install hapee-<VERSION>-lb-wurfl-update

   nix
   sudo yum install hapee-<VERSION>-lb-wurfl-update

   Example for HAProxy Enterprise 3.1r1:

   nix
   sudo yum install hapee-3.1r1-lb-wurfl-update

   nix
   sudo yum install hapee-3.1r1-lb-wurfl-update

   nix
   sudo zypper install hapee-<VERSION>-lb-wurfl-update

   nix
   sudo zypper install hapee-<VERSION>-lb-wurfl-update

   Example for HAProxy Enterprise 3.1r1:

   nix
   sudo zypper install hapee-3.1r1-lb-wurfl-update

   nix
   sudo zypper install hapee-3.1r1-lb-wurfl-update

   nix
   sudo pkg install hapee-<VERSION>-lb-wurfl-update

   nix
   sudo pkg install hapee-<VERSION>-lb-wurfl-update

   Example for HAProxy Enterprise 3.1r1:

   nix
   sudo pkg install hapee-3.1r1-lb-wurfl-update

   nix
   sudo pkg install hapee-3.1r1-lb-wurfl-update

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

   haproxy
   global
     module-path /opt/hapee-3.1/modules/
     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-path /opt/hapee-3.1/modules/
     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 #

The WURFL InFuze update module will update its database based on the interval you specified 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-3.1/hapee-lb.sock

nix
echo "wurfl-update force-update" | sudo socat stdio unix-connect:/var/run/hapee-3.1/hapee-lb.sock

output
text
WURFL: forcing update in 5m

output
text
WURFL: forcing update in 5m

wurfl-update status Jump to heading #

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-3.1/hapee-lb.sock

nix
echo "wurfl-update status" | sudo socat stdio unix-connect:/var/run/hapee-3.1/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 #

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-3.1/hapee-lb.sock

nix
echo "wurfl-update show" | sudo socat stdio unix-connect:/var/run/hapee-3.1/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