Module configuration
Last updated 2024-09-09
IMPORTANT
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 provide the ability to configure the Next-Gen WAF module. The following attributes are set by default, but may need to be modified to provide support for different environments. In the majority of cases modifying module configuration is not necessary. Contact support if you need assistance or have questions regarding modifying module configuration.
Apache
To modify the Next-Gen WAF module configuration in Apache you will need to add directives to your Apache configuration file (e.g., for CentOS it is httpd.conf, for Debian or Ubuntu it is apache.conf or apache2.conf). Note, these directives must be set after the Next-Gen WAF module is loaded.
Starting with release 1.6.0, the following directives replace any earlier ones. These directives are a renaming of the earlier ones but with the addition of the prefix SigSci
.
Name | Default Value | Description |
---|---|---|
SigSciAgentTimeout | 100 | Agent socket timeout in milliseconds. |
SigSciAgentPostLen | 100000 | Maximum POST body size in bytes. |
SigSciAgentInspection | On | Enable or disable the module. |
SigSciAgentPort | Unix: None, Windows: 9999 | The local port (when using TCP) that the agent listens on. If SigSciAgentPort is set, then SigSciAgentHost must be an IP or hostname. |
SigSciAgentHost | Unix: /var/run/sigsci.sock , Windows: 127.0.0.1 | Host or IP Address, otherwise use SigSciAgentHost to specify the domain socket file (e.g., /foo/bar.sock ). |
SigSciEnableFixups | Off | Toggles Signal Sciences fixups priority over post-read request handling to allow the request to be seen before it’s modified. |
SigSciRunBeforeModulesList | None | Next-Gen WAF module runs before the list of specified modules (e.g., mod_example.c mod_something.c ). |
SigSciRunAfterModulesList | None | Next-Gen WAF module runs after the list of specified modules (e.g., mod_example.c mod_something.c ). |
SigSciExpectedContentTypes | None | A space-delimited list of custom content-types to support. |
SigSciExtendContentTypes | false | Enables extended content inspection. |
NOTE
SigSciEnableFixups
must be turned on for SigSciAgentInspection
to conditionally work within Location directives.
NOTE
The SigSciRunBeforeModulesList
and SigSciRunAfterModulesList
directives are currently not supported on ARM64-based Linux distributions.
The following directives will be deprecated in favor of the new ones above with the SigSci
prefix but are backwards compatible and will continue to work.
Name | Description |
---|---|
AgentTimeout | Agent socket timeout (in milliseconds), default: 100 . |
AgentPostLen | Maximum POST body size in bytes, default: 100000 |
AgentInspection | Enable or disable the module, default: On |
AgentPort | The local port (when using TCP) that the agent listens on, default: none. Note, if AgentPort is set then AgentHost must be a IP or hostname. |
AgentHost | Host or IP Address, otherwise use AgentHost to specify the domain socket file. /foo/bar.sock |
The following directives are deprecated and will be ignored.
Name | Description |
---|---|
SigSciAltResponseCodes | Specifying alternative codes on which to block is deprecated. Instead we now block on any response code within the range 300-599. |
NGINX C Binary Module
IMPORTANT
To use the NGINX C binary 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 modify the Next-Gen WAF NGINX module configuration, you will need to add directives to the NGINX configuration file, located by default at /etc/nginx/nginx.conf
.
In the global section, for example after the pid /run/nginx.pid;
line:
load_module /etc/nginx/modules/ngx_http_sigsci_module.so;
For the NGINX Open Source package (nxo
) only, add the following line:
load_module /etc/nginx/modules/ndk_http_module.so;
NOTE
For the NGINX Plus package, there is no load_module ndk_http_module.so
config required. The ndk
module should be installed by the package nginx-plus-module-ndk
.
Name | Description | Values | Default Value | Section |
---|---|---|---|---|
sigsci_enabled | Enable or disable the module | on , off | on | http, server or per location |
sigsci_debug | Enable sigsci_debug only, doesn't affect other modules | on , off | off | http |
sigsci_handler_phase | Phase in which the module processes request | preaccess , access , precontent , rewrite | rewrite | 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 | 100000 | http |
sigsci_agent_timeout | Agent communication socket timeout in milliseconds | Milliseconds > 0 | 100 | http |
sigsci_anomaly_resp_size | Maximum response size in bytes. Larger than this is considered anomalous. | Bytes > 0 | 524288 | http |
sigsci_anomaly_resp_time | Maximum response time in milliseconds. Larger than this is considered anomalous. | Milliseconds > 0 | 1000 | http |
sigsci_agent_host | The IP address or a path to Unix domain socket the SignalSciences Agent listens on | Example: tcp:localhost | 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 | none | http |
sigsci_websocket_enabled | Enable or disable WebSocket inspection | on , off | off | 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:
1# sigsci module settings2##3sigsci_debug on;4sigsci_agent_timeout 200;
These examples show using location
sections with the sigsci_enabled
parameter:
1# sigsci_enabled set to "on"2location /inspect/ {3 sigsci_enabled on;4 proxy_pass http://127.0.0.1:80/inspect/;5}
1# sigsci_enabled set to "off"2location /noinspect/ {3 sigsci_enabled off;4 proxy_pass http://127.0.0.1:80/noinspect/;5}
Detailed example using server
and location
sections for the sigsci_websocket_enabled
parameter:
1http {2
3 # must be turned on in global section4 sigsci_websocket_enabled on;5
6 server {7 ...8 # turned off for this server section9 sigsci_websocket_enabled off;10
11 # websocket turned on for this location12 location /websenabled {13 sigsci_websocket_enabled on;14 proxy_pass http://websocket;15 ...16 }17
18 # websocket off for this location since it is off in server19 location /websdisabled {20 proxy_pass http://websocket;21 ...22 }
NGINX Lua Module
IMPORTANT
We strongly recommend that you use the more performant NGINX C binary module if possible. The NGINX Lua module takes advantage of OpenResty and has more installation dependencies as a result.
To modify the Next-Gen WAF Lua module for NGINX, changes can be made in the Next-Gen WAF Lua script, which by default is at /opt/sigsci/nginx/sigsci.conf
.
Name | Description |
---|---|
agenthost | The IP address or path to Unix domain socket the SignalSciences Agent is listening on, default: unix:/var/run/sigsci.sock . |
agentport | The local port (when using TCP) that the agent listens on, default: 12345 |
timeout | Agent socket timeout (in milliseconds), default: 100 . |
maxpost | Maximum POST body size in bytes, default: 100000 |
Example configuration
1sigsci.agenthost = "unix:/var/run/sigsci.sock"2sigsci.agentport = 123453sigsci.timeout = 1004sigsci.maxpost = 1000000
HAProxy
Configuration changes are typically not required for the HAProxy module to work. However, it is possible to override the default settings if needed. To do so, you must create an override.lua
file in which to add these configuration directives. Then, update the global
section of your HAProxy config file (/usr/local/etc/haproxy/haproxy.cfg
) to load this over-ride config file.
Example of configuration
1global2 ...3 lua-load /path/to/override.lua4 ...
Over-ride Directives
These directives may be used in your over-ride config file.
Name | Description |
---|---|
sigsci.agenthost | The IP address or path to unix domain socket the SignalSciences Agent is listening on, default: /var/run/sigsci.sock (unix domain socket). |
sigsci.agentport | The local port (when using TCP) that the agent listens on, default: nil |
sigsci.log_debug | Enable verbose logging, default: false |
sigsci.log_network_errors | Enable logging of socket connection errors, default: false |
sigsci.timeout | Agent socket timeout (in seconds), default: 1 (0 means off). |
sigsci.maxpost | Maximum POST body size in bytes, default: 100000 |
sigsci.extra_blocking_resp_hdr | User may supply a response header to be added upon 406 responses, default: "" |
sigsci.expected_content_types | A list of custom content-types to support |
sigsci.extend_content_types | Enables extended content inspection. Default value is false . |
Example of over-ride configuration
1sigsci.agenthost = "192.0.2.243"2sigsci.agentport = 90903sigsci.extra_blocking_resp_hdr = "Access-Control-Allow-Origin: https://example.com"
IIS
You can set the configuration for the IIS module using the MSI installer, the SigsciCtl.exe
utility in v2.0.0+, IIS Manager UI, PowerShell, or the appcmd.exe
utility. See Configuration Usage for more information on configuring the IIS module.
Name | Default Value | Description |
---|---|---|
agentHost | 127.0.0.1 | |
agentPort | 737 | |
Debug | False | Enable Module debugging; sends to event-viewer. |
ReuseConnections | False | Use a socket pool with the maximum number of sockets based on hardware concurrency. |
MaxPostSize | 100000 | |
AnomalySize | 524288 | |
AnomalyDurationMillis | 1000 | |
TimeoutMillis | 200 | Agent socket timeout in milliseconds. |
ExpectedContentTypes | A space delimited list of custom content-types to support. | |
ExtendContentTypes | false | This can be set to true to enable extended content inspection. |
Language Modules
See language specific module pages for configuration details.
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.