The HTTP/1.1 Connector Component

[Introduction] [Component Attributes] [Special Features]

Introduction

The HTTP/1.1 Connector component is a Connector implementation 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 serve JSP pages. A particular instance of this component listens for connections on a configured TCP/IP port number on the server. One or more such connectors can be configured, each forwarding requests to a particular Engine for processing.

This Connector is configured by including a <Connector> element in your conf/server.xml configuration file, nested inside a Service element. All connectors that you have configured are automatically attached to the Engine that is specified after the connector.

At server startup time, this Connector will create a number of processor threads (based on the value of the minProcessors property). Each incoming request requires a thread, and the associated processor, for the duration of that request. If more simultaneous requests are received than can be handled by the current set of available processors, additional threads (and associated processors) will be created up to the configured value of the maxProcessors property, which defines the maximum number of simultaneous requests this connector is allowed to process.

Component Attributes

The HTTP/1.1 Connector supports the following attributes:

Attribute	Description
`acceptCount`	The maximum queue length for incoming connection indications that will be allowed on our server socket. If a connection indication arrives when the queue is full, the connection is refused. If not specfied, a backlog of 10 will be allowed.
`address`	For servers with more than one IP address, this property specifies which address will be used for listening on the specified port. If not specified, this port number will be used on all IP addresses associated with this server.
`bufferSize`	The size (in bytes) of the buffer to be provided for input streams created by this connector. Increasing the buffer size can improve performance, at the expense of higher memory usage. If not specified, a buffer size of 2048 bytes will be provided.
`className`	Java class name of the implementation to use. Must be specified as `org.apache.tomcat.connector.http.HttpConnector` to use the standard implementation.
`debug`	The debugging detail level of log messages generated by this connector, where higher numbers create more detailed output. If not specified, the debugging detail level will be set to zero (0).
`enableLookups`	Set this attribute to `true` to enable DNS lookups of the remote host name when `request.getRemoteHost()` is called. If lookups are disabled, the remote IP address (as a String) is returned instead. By default, DNS lookups are enabled.
`maxProcessors`	The maximum number of processor threads that will ever be created by this Connector, which therefore determines the maximum number of simultaneous requests that can be handled. If not specified, the maximum will be set to 20.
`minProcessors`	The number of processor threads that will be initialized when this Connector is first started. If not specified, 5 processors will be initialized.
`port`	The TCP/IP port number on which this connector should listen for client connections. Your operating system will allow only one server application to listen to a particular port at a particular time. If not specified, port 8080 will be used.
`proxyName`	If specified, this value will be used as the value returned by `request.getServerName()`, instead of the value included on the `Host` header. This is useful when running Tomcat behind a proxy server (or a web server acting as a proxy server) on a different host. See Proxy Support, below, for more information on running behind a proxy server.
`proxyPort`	If specified, this value will be used as the value returned by `request.getServerPort()`, instead of the value specified by the `port` attribute. This is useful when running Tomcat behind a proxy server (or a web server acting as a proxy server). See Proxy Support, below, for more information about running behind a proxy server.

Special Features

HTTP/1.1 and HTTP/1.0 Protocol Support

This Connector supports all of the required features of the HTTP/1.1 protocol as described in RFC 2616, including persistent connections and chunked encoding. If the client (typically a browser) supports only HTTP/1.0, the Connector gracefully falls back to supporting this as well, so that interoperability is maximized. No special configuration is required to enable this support.

Logging Output

Any debugging or exception logging information generated by this Connector will be sent to the Logger associated with the Engine which is used to process requests for this Connector.

SSL Support

You can enable SSL support for an instance of this Connector by configuring an appropriate socket factory, as follows:

Attribute	Description
`algorithm`	The certificate encoding algorithm to be used. If not specified, the default value is `SunX509`.
`className`	The fully qualified Java class name of the SSL socket factory. With the standard HTTP 1.1 connectory, you must specify `org.apache.catalina.net.SSLServerSocketFactory` here.
`clientAuth`	Set to `true` if you want the SSL stack to require a valid certificate chain from the client before accepting a connection. A `false` value (which is the default) will not require such a certificate chain.
`keystoreFile`	The pathname of the keystore file from which the server certificate is loaded. By default, the pathname is the file ".keystore" in the home directory of the operating system username that is running Tomcat.
`keystorePass`	The password used to access the server certificate from the keystore file identified above. If not specified, the default value is "changeit".
`keystoreType`	The type of keystore file to be used for the server certificate. If not specified, the default value is "JKS".
`protocol`	The version of the SSL protocol to use. If not specified, the default value is "TLS".

Successful use of SSL support requires that you have installed the JAR files from the Java Secure Sockets Extension (JSSE) package into your conf/server directory.

Proxy Support

The proxyName and proxyPort attributes can be used when Tomcat is run behind a proxy server. These attributes modify the values returned to web applications by the request.getServerName() and request.getServerPort() methods, which are often used to construct absolute URLs for redirects. Using the modified values will cause redirected requests to be flowed through the proxy server as well, instead of directly to the port on which Tomcat is listening.

Proxy support can take many forms. The following outline assumes that you are running Tomcat behind an Apache web server (listening to port 80) on the same server that Tomcat is running on, and you wish to have all requests flow through Apache, but forward requests for a particular web application to Tomcat for processing.

Configure your copy of Apache so that it includes the mod_proxy module. If you are building from source, the easiest way to do this is to include the --enable-module=proxy directive on the ./configure command line.
Include two directives in your httpd.conf file for each web application that you wish to forward to Tomcat. For example:
```
        ProxyPass         /myapp  http://localhost:8081/myapp
        ProxyPassReverse  /myapp  http://localhost:8081/myapp
    
```
tells Apache to forward all requests sent to URLs like http://localhost/myapp/* to be forwarded the Tomcat connector listening on port 8081.
Configure your copy of Tomcat to have a special Connector listening on port 8081, with appropriate proxy settings as shown below:
```
        <Connector className="org.apache.catalina.connector.http.HttpConnector"
         port="8081" ... proxyPort="80" proxyName="www.mycompany.com"/>
    
```
which will cause servlets in this web app to think that the request was directed to www.mycompany.com on port 80.
It is legal to omit the proxyName attribute from the <Connector> element. If you do so, the value reported by the request.getServerName() method will be the hostname to which Apache forwards (in the configuration described above, it would be "localhost").
If you also have a Tomcat connector listening on port 8080 (within the same <Service>, the requests to either port will be processed by exactly the same set of web applications. You might want to use the IP filtering features of your operating system to restrict connections for port 8081 to come from only the local host (which is presumably the Apache web server).
Alternatively, you can set up a series of web applications that are only available via proxying as follows:
- Configure another <Service> that contains a <Connector> configured for proxying, as above.
- Configure appropriate <Engine>, <Host>, and <Context> entries for the web applications accessible via proxying.
- Optionally, protect port 8081 with IP filters as described earlier.
When requests are proxied from Apache, the web server will be recording these requests in its access log. Therefore, you will generally want to disable any access logging done by Tomcat (by removing or commenting out the <Valve> line).

NOTE - Unlike the usual situation when Tomcat is used behind a web connector, Tomcat will serve all requests (including static files) for the specified web application.