# The Valve Component

[Introduction] [Common Attributes] [Standard Implementation Attributes]

## Introduction

A Valve component represents an instance of a specified Java class that will be involved in the processing of each request and response handled by the Container within which it is nested, as follows:

- A Valve nested inside an Engine will process all requests received by any Connector associated with the Service in which this Engine is nested.
- A Valve nested inside a Host will process all requests received by the associated Engine and directed to the specified virtual host, but not requests directed to any other virtual host associated with that Engine.
- A Valve nested inside a Context will process all requests received by the associated Host, and mapped to the specified web application, but not requests mapped to any other web application associated with that Host.

Valves are typically used to implement optional features for the associated Container. See the "Special Features" section of the documentation on Engine, host, and Context Containers for more information about the Valves designed to be associated with each Container type. This page summarizes the configuration information for all standard Valve implementations that are provided with Catalina.

## Common Attributes

All implementations of the Valve component support the following attributes:

Attribute | Description
--- | ---
`className` | Java class name of the implementation to use. This class must implement the `org.apache.catalina.Valve` interface. Because there is no single standard implementation, this attribute is required. See Standard Implementation Attributes for the names of the supported classes.

## Standard Implementation Attributes

Unlike most other Catalina components, there is not a single standard implementation of the Valve component available. Instead, a variety of standard implementations, with different functional purposes, are available for your use. To select one, use the specified value for the `className` attribute, and configure the remaining attributes as described below.

### Access Log Valve (`org.apache.catalina.valve.AccessLogValve`)

The Access Log Valve creates log files in the same format as those created by standard web servers. These logs can later be analyzed by standard log analysis tools to track page hit counts, user session activity, and so on. The access log Valve shares many configuration characteristics with the File Logger components used to record internal event, exception, and debugging output from Catalina components, including the automatic rollover of log files at midnight each night. An Access Log Valve can be associated with an Engine, Host, or Context Container, and will log requests processed by the associated Container and any nested Containers.

The Access Log Valve supports the following additional attributes:

Attribute | Description
--- | ---
`directory` | Relative or absolute pathname of the directory into which log files will be created. If a relative path is specified, it is interpreted as relative to $CATALINA_HOME. If no directory is specified, the default value is "logs" (relative to the Catalina home directory).
`pattern` | A formatting layout identifying the various information fields from the request and response to be logged, or the word `common` to select the standard Common Log Format. See below for more information on pattern variables. If no value is specified, the `common` format is utilized.
`prefix` | The prefix added to the front of each log file name. If not specified, the default value is "access_log.". To specify no prefix, use a zero-length string.
`resolveHosts` | Should the IP address of the remote client for each request be resolved to the corresponding host name (via a DNS lookup)? You might wish to turn off host resolution to improve performance in high activity web applications. If not specified, the default value is `false`, indicating that remote host resolution will not take place.
`suffix` | The suffix added to the end of each log file name. If not specified, the default value is "". To specify no suffix, use a zero-length string.
`timestamp` | Should log messages be date/time stamped? Set this value to `true` or `false`. If not specified, log messages will not be date/time stamped.

Values for the `pattern` attribute are made up of literal text strings, and pattern identifiers prefixed by the % character, which cause replacement by the corresponding variable value from the current request and response. The following pattern codes are supported:

- %a - Remote IP address
- %A - Local IP address
- %b - Bytes sent, excluding HTTP headers, or '-' if zero
- %B - Bytes sent, excluding HTTP headers
- %h - Remote host name (or IP address if resolveHosts is false)
- %H - Request protocol
- %l - Remote logical username from identd (always returns '-')
- %m - Request method (GET, POST, etc.)
- %p - Local port on which this request was received
- %q - Query string (prepended with a '?' if it exists)
- %r - First line of the request (method and request URI)
- %s - HTTP status code of the response
- %t - Date and time, in Common Log Format
- %u - Remote user that was authenticated (if any), else '-'
- %U - Requested URL path
- &v - Local server name

If you specify a pattern of `common`, or do not specify a pattern at all, the common pattern `%h %l %u %t "%r" %s %b` is used, which corresponds to the default logging format for many web servers.

### Remote Address Filter (`org.apache.catalina.valve.RemoteAddrValve`)

The Remote Address Filter allows you to compare the IP address of the client that submitted this request against one or more regular expressions, and either allow the request to continue or refuse to process a request from this client based on the outcome of the comparison. A Remote Address Filter can be associated with an Engine, Host, or Context Container, and will filter requests processed by the associated Container and any nested Containers.

The Remote Address Filter supports the following additional attributes:

Attribute | Description
--- | ---
allow | A comma-separated list of regular expression patterns that the remote client's IP address is compared to. If this attribute is specified, the remote address must match at least one of the patterns to be allowed. If this attribute is not specified, all requests are allowed unless the remote address matches a `deny` pattern.
deny | A comma-separated list of regular expression patterns that the remote client's IP address is compared to. If this attribute is specified, the remote address must not match any of the specified patterns to be allowed. If this attribute is not specified, any request where the remote address matches one of the `accept` patterns is allowed.

### Remote Host Filter (`org.apache.catalina.valve.RemoteHostValve`)

The Remote Host Filter allows you to compare the remote host address of the client that submitted this request against one or more regular expressions, and either allow the request to continue or refuse to process a request from this client based on the outcome of the comparison. A Remote Host Filter can be associated with an Engine, Host, or Context Container, and will filter requests processed by the associated Container and any nested Containers.

The Remote Address Host supports the following additional attributes:

Attribute | Description
--- | ---
allow | A comma-separated list of regular expression patterns that the remote client's host address is compared to. If this attribute is specified, the remote address must match at least one of the patterns to be allowed. If this attribute is not specified, all requests are allowed unless the remote address matches a `deny` pattern.
deny | A comma-separated list of regular expression patterns that the remote client's host address is compared to. If this attribute is specified, the remote address must not match any of the specified patterns to be allowed. If this attribute is not specified, any request where the remote address matches one of the `accept` patterns is allowed.

### Request Dumper Valve (`org.apache.catalina.valve.RequestDumperValve`)

The Request Dumper Valve is a debugging tool that lets you insert a component that dumps the HTTP headers associated with the specified request (before processing) and response (after processing) to the Logger that is associated with our corresponding Container. It is especially useful when trying to debug problems related to headers or cookies sent by an HTTP client. A Request Dumper Filter can be associated with an Engine, Host, or Context Container, and will log requests processed by the associated Container and any nested Containers.

The Request Dumper Filter supports no additional attributes.