Module configuration

We provide the ability to configure the Signal Sciences 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 Signal Sciences 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 Signal Sciences 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.

NameDescription
SigSciAgentTimeoutAgent socket timeout (in milliseconds), default: 100.
SigSciAgentPostLenMaximum POST body size in bytes, default: 100000
SigSciAgentInspectionEnable or disable the module, default: On
SigSciAgentPortThe 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.
SigSciAgentHostHost or IP Address, otherwise use AgentHost to specify the domain socket file. /foo/bar.sock
SigSciEnableFixupsFixups is the phase in request processing after authorization but before the content handler. This setting toggles Signal Sciences fixups priority over post read request handling to allow the request to be seen before it's modified. (On or Off) - default is Off
SigSciRunBeforeModulesListSignal Sciences module runs before the list of specified modules. Example: mod_example.c mod_something.c
SigSciRunAfterModulesListSignal Sciences module runs after the list of specified modules. Example: mod_example.c mod_something.c
SigSciExpectedContentTypesA space-delimited list of custom content-types to support.
SigSciExtendContentTypesEnables extended content inspection. Default value is false.
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 Signal Sciences 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.org 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 and DescriptionValuesDefault ValueSection
sigsci_enabled: Enable or disable the moduleon, offonhttp, server or per location
sigsci_debug: Enable sigsci_debug only, doesn't affect other moduleson, offoffhttp
sigsci_handler_phase: Phase in which the module processes requestpreaccess, access, precontent, rewriterewritehttp
sigsci_agent_max_post_len: Maximum POST body size in bytes to be sent to agent0 => don't send post body; else number bytes > 0100000http
sigsci_agent_timeout: Agent communication socket timeout in millisecondsMilliseconds > 0100http
sigsci_anomaly_resp_size: Maximum response size in bytes. Larger than this is considered anomalous.Bytes > 0524288http
sigsci_anomaly_resp_time: Maximum response time in milliseconds. Larger than this is considered anomalous.Milliseconds > 01000http
sigsci_agent_host: The IP address or a path to Unix domain socket the SignalSciences Agent listens onExample: tcp:localhostunix:/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 numbernonehttp
sigsci_websocket_enabled: Enable 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 Signal Sciences Lua module for NGINX, changes can be made in the Signal Sciences 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.