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 an archive (lighttpd-mod_wurfl-XX.tar.gz) containing an example configuration file named wurfl.conf and the module itself, where XX is the current up-to-date version.

Every distribution, with the exception of CentOS, has its own version of Lighttpd available in the 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.

Please Note that any module compiled, 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 the correct 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). 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 updates of the 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 a new WURFL data file to be downloaded and used by the engine. Options are: DAILY and WEEKLY.

Do note that the WurflRoot file type and WurflUpdater data url file types match so you may need to change the WurflRoot file type accordingly. A wurfl.zip file must be present in a writable path in order for the updater to check the file and determine whether or not it needs to update the file.

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

Configuration file for WURFL Lighttpd module

server.modules += ( "mod_wurfl" )

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

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

### 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_root_id,wurfl_useragent"

### -- 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 wurfl.zip file must be
### -- writable by Lighttpd process
###wurfl.updater = "https://data.scientiamobile.com/xxxxx/wurfl.zip,DAILY"

The requested static and virtual capability values will be placed in the appropriate environment variables with 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.

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. The wurfl_id variable is set by default so you don't have to specify it in the wurfl.requested-properties options 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_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

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 the 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 modules 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, check if the mod_fastcgi.so module exists on your distribution by typing:

find / -name "mod_fastcgi.so" | 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 the 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`

© 2021 ScientiaMobile Inc.
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.