Gitiles
Code Review Sign In
source.supwisdom.com / UniIdentify / tomcat / 6266f996613ae5631b7288523f895b36e30fe5af / . / tomcat-cas / webapps / docs / apr.html
blob: 90eb2b9343095756f5985c1560d12b8f72e41971 [file] [log] [blame]
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 (7.0.77) - Apache Portable Runtime (APR) based Native library for Tomcat</title><meta name="author" content="Remy Maucherat"><style type="text/css" media="print">
2 .noPrint {display: none;}
3 td#mainBody {width: 100%;}
4</style><style type="text/css">
5code {background-color:rgb(224,255,255);padding:0 0.1em;}
6code.attributeName, code.propertyName {background-color:transparent;}
7
8
9table {
10 border-collapse: collapse;
11 text-align: left;
12}
13table *:not(table) {
14 /* Prevent border-collapsing for table child elements like <div> */
15 border-collapse: separate;
16}
17
18th {
19 text-align: left;
20}
21
22
23div.codeBox pre code, code.attributeName, code.propertyName, code.noHighlight, .noHighlight code {
24 background-color: transparent;
25}
26div.codeBox {
27 overflow: auto;
28 margin: 1em 0;
29}
30div.codeBox pre {
31 margin: 0;
32 padding: 4px;
33 border: 1px solid #999;
34 border-radius: 5px;
35 background-color: #eff8ff;
36 display: table; /* To prevent <pre>s from taking the complete available width. */
37 /*
38 When it is officially supported, use the following CSS instead of display: table
39 to prevent big <pre>s from exceeding the browser window:
40 max-width: available;
41 width: min-content;
42 */
43}
44
45div.codeBox pre.wrap {
46 white-space: pre-wrap;
47}
48
49
50table.defaultTable tr, table.detail-table tr {
51 border: 1px solid #CCC;
52}
53
54table.defaultTable tr:nth-child(even), table.detail-table tr:nth-child(even) {
55 background-color: #FAFBFF;
56}
57
58table.defaultTable tr:nth-child(odd), table.detail-table tr:nth-child(odd) {
59 background-color: #EEEFFF;
60}
61
62table.defaultTable th, table.detail-table th {
63 background-color: #88b;
64 color: #fff;
65}
66
67table.defaultTable th, table.defaultTable td, table.detail-table th, table.detail-table td {
68 padding: 5px 8px;
69}
70
71
72p.notice {
73 border: 1px solid rgb(255, 0, 0);
74 background-color: rgb(238, 238, 238);
75 color: rgb(0, 51, 102);
76 padding: 0.5em;
77 margin: 1em 2em 1em 1em;
78}
79</style></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="
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]80 The Apache Tomcat Servlet/JSP Container
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]81 " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.77, Mar 28 2017</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="./images/asf-logo.svg" align="right" alt="Apache Logo" border="0" style="width: 266px;height: 83px;"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL/TLS</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">16) MBeans Descriptors</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.2 Javadocs</a></li><li><a href="elapi/index.html">EL 2.2 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>Apache Portable Runtime (APR) based Native library for Tomcat</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
82<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Installation">Installation</a><ol><li><a href="#Windows">Windows</a></li><li><a href="#Linux">Linux</a></li></ol></li><li><a href="#APR_Components">APR Components</a></li><li><a href="#APR_Lifecycle_Listener_Configuration">APR Lifecycle Listener Configuration</a><ol><li><a href="#AprLifecycleListener">AprLifecycleListener</a></li></ol></li><li><a href="#APR_Connectors_Configuration">APR Connectors Configuration</a><ol><li><a href="#HTTP/HTTPS">HTTP/HTTPS</a></li><li><a href="#AJP">AJP</a></li></ol></li></ul>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]83</blockquote></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>
84
85 <p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]86 Tomcat can use the <a href="http://apr.apache.org/">Apache Portable Runtime</a> to
87 provide superior scalability, performance, and better integration with native server
88 technologies. The Apache Portable Runtime is a highly portable library that is at
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]89 the heart of Apache HTTP Server 2.x. APR has many uses, including access to advanced IO
90 functionality (such as sendfile, epoll and OpenSSL), OS level functionality (random number
91 generation, system status, etc), and native process handling (shared memory, NT
92 pipes and Unix sockets).
93 </p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]94
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]95 <p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]96 These features allows making Tomcat a general purpose webserver, will enable much better
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]97 integration with other native web technologies, and overall make Java much more viable as
98 a full fledged webserver platform rather than simply a backend focused technology.
99 </p>
100
101 </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>
102
103 <p>
104 APR support requires three main native components to be installed:
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]105 </p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]106 <ul>
107 <li>APR library</li>
108 <li>JNI wrappers for APR used by Tomcat (libtcnative)</li>
109 <li>OpenSSL libraries</li>
110 </ul>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]111
112 <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>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]113
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]114 <p>
115 Windows binaries are provided for tcnative-1, which is a statically compiled .dll which includes
116 OpenSSL and APR. It can be downloaded from <a href="http://tomcat.apache.org/download-native.cgi">here</a>
117 as 32bit or AMD x86-64 binaries.
118 In security conscious production environments, it is recommended to use separate shared dlls
119 for OpenSSL, APR, and libtcnative-1, and update them as needed according to security bulletins.
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]120 Windows OpenSSL binaries are linked from the <a href="http://www.openssl.org">Official OpenSSL
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]121 website</a> (see related/binaries).
122 </p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]123
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]124 </blockquote></td></tr></table>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]125
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]126 <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>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]127
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]128 <p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]129 Most Linux distributions will ship packages for APR and OpenSSL. The JNI wrapper (libtcnative) will
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]130 then have to be compiled. It depends on APR, OpenSSL, and the Java headers.
131 </p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]132
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]133 <p>
134 Requirements:
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]135 </p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]136 <ul>
137 <li>APR 1.2+ development headers (libapr1-dev package)</li>
138 <li>OpenSSL 0.9.7+ development headers (libssl-dev package)</li>
139 <li>JNI headers from Java compatible JDK 1.4+</li>
140 <li>GNU development environment (gcc, make)</li>
141 </ul>
142
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]143 <p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]144 The wrapper library sources are located in the Tomcat binary bundle, in the
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]145 <code>bin/tomcat-native.tar.gz</code> archive.
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]146 Once the build environment is installed and the source archive is extracted, the wrapper library
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]147 can be compiled using (from the folder containing the configure script):
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]148 </p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]149 <div class="codeBox"><pre><code>./configure &amp;&amp; make &amp;&amp; make install</code></pre></div>
150
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]151 </blockquote></td></tr></table>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]152
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]153 </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"><!--()--></a><a name="APR_Components"><strong>APR Components</strong></a></font></td></tr><tr><td><blockquote>
154
155 <p>
156 Once the libraries are properly installed and available to Java (if loading fails, the library path
157 will be displayed), the Tomcat connectors will automatically use APR. Configuration of the connectors
158 is similar to the regular connectors, but have a few extra attributes which are used to configure
159 APR components. Note that the defaults should be well tuned for most use cases, and additional
160 tweaking shouldn't be required.
161 </p>
162
163 <p>
164 When APR is enabled, the following features are also enabled in Tomcat:
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]165 </p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]166 <ul>
167 <li>Secure session ID generation by default on all platforms (platforms other than Linux required
168 random number generation using a configured entropy)</li>
169 <li>OS level statistics on memory usage and CPU usage by the Tomcat process are displayed by
170 the status servlet</li>
171 </ul>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]172
173 </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"><!--()--></a><a name="APR_Lifecycle_Listener_Configuration"><strong>APR Lifecycle Listener Configuration</strong></a></font></td></tr><tr><td><blockquote>
174 <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>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]175 <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 class="attributeName">SSLEngine</code></td><td align="left" valign="center">
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]176 <p>
177 Name of the SSLEngine to use. off: Do not use SSL, on: Use SSL but no specific ENGINE.
178 The default value is <b>on</b>.
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]179 This initializes the native SSL engine, then enable the use of this engine in the connector
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]180 using the <code>SSLEnabled</code> attribute. Example:
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]181 </p>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]182 <div class="codeBox"><pre><code>&lt;Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" /&gt;</code></pre></div>
183
184 <p>See the <a href="http://www.openssl.org">Official OpenSSL
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]185 website</a> for more details on SSL hardware engines and manufacturers.
186 </p>
Hongqing Liu71898292014-10-15 13:31:32 +0800[diff] [blame]187 </td></tr></table>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]188 </blockquote></td></tr></table>
189 </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"><!--()--></a><a name="APR_Connectors_Configuration"><strong>APR Connectors Configuration</strong></a></font></td></tr><tr><td><blockquote>
190
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]191 <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="HTTP/HTTPS"><strong>HTTP/HTTPS</strong></a></font></td></tr><tr><td><blockquote>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]192
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]193 <p>For HTTP configuration, see the <a href="config/http.html">HTTP</a>
194 connector configuration documentation.</p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]195
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]196 <p>For HTTPS configuration, see the
197 <a href="config/http.html#SSL_Support">HTTPS</a> connector configuration
198 documentation.</p>
199
200 <p>An example SSL Connector declaration is:</p>
201 <div class="codeBox"><pre><code>&lt;Connector port="443" maxHttpHeaderSize="8192"
202 maxThreads="150"
203 enableLookups="false" disableUploadTimeout="true"
204 acceptCount="100" scheme="https" secure="true"
205 SSLEnabled="true"
206 SSLCertificateFile="${catalina.base}/conf/localhost.crt"
207 SSLCertificateKeyFile="${catalina.base}/conf/localhost.key" /&gt;</code></pre></div>
208
209
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]210 </blockquote></td></tr></table>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]211
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]212 <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>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]213
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]214 <p>For AJP configuration, see the <a href="config/ajp.html">AJP</a>
215 connector configuration documentation.</p>
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]216
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]217 </blockquote></td></tr></table>
刘洪青6266f992017-05-15 21:21:03 +0800[diff] [blame^]218
219 </blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
220 on improving documentation for Apache Tomcat.<br><br>
221 If you have trouble and need help, read
222 <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
223 and ask your question on the tomcat-users
224 <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
225 Do not ask such questions here. This is not a Q&amp;A section.<br><br>
226 The Apache Comments System is explained <a href="./comments.html">here</a>.
227 Comments may be removed by our moderators if they are either
228 implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
229 var comments_shortname = 'tomcat';
230 var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/apr.html';
231 (function(w, d) {
232 if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
233 d.write('<div id="comments_thread"><\/div>');
234 var s = d.createElement('script');
235 s.type = 'text/javascript';
236 s.async = true;
237 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
238 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
239 }
240 else {
241 d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
242 }
243 })(window, document);
244 //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
245 Copyright &copy; 1999-2017, Apache Software Foundation
Hongqing Liufd5ee812014-05-10 16:32:51 +0800[diff] [blame]246 </em></font></div></td></tr></table></body></html>