Build a custom agent

If your Linux distribution or preferred NGINX version is not in the supported matrix, or if you require additional custom flags in your NGINX build that break compatibility with the tCell module, we recommend that you compile your own module.

To build your own version of the tCell module:

  1. Ensure your build environment is up-to-date.
  2. Download the NGINX source code.
  3. Download the module source.
  4. Install the required packages to build your version of NGINX.
  5. Build and install NGINX.
  6. Update your NGINX configuration and provide the agent configuration.
  7. Start the NGINX service.

Ensure your build environment is up-to-date

The module contains static libraries which are linked depending on the distribution's version of libc. If your version of libc or binutils is out-of-date, the module will fail to compile.

If building with Glibc, use the following versions:

PackageMinimum Version
GLibc2.15
binutils2.20

If building with musl libc, use the following versions:

PackageMinimum Version
Musl Libc1.1.20
binutils2.20

Tip: Use ldd -v to check the libc version.

Tip: Use ld -v to check the binutils version.

Download the NGINX source code

You can find any version of the NGINX source code on github or through the official NGINX site. Download your preferred version of the source code.

Support: We support custom module compilation only for versions of NGINX after 1.10.3.

Download the module source

The most recent source code for the tCell NGINX module is available for installation on the tCell dashboard, under the Download Agent tab in the Admin menu. Move the decompressed source into your NGINX source directory.

Support: We provide the module source only for versions of the agent after 3.2.2.

Install the required packages to build your version of NGINX

The tCell NGINX module requires the libuuid development library to be built. By default, NGINX requires the libssl, libpcre3, and libzip development libraries to be built as well. Use the appropriate package manager to install these packages:

(Ubuntu)

1
sudo apt update && sudo apt install uuid-dev libssl-dev libpcre3-dev libzip-dev

(Alpine)

1
sudo apk update && sudo apk add libuuid libssl-devel libpcre3-devel libzip-devel

Build and install NGINX

Run the configure script in the NGINX source directory with your desired flags, adding one of these lines to the end of every configuration argument:

1
--add-dynamic-module=./nginx_tcell_module_source

or

1
--add-module=./nginx_tcell_module_source

A more in-depth guide to the NGINX build process and flags can be found on the official NGINX site.

Note: Report any issues with configuration or building to tCell Support.

Update your NGINX configuration and provide the agent configuration

During the configuration step, the --prefix parameter specifies the path to the NGINX configuration directory; the default is /usr/local/nginx/conf. The --conf-path parameter specifies the name of the NGINX configuration directory; the default is conf. The NGINX configuration file is named nginx.conf.

  1. Add the following line to nginx.conf:
1
load_module modules/ngx_http_tcell_agent_module so;
  1. Ensure that the tcell_app_id is set inside the http block.
  2. Copy the tcell_agent.conf file from the dashboard into the conf directory.

Start the NGINX service

Run:

1
sudo nginx -s quit
2
sudo nginx

You should now be running an NGINX service protected by tCell. Check your tCell log directory to make sure everything started correctly.