---
title: Installing the Java Module as a Servlet Filter
summary: null
url: >-
  https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/module-agent-deployment/java-module/java-module-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 Next-Gen WAF 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 Next-Gen WAF agent.

## Agent Configuration

Like other Next-Gen WAF modules, the servlet filter supports both Unix domain sockets and TCP sockets for communication with the Next-Gen WAF 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:

```text
accesskeyid = "YOUR AGENT ACCESSKEYID"
secretaccesskey = "YOUR AGENT SECRETACCESSKEY"
rpc-address = "127.0.0.1:9999"
```

## Download

Download the Next-Gen WAF Java module manually or access it with Maven.

### Access with Maven

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

```xml
<repositories>
   <repository>
      <id>sigsci-stable</id>
      <url>https://mvn.security.fastly.com/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.security.fastly.com/sigsci-module-java/VERSION> or <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 Next-Gen WAF Java module:

1. Click one of the following links to download the latest version of our Java module:

   - [https://dl.security.fastly.com](https://dl.security.fastly.com/sigsci-module-java/sigsci-module-java_latest.tar.gz)
   - [https://dl.signalsciences.net](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\\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\\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.

   > **HINT:** 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. Determine the appropriate `filter-class` for your installation:

   - For systems using Jakarta EE (Servlet API 5+):

     ```xml
      <filter-class>com.signalsciences.jakartafilter.SigSciFilter</filter-class>
     ```

   - For Java EE:

     ```xml
     <filter-class>com.signalsciences.servlet.filter.SigSciFilter</filter-class>
     ```

   > **NOTE:** Failure to specify the appropriate servlet API may result in errors such as `package javax.servlet.x does not exist`.

   Example minimal configuration using the Java EE servlet filter class:

   ```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>extendContentTypes</param-name>
            <param-value>true</param-value>
         </init-param>
      </filter>
      <filter-mapping>
         <filter-name>SigSciFilter</filter-name>
         <url-pattern>/*</url-pattern>
      </filter-mapping>
   </web-app>
   ```

   > **NOTE:** 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 to avoid communication failures. The module configuration below provides more details.

2. Restart the Application Server.

## 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. Use the appropriate prefix to specify either Unix Domain Sockets or a TCP connection: `unix:/<file path>` or `tcp://<host>:<port>`                                                           |
| `rpcTimeout`                 | Required, 300ms                  | The timeout in milliseconds that the RPC client waits for a response back from the agent.                                                                                                                                                                            |
| `rpcThreadCount`             | Optional, Integer                | The number of threads used for RPC communication between the module and the agent. This value is used only when an explicit count is provided; otherwise, a default is calculated based on CPU count and pool status.                                                |
| `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 Next-Gen WAF 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 IP addresses to be excluded from filter processing.                                                                                                                                                                |
| `excludeIpRange`             | Optional, no default             | A comma-delimited list of IP ranges or specific IP addresses 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.                                                                                                                                                            |
| `multipartParsingEnabled`    | Optional, false                  | A boolean option that should be set to true if the servlet is annotated with [MultipartConfig](https://tomcat.apache.org/tomcat-7.0-doc/servletapi/javax/servlet/annotation/MultipartConfig.html) or if the configuration in web.xml contains &lt;multipart-config>. |
| `multipartFileSizeThreshold` | Optional, no default             | The maximum number of bytes that can be uploaded and stored on disk. This option must be used in conjunction with the `multipartParsingEnabled` option.                                                                                                              |
| `extendContentTypes`         | Optional, false                  | This can be set to true to enable extended content inspection.                                                                                                                                                                                                       |

## Example configuration

The configuration shown here provides an example using all the parameters noted earlier in this guide:

```xml
   {/* Signal Sciences Filter */}
   <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>
         <init-param>
            <param-name>extendContentTypes</param-name>
            <param-value>true</param-value>
         </init-param>
      </filter>
      <filter-mapping>
         <filter-name>SigSciFilter</filter-name>
         <url-pattern>/*</url-pattern>
         </filter-mapping>
   </web-app>
   {/* end Signal Sciences Filter */}
```

## Related content

- [About module-agent deployment](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/module-agent-deployment/about-module-agent-deployment)
- [Using an API with the Next-Gen WAF](https://www.fastly.com/documentation/guides/next-gen-waf/developer/using-an-api-with-the-next-gen-waf)