This document describes version 6 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 6 ended on 29 August 2023. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu.

Installing and configuring the SecureFlow Manager on Nginx

This article describes how to add the SecureFlow Manager (SFM) to an Nginx reverse proxy.

For Nginx, the SecureFlow Manager is provided as a dynamic module (.so) called unblufilter. To use the SFM with your Nginx reverse proxy, you will have to build the dynamic module and add a number of directives to your Nginx configuration files.

This article assumes you have a functioning installation of Nginx version 1.9.11 or greater. The unblufilter dynamic module does not run on older versions of Nginx.

Prerequisites

Before building and installing the SFM, ensure that you have the following software installed on your system:

GCC version 4.8.1 or greater, the GNU C/C+\+ compiler, with support for the C\+\+11 standard
make

You can install both applications these using your distribution’s package manager. On Ubuntu, for example, run the following command to install the GCC compiler and make:

Listing 1. Installing SFM general dependencies on Ubuntu

sudo apt-get install -y build-essential

Obtaining the SFM source code

The SFM is provided as a set of two zipped tarballs:

The first archive contains the libunblufilter library, which provides the main functionality of the SFM.
The second archive contains a wrapper tailored to the system you want to integrate the SFM into.

If you don’t have the SFM source code yet, please contact a member of the Unblu Services team.

Installing the `libunblufilter` library

All system-specific SFM implementations, including the Nginx module, rely on the libunblufilter library. You must install the library before you configure and build unblufilter for Nginx.

Before you can install libunblufilter, you must configure and run its build.

Configuring the `libunblufilter` build

The code snippet below shows how to configure the build of the libunblufilter library:

Listing 2. Configuring the libunblufilter build

tar xvf <libunblufilter-tarball-name>.tar.gz (1)
cd libunblufilter-<version>/ (2)
mkdir build (3)
cd build/ (4)
../configure <OPTIONS> (5)

1	Replace `<libunblufilter-tarball-name>` with the archive’s name
2	Replace `<version>` with the version number of the `libunblufilter`
3	Optional; use to separate your build files from the source files
4	Only necessary if you created a `build` directory in the previous step
5	Replace `<OPTIONS>` with zero or more of the options listed in the following section

The options available for configuring the libunblufilter library are:

--enable-debug

This option is used to build the library with debug symbols and without optimization.

DO NOT use the resulting file in production.

--with-pic

This option is required to generate position-independent code (PIC). This is required if a library is used in another library. libtool generates both PIC and non-PIC. PIC 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

The option --disable-shared indicates that a static (non-shared) object should be built. Later, when you build a module 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>

Use the option libdir to specify the library’s installation directory. The default installation directory is /usr/local/lib64, provided the build is x86_64 and the directory /usr/local/lib64 exists. Replace <DIR> with your preferred installation directory if you don’t want to use the default.

Specifying the installation directory doesn’t affect the installation directory of the unblu_filter_api.h header file. The latter will still default to /usr/local/include. See the DESTDIR install option below for information on how to change the installation directory of the library and the header file.

The result of the configuration step will be a makefile that you can use to build the library.

Building and installing the `libunblufilter` library

To build the library, run the following commands:

Listing 3. Building and installing the libunblufilter library

make
sudo make install [OPTION]

There is only one make install option, DESTDIR=<dir>, 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.

The DESTDIR option will prefix the previous --libdir command as well. Consider the shell commands below:

Listing 4. Example of installing libunblufilter with the DESTDIR option

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

This will put both libunblufilter.so and unblu_filter_api.h in the directory /tmp/libunblufilter/usr/local. Without --libdir=/usr/local, the files would be installed at /tmp/libunblufilter/usr/lib64/libunblufilter.so and /tmp/libunblufilter/usr/local/include/unblu_filter_api.h, respectively.

Once the libunblufilter library is available, you can proceed to install the SFM.

Installing the SecureFlow Manager on Nginx

Like the libunblufilter library, the SFM module for Nginx is provided as a zipped tarball archive. You will have to configure and build the module.

Dependencies

You should already have installed some of the tools needed when you built libunblufilter. The installation scripts provided with the module source code use some additional tools to extract configuration options:

curl as an HTTP client, and to download sources during the build
pcregrep
sed
xargs

You can install all of these using your distribution’s package manager. On Ubuntu, for example, run the following command:

Listing 5. Install SFM Nginx module dependencies on Ubuntu

sudo apt-get install -y \
    curl \
    libcurl4-openssl-dev \
    pcregrep \
    findutils \ (1)
    sed

1	Installs `xargs`

Installing the Nginx SFM module

The next step in the installation process is to unpack the archive and switch to the unblufilter directory. If you don’t have the archive for the Nginx SFM module yet, please contact a member of the Unblu Services team.

Listing 6. Unpacking the Nginx SFM module archive

tar zxf <sfm-module-name>.tar.gz (1)
cd unblufilter

1	Replace `<sfm-module-name>` with the name of the tarball

The unblufilter directory contains a number of scripts to help with the process of building and installing the module:

setup.sh determines your Nginx configure arguments, downloads the Nginx source code, and generates a makefile for the SFM module.
build.sh builds the SFM module using make modules. The resulting file is called ngx_http_unblufilter_module.so.
install.sh copies the SFM module to the directory specified in the --modules-path configuration argument of your Nginx installation.

Review the scripts and, if they suit your requirements, run them in order:

Listing 7. Building and installing the Nginx SFM module

mkdir build (1)
cd build/ (2)
../setup.sh
../build.sh
../install.sh

1	Optional; use to separate your build files from the source files
2	Only necessary if you created a `build` directory in the previous step

Configuring the Nginx SFM module

To enable the SFM module, add it to your Nginx configuration file. You can determine the location of your installation’s configuration file by running nginx -V and looking for the --conf-path configure argument. The directives for the SFM module can be added to either the http scope or the server scope. In the example below, they have been added to the server scope.

Listing 8. Enable and configure the SFM module for Nginx

load_module <modules-path>/ngx_http_unblufilter_module.so; (1)
...
  server {
    ...
    UnbluModule  on; (2)
    UnbluApiKey  <your-unblu-api-key>; (3)
    ...
  }

1	Load the module in the global scope of the configuration file. Replace `<modules-path>` with the value of the `--modules-path` configure argument.
2	Activate the SFM module.
3	See the available directives section below for an overview of the options available to configure the SFM module.

The directory unblufilter/config/templates in the unpacked archive contains examples of how to configure Nginx and the SFM module. Please review these examples carefully before you modify your Nginx configuration.

Available directives

To configure the SFM, set the following configuration parameters are available:

UnbluApiKey: Your Unblu API key. This directive is always required.
UnbluCompatMode: The compatibility mode for the Unblu Server. Set to the major version of your Unblu installation, such as UnbluCompatMode 6 for Unblu 6.
UnbluConfigOrigin: Where to retrieve the SFM configuration file from. Set to either local or remote.

There are two configuration parameters related to UnbluConfigOrigin:
- UnbluConfigDirectory: 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.
- UnbluConfigExpiration: The time, in seconds, until the downloaded configuration of the Unblu Server expires and must be downloaded again. Only required if UnbluConfigOrigin is set to remote; ignored if UnbluConfigOrigin is set to local.
UnbluCurlDisableCertValidation: Disable certificate validation using curl. Possible values are On and Off. Set to On to disable certificate validation.
UnbluDefaultCharset: Character set used if none is specified in an HTTP (text) response.
UnbluModule: Set to On to activate the SFM module.
UnbluPublicPathPrefix: Must match the setting of com.unblu.identifier.publicPathPrefix in the Unblu Server, preceded by a slash /.
UnbluServerUrl: The URL to your Unblu Server.
UnbluServerAdminBackend: The URL of the admin backend, typically set to the default rest/filterBackend.
UnbluSystemPathPrefix: Must match the setting of com.unblu.identifier.systemPathPrefix in the Unblu Server, preceded by a slash /.