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


IMPORTANT: 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

IMPORTANT: The WURFL Lighttpd Module is available starting from WURFL version 1.5.1.2.

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 6 64bit 1.4.35 EPEL repository
CentOS 6 32bit 1.4.35 EPEL repository
CentOS 5 64bit 1.4.35 EPEL repository
Fedora 19 64bit 1.4.35 Official repository
Debian 6 64bit 1.4.28 Official repository
Debian 7 64bit 1.4.31 Official repository
Ubuntu 12.04 64bit 1.4.28 Official repository
Ubuntu 13.04 64bit 1.4.31 Official repository
Ubuntu 13.10 64bit 1.4.31 Official repository
Ubuntu 14.04 64bit 1.4.33 Official repository
FreeBSD 9 64bit 1.4.35 Official repository
SmartOS base64:1.8.4 64bit 1.4.29 Official Joyent repository
MacOSX 10.9.2 Mavericks 64bit Latest version (currently 1.4.35) Lighttpd official site, build from source code

Installing Wurfl Lighttpd module on Linux/Unix sistems

Let's take CentOS 6 64 bit and lighttpd-mod_wurfl-1.5.1.2.tar.gz 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-1.5.1.2.tar.gz archive into /home/myself, where myself is your account name, and execute the following commands:

cp /home/myself/lighttpd-mod_wurfl-1.5.1.2/mod_wurfl.so /usr/lib64/lighttpd/
cp /home/myself/lighttpd-mod_wurfl-1.5.1.2/wurfl.conf /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

How to build Lighttpd from source code on MacOSX 10.9.2

Since there is no official Lighttpd installer for MacOSX, we are forced to build the latest available version (version 1.4.35 as of May, 7th 2014) from source code. Here you can find a list of 1.4.x releases.

First, download the 1.4.35 Lighttpd version and extract the archive:

wget http://download.lighttpd.net/lighttpd/releases-1.4.x/lighttpd-1.4.35.tar.gz
tar -zxvf lighttpd-1.4.35.tar.gz

On some systems it may be necessary to export an extra environment variable before building the source code. This is because the autoconf tool cannot always find where automake is installed. Execute the following commands:

which automake                      # The output should be something like /usr/local/bin/automake
export AUTOMAKE=/usr/local/bin/automake

Lighttpd depends also on Python version 2.6 or above, so make sure that this is also installed prior to building the source files. To check your installed python version, just type:

python -V

We are now ready to build Lighttpd:

autoreconf -fi
./configure --prefix=/usr/          #You can choose where to install Lighttpd through the configure's --prefix option
make clean
make install

We provide the lighttpd-mod_wurfl-XX.tar.gz package which contains our precompiled module mod_wurfl.so and a WURFL configuration file named wurfl.conf.

  • mod_wurfl.so needs to be placed into /usr/lib/lighttpd/
  • wurfl.conf needs to be placed into /etc/lighttpd/conf.d

Remember that we need to enable our module by including the wurfl.conf file, and this can be done by manually editing /etc/lighttpd/lighttpd.conf (or modules.conf if it exists) by adding the following line:

include "conf.d/wurfl.conf"

Now that everything is in place and set up, we can launch the lighttpd process by executing (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.target lets you choose between high_accuracy and high_performance modes.
  • 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 capabilities to extract for each request.

Configuration file for WURFL Lighttpd module

server.modules += ( "mod_wurfl" )

wurfl.root = "/usr/share/wurfl/wurfl-eval.xml"

### Specify the Engine Target. Possible values are:
### [high_]accuracy
### [high_]performance
wurfl.target = "performance"

### 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 capabilities in the format: "capability1,capability2"

### Comment this line if you want WURFL to load all the capabilities.
wurfl.requested-capabilities = "device_os,device_os_version,is_tablet,is_wireless_device,pointing_method,preferred_markup,resolution_height,resolution_width,ux_full_desktop,xhtml_support_level,is_smarttv,can_assign_phone_number,brand_name,model_name,marketing_name,mobile_browser_version"

Also note that the requested 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.

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. Consider that these environment variables are automatically calculated and are always available.

Environment Variables Table

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

;cgi.fix_pathinfo=1

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 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 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:

/etc/lighttpd/conf-available
/etc/lighttpd/conf-enabled
/etc/lighttpd/lighttpd.conf

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`

A note about SmartOS's issues with libgcc

SmartOS usually looks in the wrong path for the libgcc core library, which causes segmentation faults when handling exceptions.

To fix this, we must tell SmartOS where to find the right libgcc library in the following way:

export LD_PRELOAD_64=/usr/sfw/lib/amd64/libgcc_s.so.1

IMPORTANT: This export command must be executed in the very same environment we choose to run lighttpd.

License

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.