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

  1. Amazon Linux 2023 (AL2023)
  2. Amazon Linux 2 (AL2)
  3. Amazon Linux 2018.03
$ 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

  1. Bullseye (11) and above
  2. Buster (10) and lower
$ 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. RHEL 9
  2. RHEL 8
  3. RHEL 7
  4. RHEL 6
1$ sudo tee /etc/yum.repos.d/sigsci.repo <<-'EOF'
2[sigsci_release]
3name=sigsci_release
4baseurl=https://yum.signalsciences.net/release/el/9/$basearch
5repo_gpgcheck=1
6gpgcheck=1
7enabled=1
8gpgkey=https://yum.signalsciences.net/release/gpgkey https://dl.signalsciences.net/sigsci-agent/gpg.key
9sslverify=1
10sslcacert=/etc/pki/tls/certs/ca-bundle.crt
11EOF

Ubuntu

  1. Releases 22.04+
  2. Releases 20.04 and lower
$ 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.

  1. Debian / Ubuntu
  2. RHEL / CentOS / Amazon
  3. Alpine Linux
$ 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
Was this guide helpful?

Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.