Installing the Java Module as a Servlet Filter

Requirements

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

Supported Application Types

The Signal Sciences Java servlet filter module can be deployed to a variety of Servlet 3.0+ Java application servers (e.g., Apache Tomcat, Jetty, Glassfish, Resin).

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: 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 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"

Download

Download the Signal Sciences Java module manually or access it with Maven.

Access with Maven

For projects using Maven for build or deployment, the latest version of Signal Sciences Java modules can be installed by adding XML to the project pom.xml file. For example:

<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>LATEST_MODULE_VERSION</version>
</dependency>

Be sure to replace LATEST_MODULE_VERSION with the latest release of the Java module. You can find the latest version in our version file at https://dl.signalsciences.net/sigsci-module-java/VERSION.

Download manually

If you aren’t using Maven to build or deploy your Java projects, follow these steps to manually download the Signal Sciences Java module:

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

2. Extract sigsci-module-java_latest.tar.gz.

3. Deploy the jars using one of the following options:

   • 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.

   Note: If you want coverage across all web applications in your Application Server instance, the jar files must be placed in the server classpath. For example, in Tomcat that would be %CATALINA_HOME%/lib.

Installation

1. Update the web.xml file of your application with filter and filter-mapping entries.

   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>

   Add the following lines to your application’s deployment descriptor within the existing <web-app> </web-app> section.

   Note: If you want coverage across all web applications in your Application Server instance, the filter and filter-mapping entries must be applied to default deployment descriptor for the container. For example, in Tomcat that would be %CATALINA_HOME%/conf/web.xml.

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

2. Restart the Application Server.

Module Configuration

Sample module configuration:

Module configuration changes must be 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 -->