Module configuration

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.

NameDefault ValueDescription
SigSciAgentTimeout100Agent socket timeout in milliseconds.
SigSciAgentPostLen100000Maximum POST body size in bytes.
SigSciAgentInspectionOnEnable or disable the module.
SigSciAgentPortUnix: None, Windows: 9999The local port (when using TCP) that the agent listens on. If SigSciAgentPort is set, then SigSciAgentHost must be an IP or hostname.
SigSciAgentHostUnix: /var/run/sigsci.sock, Windows: 127.0.0.1Host or IP Address, otherwise use SigSciAgentHost to specify the domain socket file (e.g., /foo/bar.sock).
SigSciEnableFixupsOffToggles Signal Sciences fixups priority over post-read request handling to allow the request to be seen before it’s modified.
SigSciRunBeforeModulesListNoneNext-Gen WAF module runs before the list of specified modules (e.g., mod_example.c mod_something.c).
SigSciRunAfterModulesListNoneNext-Gen WAF module runs after the list of specified modules (e.g., mod_example.c mod_something.c).
SigSciExpectedContentTypesNoneA space-delimited list of custom content-types to support.
SigSciExtendContentTypesfalseEnables 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.

NameDescription
AgentTimeoutAgent socket timeout (in milliseconds), default: 100.
AgentPostLenMaximum POST body size in bytes, default: 100000
AgentInspectionEnable or disable the module, default: On
AgentPortThe 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.
AgentHostHost or IP Address, otherwise use AgentHost to specify the domain socket file. /foo/bar.sock

The following directives are deprecated and will be ignored.

NameDescription
SigSciAltResponseCodesSpecifying 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.

NameDescriptionValuesDefault ValueSection
sigsci_enabledEnable or disable the moduleon, offonhttp, server or per location
sigsci_debugEnable sigsci_debug only, doesn't affect other moduleson, offoffhttp
sigsci_handler_phasePhase in which the module processes requestpreaccess, access, precontent, rewriterewritehttp
sigsci_agent_max_post_lenMaximum POST body size in bytes to be sent to agent0 => don't send post body; else number bytes > 0100000http
sigsci_agent_timeoutAgent communication socket timeout in millisecondsMilliseconds > 0100http
sigsci_anomaly_resp_sizeMaximum response size in bytes. Larger than this is considered anomalous.Bytes > 0524288http
sigsci_anomaly_resp_timeMaximum response time in milliseconds. Larger than this is considered anomalous.Milliseconds > 01000http
sigsci_agent_hostThe IP address or a path to Unix domain socket the SignalSciences Agent listens onExample: tcp:localhostunix:/var/run/sigsci.sock:http
sigsci_agent_portThe TCP port that the agent listens on. Note: use only when sigsci_agent_host set to be an IP or hostname.valid TCP port numbernonehttp
sigsci_websocket_enabledEnable or disable WebSocket inspectionon, offoffhttp, 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 settings
2##
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 section
4 sigsci_websocket_enabled on;
5
6 server {
7 ...
8 # turned off for this server section
9 sigsci_websocket_enabled off;
10
11 # websocket turned on for this location
12 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 server
19 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.

NameDescription
agenthostThe IP address or path to Unix domain socket the SignalSciences Agent is listening on, default: unix:/var/run/sigsci.sock.
agentportThe local port (when using TCP) that the agent listens on, default: 12345
timeoutAgent socket timeout (in milliseconds), default: 100.
maxpostMaximum POST body size in bytes, default: 100000

Example configuration

1sigsci.agenthost = "unix:/var/run/sigsci.sock"
2sigsci.agentport = 12345
3sigsci.timeout = 100
4sigsci.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

1global
2 ...
3 lua-load /path/to/override.lua
4 ...

Over-ride Directives

These directives may be used in your over-ride config file.

NameDescription
sigsci.agenthostThe IP address or path to unix domain socket the SignalSciences Agent is listening on, default: /var/run/sigsci.sock (unix domain socket).
sigsci.agentportThe local port (when using TCP) that the agent listens on, default: nil
sigsci.log_debugEnable verbose logging, default: false
sigsci.log_network_errorsEnable logging of socket connection errors, default: false
sigsci.timeoutAgent socket timeout (in seconds), default: 1 (0 means off).
sigsci.maxpostMaximum POST body size in bytes, default: 100000
sigsci.extra_blocking_resp_hdrUser may supply a response header to be added upon 406 responses, default: ""
sigsci.expected_content_typesA list of custom content-types to support
sigsci.extend_content_typesEnables extended content inspection. Default value is false.

Example of over-ride configuration

1sigsci.agenthost = "192.0.2.243"
2sigsci.agentport = 9090
3sigsci.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.

NameDefault ValueDescription
agentHost127.0.0.1
agentPort737
DebugFalseEnable Module debugging; sends to event-viewer.
ReuseConnectionsFalseUse a socket pool with the maximum number of sockets based on hardware concurrency.
MaxPostSize100000
AnomalySize524288
AnomalyDurationMillis1000
TimeoutMillis200Agent socket timeout in milliseconds.
ExpectedContentTypesA space delimited list of custom content-types to support.
ExtendContentTypesfalseThis can be set to true to enable extended content inspection.

Language Modules

See language specific module pages for configuration details.

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.