--- title: Installing the NGINX dynamic module summary: null url: >- https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/module-agent-deployment/nginx-module/installing-the-nginx-dynamic-module --- The NGINX dynamic module is compiled and then [dynamically loaded](https://docs.nginx.com/nginx/admin-guide/dynamic-modules/dynamic-modules/) 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. > **IMPORTANT:** To use the NGINX dynamic module, your NGINX must have been compiled with the `--with-compat` flag. If your NGINX was not compiled with that flag, you must use the NGINX Lua module. To install the module, complete the following steps: 1. [Add the package repositories.](#adding-our-package-repositories) 1. [Install the module.](#installing-the-nginx-dynamic-module) 1. [Load the module.](#loading-the-nginx-dynamic-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 Add the version of the Alpine Linux package repository that you want to use. > **NOTE:** ```term copy nolinenums $ apk update && apk add wget $ wget -q https://apk.security.fastly.com/sigsci_apk.pub ; mv sigsci_apk.pub /etc/apk/keys $ echo https://apk.security.fastly.com/$(grep -oE '[0-9]+\.[0-9]{2}' /etc/alpine-release)/main | tee -a /etc/apk/repositories && apk update ``` ### Amazon Linux Add the version of the Amazon Linux package repository that you want to use. > **NOTE:** ### Debian Add the version of the Debian package repository that you want to use. > **NOTE:** ### 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. > **NOTE:** ### Ubuntu Add the version of the Ubuntu package repository that you want to use. > **NOTE:** ## Installing the NGINX dynamic module After [adding our package repositories](#adding-our-package-repositories), you can install the NGINX dynamic module for [NGINX Open Source](#installing-the-nginx-dynamic-module-for-nginx-open-source) or [NGINX Plus](#installing-the-nginx-dynamic-module-for-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](#adding-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](/guides/next-gen-waf/setup-and-configuration/package-downloads#nginx) 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](/guides/next-gen-waf/setup-and-configuration/module-agent-deployment/nginx-module/upgrading-nginx#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: ```term copy nolinenums $ nginx -v ``` > **NOTE:** 1. 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`](https://nginx.org/en/download.html). * `nginx-module-fastly-nxm`: use this package for *mainline* (odd-numbered) releases of NGINX provided by [`nginx.org`](https://nginx.org/en/download.html). * `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`](https://nginx.org/en/download.html), 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. 1. 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 `` for the particular [package type you are using](/guides/next-gen-waf/setup-and-configuration/module-agent-deployment/nginx-module/about-the-nginx-module#choosing-an-nginx-module-variation). ### 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: ```term copy nginx -v ``` For example, in the response below, the NGINX Plus version is `R30`: ```term nolinenums nginx version: nginx/1.25.1 (nginx-plus-r30-p1) ``` > **NOTE:** 1. 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. ## Loading the NGINX dynamic module After [installing the NGINX dynamic module](#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`](http://nginx.org/en/docs/ngx_core_module.html#load_module) directive to load the NGINX dynamic module into NGINX's [`main`](http://nginx.org/en/docs/ngx_core_module.html) context (for instance, under the `pid` directive). ```term copy load_module /etc/nginx/modules/ngx_http_fastly_module.so; ``` 1. Run the following command to make sure your changes are valid: ```term copy $ nginx -t ``` The output will look something like this: ```term copy nolinenums nginx: the configuration file /etc/nginx/nginx.conf syntax is ok nginx: configuration file /etc/nginx/nginx.conf test is successful ``` 1. Restart NGINX: ```term copy $ service nginx restart ``` For servers that are not running an init system (e.g., an Alpine container), the following command will reload the configuration: ```term copy $ nginx -s reload ``` 1. *(Optional)* Verify the module was successfully loaded: ```term copy nolinenums $ cat /var/log/nginx/error.log | grep 'sigsci:' ``` The `error.log` will look something like this when the module is loaded: ```term copy nolinenums 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](/guides/next-gen-waf/setup-and-configuration/module-agent-deployment/nginx-module/about-the-nginx-module#choosing-an-nginx-module-variation). ## Configuring the NGINX dynamic module The NGINX dynamic module supports the following additional configuration settings. | Name | Description | Values | Section | | ---- | ----------- | ------ | ------- | | `sigsci_enabled` | Enable or disable the module | `on` (default), `off` | http, server or per location | | `sigsci_debug` | Enable `sigsci_debug` only, doesn't affect other modules | `on`, `off` (default) | http | | `sigsci_handler_phase` | Phase in which the module processes request | `preaccess`, `access`, `precontent`, `rewrite` (default) | http | | `sigsci_agent_max_post_len` | Maximum POST body size in bytes to be sent to agent | 0 => don't send post body; else number bytes > 0 (defaults to `100000`) | http | | `sigsci_agent_timeout` | Agent communication socket timeout in milliseconds | Milliseconds > 0 (defaults to `100`) | http | | `sigsci_anomaly_resp_size` | Maximum response size in bytes. Larger than this is considered anomalous. | Bytes > 0 (defaults to `524288`) | http | | `sigsci_anomaly_resp_time` | Maximum response time in milliseconds. Larger than this is considered anomalous. | Milliseconds > 0 (defaults to `1000`) | http | | `sigsci_agent_host` | The IP address or a path to Unix domain socket the SignalSciences Agent listens on | Example: `tcp:localhost` (defaults to `unix:/var/run/sigsci.sock`) | http | | `sigsci_agent_port` | The TCP port that the agent listens on. Note: use only when `sigsci_agent_host` set to be an IP or hostname. | valid TCP port number | http | | `sigsci_websocket_enabled` | Enable or disable WebSocket inspection | `on`, `off` (default) | http, server or per location | > **NOTE:** `sigsci_websocket_enabled` is `off` by default. To enable it, it must be specified in the `http` section. Thereafter, it may be turned `off` and `on` in the `server` and `location` sections as needed. __Examples of configuration__ Following is an example of setting SignalSciences module parameters in the `http` section: ```text # sigsci module settings ## sigsci_debug on; sigsci_agent_timeout 200; ``` These examples show using `location` sections with the `sigsci_enabled` parameter: ```text # sigsci_enabled set to "on" location /inspect/ { sigsci_enabled on; proxy_pass http://127.0.0.1:80/inspect/; } ``` ```text # 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: ```text 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; ... } ``` ## Related content * [About module-agent deployment](/guides/next-gen-waf/setup-and-configuration/module-agent-deployment/about-module-agent-deployment) * [Using an API with the Next-Gen WAF](/guides/next-gen-waf/developer/using-an-api-with-the-next-gen-waf)