The HTTP Connector

Introduction

The HTTP Connector element represents a Connector component that supports the HTTP/1.1 protocol. It enables Catalina to function as a stand-alone web server, in addition to its ability to execute servlets and JSP pages. A particular instance of this component listens for connections on a specific TCP port number on the server. One or more such Connectors can be configured as part of the Web subSystem to perform request processing and create the response.

If you wish to configure the Connector that is used for connections to web servers using the AJP protocol (such as the mod_jk 1.2.x connector for Apache 1.3), see here instead.

Each incoming request requires a thread for the duration of that request. If more simultaneous requests are received than can be handled by the currently available request processing threads, additional threads will be created up to the configured maximum (the value of the max-connections attribute). Additional connections will be rejected.

Attributes

Common Attributes

All implementations of Connector support the following attributes:

Attribute Description
name
Name of the connector

enable-lookups
Set to true if you want calls to request.getRemoteHost() to perform DNS lookups in order to return the actual host name of the remote client. Set to false to skip the DNS lookup and return the IP address in String form instead (thereby improving performance). By default, DNS lookups are enabled.

max-post-size
The maximum size in bytes of the POST which will be handled by the container FORM URL parameter parsing. The limit can be disabled by setting this attribute to a value less than or equal to 0. If not specified, this attribute is set to 2097152 (2 megabytes).

max-save-post-size
The maximum size in bytes of the POST which will be saved/buffered by the container during FORM or CLIENT-CERT authentication. For both types of authentication, the POST will be saved/buffered before the user is authenticated. For CLIENT-CERT authentication, the POST is buffered for the duration of the SSL handshake and the buffer emptied when the request is processed. For FORM authentication the POST is saved whilst the user is re-directed to the login form and is retained until the user successfully authenticates or the session associated with the authentication request expires. The limit can be disabled by setting this attribute to -1. Setting the attribute to zero will disable the saving of POST data during authentication and the buffering during SSL handshake. If not specified, this attribute is set to 4096 (4 kilobytes).

max-connections
Max of connections supported by the connector. That is the max number of threads when using the JIO connector and the end point poller size for all connectors. for the native connector the max number of threads is calculated (32 times the number of processors available to the Java virtual machine.).

protocol
Sets the protocol to handle incoming traffic. The default value is HTTP/1.1 and configures the org.apache.coyote.http11.Http11Protocol. This is the blocking Java connector.
If the PATH(Windows) or LD_LIBRARY_PATH(on most unix system) environment variables contain the Tomcat native library, the APR connector will automatically be configured. Please be advised that the APR connector has different settings for HTTPS than the default Java connector.
Other values for this attribute are, but not limited to:
org.apache.coyote.http11.Http11Protocol - same as HTTP/1.1
org.apache.coyote.http11.Http11NioProtocol - non blocking Java connector, note that it require java7 and that is not based on the NIO1 connector of the ASF Tomcat but uses NIO2
org.apache.coyote.http11.Http11AprProtocol - the APR connector.
The configuration for both Java connectors are identical, both for http and https.
For more information on the APR connector and APR specific SSL settings please visit the APR documentation

proxy-name
If this Connector is being used in a proxy configuration, configure this attribute to specify the server name to be returned for calls to request.getServerName().

proxy-port
If this Connector is being used in a proxy configuration, configure this attribute to specify the server port to be returned for calls to request.getServerPort().

redirect-port
If this Connector is supporting non-SSL requests, and a request is received for which a matching <security-constraint> requires SSL transport, Catalina will automatically redirect the request to the port number specified here.

ssl
Use this element to enable SSL traffic on a connector. To turn on SSL handshake/encryption/decryption on a connector. When present you will want to set the scheme and the secure attributes as well to pass the correct request.getScheme() and request.isSecure() values to the servlets See SSL Support for more information.

scheme
Set this attribute to the name of the protocol you wish to have returned by calls to request.getScheme(). For example, you would set this attribute to "https" for an SSL Connector. The default value is "http".

secure
Set this attribute to true if you wish to have calls to request.isSecure() to return true for requests received by this Connector. You would want this on an SSL Connector or a non SSL connector that is receiving data from a SSL accelerator, like a crypto card, a SSL appliance or even a webserver. The default value is false.

enabled
Set this attribute to false if you don't wan the Connector to be used. The default value is true.

executor
A reference to the name in an Executor element. If this attribute is enabled, and the named executor exists, the connector will use the executor, and all the other thread attributes will be ignored.

Standard Implementation

HTTP doesn't support more attributes that the ones listed above.

Nested Components

ssl: SSL configuration See HTTPS

Special Features

HTTP/1.1 and HTTP/1.0 Support

This Connector supports all of the required features of the HTTP/1.1 protocol, as described in RFC 2616, including persistent connections, pipelining, expectations and chunked encoding. If the client (typically a browser) supports only HTTP/1.0, the Connector will gracefully fall back to supporting this protocol as well. No special configuration is required to enable this support. The Connector also supports HTTP/1.0 keep-alive.

RFC 2616 requires that HTTP servers always begin their responses with the highest HTTP version that they claim to support. Therefore, this Connector will always return HTTP/1.1 at the beginning of its responses.

Proxy Support

The proxy-name and proxy-port attributes can be used when JBoss Web is run behind a proxy server. These attributes modify the values returned to web applications that call the request.getServerName() and request.getServerPort() methods, which are often used to construct absolute URLs for redirects. Without configuring these attributes, the values returned would reflect the server name and port on which the connection from the proxy server was received, rather than the server name and port to whom the client directed the original request.

For more information, see the Proxy Support HOW-TO.

SSL Support

See HTTPS connector.

For more information, see the SSL Configuration HOW-TO.

Attribute	Description
`name`	Name of the connector
`enable-lookups`	Set to `true` if you want calls to `request.getRemoteHost()` to perform DNS lookups in order to return the actual host name of the remote client. Set to `false` to skip the DNS lookup and return the IP address in String form instead (thereby improving performance). By default, DNS lookups are enabled.
`max-post-size`	The maximum size in bytes of the POST which will be handled by the container FORM URL parameter parsing. The limit can be disabled by setting this attribute to a value less than or equal to 0. If not specified, this attribute is set to 2097152 (2 megabytes).
`max-save-post-size`	The maximum size in bytes of the POST which will be saved/buffered by the container during FORM or CLIENT-CERT authentication. For both types of authentication, the POST will be saved/buffered before the user is authenticated. For CLIENT-CERT authentication, the POST is buffered for the duration of the SSL handshake and the buffer emptied when the request is processed. For FORM authentication the POST is saved whilst the user is re-directed to the login form and is retained until the user successfully authenticates or the session associated with the authentication request expires. The limit can be disabled by setting this attribute to -1. Setting the attribute to zero will disable the saving of POST data during authentication and the buffering during SSL handshake. If not specified, this attribute is set to 4096 (4 kilobytes).
`max-connections`	Max of connections supported by the connector. That is the max number of threads when using the JIO connector and the end point poller size for all connectors. for the native connector the max number of threads is calculated (32 times the number of processors available to the Java virtual machine.).
`protocol`	Sets the protocol to handle incoming traffic. The default value is `HTTP/1.1` and configures the `org.apache.coyote.http11.Http11Protocol`. This is the blocking Java connector. If the `PATH(Windows)` or `LD_LIBRARY_PATH(on most unix system)` environment variables contain the Tomcat native library, the APR connector will automatically be configured. Please be advised that the APR connector has different settings for HTTPS than the default Java connector. Other values for this attribute are, but not limited to: `org.apache.coyote.http11.Http11Protocol` - same as HTTP/1.1 `org.apache.coyote.http11.Http11NioProtocol` - non blocking Java connector, note that it require java7 and that is not based on the NIO1 connector of the ASF Tomcat but uses NIO2 `org.apache.coyote.http11.Http11AprProtocol` - the APR connector. The configuration for both Java connectors are identical, both for http and https. For more information on the APR connector and APR specific SSL settings please visit the APR documentation
`proxy-name`	If this Connector is being used in a proxy configuration, configure this attribute to specify the server name to be returned for calls to `request.getServerName()`.
`proxy-port`	If this Connector is being used in a proxy configuration, configure this attribute to specify the server port to be returned for calls to `request.getServerPort()`.
`redirect-port`	If this Connector is supporting non-SSL requests, and a request is received for which a matching `<security-constraint>` requires SSL transport, Catalina will automatically redirect the request to the port number specified here.
`ssl`	Use this element to enable SSL traffic on a connector. To turn on SSL handshake/encryption/decryption on a connector. When present you will want to set the `scheme` and the `secure` attributes as well to pass the correct `request.getScheme()` and `request.isSecure()` values to the servlets See SSL Support for more information.
`scheme`	Set this attribute to the name of the protocol you wish to have returned by calls to `request.getScheme()`. For example, you would set this attribute to "`https`" for an SSL Connector. The default value is "`http`".
`secure`	Set this attribute to `true` if you wish to have calls to `request.isSecure()` to return `true` for requests received by this Connector. You would want this on an SSL Connector or a non SSL connector that is receiving data from a SSL accelerator, like a crypto card, a SSL appliance or even a webserver. The default value is `false`.
`enabled`	Set this attribute to `false` if you don't wan the Connector to be used. The default value is `true`.
`executor`	A reference to the name in an Executor element. If this attribute is enabled, and the named executor exists, the connector will use the executor, and all the other thread attributes will be ignored.