Documentation

Unblu 6 (latest)

Native Apache2 Unblu Module the Core SecureFlow Manager Filter Library

Now that the collaboration server runs you can add the SecureFlow Manager (filter) to your reverse proxy server so that it forwards the co-browsing requests to the collaboration server.

By way of an example this section describes how to build the Apache 2 modules mod_unblufilter and libunblufilter.

When attempting to run Microsoft Internet Explorer with web servers there are some (‘Keep-alive’ timeout) issues to bear in mind. For more on this see: Reverse Proxy Integration.
You can run the SecureFlow Manager on a number of common proxies or web application firewalls, including AdNovum nevisProxy or Airlock. It is even possible to run the SecureFlow Manager in a custom installation. If you have any doubts as to whether the SecureFlow Manager will run on your reverse proxy solution then contact us with your details.
This document focuses on Unix/Linux OS (x86 and x86_64 platforms) but unblu supports a variety of other platforms.

For more on the SecureFlow Manager and its many uses, see: SecureFlow Manager Usage.

If you need to adapt the filter (SecureFlow Manager) integration you can find a full specification here: Filter Specification.

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

Source Packages

The distribution contains the following packages (.tar.gz) in source code form, which is based on GNU Autobuild for building and installation convenience under Linux and Unix:

libunblufilter

provides the core unblu functions, such as adding unblu'`s functions to the website.

mod_unblufilter

wraps the core functions and provides libunblufilter to Apache 2 as a filter.

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. It contains 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 are required to forward any requests to /unblu/ (the Collaboration Server - except if you use your own proxy setup):

mod_proxy

mod_proxy_http

libunblufilter Dependency

Building mod_unblufilterrequires 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.

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

In order to build libunblufilter unpack it with the following commands:

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

  • --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 will not build a shared object. 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: 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 libdir.

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