Native Apache2 Unblu Module And Unblu Core Filter Library

1. Purpose

This document describes how to build the Apache2 module (mod_unblufilter) as well as libunblufilter (prerequisite of mod_unblufilter). While building works on various Unix and Linux platforms as well as Windows, the document is currently focused on Unix/Linux OS (x86 and x86_64 platforms).

2. Introduction

In order to install unblu as a filter in your Apache 2 web server, Unblu inc. delivers two packages (.tar.gz) in source code form which is based on GNU autobuild for building and installation convenience under Linux and Unix.

2.1. Source Packages

  • libunblufilter:
    Provides core unblu functionality like "code injection" and detection if code injection is required according to some configuration.
  • mod_unblufilter:
    wraps and provides libunblufilter to Apache 2 as a filter

2.2. Build and Runtime dependencies

2.2.1. General package dependencies

mod_unblufilter depends directly on libunblufilter which is to be built beforehand (see below). In addition it depends on

  • curl (at runtime, curl-dev at build time)
  • libexpat (at runtime)
  • uuid (at build time)
  • libidn (at runtime, libidn-dev at build time)

Please see the README file of the mod_unblufilter dist package. It contains more accurate informations about dependencies as well as (linux distro-) specific package name informations.

2.2.2. Apache dependencies

In addition to the above package dependencies, building mod_unblufilter requires Apache 2 as well as the Apache 2 specific development assistance tool apxs (see http://httpd.apache.org/docs/2.2/programs/apxs.html for details) to be present. Again, see the README file for details especially about the required package name to include for your distro.

2.2.2.1. Apache runtime dependencies

  • mod_filter

At runtime, mod_unblufilter will require mod_filter module to be present (see http://httpd.apache.org/docs/2.2/mod/mod_filter.html). This is required for the sake of simplicity when it comes to configure mod_unblufilter as a filter in Apache 2 in the required filter chain position.

Optional (usually required, but some projects have their own proxy setup):

  • mod_proxy
  • mod_proxy_http

This is required to forward any requests to /unblu/ to the backend unblu server.

2.2.3. libunblufilter dependency

As mentionned, building mod_unblufilter requires building libunblufilter first. In order to have a simple setup in the end, it is recommended to include libunblufilter as a static library into mod_unblufilter. As such, there is no runtime dependency to libunblufilter.so. Instead, mod_unblufilter is self-contained and only depends on typical system libraries (libc etc.).
Be advised, that this is a recommendation, not a hard requirement. If shared objects are the preferred way to go, building and using them is possible with no extra effort. It is all configurable during builds.

3. Building

For both builds, mod_unblufilter as well as libunblufilter it is possible to build DEBUG or RELEASE versions. They differ in that DEBUG is not optimized for speed, and any stack traces / core dumps are more reliable. Both build types however will include symbols by default.
In addition DEBUG builds may have additional or slightly different diagnostic code enabled. It is recommended, to have both build versions available for installation. In early test environments (development env), DEBUG builds are preferred, in late system integration or acceptance test environments, RELEASE versions are recommended.

Production environments must use RELEASE versions only.

3.1. Building libunblufilter

In order to build libunblufilter, unpack it as follows:

tar zxf libunblufilter.tar.gz
cd libunblufilter

If tar is not able to unzip directly, unzip it first with gunzip:

gunzip libunblufilter.tar.gz
tar xf libunblufilter.tar
cd libunblufilter

All build commands below will assume, that you're in the extracted libunblufilter directory.

3.1.1. Release build

The following list of commands is the suggestion to be used for a release version build of libunblufilter with direct installation of the resulting library into /usr/local/include (header file) and /usr/local/lib (or .../lib64 if x86_64 is the current arch and build type and the directory exists). This is, what's typically required to afterwards build depending libraries such as mod_unblufilter.

mkdir -p build/RELEASE
cd build/RELEASE
../../configure --with-pic --disable-shared
make
sudo make install

Options:

  • with-pic is required to make sure, position independant code is generated (required, if a library is to be used in another library - as in our case with the apache module).
    Libtool generally generates PIC code as well as non-PIC code. PIC code ends up in the shared module, non-PIC in the static library. In our case, we want both libraries to be PIC, since both are intended to be used in a shared library. We actually enforce to produce PIC only code, but due to a bug in libtool, the enforcement does not work and thus requires user intervention here.
  • disable-shared will not build a shared object. Thus, building a module later that depends on libunblufilter will automatically choose the static library instead of the shared module. This is the recommended build configuration. Drop this option, if you want libunblufilter to be used as shared module later on.
  • libdir: library installation directory. This is automatically chosen to be /usr/local/lib64, if x86_64 is the chosen build (which it is by default on such a machine) and /usr/local/lib64 exists. You may override this by explicitely specifying libdir.
    Note, that specifying libdir will not affect the installation directory of the unblu_filter_api.h header file. This will still end up in /usr/local/include by default. Specify prefix if you want to alter this.
    Example:

    ../../configure --with-pic --libdir=/usr/lib64
    
  • DESTDIR option: Prefix to be used when "installing" library and header file. Useful when output should not be used directly but instead e.g. packaged. Note that this prefix will even "extend" the previous --libdircommand by that it will prefix this as well. Example:

    ../../configure --with-pic --libdir=/usr/lib64
    make install DESTDIR=/tmp/libunblufilter
    # produces a directory structure like /tmp/libunblufilter/usr/lib64/libunblufilter.so... as well as /tmp/libunblufilter/usr/local/include/unblu_filter_api.h
    
  • Installation into directories such as /usr/lib or /usr/local/lib may require root rights. This is why in the above example, installation happens with sudo make install.

3.1.2. Debug / test build

Building the debug version is generally the same as for the release version, except that there is an additional option --enable-debug to be provided to configure. All other options are the same as for the release version.

mkdir -p build/DEBUG
cd build/DEBUG
../../configure --enable-debug --with-pic --disable-shared
make
sudo make install

3.2. Building mod_unblufilter

mod_unblufilter is the Apache 2 (filter) module to be installed to Apache 2 to support unblu.

3.2.1. mod_unblufilter unpacking

In order to build mod_unblufilter, unpack it as follows:

tar zxf mod_unblufilter-1.0.0.tar.gz
cd mod_unblufilter-1.0.0

If tar is not able to unzip directly, unzip it first with gunzip:

gunzip mod_unblufilter-1.0.0.tar.gz
tar xf mod_unblufilter-1.0.0.tar
cd mod_unblufilter-1.0.0

3.2.2. Release build

Once unpacked, this is how to build mod_unblufilter:

mkdir -p build/RELEASE
cd build/RELEASE
../../configure --with-apxs=/usr/sbin/apxs
make
make install DESTDIR=/tmp/mod_unblufilter

Options:

  • with-apxs: specify path to apxs tool. If apxs is in standard directories or reachable with $PATH, then this may not be needed.
  • DESTDIR: Without specifying DESTDIR installation will happen into the Apache 2 modules directory as retrievable via apxs. For packaging builds, this may not be intended. Instead, "stage" installing into some other directory may be preferred. In such situations, DESTDIR specifies a prefix to be used. In the above example, if Apache 2 modules are located in /usr/lib64/httpd/modules, after installation, mod_unblufilter would be located under /tmp/mod_unblufilter/usr/lib64/httpd/modules/

Note that make install does not require root access rights, if using DESTDIR with a target that is writable by the current user (such as /tmp). Such rights are required, though, if no DESTDIR is specified.

3.2.3. Debug build

Building the debug version is generally the same as for the release version, except that there is an additional option --enable-debug to be provided to configure. All other options are the same as for the release version.

mkdir -p build/DEBUG
cd build/DEBUG
../../configure --enable-debug --with-apxs=/usr/sbin/apxs
make
make install DESTDIR=/tmp/mod_unblufilter

4. Configure Apache 2

Note: The dist package of mod_unblufilter provides a config directory containing a number of example configurations for various platforms. These examples are more accurate than descriptions in this document.

The following example is "self contained". That is: With this configuration all Apache2 configurations required to let unblu run over this apache are included. In particular, that includes configuration of a reverse proxy path for /unblu requests, adding mod_unblufilter using the mod_filter Apache2 module and the mod_unblufilter configuration itself.

Configuration:

################################################################################
# Configure reverse proxy to /unblu of unbluserver 
<IfModule !mod_proxy.c>
LoadModule proxy_module modules/mod_proxy.so
<IfModule !mod_proxy_http.c>
LoadModule proxy_http_module modules/mod_proxy_http.so
</IfModule>
</IfModule>

ProxyRequests Off

<Proxy *>
	Order deny,allow
	Allow from all
</Proxy>

ProxyPass /unblu/ http://unbluserver/unblu/
ProxyPassReverse /unblu/ http://unbluserver/unblu/

################################################################################
# Configure unblu
LoadModule unblufilter_module modules/mod_unblufilter.so
UnbluServerUrl http://unbluserver/

UnbluConfigOrigin local
UnbluConfigDirectory /etc/httpd/unblu/unblu.conf

################################################################################
# Advanced Unblu Configuration
# following settings are defaults - uncomment and adapt to change
#UnbluPublicPathPrefix /unblu
#UnbluSystemPathPrefix /sys-unblu
#UnbluServerAdminBackend rest/filterBackend
#UnbluDefaultCharset ISO-8859-1
#UnbluConfigOrigin local
#UnbluConfigDirectory /etc/httpd/unblu/unblu.conf
#UnbluConfigExpiration 3600
#UnbluMaxResponseSizeResource 100kb
#UnbluMaxResponseSizeInjection 10kb

################################################################################
# Add us to the filter chain
<IfModule !mod_filter.c>
LoadModule filter_module modules/mod_filter.so
</IfModule>

# The following lines require filter_module to be active!
# See http://httpd.apache.org/docs/2.1/mod/mod_filter.html for details about filters

# FilterProvider Syntax:
# 	FilterProvider filter-name provider-name  [req|resp|env]=dispatch match
# NOTE: don't change the provider-name (unblufilter) - it's hardcoded and wires this configuration with the filter module
FilterProvider unblufilter unblufilter resp=Content-Type *

# FilterChain Syntax:
# 	FilterChain [+=-@!]filter-name ...
# NOTE: The @ before the filter-name ensures, the filter is inserted at the first position
FilterChain @unblufilter

4.1. Configuration parameter description

4.1.1. Reverse proxy

The following settings are "generic" and usually need no adaptation:

  • IfModule !mod_proxy.c: load mod_proxy if not loaded already
  • IfModule !mod_proxy_http.c: load mod_proxy_http if not loaded already
  • ProxyRequests: Configure this as a reverse proxy (thus set to "no" to disable forward proxy capabilities)
  • Proxy section: configure access control to proxy (allow all)

The following two lines require adaptation: "unbluserver" must be replaced with the according hostname plus port (if non-standard) of the backend unblu server.

  • ProxyPass: configure /unblu requests to be proxied
  • ProxyPassReverse: Make sure response headers are adapted accordingly to have a transparent reverse proxy

4.1.2. Unblu configuration

The following settings are required and must be adapted accordingly:

  • LoadModule: load mod_unblufilter
  • UnbluServerUrl: hostname and path of the backend unblu server or a proxy, where the server should be reached through

The following settings are commented out since they represent defaults:

  • UnbluPublicPathPrefix: Must have a leading slash and otherwise match the setting of com.unblu.identifier.publicPathPrefixPattern in the unblu server (unblu by default)
  • UnbluSystemPathPrefix: Must have a leading slash and otherwise match the setting of com.unblu.identifier.systemPathPrefixPattern in the unblu server (sys-unblu by default)
  • UnbluServerAdminBackend: The url of the admin backend to be used by the Apache 2 unblu filter. Typically fixed to the default rest/filterBackend (unlikely to change)
  • UnbluConfigOrigin: Can be either local or remote(default).
    • If local, the config file is supposed to be located at UnbluConfigDirectory (UnbluConfigDirectory being the path and filename in this case).
      Note, that UnbluConfigExpiration is ignored when local is selected.
    • If remote, the config file will be downloaded from the remote Unblu server and stored into the directory given by UnbluConfigDirectory (which must be writable and readable in this case).
  • UnbluDefaultCharset: Charset to be assumed, if none is specified in a http (text) response.
  • UnbluConfigDirectory: If UnbluConfigOrigin is set to remote, this is not required. If UnbluConfigOrigin is set to local, this must specify path and filename of the configuration file.
  • UnbluConfigExpiration: Time in seconds until the downloaded configuration of the unblu server expires and must be re-downloaded. Ignored, if UnbluConfigOrigin is set to local

4.1.3. mod_filter configuration

  • FilterProvider: mod_filter specific command to enable mod_unblufilter as a filter in Apache 2
  • FilterChain: specifies, where in the filter chain unblu should be called. Unblu must be called before any url transformations are performed (like url en-/de-cryption etc.)

How can we help?

Chat with us and we will take you through our site!

Read about how we use cookies and how you can control them by clicking "Cookie Settings." If you continue to use this site, you consent to our use of cookies.