You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2012/03/31 20:52:23 UTC
svn commit: r1307873 [3/22] - in /tomcat/site/trunk/docs: connectors-doc/
connectors-doc/ajp/ connectors-doc/ajp/printer/
connectors-doc/generic_howto/ connectors-doc/generic_howto/printer/
connectors-doc/images/ connectors-doc/miscellaneous/ connector...
Added: tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/proxy.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/proxy.html?rev=1307873&view=auto
==============================================================================
--- tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/proxy.html (added)
+++ tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/proxy.html Sat Mar 31 18:52:20 2012
@@ -0,0 +1,312 @@
+<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>The Apache Tomcat Connector - Generic HowTo - Reverse Proxy HowTo</title><meta name="author" value="Rainer Jung"><meta name="email" value="rjung@apache.org"><link href="../../style.css" type="text/css" rel="stylesheet"></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="4"><!--PAGE HEADER--><tr><td colspan="2"><!--TOMCAT LOGO--><a href="http://tomcat.apache.org/"><img src="../../images/tomcat.gif" align="left" alt="Apache Tomcat" border="0"></a><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="http://www.apache.org/images/asf-logo.gif" align="right" alt=" :: Apache Software Foundation" border="0"></a></td></tr><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%" cellsp
acing="4"><tr><td align="left" valign="top"><h1>The Apache Tomcat Connector - Generic HowTo</h1><h2>Reverse Proxy HowTo</h2></td><td align="right" valign="top" nowrap="true"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0" alt=" "></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+<br>
+<p>The Apache module mod_jk and its ISAPI and NSAPI variants connect
+a web server to a backend (typically Tomcat) using the AJP protocol.
+The web server receives an HTTP(S) request and the module forwards
+the request to the backend. This function is usually called a gateway
+or a proxy, in the context of HTTP it is called a reverse proxy.
+</p>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Typical Problems"><strong>Typical Problems</strong></a></font></td></tr><tr><td><blockquote>
+<br>
+<p>A reverse proxy is not totally transparent to the application on
+the backend. For instance the host name and port the original client
+(e.g. browser) needs to talk to belong to the web server and not to the
+backend, so the reverse proxy talks to a different host name and port.
+When the application on the backend returns content including
+self-referential URLs using its own backend address and port, the
+client will usually not be able to use these URLs.
+</p>
+<p>Another example is the client IP address, which for the web server is the
+source IP of the incoming connection, whereas for the backend the
+connection always comes from the web server. This can be a problem, when
+the client IP is used by the backend application e.g. for security reasons.
+</p>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="AJP as a Solution"><strong>AJP as a Solution</strong></a></font></td></tr><tr><td><blockquote>
+<br>
+<p>Most of these problems are automatically handled by the AJP protocol
+and the AJP connectors of the backend. The AJP protocol transports
+this communication metadata and the backend connector presents this
+metadata whenever the application asks for it using Servlet API methods.
+</p>
+<p>The following list contains the communication metadata handled by AJP
+and the ServletRequest/HttpServletRequest API calls which can be used to retrieve them:
+<ul>
+<li>local name: <b class="code">getLocalName()</b> and <b class="code">getLocalAddr</b>.
+This is also equal to <b class="code">getServerName()</b>, unless a <b class="code">Host</b> header
+is contained in the request. In this case the server name is taken from that header.
+</li>
+<li>local port: <b class="code">getLocalPort()</b>
+This is also equal to <b class="code">getServerPort()</b>, unless a <b class="code">Host</b> header
+is contained in the request. In this case the server port is taken from that header
+if it contains an explicit port, or is equal to the default port of the scheme used.
+</li>
+<li>client address: <b class="code">getRemoteAddr()</b>
+</li>
+<li>client port: <b class="code">getRemotePort()</b>
+The remote port was initially not supported. It is available when using mod_jk 1.2.32
+with Apache or IIS (not for the NSAPI plugin) together with Tomcat version at least
+5.5.28, 6.0.20 or 7.0.0. For older versions, <b class="code">getRemotePort()</b>
+will incorrectly return 0 or -1. As a workaround you can forward the remote port by setting
+<b class="code">JkEnvVar REMOTE_PORT</b> and then either using
+<b class="code">request.getAttribute("REMOTE_PORT")</b> instead of <b class="code">getRemotePort()</b>
+or wrapping the request using a filter and overriding <b class="code">getRemotePort()</b> with
+<b class="code">request.getAttribute("REMOTE_PORT")</b>.
+</li>
+<li>client host: <b class="code">getRemoteHost()</b>
+</li>
+<li>authentication type: <b class="code">getAuthType()</b>
+</li>
+<li>remote user: <b class="code">getRemoteUser()</b>,
+if <b class="code">tomcatAuthentication="false"</b>
+</li>
+<li>protocol: <b class="code">getProtocol()</b>
+</li>
+<li>HTTP method: <b class="code">getMethod()</b>
+</li>
+<li>URI: <b class="code">getRequestURI()</b>
+</li>
+<li>HTTPS used: <b class="code">isSecure()</b>, <b class="code">getScheme()</b>
+</li>
+<li>query string: <b class="code">getQueryString()</b>
+</li>
+</ul>
+The following additional SSL-related data will be made available by Apache and forwarded by mod_jk only
+if you set <b class="code">SSLOptions +StdEnvVars</b>. For the certificate information you also need
+to set <b class="code">SSLOptions +ExportCertData</b>.
+<ul>
+<li>SSL cipher: <b class="code">getAttribute(javax.servlet.request.cipher_suite)</b>
+</li>
+<li>SSL key size: <b class="code">getAttribute(javax.servlet.request.key_size)</b>.
+Can be disabled using <b class="code">JkOptions -ForwardKeySize</b>.
+</li>
+<li>SSL client certificate: <b class="code">getAttribute(javax.servlet.request.X509Certificate)</b>.
+If you want the whole certificate chain, then you need to also set <b class="code">JkOptions ForwardSSLCertChain</b>.
+It is likely, that in this case you also need to adjust the maximal AJP packet size
+using the worker attribute <a href="../../reference/workers.html">max_packet_size</a>.
+</li>
+<li>SSL session ID: <b class="code">getAttribute(javax.servlet.request.ssl_session)</b>.
+This is for Tomcat, it has not yet been standardized.
+</li>
+</ul>
+</p>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Fine Tuning"><strong>Fine Tuning</strong></a></font></td></tr><tr><td><blockquote>
+<br>
+<p>In some situations this is not enough though. Assume there is another
+less clever reverse proxy in front of your web server, for instance an
+HTTP load balancer or similar device which also serves as an SSL accelerator.
+</p>
+<p>Then you are sure that all your clients use HTTPS, but your web server doesn't
+know about that. All it can see is requests coming from the accelerator using
+plain HTTP.
+</p>
+<p>Another example would be a simple reverse proxy in front of your web server,
+so that the client IP address that your web server sees is always the IP address
+of this reverse proxy, and not of the original client. Often such reverse proxies
+generate an additional HTTP header, like <b class="code">X-Forwareded-for</b> which
+contains the original client IP address (or a list of IP addresses, if there are
+more cascading reverse proxies in front). It would be nice, if we could use the
+content of such a header as the client IP address to pass to the backend.
+</p>
+<p>So we might need to manipulate some of the data that AJP sends to the backend.
+When using mod_jk inside Apache httpd you can use several httpd environment
+variables to let mod_jk know, which data it should forward. These environment variables
+can be set by the httpd directives SetEnv or SetEnvIf, but also in a very flexible
+way using mod_rewrite (since httpd 2.x it can not only test against environment
+variables, but also set them).
+</p>
+<p>The following list contains all environment variables mod_jk checks, before
+sending data to the backend:
+<ul>
+<li>JK_LOCAL_NAME: the local name
+</li>
+<li>JK_LOCAL_PORT: the local port
+</li>
+<li>JK_REMOTE_HOST: the client host
+</li>
+<li>JK_REMOTE_ADDR: the client address
+</li>
+<li>JK_AUTH_TYPE: the authentication type
+</li>
+<li>JK_REMOTE_USER: the remote user
+</li>
+<li>HTTPS: On (case-insensitive) to indicate, that HTTPS is used
+</li>
+<li>SSL_CIPHER: the SSL cipher
+</li>
+<li>SSL_CIPHER_USEKEYSIZE: the SSL key size
+</li>
+<li>SSL_CLIENT_CERT: the SSL client certificate
+</li>
+<li>SSL_CLIENT_CERT_CHAIN_: prefix of variable names, containing
+the client cerificate chain
+</li>
+<li>SSL_SESSION_ID: the SSL session ID
+</li>
+</ul>
+</p>
+<p>Remember: in general you don't need to set them. The module retrieves the data automatically
+from the web server. Only in case you want to change this data, you can overwrite it by
+using these variables.
+</p>
+<p>Some of these variables might also be used by other web server modules. All
+variables whose name does not begin with "JK" are set directly by Apache httpd.
+If you want to change the data, but do not want to negatively influence the behaviour
+of other modules, you can change the names of all variables mod_jk uses to private ones.
+For the details see the <a href="../../reference/apache.html">Apache reference</a> page.
+</p>
+<p>All variables, that are not SSL-related have only been introduced in version 1.2.27.
+</p>
+<p>Finally there is a shortcut to forward the local IP of the web server as the remote IP.
+This can be useful, e.g. when using the Tomcat remote address valve for allowing connections
+only from registered Apache web servers. This feature is activated by setting
+<b class="code">JkOptions ForwardLocalAddress</b>.
+</p>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Tomcat AJP Connector Settings"><strong>Tomcat AJP Connector Settings</strong></a></font></td></tr><tr><td><blockquote>
+<br>
+<p>As an alternative to using the environment variables described in the previous section
+(which do only exist when using Apache httpd), you can also configure Tomcat to overwrite
+some of the communications data forwarded by mod_jk. The AJP connector in Tomcat's <b class="code">server.xml</b>
+allows to set the <a href="http://tomcat.apache.org/tomcat-6.0-doc/config/ajp.html#Attributes">following properties</a>:
+<ul>
+<li>proxyName: server name as returned by <b class="code">getServerName()</b>
+</li>
+<li>proxyPort: server port as returned by <b class="code">getServerPort()</b>
+</li>
+<li>scheme: protocol scheme as returned by <b class="code">getScheme()</b>
+</li>
+<li>secure: set to "true", if you wish <b class="code">isSecure()</b> to return "true".
+</li>
+</ul>
+Remember: in general you don't need to set those. AJP automatically handles all cases
+where the web server running mod_jk knows the right data.
+</p>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="URL Handling"><strong>URL Handling</strong></a></font></td></tr><tr><td><blockquote>
+<br>
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="URL Rewriting"><strong>URL Rewriting</strong></a></font></td></tr><tr><td><blockquote>
+<p>Sometimes one want to change path components of the URLs under which an application
+is available. Especially if a web application is deployed as some context, say <b class="code">/myapp</b>,
+marketing prefers short URLs, so want the application to be directly available under
+<b class="code">http://www.mycompany.com/</b>. Although you can deploy the application as the so-called
+ROOT context, which will be directly available at "/", admins often prefer not to use
+the ROOT context, e.g. because only one application can be the root context (per host).
+</p>
+<p>The procedure to change the URLs in the reverse proxy is tedious, because often
+an application produces self-referential URLs, which then include the path components
+which you tried to hide to the outside world. Nevertheless, if you absolutely need to do it,
+here are the steps.
+</p>
+<p>Case A: You need to make the application available at a simple URL, but it is OK, if
+users proceed using the more complex URLs, as long as they don't have to type them in.
+That's the easy case, and if this suffices to you, you're lucky. Use a simply RedirectMatch
+for Apache httpd:
+</p>
+<div class="example"><pre>
+RedirectMatch ^/$ http://www.mycompany.com/myapp/
+</pre></div>
+<p>Your application will then be available under <b class="code">http://www.mycompany.com/</b>,
+and each visitor will be immediately redirected to the real URL
+<b class="code">http://www.mycompany.com/myapp/</b>
+</p>
+<p>Case B: You need to hide path components for all requests going to the application.
+Here's the recipe for the case, where you want to hide the first path component
+<b class="code">/myapp</b>. More complex manipulations are left as an exercise to the reader.
+First the solution for the case of Apache httpd:
+</p>
+<p>1. Use <a href="http://httpd.apache.org/docs/2.2/mod/mod_rewrite.html"><b class="code">mod_rewrite</b></a>
+to add <b class="code">/myapp</b> to all requests before forwarding to the backend:
+</p>
+<div class="example"><pre>
+# Don't forget the PT flag! (pass through)
+RewriteRule ^/(.*) http://www.mycompany.com/myapp/$1 [PT]
+</pre></div>
+<p>2. Use <a href="http://httpd.apache.org/docs/2.2/mod/mod_headers.html"><b class="code">mod_headers</b></a>
+to rewrite any HTTP redirects your application might return. Such redirects typically contain
+the path components you want to hide, because by the HTTP standard, redirects always need to include
+the full URL, and your application is not aware of the fact, that your clients talk to it via
+some shortened URL. An HTTP redirect is done with a special response header named <b class="code">Location</b>.
+We rewrite the Location headers of our responses:
+</p>
+<div class="example"><pre>
+# Keep protocol, server and port if present,
+# but insert our webapp name before the rest of the URL
+Header edit Location ^([^/]*//[^/]*)?/(.*)$ $1/myapp/$2
+</pre></div>
+<p>3. Use <b class="code">mod_headers</b> again, to rewrite the paths contained in any cookies,
+your application might set. Such cookie paths again might contain
+the path components you want to hide.
+A cookie is set with the HTTP response header named <b class="code">Set-Cookie</b>.
+We rewrite the Set-Cookie headers of our responses:
+</p>
+<div class="example"><pre>
+# Fix the cookie path
+Header edit Set-Cookie "^(.*; Path=/)(.*)" $1/myapp/$2
+</pre></div>
+<p>3. Some applications might contain hard coded absolute links.
+In this case check, whether you find a configuration item for your web framework
+to configure the base URL. If not, your only chance is to parse all response
+content bodies and do search and replace. This is fragile and very resource intensive.
+If you really need to do this, you can use
+<a href="http://apache.webthing.com/mod_proxy_html/"><b class="code">mod_proxy_html</b></a>,
+<a href="http://httpd.apache.org/docs/2.2/mod/mod_substitute.html"><b class="code">mod_substitute</b></a>
+or <a href="http://blogs.sun.com/basant/entry/using_mod_sed_to_filter"><b class="code">mod_sed</b></a>
+for this task.
+</p>
+<p>If you are using Microsoft IIS as a web server, the ISAPI plugin provides a way
+of doing the first step with a builtin feature. You define a mapping file for simple prefix
+changes like this:
+</p>
+<div class="example"><pre>
+# Add a context prefix to all requests ...
+/=/myapp/
+# ... or change some prefix ...
+/oldapp/=/myapp/
+</pre></div>
+<p>and then put the name of the file in the <b class="code">rewrite_rule_file</b> entry of the registry or your
+<b class="code">isapi_redirect.properties</b> file. In you <b class="code">uriworkermap.properties</b> file, you
+still need to map the URLs as they are before rewriting!
+</p>
+<p>More complex rewrites can be done using the same file, but with regular expressions. A leading
+tilde sign '<b class="code">~</b>', indicates, that you are using a regular expression:
+</p>
+<div class="example"><pre>
+# Use a regular expression rewrite
+~/oldapps([0-9]*)/=/newapps$1/
+</pre></div>
+<p>There is no support for Steps 2 (rewriting redirect responses) or 3 (rewriting cookie paths).
+</p>
+</blockquote></td></tr></table>
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="URL Encoding"><strong>URL Encoding</strong></a></font></td></tr><tr><td><blockquote>
+<p>Some types of problems are triggered by the use of encoded URLs
+(see <a href="http://en.wikipedia.org/wiki/Percent-encoding">percent encoding</a>).
+For the same location there exist
+a lot of different URLs which are equivalent. The reverse proxy needs to inspect the URL in order
+to apply its own authentication rules and to decide, to which backend it should send the request
+(or whether it should handle it itself). Therefore the request URL first is normalized:
+percent encoded characters are decoded, <b class="code">/./</b> is replaced by <b class="code">/</b>,
+<b class="code">/XXX/../</b> is replaced by <b class="code">/</b> and similar manipulations of the URL are done.
+After that, the web server might apply rewrite rules to further change the URL in less obvious ways.
+Finally there is no more way to put the resulting URL in an encoding, which is "similar" to
+the one which was used for the original URL.
+</p>
+<p>
+For historical reasons, there have been several alternatives, how mod_jk and the ISAPI
+plugin encoded the resulting URL before sending it to the backend. They could be chosen via
+<b class="code">JkOptions</b> (Apache httpd) or <b class="code">uri_select</b> (ISAPI). None of those historical
+encodings are recommended, because they have either negative functionality implications or
+pose a security risk. The default encoding since version 1.2.24 is <b class="code">ForwardURIProxy</b>
+(Apache httpd) or <b class="code">proxy</b> (ISAPI) and it is strongly recommended to keep the default
+and remove all old explicit settings.
+</p>
+</blockquote></td></tr></table>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Request Attributes"><strong>Request Attributes</strong></a></font></td></tr><tr><td><blockquote>
+<br>
+<p>
+You can also add more attributes to any request you are forwarding when using Apache httpd.
+For this use the <b class="code">JkEnvVar</b> directive (for details see the
+<a href="../../reference/apache.html">Apache reference</a> page). Such request attributes can be
+retrieved on the Tomcat side via request.getAttribute(attributeName).
+Note that their names will not be listed in request.getAttributeNames()!
+</p>
+</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>
+ Copyright © 1999-2012, Apache Software Foundation
+ </em></font></div></td></tr></table></body></html>
\ No newline at end of file
Propchange: tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/proxy.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/quick.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/quick.html?rev=1307873&view=auto
==============================================================================
--- tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/quick.html (added)
+++ tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/quick.html Sat Mar 31 18:52:20 2012
@@ -0,0 +1,130 @@
+<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>The Apache Tomcat Connector - Generic HowTo - Quick Start HowTo</title><meta name="author" value="Henri Gomez"><meta name="email" value="hgomez@apache.org"><link href="../../style.css" type="text/css" rel="stylesheet"></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="4"><!--PAGE HEADER--><tr><td colspan="2"><!--TOMCAT LOGO--><a href="http://tomcat.apache.org/"><img src="../../images/tomcat.gif" align="left" alt="Apache Tomcat" border="0"></a><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="http://www.apache.org/images/asf-logo.gif" align="right" alt=" :: Apache Software Foundation" border="0"></a></td></tr><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%" cellspa
cing="4"><tr><td align="left" valign="top"><h1>The Apache Tomcat Connector - Generic HowTo</h1><h2>Quick Start HowTo</h2></td><td align="right" valign="top" nowrap="true"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0" alt=" "></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><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>
+ This document describes the configuration files used by JK on the
+ Web Server side for the 'impatient':
+ <ul>
+ <li>
+ <b>workers.properties</b> is a mandatory file used by the webserver and which
+ is the same for all JK implementations (Apache/IIS/NES).
+ </li>
+ <li>
+ <b>web server</b> add-ons to be set on the webserver side.
+ </li>
+ </ul>
+</p>
+<p>
+ We'll give here minimum servers configuration and an example <b>workers.properties</b>
+ to be able to install and check quickly your configuration.
+</p>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Minimum workers.properties"><strong>Minimum workers.properties</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+ Here is a minimum <b>workers.properties</b>, using just ajp13 to connect your Apache webserver
+ to the Tomcat engine, complete documentation is available in <a href="workers.html">Workers HowTo</a>.
+</p>
+<p>
+<div class="example"><pre>
+
+ # Define 1 real worker using ajp13
+ worker.list=worker1
+ # Set properties for worker1 (ajp13)
+ worker.worker1.type=ajp13
+ worker.worker1.host=localhost
+ worker.worker1.port=8009
+
+</pre></div>
+</p>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Minimum Apache web server configuration"><strong>Minimum Apache web server configuration</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+ Here is a minimum information about Apache configuration, a
+ more complete <a href="../../webserver_howto/apache.html">separate HowTo for Apache</a> is available.
+</p>
+<p>
+ You should first have <b>mod_jk.so</b> (unix) or <b>mod_jk.dll</b> (Windows) installed
+ in your Apache module directory (see your Apache documentation to locate it).
+</p>
+<p>
+ Usual locations for modules directory on Unix:
+ <ul>
+ <li>/usr/lib/apache/</li>
+ <li>/usr/lib/apache2/</li>
+ <li>/usr/local/apache/libexec/</li>
+ </ul>
+</p>
+<p>
+ Usual locations for modules directory on Windows :
+ <ul>
+ <li>C:\Program Files\Apache Group\Apache\modules\</li>
+ <li>C:\Program Files\Apache Group\Apache2\modules\</li>
+ </ul>
+</p>
+<p>
+ You'll find a link to prebuilt binaries
+ <a href="http://tomcat.apache.org/download-connectors.cgi/">here</a>
+</p>
+<p>
+ Here is the minimum which should be set in <b>httpd.conf</b> directly or
+ included from another file:
+</p>
+<p>
+ Usual locations for configuration directory on Unix:
+ <ul>
+ <li>/etc/httpd/conf/</li>
+ <li>/etc/httpd2/conf/</li>
+ <li>/usr/local/apache/conf/</li>
+ </ul>
+</p>
+<p>
+ Usual locations for configuration directory on Windows :
+ <ul>
+ <li>C:\Program Files\Apache Group\Apache\conf\</li>
+ <li>C:\Program Files\Apache Group\Apache2\conf\</li>
+ </ul>
+</p>
+<p>
+<div class="example"><pre>
+
+ # Load mod_jk module
+ # Update this path to match your modules location
+ LoadModule jk_module libexec/mod_jk.so
+ # Declare the module for <IfModule directive> (remove this line on Apache 2.x)
+ AddModule mod_jk.c
+ # Where to find workers.properties
+ # Update this path to match your conf directory location (put workers.properties next to httpd.conf)
+ JkWorkersFile /etc/httpd/conf/workers.properties
+ # Where to put jk shared memory
+ # Update this path to match your local state directory or logs directory
+ JkShmFile /var/log/httpd/mod_jk.shm
+ # Where to put jk logs
+ # Update this path to match your logs directory location (put mod_jk.log next to access_log)
+ JkLogFile /var/log/httpd/mod_jk.log
+ # Set the jk log level [debug/error/info]
+ JkLogLevel info
+ # Select the timestamp log format
+ JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
+ # Send everything for context /examples to worker named worker1 (ajp13)
+ JkMount /examples/* worker1
+
+</pre></div>
+</p>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Minimum IIS web server configuration"><strong>Minimum IIS web server configuration</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+ A separate <a href="../../webserver_howto/iis.html">HowTo for the IIS web server</a> is available.
+</p>
+<p class="todo">
+ This paragraph has not been written yet, but <b>you</b> can contribute to it.
+ </p>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Minimum NES/iPlanet/Sun web server configuration"><strong>Minimum NES/iPlanet/Sun web server configuration</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+ A separate <a href="../../webserver_howto/nes.html">HowTo for the Netscape/iPlanet/Sun web server</a> is available.
+<p class="todo">
+ This paragraph has not been written yet, but <b>you</b> can contribute to it.
+ </p>
+</p>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Test your configuration"><strong>Test your configuration</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+ (Re)start the web server and browse to the <a href="http://localhost/examples/">http://localhost/examples/</a>
+</p>
+
+</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>
+ Copyright © 1999-2012, Apache Software Foundation
+ </em></font></div></td></tr></table></body></html>
\ No newline at end of file
Propchange: tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/quick.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/timeouts.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/timeouts.html?rev=1307873&view=auto
==============================================================================
--- tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/timeouts.html (added)
+++ tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/timeouts.html Sat Mar 31 18:52:20 2012
@@ -0,0 +1,373 @@
+<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>The Apache Tomcat Connector - Generic HowTo - Timeouts HowTo</title><meta name="author" value="Rainer Jung"><meta name="email" value="rjung@apache.org"><link href="../../style.css" type="text/css" rel="stylesheet"></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="4"><!--PAGE HEADER--><tr><td colspan="2"><!--TOMCAT LOGO--><a href="http://tomcat.apache.org/"><img src="../../images/tomcat.gif" align="left" alt="Apache Tomcat" border="0"></a><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="http://www.apache.org/images/asf-logo.gif" align="right" alt=" :: Apache Software Foundation" border="0"></a></td></tr><!--HEADER SEPARATOR--><tr><td colspan="2"><hr 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>The Apache Tomcat Connector - Generic HowTo</h1><h2>Timeouts HowTo</h2></td><td align="right" valign="top" nowrap="true"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0" alt=" "></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
+<br>
+<p>Setting communication timeouts is very important to improve the
+communication process. They help to detect problems and stabilise
+a distributed system. JK can use several different timeout types, which
+can be individually configured. For historical reasons, all of them are
+disabled by default. This HowTo explains their use and gives
+hints how to find appropriate values.
+</p>
+<p>All timeouts can be configured in the workers.properties file.
+For a complete reference of all worker configuration
+items, please consult the worker <a href="../../reference/workers.html">reference</a>.
+This page assumes, that you are using at least version 1.2.16 of JK.
+Dependencies on newer versions will be mentioned where necessary.
+</p>
+<p><font color="#ff0000">
+Do not set timeouts to extreme values. Very small timeouts will likely
+be counterproductive.
+</font></p>
+<p><font color="#ff0000">
+Long Garbage Collection pauses on the backend do not make a good
+fit with some timeouts. Try to optimise your Java memory and GC settings.
+</font></p>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JK Timeout Attributes"><strong>JK Timeout Attributes</strong></a></font></td></tr><tr><td><blockquote>
+<br>
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="CPing/CPong"><strong>CPing/CPong</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+CPing/CPong is our notion for using small test packets to check the
+status of backend connections. JK can use such test packets directly after establishing
+a new backend connection (connect mode) and also directly before each request gets
+send to a backend (prepost mode).
+Starting with version 1.2.27 it can also be used when a connection was idle
+for a long time (interval mode).
+The maximum waiting time (timeout) for a CPong answer to a CPing and the idle
+time in interval mode can be configured.
+</p>
+<p>
+The test packets will be answered by the backend very fast with a minimal amount of
+needed processing resources. A positive answer tells us, that the backend can be reached
+and is actively processing requests. It does not detect, if some context is deployed
+and working. The benefit of CPing/CPong is a fast detection of a communication
+problem with the backend. The downside is a slightly increased latency.
+</p>
+<p>
+The worker attribute <b>ping_mode</b> can be set to a combination of characters
+to determine, in which situations test packets are used:
+<ul>
+<li><b>C</b>: connect mode, timeout <b>ping_timeout</b> overwritten by <b>connect_timeout</b></li>
+<li><b>P</b>: prepost mode, timeout <b>ping_timeout</b> overwritten by <b>prepost_timeout</b></li>
+<li><b>I</b>: interval mode, timeout <b>ping_timeout</b>, idle time <b>connection_ping_interval</b></li>
+<li><b>A</b>: all modes</li>
+</ul>
+</p>
+<p>
+Multiple values must be concatenated without any separator characters.
+We recommend using all CPing tests. If your application is very latency sensitive, then
+you should only use the combination of connect and interval mode.
+</p>
+<p>
+Activating the CPing probing via <b>ping_mode</b> has been added in version 1.2.27.
+For older versions only the connect and prepost modes exist and must be activated by
+explicitely setting <b>connect_timeout</b> and <b>prepost_timeout</b>.
+</p>
+<p>
+The worker attribute <b>ping_timeout</b> sets the default wait timeout
+in milliseconds for CPong for all modes. By default the value is "10000"
+milliseconds. The value only gets used, if you activate CPing/Cpong probes
+via <b>ping_mode</b>. The default value should be fine, except if you experience
+very long Java garbage collection pauses.
+Depending on your network latency and stability, good custom values
+often are between 5000 and 15000 milliseconds.
+You can overwrite the timeout used for connect and prepost mode with
+<b>connect_timeout</b> and <b>prepost_timeout</b>.
+Remember: don't use extremely small values.
+</p>
+<p>
+The worker attribute <b>connect_timeout</b> sets the wait timeout
+in milliseconds for CPong during connection establishment. You can use it
+if you want to overwrite the general timeout set with <b>ping_timeout</b>.
+To use connect mode CPing, you need to enable it via <b>ping_mode</b>.
+Since JK usually uses persistent connections, opening new connections is a
+rare event. We therefore recommend activating connect mode.
+Depending on your network latency and stability, good values often
+are between 5000 and 15000 milliseconds.
+Remember: don't use extremely small values.
+</p>
+<p>
+The worker attribute <b>prepost_timeout</b> sets the wait timeout
+in milliseconds for CPong before request forwarding. You can use it
+if you want to overwrite the general timeout set with <b>ping_timeout</b>.
+To use prepost mode CPing, you need to enable it via <b>ping_mode</b>.
+Activating this type of CPing/CPong adds a small latency to each
+request. Usually this is small enough and the benefit of CPing/CPong is more important.
+So in general we also recommend using <b>prepost_timeout</b>.
+Depending on your network latency and stability, good values often
+are between 5000 and 10000 milliseconds.
+Remember: don't use extremely small values.
+</p>
+<p>
+Until version 1.2.27 <b>ping_mode</b> and <b>ping_timeout</b> did not
+exist and to enable connect or prepost mode CPing you had to set <b>connect_timeout</b>
+respectively <b>prepost_timeout</b> to some reasonable positive value.
+</p>
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Low-Level TCP Timeouts"><strong>Low-Level TCP Timeouts</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+Some platforms allow to set timeouts for all operations on TCP sockets.
+This is available for Linux and Windows, other platforms do not support this,
+e.g. Solaris. If your platform supports TCP send and receive timeouts,
+you can set them using the worker attribute <b>socket_timeout</b>.
+You can not set the two timeouts to different values.
+</p>
+<p>
+JK will accept this attribute even if your platform does not support
+socket timeouts. In this case setting the attribute will have no effect.
+By default the value is "0" and the timeout is disabled.
+You can set the attribute to some seconds value (not: milliseconds).
+JK will then set the send and the receive timeouts of the backend
+connections to this value. The timeout is low-level, it is
+used for each read and write operation on the socket individually.
+</p>
+<p>
+Using this attribute will make JK react faster to some types of network problems.
+Unfortunately socket timeouts have negative side effects, because for most
+platforms, there is no good way to recover from such a timeout, once it fired.
+For JK there is no way to decide, if this timeout fired because of real network
+problems, or only because it didn't receive an answer packet from a backend in time.
+So remember: don't use extremely small values.
+</p>
+<p>
+For the general case of connection establishment you can use
+<b>socket_connect_timeout</b>. It takes a millisecond value and works
+on most platforms, even if <b>socket_timeout</b> is not supported.
+We recommend using <b>socket_connect_timeout</b> because in some network
+failure situations failure detection during connection establishment
+can take several minutes due to TCP retransmits. Depending on the quality
+of your network a timeout somewhere between 1000 and 5000 milliseconds
+should be fine. Note that <b class="code">socket_timeout</b> is in seconds, and
+<b class="code">socket_connect_timeout</b> in milliseconds.
+</p>
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Connection Pools and Idle Timeouts"><strong>Connection Pools and Idle Timeouts</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+JK handles backend connections in a connection pool per web server process.
+The connections are used in a persistent mode. After a request completed
+successfully we keep the connection open and wait for the next
+request to forward. The connection pool is able to grow according
+to the number of threads that want to forward requests in parallel.
+</p>
+<p>
+Most applications have a varying load depending on the hour of the day
+or the day of the month. Other reasons for a growing connection pool
+would be temporary slowness of backends, leading to an increasing
+congestion of the frontends like web servers. Many backends use a dedicated
+thread for each incoming connection they handle. So usually one wants the
+connection pool to shrink, if the load diminishes.
+</p>
+<p>
+JK allows connections in the pool to get closed after some idle time.
+This maximum idle time can be configured with the attribute
+<b>connection_pool_timeout</b> which is given in units of seconds.
+The default value is "0", which disables closing idle connections.
+</p>
+<p>
+We generally recommend values around 10 minutes, so setting
+<b>connection_pool_timeout</b> to 600 (seconds). If you use this attribute,
+please also set the attribute <b>connectionTimeout</b> in the AJP
+Connector element of your Tomcat server.xml configuration file to
+an analogous value. <b>Caution</b>: connectionTimeout is in milliseconds.
+So if you set JK connection_pool_timeout to 600, you should set Tomcat
+connectionTimeout to 600000.
+</p>
+<p>
+JK connections do not get closed immediately after the timeout passed.
+Instead there is an automatic internal maintenance task
+running every 60 seconds, that checks the idle status of all connections.
+The 60 seconds interval
+can be adjusted with the global attribute worker.maintain. We do not
+recommend to change this value, because it has a lot of side effects.
+Until version 1.2.26, the maintenance task only runs, if requests get
+processed. So if your web server has processes that do not receive any
+requests for a long time, there is no way to close the idle connections
+in its pool. Starting with version 1.2.27 you can configure an independent
+watchdog thread when using Apache 2.x with threaded APR or IIS.
+</p>
+<p>
+The maximum connection pool size can be configured with the
+attribute <b>connection_pool_size</b>. We generally do not recommend
+to use this attribute in combination with Apache httpd. For
+Apache httpd we automatically detect the number of threads per
+process and set the maximum pool size to this value. For IIS we use
+a default value of 250 (before version 1.2.20: 10),
+for the Sun Web Server the default is "1".
+We strongly recommend adjusting this value for IIS and the Sun Web Server
+to the number of requests one web server process should
+be able to send to a backend in parallel. You should measure how many connections
+you need during peak hours without performance problems, and then add some
+percentage depending on your growth rate etc. Finally you should check,
+whether your web server processes are able to use at least as many threads,
+as you configured as the pool size.
+</p>
+<p>
+The JK attribute <b>connection_pool_minsize</b> defines,
+how many idle connections remain when the pool gets shrunken.
+By default this is half of the maximum pool size.
+</p>
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Firewall Connection Dropping"><strong>Firewall Connection Dropping</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+One particular problem with idle connections comes from firewalls, that
+are often deployed between the web server layer and the backend.
+Depending on their configuration, they will silently drop
+connections from their status table if they are idle for to long.
+</p>
+<p>
+From the point of view of JK and of the web server, the other side
+simply doesn't answer any traffic. Since TCP is a reliable protocol
+it detects the missing TCP ACKs and tries to resend the packets for
+a relatively long time, typically several minutes.
+</p>
+<p>
+Many firewalls will allow connection closing, even if they dropped
+the connection for normal traffic. Therefore you should always use
+<a href="#Connection Pools and Idle Timeouts">connection_pool_timeout and
+connection_pool_minsize</a> on the JK side
+and connectionTimeout on the Tomcat side.
+</p>
+<p>
+Furthermore using the boolean attribute <b>socket_keepalive</b> you can
+set a standard socket option, that automatically sends TCP keepalive packets
+after some idle time on each connection. By default this is set to "False".
+If you suspect idle connection drops by firewalls you should set this to
+"True".
+</p>
+<p>
+Unfortunately the default intervals and algorithms for these packets
+are platform specific. You might need to inspect TCP tuning options for
+your platform on how to control TCP keepalive.
+Often the default intervals are much longer than the firewall timeouts
+for idle connections. Nevertheless we recommend talking to your firewall
+administration and your platform administration in order to make them agree
+on good configuration values for the firewall and the platform TCP tuning.
+</p>
+<p>
+In case none of our recommendations help and you are definitively having
+problems with idle connection drops, you can disable the use of persistent
+connections when using JK together with Apache httpd. For this you set
+"JkOptions +DisableReuse" in your Apache httpd configuration.
+This will have a huge negative performance impact!
+</p>
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Reply Timeout"><strong>Reply Timeout</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+JK can also use a timeout on request replies. This timeout does not
+measure the full processing time of the response. Instead it controls,
+how much time between consecutive response packets is allowed.
+</p>
+<p>
+In most cases, this is what one actually wants. Consider for example
+long running downloads. You would not be able to set an effective global
+reply timeout, because downloads could last for many minutes.
+Most applications though have limited processing time before starting
+to return the response. For those applications you could set an explicit
+reply timeout. Applications that do not harmonise with reply timeouts
+are batch type applications, data warehouse and reporting applications
+which are expected to observe long processing times.
+</p>
+<p><font color="#ff0000">
+If JK aborts waiting for a response, because a reply timeout fired,
+there is no way to stop processing on the backend. Although you free
+processing resources in your web server, the request
+will continue to run on the backend - without any way to send back a
+result once the reply timeout fired.
+</font></p>
+<p>
+JK uses the worker attribute <b>reply_timeout</b> to set reply timeouts.
+The default value is "0" (timeout disabled) and you can set it to any
+millisecond value.
+</p>
+<p>
+In combination with Apache httpd, you can also set a more flexible reply_timeout
+using an httpd environment variable. If you set the variable JK_REPLY_TIMEOUT
+to some integer value, this value will be used instead of the value in
+the worker configuration. This way you can set reply timeouts more flexible
+with mod_setenvif and mod_rewrite depending on URI, query string etc.
+If the environment variable JK_REPLY_TIMEOUT is not set, or is set to a
+negative value, the default reply timeout of the worker will be used. If
+JK_REPLY_TIMEOUT contains the value "0", then the reply timeout will be disabled
+for the request.
+</p>
+<p>
+In combination with a load balancing worker, JK will disable a member
+worker of the load balancer if a reply timeout fires. The worker will then
+no longer be used until it gets recovered during the next automatic
+maintenance task. Starting with JK 1.2.24 you can improve this behaviour using
+<b><a href="../../reference/workers.html">max_reply_timeouts</a></b>. This
+attribute will allow occasional long running requests without disabling the
+worker. Only if those requests happen to often, the worker gets disabled by the
+load balancer.
+</p>
+</blockquote></td></tr></table>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Load Balancer Error Detection"><strong>Load Balancer Error Detection</strong></a></font></td></tr><tr><td><blockquote>
+<br>
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Local and Global Error States"><strong>Local and Global Error States</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+A load balancer worker does not only have the ability to balance load.
+It also handles stickyness and failover of requests in case of errors.
+When a load balancer detects an error on one of its members, it needs to
+decide, whether the error is serious, or only a temporary error or maybe
+only related to the actual request that was processed. Temporary errors
+are called local errors, serious errors will be called global errors.
+</p>
+<p>
+If the load balancer decides that a backend should be put into the global error
+state, then the web server will not send any more requests there. If no session
+replication is used, this means that all user sessions located on the respective
+backend are no longer available. The users will be send to another backend
+and will have to login again. So the global error state is not transparent to the
+users. The application is still available, but users might loose some work.
+</p>
+<p>
+In some cases the decision between local error and global error is easy.
+For instance if there is an error sending back the response to the client (browser),
+then it is very unlikely that the backend is broken.
+So this situation is a typical example of a local error.
+</p>
+<p>
+Some situations are harder to decide though. If the load balancer can't establish
+a new connection to a backend, it could be because of a temporary overload situation
+(so no more free threads in the backend), or because the backend isn't alive any more.
+Depending on the details, the right state could either be local error or global error.
+</p>
+</blockquote></td></tr></table>
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Error Escalation Time"><strong>Error Escalation Time</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+Until version 1.2.26 most errors were interpreted as global errors.
+Starting with version 1.2.27 many errors which were previously interpreted as global
+were switched to being local whenever the backend is still busy. Busy means, that
+other concurrent requests are send to the same backend (successful or not).
+</p>
+<p>
+In many cases there is no perfect way of making the decision
+between local and global error. The load balancer simply doesn't have enough information.
+In version 1.2.28 you can now tune, how fast the load balancer switches from local error to
+global error. If a member of a load balancer stays in local error state for too long,
+the load balancer will escalate it into global error state.
+</p>
+<p>
+The time tolerated in local error state is controlled by the load balancer attribute
+<b>error_escalation_time</b> (in seconds). The default value is half of <b>recover_time</b>,
+so unless you changed <b>recover_time</b> the default is 30 seconds.
+</p>
+<p>
+Using a smaller value for <b>error_escalation_time</b> will make the load balancer react
+faster to serious errors, but also carries the risk of more often loosing sessions
+in not so serious situations. You can lower <b>error_escalation_time</b> down to 0 seconds,
+which means all local errors which are potentially serious are escalated to global errors
+immediately.
+</p>
+<p>
+Note that without good basic error detection the whole escalation procedure is useless.
+So you should definitely use <b>socket_connect_timeout</b> and activate CPing/CPong
+with <b>ping_mode</b> and <b>ping_timeout</b> before thinking about also tuning
+<b>error_escalation_time</b>.
+</p>
+</blockquote></td></tr></table>
+</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>
+ Copyright © 1999-2012, Apache Software Foundation
+ </em></font></div></td></tr></table></body></html>
\ No newline at end of file
Propchange: tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/timeouts.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/workers.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/workers.html?rev=1307873&view=auto
==============================================================================
--- tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/workers.html (added)
+++ tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/workers.html Sat Mar 31 18:52:20 2012
@@ -0,0 +1,407 @@
+<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>The Apache Tomcat Connector - Generic HowTo - Workers HowTo</title><meta name="author" value="Henri Gomez"><meta name="email" value="hgomez@apache.org"><meta name="author" value="Gal Shachor"><meta name="email" value="shachor@il.ibm.com"><meta name="author" value="Mladen Turk"><meta name="email" value="mturk@apache.org"><link href="../../style.css" type="text/css" rel="stylesheet"></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="4"><!--PAGE HEADER--><tr><td colspan="2"><!--TOMCAT LOGO--><a href="http://tomcat.apache.org/"><img src="../../images/tomcat.gif" align="left" alt="Apache Tomcat" border="0"></a><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="http://www.apache.org/images/asf-logo.gif" align="right" alt=" :: Apache Software Foundation" border="0"></a></td></tr><!--HEADER SEPARATO
R--><tr><td colspan="2"><hr 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>The Apache Tomcat Connector - Generic HowTo</h1><h2>Workers HowTo</h2></td><td align="right" valign="top" nowrap="true"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0" alt=" "></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><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>
+A Tomcat worker is a Tomcat instance that is waiting to execute servlets on behalf of some web server.
+For example, we can have a web server such as Apache forwarding servlet requests to a
+Tomcat process (the worker) running behind it.
+</p>
+<p>
+The scenario described above is a very simple one;
+in fact one can configure multiple Tomcat workers to serve servlets on
+behalf of a certain web server.
+The reasons for such configuration can be:
+</p>
+<ul>
+<li>
+We want different contexts to be served by different Tomcat workers to provide a
+development environment where all the developers share the same web server but own a Tomcat worker of their own.
+</li>
+<li>
+We want different virtual hosts served by different Tomcat processes to provide a
+clear separation between sites belonging to different companies.
+</li>
+<li>
+We want to provide load balancing, meaning run multiple Tomcat workers each on a
+machine of its own and distribute the requests between them.
+</li>
+</ul>
+
+<p>
+There are probably more reasons for having multiple workers but I guess that this list is enough...
+Tomcat workers are defined in a properties file dubbed workers.properties and this tutorial
+explains how to work with it.
+</p>
+
+<p>
+This document was originally part of <b>Tomcat: A Minimalistic User's Guide</b> written by Gal Shachor,
+but has been split off for organisational reasons.
+</p>
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Defining Workers"><strong>Defining Workers</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+Defining workers to the Tomcat web server plugin can be done using a properties file
+(a sample file named workers.properties is available in the conf/ directory).
+</p>
+
+<p>
+the file contains entries of the following form:
+</p>
+
+<p>
+<b>worker.list</b>=<a comma separated list of worker names>
+</p>
+
+<div class="example"><pre>
+ # the list of workers
+ worker.list= worker1, worker2
+</pre></div>
+
+<p>
+When starting up, the web server plugin will instantiate the workers whose name appears in the
+<b>worker.list</b> property, these are also the workers to whom you can map requests. The directive can be used multiple times.
+</p>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Workers Type"><strong>Workers Type</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+Each named worker should also have a few entries to provide additional information on his behalf.
+This information includes the worker's type and other related worker information.
+Currently the following worker types that exists are (JK 1.2.5):
+</p>
+
+<table>
+ <tr><th>Type</th><th>Description</th></tr>
+ <tr><td>ajp12</td><td>This worker knows how to forward requests to out-of-process Tomcat workers using the ajpv12 protocol.</td></tr>
+ <tr><td>ajp13</td><td>This worker knows how to forward requests to out-of-process Tomcat workers using the ajpv13 protocol.</td></tr>
+ <tr><td>lb</td><td>This is a load-balancing worker; it knows how to provide round-robin based sticky load balancing with a certain level of fault-tolerance.</td></tr>
+ <tr><td>status</td><td>This is a status worker for managing load balancers.</td></tr>
+</table>
+
+<p>
+Defining workers of a certain type should be done with the following property format:
+</p>
+
+<p>
+<b>worker</b>.<b>worker name</b>.<b>type</b>=<worker type>
+Where worker name is the name assigned to the worker and the worker type is one of the four types defined
+in the table (a worker name may only contain any space the characters [a-zA-Z0-9\-_]).
+</p>
+
+<div class="example"><pre>
+ # Defines a worker named "local" that uses the ajpv12 protocol to forward requests to a Tomcat process.
+ worker.local.type=ajp12
+ # Defines a worker named "remote" that uses the ajpv13 protocol to forward requests to a Tomcat process.
+ worker.remote.type=ajp13
+ # Defines a worker named "loadbalancer" that loadbalances several Tomcat processes transparently.
+ worker.loadbalancer.type=lb
+</pre></div>
+
+</blockquote></td></tr></table>
+
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Setting Worker Properties"><strong>Setting Worker Properties</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+After defining the workers you can also specify properties for them.
+Properties can be specified in the following manner:
+</p>
+
+<p>
+worker.<worker name>.<property>=<property value>
+</p>
+
+Each worker has a set of properties that you can set as specified in the following subsections:
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="ajp12 Worker properties"><strong>ajp12 Worker properties</strong></a></font></td></tr><tr><td><blockquote>
+<p><p><font color="#ff0000">
+The <b>ajp12</b> has been <b>deprecated</b> with Tomcat 3.3.x and you should use instead
+<b>ajp13</b> which is the only ajp protocol known by Tomcat 4.x and 5 and 5.5 and Tomcat 6.
+</font></p></p>
+<p>
+The ajp12 typed workers forward requests to out-of-process Tomcat workers
+using the ajpv12 protocol over TCP/IP sockets.
+</p>
+
+<p>
+the ajp12 worker properties are :
+</p>
+
+<p>
+<b>host</b> property sets the host where the Tomcat worker is listening for ajp12 requests.
+</p>
+
+<p>
+<b>port</b> property sets the port where the Tomcat worker is listening for ajp12 requests
+</p>
+
+<p>
+<b>lbfactor</b> property is used when working with a load balancer worker, this is the load-balancing factor for the worker.
+We'll see more on this in the <a href="../../generic_howto/loadbalancers.html">lb worker</a> section.
+</p>
+
+<div class="example"><pre>
+ # worker "worker1" will talk to Tomcat listening on machine www.x.com at port 8007 using 2 lb factor
+ worker.worker1.host=www.x.com
+ worker.worker1.port=8007
+ worker.worker1.lbfactor=2
+</pre></div>
+
+<p>
+Notes: In the ajpv12 protocol, connections are created, used and then closed at each request.
+The default port for ajp12 is 8007
+</p>
+
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="ajp13 Worker properties"><strong>ajp13 Worker properties</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+The ajp13 typed workers forward requests to out-of-process Tomcat workers using the ajpv13 protocol over TCP/IP sockets.
+The main difference between ajpv12 and ajpv13 are that:
+<ul>
+<li>
+ajpv13 is a more binary protocol and it tries to compress some of the request data by coding
+frequently used strings as small integers.
+</li>
+<li>
+ajpv13 reuses open sockets and leaves them open for future requests (remember when you've got a Firewall between your
+web server and Tomcat).
+</li>
+<li>
+ajpv13 has special treatment for SSL information so that the container can implement
+SSL related methods such as isSecure().
+</li>
+</ul>
+
+</p>
+
+<p>
+You should note that Ajp13 is now the only out-process protocol supported by Tomcat 4.0.x, 4.1.x, 5.0.x, 5.5.x and 6.
+</p>
+
+
+<div class="example"><pre>
+ # worker "worker2" will talk to Tomcat listening on machine www2.x.com at port 8009 using 3 lb factor
+ worker.worker2.host=www2.x.com
+ worker.worker2.port=8009
+ worker.worker2.lbfactor=3
+ # worker "worker2" uses connections, which will stay no more than 10mn in the connection pool
+ worker.worker2.connection_pool_timeout=600
+ # worker "worker2" ask operating system to send KEEP-ALIVE signal on the connection
+ worker.worker2.socket_keepalive=1
+ # mount can be used as an alternative to the JkMount directive
+ worker.worker2.mount=/contexta /contexta/* /contextb /contextb/*
+</pre></div>
+
+<p>
+Notes: In the ajpv13 protocol, the default port is 8009
+</p>
+
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="lb Worker properties"><strong>lb Worker properties</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+The load-balancing worker does not really communicate with Tomcat workers.
+Instead it is responsible for the management of several "real" workers.
+This management includes:
+</p>
+
+<ul>
+<li>
+Instantiating the workers in the web server.
+</li>
+<li>
+Using the worker's load-balancing factor, perform weighed-round-robin load balancing where
+high lbfactor means stronger machine (that is going to handle more requests)
+</li>
+<li>
+Keeping requests belonging to the same session executing on the same Tomcat worker.
+</li>
+<li>
+Identifying failed Tomcat workers, suspending requests to them and instead falling-back on
+other workers managed by the lb worker.
+</li>
+</ul>
+
+<p>
+The overall result is that workers managed by the same lb worker are load-balanced (based on their lbfactor and current user session) and also fall-backed so a single Tomcat process death will not "kill" the entire site.
+The following table specifies some properties that the lb worker can accept:
+<ul>
+<li><b>balance_workers</b> is a comma separated list of workers that the load balancer need to manage.
+As long as these workers should only be used via the load balancer worker,
+there is no need to also put them into the worker.list property.
+This directive can be used multiple times for the same load balancer.</li>
+<li><b>sticky_session</b> specifies whether requests with SESSION ID's should be routed back to the same
+Tomcat worker. Set sticky_session to False when Tomcat is using a Session Manager which
+can persist session data across multiple instances of Tomcat. By default sticky_session is set to True.</li>
+</ul>
+</p>
+
+<div class="example"><pre>
+ # The worker balance1 while use "real" workers worker1 and worker2
+ worker.balance1.balance_workers=worker1, worker2
+</pre></div>
+
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Status Worker properties"><strong>Status Worker properties</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+The status worker does not communicate with Tomcat.
+Instead it is responsible for the load balancer management.
+</p>
+<div class="example"><pre>
+ # Add the status worker to the worker list
+ worker.list=jkstatus
+ # Define a 'jkstatus' worker using status
+ worker.jkstatus.type=status
+</pre></div>
+<p>Next thing is to mount the requests to the jkstatus worker. For Apache
+web servers use the:</p>
+<div class="example"><pre>
+ # Add the jkstatus mount point
+ JkMount /jkmanager/* jkstatus
+</pre></div>
+<p>To obtain a higher level of security use the:</p>
+<div class="example"><pre>
+ # Enable the JK manager access from localhost only
+ <Location /jkmanager/>
+ JkMount jkstatus
+ Order deny,allow
+ Deny from all
+ Allow from 127.0.0.1
+ </Location>
+</pre></div>
+
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Property file macros"><strong>Property file macros</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+You can define "macros" in the property files.
+These macros let you define properties and later on use them while
+constructing other properties.
+</p>
+
+<div class="example"><pre>
+ # property example, like a network base address
+ mynet=194.226.31
+ # Using the above macro to simplify the address definitions
+ # for a farm of workers.
+ worker.node1.host=$(mynet).11
+ worker.node2.host=$(mynet).12
+ worker.node3.host=$(mynet).13
+</pre></div>
+
+</blockquote></td></tr></table>
+
+<table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Hierarchical property configuration"><strong>Hierarchical property configuration</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+Workers can reference configurations of other workers.
+If worker "x" references worker "y", then it inherits all
+configuration parameters from "y", except for the ones
+that have explicitly been set for "x".
+</p>
+
+<div class="example"><pre>
+ # worker toe defines some default settings
+ worker.toe.type=ajp13
+ worker.toe.socket_keepalive=true
+ worker.toe.connect_timeout=10000
+ worker.toe.recovery_options=7
+ # workers tic and tac inherit those values
+ worker.tic.reference=worker.toe
+ worker.tac.reference=worker.toe
+</pre></div>
+
+<p>
+Please note, that the reference contains
+the full prefix to the referenced configuration attributes,
+not only the name of the referenced worker.
+</p>
+
+<p>
+References can be nested. Be careful to avoid loops!
+</p>
+
+<p>
+Attributes which are allowed multiple times for a single worker
+can not be merged from a worker and a reference. An attribute
+is only inherited from a reference, if it is not already set
+for the referring worker.
+</p>
+
+<p>
+References are especially useful, when configuring load balancers.
+Try to understand the following two stage references:
+</p>
+
+<div class="example"><pre>
+ # We only use one load balancer
+ worker.list=lb
+ # Let's define some defaults
+ worker.basic.port=8009
+ worker.basic.type=ajp13
+ worker.basic.socket_keepalive=true
+ worker.basic.connect_timeout=10000
+ worker.basic.recovery_options=7
+ # And we use them in two groups
+ worker.lb1.domain=dom1
+ worker.lb1.distance=0
+ worker.lb1.reference=worker.basic
+ worker.lb2.domain=dom2
+ worker.lb2.distance=1
+ worker.lb2.reference=worker.basic
+ # Now we configure the load balancer
+ worker.lb.type=lb
+ worker.lb.method=B
+ worker.lb.balanced_workers=w11,w12,w21,w22
+ worker.w11.host=myhost11
+ worker.w11.reference=worker.lb1
+ worker.w12.host=myhost12
+ worker.w12.reference=worker.lb1
+ worker.w21.host=myhost21
+ worker.w21.reference=worker.lb2
+ worker.w22.host=myhost22
+ worker.w22.reference=worker.lb2
+</pre></div>
+
+</blockquote></td></tr></table>
+
+</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="A sample worker.properties"><strong>A sample worker.properties</strong></a></font></td></tr><tr><td><blockquote>
+<p>
+Since coping with worker.properties on your own is not an easy thing to do,
+a sample worker.properties file is bundled along JK.
+</p>
+
+<p>
+You could also find here a sample workers.properties defining :
+</p>
+
+<ul>
+<li>
+An ajp12 worker that used the host localhost and the port 8007
+</li>
+<li>
+An ajp13 worker that used the host localhost and the port 8008
+</li>
+<li>
+An lb worker that load balance the ajp12 and ajp13 workers
+</li>
+</ul>
+
+<div class="example"><pre>
+ # Define 3 workers, 2 real workers using ajp12, ajp13, the last one being a loadbalancing worker
+ worker.list=worker1, worker2, worker3
+ # Set properties for worker1 (ajp12)
+ worker.worker1.type=ajp12
+ worker.worker1.host=localhost
+ worker.worker1.port=8007
+ worker.worker1.lbfactor=1
+ # Set properties for worker2 (ajp13)
+ worker.worker2.type=ajp13
+ worker.worker2.host=localhost
+ worker.worker2.port=8009
+ worker.worker2.lbfactor=1
+ worker.worker2.connection_pool_timeout=600
+ worker.worker2.socket_keepalive=1
+ worker.worker2.socket_timeout=60
+ # Set properties for worker3 (lb) which use worker1 and worker2
+ worker.worker3.balance_workers=worker1,worker2
+</pre></div>
+
+</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>
+ Copyright © 1999-2012, Apache Software Foundation
+ </em></font></div></td></tr></table></body></html>
\ No newline at end of file
Propchange: tomcat/site/trunk/docs/connectors-doc/generic_howto/printer/workers.html
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org