search close

Module Configuration

access_time Updated Sep 21, 2021

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.

Name Description
SigSciAgentTimeout Agent socket timeout (in milliseconds), default: 100.
SigSciAgentPostLen Maximum POST body site in bytes, default: 100000
SigSciAgentInspection Enable or disable the module, default: On
SigSciAgentPort 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.
SigSciAgentHost Host or IP Address, otherwise use AgentHost to specify the domain socket file. “/foo/bar.sock”
SigSciEnableFixups Fixups 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”
SigSciRunBeforeModulesList Signal Sciences module runs before the list of specified modules, ex: mod_example.c mod_something.c
SigSciRunAfterModulesList Signal Sciences module runs after the list of specified modules, ex: mod_example.c mod_something.c

The following directives will be Deprecated in favor of the new ones above with the SigSci prefix but are backwards compatible - thus will continue to work.

Name Description
AgentTimeout Agent socket timeout (in milliseconds), default: 100.
AgentPostLen Maximum POST body site 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

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 Nginx.org package (nxo) only, add the following line:

load_module /etc/nginx/modules/ndk_http_module.so;

Note: For NGINX Plus 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 ex: 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:

        # sigsci module settings
        ##
        sigsci_debug         on;
        sigsci_agent_timeout  200;

These examples show using location sections with the sigsci_enabled parameter:

        # sigsci_enabled set to "on"
        location /inspect/ {
            sigsci_enabled  on;
            proxy_pass      http://127.0.0.1:80/inspect/;
        }
        # 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:

  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;
            ...
        }

Nginx Lua Module

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.

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 site in bytes, default: 100000

Example of configuration

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

global
   ...
   lua-load /path/to/override.lua
   ...

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.timeout Agent socket timeout (in seconds), default: 1 (0 means off).
sigsci.maxpost Maximum POST body site in bytes, default: 100000
sigsci.extra_blocking_resp_hdr User may supply a response header to be added upon 406 responses, default: ""

Example of over-ride configuration

sigsci.agenthost = "192.0.2.243"
sigsci.agentport = 9090
sigsci.extra_blocking_resp_hdr = "Access-Control-Allow-Origin: https://example.com"

IIS

Typically, configuration changes are not necessary. By default the module will use port 737 to communicate with the agent (or, in v2.0.0+, if the agent was configured to use an alternate port, it will use that port). The configuration can be set via the MSI installer, the new SigsciCtl.exe utility in v2.0.0+, IIS Manager UI, via PowerShell, or using the appcmd.exe utility. Configuring via MSI or SigsciCtl.exe utility is recommended.

To set a configuration option when installing the MSI, just specify the option on the commandline in option=value format.via as follows:

msiexec /qn /i sigsci-module-iis_latest.msi agentHost=203.0.113.182 agentPort=737

To set a configuration option via SigsciCtl.exe utility after install, use the Configure-Module command such as follows:

"%PROGRAMFILES%\Signal Sciences\IIS Module\SigsciCtl.exe" Configure-Module agentHost=203.0.113.182 agentPort=737

To view the active configuration via the SigsciCtl.exe utility the Get-Configs command such as follows:

"%PROGRAMFILES%\Signal Sciences\IIS Module\SigsciCtl.exe" Get-Configs

This should output something similar to the following:

C:\WINDOWS\system32\inetsrv\config\schema:

Date                         Size Name
-------------------- ------------ --------------------------------
2020-02-13 03:12:56Z          677 SignalSciences_schema.xml

"SignalSciences" Configuration Section (Global):

                       Attribute Value
-------------------------------- ----------------------------------------------------------------
                       agentHost
                       agentPort 737
                  statusPagePath
                           Debug False
                ReuseConnections False
                     MaxPostSize 100000
                     AnomalySize 524288
           AnomalyDurationMillis 1000
                   TimeoutMillis 200

To set a configuration option via PowerShell (modern Windows only) use the -SectionPath "SignalSciences" option such as follows:

Set-IISConfigAttributeValue -ConfigElement (Get-IISConfigSection -SectionPath "SignalSciences") -AttributeName "agentPort" -AttributeValue 737

To list the configuration using PowerShell, run:

(Get-IISConfigSection -SectionPath "SignalSciences").RawAttributes

To reset the configuration to defaults using PowerShell, run:

Clear-WebConfiguration -Filter SignalSciences -PSPath 'IIS:\'

To set a configuration option via the appcmd.exe command line tool use the -section:SignalSciences option such as follows:

"%SYSTEMROOT%\system32\inetsrv\appcmd.exe" set config -section:SignalSciences -agentPort:737

To list the configuration using appcmd.exe, run (default values will not be shown):

"%SYSTEMROOT%\system32\inetsrv\appcmd.exe" list config -section:SignalSciences

To reset the configuration to defaults using appcmd.exe, run:

"%SYSTEMROOT%\system32\inetsrv\appcmd.exe" clear config -section:SignalSciences

Note: Ensure that the same port number is used by the both the module and the agent configurations.

Language Modules

See language specific module pages for configuration details.