infuze apache module user guide

WURFL InFuze Module for Apache: User Guide

This document is about the Apache server and how you, a developer or a system administrator, would install and configure the WURFL Module for Apache on Unix (Linux) systems.

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.

Install WURFL Apache Module on Ubuntu

Run the following command to install the latest Apache software:

sudo apt-get update
sudo apt-get install apache2 apache2-threaded-dev

Download and install the WURFL Apache module deb package:

sudo dpkg -r mod-wurfl
sudo dpkg -i mod_wurfl-1.8.1.0.Apache.2.2.31.x86_64.deb

Install WURFL Apache Module on RedHat/Fedora/CentOS

Run the following command to install the latest Apache Cache software:

sudo yum update
sudo yum -y install openssl-devel
sudo yum -y install pcre httpd

Download and install the WURFL Apache module rpm package:

sudo rpm -e mod-wurfl
sudo rpm -i mod_wurfl-1.8.2.0.Apache.2.2.31.x86_64.rpm

Install WURFL Apache Module on FreeBSD 9

The installation procedure for FreeBSD 9 is slightly different. You will need to use the pre-compiled files provided by ScientiaMobile.

Run the following command to ensure your system is up to date and install several dependent packages:

pkg_add -rv openssl
pkg_add -rv apache22

For this example, we will use 1.4.3 libwurfl version as a reference and the source files will be downloaded in the /opt/ directory. Download, extract, and install the files provided by ScientiaMobile:

cd /opt/
tar xvfz libwurfl_apache_1.4.3_install.tgz
cp -r ./wurfl_install /

Important Note: If you are using WURFL 1.5.0 or greater then you can safely use the following command instead of the previous ones:

cd /
tar xzvf libwurfl_apache_1.5.0_install.tgz

Consider that, by default, Apache will automatically load all the configuration files located in Apache's "extra" directory. Therefore, starting from WURFL version 1.5.0, we placed the httpd-wurfl.conf configuration file directly into the extra directory just mentioned.

ScientiaMobile provides a script which automatically installs all required libraries. Furthermore, the script will extract the tarball contents and copy them into the correct location. This script will NOT add the LoadModule directive that Apache uses to specify which modules are to be loaded.

Therefore, after executing the script, you must manually edit the /usr/local/etc/apache22/httpd.conf configuration file, locate the place where all the LoadModule directives are defined, and add the following line:

LoadModule wurfl_module /usr/local/libexec/apache22/mod_wurfl.so

Restart Apache to apply changes:

/usr/local/sbin/apachectl restart

If you recieve the warning message:

[warn] (2)No such file or directory: Failed to enable ‘httpready’ Accept Filter

you can execute the following commands:

kldload accf_http
grep accf /boot/defaults/loader.conf

This last command will show you the line “accf_http_load=”NO” #wait for full HTTP request accept filter”. To solve the problem just edit the /boot/defaults/loader.conf file and change the parameter value to YES. Save, quit the editor, and restart Apache again.

Tip: before running Apache make sure that in /etc/hosts you have specified the correct hostname after each server address. Otherwise, you will get an error when starting Apache which looks like “httpd: apr_sockaddr_info_get() failed for ...”.

The installation process is now completed.

Install WURFL Apache Module on Windows

You will first need to obtain the Apache mod-wurfl installer provided by ScientiaMobile. This installs the Visual Studio 2012 runtime library, mod-wurfl shared object, and a recent evalution copy of the WURFL file called wurfl_eval.xml.

Run the executable installer and it should automatically install to Windows program files which usually can be found at C:/Program Files (x86)/Scientiamobile/wurfl/apache/.

You will need to add the following directives to your Apache configuration file, e.g. httpd.conf file, to properly load the mod-wurfl module:

LoadModule wurfl_module "C:\Program Files (x86)\Scientiamobile\wurfl\apache\mod_wurfl.so"

<IfModule wurfl_module>
    WurflRoot "C:\Program Files (x86)\Scientiamobile\wurfl\apache\wurfl-eval.xml"
</IfModule>

Once the installation has completed, you will need to restart Apache server in order to load the WURFL Module.

Configuration Guide

Apache is configured by placing directives in plain text configuration files. The main configuration file is usually called httpd.conf and includes the WURFL Apache Module configuration file wurfl.conf.

Below is an example snippet of the wurfl.conf configuration file for WURFL setup:

Note: Linux and FreeBSD come preloaded with the wurfl.conf file which can be found in /etc/apache2/mods-available/, /etc/httpd/conf.d/wurfl.conf, or/usr/local/etc/apache22/extra/. The configuration example below may be different depending on your operating system and configuration setup.*

<IfModule wurfl_module>
    # -- WURFL root definition. User MUST specify this path in order to make WURFL engine correctly start.
    WurflRoot /usr/share/wurfl/wurfl.xml

    # -- WURFL patches definition (as much as needed, patches will be applied in the same order as specified in this conf file)
    #WurflPatch /path/to/first/patch.xml

    # -- WURFL engine target: one of the following (default is WurflTargetPerformance)
    #WurflTargetPerformance
    #WurflTargetAccuracy

    # -- WURFL UA priority: one of the following (default is WurflUserAgentPriorityOverrideSideloadedBrowserUserAgent)
    #WurflUserAgentPriorityOverrideSideloadedBrowserUserAgent
    #WurflUserAgentPriorityUsePlainUserAgent

    # -- WURFL cache: one of the following
    #WurflCacheNull
    #WurflCacheLRU 10000
    #WurflCacheDoubleLRU 100000,30000

    # -- WURFL user requested capabilities (as an example, this is not a complete list)
    #WurflRequestCapability is_console;
    #WurflRequestCapability is_tablet;
    #WurflRequestCapability is_wireless_device;

    # -- WURFL user requested virtual capabilities (as an example, this is not a complete list)
    # -- Since WURFL API version 1.7.1.0, virtual capabilities are no longer injected by default
    # -- and have to be explicitly specified.
    #WurflRequestCapability advertised_device_os;
    #WurflRequestCapability is_android;

    # -- WURFL user requested properties
    # -- Since WURFL API version 1.8.0.0, WURFL properties except "wurfl_id" are no longer injected by default
    # -- and have to be explicitly specified.
    #WurflRequestProperty  wurfl_root_id;
     #WurflRequestProperty  wurfl_isdevroot;
     #WurflRequestProperty  wurfl_useragent;
     #WurflRequestProperty  wurfl_engine_target;
     #WurflRequestProperty  wurfl_useragent_priority;
     #WurflRequestProperty  wurfl_info;
     #WurflRequestProperty  wurfl_api_version;
     #WurflRequestProperty  wurfl_last_load_time;
     #WurflRequestProperty  wurfl_normalized_useragent;

</IfModule>

Please refer to the directives guide that explains each element in detail (Table 1), their parameters, constraints, and default recommended settings.

Table 1:

Syntax Description Availability
WurflRoot <string> This defines the location (path) of the WURFL xml file. 1.4
WurflPatch <string> This function to add one or more custom patch files to the WURFL repository. 1.4
WurflTargetPerformance
or
WurflTargetAccuracy
You can choose between high-accuracy (WURFL_ENGINE_TARGET_HIGH_ACCURACY) or high-performance (WURFL_ENGINE_TARGET_HIGH_PERFORMANCE) targets. In High-Performance mode, desktop web browser detection is done programmatically without referencing the WURFL data. As a result, most desktop web browsers are returned as generic_web_browser WURFL ID for performance. If either High-Performance or High-Accuracy are not defined, High-Performance mode is enabled by default. 1.4
WurflCacheNull
or
WurflCacheLRU <num>
or
WurflCacheDoubleLRU <num>,<num>
The caching strategies are also configurable. You can choose between NULL, LRU, or Double LRU cache mechanisms. The default is Double LRU, which is a two-cache strategy (one going from User-Agent to Device-Id, the other from Device-Id to Device). The default parameters are 10,000, 3,000 (maximum 10,000 elements for the User-Agent to device-id cache and maximum 3,000 elements for the device-id to device cache) and the values are in elements. The LRU cache comes with User-Agent to Device mapping only, and the NULL parameter will disable the cache mode. These parameters refer to the max capacity size of the cache itself in Kilobytes. For more information, please see LRU Cache Mechanism. 1.4
WurflRequestCapability <string> This function defines one or more WURFL Capabilities and/or WURFL Virtual Capabilities to be loaded in the memory run-time. Those WURFL capabilities/virtual capabilities will be loaded to Environment Variable for every HTTP requests. 1.4
WurflRequestProperty <string> Enables injection of WURFL Properties (see section WURFL Properties below) in the Environment Variable for every HTTP requests. 1.8.2.0
WurflUserAgentPriorityOverrideSideloadedBrowserUserAgent
or
WurflUserAgentPriorityUsePlainUserAgent
You can choose between these two options in order to decide the useragent priority to use. WurflUserAgentPriorityOverrideSideloadedBrowserUserAgent tells WURFL to use the sideloaded browser user agent for device detection, while WurflUserAgentPriorityUsePlainUserAgent tells WURFL to use the plain user agent instead. 1.5.2

Capabilities and Virtual Capabilities in WURFL Apache module

You can insert any number of WurflRequestCapability directives, specifying both capabilities and virtual capabilities. For the list of supported WURFL capabilities, see official website for list of WURFL Capabilities. As of release 1.8.0.0, there is no need to include the mandatory capabilities list in the conf file.

Warning: If you do not include any WurflRequestCapability directives in the config file, the Apache Module will load ALL WURFL capabilities found in the WURFL database. This scenario may be useful when used with a pre-filtered version of the WURFL database with limited sets of capabilities; however, we strongly recommend using the predefined list of capabilities stored in the config file. Please be aware that loading too many capabilities (e.g. over 500 capabilities) may cause missing environment variables due to overflow limits and performance level may be degraded.

WURFL Properties

The WURFL Apache module sets some useful convenience variables to retrieve information regarding the currently active WURFL configuration.
These variables are automatically calculated and are injected in HTTP requests if specified in a WurflRequestProperty command.
Please note that the wurfl_id variable is injected by default so you don't have to specify it in a WurflRequestProperty command.

WURFL Properties Table

Variable Name Contents Availability
wurfl_id Contains the device ID of the matched device. It is injected by default so you don't have to specify it in a wurfl_request_property command 1.4
wurfl_root_id Contains the device root ID of the matched device. 1.4
wurfl_isdevroot Tells if the matched device is a root device. Possible values are "TRUE" or "FALSE" 1.4
wurfl_useragent The original useragent coming with this particular web request 1.5.1
wurfl_api_version Contains a string representing the currently used Libwurfl API version 1.5.1
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
wurfl_info A string containing information on the parsed wurfl.xml and its full path 1.5.1
wurfl_last_load_time Contains the UNIX timestamp of the last time WURFL has been loaded successfully. 1.5.1
wurfl_normalized_useragent The normalized useragent. 1.5.1.3
wurfl_useragent_priority The user agent priority used by WURFL. 1.5.2

Testing WURFL Apache Module

For every HTTP requests, the WURFL Apache Module will detect and push the device capabilities data to the Apache Environment. The WURFL variable names will be shown in uppercase and prefixed with WURFL_. For example, the brand_name capability will be shown as WURFL_BRAND_NAME.

To view results of WURFL capabilities, see the outputs of Apache Environment variables for each HTTP Requests. For example, use the following command on a PHP Script to show output of Apache Environment variables:

var_export($_SERVER);

Instead of PHP, you can run the simple CGI script called printenv.pl that usually comes along with the Apache installs. Load the following GGI script to Apache environment:

#!/usr/bin/perl
print "Content-type: text/plain\n\nENVIRONMENT VARIABLES!\n\n";
print "$_ = '$ENV{ $_ }'\n" for sort keys %ENV;

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.