Installing the SecureFlow Manager on Apache HTTP Server

Requirements

For installation on the Apache HTTP Server, the SecureFlow Manager is delivered as two source code packages:

libunblufilter.tar.gz
mod_unblufilter.tar.gz

To install the SFM on Apache you will need to build the contents of these packages using the GNU Build System.

These directions assume that you are building and deploying in a Unix environment. To build and deploy on Windows or another platform you will need to adapt these instructions appropriately.

The libunblufilter package comprises the core functionality of the SFM.

The mod_unblufilter package wraps libunblufilter and makes it available as an .so file for deployment as a filter in the Apache instance. You need to build libunblu The end result of your build and install process should be that mod_unblufilter

General Package Dependencies

mod_unblufilter depends directly on libunblufilter (so you need to build libunblufilter first). In addition, it depends on the following:

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

See the README file of the mod_unblufilter distribution package for more detailed information about dependencies as well as package names for each distribution.

Apache 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). See the README file for details; especially concerning the required package name to include for your distribution.

At runtime mod_unblufilter will require the 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 configuring mod_unblufilter as a filter in Apache 2 in the required filter chain position.

Usually the following addtional modules are required to forward any requests to /unblu/ (i.e. the Unblu server):

mod_proxy
mod_proxy_http

libunblufilter Dependency

Building mod_unblufilter requires building libunblufilter first. In order to have a simple setup in the end, we recommend you include libunblufilter as a static library in mod_unblufilter. Thus, there is no runtime dependency to libunblufilter.so. Instead, mod_unblufilter is self-contained and only depends on typical system libraries (libc etc.).

This is a recommendation, not a hard requirement. If you prefer to use shared objects, building and using them is possible with little extra effort. You can configure this during the build process.

Package Requirements

There are no requirements to third party libraries. Required libraries (json-c and pcre) are directly included in this package as nested packages.

All system requirements are checked with ./configure call. If any are not met, configure will complain with a message. In case of doubt about a certain package (name / version), it is safe to just try ./configure - if it succeeds, installed packages are fine.

Building the module

This package contains the full source code to build. It is based on GNU autobuild tools. As such, building is typically done the following way: * extract the package * (optional): create a ./build subdirectory (to avoid having build .o files in the middle of source code) * decide what configure options you want to use: * --enable-debug: if you want to have a build including debug symbols and without optimization. *DO NOT use the resulting file in production! * run configure, make

Example

tar zxf libunblufilter-1.7.5.tar.gz
cd libunblufilter-1.7.5
mkdir build
cd build
../configure --enable-debug
make

The resulting module will be located at libunblufilter-1.7.5/build/src/main/.libs/libunblufilter.so

In order to have this module available for further compilations (e.g. when building mod_unblufilter afterwards) it is recommended to "install" the module: make install

If you don’t want to have libunblufilter installed in it’s default locations, you may use DESTDIR to specify the target directory to "install" into make install DESTDIR=/tmp/libunblufilter

Building

Both mod_unblufilter and libunblndufilter, can be built in DEBUG or RELEASE versions. The versions differ in that DEBUG is not optimized for speed, and stack traces / core dumps are more reliable. However, both build types will include symbols by default. In addition, DEBUG builds may have additional or slightly different diagnostic code enabled. We recommend you build both versions. In development and early test environments DEBUG builds are typically better. In late system integration or acceptance test environments, we recommend you use RELEASE versions. Production environments must use RELEASE versions only.

Building libunblufilter

To build libunblufilter, do the following:

$ tar zxf libunblufilter.tar.gz
$ cd libunblufilter

If the tar command is not able to unpack the file directly, use gunzip first:

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

All build commands below will assume that you are in the extracted libunblufilter directory.

Release Build Options

Now execute the configure with appropriate options. For example:

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

--with-pic is required to make sure that position-independent code is generated (this is required if a library is used in another library — as in the case here with the apache module). Libtool generally generates PIC code as well as non-PIC code. PIC code is used for the shared module, non-PIC for the static library. Here, both libraries need to be PIC, since both are intended for a shared library.
--disable-shared indicates that a non-shared (static) object is to be built. This means that when you build a module later that depends on libunblufilter, the target will be the static library and not the shared module. This is the recommended build configuration. Remove this option if you want to use libunblufilter as a shared module.
--libdir:<dir> specifies the library installation directory. If the build is x86_64 and /usr/local/lib64 exists, the default is /usr/local/lib64 . You may override the default by specifying the directory with this option.

Specifying libdir will not affect the installation directory of the unblu_filter_api.h header file. This will still default to /usr/local/include. Specify a prefix if you want to alter this, for example:

../../configure --with-pic --libdir=/usr/lib64

DESTDIR (option): The prefix used when installing the library and the header file. Use this if the output should not be used directly but for a packaged example. Note that this will prefix the previous --libdir command as well.

The following example uses DESTDIR:

../../configure --with-pic --libdir=/usr/lib64 make install DESTDIR=/tmp/libunblufilter

This 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 access. This is why in the above example the installation uses sudo make install.

Debug / test build

Building the debug version is generally the same as the release version, except that you add the option --enable-debug to the configure command. 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

Building mod_unblufilter

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

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 the tar command is not able to unpack the file directly, use gunzip first:

gunzip mod_unblufilter-1.0.0.tar.gz

tar xf mod_unblufilter-1.0.0.tar

cd mod_unblufilter-1.0.0

Once unpacked, build mod_unblufilter as follows:

mkdir -p build/RELEASE

cd build/RELEASE ../../configure --with-apxs=/usr/sbin/apxs

make

make install DESTDIR=/tmp/mod_unblufilter

Options

with-apxs: specify the path to the apxs tool. (If apxs is in standard directories or can be reached via $PATH, this is not necessary.)
DESTDIR: Without specifying DESTDIR, the target of the installation is the Apache 2 modules directory as retrieved via apxs. For packaging builds this may not be intended. Instead, you may prefer to use a ‘staged’ installation in a different directory. 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/

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.

Building the debug version is generally the same as the release version, except that you add the option --enable-debug to the configure command. 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

Configuring Apache 2 (Example)

For a more complete description on how to build the Apache 2 module and Filter see: Installing the Filter

The dist package of mod_unblufilter provides a config directory containing a number of example configurations for various platforms.

The following example is ‘self-contained’. That is: With this configuration, all Apache 2 configurations required to run unblu via this apache server are included. In particular, this includes configuration of a reverse proxy path for /unblu requests, adding mod_unblufilter using the mod_filter Apache 2 module and the mod_unblufilter configuration itself.

Example Configuration

############################################################
# Configure reverse proxy to /unblu of collaboration server

<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
UnbluModule On
UnbluServerUrl http://unbluserver/
UnbluConfigOrigin local
UnbluConfigDirectory /etc/httpd/unblu/unblu.conf
#############################################################
# Advanced Unblu Configuration
# the following settings are defaults - uncomment and adapt them
#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 the filter module 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: do not change the provider-name (unblufilter) - it is hardcoded
# and connects this configuration to the filter module

FilterProvider unblufilter resp=Content-Type *

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

FilterChain @unblufilter
#############################################################

Configuration Parameter Description

Reverse proxy server

The following settings are generic and usually need no adaptation:

IfModule !mod_proxy.c: loads mod_proxy if not loaded already
IfModule !mod_proxy_http.c: loads 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 hostname plus port (if non-standard) of the backend collaboration server.

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

The following settings are required and must be adapted accordingly:

LoadModule: load mod_unblufilter
UnbluServerUrl: hostname and path of the backend Collaboration Server or a proxy, where the server can be reached.

The following settings are commented out (in the provided example configuration) because they represent default values:

UnbluPublicPathPrefix: Must have a leading slash and otherwise match the setting of com.unblu.identifier.publicPathPrefix in the Unblu Server (unblu by default).
UnbluSystemPathPrefix: Must have a leading slash and otherwise match the setting of com.unblu.identifier.systemPathPrefix in the Unblu Server (sys-unblu by default).
UnbluServerAdminBackend: The URL of the admin backend to be used by the Apache 2 filter. Typically fixed to the default rest/filterBackend (unlikely to change).
UnbluConfigOrigin: Can be either local or remote (default).

If local, the configuration file must be located at UnbluConfigDirectory (UnbluConfigDirectory is the path and filename in this case).

UnbluConfigExpiration is ignored when local is selected.

If remote, the configuration file will be downloaded from the remote Collaboration Server and stored in the directory given by UnbluConfigDirectory (which must be writable and readable in this case).

UnbluDefaultCharset: Character set used if none is specified in an http (text) response.
UnbluConfigDirectory: If UnbluConfigOrigin is set to remote, this is not required. If UnbluConfigOrigin is set to local, this must specify the 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.

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 is called. unblu must be called before any URL transformations are performed (such as URL encryption or decryption).