From 6f94c1402862d44177301011a0163d0c0ff87616 Mon Sep 17 00:00:00 2001 From: markt Date: Mon, 1 Feb 2010 14:39:47 +0000 Subject: [PATCH] Align the HTTP and HTTPS documentation with the code. Move the APR/native configuration into the standard config directory. git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@905290 13f79535-47bb-0310-9956-ffa450edef68 --- webapps/docs/apr.xml | 189 ++---------- webapps/docs/config/ajp.xml | 72 ++--- webapps/docs/config/http.xml | 718 ++++++++++++++++++++++++++++--------------- 3 files changed, 517 insertions(+), 462 deletions(-) diff --git a/webapps/docs/apr.xml b/webapps/docs/apr.xml index 0191b3ff9..712414163 100644 --- a/webapps/docs/apr.xml +++ b/webapps/docs/apr.xml @@ -145,179 +145,26 @@
+ + + +

For HTTP configuration, see the HTTP + connector configuration documentation.

- - -

- When APR is enabled, the HTTP connector will use sendfile for handling large static files (all such - files will be sent asynchronously using high performance kernel level calls), and will use - a socket poller for keepalive, increasing scalability of the server. -

- -

- The following attributes are supported in the HTTP APR connector in addition to the ones supported - in the regular HTTP connector: -

- - - - -

The number of milliseconds this Connector will wait for - another HTTP request before closing the connection. - The default value is to use the value that has been set for the - connectionTimeout attribute. This value also controls the timeout interval which - is used for Comet connections.

- - - -

Duration of a poll call. Lowering this value will slightly decrease latency of connections - being kept alive in some cases, but will use more CPU as more poll calls are being made. The - default value is 2000 (5ms).

- - - -

Amount of sockets that the poller responsible for polling kept alive connections can hold at a - given time. Extra connections will be closed right away. The default value is 8192, corresponding to - 8192 keepalive connections.

- - - -

Number of threads used to poll kept alive connections. On Windows the - default is chosen so that the sockets managed by each thread is - less than 1024. For Linux the default is 1. Changing the default on - Windows is likely to have a negative performance impact.

- - - -

Use kernel level sendfile for certain static files. The default value is true.

- - - -

Amount of sockets that the poller responsible for sending static files asynchronously can hold - at a given time. Extra connections will be closed right away without any data being sent - (resulting in a zero length file on the client side). Note that in most cases, sendfile is a call - that will return right away (being taken care of "synchronously" by the kernel), and the sendfile - poller will not be used, so the amount of static files which can be sent concurrently is much larger - than the specified amount. The default value is 1024.

- - - -

Number of threads used service sendfile sockets. On Windows the - default is chosen so that the sockets managed by each thread is - less than 1024. For Linux the default is 1. Changing the default on - Windows is likely to have a negative performance impact.

- - - - - - - - -

- When APR is enabled, the HTTPS connector will use a socket poller for keepalive, increasing - scalability of the server. It also uses OpenSSL, which may be more optimized than JSSE depending - on the processor being used, and can be complemented with many commercial accelerator components. - Unlike the HTTP connector, the HTTPS connector cannot use sendfile to optimize static file - processing. -

- -

- The HTTPS APR connector has the same basic attributes than the HTTP APR connector, but adds - OpenSSL specific ones. For the full details on using OpenSSL, please refer to OpenSSL documentations - and the many books available for it (see the Official OpenSSL - website). The SSL specific attributes for the connector are: -

- - - - -

- Enable SSL on the socket, default value is false. Set this value to true - to enable SSL handshake/encryption/decryption in the APR connector. -

- - -

- Protocol which may be used for communicating with clients. The default is "all", with - other acceptable values being "SSLv2", "SSLv3", "TLSv1", and "SSLv2+SSLv3". -

- - -

- Ciphers which may be used for communicating with clients. The default is "ALL", with - other acceptable values being a list of ciphers, with ":" used as the delimiter - (see OpenSSL documentation for the list of ciphers supported). -

- - -

- Name of the file that contains the server certificate. The format is PEM-encoded. -

- - -

- Name of the file that contains the server private key. The format is PEM-encoded. - The default value is the value of "SSLCertificateFile" and in this case both certificate - and private key have to be in this file (NOT RECOMMENDED). -

- - -

- Pass phrase for the encrypted private key. If "SSLPassword" is not provided, the callback function - should prompt for the pass phrase. -

- - -

- Ask client for certificate. The default is "none", meaning the client will not have the opportunity - to submit a certificate. Other acceptable values include "optional", "require" and "optionalNoCA". -

- - -

- Maximum verification depth for client certificates. The default is "10". -

- - -

- See the mod_ssl documentation. -

- - -

- See the mod_ssl documentation. -

- - -

- See the mod_ssl documentation. -

- - -

- See the mod_ssl documentation. -

- - -

- See the mod_ssl documentation. -

- +

For HTTPS configuration, see the + HTTPS connector configuration + documentation.

- - -

- An example SSL Connector declaration can be: - - <Connector port="443" maxHttpHeaderSize="8192" - maxThreads="150" - enableLookups="false" disableUploadTimeout="true" - acceptCount="100" scheme="https" secure="true" - SSLEnabled="true" - SSLCertificateFile="${catalina.base}/conf/localhost.crt" - SSLCertificateKeyFile="${catalina.base}/conf/localhost.key" /> -

+

An example SSL Connector declaration is: + + <Connector port="443" maxHttpHeaderSize="8192" + maxThreads="150" + enableLookups="false" disableUploadTimeout="true" + acceptCount="100" scheme="https" secure="true" + SSLEnabled="true" + SSLCertificateFile="${catalina.base}/conf/localhost.crt" + SSLCertificateKeyFile="${catalina.base}/conf/localhost.key" /> +

diff --git a/webapps/docs/config/ajp.xml b/webapps/docs/config/ajp.xml index b178678c7..ae6f1c61b 100644 --- a/webapps/docs/config/ajp.xml +++ b/webapps/docs/config/ajp.xml @@ -46,17 +46,18 @@ the jvmRoute attribute of the Engine.

-

The native connectors supported with this Tomcat release are: -

    -
  • JK 1.2.x with any of the supported servers
    • -
  • mod_proxy on Apache httpd 2.x (included by default in Apache HTTP Server 2.2), - with AJP enabled: see - the httpd docs - for details.
    • -
-

- -

Other native connectors supporting AJP may work, but are no longer supported.

+

The native connectors supported with this Tomcat release are: +

    +
  • JK 1.2.x with any of the supported servers
    • +
  • mod_proxy on Apache httpd 2.x (included by default in Apache HTTP + Server 2.2), with AJP enabled: see + the + httpd docs for details.
    • +
+

+ +

Other native connectors supporting AJP may work, but are no longer + supported.

@@ -77,8 +78,9 @@

If set to true, all paths for session cookies will be set - to /. This can be useful for portlet specification implementations. - If not specified, this attribute is set to false.

+ to /. This can be useful for portlet specification + implementations. If not specified, this attribute is set to + false.

 @@ -92,7 +94,7 @@

The maximum size in bytes of the POST which will be handled by - the container FORM URL parameter parsing. The feature can be disabled 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).

 @@ -112,6 +114,13 @@ to 4096 (4 kilobytes).

 + +

The TCP port number on which this Connector + 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.

+ +

Sets the protocol to handle incoming traffic. To configure an AJP connector this must be specified. If no value for protocol is provided, @@ -157,25 +166,21 @@ number specified here.

 - -

This attribute controls request registration for JMX monitoring - of the Connector. It is enabled by default, but may be turned - it off to save a bit of memory.

- -

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". - See SSL Support for more information.

+

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). The default value is false.

+ 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.

 @@ -196,7 +201,7 @@

Set this attribute to true to cause Tomcat to use - the ServerName passed by the native web server to determine the Host + the IP address passed by the native web server to determine the Host to send the request to. The default value is false.

 @@ -205,8 +210,6 @@ support for the Servlet specification using the header recommended in the specification. The default value is false.

 - - @@ -214,8 +217,7 @@ -

To use AJP, you - must specify the protocol attribute (see above).

+

To use AJP, you must specify the protocol attribute (see above).

These implementations support the AJP 1.3 protocol.

@@ -252,13 +254,6 @@ presented. The default value is infinite (i.e. no timeout).

- -

Sets the TCP_DEFER_ACCEPT flag on the listening socket for - this connector. The default value is true where - TCP_DEFER_ACCEPT is supported by the operating system, - otherwise it is false.

- -

A reference to the name in an Executor element. If this attribute is enabled, and the named executor exists, the connector will @@ -290,13 +285,6 @@ value is 8192.

 - -

The TCP port number on which this Connector - 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.

- -

Only requests from workers with this secret keyword will be accepted.

diff --git a/webapps/docs/config/http.xml b/webapps/docs/config/http.xml index c3417fc50..5f93bca00 100644 --- a/webapps/docs/config/http.xml +++ b/webapps/docs/config/http.xml @@ -78,14 +78,9 @@

If set to true, all paths for session cookies will be set - to /. This can be useful for portlet specification implementations. - If not specified, this attribute is set to false.
- A side effect to setting this to true, is that if Tomcat creates a new session it will attempt to use the - cookie session id if supplied by the client.
- SVN check in
- Dev discussion
- Work around -

+ to /. This can be useful for portlet specification + implementations. If not specified, this attribute is set to + false.

 @@ -119,17 +114,23 @@ to 4096 (4 kilobytes).

 + +

The TCP port number on which this Connector + 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.

+ + -

- Sets the protocol to handle incoming traffic. - The default value is HTTP/1.1 which uses an auto-switching - mechanism to select either a blocking Java based connector or an - APR/native based connector. If the PATH (Windows) or - LD_LIBRARY_PATH (on most unix systems) environment variables - contain the Tomcat native library, the native/APR connector will be used. - If the native library cannot be found, the blocking Java based connector - will be used. Please be advised that the native/APR connector has - different settings for HTTPS than the Java connectors.
+

Sets the protocol to handle incoming traffic. The default value is + HTTP/1.1 which uses an auto-switching mechanism to select + either a blocking Java based connector or an APR/native based connector. + If the PATH (Windows) or LD_LIBRARY_PATH (on + most unix systems) environment variables contain the Tomcat native + library, the native/APR connector will be used. If the native library + cannot be found, the blocking Java based connector will be used. Note + that the native/APR connector has different settings for HTTPS than the + Java connectors.
To use an explicit protocol rather than rely on the auto-switching mechanism described above, the following values may be used:
org.apache.coyote.http11.Http11Protocol - @@ -171,20 +172,6 @@ number specified here.

 - -

- Use this attribute to enable SSL traffic on a connector. - To turn on SSL handshake/encryption/decryption on a connector - set this value to true. - The default value is false. - When turning this value true 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. -

- -

Set this attribute to the name of the protocol you wish to have returned by calls to request.getScheme(). For @@ -229,9 +216,6 @@ support for the Servlet specification using the header recommended in the specification. The default value is false.

 - - - @@ -239,9 +223,9 @@ -

- HTTP supports the following additional attributes (in addition to the - common attributes listed above):

+

The standard HTTP connectors (BIO, NIO and APR/native) all support the + following attributes in addition to the common Connector attributes listed + above.

@@ -252,6 +236,14 @@ value is 100.

 + +

The number of threads to be used to accept connections. Increase this + value on a multi CPU machine, although you would never really need more + than 2. Also, with a lot of non keep alive connections, you + might want to increase this value as well. Default value is + 1.

+ +

For servers with more than one IP address, this attribute specifies which address will be used for listening on the specified @@ -259,12 +251,6 @@ associated with the server.

 - -

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.

- -

The value is a comma separated list of MIME types for which HTTP compression may be used. @@ -283,10 +269,16 @@ attribute is set to "off".

 + +

If compression is set to "on" then this attribute + may be used to specify the minimum amount of data before the output is + compressed. If not specified, this attribute is defaults to "2048".

+ +

The number of milliseconds during which the sockets used by this Connector will linger when they are closed. - The default value is -1 (socket linger is disabled).

+ The default value -1 which disables this option.

 @@ -295,19 +287,6 @@ presented. The default value is 60000 (i.e. 60 seconds).

 - -

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.

- - - -

The number of milliseconds this Connector will wait for - another HTTP request before closing the connection. - The default value is to use the value that has been set for the - connectionTimeout attribute.

- -

This flag allows the servlet container to use a different, longer connection timeout while a servlet is being executed, which in the end @@ -316,10 +295,25 @@ this attribute is set to "true".

 + +

A reference to the name in an Executor + element. If this attribute is set, and the named executor exists, the + connector will use the executor, and all the other thread attributes will + be ignored. Note that if a shared executor is not specified for a + connector then the connector will use a private, internal executor to + provide the thread pool.

+ + + +

The number of milliseconds this Connector will wait + for another HTTP request before closing the connection. The default value + is to use the value that has been set for the + connectionTimeout attribute.

+ +

The maximum size of the request and response HTTP header, specified - in bytes. - If not specified, this attribute is set to 8192 (8 KB).

+ in bytes. If not specified, this attribute is set to 8192 (8 KB).

 @@ -340,6 +334,11 @@ execute tasks using the executor rather than an internal thread pool.

 + +

The minimum number of threads always kept running. If not specified, + the default of 10 is used.

+ +

The value is a comma separated list of regular expressions matching user-agents of HTTP clients for which compression should not be used, @@ -348,13 +347,13 @@ The default value is an empty String (regexp matching disabled).

 - -

The TCP port number on which this Connector - 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.

+ +

The protocol handler caches Processor objects to speed up performance. + This setting dictates how many of these objects get cached. + -1 means unlimited, default is 200. Set this + value somewhere close to your maxThreads value.

 - +

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 @@ -379,6 +378,19 @@ By default, a buffers of 9000 bytes will be used.

 + +

Use this attribute to enable SSL traffic on a connector. + To turn on SSL handshake/encryption/decryption on a connector + set this value to true. + The default value is false. + When turning this value true 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. +

+ +

If set to true, the TCP_NO_DELAY option will be set on the server socket, which improves performance under most @@ -394,8 +406,15 @@ + + + +

The BIO and NIO implementation support the following Java TCP socket + attributes in addition to the common Connector and HTTP attributes listed + above.

+

(int)The socket receive buffer (SO_RCVBUF) size in bytes. JVM default @@ -406,8 +425,8 @@ used if not set.

 -

(bool)same as the standard setting tcpNoDelay. JVM - default used if not set.

+

(bool)This is equivalent to standard attribute + tcpNoDelay.

(bool)Boolean value for the socket's keep alive setting @@ -423,21 +442,31 @@

(bool)Boolean value for the sockets so linger option (SO_LINGER). + A value for the standard attribute connectionLinger + that is >=0 is equivalent to setting this to true. + A value for the standard attribute connectionLinger + that is <0 is equivalent to setting this to false. Both this attribute and soLingerTime must be set else the JVM defaults will be used for both.

 -

(bool)Value in seconds for the sockets so linger option (SO_LINGER). +

(int)Value in seconds for the sockets so linger option (SO_LINGER). + This is equivalent to standard attribute + connectionLinger. Both this attribute and soLingerOn must be set else the JVM defaults will be used for both.

 -

(int)Value in milliseconds for the sockets read timeout (SO_TIMEOUT). - JVM default used if not set.

+

This is equivalent to standard attribute + connectionTimeout.

(byte)Value between 0 and 255 for the traffic class on the socket. JVM default used if not set.

+

NoteOn some JDK versions, setting + soTrafficClass causes a problem. A work around for this + is to add the -Djava.net.preferIPv4Stack=true value to your + JVM options.

(int)The first value for the performance settings. See @@ -464,165 +493,236 @@ - + + +

There are no BIO specific configuration settings.

+ + + + -

The NIO connector exposes all the low level socket properties that can be used to tune the connector. - Most of these attributes are directly linked to the socket implementation in the JDK so you can find out - about the actual meaning in the JDK API documentation.
- NoteOn some JDK versions, setTrafficClass causes a problem, a work around for this is to add - the -Djava.net.preferIPv4Stack=true value to your command line

+

The following attributes are specific to the NIO connector.

- -

(bool)Use this attribute to enable or disable sendfile capability. - The default value is true -

- - -

(bool)Set to true to use the NIO thread pool executor. The default value is true. - If set to false, it uses a thread pool based on a stack for its execution. - Generally, using the executor yields a little bit slower performance, but yields a better - fairness for processing connections in a high load environment as the traffic gets queued through a - FIFO queue. If set to true(default) then the max pool size is the maxThreads attribute - and the core pool size is the minSpareThreads. - This value is ignored if the executor attribute is present and points to a valid shared thread pool. -

- - -

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.

- - -

(int)The number of threads to be used to accept connections. Increase this value on a multi CPU machine, - although you would never really need more than 2. Also, with a lot of non keep alive connections, - you might want to increase this value as well. Default value is 1.

+ + +

(int)The priority of the acceptor threads. The threads used to accept + new connections. The default value is + java.lang.Thread#NORM_PRIORITY. See the JavaDoc for the + java.lang.Thread class for more details on what this priority means.

 +

(int)The number of threads to be used to run for the polling events. Default value is 1 per processor. Can't see a reason to go above that. But experiment and find your own results.

 + -

(int)The priority of the poller threads. - The default value is java.lang.Thread#NORM_PRIORITY. - See the JavaDoc for the java.lang.Thread class for more details on - what this priority means. -

+

(int)The priority of the poller threads. The default value is + java.lang.Thread#NORM_PRIORITY. See the JavaDoc for the + java.lang.Thread class for more details on what this priority means.

 - -

(int)The priority of the acceptor threads. The threads used to accept new connections. - The default value is java.lang.Thread#NORM_PRIORITY. - See the JavaDoc for the java.lang.Thread class for more details on - what this priority means. -

- - + -

(int)The time in milliseconds to timeout on a select() for the poller. - This value is important, since connection clean up is done on the same thread, so do not set this - value to an extremely high one. The default value is 1000 milliseconds.

+

(int)The time in milliseconds to timeout on a select() for the + poller. This value is important, since connection clean up is done on + the same thread, so do not set this value to an extremely high one. The + default value is 1000 milliseconds.

 + -

(bool)Whether to allow comet servlets or not, Default value is true.

+

(bool)Whether to allow comet servlets or not. Default value is + true.

 - -

(int)The protocol handler caches Http11NioProcessor objects to speed up performance. - This setting dictates how many of these objects get cached. - -1 means unlimited, default is 200. Set this value somewhere close to your maxThreads value. -

- - -

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.

+ + +

(bool)Use this attribute to enable or disable sendfile capability. + The default value is true.

 -

(bool)Boolean value, whether to use direct ByteBuffers or java mapped ByteBuffers. Default is false -
When you are using direct buffers, make sure you allocate the appropriate amount of memory for the - direct memory space. On Sun's JDK that would be something like -XX:MaxDirectMemorySize=256m

+

(bool)Boolean value, whether to use direct ByteBuffers or java mapped + ByteBuffers. Default is false.
+ When you are using direct buffers, make sure you allocate the + appropriate amount of memory for the direct memory space. On Sun's JDK + that would be something like -XX:MaxDirectMemorySize=256m. +

+ -

(int)Each connection that is opened up in Tomcat get associated with a read and a write ByteBuffer - This attribute controls the size of these buffers. By default this read buffer is sized at 8192 bytes. - For lower concurrency, you can increase this to buffer more data. - For an extreme amount of keep alive connections, decrease this number or increase your heap size.

+

(int)Each connection that is opened up in Tomcat get associated with + a read ByteBuffer. This attribute controls the size of this buffer. By + default this read buffer is sized at 8192 bytes. For lower + concurrency, you can increase this to buffer more data. For an extreme + amount of keep alive connections, decrease this number or increase your + heap size.

 + -

(int)Each connection that is opened up in Tomcat get associated with a read and a write ByteBuffer - This attribute controls the size of these buffers. By default this write buffer is sized at 8192 bytes. - For low concurrency you can increase this to buffer more response data. - For an extreme amount of keep alive connections, decrease this number or increase your heap size. -
- The default value here is pretty low, you should up it if you are not dealing with tens of thousands - concurrent connections.

+

(int)Each connection that is opened up in Tomcat get associated with + a write ByteBuffer. This attribute controls the size of this buffer. By + default this write buffer is sized at 8192 bytes. For low + concurrency you can increase this to buffer more response data. For an + extreme amount of keep alive connections, decrease this number or + increase your heap size.
+ The default value here is pretty low, you should up it if you are not + dealing with tens of thousands concurrent connections.

 + -

(int)The Nio connector uses a class called NioChannel that holds elements linked to a socket. - To reduce garbage collection, the Nio connector caches these channel objects. - This value specifies the size of this cache. - The default value is 500, and represents that the cache will hold 500 NioChannel objects. - Other values are -1. unlimited cache, and 0, no cache.

+

(int)The NIO connector uses a class called NioChannel that holds + elements linked to a socket. To reduce garbage collection, the NIO + connector caches these channel objects. This value specifies the size of + this cache. The default value is 500, and represents that + the cache will hold 500 NioChannel objects. Other values are + -1 for unlimited cache and 0 for no cache.

 + -

(int)The NioChannel pool can also be size based, not used object based. The size is calculated as follows:
- NioChannel buffer size = read buffer size + write buffer size
- SecureNioChannel buffer size = application read buffer size + application write buffer size + network read buffer size + network write buffer size
- The value is in bytes, the default value is 1024*1024*100 (100MB) -

+

(int)The NioChannel pool can also be size based, not used object + based. The size is calculated as follows:
+ NioChannel + buffer size = read buffer size + write buffer size
+ SecureNioChannel buffer size = application read buffer size + + application write buffer size + network read buffer size + + network write buffer size
+ The value is in bytes, the default value is 1024*1024*100 + (100MB).

 + -

(int)Tomcat will cache SocketProcessor objects to reduce garbage collection. - The integer value specifies how many objects to keep in the cache at most. - The default is 500. - Other values are -1. unlimited cache, and 0, no cache.

+

(int)Tomcat will cache SocketProcessor objects to reduce garbage + collection. The integer value specifies how many objects to keep in the + cache at most. The default is 500. Other values are + -1 for unlimited cache and 0for no cache.

 + -

(int)Tomcat will cache KeyAttachment objects to reduce garbage collection. - The integer value specifies how many objects to keep in the cache at most. - The default is 500. - Other values are -1. unlimited cache, and 0, no cache.

+

(int)Tomcat will cache KeyAttachment objects to reduce garbage + collection. The integer value specifies how many objects to keep in the + cache at most. The default is 500. Other values are + -1 for unlimited cache and 0for no cache.

 + -

(int)Tomcat will cache PollerEvent objects to reduce garbage collection. - The integer value specifies how many objects to keep in the cache at most. - The default is 500. - Other values are -1. unlimited cache, and 0, no cache.

+

(int)Tomcat will cache PollerEvent objects to reduce garbage + collection. The integer value specifies how many objects to keep in the + cache at most. The default is 500. Other values are + -1 for unlimited cache and 0for no cache.

 + -

(int)The max selectors to be used in the pool, to reduce selector contention. - Use this option when the command line org.apache.tomcat.util.net.NioSelectorShared value is set to false. - Default value is 200.

+

(int)The max selectors to be used in the pool, to reduce selector + contention. Use this option when the command line + org.apache.tomcat.util.net.NioSelectorShared value is set + to false. Default value is 200.

 + -

(int)The max spare selectors to be used in the pool, to reduce selector contention. - When a selector is returned to the pool, the system can decide to keep it or let it be GC:ed. - Use this option when the command line org.apache.tomcat.util.net.NioSelectorShared value is set to false. - Default value is -1 (unlimited)

+

(int)The max spare selectors to be used in the pool, to reduce + selector contention. When a selector is returned to the pool, the system + can decide to keep it or let it be GC'd. Use this option when the + command line org.apache.tomcat.util.net.NioSelectorShared + value is set to false. Default value is -1 (unlimited).

 + -

The following command line options are available for the NIO connector:
- -Dorg.apache.tomcat.util.net.NioSelectorShared=true|false - default is true. - Set this value to false if you wish to use a selector for each thread. - the property. If you do set it to false, you can control the size of the pool of selectors by using the - selectorPool.maxSelectors attribute

+

The following command line options are available for the NIO + connector:
+ -Dorg.apache.tomcat.util.net.NioSelectorShared=true|false + - default is true. Set this value to false if you wish to + use a selector for each thread. If you do set it to false, you can + control the size of the pool of selectors by using the + selectorPool.maxSelectors attribute.

 + -

(int)The NIO connector implements an OutOfMemoryError strategy called parachute. - It holds a chunk of data as a byte array. In case of an OOM, - this chunk of data is released and the error is reported. This will give the VM enough room - to clean up. The oomParachute represent the size in bytes of the parachute(the byte array). - The default value is 1024*1024(1MB). - Please note, this only works for OOM errors regarding the Java Heap space, and there is absolutely no - guarantee that you will be able to recover at all. - If you have an OOM outside of the Java Heap, then this parachute trick will not help. +

(int)The NIO connector implements an OutOfMemoryError strategy called + parachute. It holds a chunk of data as a byte array. In case of an OOM, + this chunk of data is released and the error is reported. This will give + the VM enough room to clean up. The oomParachute represents + the size in bytes of the parachute(the byte array). The default value is + 1024*1024(1MB). Please note, this only works for OOM errors + regarding the Java Heap space, and there is absolutely no guarantee + that you will be able to recover at all. If you have an OOM outside of + the Java Heap, then this parachute trick will not help. +

+ + + + + + +

The following attributes are specific to the APR connector.

+ + + + +

Sets the TCP_DEFER_ACCEPT flag on the listening socket + for this connector. The default value is true where + TCP_DEFER_ACCEPT is supported by the operating system, + otherwise it is false.

+ + + +

Amount of sockets that the poller responsible for polling kept alive + connections can hold at a given time. Extra connections will be closed + right away. The default value is 8192, corresponding to 8192 keep-alive + connections.

+ + + +

Number of threads used to poll kept alive connections. On Windows the + default is chosen so that the sockets managed by each thread is + less than 1024. For Linux the default is 1. Changing the default on + Windows is likely to have a negative performance impact.

+ + + +

Duration of a poll call. Lowering this value will slightly decrease + latency of connections being kept alive in some cases, but will use more + CPU as more poll calls are being made. The default value is 2000 (5ms).

+ + +

Amount of sockets that the poller responsible for sending static + files asynchronously can hold at a given time. Extra connections will be + closed right away without any data being sent (resulting in a zero + length file on the client side). Note that in most cases, sendfile is a + call that will return right away (being taken care of "synchronously" by + the kernel), and the sendfile poller will not be used, so the amount of + static files which can be sent concurrently is much larger than the + specified amount. The default value is 1024.

+ + + +

Number of threads used service sendfile sockets. On Windows the + default is chosen so that the sockets managed by each thread is + less than 1024. For Linux the default is 1. Changing the default on + Windows is likely to have a negative performance impact.

+ + + +

(int)The priority of the acceptor and poller threads. The default + value is java.lang.Thread#NORM_PRIORITY. See the JavaDoc + for the java.lang.Thread class for more details on what this priority + means.

+ + + +

(bool)Whether to allow comet servlets or not. Default value is + true.

+ + + +

(bool)Use this attribute to enable or disable sendfile capability. + The default value is true.

+ + + @@ -682,12 +782,17 @@ Connector by setting the SSLEnabled attribute to true.

-

You will also need to set the scheme and secure attributes - to the values https and true respectively, - to pass correct information to the servlets.

+

You will also need to set the scheme and secure + attributes to the values https and true + respectively, to pass correct information to the servlets.

-

In addition, you may need to configure the following - attributes:

+

The BIO and NIO connectors used the JSSE SSL whereas the APR/native + connector uses OpenSSL. Therefore, in addition to using different attributes + to configure SSL, the APR/native connector also requires keys and certificates + to be provided in a different format.

+ +

The BIO and NIO connectors use the following attributes to configure SSL: +

@@ -699,6 +804,23 @@ documentation for the default value.

+ +

Is unsafe legacy TLS renegotiation allowed which is likely to expose + users to CVE-2009-3555, a man-in-the-middle vulnerability in the TLS + protocol that allows an attacker to inject arbitrary data into the user's + request. If not specified, a default of false is used.

+ + + +

The comma separated list of encryption ciphers that this socket is + allowed to use. By default, the default ciphers for the JVM will be used. + Note that this usually means that the weak export grade ciphers will be + included in the list of available ciphers. The ciphers are specified using + the JSSE cipher naming convention. The special value of ALL + will enable all supported ciphers. This will include many that are not + secure. ALL is intended for testing purposes only.

+ +

Set to true if you want the SSL stack to require a valid certificate chain from the client before accepting a connection. @@ -709,6 +831,23 @@ constraint that uses CLIENT-CERT authentication.

 + +

The certificate revocation list to be used to verify client + certificates. If not defined, client certificates will not be checked + against a certificate revocation list.

+ + + +

The alias used to for the server certificate in the keystore. If not + specified the first key read in the keystore will be used.

+ + + +

The password used to access the server certificate from the + specified keystore file. The default value is "changeit". +

+ +

The pathname of the keystore file where you have stored the server certificate to be loaded. By default, the pathname is @@ -724,11 +863,6 @@

- -

The type of keystore file to be used for the server certificate. - If not specified, the default value is "JKS".

- -

The name of the keystore provider to be used for the server certificate. If not specified, the list of registered providers is @@ -737,30 +871,44 @@

+ +

The type of keystore file to be used for the server certificate. + If not specified, the default value is "JKS".

+ + + +

The number of SSL sessions to maintain in the session cache. Use 0 to + specify an unlimited cache size. If not specified, a default of 0 is + used.

+ + + +

The time, in seconds, after the creation of an SSL session that it will + timeout. Use 0 to specify an unlimited timeout. If not specified, a + default of 86400 (24 hours) is used.

+ + + +

NIO only. The version of the SSL protocols to use. If + not specified, the default is "TLSv1,SSLv3,SSLv2Hello".

+ +

The version of the SSL protocol to use. If not specified, the default is "TLS".

 - -

The comma separated list of encryption ciphers that this socket is - allowed to use. By default, the default ciphers for the JVM will be used. - Note that this usually means that the weak export grade ciphers will be - included in the list of available ciphers. The ciphers are specified using - the JSSE cipher naming convention. The special value of ALL - will enable all supported ciphers. This will include many that are not - secure. ALL is intended for testing purposes only.

- - - -

The alias used to for the server certificate in the keystore. If not - specified the first key read in the keystore will be used.

+ +

The maximum number of intermediate certificates that will be allowed + when validating client certificates. If not specified, the default value + of 5 will be used.

 - -

The password used to access the server certificate from the - specified keystore file. The default value is "changeit". -

+ +

The algorithm to use for truststore. If not specified, the default + value returned by + javax.net.ssl.TrustManagerFactory.getDefaultAlgorithm() is + used.

 @@ -778,13 +926,6 @@ keystorePassis set, no trust store will be configured.

 - -

The type of key store used for the trust store. The default is the - value of the javax.net.ssl.trustStoreType system property. If - that property is null, the value of keystoreType is used as - the default.

- -

The name of the truststore provider to be used for the server certificate. The default is the value of the @@ -797,46 +938,125 @@

- -

The algorithm to use for truststore. If not specified, the default - value returned by - javax.net.ssl.TrustManagerFactory.getDefaultAlgorithm() is - used.

+ +

The type of key store used for the trust store. The default is the + value of the javax.net.ssl.trustStoreType system property. If + that property is null, the value of keystoreType is used as + the default.

+ + + + +

When APR/native is enabled, the HTTPS connector will use a socket poller + for keep-alive, increasing scalability of the server. It also uses OpenSSL, + which may be more optimized than JSSE depending on the processor being used, + and can be complemented with many commercial accelerator components. Unlike + the HTTP connector, the HTTPS connector cannot use sendfile to optimize static + file processing.

+ +

The HTTPS APR/native connector has the same attributes than the HTTP + APR/native connector, but adds OpenSSL specific ones. For the full details on + using OpenSSL, please refer to OpenSSL documentations and the many books + available for it (see the Official OpenSSL + website). The SSL specific attributes for the APR/native connector are: +

+ + + + +

See + the mod_ssl documentation.

+ + + +

See + the mod_ssl documentation.

 - -

The certificate revocation list to be used to verify client - certificates. If not defined, client certificates will not be checked - against a certificate revocation list.

+ +

See + the mod_ssl documentation.

 - -

The maximum number of intermediate certificates that will be allowed - when validating client certificates. If not specified, the default value - of 5 will be used.

+ +

See + the mod_ssl documentation.

 - -

The number of SSL sessions to maintain in the session cache. Use 0 to - specify an unlimited cache size. If not specified, a default of 0 is - used.

+ +

See + the mod_ssl documentation.

 - - -

The time, in seconds, after the creation of an SSL session that it will - timeout. Use 0 to specify an unlimited timeout. If not specified, a - default of 86400 (24 hours) is used.

+ + +

Name of the file that contains the concatenated certificates for the + trusted certificate authorities. The format is PEM-encoded.

 - -

Is unsafe legacy TLS renegotiation allowed which is likely to expose - users to CVE-2009-3555, a man-in-the-middle vulnerability in the TLS - protocol that allows an attacker to inject arbitrary data into the user's - request. If not specified, a default of false is used.

+ +

Name of the directory that contains the certificates for the trusted + certificate authorities. The format is PEM-encoded.

 - + +

Name of the file that contains the concatenated certificate revocation + lists for the certificate authorities. The format is PEM-encoded.

+ + + +

Name of the directory that contains the certificate revocation lists + for the certificate authorities. The format is PEM-encoded.

+ + +

Name of the file that contains concatenated certifcates for the + certificate authorities which form the certifcate chain for the server + certificate. The format is PEM-encoded.

+ + + +

Name of the file that contains the server certificate. The format is + PEM-encoded.

+ + + +

Name of the file that contains the server private key. The format is + PEM-encoded. The default value is the value of "SSLCertificateFile" and in + this case both certificate and private key have to be in this file (NOT + RECOMMENDED).

+ + + +

Ciphers which may be used for communicating with clients. The default + is "ALL", with other acceptable values being a list of ciphers, with ":" + used as the delimiter (see OpenSSL documentation for the list of ciphers + supported).

+ + + +

Pass phrase for the encrypted private key. If "SSLPassword" is not + provided, the callback function should prompt for the pass phrase.

+ + + +

Protocol which may be used for communicating with clients. The default + is "all", with other acceptable values being "SSLv2", "SSLv3", "TLSv1" + and "SSLv2+SSLv3".

+ + + +

Ask client for certificate. The default is "none", meaning the client + will not have the opportunity to submit a certificate. Other acceptable + values include "optional", "require" and "optionalNoCA".

+ + + +

Maximum verification depth for client certificates. The default is + "10".

+ + + +

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

-- 2.11.0