274 lines
22 KiB
HTML
274 lines
22 KiB
HTML
|
<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - Apache Portable Runtime and Tomcat</title><meta name="author" value="Remy Maucherat"><meta name="email" value=""></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="./../images/tomcat.gif" align="right" alt="
|
||
|
The Apache Tomcat Servlet/JSP Container
|
||
|
" border="0"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%" cellspacing="4"><tr><td align="left" valign="top"><h1>Apache Tomcat 6.0</h1><h2>Apache Portable Runtime and Tomcat</h2></td><td align="right" valign="top" nowrap="true"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
||
|
<p>
|
||
|
Tomcat can use 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 Tomcat 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>
|
||
|
|
||
|
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Installation"><strong>Installation</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
||
|
<p>
|
||
|
APR support requires three main native components to be installed:
|
||
|
<ul>
|
||
|
<li>APR library</li>
|
||
|
<li>JNI wrappers for APR used by Tomcat (libtcnative)</li>
|
||
|
<li>OpenSSL libraries</li>
|
||
|
</ul>
|
||
|
</p>
|
||
|
|
||
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Windows"><strong>Windows</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
||
|
<p>
|
||
|
Windows binaries are provided for tcnative-1, which is a statically compiled .dll which includes
|
||
|
OpenSSL and APR. It can be downloaded from <a href="http://tomcat.heanet.ie/native/">here</a>
|
||
|
as 32bit or AMD x86-64 binaries.
|
||
|
In security conscious production environments, it is recommended to use separate shared dlls
|
||
|
for OpenSSL, APR, and libtcnative-1, and update them as needed according to security bulletins.
|
||
|
Windows OpenSSL binaries are linked from the <a href="http://www.openssl.org">Official OpenSSL
|
||
|
website</a> (see related/binaries).
|
||
|
</p>
|
||
|
|
||
|
</blockquote></td></tr></table>
|
||
|
|
||
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Linux"><strong>Linux</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
||
|
<p>
|
||
|
Most Linux distributions will ship packages for APR and OpenSSL. The JNI wrapper (libtcnative) will
|
||
|
then have to be compiled. It depends on APR, OpenSSL, and the Java headers.
|
||
|
</p>
|
||
|
|
||
|
<p>
|
||
|
Requirements:
|
||
|
<ul>
|
||
|
<li>APR 1.2+ development headers (libapr1-dev package)</li>
|
||
|
<li>OpenSSL 0.9.7+ development headers (libssl-dev package)</li>
|
||
|
<li>JNI headers from Java compatible JDK 1.4+</li>
|
||
|
<li>GNU development environment (gcc, make)</li>
|
||
|
</ul>
|
||
|
</p>
|
||
|
|
||
|
<p>
|
||
|
The wrapper library sources are located in the Tomcat binary bundle, in the
|
||
|
<code>bin/tomcat-native.tar.gz</code> archive.
|
||
|
Once the build environment is installed and the source archive is extracted, the wrapper library
|
||
|
can be compiled using (from the folder containing the configure script):
|
||
|
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>./configure && make && make install</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
|
||
|
</p>
|
||
|
|
||
|
</blockquote></td></tr></table>
|
||
|
|
||
|
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="APR Components"><strong>APR Components</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
||
|
<p>
|
||
|
Once the libraries are properly installed and available to Java (if loading fails, the library path
|
||
|
will be displayed), the Tomcat connectors will automatically use APR. Configuration of the connectors
|
||
|
is similar to the regular connectors, but have a few extra attributes which are used to configure
|
||
|
APR components. Note that the defaults should be well tuned for most use cases, and additional
|
||
|
tweaking shouldn't be required.
|
||
|
</p>
|
||
|
|
||
|
<p>
|
||
|
When APR is enabled, the following features are also enabled in Tomcat:
|
||
|
<ul>
|
||
|
<li>Secure session ID generation by default on all platforms (platforms other than Linux required
|
||
|
random number generation using a configured entropy)</li>
|
||
|
<li>OS level statistics on memory usage and CPU usage by the Tomcat process are displayed by
|
||
|
the status servlet</li>
|
||
|
</ul>
|
||
|
</p>
|
||
|
|
||
|
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="APR Lifecycle Listener Configuration"><strong>APR Lifecycle Listener Configuration</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="AprLifecycleListener"><strong>AprLifecycleListener</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
<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 <b>on</b>.
|
||
|
This initializes the native SSL engine, then enable the use of this engine in the connector
|
||
|
using the <code>SSLEnabled</code> attribute. Example:
|
||
|
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
<Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
|
||
|
</pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
|
||
|
</p>
|
||
|
<p>See the <a href="http://www.openssl.org">Official OpenSSL
|
||
|
website</a> for more details on SSL hardware engines and manufacturers.
|
||
|
</p>
|
||
|
</attribute>
|
||
|
</blockquote></td></tr></table>
|
||
|
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="APR Connectors Configuration"><strong>APR Connectors Configuration</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
||
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="HTTP"><strong>HTTP</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
||
|
<p>
|
||
|
When APR is enabled, the HTTP connector will use sendfile for hadling large static files (all such
|
||
|
files will be sent ansychronously using high performance kernel level calls), and will use
|
||
|
a socket poller for keepalive, increasing scalability of the server.
|
||
|
</p>
|
||
|
|
||
|
<p>
|
||
|
The following attributes are supported in the HTTP APR connector in addition to the ones supported
|
||
|
in the regular HTTP connector:
|
||
|
</p>
|
||
|
|
||
|
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>keepAliveTimeout</code></td><td align="left" valign="center">
|
||
|
<p>The number of milliseconds this <strong>Connector</strong> 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.</p>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>pollTime</code></td><td align="left" valign="center">
|
||
|
<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 2000 (5ms).</p>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>pollerSize</code></td><td align="left" valign="center">
|
||
|
<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 8192, corresponding to
|
||
|
8192 keepalive connections.</p>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>useSendfile</code></td><td align="left" valign="center">
|
||
|
<p>Use kernel level sendfile for certain static files. The default value is true.</p>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>sendfileSize</code></td><td align="left" valign="center">
|
||
|
<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 1024.</p>
|
||
|
</td></tr></table>
|
||
|
|
||
|
</blockquote></td></tr></table>
|
||
|
|
||
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="HTTPS"><strong>HTTPS</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
||
|
<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>
|
||
|
|
||
|
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>SSLEnabled</code></td><td align="left" valign="center">
|
||
|
<p>
|
||
|
Enable SSL on the socket, default value is false. Set this value to true
|
||
|
to enable SSL handshake/encryption/decryption in the APR connector.
|
||
|
</p>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>SSLProtocol</code></td><td align="left" valign="center">
|
||
|
<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>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>SSLCipherSuite</code></td><td align="left" valign="center">
|
||
|
<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>
|
||
|
</td></tr><tr><td align="left" valign="center"><strong><code>SSLCertificateFile</code></strong></td><td align="left" valign="center">
|
||
|
<p>
|
||
|
Name of the file that contains the server certificate. The format is PEM-encoded.
|
||
|
</p>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>SSLCertificateKeyFile</code></td><td align="left" valign="center">
|
||
|
<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>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>SSLPassword</code></td><td align="left" valign="center">
|
||
|
<p>
|
||
|
Pass phrase for the encrypted private key. If "SSLPassword" is not provided, the callback fonction
|
||
|
should prompt for the pass phrase.
|
||
|
</p>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>SSLVerifyClient</code></td><td align="left" valign="center">
|
||
|
<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>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>SSLVerifyDepth</code></td><td align="left" valign="center">
|
||
|
<p>
|
||
|
Maximum verification depth for client certificates. The default is "10".
|
||
|
</p>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>SSLCACertificateFile</code></td><td align="left" valign="center">
|
||
|
<p>
|
||
|
See <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcacertificatefile">the mod_ssl documentation</a>.
|
||
|
</p>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>SSLCACertificatePath</code></td><td align="left" valign="center">
|
||
|
<p>
|
||
|
See <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcacertificatepath">the mod_ssl documentation</a>.
|
||
|
</p>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>SSLCertificateChainFile</code></td><td align="left" valign="center">
|
||
|
<p>
|
||
|
See <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcertificatechainfile">the mod_ssl documentation</a>.
|
||
|
</p>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>SSLCARevocationFile</code></td><td align="left" valign="center">
|
||
|
<p>
|
||
|
See <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcarevocationfile">the mod_ssl documentation</a>.
|
||
|
</p>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>SSLCARevocationPath</code></td><td align="left" valign="center">
|
||
|
<p>
|
||
|
See <a href="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html#sslcarevocationpath">the mod_ssl documentation</a>.
|
||
|
</p>
|
||
|
</td></tr></table>
|
||
|
|
||
|
<p>
|
||
|
An example SSL Connector declaration can be:
|
||
|
<div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
|
||
|
<Connector port="443" maxHttpHeaderSize="8192"
|
||
|
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
|
||
|
enableLookups="false" disableUploadTimeout="true"
|
||
|
acceptCount="100" scheme="https" secure="true"
|
||
|
SSLEnabled="true"
|
||
|
SSLCertificateFile="${catalina.base}/conf/localhost.crt"
|
||
|
SSLCertificateKeyFile="${catalina.base}/conf/localhost.key" /></pre></td><td bgcolor="#023264" width="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="./../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
|
||
|
</p>
|
||
|
|
||
|
</blockquote></td></tr></table>
|
||
|
|
||
|
<table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="AJP"><strong>AJP</strong></a></font></td></tr><tr><td><blockquote>
|
||
|
|
||
|
<p>
|
||
|
When APR is enabled, the AJP connector will use 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 Tomcat. 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 APR connector in addition to the ones supported
|
||
|
in the regular AJP connector:
|
||
|
</p>
|
||
|
|
||
|
<table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code>pollTime</code></td><td align="left" valign="center">
|
||
|
<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 2000 (5ms).</p>
|
||
|
</td></tr><tr><td align="left" valign="center"><code>pollerSize</code></td><td align="left" valign="center">
|
||
|
<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 8192, corresponding to
|
||
|
8192 keepalive connections.</p>
|
||
|
</td></tr></table>
|
||
|
|
||
|
</blockquote></td></tr></table>
|
||
|
|
||
|
</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade="noshade" size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
|
||
|
Copyright © 1999-2006, Apache Software Foundation
|
||
|
</em></font></div></td></tr></table></body></html>
|