Menu
▾
▴
[Jboss-svn-commits] JBL Code SVN: r2479 - trunk/labs/jbossweb/xdocs/reference
|
From: <jbo...@li...> - 2006-02-16 08:50:22
|
Author: mla...@jb... Date: 2006-02-16 03:50:16 -0500 (Thu, 16 Feb 2006) New Revision: 2479 Added: trunk/labs/jbossweb/xdocs/reference/conf.xml Removed: trunk/labs/jbossweb/xdocs/reference/arch03.xml Modified: trunk/labs/jbossweb/xdocs/reference/project.xml Log: Remove arch03.xml to conf.xml Deleted: trunk/labs/jbossweb/xdocs/reference/arch03.xml =================================================================== --- trunk/labs/jbossweb/xdocs/reference/arch03.xml 2006-02-16 08:28:59 UTC (rev 2478) +++ trunk/labs/jbossweb/xdocs/reference/arch03.xml 2006-02-16 08:50:16 UTC (rev 2479) @@ -1,647 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE document [ - <!ENTITY project SYSTEM "project.xml"> -]> -<document url="arch03.html"> - - &project; - - <properties> - <author email="mla...@jb...">Mladen Turk</author> - <author email="rem...@jb...">Remy Maucherat</author> - <title>Configuration</title> - </properties> - -<body> - -<section name="Layout"> - <p>JBoss Web uses Embedded Tomcat. The Configuration model is the same as for the JBoss - Application Server. This gives you an easy transition from JBoss Web Server to full-blown - Application Server. - </p> - <figure src="/images/design/configlayout.png" name="Figure 5" text="Configuration Files"/> -</section> - - <section name="APR in JBoss Web"> - - <p> - JBoss Web uses the <a href="http://apr.apache.org/">Apache Portable Runtime</a> to - provide superior scalability, performance, and better integration with native server - technologies. The Apache Portable Runtime is a highly portable library that is at - the heart of Apache HTTP Server 2.x. APR has many uses, including access to advanced IO - functionality (such as sendfile, epoll and OpenSSL), OS level functionality (random number - generation, system status, etc), and native process handling (shared memory, NT - pipes and Unix sockets). - </p> - - <p> - These features allows making JBoss Web a general purpose webserver, will enable much better - integration with other native web technologies, and overall make Java much more viable as - a full fledged webserver platform rather than simply a backend focused technology. - </p> - - </section> - - - <section name="APR Connectors Configuration"> - - <p> - Connector configuration is done using Connector elements in the server.xml file. - </p> - - <subsection name="HTTP"> - - <p> - The HTTP connector uses sendfile for hadling large static files (all such - files will be sent ansychronously using high performance kernel level calls), and uses - a socket poller for keepalive, increasing scalability of the server. - </p> - - <p> - The following attributes are supported in the HTTP connector: - </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="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="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="compressableMimeType" 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="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="emptySessionPath" required="false"> - <p>If set to <code>true</code>, all paths for session cookies will be set - to <code>/</code>. This can be useful for portlet specification implementations, - but will greatly affect performance if many applications are accessed on a given - server by the client. - If not specified, this attribute is set to <code>false</code>.</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="firstReadTimeout" required="false"> - <p>The first read of a request will be made using the specified timeout. If no data is available - after the specified time, the socket will be placed in the poller. Setting this value to 0 will - increase scalability, but will have a minor impact on latency (see the related pollTime attribute). - The default value is 100 (100ms). Note: on Windows, the actual value of firstReadTimeout will - be 500 + the specified value.</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="maxPostSize" required="false"> - <p>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).</p> - </attribute> - - <attribute name="maxSavePostSize" required="false"> - <p>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. If not specified, this attribute is set to - 4096 (4 kilobytes).</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="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="pollTime" required="false"> - <p>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 5000 (5ms).</p> - </attribute> - - <attribute name="pollerSize" required="false"> - <p>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 768, corresponding to - 768 keepalive connections.</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>.</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>.</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="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>".</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="sendfileSize" required="false"> - <p>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 "synchonously" 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 256.</p> - </attribute> - - <attribute name="server" required="false"> - <p>The Server header for the http response. - Unless your paranoid, you won't need this feature. - </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> - - <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> - - <attribute name="useIPVHosts" required="false"> - <p>Set this attribute to <code>true</code> to cause JBoss Web to use - the IP address that the request was recieved on to determine the Host - to send the request to. The default value is <code>false</code>.</p> - </attribute> - - <attribute name="useSendfile" required="false"> - <p>Use kernel level sendfile for certain static files. The default value is true.</p> - </attribute> - - <attribute name="xpoweredBy" required="false"> - <p>Set this attribute to <code>true</code> to cause JBoss Web to advertise - support for the Servlet specification using the header recommended in the - specification. The default value is <code>false</code>.</p> - </attribute> - - </attributes> - - </subsection> - - <subsection name="HTTPS"> - - <p> - 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. - </p> - - <p> - 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 <a href="http://www.openssl.org">Official OpenSSL - website</a>). The SSL specific attributes for the connector are: - </p> - - <attributes> - - <attribute name="SSLEngine" required="false"> - <p> - Name of the SSLEngine to use. off: Do not use SSL, on: Use SSL but no specific ENGINE. - The default value is off. - </p> - </attribute> - <attribute name="SSLProtocol" required="false"> - <p> - Protocol which may be used for communicating with clients. The default is "all", with - other acceptable values being "SSLv2", "SSLv3", "TLSv1", and "SSLv2+SSLv3". - </p> - </attribute> - <attribute name="SSLCipherSuite" required="false"> - <p> - 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). - </p> - </attribute> - <attribute name="SSLCertificateFile" required="true"> - <p> - Name of the file that contains the server certificate. The format is PEM-encoded. - </p> - </attribute> - <attribute name="SSLCertificateKeyFile" required="false"> - <p> - 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). - </p> - </attribute> - <attribute name="SSLPassword" required="false"> - <p> - Pass phrase for the encrypted private key. If "SSLPassword" is not provided, the callback fonction - should prompt for the pass phrase. - </p> - </attribute> - <attribute name="SSLVerifyClient" required="false"> - <p> - 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". - </p> - </attribute> - <attribute name="SSLVerifyDepth" required="false"> - <p> - Maximum verification depth for client certificates. The default is "10". - </p> - </attribute> - <attribute name="SSLCACertificateFile" required="false"> - <p> - See <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcacertificatefile">the mod_ssl documentation</a>. - </p> - </attribute> - <attribute name="SSLCACertificatePath" required="false"> - <p> - See <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcacertificatepath">the mod_ssl documentation</a>. - </p> - </attribute> - <attribute name="SSLCertificateChainFile" required="false"> - <p> - See <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcertificatechainfile">the mod_ssl documentation</a>. - </p> - </attribute> - <attribute name="SSLCARevocationFile" required="false"> - <p> - See <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcarevocationfile">the mod_ssl documentation</a>. - </p> - </attribute> - <attribute name="SSLCARevocationPath" required="false"> - <p> - See <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcarevocationpath">the mod_ssl documentation</a>. - </p> - </attribute> - - </attributes> - - <p> - An example SSL Connector declaration can be: - <source> - <Connector port="443" maxHttpHeaderSize="8192" - maxThreads="50" enableLookups="false" disableUploadTimeout="true" - acceptCount="100" scheme="https" secure="true" - SSLEngine="on" - SSLCertificateFile="${catalina.base}/conf/localhost.crt" - SSLCertificateKeyFile="${catalina.base}/conf/localhost.key" /></source> - </p> - - </subsection> - - <subsection name="AJP"> - - <p> - The AJP connector uses a socket poller for keepalive, increasing - scalability of the server. As AJP is designed around a pool of persistent (or almost - persistent) connections, this will reduce significantly the amount of processing threads - needed by JBoss Web. Unlike the HTTP connector, the AJP connector cannot use sendfile to optimize - static file processing. - </p> - - <p> - The following attributes are supported in the AJP connector: - </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="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. A value of <code>127.0.0.1</code> - indicates that the Connector will only listen on the loopback - interface.</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="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 infinite (i.e. no timeout).</p> - </attribute> - - <attribute name="emptySessionPath" required="false"> - <p>If set to <code>true</code>, all paths for session cookies will be set - to <code>/</code>. This can be useful for portlet specification implementations, - but will greatly affect performance if many applications are accessed on a given - server by the client. - If not specified, this attribute is set to <code>false</code>.</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="firstReadTimeout" required="false"> - <p>The first read of a request will be made using the specified timeout. If no data is available - after the specified time, the socket will be placed in the poller. Setting this value to 0 will - increase scalability, but will have a minor impact on latency (see the related pollTime attribute). - The default value is 100 (100ms). Note: on Windows, the actual value of firstReadTimeout will - be 500 + the specified value.</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 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).</p> - </attribute> - - <attribute name="maxSavePostSize" required="false"> - <p>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. If not specified, this attribute is set - to 4096 (4 kilobytes).</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="pollTime" required="false"> - <p>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 5000 (5ms).</p> - </attribute> - - <attribute name="pollerSize" required="false"> - <p>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 768, corresponding to - 768 keepalive connections.</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>AJP/1.3</code> to use the AJP - handler.</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>.</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>.</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="request.registerRequests" required="false"> - <p>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.</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>".</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="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="tomcatAuthentication" required="false"> - <p>If set to <code>true</code>, the authetication will be done in Jboss Web. - Otherwise, the authenticated principal will be propagated from the native - webaserver and used for authorization in JBoss Web. - The default value is <code>true</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> - - <attribute name="useIPVHosts" required="false"> - <p>Set this attribute to <code>true</code> to cause JBoss Web to use - the ServerName passed by the native web server to determine the Host - to send the request to. The default value is <code>false</code>.</p> - </attribute> - - <attribute name="xpoweredBy" required="false"> - <p>Set this attribute to <code>true</code> to cause JBoss Web to advertise - support for the Srevlet specification using the header recommended in the - specification. The default value is <code>false</code>.</p> - </attribute> - - </attributes> - - </subsection> - - </section> - - -</body> -</document> Added: trunk/labs/jbossweb/xdocs/reference/conf.xml =================================================================== --- trunk/labs/jbossweb/xdocs/reference/conf.xml 2006-02-16 08:28:59 UTC (rev 2478) +++ trunk/labs/jbossweb/xdocs/reference/conf.xml 2006-02-16 08:50:16 UTC (rev 2479) @@ -0,0 +1,647 @@ +<?xml version="1.0"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="conf.html"> + + &project; + + <properties> + <author email="mla...@jb...">Mladen Turk</author> + <author email="rem...@jb...">Remy Maucherat</author> + <title>Configuration</title> + </properties> + +<body> + +<section name="Layout"> + <p>JBoss Web uses Embedded Tomcat. The Configuration model is the same as for the JBoss + Application Server. This gives you an easy transition from JBoss Web Server to full-blown + Application Server. + </p> + <figure src="/images/design/configlayout.png" name="Figure 5" text="Configuration Files"/> +</section> + + <section name="APR in JBoss Web"> + + <p> + JBoss Web uses the <a href="http://apr.apache.org/">Apache Portable Runtime</a> to + provide superior scalability, performance, and better integration with native server + technologies. The Apache Portable Runtime is a highly portable library that is at + the heart of Apache HTTP Server 2.x. APR has many uses, including access to advanced IO + functionality (such as sendfile, epoll and OpenSSL), OS level functionality (random number + generation, system status, etc), and native process handling (shared memory, NT + pipes and Unix sockets). + </p> + + <p> + These features allows making JBoss Web a general purpose webserver, will enable much better + integration with other native web technologies, and overall make Java much more viable as + a full fledged webserver platform rather than simply a backend focused technology. + </p> + + </section> + + + <section name="APR Connectors Configuration"> + + <p> + Connector configuration is done using Connector elements in the server.xml file. + </p> + + <subsection name="HTTP"> + + <p> + The HTTP connector uses sendfile for hadling large static files (all such + files will be sent ansychronously using high performance kernel level calls), and uses + a socket poller for keepalive, increasing scalability of the server. + </p> + + <p> + The following attributes are supported in the HTTP connector: + </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="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="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="compressableMimeType" 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="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="emptySessionPath" required="false"> + <p>If set to <code>true</code>, all paths for session cookies will be set + to <code>/</code>. This can be useful for portlet specification implementations, + but will greatly affect performance if many applications are accessed on a given + server by the client. + If not specified, this attribute is set to <code>false</code>.</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="firstReadTimeout" required="false"> + <p>The first read of a request will be made using the specified timeout. If no data is available + after the specified time, the socket will be placed in the poller. Setting this value to 0 will + increase scalability, but will have a minor impact on latency (see the related pollTime attribute). + The default value is 100 (100ms). Note: on Windows, the actual value of firstReadTimeout will + be 500 + the specified value.</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="maxPostSize" required="false"> + <p>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).</p> + </attribute> + + <attribute name="maxSavePostSize" required="false"> + <p>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. If not specified, this attribute is set to + 4096 (4 kilobytes).</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="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="pollTime" required="false"> + <p>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 5000 (5ms).</p> + </attribute> + + <attribute name="pollerSize" required="false"> + <p>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 768, corresponding to + 768 keepalive connections.</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>.</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>.</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="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>".</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="sendfileSize" required="false"> + <p>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 "synchonously" 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 256.</p> + </attribute> + + <attribute name="server" required="false"> + <p>The Server header for the http response. + Unless your paranoid, you won't need this feature. + </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> + + <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> + + <attribute name="useIPVHosts" required="false"> + <p>Set this attribute to <code>true</code> to cause JBoss Web to use + the IP address that the request was recieved on to determine the Host + to send the request to. The default value is <code>false</code>.</p> + </attribute> + + <attribute name="useSendfile" required="false"> + <p>Use kernel level sendfile for certain static files. The default value is true.</p> + </attribute> + + <attribute name="xpoweredBy" required="false"> + <p>Set this attribute to <code>true</code> to cause JBoss Web to advertise + support for the Servlet specification using the header recommended in the + specification. The default value is <code>false</code>.</p> + </attribute> + + </attributes> + + </subsection> + + <subsection name="HTTPS"> + + <p> + 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. + </p> + + <p> + 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 <a href="http://www.openssl.org">Official OpenSSL + website</a>). The SSL specific attributes for the connector are: + </p> + + <attributes> + + <attribute name="SSLEngine" required="false"> + <p> + Name of the SSLEngine to use. off: Do not use SSL, on: Use SSL but no specific ENGINE. + The default value is off. + </p> + </attribute> + <attribute name="SSLProtocol" required="false"> + <p> + Protocol which may be used for communicating with clients. The default is "all", with + other acceptable values being "SSLv2", "SSLv3", "TLSv1", and "SSLv2+SSLv3". + </p> + </attribute> + <attribute name="SSLCipherSuite" required="false"> + <p> + 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). + </p> + </attribute> + <attribute name="SSLCertificateFile" required="true"> + <p> + Name of the file that contains the server certificate. The format is PEM-encoded. + </p> + </attribute> + <attribute name="SSLCertificateKeyFile" required="false"> + <p> + 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). + </p> + </attribute> + <attribute name="SSLPassword" required="false"> + <p> + Pass phrase for the encrypted private key. If "SSLPassword" is not provided, the callback fonction + should prompt for the pass phrase. + </p> + </attribute> + <attribute name="SSLVerifyClient" required="false"> + <p> + 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". + </p> + </attribute> + <attribute name="SSLVerifyDepth" required="false"> + <p> + Maximum verification depth for client certificates. The default is "10". + </p> + </attribute> + <attribute name="SSLCACertificateFile" required="false"> + <p> + See <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcacertificatefile">the mod_ssl documentation</a>. + </p> + </attribute> + <attribute name="SSLCACertificatePath" required="false"> + <p> + See <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcacertificatepath">the mod_ssl documentation</a>. + </p> + </attribute> + <attribute name="SSLCertificateChainFile" required="false"> + <p> + See <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcertificatechainfile">the mod_ssl documentation</a>. + </p> + </attribute> + <attribute name="SSLCARevocationFile" required="false"> + <p> + See <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcarevocationfile">the mod_ssl documentation</a>. + </p> + </attribute> + <attribute name="SSLCARevocationPath" required="false"> + <p> + See <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcarevocationpath">the mod_ssl documentation</a>. + </p> + </attribute> + + </attributes> + + <p> + An example SSL Connector declaration can be: + <source> + <Connector port="443" maxHttpHeaderSize="8192" + maxThreads="50" enableLookups="false" disableUploadTimeout="true" + acceptCount="100" scheme="https" secure="true" + SSLEngine="on" + SSLCertificateFile="${catalina.base}/conf/localhost.crt" + SSLCertificateKeyFile="${catalina.base}/conf/localhost.key" /></source> + </p> + + </subsection> + + <subsection name="AJP"> + + <p> + The AJP connector uses a socket poller for keepalive, increasing + scalability of the server. As AJP is designed around a pool of persistent (or almost + persistent) connections, this will reduce significantly the amount of processing threads + needed by JBoss Web. Unlike the HTTP connector, the AJP connector cannot use sendfile to optimize + static file processing. + </p> + + <p> + The following attributes are supported in the AJP connector: + </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="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. A value of <code>127.0.0.1</code> + indicates that the Connector will only listen on the loopback + interface.</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="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 infinite (i.e. no timeout).</p> + </attribute> + + <attribute name="emptySessionPath" required="false"> + <p>If set to <code>true</code>, all paths for session cookies will be set + to <code>/</code>. This can be useful for portlet specification implementations, + but will greatly affect performance if many applications are accessed on a given + server by the client. + If not specified, this attribute is set to <code>false</code>.</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="firstReadTimeout" required="false"> + <p>The first read of a request will be made using the specified timeout. If no data is available + after the specified time, the socket will be placed in the poller. Setting this value to 0 will + increase scalability, but will have a minor impact on latency (see the related pollTime attribute). + The default value is 100 (100ms). Note: on Windows, the actual value of firstReadTimeout will + be 500 + the specified value.</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 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).</p> + </attribute> + + <attribute name="maxSavePostSize" required="false"> + <p>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. If not specified, this attribute is set + to 4096 (4 kilobytes).</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="pollTime" required="false"> + <p>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 5000 (5ms).</p> + </attribute> + + <attribute name="pollerSize" required="false"> + <p>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 768, corresponding to + 768 keepalive connections.</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>AJP/1.3</code> to use the AJP + handler.</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>.</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>.</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="request.registerRequests" required="false"> + <p>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.</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>".</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="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="tomcatAuthentication" required="false"> + <p>If set to <code>true</code>, the authetication will be done in Jboss Web. + Otherwise, the authenticated principal will be propagated from the native + webaserver and used for authorization in JBoss Web. + The default value is <code>true</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 se... [truncated message content] |