Upgrading the NGINX module

This guide only applies to Next-Gen WAF customers with access to the Next-Gen WAF control panel. If you have access to the Next-Gen WAF product in the Fastly control panel, you can only deploy the Next-Gen WAF with the Edge WAF deployment method.

We update our NGINX dynamic module within three weeks of a stable or mainline NGINX release or a NGINX Plus release occurs. We will expedite a release when there are exceptions (e.g., critical vulnerability). Our Compatibility and requirements guide lists the distributions our NGINX module has packages available for.

Check the NGINX Lua module release notes or NGINX Native module release notes for a list of what's new in the NGINX module.

Upgrading the module on Alpine Linux systems

To upgrade the Next-Gen WAF NGINX module on Alpine Linux systems, follow these steps for the appropriate package:

  1. Stable
  2. Mainline
  3. Distribution-provided
  4. NGINX Plus
  1. Upgrade the NGINX Alpine Linux module package.

    $ apk update
    $ apk add nginx-module-fastly-nxs
  2. Restart your NGINX service.

Upgrading the module on RHEL, CentOS, Amazon Linux and other RHEL-derived distributions

Amazon Linux 2 customers should ensure that the baseurl in sigsci.repo is set to https://yum.signalsciences.net/release/amazon/2/$basearch:

[sigsci_release]
name=sigsci_release
baseurl=https://yum.signalsciences.net/release/amazon/2/$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

To upgrade the Next-Gen WAF NGINX module for the NGINX on Red Hat Enterprise Linux (RHEL) and its derivative (e.g., CentOS) systems for a version of NGINX, follow the steps for the appropriate package:

  1. Stable
  2. Mainline
  3. Distribution-provided
  4. NGINX Plus
  1. Upgrade the NGINX module package.

    $ sudo yum update
    $ sudo yum install nginx-module-fastly-nxs
  2. Restart your NGINX service.

Upgrading the module on Ubuntu and Debian systems

To upgrade the Next-Gen WAF NGINX module for the NGINX version on Ubuntu and Debian systems, follow the steps for the appropriate package:

  1. Stable
  2. Mainline
  3. Distribution-provided
  4. NGINX Plus
  1. Upgrade the NGINX module package.

    $ sudo apt-get update
    $ sudo apt-get install nginx-module-fastly-nxs
  2. Restart your NGINX service.

Switching to a nginx-module-fastly package

If your existing installation uses one of the nginx-module-sigsci packages, you can switch to one of our nginx-module-fastly packages by completing the following steps:

Prerequisites

Before switching to an nginx-module-fastly package, ensure the following steps have been completed.

  1. Debian / Ubuntu
  2. RHEL / CentOS / Amazon
  3. Alpine Linux
  1. Run the following command to ensure you have access to the latest packages. You will be prompted to provide your root password.

    $ sudo apt-get update
  2. Determine the NGINX version and package source. Refer to our section on determining the NGINX version.

  3. Check the Next-Gen WAF module you are using by running the following command. Be sure to record the version and whether it is a -nxo or -nxp module. You'll need this information in a future step.

    $ apt list --installed | grep module-sigsci

Replacing the package

  1. Run the following command according to your distribution of Linux. Substitute <sigsci-module> for either nginx-module-sigsci-nxo or nginx-module-sigsci-nxp as you determined in the previous step.

    1. Debian / Ubuntu
    2. RHEL / CentOS / Amazon
    3. Alpine Linux
    $ sudo apt-get remove <sigsci-module>
  2. Remove the load_module command for the old sigsci_module.so in /etc/nginx/nginx.conf. Look for the following line and remove it. The Fastly packages have renamed the shared object to ngx_http_fastly_module.so.

    load_module /etc/nginx/modules/ngx_http_sigsci_module.so;
  3. Install the variation of the NGINX dynamic module that is appropriate for your version of NGINX using the version of NGINX and the Fastly module that you noted in previous steps. For information about our module variations, check out Choosing an NGINX module variation.

  4. Load the NGINX dynamic module.

  5. If you are using SELinux, update your SELinux policy.

Determining the NGINX version

Determining the NGINX version as well as the source of NGINX is necessary to ensure that you install the correct version of the NGINX native module. Follow these steps to determine the NGINX version.

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

Run the following command to determine which version you have installed.

$ apt list --installed | grep nginx

On Debian and Ubuntu, the package name nginx will be followed by a / character and then the name of the repository it comes from. If it says nginx/nginx it means you are using a version of NGINX provided by Nginx.org. If it says nginx/stable or nginx/noble-updates or something else, then you are using a distribution-provided version of NGINX. Following the package and repository information, you will see the version of NGINX, for example 1.24.0. For example, the following shows NGINX version 1.24.0 installed from an Ubuntu repository.

$ apt list --installed | grep nginx
nginx/noble-updates,noble-security,now 1.24.0-2ubuntu7.3 arm64 [installed]

Determining the module version

The version in the package file name is the version of NGINX that the module package is built to work with. To determine the module version, you must query the package using the package tools appropriate to your distribution. The module version will be listed in the Description: field.

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

To query the description for an installed package on Alpine Linux systems, use apk info -d <package name>. For example:

$ apk info -d nginx-module-fastly-nxs

The output will look something like this:

nginx-module-fastly-nxs-1.24.0-r1201 description:
Fastly module v1.2.0 for Nginx 1.24.0

Alpine Linux does not support querying the metadata for packages that have been downloaded but not installed.