Contact usRequest a demo

Installing the SecureFlow Manager on the Apache 2 HTTP server

This article describes how to install the SecureFlow Manager (SFM) on Apache 2. It assumes you are building and deploying in a Unix environment. To build and deploy on Windows or another platform, adapt the instructions accordingly.

Installing the SFM on Apache 2 consists of using the GNU Build System to build the contents of the following two packages:

  • libunblufilter.tar.gz comprises the core functionality of the SFM.

  • mod_unblufilter.tar.gz wraps libunblufilter and makes it available as an .so file for deployment as a filter in the Apache instance.

Requirements

Required third-party libraries--json-c and pcre--are directly included as nested packages. There are no further requirements for third-party libraries.

You can verify that your system meets the requirements to build and run the SFM by running ./configure once you’ve extracted the packages' source code.

Apache dependencies

Building mod_unblufilter requires Apache 2 as well as the Apache 2-specific development assistance tool apxs. See the README file for details, especially concerning the required package name to include for your distribution.

At runtime, mod_unblufilter requires the mod_filter module. 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 additional modules are required to forward any requests to /unblu/, that is, the Unblu server:

  • mod_proxy

  • mod_proxy_http

mod_unblufilter dependencies

mod_unblufilter depends directly on libunblufilter, so you must build libunblufilter first. In addition, mod_unblufilter depends on the following packages:

  • 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.

Installing the SFM

Installing the SFM consists of two steps:

  1. Building libunblufilter

  2. Building mod_unblufilter

DEBUG and RELEASE versions

Both libunblufilter and mod_unblufilter can be built as DEBUG or RELEASE versions. The DEBUG version isn’t optimized for speed, but its stack traces and core dumps are more reliable. DEBUG builds may also have additional or slightly different diagnostic code enabled. However, both build types will include symbols by default.

You can build both versions:

  • In development and early test environments DEBUG builds are typically more appropriate.

  • In later system integration or acceptance test environments, you should use RELEASE versions.

Production environments must only use RELEASE versions. Never use DEBUG versions in production.

Building libunblufilter

The libunblufilter package contains the full source code to build the main functionality of the SFM. It is based on autobuild tools.

Listing 1. Commands to build libunblufilter 
tar zxf libunblufilter-1.7.5.tar.gz
cd libunblufilter-1.7.5
mkdir build (1)
cd build
../configure <options> (2)
make
1 Optional; if you don’t create a build directory, adapt the call to configure accordingly.
2 See below for a list of the options available. Run ../configure --help for further information.

The module that results from running the commands above is located at libunblufilter-1.7.5/build/src/main/.libs/libunblufilter.so.

To make the module available for further compilations, such as building mod_unblufilter afterwards, it is recommended that you install the module:

Listing 2. Command to install libunblufilter 
make install DESTDIR=/tmp/libunblufilter (1)
1 DESTDIR is optional. It specifies the target directory. Use it if you don’t want libunblufilter installed to its default location, or if the output should be used for a packaged example.

make install doesn’t require root access if DESTDIR points to a target that is writable by the user executing the command. If no DESTDIR is specified, you need root access.

The following build options are available:

  • --with-pic is required to generate position-independent code (PIC). PIC code is used for the shared module, non-PIC for the static library.

    Libtool generally generates both PIC and non-PIC code.

  • --disable-shared builds a static object. This means that when you build a module that depends on libunblufilter, the target is the static library and not the shared module. This is the recommended build configuration.

    Don’t include 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 directory is /usr/local/lib64 . To override the default, specify a directory with this option.

    Specifying --libdir doesn’t affect the installation directory of the unblu_filter_api.h header file, which defaults to /usr/local/include. Specify a prefix with DESTDIR if you want to change the installation directory for the header file:

    Listing 3. Building libunblufilter with --libdir and DESTDIR 
    ../../configure --with-pic --libdir=/usr/lib64
make install DESTDIR=/tmp/libunblufilter

    This results in the following directory structure:

    Listing 4. Directory structure using --libdir and DESTDIR 
    /tmp/libunblufilter/usr
├── lib64
│   └── libunblufilter.so
│
└── local
    └── include
        └── unblu_filter_api.h

  • --enable-debug builds a DEBUG version of libunblufilter.

Include libunblufilter as a static library

The recommended way to build libunblufilter is to include it as a static library in mod_unblufilter. That way, there is no runtime dependency to libunblufilter.so. Instead, mod_unblufilter only depends on typical system libraries such as libc.

Including mod_unblufilter as a static library is only a recommendation, not a hard requirement. You can build and use the module as a shared object with little extra effort.

Building mod_unblufilter

To build mod_unblufilter, run the following commands:

Listing 5. Commands to build mod_unblufilter 
tar zxf mod_unblufilter-1.0.0.tar.gz
cd mod_unblufilter-1.0.0
mkdir -p build/RELEASE (1)
cd build/RELEASE
../../configure --with-apxs=/usr/sbin/apxs (2)
make
make install DESTDIR=/tmp/mod_unblufilter (3)
1 Optional; if you don’t create a build directory, adapt the call to configure accordingly.
2 The path to the apxs tool. Not required if apxs is in a standard directory or can be reached via $PATH.
3 By default, the installation target is the Apache 2 modules directory as determined by apxs. DESTDIR specifies a prefix to use before the modules directory. This is useful if you want to perform a staged installation.

In the example above, if the 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 doesn’t require root access if using DESTDIR with a target that is writable by the user executing the command. If no DESTDIR is specified, you need root access.

To build the DEBUG version of mod_unblufilter, include the option --enable-debug. The options available when building the debug version are the same as for the release version.

Listing 6. Building the debug version of mod_unblufilter 
mkdir -p build/DEBUG
cd build/DEBUG ../../configure --enable-debug --with-apxs=/usr/sbin/apxs
make
make install DESTDIR=/tmp/mod_unblufilter

Configuring the SFM

Once you’ve installed libunblufilter and mod_unblufilter, you have to configure Apache 2 to use it.

The following commented and annotated example configuration is self-contained. It includes all the configurations required to run Unblu via an Apache 2 server. In particular, it includes the 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.

If you have multiple Unblu accounts running on the same Unblu server, you can use the Unblu directives within <VirtualHost> blocks in the Apache configuration. In particular, setting the UnbluApiKey differently in each block allows the SFM to distinguish between requests for different accounts.

The distributed mod_unblufilter package contains a config directory with a configuration example.

Listing 7. Example configuration for the SFM on Apache 2 
############################################################
# Configure reverse proxy to /unblu of Collaboration Server

<IfModule !mod_proxy.c> (1)
LoadModule proxy_module modules/mod_proxy.so
<IfModule !mod_proxy_http.c> LoadModule proxy_http_module modules/mod_proxy_http.so (2)
</IfModule>
</IfModule>

ProxyRequests Off (3)

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

ProxyPass /unblu/ http://unbluserver/unblu/ (5)
ProxyPassReverse /unblu/ http://unbluserver/unblu/ (6)
#############################################################
# Configure Unblu
LoadModule unblufilter_module modules/mod_unblufilter.so (7)
UnbluModule On
UnbluServerUrl http://unbluserver/ (8)
UnbluConfigOrigin local (9)
UnbluConfigDirectory /path/to/your/unblu.conf (10)
UnbluApiKey yourUnbluAPIKey (11)
UnbluCompatMode 6 (12)
#############################################################
# Advanced Unblu Configuration
# the following settings are defaults - uncomment and adapt them
#UnbluPublicPathPrefix /unblu (13)
#UnbluSystemPathPrefix /system (14)
#UnbluServerAdminBackend rest/filterBackend
#UnbluDefaultCharset ISO-8859-1 (15)
#UnbluConfigOrigin local
#UnbluConfigDirectory /etc/httpd/unblu/unblu.conf
#UnbluConfigExpiration 3600 (16)
#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.4/mod/mod_filter.html
# for details about filters
# FilterProvider Syntax:
# FilterProvider filter-name provider-name  expression
# NOTE: do not change the provider-name (unblufilter) - it is hardcoded
# and connects this configuration to the filter module
#
FilterProvider chatfilter unblufilter  "%{CONTENT_TYPE}=~ /.*/" (17)

# FilterChain Syntax:
# FilterChain [+=-@!]filter-name ...
# NOTE: The @ before the filter-name ensures that the filter is inserted at the
# first position
#
FilterChain @unblufilter (18)
#############################################################
1 Load mod_proxy if it hasn’t already been loaded.
2 Load mod_proxy_http if it hasn’t already been loaded.
3 Set to Off to disable forward proxy capabilities.
4 Configure access control to proxy.
5 Proxy requests to /unblu. Replace https://unbluserver with the host name of the Unblu Collaboration Server. If running on a non-standard port, include the port.
6 Make sure response headers are adapted to have a transparent reverse proxy Unblu configuration. Replace https://unbluserver with the host name of the Unblu Collaboration Server. If running on a non-standard port, include the port.
7 Load mod_unblufilter.
8 The host name and path of the Unblu Collaboration Server, or a proxy by which the server can be reached.
9 Load the unblu.conf Unblu configuration file from a local or remote source.
10 The local path to your unblu.conf file.

  • If UnbluConfigOrigin is set to local, the value should be the path and filename of the local configuration file.

  • If UnbluConfigOrigin is set to remote, the value should be the path to a directory. The Unblu server stores the configuration file there under the name unblu_<yourUnbluApiKey>.config.
11 Your Unblu API key.
12 The compatibility mode for the Unblu server. Set to the major version of your Unblu installation, such as UnbluCompatMode 6 for Unblu 6.
13 If changed, the new value must have a leading slash. The remainder must match the configuration property com.unblu.identifier.publicPathPrefix in the Unblu Server.
14 If changed, the new value must have a leading slash. The remainder must match the configuration property com.unblu.identifier.systemPathPrefix in the Unblu Server.
15 The character set used if none is specified in an HTTP (text) response.
16 The time, in seconds, until the configuration file downloaded from the Unblu Server expires and has to be downloaded again. Ignored if UnbluConfigOrigin is set to local.
17 mod_filter-specific command to enable mod_unblufilter as a filter in Apache 2.
18 Specifies where in the filter chain Unblu is called. Unblu must be called before any URL transformations such as URL encryption or decryption.