Installing the NGINX dynamic module

The NGINX dynamic module is compiled and then dynamically loaded into NGINX at runtime without recompiling the entire NGINX binary. This module is written in C and can be integrated with NGINX Open Source and NGINX Plus.

To install the module, complete the following steps:

1. Add the package repositories.
2. Install the module.
3. Load the module.

Adding our package repositories

Before installing the NGINX dynamic module, you must configure your package management system to pull from our repositories.

Alpine Linux 3.11+

$ apk update && apk add wget
$ wget -q https://apk.signalsciences.net/sigsci_apk.pub ; mv sigsci_apk.pub /etc/apk/keys
$ echo https://apk.signalsciences.net/$(grep -oE '[0-9]+\.[0-9]{2}' /etc/alpine-release)/main | tee -a /etc/apk/repositories && apk update

Amazon Linux

$ echo '[sigsci_release]
name=sigsci_release
baseurl=https://yum.signalsciences.net/release/el/$releasever/$basearch
gpgcheck=1
repo_gpgcheck=1
enabled=1
gpgkey=https://yum.signalsciences.net/release/gpgkey https://dl.signalsciences.net/sigsci-agent/gpg.key
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt' | sudo tee /etc/yum.repos.d/sigsci.repo

Debian

$ sudo apt-get update
$ sudo apt-get install -y apt-transport-https wget gnupg lsb-release
$ sudo wget -qO - https://apt.signalsciences.net/release/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/sigsci.gpg
$ sudo echo "deb [signed-by=/usr/share/keyrings/sigsci.gpg] https://apt.signalsciences.net/release/debian/ `lsb_release -cs` main" | sudo tee /etc/apt/sources.list.d/sigsci-release.list
$ sudo apt-get update

RHEL and derivatives

The following commands apply to Red Hat Enterprise Linux (RHEL) and its derivatives (e.g., CentOS). Tab names refer to the base RHEL source version.

1
2
3
4
5
6
7
8
9
10
11

$ sudo tee /etc/yum.repos.d/sigsci.repo <<-'EOF'
[sigsci_release]
name=sigsci_release
baseurl=https://yum.signalsciences.net/release/el/9/$basearch
repo_gpgcheck=1
gpgcheck=1
enabled=1
gpgkey=https://yum.signalsciences.net/release/gpgkey https://dl.signalsciences.net/sigsci-agent/gpg.key
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
EOF

Ubuntu

$ sudo apt-get update
$ sudo apt-get install -y apt-transport-https wget gnupg lsb-release
$ sudo wget -qO - https://apt.signalsciences.net/release/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/sigsci.gpg
$ sudo echo "deb [signed-by=/usr/share/keyrings/sigsci.gpg] https://apt.signalsciences.net/release/ubuntu/ `lsb_release -cs` main" | sudo tee /etc/apt/sources.list.d/sigsci-release.list
$ sudo apt-get update

Installing the NGINX dynamic module

After adding our package repositories, you can install the NGINX dynamic module for NGINX Open Source or NGINX Plus.

Limitations and considerations

Keep the following things in mind when installing the NGINX dynamic module:

• Before installing the NGINX dynamic module, you must add our package repositories for your distribution and update repository metadata.

• The NGINX dynamic module version that you install must mirror the core version of your NGINX installation. For instance, if you have NGINX 1.18.0 installed, you must install version 1.18.0 of the module.

• File names of our NGINX module package versions include the NGINX version that they're compiled against, and in some cases, a build prefix and distribution release (e.g., 1.25.3-715~jammy). When build numbers exist for the same NGINX version, we recommend installing the package with the highest build number.

  Appending a wildcard (*) to the installation command ensures you install the latest version available for the specified NGINX version. You may need to update your repository metadata (e.g., apt update) for newer versions.

Installing the NGINX dynamic module for NGINX Open Source

Our NGINX dynamic module for NGINX Open Source is compiled for NGINX Open Source. To install this module:

1. Find your NGINX binary version:

   $ nginx -v

   NOTE

   If nothing is returned or you get a nginx: not found error, make sure NGINX is correctly installed and available on the applicable shell path. If NGINX has not been installed as a package (e.g., extracted from a tarball), subsequent commands to install packages may fail due to NGINX package dependencies not being met.

2. Use your distributions package manager to install the NGINX dynamic module (nginx-module-sigsci-nxo) package for your specific NGINX Open Source release. The version you install must mirror the core version of your NGINX installation.

   1. Debian / Ubuntu
   2. RHEL / CentOS
   3. Alpine Linux
   4. Amazon Linux 2 / 2018.3

   To install the lastest version of our module, run the following command:

   $ sudo apt-get install nginx-module-sigsci-nxo

   To install a specific version of our module, run the following command, being sure to replace <nginx-core-version> with the NGINX core version you have installed:

   $ sudo apt-get install nginx-module-sigsci-nxo=<nginx-core-version>\*

   For example, if your installed NGINX core version is 1.18.0, the command would be the following:

   $ sudo apt-get install nginx-module-sigsci-nxo=1.18.0\*

Installing the NGINX dynamic module for NGINX Plus

Our NGINX dynamic module for NGINX Plus is compiled for the NGINX Plus web server maintained by F5. The version of the module you install is based on the core NGINX that NGINX Plus is based on. To install this module:

1. Find your NGINX core version:

   nginx -v

   For example, in the response below, NGINX Plus version R30 correlates to NGINX core version 1.25.1:

   nginx version: nginx/1.25.1 (nginx-plus-r30-p1)

   NOTE

   If nothing is returned or you get a nginx: not found error, make sure NGINX is correctly installed and available on the applicable shell path. If NGINX has not been installed as a package (e.g., extracted from a tarball), subsequent commands to install packages may fail due to NGINX package dependencies not being met.

   Alternatively, if you know your NGINX Plus version, you can source the correlative NGINX core version it is based on from the NGINX Plus release notes.

2. Use your distributions package manager to install the NGINX dynamic module (nginx-module-sigsci-nxp) package for your specific NGINX Plus release. The version you install must mirror the core version of your NGINX installation.

   1. Ubuntu / Debian
   2. RHEL / CentOS
   3. Alpine Linux
   4. Amazon Linux 2 / AL2 / 2018.3

   To install the lastest version of our module that is compatible with your NGINX core version, run the following command:

   $ sudo apt-get install nginx-module-sigsci-nxp=$(nginx -v 2>&1 | grep -oP 'nginx/\K[0-9.]+')\*

   To install a specific version of our module, run the following command, being sure to replace <nginx-core-version> with the NGINX core version you have installed:

   $ sudo apt-get install nginx-module-sigsci-nxp=<nginx-core-version>\*

   For example, if your installed NGINX Plus version is R30, the command would be the following:

   $ sudo apt-get install nginx-module-sigsci-nxp=1.25.1\*

Loading the NGINX dynamic module

After installing the NGINX dynamic module, you need to declare the NGINX dynamic module in your NGINX configuration so that the module loads into NGINX at runtime:

1. In your NGINX configuration file (often located by default at /etc/nginx/nginx.conf), use the NGINX load_module directive to load the NGINX dynamic module into NGINX's main context (for instance, under the pid directive).

   load_module /etc/nginx/modules/ngx_http_sigsci_module.so;

2. Run the following command to make sure your changes are valid:

   $ nginx -t

   The output will look something like this:

   nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
   nginx: configuration file /etc/nginx/nginx.conf test is successful

3. Restart NGINX:

   $ service nginx restart

   For servers that are not running an init system (e.g., an Alpine container), the following command will reload the configuration:

   $ nginx -s reload

4. (Optional) Verify the module was successfully loaded:

   $ cat /var/log/nginx/error.log | grep 'sigsci:'

   The error.log will look something like this when the module is loaded:

   1970/01/01 00:00:00 [notice] 4242#4242: sigsci_init_main_conf: Using default UDS socket: /var/run/sigsci.sock
   1970/01/01 00:00:00 [notice] 4242#4242: sigsci:init: setting phase REWRITE: ngx-phase=3
   1970/01/01 00:00:00 [notice] 4242#4242: sigsci:sigsci_create_random: initialized random checking
   1970/01/01 00:00:00 [notice] 4242#4242: signal process started

Scripting the installation

You can also use a sequence of shell commands to install the NGINX dynamic module. Each command in the sequence sources the output from the previous command as a variable. This can be useful within scripted installations, such as a Dockerfile RUN directive.

$ module_version=$(apt-cache madison nginx-module-sigsci-nxo | grep $(nginx -v 2>&1 | grep -oP 'nginx/\K[0-9.]+') | awk -F'|' '{print $2}' | head -n 1 | xargs)
$ apt-get install -y nginx-module-sigsci-nxo=$module_version
$ unset module_version