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/amazon/2023/$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.

• The module version (distinct from the NGINX version) is available in the package metadata. For details on querying the module version, check out Determining the module version.

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. Identify the appropriate module for your NGINX version. Base your selection on whether you are using the stable, mainline, or distribution-provided release of NGINX:

   • nginx-module-fastly-nxs: use this package for stable (even-numbered) releases of NGINX provided by nginx.org.
   • nginx-module-fastly-nxm: use this package for mainline (odd-numbered) releases of NGINX provided by nginx.org.
   • nginx-module-fastly-nxd: use this package for releases of NGINX provided by your Linux distribution. If you have NGINX on your system but did not install it from nginx.org, you are using a distribution-provided release.
   • nginx-module-sigsci-nxo: use this package only if your existing NGINX installation already uses this package. New installations should use the most appropriate of the other three packages.

3. Use your distribution's package manager to install the NGINX dynamic module package for your specific NGINX Open Source release. The version you install must mirror the core version of your NGINX installation. Substitute <nginx-dynamic-module-variation> for the particular package type you are using.

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

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

   $ sudo apt-get install <nginx-dynamic-module-variation>

   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-dynamic-module-variation>=<nginx-core-version>\*

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

   $ sudo apt-get install nginx-module-fastly-nxs=1.26.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. To install this module:

1. Find your NGINX Plus version:

   nginx -v

   For example, in the response below, the NGINX Plus version is R30:

   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.

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

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

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

   $ sudo apt-get install nginx-module-fastly-nxp

   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-fastly-nxp=<nginx-plus-version>\*

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

   $ sudo apt-get install nginx-module-fastly-nxp=30\*

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_fastly_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. These examples assume you have installed the stable version of NGINX. Adjust them to suit your chosen version.

$ module_version=$(apt-cache madison nginx-module-fastly-nxs | 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-fastly-nxs=$module_version
$ unset module_version

Configuring the NGINX dynamic module

The NGINX dynamic module supports the following additional configuration settings.

Examples of configuration

Following is an example of setting SignalSciences module parameters in the http section:

1
2
3
4

# sigsci module settings
##
sigsci_debug         on;
sigsci_agent_timeout  200;

These examples show using location sections with the sigsci_enabled parameter:

1
2
3
4
5

# sigsci_enabled set to "on"
location /inspect/ {
   sigsci_enabled  on;
   proxy_pass      http://127.0.0.1:80/inspect/;
}

1
2
3
4
5

# sigsci_enabled set to "off"
location /noinspect/ {
   sigsci_enabled  off;
   proxy_pass      http://127.0.0.1:80/noinspect/;
}

Detailed example using server and location sections for the sigsci_websocket_enabled parameter:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

http {

    # must be turned on in global section
    sigsci_websocket_enabled on;

    server {
        ...
        # turned off for this server section
        sigsci_websocket_enabled off;

        # websocket turned on for this location
        location /websenabled {
            sigsci_websocket_enabled on;
            proxy_pass http://websocket;
            ...
        }

        # websocket off for this location since it is off in server
        location /websdisabled {
            proxy_pass http://websocket;
            ...
        }