search close

Installing the Java Module as a Servlet Filter

access_time Updated Jun 20, 2021

Requirements

  • A Servlet 3.x compliant Java servlet container (e.g. Tomcat 7.0.x.+, Jetty 9+, GlassFish 3.0+, JBoss 6+, etc)

Supported Application Types

The Signal Sciences servlet filter module can be easily deployed to a variety of Servlet 3.0+ Java application servers (i.e. Apache Tomcat, Jetty, JBoss, Glassfish, Resin, etc). The module is compatible with application servers deployed on both Linux and Windows servers running the Signal Sciences agent.

Agent Configuration

Like other Signal Sciences modules, the servlet filter supports both unix domain sockets and TCP sockets for communication with the Signal Sciences Agent. By default, the agent uses Unix Domain Sockets with the address set to unix:/var/run/sigsci.sock. It is possible to override this or specify a TCP socket instead by configuring the rpc-address parameter in the Agent.

Additionally, ensure the agent is configured to use the default rpc-Version (which is rpc-version=0). This can be done by verifying the parameter rpc-version is not specified in the agent configuration or if it is specified, ensure that is is specified with a value of 0. Below is an example Agent configuration that overrides the default unix domain socket value:

````
accesskeyid = “<YOUR AGENT ACCESSKEYID>“
secretaccesskey = “<YOUR AGENT SECRETACCESSKEY>“
rpc-address = "127.0.0.1:9999"
````

Installation

  1. Download or access the Java module:

    1. Download the Java module at https://dl.signalsciences.net/sigsci-module-java/sigsci-module-java_latest.tar.gz

    2. Copy jar file to the application classpath. For example in Tomcat this would be %CATALINA_HOME%\webbapps\<APP_FOLDER>\WEB-INF\lib.

    3. Extract sigsci-module-java_latest.tar.gz. There are two options for deploying the jars:

      • Copy sigsci-module-java-{version}-shaded.jar (an uber jar with all the dependencies bundled) to your application’s classpath (e.g. %CATALINA_HOME%\webbapps\<APP_FOLDER>\WEB-INF\lib).

      • Copy sigsci-module-java-{version}.jar and its dependencies in the lib folder to your application’s classpath (e.g. %CATALINA_HOME%\webbapps\<APP_FOLDER>\WEB-INF\lib). If you already have any of the dependency jar files in your application classpath folder (i.e. for Tomcat in the WEB-INF\lib) then it is not necessary to copy them, even if the version numbers are different. The logging jars are optional based on how slf4j is configured.

    For Java projects using Maven for build or deployment, the Signal Sciences Java modules can be installed by adding the following to the project pom.xml:

    <repositories>
        <repository>
            <id>sigsci-stable</id>
            <url>https://packages.signalsciences.net/release/maven2</url>
        </repository>
    </repositories>
    
    <dependency>
      <groupId>com.signalsciences</groupId>
      <artifactId>sigsci-module-java</artifactId>
      <version>1.1.3</version>
    </dependency>
    

  2. Update your application’s web.xml with filter and filter-mapping entry.

    Add the following stanza to your application’s deployment descriptor within the existing <web-app> </web-app> section. Note that the filter supports the use of either unix domain sockets or tcp sockets for the rpcServerURI parameter. Ensure that the value specified here matches the address specified in your Agent configuration. Specify the value using the following formats based on socket type:

    • TCP Sockets: tcp://<host>:<port>
    • Unix Domain Sockets: unix:/<file path>
    <web-app>
        <filter>
            <filter-name>SigSciFilter</filter-name>
            <filter-class>com.signalsciences.servlet.filter.SigSciFilter</filter-class>
            <async-supported>true</async-supported>
            <init-param>
                <param-name>rpcServerURI</param-name>
                <param-value>unix:/var/run/sigsci/sigsci.sock</param-value>
            </init-param>
            <init-param>
                <param-name>expectedContentTypes</param-name>
                <param-value>application/x-java-serialized-object</param-value>
            </init-param>
            <init-param>
            <param-name>excludeIpRange</param-name>
                <param-value>192.168.0.1-192.168.0.5,192.169.0.10-192.169.0.12,193.168.0.1,192.168.10.1-192.168.10.5,192.168.10.7</param-value>
            </init-param>
            <init-param>
                <param-name>excludeCidrBlock</param-name>
                <param-value>192.168.14.0/24,193.165.0.0/28,192.168.11.0/24</param-value>
            </init-param>
            <init-param>
                <param-name>excludePath</param-name>
                <param-value>/test/exit,/hello,/bonus</param-value>
            </init-param>
            <init-param>
                <param-name>excludeHost</param-name>
                <param-value>localhost,127.0.0.2</param-value>
            </init-param>
        </filter>
        <filter-mapping>
            <filter-name>SigSciFilter</filter-name>
            <url-pattern>/*</url-pattern>
        </filter-mapping>
    </web-app>
    
  3. Restart the Application Server.

Note: If you want coverage across all web applications in your Application Server instance, the jar files in step one should be placed in the server classpath (in Tomcat that would be %CATALINA_HOME%/lib). The filter and filter-mapping entries detailed in step 2 should be applied to default deployment descriptor for the container (in Tomcat that would be %CATALINA_HOME%/conf/web.xml). Additional Agent configuration options are detailed on the agent configuration page.

Module Configuration

Option Default Description
rpcServerURI required, tcp://127.0.0.1:9999 The unix domain socket or tcp connection to communicate with the agent.
rpcTimeout required, 300ms The timeout in milliseconds that the RPC client waits for a response back from the agent.
maxResponseTime optional, no default The maximum time in seconds that the server response time will be evaluated against (i.e. to see if it exceeds this value) to determine if the module should send a post request to the agent.
maxResponseSize optional, no default The maximum size in bytes that the server response size will be evaluated against (i.e. to see if it exceeds this value) to determine if the module should send a post request to the agent.
maxPost optional, no default The maximum POST body size in bytes that can be sent to the Signal Sciences agent. For any POST body size exceeding this limit, the module will not send the request to the agent for detection.
asyncStartFix optional, false This can be set to true to workaround missing request body when handling requests asynchronously in servlets.
altResponseCodes optional, no default Space separated alternative agent response codes used to block the request in addition to 406. For example “403 429 503”.
excludeCidrBlock optional, no default A comma-delimited list of CIDR blocks or specific IPs to be excluded from filter processing.
excludeIpRange optional, no default A comma-delimited list of IP ranges or specific IPs to be excluded from filter processing.
excludePath optional, no default A comma-delimited list of paths to be excluded from filter processing. If the URL starts with the specified value it will be excluded. Matching is case-insensitive.
excludeHost optional, no default A comma-delimited list of host names to be excluded from filter processing. Matching is case-insensitive.

Sample module configuration:

Module configuration changes are made in the <!-- Signal Sciences Filter --> section of your application’s web.xml file:

<!-- Signal Sciences Filter -->
<filter>
    <filter-name>sigSciFilter</filter-name>
    <filter-class>com.signalsciences.servlet.filter.SigSciFilter</filter-class>
     <async-supported>true</async-supported>  
<init-param>
   <param-name>rpcTimeout</param-name>
   <param-value>500</param-value>
</init-param>
  <init-param>
   <param-name>asyncStartFix</param-name>
   <param-value>true</param-value>
</init-param>  
</filter>
<filter-mapping>
    <filter-name>sigSciFilter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>
<!-- end Signal Sciences Filter -->