| <?xml version="1.0"?> |
| <!DOCTYPE document [ |
| <!ENTITY project SYSTEM "project.xml"> |
| ]> |
| <document url="http.html"> |
| |
| &project; |
| |
| <properties> |
| <author email="craigmcc@apache.org">Craig R. McClanahan</author> |
| <author email="yoavs@apache.org">Yoav Shapira</author> |
| <title>The HTTP Connector</title> |
| </properties> |
| |
| <body> |
| |
| |
| <section name="Introduction"> |
| |
| <p>The <strong>HTTP Connector</strong> element represents a |
| <strong>Connector</strong> 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 <strong>Connectors</strong> can be |
| configured as part of a single <a href="service.html">Service</a>, each |
| forwarding to the associated <a href="engine.html">Engine</a> to perform |
| request processing and create the response.</p> |
| |
| <p>If you wish to configure the <strong>Connector</strong> that is used |
| for connections to web servers using the AJP protocol (such as the |
| <code>mod_jk</code> connector for Apache 1.3), see |
| <a href="ajp.html">here</a> instead.</p> |
| |
| <p>At server startup time, this <strong>Connector</strong> will create a |
| number of request processing threads (based on the value configured for |
| the <code>minSpareThreads</code> attribute). 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 <code>maxThreads</code> attribute). |
| If still more simultaneous requests are received, they are stacked up |
| inside the server socket created by the <strong>Connector</strong>, up to |
| the configured maximum (the value of the <code>acceptCount</code> |
| attribute. Any further simultaneous requests will receive "connection |
| refused" errors, until resources are available to process them.</p> |
| |
| </section> |
| |
| |
| <section name="Attributes"> |
| |
| <subsection name="Common Attributes"> |
| |
| <p>All implementations of <strong>Connector</strong> |
| support the following attributes:</p> |
| |
| <attributes> |
| |
| <attribute name="address" required="false"> |
| <p>For servers with more than one IP address, this attribute |
| specifies which address will be used for listening on the specified |
| port. By default, this port will be used on all IP addresses |
| associated with the server.</p> |
| </attribute> |
| |
| <attribute name="allowTrace" required="false"> |
| <p>A boolean value which can be used to enable or disable the TRACE |
| HTTP method. If not specified, this attribute is set to false.</p> |
| </attribute> |
| |
| <attribute name="enableLookups" required="false"> |
| <p>Set to <code>true</code> if you want calls to |
| <code>request.getRemoteHost()</code> to perform DNS lookups in |
| order to return the actual host name of the remote client. Set |
| to <code>false</code> to skip the DNS lookup and return the IP |
| address in String form instead (thereby improving performance). |
| By default, DNS lookups are enabled.</p> |
| </attribute> |
| |
| <attribute name="maxPostSize" required="false"> |
| <p>The maximum size in bytes of the POST which will be handled by |
| the container FORM URL parameter parsing. The feature can be disbled by |
| setting this attribute to a value inferior or equal to 0. |
| If not specified, this attribute is set to 2097152 (2 megabytes).</p> |
| </attribute> |
| |
| <attribute name="redirectPort" required="false"> |
| <p>If this <strong>Connector</strong> is supporting non-SSL |
| requests, and a request is received for which a matching |
| <code><security-constraint></code> requires SSL transport, |
| Catalina will automatically redirect the request to the port |
| number specified here.</p> |
| </attribute> |
| |
| <attribute name="scheme" required="false"> |
| <p>Set this attribute to the name of the protocol you wish to have |
| returned by calls to <code>request.getScheme()</code>. For |
| example, you would set this attribute to "<code>https</code>" |
| for an SSL Connector. The default value is "<code>http</code>". |
| See <a href="#SSL Support">SSL Support</a> for more information.</p> |
| </attribute> |
| |
| <attribute name="secure" required="false"> |
| <p>Set this attribute to <code>true</code> if you wish to have |
| calls to <code>request.isSecure()</code> to return <code>true</code> |
| for requests received by this Connector (you would want this on an |
| SSL Connector). The default value is <code>false</code>.</p> |
| </attribute> |
| |
| <attribute name="URIEncoding" required="false"> |
| <p>This specifies the character encoding used to decode the URI bytes, |
| after %xx decoding the URL. If not specified, ISO-8859-1 will be used. |
| </p> |
| </attribute> |
| |
| <attribute name="useBodyEncodingForURI" required="false"> |
| <p>This specifies if the encoding specified in contentType should be used |
| for URI query parameters, instead of using the URIEncoding. This |
| setting is present for compatibility with Tomcat 4.1.x, where the |
| encoding specified in the contentType, or explicitely set using |
| Request.setCharacterEncoding method was also used for the parameters from |
| the URL. The default value is <code>false</code>. |
| </p> |
| </attribute> |
| |
| </attributes> |
| |
| </subsection> |
| |
| <subsection name="Standard Implementation"> |
| |
| <p>The standard implementation of the <strong>HTTP |
| Connector</strong> is |
| <strong>org.apache.coyote.tomcat5.CoyoteConnector</strong>. |
| It supports the following additional attributes (in addition to the |
| common attributes listed above):</p> |
| |
| <attributes> |
| |
| <attribute name="acceptCount" required="false"> |
| <p>The maximum queue length for incoming connection requests when |
| all possible request processing threads are in use. Any requests |
| received when the queue is full will be refused. The default |
| value is 10.</p> |
| </attribute> |
| |
| <attribute name="bufferSize" required="false"> |
| <p>The size (in bytes) of the buffer to be provided for input |
| streams created by this connector. By default, buffers of |
| 2048 bytes will be provided.</p> |
| </attribute> |
| |
| <attribute name="compressableMimeTypes" required="false"> |
| <p>The value is a comma separated list of MIME types for which HTTP |
| compression may be used. |
| The default value is <code>text/html,text/xml,text/plain</code>.</p> |
| </attribute> |
| |
| <attribute name="compression" required="false"> |
| <p>The <strong>Connector</strong> may use HTTP/1.1 GZIP compression in |
| an attempt to save server bandwidth. The acceptable values for the |
| parameter is "off" (disable compression), "on" (allow compression, which |
| causes text data to be compressed), "force" (forces compression in all |
| cases), or a numerical integer value (which is equivalent to "on", but |
| specifies the minimum amount of data before the output is compressed). If |
| the content-length is not known and compression is set to "on" or more |
| aggressive, the output will also be compressed. If not specified, this |
| attribute is set to "off".</p> |
| </attribute> |
| |
| <attribute name="connectionLinger" required="false"> |
| <p>The number of milliseconds during which the sockets used by this |
| <strong>Connector</strong> will linger when they are closed. |
| The default value is -1 (socket linger is disabled).</p> |
| </attribute> |
| |
| <attribute name="connectionTimeout" required="false"> |
| <p>The number of milliseconds this <strong>Connector</strong> will wait, |
| after accepting a connection, for the request URI line to be |
| presented. The default value is 60000 (i.e. 60 seconds).</p> |
| </attribute> |
| |
| <attribute name="debug" required="false"> |
| <p>The debugging detail level of log messages generated by this |
| component, with higher numbers creating more detailed output. |
| If not specified, this attribute is set to zero (0).</p> |
| </attribute> |
| |
| <attribute name="disableUploadTimeout" required="false"> |
| <p>This flag allows the servlet container to use a different, longer |
| connection timeout while a servlet is being executed, which in the end |
| allows either the servlet a longer amount of time to complete its |
| execution, or a longer timeout during data upload. If not specified, |
| this attribute is set to "false".</p> |
| </attribute> |
| |
| <attribute name="maxHttpHeaderSize" required="false"> |
| <p>The maximum size of the request and response HTTP header, specified |
| in bytes. |
| If not specified, this attribute is set to 4096 (4 KB).</p> |
| </attribute> |
| |
| <attribute name="maxKeepAliveRequests" required="false"> |
| <p>The maximum number of HTTP requests which can be pipelined until |
| the connection is closed by the server. Setting this attribute to 1 will |
| disable HTTP/1.0 keep-alive, as well as HTTP/1.1 keep-alive and |
| pipelining. Setting this to -1 will allow an unlimited amount of |
| pipelined or keep-alive HTTP requests. |
| If not specified, this attribute is set to 100.</p> |
| </attribute> |
| |
| <attribute name="maxSpareThreads" required="false"> |
| <p>The maximum number of unused request processing threads that |
| will be allowed to exist until the thread pool starts stopping the |
| unnecessary threads. The default value is 50.</p> |
| </attribute> |
| |
| <attribute name="maxThreads" required="false"> |
| <p>The maximum number of request processing threads to be created |
| by this <strong>Connector</strong>, which therefore determines the |
| maximum number of simultaneous requests that can be handled. If |
| not specified, this attribute is set to 200.</p> |
| </attribute> |
| |
| <attribute name="minSpareThreads" required="false"> |
| <p>The number of request processing threads that will be created |
| when this <strong>Connector</strong> is first started. The connector |
| will also make sure it has the specified number of idle processing |
| threads available. This attribute should be set to a value smaller |
| than that set for <code>maxThreads</code>. The default value is 4.</p> |
| </attribute> |
| |
| <attribute name="noCompressionUserAgents" required="false"> |
| <p>The value is a comma separated list of regular expressions matching |
| user-agents of HTTP clients for which compression should not be used, |
| because these clients, although they do advertise support for the |
| feature, have a broken implementation. |
| The default value is an empty String (regexp matching disabled).</p> |
| </attribute> |
| |
| <attribute name="port" required="true"> |
| <p>The TCP port number on which this <strong>Connector</strong> |
| will create a server socket and await incoming connections. Your |
| operating system will allow only one server application to listen |
| to a particular port number on a particular IP address.</p> |
| </attribute> |
| |
| <attribute name="protocol" required="false"> |
| <p>This attribute value must be <code>HTTP/1.1</code> to use the HTTP |
| handler, which is the default.</p> |
| </attribute> |
| |
| <attribute name="proxyName" required="false"> |
| <p>If this <strong>Connector</strong> is being used in a proxy |
| configuration, configure this attribute to specify the server name |
| to be returned for calls to <code>request.getServerName()</code>. |
| See <a href="#Proxy Support">Proxy Support</a> for more |
| information.</p> |
| </attribute> |
| |
| <attribute name="proxyPort" required="false"> |
| <p>If this <strong>Connector</strong> is being used in a proxy |
| configuration, configure this attribute to specify the server port |
| to be returned for calls to <code>request.getServerPort()</code>. |
| See <a href="#Proxy Support">Proxy Support</a> for more |
| information.</p> |
| </attribute> |
| |
| <attribute name="restrictedUserAgents" required="false"> |
| <p>The value is a comma separated list of regular expressions matching |
| user-agents of HTTP clients for which HTTP/1.1 or HTTP/1.0 keep alive |
| should not be used, even if the clients advertise support for these |
| features. |
| The default value is an empty String (regexp matching disabled).</p> |
| </attribute> |
| |
| <attribute name="socketBuffer" required="false"> |
| <p>The size (in bytes) of the buffer to be provided for socket |
| output buffering. -1 can be specified to disable the use of a buffer. |
| By default, a buffers of 9000 bytes will be used.</p> |
| </attribute> |
| |
| <attribute name="tcpNoDelay" required="false"> |
| <p>If set to <code>true</code>, the TCP_NO_DELAY option will be |
| set on the server socket, which improves performance under most |
| circumstances. This is set to <code>true</code> by default.</p> |
| </attribute> |
| |
| <attribute name="threadPriority" required="false"> |
| <p>The priority of the request processing threads within the JVM. |
| The default value is <code>java.lang.Thread#NORM_PRIORITY</code>. |
| See the JavaDoc for the java.lang.Thread class for more details on |
| what this priority means. |
| </p> |
| </attribute> |
| |
| </attributes> |
| |
| </subsection> |
| |
| </section> |
| |
| |
| <section name="Nested Components"> |
| |
| <p>The only element that may be embedded inside a <strong>Connector</strong> |
| element is a <strong>Factory</strong> element, which is used to configure |
| a server socket factory component. This element is never required, but |
| is still supported for backwards compatibility with earlier version of |
| Tomcat.</p> |
| |
| </section> |
| |
| |
| <section name="Special Features"> |
| |
| |
| <subsection name="HTTP/1.1 and HTTP/1.0 Support"> |
| |
| <p>This <strong>Connector</strong> 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 |
| <strong>Connector</strong> will gracefully fall back to supporting this |
| protocol as well. No special configuration is required to enable this |
| support. The <strong>Connector</strong> also supports HTTP/1.0 |
| keep-alive.</p> |
| |
| <p>RFC 2616 requires that HTTP servers always begin their responses with |
| the highest HTTP version that they claim to support. Therefore, this |
| <strong>Connector</strong> will always return <code>HTTP/1.1</code> at |
| the beginning of its responses.</p> |
| |
| </subsection> |
| |
| |
| <subsection name="Logging Output"> |
| |
| <p>Any debugging or exception logging information generated by this |
| <strong>Connector</strong> will be automatically routed to the |
| <a href="logger.html">Logger</a> that is associated with our related |
| <a href="engine.html">Engine</a>. No special configuration is required |
| to enable this support.</p> |
| |
| </subsection> |
| |
| |
| <subsection name="Proxy Support"> |
| |
| <p>The <code>proxyName</code> and <code>proxyPort</code> attributes can |
| be used when Tomcat is run behind a proxy server. These attributes |
| modify the values returned to web applications that call the |
| <code>request.getServerName()</code> and <code>request.getServerPort()</code> |
| 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.</p> |
| |
| <p>For more information, see the |
| <a href="../proxy-howto.html">Proxy Support HOW-TO</a>.</p> |
| |
| </subsection> |
| |
| |
| <subsection name="SSL Support"> |
| |
| <p>You can enable SSL support for a particular instance of this |
| <strong>Connector</strong> by setting the <code>secure</code> attribute to |
| <code>true</code>. In addition, you may need to configure the following |
| attributes:</p> |
| |
| <attributes> |
| |
| <attribute name="algorithm" required="false"> |
| <p>The certificate encoding algorithm to be used. If not |
| specified, the default value is <code>SunX509</code>.</p> |
| </attribute> |
| |
| <attribute name="clientAuth" required="false"> |
| <p>Set to <code>true</code> if you want the SSL stack to |
| require a valid certificate chain from the client before |
| accepting a connection. A <code>false</code> value (which |
| is the default) will not require a certificate chain unless |
| the client requests a resource protected by a security constraint |
| that uses <code>CLIENT-CERT</code> authentication.</p> |
| </attribute> |
| |
| <attribute name="keystoreFile" required="false"> |
| <p>The pathname of the keystore file where you have stored the |
| server certificate to be loaded. By default, the pathname is |
| the file "<code>.keystore</code>" in the operating system home |
| directory of the user that is running Tomcat.</p> |
| </attribute> |
| |
| <attribute name="keystorePass" required="false"> |
| <p>The password used to access the server certificate from the |
| specified keystore file. The default value is "<code>changeit</code>". |
| </p> |
| </attribute> |
| |
| <attribute name="keystoreType" required="false"> |
| <p>The type of keystore file to be used for the server certificate. |
| If not specified, the default value is "<code>JKS</code>".</p> |
| </attribute> |
| |
| <attribute name="sslProtocol" required="false"> |
| <p>The version of the SSL protocol to use. If not specified, |
| the default is "<code>TLS</code>".</p> |
| </attribute> |
| |
| <attribute name="ciphers" required="false"> |
| <p>A comma seperated list of the encryption ciphers that may be used. |
| If not specified, then any available cipher may be used.</p> |
| </attribute> |
| |
| </attributes> |
| |
| <p>For more information, see the |
| <a href="../ssl-howto.html">SSL Configuration HOW-TO</a>.</p> |
| |
| </subsection> |
| |
| |
| </section> |
| |
| |
| </body> |
| |
| </document> |