This document describes version 5 of Unblu. If you’re using the latest major version of Unblu, go to the documentation of the latest version. The support period for version 5 ended on 22 November 2021. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu. |
Installing the SecureFlow Manager (Filter)
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_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. |
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 uselibunblufilter
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