infuze lighttpd module user guide

WURFL InFuze Module for Lighttpd: User Guide

This document is about the Lighttpd Webserver and how you, a developer or system administrator, would install and configure the WURFL Module for Lighttpd on Unix/Linux and MAC OS X.

Installing libwurfl

In order for the Module to work it is ESSENTIAL that the libwurfl library is installed on your system. libwurfl is provided in your Customer Vault/FileX.

If you have not already installed libwurfl, instructions can be found here. Release notes for each API can be found here.

Installing the WURFL InFuze Module for Lighttpd

We provide a lighttpd-mod_wurfl-XX.tar.gz archive containing an example configuration file named wurfl.conf and the module itself, where XX is the currently used WURFL version.

Every distribution, with the exception of CentOS, has its own version of Lighttpd available in their main repository. To avoid having to compile Lighttpd from source, you can add the EPEL (Extra Packages for Enterprise Linux) repository to get a ready-to-install version of Lighttpd. Check out this link for further information on how to add the repository on CentOS 5 or CentOS 6.

Note that any module compiled, for example, with Lighttpd 1.4.35 will NOT work on any other version. If you decide to upgrade Lighttpd in the future, please contact ScientiaMobile to get our WURFL module for that particular version.

This table shows the currently used Lighttpd versions on every distribution we support:

Distribution Lighttpd version Reference repository
CentOS 5 64bit Latest EPEL repository
CentOS 6 64bit Latest EPEL repository
CentOS 7 64bit Latest EPEL repository
Debian 6 64bit Latest Official repository
Debian 7 64bit Latest Official repository
Debian 8 64bit Latest Official repository
Ubuntu 10.04 64bit Latest Official repository
Ubuntu 12.04 64bit Latest Official repository
Ubuntu 13.04 64bit Latest Official repository
Ubuntu 14.04 64bit Latest Official repository
Ubuntu 15.04 64bit Latest Official repository
Ubuntu 16.04 64bit Latest Official repository

Installing Wurfl Lighttpd module on Linux/Unix sistems

Let's take CentOS 6 64 bit and lighttpd-mod_wurfl- as an example.

Make sure you have already installed Lighttpd from the EPEL repository (version 1.4.35 as of May, 7th 2014); if not, just type:

yum install lighttpd

Lighttpd places its configuration files into /etc/lighttpd where you can find the two main configuration files named lighttpd.conf and modules.conf.

For example, extract the contents of lighttpd-mod_wurfl- archive into /home/myself, where myself is your account name, and execute the following commands:

cp /home/myself/lighttpd-mod_wurfl- /usr/lib64/lighttpd/
cp /home/myself/lighttpd-mod_wurfl- /etc/lighttpd/conf.d/

To enable the WURFL module for Lighttpd, include the wurfl.conf config file amongst the ones Lighttpd loads by default. You will need to manually edit /etc/lighttpd/modules.conf and add the following include directive at the end of that file:

include "conf.d/wurfl.conf"

With the module loaded, Lighttpd is ready to launch. Exectute the following command (if you want to daemonize Lighttpd just remove the -D option):

lighttpd -D -f /etc/lighttpd/lighttpd.conf

WURFL Lighttpd configuration file template

Here is an example of a wurfl.conf configuration file. You can configure the following WURFL options:

  • wurfl.root lets you specify a path to wurfl.xml (distributed together with libwurfl).
  • wurfl.useragent-priority lets you specify the user agent priority that WURFL should follow when starting a new device detection.
  • wurfl.cache lets you choose the type of cache you want to use.
  • wurfl.requested-capabilities lets you specify a list of static and virtual capabilities to extract for each request.
  • wurfl.requested-properties lets you specify a list of properties to extract for each request (if not set, only ID property will be extracted).
  • wurfl.updater Allows seamless update of WURFL engine with new data downloaded from Scientiamobile.

wurfl.updater takes two parameters, comma separated: - data url taken from your personal Scientiamobile Vault account, choosing between two data file types: .zip or .xml.gz. - updater checking frequency how often the updater checks for any new WURFL data file to be downloaded and used by the engine, which you can choose between DAILY and WEEKLY.

Take care that WurflRoot file type and WurflUpdater data url file types match so you may need to change the WurflRoot file type accordingly.

In order to let the Updater perform its activities both the WurflRoot folder and file must be writable by lighttpd process. The wurfl-updater.log file in WurflRoot folder will contains details on Updater activity.

Configuration file for WURFL Lighttpd module

server.modules += ( "mod_wurfl" )

wurfl.root = "/usr/share/wurfl/"

### Specify the Useragent Priority. Possible values are:
### useragent_priority_override_sideloaded_browser_useragent
### useragent_priority_use_plain_useragent
wurfl.useragent-priority = "useragent_priority_override_sideloaded_browser_useragent"

### Specify the Cache to be used by WURFL. Possible values are:
### "none"
### "double_lru:<num,num>"
wurfl.cache = "double_lru:10000,3000"

### Specify a set of comma-separated user requested static capabilities and virtual capabilities in the format: "capability1,capability2,...,capabilityN"
wurfl.requested-capabilities = "is_tablet,brand_name,is_robot,advertised_device_os"
### Specify a set of comma-separated user requested properties in the format: "property1,property2,...,propertyN"
###wurfl.requested-properties = "wurfl_useragent,wurfl_engine_target"

### -- WURFL Updater allows seamless update of WURFL engine with new data downloaded from Scientiamobile.
### -- WURFL file should be either .zip or .xml.gz and match WurflRoot file type
### -- Put your personal updater url taken from Scientiamobile customer Vault.
### -- Valid values for the updater check frequency (how often the updater checks for any new WURFL data file
### -- to be downloaded and used by the engine) are DAILY,WEEKLY
### -- Updater log file (wurfl-updater.log) may be found in "WurflRoot" folder. The folder and file must be
### -- writable by Lighttpd process
###wurfl.updater = ",DAILY"

Also note that the requested capability values and virtual capability values will be placed in appropriate environment variables having a WURFL_ prefix. For example, if you requested the marketing_name capability, the environment variable will be called WURFL_MARKETING_NAME.

For a list of all supported capabilities please take a look at the full list of capabilities.

IMPORTANT: Decommissioning of Engine Target Options

Prior to version 1.9 of the API, users could choose between High Accuracy and High Performance engine optimization options. These options had been introduced years ago to manage the behavior of certain web browsers and their tendency to present "always different" User-Agent strings that would baffle strategies to cache similar WURFL queries in memory. As the problem has been solved by browser vendors, the need to adopt this strategy has diminished and ultimately disappeared (i.e. there was no longer much to be gained with the high-performance mode in most circumstances) and ScientiaMobile elected to "remove" this option to simplify configuration and go in the direction of uniform API behavior in different contexts.

When we wrote "remove" in the previous sentence, we were not being totally accurate. Customers who may find themselves in the unlikely situation of having to analyze significant amounts of legacy web traffic, may still enable the old high-performance internal behavior by enabling the ENGINE_TARGET_FAST_DESKTOP_BROWSER_MATCH option in their engine target configuration. Please note that users with the old HIGH PERFORMANCE target engine will not receive an error. The old behavior will not be triggered, though. The default target (corresponding to the old High Accuracy) will be used instead.

Environment Variables in WURFL Lighttpd module

The WURFL Lighttpd module sets some useful convenience environment variables to retrieve information regarding the currently active WURFL configuration, if specified in wurfl.requested-properties option as a list comma separated. Please note that the wurfl_id variable is set by default so you don't have to specify it in wurfl.requested-properties option list.

Environment Variables Table

Variable Name Contents Availability
WURFL_API_VERSION Contains a string representing the currently used Libwurfl API version
WURFL_INFO A string containing informations on the parsed wurfl.xml and its full path
WURFL_LAST_LOAD_TIME Contains the UNIX timestamp of the last time WURFL has been loaded successfully.
WURFL_ENGINE_TARGET Contains a string representing the currently set WURFL Engine Target. Possible values are HIGH_ACCURACY, HIGH_PERFORMANCE or INVALID
WURFL_USERAGENT The original useragent coming with this particular web request
WURFL_NORMALIZED_USERAGENT The normalized useragent of this device
WURFL_ROOTID Contains the device root ID of the matched device.
WURFL_ID Contains the device ID of the matched device.
WURFL_ISDEVROOT Tells if the matched device is a root device. Possible values are TRUE or FALSE
WURFL_USERAGENT_PRIORITY The user agent priority WURFL is currently using 1.5.2

Testing Wurfl Lighttpd Module with FastCGI

NOTE: Both php and php-cgi must be installed prior to test the module using FastCGI.

One way to test our module is by using the Lighttpd FastCGI module and PHP.

Before installing the Lighttpd FastCGI module, we must manually edit PHP's main configuration file, php.ini, by locating this line and uncommenting it (by removing the leading ; character):


Some PHP versions on different distributions should already have this variable set to 1 by default, but you should double check to be sure that php-cgi will work as expected.

Also, some distributions (like CentOS) have specific packages for Lighttpd FastCGI module named lighttpd-fastcgi. In this case you simply need to install it and make sure that, in the modules.conf (or lighttpd.conf), the fastcgi.conf inclusion is uncommented. If the lighttpd-fastcgi package is unavailable you need to check if the module exists on your distribution by typing:

find / -name "" | grep lighttpd

If the module exists then you just have to enable the module by including the fastcgi.conf configuration file into modules.conf (or lighttpd.conf). Otherwise, you will need to build Lighttpd from source (1.4.35 is the latest available version as of May, 7th 2014, take a look at the Lighttpd main page for more information).

At this point we have to tell FastCGI where to find the backing php-cgi executable:

which php-cgi

Take note of the which command output (path to php-cgi, /usr/bin/php-cgi for example) and edit Lighttpd's fastcgi.conf adding the following lines:

fastcgi.server = ( ".php" => ((
    "bin-path" => "/usr/bin/php-cgi",
    "socket" => "/tmp/php.socket"

Lighttpd does listen on port 80 by default, however, the server's document root may vary depending on your distribution. If the server's document root directory is set to /var/www/lighttpd, we can write an index.php (containing a phpinfo() call) and place it into that directory

It is time to launch Lighttpd with our module and FastCGI module loaded:

lighttpd -f /etc/lighttpd/lighttpd.conf

In order to verify if the module is working correctly, open a web browser and type localhost/index.php. You should see the phpinfo() printed onscreen, including all the WURFL information you requested in wurfl.conf, and some other basic information such as WURFL version.

A note about the Lighttpd path differences between Linux/Unix distributions

On some distributions like Debian6 or Debian7 there is no modules.conf and the conf.d/ directory is missing. Instead, the /etc/lighttpd structure looks like this:


The conf-available directory is essentially the equivalent of conf.d. Thus, you can place wurfl.conf under that directory and include the directive into lighttpd.conf

include `conf-available/wurfl.conf`


2017 ScientiaMobile Incorporated All Rights Reserved.

NOTICE: All information contained herein is, and remains the property of ScientiaMobile Incorporated and its suppliers, if any. The intellectual and technical concepts contained herein are proprietary to ScientiaMobile Incorporated and its suppliers and may be covered by U.S. and Foreign Patents, patents in process, and are protected by trade secret or copyright law. Dissemination of this information or reproduction of this material is strictly forbidden unless prior written permission is obtained from ScientiaMobile Incorporated.