diff options
| author |   hongbotian <hongbo.tianhongbo@huawei.com> | 2015-11-30 02:41:33 -0500 |
|---|---|---|
| committer | hongbotian <hongbo.tianhongbo@huawei.com> | 2015-11-30 02:43:36 -0500 |
| commit | 9401f816dd0d9d550fe98a8507224bde51c4b847 (patch) | |
| tree | 94f2d7a7893a787bafdca8b5ef063ea316938874 /rubbos/app/tomcat-connectors-1.2.32-src/xdocs | |
| parent | e8ec7aa8e38a93f5b034ac74cebce5de23710317 (diff) | |
upload tomcat
JIRA: BOTTLENECK-7
Change-Id: I875d474869efd76ca203c30b60ebc0c3ee606d0e
Signed-off-by: hongbotian <hongbo.tianhongbo@huawei.com>
Diffstat (limited to 'rubbos/app/tomcat-connectors-1.2.32-src/xdocs')
50 files changed, 15255 insertions, 0 deletions
diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/ajp/ajpv13a.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/ajp/ajpv13a.xml new file mode 100644 index 00000000..3ab4502d --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/ajp/ajpv13a.xml @@ -0,0 +1,698 @@ +<?xml version="1.0"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="ajpv13a.html"> + + &project; + <copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> +<properties> +<title>AJPv13</title> +<author email="danmil@shore.net">danmil@shore.net</author> +<author email="jfrederic.clere@fujitsu-siemens.com">Jean-Frederic Clere</author> +<date>$Date: 2007-06-09 22:38:06 +0200 (Sat, 09 Jun 2007) $</date> +</properties> +<body> +<section name="Intro"> + +<p> +The original document was written by +Dan Milstein, <author email="danmil@shore.net">danmil@shore.net</author> +on December 2000. The present document is generated out of an xml file +to allow a more easy integration in the Tomcat documentation. + +</p> + +<p> +This describes the Apache JServ Protocol version 1.3 (hereafter +<b>ajp13</b>). There is, apparently, no current documentation of how the +protocol works. This document is an attempt to remedy that, in order to +make life easier for maintainers of JK, and for anyone who wants to +port the protocol somewhere (into jakarta 4.x, for example). +</p> + +</section> + +<section name="author"> + +<p> +I am not one of the designers of this protocol -- I believe that Gal +Shachor was the original designer. Everything in this document is derived +from the actual implementation I found in the tomcat 3.x code. I hope it +is useful, but I can't make any grand claims to perfect accuracy. I also +don't know why certain design decisions were made. Where I was able, I've +offered some possible justifications for certain choices, but those are +only my guesses. In general, the C code which Shachor wrote is very clean +and comprehensible (if almost totally undocumented). I've cleaned up the +Java code, and I think it's reasonably readable. +</p> +</section> + +<section name="Design Goals"> + +<p> +According to email from Gal Shachor to the jakarta-dev mailing list, +the original goals of <b>JK</b> (and thus <b>ajp13</b>) were to extend +<b>mod_jserv</b> and <b>ajp12</b> by (I am only including the goals which +relate to communication between the web server and the servlet container): + +<ul> + <li> Increasing performance (speed, specifically). </li> + + <li> Adding support for SSL, so that <code>isSecure()</code> and + <code>getScheme()</code> will function correctly within the servlet + container. The client certificates and cipher suite will be + available to servlets as request attributes. </li> + +</ul> +</p> +</section> + +<section name="Overview of the protocol"> + +<p> +The <b>ajp13</b> protocol is packet-oriented. A binary format was +presumably chosen over the more readable plain text for reasons of +performance. The web server communicates with the servlet container over +TCP connections. To cut down on the expensive process of socket creation, +the web server will attempt to maintain persistent TCP connections to the +servlet container, and to reuse a connection for multiple request/response +cycles. +</p><p> +Once a connection is assigned to a particular request, it will not be +used for any others until the request-handling cycle has terminated. In +other words, requests are not multiplexed over connections. This makes +for much simpler code at either end of the connection, although it does +cause more connections to be open at once. +</p><p> +Once the web server has opened a connection to the servlet container, +the connection can be in one of the following states: +</p><p> +<ul> + <li> Idle <br/> No request is being handled over this connection. </li> + <li> Assigned <br/> The connecton is handling a specific request.</li> +</ul> + +</p><p> +Once a connection is assigned to handle a particular request, the basic +request informaton (e.g. HTTP headers, etc) is sent over the connection in +a highly condensed form (e.g. common strings are encoded as integers). +Details of that format are below in Request Packet Structure. If there is a +body to the request (content-length > 0), that is sent in a separate +packet immediately after. +</p><p> +At this point, the servlet container is presumably ready to start +processing the request. As it does so, it can send the +following messages back to the web server: + +<ul> + <li>SEND_HEADERS <br/>Send a set of headers back to the browser.</li> + + <li>SEND_BODY_CHUNK <br/>Send a chunk of body data back to the browser.</li> + + <li>GET_BODY_CHUNK <br/>Get further data from the request if it hasn't all + been transferred yet. This is necessary because the packets have a fixed + maximum size and arbitrary amounts of data can be included the body of a + request (for uploaded files, for example). (Note: this is unrelated to + HTTP chunked tranfer).</li> + + <li>END_RESPONSE <br/> Finish the request-handling cycle.</li> +</ul> +</p><p> + +Each message is accompanied by a differently formatted packet of data. See +Response Packet Structures below for details. +</p> +</section> + +<section name="Basic Packet Structure"> + +<p> +There is a bit of an XDR heritage to this protocol, but it differs in +lots of ways (no 4 byte alignment, for example). +</p><p> +Byte order: I am not clear about the endian-ness of the individual +bytes. I'm guessing the bytes are little-endian, because that's what XDR +specifies, and I'm guessing that sys/socket library is magically making +that so (on the C side). If anyone with a better knowledge of socket calls +can step in, that would be great. +</p><p> +There are four data types in the protocol: bytes, booleans, integers and +strings. + +<dl> + <dt><b>Byte</b></dt> + <dd>A single byte.</dd> + + <dt><b>Boolean</b></dt> + <dd>A single byte, 1 = true, 0 = false. Using other non-zero values as + true (i.e. C-style) may work in some places, but it won't in + others.</dd> + + <dt><b>Integer</b></dt> + <dd>A number in the range of 0 to 2^16 (32768). Stored in 2 bytes with + the high-order byte first.</dd> + + <dt><b>String</b></dt> + <dd>A variable-sized string (length bounded by 2^16). Encoded with the + length packed into two bytes first, followed by the string (including the + terminating '\0'). Note that the encoded length does <b>not</b> include + the trailing '\0' -- it is like <code>strlen</code>. This is a touch + confusing on the Java side, which is littered with odd autoincrement + statements to skip over these terminators. I believe the reason this was + done was to allow the C code to be extra efficient when reading strings + which the servlet container is sending back -- with the terminating \0 + character, the C code can pass around references into a single buffer, + without copying. If the \0 was missing, the C code would have to copy + things out in order to get its notion of a string. Note a size of -1 + (65535) indicates a null string and no data follow the length in this + case.</dd> +</dl> +</p> + +<subsection name="Packet Size"> +<p> +According to much of the code, the max packet +size is 8 * 1024 bytes (8K). The actual length of the packet is encoded in the +header. +</p> +</subsection> + +<subsection name="Packet Headers"> +<p> +Packets sent from the server to the container begin with +<code>0x1234</code>. Packets sent from the container to the server begin +with <code>AB</code> (that's the ASCII code for A followed by the ASCII +code for B). After those first two bytes, there is an integer (encoded as +above) with the length of the payload. Although this might suggest that +the maximum payload could be as large as 2^16, in fact, the code sets the +maximum to be 8K. + + +<table> + <tr> + <th colspan="6">Packet Format (Server->Container)</th> + </tr> + + <tr> + <th>Byte</th> + <td>0</td> + <td>1</td> + <td>2</td> + <td>3</td> + <td>4...(n+3)</td> + </tr> + + <tr> + <th>Contents</th> + <td>0x12</td> + <td>0x34</td> + <td colspan="2">Data Length (n)</td> + <td>Data</td> + </tr> +</table> + +<table> + <tr> + <th colspan="6"><b>Packet Format (Container->Server)</b></th> + </tr> + + <tr> + <th>Byte</th> + <td>0</td> + <td>1</td> + <td>2</td> + <td>3</td> + <td>4...(n+3)</td> + </tr> + + <tr> + <th>Contents</th> + <td>A</td> + <td>B</td> + <td colspan="2">Data Length (n)</td> + <td>Data</td> + </tr> +</table> +</p> +<p> +<A NAME="prefix-codes"></A> For most packets, the first byte of the +payload encodes the type of message. The exception is for request body +packets sent from the server to the container -- they are sent with a +standard packet header (0x1234 and then length of the packet), but without +any prefix code after that (this seems like a mistake to me). +</p><p> +The web server can send the following messages to the servlet container: + +<table> + <tr> + <th>Code</th> + <th>Type of Packet</th> + <th>Meaning</th> + </tr> + <tr> + <td>2</td> + <td>Forward Request</td> + <td>Begin the request-processing cycle with the following data</td> + </tr> + <tr> + <td>7</td> + <td>Shutdown</td> + <td>The web server asks the container to shut itself down.</td> + </tr> + <tr> + <td>8</td> + <td>Ping</td> + <td>The web server asks the container to take control (secure login phase).</td> + </tr> + <tr> + <td>10</td> + <td>CPing</td> + <td>The web server asks the container to respond quickly with a CPong.</td> + </tr> + <tr> + <td>none</td> + <td>Data</td> + <td>Size (2 bytes) and corresponding body data.</td> + </tr> +</table> +</p> +<p> +To ensure some +basic security, the container will only actually do the <code>Shutdown</code> if the +request comes from the same machine on which it's hosted. +</p> +<p> +The first <code>Data</code> packet is send immediatly after the <code>Forward Request</code> by the web server. +</p> + +<p>The servlet container can send the following types of messages to the web +server: +<table> + <tr> + <th>Code</th> + <th>Type of Packet</th> + <th>Meaning</th> + </tr> + <tr> + <td>3</td> + <td>Send Body Chunk</td> + <td>Send a chunk of the body from the servlet container to the web + server (and presumably, onto the browser). </td> + </tr> + <tr> + <td>4</td> + <td>Send Headers</td> + <td>Send the response headers from the servlet container to the web + server (and presumably, onto the browser).</td> + </tr> + <tr> + <td>5</td> + <td>End Response</td> + <td>Marks the end of the response (and thus the request-handling cycle).</td> + </tr> + <tr> + <td>6</td> + <td>Get Body Chunk</td> + <td>Get further data from the request if it hasn't all been transferred + yet.</td> + </tr> + <tr> + <td>9</td> + <td>CPong Reply</td> + <td>The reply to a CPing request</td> + </tr> +</table> +</p> +<p> +Each of the above messages has a different internal structure, detailed below. +</p> +</subsection> +</section> + +<section name="Request Packet Structure"> + +<p> +For messages from the server to the container of type "Forward Request": +</p><p> +<source> +AJP13_FORWARD_REQUEST := + prefix_code (byte) 0x02 = JK_AJP13_FORWARD_REQUEST + method (byte) + protocol (string) + req_uri (string) + remote_addr (string) + remote_host (string) + server_name (string) + server_port (integer) + is_ssl (boolean) + num_headers (integer) + request_headers *(req_header_name req_header_value) + attributes *(attribut_name attribute_value) + request_terminator (byte) OxFF +</source> +</p><p> +The <code>request_headers</code> have the following structure: +</p><p> +<source> +req_header_name := + sc_req_header_name | (string) [see below for how this is parsed] + +sc_req_header_name := 0xA0xx (integer) + +req_header_value := (string) +</source> +</p><p> + +The <code>attributes</code> are optional and have the following structure: +</p><p> +<source> +attribute_name := sc_a_name | (sc_a_req_attribute string) + +attribute_value := (string) + +</source> +</p><p> +Not that the all-important header is "content-length', because it +determines whether or not the container looks for another packet +immediately. +</p><p> +Detailed description of the elements of Forward Request. +</p> +<subsection name="request_prefix"> +<p> +For all requests, this will be 2. +See above for details on other <A HREF="#prefix-codes">prefix codes</A>. +</p> +</subsection> + +<subsection name="method"> +<p> +The HTTP method, encoded as a single byte: +</p> + +<p> +<table> + <tr><th>Command Name</th><th>Code</th></tr> + <tr><td>OPTIONS</td><td>1</td></tr> + <tr><td>GET</td><td>2</td></tr> + <tr><td>HEAD</td><td>3</td></tr> + <tr><td>POST</td><td>4</td></tr> + <tr><td>PUT</td><td>5</td></tr> + <tr><td>DELETE</td><td>6</td></tr> + <tr><td>TRACE</td><td>7</td></tr> + <tr><td>PROPFIND</td><td>8</td></tr> + <tr><td>PROPPATCH</td><td>9</td></tr> + <tr><td>MKCOL</td><td>10</td></tr> + <tr><td>COPY</td><td>11</td></tr> + <tr><td>MOVE</td><td>12</td></tr> + <tr><td>LOCK</td><td>13</td></tr> + <tr><td>UNLOCK</td><td>14</td></tr> + <tr><td>ACL</td><td>15</td></tr> + <tr><td>REPORT</td><td>16</td></tr> + <tr><td>VERSION-CONTROL</td><td>17</td></tr> + <tr><td>CHECKIN</td><td>18</td></tr> + <tr><td>CHECKOUT</td><td>19</td></tr> + <tr><td>UNCHECKOUT</td><td>20</td></tr> + <tr><td>SEARCH</td><td>21</td></tr> + <tr><td>MKWORKSPACE</td><td>22</td></tr> + <tr><td>UPDATE</td><td>23</td></tr> + <tr><td>LABEL</td><td>24</td></tr> + <tr><td>MERGE</td><td>25</td></tr> + <tr><td>BASELINE_CONTROL</td><td>26</td></tr> + <tr><td>MKACTIVITY</td><td>27</td></tr> +</table> +</p> + +<p>Later version of ajp13, when used with mod_jk2, will transport +additional methods, even if they are not in this list. +</p> + +</subsection> + +<subsection name="protocol, req_uri, remote_addr, remote_host, server_name, server_port, is_ssl"> +<p> + These are all fairly self-explanatory. Each of these is required, and + will be sent for every request. +</p> +</subsection> + +<subsection name="Headers"> +<p> + The structure of <code>request_headers</code> is the following: + First, the number of headers <code>num_headers</code> is encoded. + Then, a series of header name <code>req_header_name</code> / value + <code>req_header_value</code> pairs follows. + Common header names are encoded as integers, + to save space. If the header name is not in the list of basic headers, + it is encoded normally (as a string, with prefixed length). The list of + common headers <code>sc_req_header_name</code>and their codes + is as follows (all are case-sensitive): +</p><p> +<table> + <tr><th>Name</th><th>Code value</th><th>Code name</th></tr> + <tr><td>accept</td><td>0xA001</td><td>SC_REQ_ACCEPT</td></tr> + <tr><td>accept-charset</td><td>0xA002</td><td>SC_REQ_ACCEPT_CHARSET</td></tr> + <tr><td>accept-encoding</td><td>0xA003</td><td>SC_REQ_ACCEPT_ENCODING</td></tr> + <tr><td>accept-language</td><td>0xA004</td><td>SC_REQ_ACCEPT_LANGUAGE</td></tr> + <tr><td>authorization</td><td>0xA005</td><td>SC_REQ_AUTHORIZATION</td></tr> + <tr><td>connection</td><td>0xA006</td><td>SC_REQ_CONNECTION</td></tr> + <tr><td>content-type</td><td>0xA007</td><td>SC_REQ_CONTENT_TYPE</td></tr> + <tr><td>content-length</td><td>0xA008</td><td>SC_REQ_CONTENT_LENGTH</td></tr> + <tr><td>cookie</td><td>0xA009</td><td>SC_REQ_COOKIE</td></tr> + <tr><td>cookie2</td><td>0xA00A</td><td>SC_REQ_COOKIE2</td></tr> + <tr><td>host</td><td>0xA00B</td><td>SC_REQ_HOST</td></tr> + <tr><td>pragma</td><td>0xA00C</td><td>SC_REQ_PRAGMA</td></tr> + <tr><td>referer</td><td>0xA00D</td><td>SC_REQ_REFERER</td></tr> + <tr><td>user-agent</td><td>0xA00E</td><td>SC_REQ_USER_AGENT</td></tr> +</table> +</p><p> + The Java code that reads this grabs the first two-byte integer and if + it sees an <code>'0xA0'</code> in the most significant + byte, it uses the integer in the second byte as an index into an array of + header names. If the first byte is not '0xA0', it assumes that the + two-byte integer is the length of a string, which is then read in. +</p><p> + This works on the assumption that no header names will have length + greater than 0x9999 (==0xA000 - 1), which is perfectly reasonable, though + somewhat arbitrary. (If you, like me, started to think about the cookie + spec here, and about how long headers can get, fear not -- this limit is + on header <b>names</b> not header <b>values</b>. It seems unlikely that + unmanageably huge header names will be showing up in the HTTP spec any time + soon). +</p><p> + <b>Note:</b> The <code>content-length</code> header is extremely + important. If it is present and non-zero, the container assumes that + the request has a body (a POST request, for example), and immediately + reads a separate packet off the input stream to get that body. +</p> +</subsection> + +<subsection name="Attributes"> +<p> + + The attributes prefixed with a <code>?</code> + (e.g. <code>?context</code>) are all optional. For each, there is a + single byte code to indicate the type of attribute, and then a string to + give its value. They can be sent in any order (thogh the C code always + sends them in the order listed below). A special terminating code is + sent to signal the end of the list of optional attributes. The list of + byte codes is: +</p><p> + +<table> + <tr><th>Information</th><th>Code Value</th><th>Note</th></tr> + <tr><td>?context</td><td>0x01</td><td>Not currently implemented</td></tr> + <tr><td>?servlet_path</td><td>0x02</td><td>Not currently implemented</td></tr> + <tr><td>?remote_user</td><td>0x03</td><td></td></tr> + <tr><td>?auth_type</td><td>0x04</td><td></td></tr> + <tr><td>?query_string</td><td>0x05</td><td></td></tr> + <tr><td>?route</td><td>0x06</td><td></td></tr> + <tr><td>?ssl_cert</td><td>0x07</td><td></td></tr> + <tr><td>?ssl_cipher</td><td>0x08</td><td></td></tr> + <tr><td>?ssl_session</td><td>0x09</td><td></td></tr> + <tr><td>?req_attribute</td><td>0x0A</td><td>Name (the name of the attribut follows)</td></tr> + <tr><td>?ssl_key_size</td><td>0x0B</td><td></td></tr> + <tr><td>?secret</td><td>0x0C</td><td></td></tr> + <tr><td>?stored_method</td><td>0x0D</td><td></td></tr> + <tr><td>are_done</td><td>0xFF</td><td>request_terminator</td></tr> +</table> + +</p><p> + + The <code>context</code> and <code>servlet_path</code> are not currently + set by the C code, and most of the Java code completely ignores whatever + is sent over for those fields (and some of it will actually break if a + string is sent along after one of those codes). I don't know if this is + a bug or an unimplemented feature or just vestigial code, but it's + missing from both sides of the connection. +</p><p> + The <code>remote_user</code> and <code>auth_type</code> presumably refer + to HTTP-level authentication, and communicate the remote user's username + and the type of authentication used to establish their identity (e.g. Basic, + Digest). I'm not clear on why the password isn't also sent, but I don't + know HTTP authentication inside and out. +</p><p> + The <code>query_string</code>, <code>ssl_cert</code>, + <code>ssl_cipher</code>, and <code>ssl_session</code> refer to the + corresponding pieces of HTTP and HTTPS. +</p><p> + The <code>route</code>, as I understand it, is used to support sticky + sessions -- associating a user's sesson with a particular Tomcat instance + in the presence of multiple, load-balancing servers. I don't know the + details. +</p><p> + Beyond this list of basic attributes, any number of other attributes can + be sent via the <code>req_attribute</code> code (0x0A). A pair of strings + to represent the attribute name and value are sent immediately after each + instance of that code. Environment values are passed in via this method. +</p><p> + Finally, after all the attributes have been sent, the attribute terminator, + 0xFF, is sent. This signals both the end of the list of attributes and + also then end of the Request Packet. +</p> +</subsection> + +</section> + +<section name="Response Packet Structure"> + +<p> +For messages which the container can send back to the server. + +<source> +AJP13_SEND_BODY_CHUNK := + prefix_code 3 + chunk_length (integer) + chunk *(byte) + + +AJP13_SEND_HEADERS := + prefix_code 4 + http_status_code (integer) + http_status_msg (string) + num_headers (integer) + response_headers *(res_header_name header_value) + +res_header_name := + sc_res_header_name | (string) [see below for how this is parsed] + +sc_res_header_name := 0xA0 (byte) + +header_value := (string) + +AJP13_END_RESPONSE := + prefix_code 5 + reuse (boolean) + + +AJP13_GET_BODY_CHUNK := + prefix_code 6 + requested_length (integer) +</source> + +</p> +<p> +Details: +</p> + +<subsection name="Send Body Chunk"> +<p> + The chunk is basically binary data, and is sent directly back to the browser. +</p> +</subsection> + +<subsection name="Send Headers"> +<p> + The status code and message are the usual HTTP things (e.g. "200" and "OK"). + The response header names are encoded the same way the request header names are. + See <A HREF="#header_encoding">above</A> for details about how the the + codes are distinguished from the strings. The codes for common headers are: +</p> + +<p> +<table> + <tr><th>Name</th><th>Code value</th></tr> + <tr><td>Content-Type</td><td>0xA001</td></tr> + <tr><td>Content-Language</td><td>0xA002</td></tr> + <tr><td>Content-Length</td><td>0xA003</td></tr> + <tr><td>Date</td><td>0xA004</td></tr> + <tr><td>Last-Modified</td><td>0xA005</td></tr> + <tr><td>Location</td><td>0xA006</td></tr> + <tr><td>Set-Cookie</td><td>0xA007</td></tr> + <tr><td>Set-Cookie2</td><td>0xA008</td></tr> + <tr><td>Servlet-Engine</td><td>0xA009</td></tr> + <tr><td>Status</td><td>0xA00A</td></tr> + <tr><td>WWW-Authenticate</td><td>0xA00B</td></tr> +</table> + +</p> + +<p> + After the code or the string header name, the header value is immediately + encoded. +</p> + +</subsection> + +<subsection name="End Response"> +<p> + Signals the end of this request-handling cycle. If the + <code>reuse</code> flag is true (==1), this TCP connection can now be used to + handle new incoming requests. If <code>reuse</code> is false (anything + other than 1 in the actual C code), the connection should be closed. +</p> +</subsection> + +<subsection name="Get Body Chunk"> +<p> + The container asks for more data from the request (If the body was + too large to fit in the first packet sent over or when the request is + chuncked). + The server will send a body packet back with an amount of data which is + the minimum of the <code>request_length</code>, + the maximum send body size (8186 (8 Kbytes - 6)), and the + number of bytes actually left to send from the request body. +<br/> + If there is no more data in the body (i.e. the servlet container is + trying to read past the end of the body), the server will send back an + "empty" packet, which is a body packet with a payload length of 0. + (0x12,0x34,0x00,0x00) +</p> +</subsection> +</section> + +<section name="Questions I Have"> + +<p> What happens if the request headers > max packet size? There is no +provision to send a second packet of request headers in case there are more +than 8K (I think this is correctly handled for response headers, though I'm +not certain). I don't know if there is a way to get more than 8K worth of +data into that initial set of request headers, but I'll bet there is +(combine long cookies with long ssl information and a lot of environment +variables, and you should hit 8K easily). I think the connector would just +fail before trying to send any headers in this case, but I'm not certain.</p> + +<p> What about authentication? There doesn't seem to be any authentication +of the connection between the web server and the container. This strikes +me as potentially dangerous.</p> + +</section> + +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/ajp/ajpv13ext.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/ajp/ajpv13ext.xml new file mode 100644 index 00000000..d3c8c3a0 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/ajp/ajpv13ext.xml @@ -0,0 +1,686 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="ajpv13ext.html"> + + &project; +<copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> +<properties> +<title>AJPv13 extensions Proposal</title> +<author email="hgomez@apache.org">Henri Gomez</author> +<date>$Date: 2006-12-03 13:55:56 +0100 (Sun, 03 Dec 2006) $</date> +</properties> +<body> +<section name="Introduction"> +<p> +This document is a proposal of evolution of the current +Apache JServ Protocol version 1.3, also known as ajp13. +I'll not cover here the full protocol but only the add-on from ajp13. + +This nth pass include comments from the tomcat-dev list and +misses discovered during developpment. +</p> +<subsection name="Missing features in AJP13"> +<p> +ajp13 is a good protocol to link a servlet engine like tomcat to a web server like Apache: + +<ul> +<li> +use persistants connections to avoid reconnect time at each request +</li> +<li> +encode many http commands to reduce stream size +</li> +<li> +send to servlet engine many info from web server (like SSL certs) +</li> +</ul> +<p> +But ajp13 lacks support for : +</p> +<ul> +<li> + security between web server and servlet engine. + Anybody can connect to an ajp13 port (no login mecanism used) + You could connect, for example with telnet, and keep the remote thread + up by not sending any data (no timeout in connection) +</li> +<li> + context information passed from servlet engine to web server. + Part of the configuration of JK, the web server connector, is to + indicate to the web server which URI to handle. + The mod_jk JkMount directive, told to web server which URI must be + forwarded to servlet engine. + A servlet engine allready knows which URI it handle and TC 3.3 is + allready capable to generate a config file for JK from the list + of available contexts. +</li> +<li> + state update of contexts from servlet engine to web server. + Big site with farm of Tomcat, like ISP and virtuals hosters, + may need to stop a context for admin purposes. In that case the front + web server must know that the context is currently down, to eventually + relay the request to another Tomcat +</li> +<li> + verify state of connection before sending request. + Actually JK send the request to the servlet engine and next wait + for the answer. But one of the beauty of the socket API, is you that + you could write() to a closed connection without any error reporting, + but a read() to a closed connection return you the error code. +</li> +</ul> + +</p> +</subsection> + +<subsection name="Proposed add-ons to AJP13"> +<p> +Let's descrive here the features and add-on that could be added to AJP13. +Since this document is a proposal, a reasonable level of chaos must be expected at first. +Be sure that discussion on tomcat list will help clarify points, add +features but the current list seems to be a 'minimun vital' + +<ul> + +<li> +Advanced login features at connect time +</li> + +<li> +Basic authorisation system, where a shared secret key is +present in web server and servlet engine. +</li> + +<li> +Basic protocol negociation, just to be sure that if functionnalities are added +to AJP13 in the future, current implementations will still works. +</li> + +<li> +Clean handling of 'Unknown packets' +</li> + +<li> +Extended env vars passed from web-server to servlet engine. +</li> + +<li> +Add extra SSL informations needed by Servlet 2.3 API (like SSL_KEY_SIZE) +</li> + +</ul> + +</p> +</subsection> + +<subsection name="Advanced login"> +<p> + +<ol> +<li> +WEB-SERVER send LOGIN INIT CMD + NEGOCIATION DATA + WEB SERVER INFO +</li> +<li> + TOMCAT respond with LOGIN SEED CMD + RANDOM DATA +</li> +<li> + WEB-SERVER calculted the MD5 of RANDOM DATA+SECRET DATA +</li> +<li> + WEB-SERVER send LOGIN COMP CMD + MD5 (SECRET DATA + RANDOM DATA) +</li> +<li> + TOMCAT respond with LOGIN STATUS CMD + NEGOCIED DATA + SERVLET ENGINE INFO +</li> +</ol> + +To prevent DOS attack, the servlet engine will wait +the LOGIN CMD only 15/30 seconds and reports the +timeout exception for admins investigation. + +The login command will contains basic protocol +negociation information like compressing ability, +crypto, context info (at start up), context update at +run-time (up/down), level of SSL env vars, AJP protocol +level supported (level1/level2/level3...) + +The Web server info will contain web server info and +connector name (ie Apache 1.3.26 + mod_ssl 2.8.8 + mod_jk 1.2.1 + mod_perl 1.25). + +The servlet engine will mask the negociation mask with it's own +mask (what it can do) and return it when loggin is accepted. + +This will help having a basic AJP13 implementation (level 1) +on a web-server working with a more advanced protocol handler on +the servlet engine side or vice-versa. + +AJP13 was designed to be small and fast and so many +SSL informations present in the web-server are not +forwarded to the servlet engine. + +We add here four negociations flags to provide more +informations on client SSL data (certs), server SSL datas, +crypto used, and misc datas (timeout...). +</p> +</subsection> + +<subsection name="Messages Stream"> +<p> +<source> ++----------------+------------------+-----------------+ +| LOGIN INIT CMD | NEGOCIATION DATA | WEB SERVER INFO | ++----------------+------------------+-----------------+ + ++----------------+----------------+ +| LOGIN SEED CMD | MD5 of entropy | ++----------------+----------------+ + ++----------------+----------------------------+ +| LOGIN COMP CMD | MD5 of RANDOM + SECRET KEY | ++----------------+----------------------------+ + ++-----------+---------------+---------------------+ +| LOGOK CMD | NEGOCIED DATA | SERVLET ENGINE INFO | ++-----------+---------------+---------------------+ + ++------------+--------------+ +| LOGNOK CMD | FAILURE CODE | ++------------+--------------+ +</source> + +<ul> +<li> +LOGIN INIT CMD, LOGIN SEED CMD, LOGIN COMP CMD, LOGOK CMD, LOGNOK CMD are 1 byte long. +</li> +<li> +MD5, MD5 of RANDOM + SECRET KEY are 32 chars long. +</li> +<li> +NEGOCIATION DATA, NEGOCIED DATA, FAILURE CODE are 32 bits long. +</li> +<li> +WEB SERVER INFO, SERVLET ENGINE INFO are CString. +</li> +</ul> + +The secret key will be set by a new propertie in +workers.properties : secretkey +<source> +worker.ajp13.port=8009 +worker.ajp13.host=localhost +worker.ajp13.type=ajp13 +worker.ajp13.secretkey=myverysecretkey +</source> +</p> +</subsection> + +<subsection name="Shutdown feature"> +<p> +AJP13 miss a functionnality of AJP12, which is shutdown command. +A logout will tell servlet engine to shutdown itself. +<source> ++--------------+----------------------------+ +| SHUTDOWN CMD | MD5 of RANDOM + SECRET KEY | ++--------------+----------------------------+ + ++------------+ +| SHUTOK CMD | ++------------+ + ++-------------+--------------+ +| SHUTNOK CMD | FAILURE CODE | ++-------------+--------------+ +</source> + +<ul> +<li> +SHUTDOWN CMD, SHUTOK CMD, SHUTNOK CMD are 1 byte long. +</li> +<li> +MD5 of RANDOM + SECRET KEY are 32 chars long. +</li> +<li> +FAILURE CODE is 32 bits long. +</li> +</ul> + +</p> +</subsection> + +<subsection name="Extended Env Vars feature"> +<p> +NOTA: + +While working on AJP13 in JK, I really discovered "JkEnvVar". +The following "Extended Env Vars feature" description may not +be implemented in extended AJP13 since allready available in original +implementation. + +DESC: + +Many users will want to see some of their web-server env vars +passed to their servlet engine. + +To reduce the network traffic, the web-servlet will send a +table to describing the external vars in a shorter fashion. + +We'll use there a functionnality allready present in AJP13, +attributes list : + +In the AJP13, we've got : + +<source> +AJP13_FORWARD_REQUEST := + prefix_code 2 + method (byte) + protocol (string) + req_uri (string) + remote_addr (string) + remote_host (string) + server_name (string) + server_port (integer) + is_ssl (boolean) + num_headers (integer) + request_headers *(req_header_name req_header_value) + + ?context (byte string) + ?servlet_path (byte string) + ?remote_user (byte string) + ?auth_type (byte string) + ?query_string (byte string) + ?route (byte string) + ?ssl_cert (byte string) + ?ssl_cipher (byte string) + ?ssl_session (byte string) + + ?attributes *(attribute_name attribute_value) + request_terminator (byte) +</source> + +Using short 'web server attribute name' will reduce the +network traffic. + +<source> ++-------------------+---------------------------+-------------------------------+----+ +| EXTENDED VARS CMD | WEB SERVER ATTRIBUTE NAME | SERVLET ENGINE ATTRIBUTE NAME | ES | ++-------------------+---------------------------+-------------------------------+----+ +</source> + +ie : + +<source> +JkExtVars S1 SSL_CLIENT_V_START javax.servlet.request.ssl_start_cert_date +JkExtVars S2 SSL_CLIENT_V_END javax.servlet.request.ssl_end_cert_date +JkExtVars S3 SSL_SESSION_ID javax.servlet.request.ssl_session_id + + ++-------------------+----+-------------------------------------------+ +| EXTENDED VARS CMD | S1 | javax.servlet.request.ssl_start_cert_date | ++-------------------+----+-------------------------------------------+ ++----+-----------------------------------------+ +| S2 | javax.servlet.request.ssl_end_cert_date | ++----+-----------------------------------------+ ++----+-----------------------------------------+ +| S3 | javax.servlet.request.ssl_end_cert_date | ++----+-----------------------------------------+ +</source> + +During transmission in extended AJP13 we'll see attributes name +containing S1, S2, S3 and attributes values of +2001/01/03, 2002/01/03, 0123AFE56. + +This example showed the use of extended SSL vars but +any 'personnal' web-server vars like custom authentification +vars could be reused in the servlet engine. +The cost will be only some more bytes in the AJP traffic. + +<ul> +<li> +EXTENDED VARS CMD is 1 byte long. +</li> +<li> +WEB SERVER ATTRIBUTE NAME, SERVLET ENGINE ATTRIBUTE NAME are CString. +</li> +<li> +ES is an empty CString. +</li> +</ul> + +</p> +</subsection> + +<subsection name="Context informations forwarding for Servlet engine to Web Server"> +<p> +Just after the LOGON PHASE, the web server will ask for the list of contexts +and URLs/URIs handled by the servlet engine. +It will ease installation in many sites, reduce questions about configuration +on tomcat-user list, and be ready for servlet API 2.3. + +This mode will be activated by a new directive JkAutoMount + +ie: JkAutoMount examples myworker1 /examples/ + +If we want to get ALL the contexts handled by the servlet engine, willcard +could be used : + +ie: JkAutoMount * myworker1 * + +A servlet engine could have many contexts, /examples, /admin, /test. +We may want to use only some contexts for a given worker. It was +done previously, in apache HTTP server for example, by setting by +hand the JkMount accordingly in each [virtual] area of Apache. + +If you web-server support virtual hosting, we'll forward also that +information to servlet engine which will only return contexts for +that virtual host. +In that case the servlet engine will only return the URL/URI matching +these particular virtual server (defined in server.xml). +This feature will help ISP and big sites which mutualize large farm +of Tomcat in load-balancing configuration. + +<source> ++-----------------+-------------------+----------+----------+----+ +| CONTEXT QRY CMD | VIRTUAL HOST NAME | CONTEXTA | CONTEXTB | ES | ++-----------------+-------------------+----------+----------+----+ + ++------------------+-------------------+----------+-------------------+----------+---------------+----+ +| CONTEXT INFO CMD | VIRTUAL HOST NAME | CONTEXTA | URL1 URL2 URL3 ES | CONTEXTB | URL1 URL2 ... | ES | ++------------------+-------------------+----------+-------------------+----------+---------------+----+ +</source> + +We'll discover via context-query, the list of URL/MIMES handled by the remove servlet engine +for a list of contextes. +In wildcard mode, CONTEXTA will contains just '*'. + +<ul> +<li> +CONTEXT QRY CMD and CONTEXT INFO CMD are 1 byte long. +</li> +<li> +VIRTUAL HOST NAME is a CString, ie an array of chars terminated by a null byte (/0). +</li> +<li> +An empty string is just a null byte (/0). +</li> +<li> +ES is an empty CString. Indicate end of URI/URLs or end of CONTEXTs. +</li> +</ul> + +NB:<br/> +When VirtualMode is not to be used, the VIRTUAL HOST NAME is '*'. +In that case the servlet engine will send all contexts handled. +</p> +</subsection> + +<subsection name="Context informations updates from Servlet engine to Web Server"> +<p> +Context update are messages caming from the servlet engine each time a context +is desactivated/reactivated. The update will be in use when the directive JkUpdateMount. +This directive will set the AJP13_CONTEXT_UPDATE_NEG flag. + +ie: JkUpdateMount myworker1 + +<source> ++--------------------+-------------------+----------+--------+----------+--------+----+ +| CONTEXT UPDATE CMD | VIRTUAL HOST NAME | CONTEXTA | STATUS | CONTEXTB | STATUS | ES | ++--------------------+-------------------+----------+--------+----------+--------+----+ +</source> + +<ul> +<li> +CONTEXT UPDATE CMD, STATUS are 1 byte long. +</li> +<li> +VIRTUAL HOST NAME, CONTEXTS are CString. +</li> +<li> +ES is an empty CString. Indicate end of CONTEXTs. +</li> +</ul> + +NB:<br/> +When VirtualMode is not in use, the VIRTUAL HOST NAME is '*'. +STATUS is one byte indicating if context is UP/DOWN/INVALID +</p> +</subsection> + +<subsection name="Context status query to Servlet engine"> +<p> +This query will be used by the web-server to determine if a given +contexts are UP, DOWN or INVALID (and should be removed). + +<source> ++-------------------+--------------------+----------+----------+----+ +| CONTEXT STATE CMD | VIRTUAL HOST NAME | CONTEXTA | CONTEXTB | ES | ++-------------------+--------------------+----------+----------+----+ + ++-------------------------+-------------------+----------+--------+----------+--------+----+ +| CONTEXT STATE REPLY CMD | VIRTUAL HOST NAME | CONTEXTA | STATUS | CONTEXTB | STATUS | ES | ++-------------------------+-------------------+----------+-------------------+--------+----+ +</source> + +<ul> +<li> +CONTEXT STATE CMD, CONTEXT STATE REPLY CMD, STATUS are 1 byte long. +</li> +<li> +VIRTUAL HOST NAME, CONTEXTs are CString +</li> +<li> +ES is an empty CString +</li> +</ul> + +NB:<br/> +When VirtualMode is not in use, the VIRTUAL HOST NAME is an empty string. +</p> +</subsection> + +<subsection name="Handling of unknown packets"> +<p> +Sometimes even with a well negocied protocol, we may be in a situation +where one end (web server or servlet engine), will receive a message it +couldn't understand. In that case the receiver will send an +'UNKNOW PACKET CMD' with attached the unhandled message. + +<source> ++--------------------+------------------------+-------------------+ +| UNKNOWN PACKET CMD | UNHANDLED MESSAGE SIZE | UNHANDLED MESSAGE | ++--------------------+------------------------+-------------------+ +</source> + +Depending on the message, the sender will report an error and if +possible will try to forward the message to another endpoint. + +<ul> +<li> +UNKNOWN PACKET CMD is 1 byte long. +</li> +<li> +UNHANDLED MESSAGE SIZE is 16bits long. +</li> +<li> +UNHANDLED MESSAGE is an array of byte (length is contained in UNHANDLED MESSAGE SIZE) +</li> +</ul> + +NB:<br/> +added UNHANDLED MESSAGE SIZE (development) +</p> +</subsection> + +<subsection name="Verification of connection before sending request"> +<p> +NOTA: This fonctionality may never be used, since it may slow up the normal process +since requiring on the web-server side an extra IO (read) before forwarding +the request..... + +One of the beauty of socket APIs, is that you could write on a half closed socket. +When servlet engine close the socket, the web server will discover it only at the +next read() to the socket. +Basically, in the AJP13 protocol, the web server send the HTTP HEADER and HTTP BODY +(POST by chunk of 8K) to the servlet engine and then try to receive the reply. +If the connection was broken the web server will learn it only at receive time. + +We could use a buffering scheme but what happen when you use the servlet engine +for upload operations with more than 8ko of datas ? + +The hack in the AJP13 protocol is to add some bytes to read after the end of the +service : + +<source> +EXAMPLE OF DISCUSSION BETWEEN WEB SERVER AND SERVLET ENGINE + +AJP HTTP-HEADER (+ HTTP-POST) (WEB->SERVLET) + +AJP HTTP-REPLY (SERVLET->WEB) + +AJP END OF DISCUSSION (SERVLET->WEB) + +---> AJP STATUS (SERVLET->WEB AJP13) +</source> + +The AJP STATUS will not be read by the servlet engine at the end of +the request/response #N but at the begining of the next session. + +More at that time the web server could also use OS dependants functions +(or better APR functions) to determine if there is also more data +to read. And that datas could be CONTEXT Updates. + +This will avoid the web server sending a request to a +desactivated context. In that case, if the load-balancing is used, +it will search for another servlet engine to handle the request. + +And that feature will help ISP and big sites with farm of tomcat, +to updates their servlet engine without any service interruption. + +<source> ++------------+-------------+ +| STATUS CMD | STATUS DATA | ++------------+-------------+ +</source> + +<ul> +<li> +STATUS CMD and STATUS DATA are one byte long. +</li> +</ul> +</p> +</subsection> + +</section> + +<section name="Conclusion"> +<p> +The goal of the extended AJP13 protocol is to overcome some of the original AJP13 limitation. +An easier configuration, a better support for large site and farm of Tomcat, +a simple authentification system and provision for protocol updates. + +Using the stable ajp13 implementation in JK (native) and in servlet +engine (java), it's a reasonable evolution of the well known ajp13. +</p> +</section> + +<section name="Commands and IDs in extended AJP13 Index"> +<p> +Index of Commands and ID to be added in AJP13 Protocol +</p> + +<subsection name="Commands IDs"> +<p> +<table> + <tr><th>Command Name</th><th>Command Number</th></tr> + <tr><td>AJP13_LOGINIT_CMD</td><td>0x10</td></tr> + <tr><td>AJP13_LOGSEED_CMD</td><td>0x11</td></tr> + <tr><td>AJP13_LOGCOMP_CMD</td><td>0x12</td></tr> + <tr><td>AJP13_LOGOK_CMD</td><td>0x13</td></tr> + <tr><td>AJP13_LOGNOK_CMD</td><td>0x14</td></tr> + <tr><td>AJP13_CONTEXT_QRY_CMD</td><td>0x15</td></tr> + <tr><td>AJP13_CONTEXT_INFO_CMD</td><td>0x16</td></tr> + <tr><td>AJP13_CONTEXT_UPDATE_CMD</td><td>0x17</td></tr> + <tr><td>AJP13_STATUS_CMD</td><td>0x18</td></tr> + <tr><td>AJP13_SHUTDOWN_CMD</td><td>0x19</td></tr> + <tr><td>AJP13_SHUTOK_CMD</td><td>0x1A</td></tr> + <tr><td>AJP13_SHUTNOK_CMD</td><td>0x1B</td></tr> + <tr><td>AJP13_CONTEXT_STATE_CMD</td><td>0x1C</td></tr> + <tr><td>AJP13_CONTEXT_STATE_REP_CMD</td><td>0x1D</td></tr> + <tr><td>AJP13_UNKNOW_PACKET_CMD</td><td>0x1E</td></tr> +</table> + +</p> +</subsection> + +<subsection name="Negociations Flags"> +<p> +<table> + <tr><th>Command Name</th><th>Number</th><th>Description</th></tr> + <tr><td>AJP13_CONTEXT_INFO_NEG</td><td>0x80000000</td><td>web-server want context info after login</td></tr> + <tr><td>AJP13_CONTEXT_UPDATE_NEG</td><td>0x40000000</td><td>web-server want context updates</td></tr> + <tr><td>AJP13_GZIP_STREAM_NEG</td><td>0x20000000</td><td>web-server want compressed stream</td></tr> + <tr><td>AJP13_DES56_STREAM_NEG</td><td>0x10000000</td><td>web-server want crypted DES56 stream with secret key</td></tr> + <tr><td>AJP13_SSL_VSERVER_NEG</td><td>0x08000000</td><td>Extended info on server SSL vars</td></tr> + <tr><td>AJP13_SSL_VCLIENT_NEG</td><td>0x04000000</td><td>Extended info on client SSL vars</td></tr> + <tr><td>AJP13_SSL_VCRYPTO_NEG</td><td>0x02000000</td><td>Extended info on crypto SSL vars</td></tr> + <tr><td>AJP13_SSL_VMISC_NEG</td><td>0x01000000</td><td>Extended info on misc SSL vars</td></tr> +</table> + +<br/> + +<table> + <tr><th>Negociation ID</th><th>Number</th><th>Description</th></tr> + <tr><td>AJP13_PROTO_SUPPORT_AJPXX_NEG</td><td>0x00FF0000</td><td>mask of protocol supported</td></tr> + <tr><td>AJP13_PROTO_SUPPORT_AJP13L1_NEG</td><td>0x00010000</td><td>communication could use AJP13 Level 1</td></tr> + <tr><td>AJP13_PROTO_SUPPORT_AJP13L2_NEG</td><td>0x00020000</td><td>communication could use AJP13 Level 2</td></tr> + <tr><td>AJP13_PROTO_SUPPORT_AJP13L3_NEG</td><td>0x00040000</td><td>communication could use AJP13 Level 3</td></tr> +</table> + +<br/> +All others flags must be set to 0 since they are reserved for future use. + +</p> +</subsection> + +<subsection name="Failure IDs"> +<p> +<table> + <tr><th>Failure Id</th><th>Number</th></tr> + <tr><td>AJP13_BAD_KEY_ERR</td><td>0xFFFFFFFF</td></tr> + <tr><td>AJP13_ENGINE_DOWN_ERR</td><td>0xFFFFFFFE</td></tr> + <tr><td>AJP13_RETRY_LATER_ERR</td><td>0xFFFFFFFD</td></tr> + <tr><td>AJP13_SHUT_AUTHOR_FAILED_ERR</td><td>0xFFFFFFFC</td></tr> +</table> +</p> +</subsection> + +<subsection name="Status"> +<p> +<table> + <tr><th>Failure Id</th><th>Number</th></tr> + <tr><td>AJP13_CONTEXT_DOWN</td><td>0x01</td></tr> + <tr><td>AJP13_CONTEXT_UP</td><td>0x02</td></tr> + <tr><td>AJP13_CONTEXT_OK</td><td>0x03</td></tr> +</table> +</p> +</subsection> + +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/ajp/project.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/ajp/project.xml new file mode 100644 index 00000000..ad8a5efc --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/ajp/project.xml @@ -0,0 +1,81 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<project name="Apache Tomcat Connector Documentation - AJP Protocol Reference" + href="http://tomcat.apache.org/"> + + <title>The Apache Tomcat Connector - AJP Protocol Reference</title> + + <logo href="/images/tomcat.gif"> + The Apache Tomcat Connector - AJP Protocol Reference + </logo> +<body> + + <menu name="Links"> + <item name="Docs Home" href="../index.html"/> + </menu> + + <menu name="Reference Guide"> + <item name="workers.properties" href="../reference/workers.html"/> + <item name="uriworkermap.properties" href="../reference/uriworkermap.html"/> + <item name="Status Worker" href="../reference/status.html"/> + <item name="Apache HTTP Server" href="../reference/apache.html"/> + <item name="IIS" href="../reference/iis.html"/> + </menu> + + <menu name="Generic HowTo"> + <item name="For the impatient" href="../generic_howto/quick.html"/> + <item name="All about workers" href="../generic_howto/workers.html"/> + <item name="Timeouts" href="../generic_howto/timeouts.html"/> + <item name="Load Balancing" href="../generic_howto/loadbalancers.html"/> + <item name="Reverse Proxy" href="../generic_howto/proxy.html"/> + </menu> + + <menu name="Webserver HowTo"> + <item name="Apache HTTP Server" href="../webserver_howto/apache.html"/> + <item name="IIS" href="../webserver_howto/iis.html"/> + <item name="Netscape/SunOne/Sun" href="../webserver_howto/nes.html"/> + </menu> + + <menu name="AJP Protocol Reference"> + <item name="AJPv13" href="../ajp/ajpv13a.html"/> + <item name="AJPv13 Extension Proposal" href="../ajp/ajpv13ext.html"/> + </menu> + + <menu name="Miscellaneous Documentation"> + <item name="Frequently asked questions" href="../miscellaneous/faq.html"/> + <item name="Changelog" href="../miscellaneous/changelog.html"/> + <item name="Current Tomcat Connectors bugs" href="http://issues.apache.org/bugzilla/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Tomcat+Connectors&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0="/> + <item name="Contribute documentation" href="../miscellaneous/doccontrib.html"/> + <item name="JK Status Ant Tasks" href="../miscellaneous/jkstatustasks.html"/> + <item name="Reporting Tools" href="../miscellaneous/reporttools.html"/> + <item name="Old JK/JK2 documentation" href="http://tomcat.apache.org/connectors-doc-archive/jk2/index.html"/> + </menu> + + <menu name="News"> + <item name="2011" href="../news/20110701.html"/> + <item name="2010" href="../news/20100101.html"/> + <item name="2009" href="../news/20090301.html"/> + <item name="2008" href="../news/20081001.html"/> + <item name="2007" href="../news/20070301.html"/> + <item name="2006" href="../news/20060101.html"/> + <item name="2005" href="../news/20050101.html"/> + <item name="2004" href="../news/20041100.html"/> + </menu> + +</body> +</project> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/build.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/build.xml new file mode 100644 index 00000000..800649f4 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/build.xml @@ -0,0 +1,259 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<project name="tomcat-docs" default="build-main" basedir="."> + + + <!-- ===================== Initialize Property Values =================== --> + + <!-- See "build.properties.sample" in the top level directory for all --> + <!-- property values you must customize for successful building!!! --> + <property file="build.properties"/> + <property file="../build.properties"/> + <property file="../../build.properties"/> + <property file="${user.home}/build.properties"/> + + <property name="build.compiler" value="modern"/> + <property name="build.dir" value="../build"/> + <property name="dist.dir" value="../dist"/> + <property name="dist.name" value="docs"/> + + + <!-- =================== BUILD: Create Directories ====================== --> + <target name="build-prepare"> + <mkdir dir="${build.dir}"/> + <mkdir dir="${build.dir}/${dist.name}"/> + </target> + + + <!-- ================ BUILD: Copy Static Files ========================== --> + <target name="build-static" depends="build-prepare"> + + <!-- Top Level Static Files --> + <copy todir="${build.dir}/${dist.name}"> + <fileset dir="."> + <include name="BUILDING.txt"/> + <include name="README.txt"/> + <include name="RUNNING.txt"/> + <include name="style.css"/> + </fileset> + </copy> + <copy todir="${build.dir}/${dist.name}"> + <fileset dir="." includes="**/*.html"/> + </copy> + + <!-- Images Subdirectory --> + <mkdir dir="${build.dir}/${dist.name}/images"/> + <copy todir="${build.dir}/${dist.name}/images"> + <fileset dir="images"/> + </copy> + + <mkdir dir="${build.dir}/${dist.name}/printer"/> + <!-- Top Level Static Files --> + <copy todir="${build.dir}/${dist.name}/printer"> + <fileset dir="."> + <include name="BUILDING.txt"/> + <include name="README.txt"/> + <include name="RUNNING.txt"/> + </fileset> + </copy> + <style basedir="." + destdir="${build.dir}/${dist.name}/printer" + extension=".html" + style="style.xsl" + excludes="build.xml project.xml empty.xml" + includes="*.xml"> + <param name="relative-path" expression="./.."/> + <param name="project-menu" expression="nomenu"/> + </style> + + <!-- Reference Guide --> + <style basedir="reference" + destdir="${build.dir}/${dist.name}/reference" + extension=".html" + style="style.xsl" + excludes="project.xml" + includes="*.xml"> + <param name="relative-path" expression=".."/> + </style> + <mkdir dir="${build.dir}/${dist.name}/reference/printer"/> + <style basedir="reference" + destdir="${build.dir}/${dist.name}/reference/printer" + extension=".html" + style="style.xsl" + excludes="project.xml" + includes="*.xml"> + <param name="relative-path" expression="../.."/> + <param name="project-menu" expression="nomenu"/> + </style> + + <!-- Generic Howto --> + <style basedir="generic_howto" + destdir="${build.dir}/${dist.name}/generic_howto" + extension=".html" + style="style.xsl" + excludes="project.xml" + includes="*.xml"> + <param name="relative-path" expression=".."/> + </style> + <mkdir dir="${build.dir}/${dist.name}/generic_howto/printer"/> + <style basedir="generic_howto" + destdir="${build.dir}/${dist.name}/generic_howto/printer" + extension=".html" + style="style.xsl" + excludes="project.xml" + includes="*.xml"> + <param name="relative-path" expression="../.."/> + <param name="project-menu" expression="nomenu"/> + </style> + + <!-- Webserver Howto --> + <style basedir="webserver_howto" + destdir="${build.dir}/${dist.name}/webserver_howto" + extension=".html" + style="style.xsl" + excludes="project.xml" + includes="*.xml"> + <param name="relative-path" expression=".."/> + </style> + <mkdir dir="${build.dir}/${dist.name}/webserver_howto/printer"/> + <style basedir="webserver_howto" + destdir="${build.dir}/${dist.name}/webserver_howto/printer" + extension=".html" + style="style.xsl" + excludes="project.xml" + includes="*.xml"> + <param name="relative-path" expression="../.."/> + <param name="project-menu" expression="nomenu"/> + </style> + + <!-- AJP Protocol Reference --> + <style basedir="ajp" + destdir="${build.dir}/${dist.name}/ajp" + extension=".html" + style="style.xsl" + excludes="project.xml" + includes="*.xml"> + <param name="relative-path" expression=".."/> + </style> + <mkdir dir="${build.dir}/${dist.name}/ajp/printer"/> + <style basedir="ajp" + destdir="${build.dir}/${dist.name}/ajp/printer" + extension=".html" + style="style.xsl" + excludes="project.xml" + includes="*.xml"> + <param name="relative-path" expression="../.."/> + <param name="project-menu" expression="nomenu"/> + </style> + + <!-- Miscellaneous Documentation --> + <style basedir="miscellaneous" + destdir="${build.dir}/${dist.name}/miscellaneous" + extension=".html" + style="style.xsl" + excludes="project.xml" + includes="*.xml"> + <param name="relative-path" expression=".."/> + </style> + <mkdir dir="${build.dir}/${dist.name}/miscellaneous/printer"/> + <style basedir="miscellaneous" + destdir="${build.dir}/${dist.name}/miscellaneous/printer" + extension=".html" + style="style.xsl" + excludes="project.xml" + includes="*.xml"> + <param name="relative-path" expression="../.."/> + <param name="project-menu" expression="nomenu"/> + </style> + + <!-- News --> + <style basedir="news" + destdir="${build.dir}/${dist.name}/news" + extension=".html" + style="style.xsl" + excludes="project.xml" + includes="*.xml"> + <param name="relative-path" expression=".."/> + </style> + <mkdir dir="${build.dir}/${dist.name}/news/printer"/> + <style basedir="news" + destdir="${build.dir}/${dist.name}/news/printer" + extension=".html" + style="style.xsl" + excludes="project.xml" + includes="*.xml"> + <param name="relative-path" expression="../.."/> + <param name="project-menu" expression="nomenu"/> + </style> + + </target> + + + <!-- ================= BUILD: XML-HTML Generation ======================= --> + <target name="build-main" depends="build-static"> + + <!-- Top Level Directory --> + <style basedir="." + destdir="${build.dir}/${dist.name}" + extension=".html" + style="style.xsl" + excludes="build.xml project.xml empty.xml" + includes="*.xml"> + <param name="relative-path" expression="."/> + </style> + + </target> + + + <!-- ==================== BUILD: Rebuild Everything ===================== --> + <target name="all" depends="build-clean,build-main" + description="Clean and build documentation"/> + + + <!-- ======================= BUILD: Clean Directory ===================== --> + <target name="build-clean"> + <delete dir="${build.dir}/${dist.name}"/> + </target> + + + <!-- ======================= DIST: Create Directories =================== --> + <target name="dist-prepare"> + <mkdir dir="${dist.dir}"/> + </target> + + + <!-- ======================= DIST: Create Distribution Files ============ --> + <target name="dist" depends="build-main,dist-prepare" + description="Create documentation binary distribution"> + <jar jarfile="${dist.dir}/${dist.name}.war" + basedir="${build.dir}/${dist.name}" includes="**"/> + </target> + + + <!-- ======================= DIST: Clean Directory ====================== --> + <target name="dist-clean"> + <delete dir="${dist.dir}/${dist.name}"/> + </target> + + + <!-- ====================== Convenient Synonyms ========================= --> + <target name="clean" depends="build-clean,dist-clean" + description="Clean build and dist directories"/> + + +</project> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/empty.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/empty.xml new file mode 100644 index 00000000..ead4ae08 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/empty.xml @@ -0,0 +1,40 @@ +<?xml version="1.0"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="empty.html"> + &project; +<copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> +<properties> + +<title>Empty template</title> +<author email="developer@apache.org">Developer Name</author> + +<date>$Date: 2006-10-22 00:16:34 +0200 (Sun, 22 Oct 2006) $</date> +</properties> +<body> + +<section name="Generic"> +<p> +This is a generic template for JK documentation. Please fill in the <b>url</b> and <b>title</b> +tags, as well as <b>author</b> tags. +</p> +</section> + +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/loadbalancers.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/loadbalancers.xml new file mode 100644 index 00000000..eda22cd4 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/loadbalancers.xml @@ -0,0 +1,236 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="loadbalancers.html"> + + &project; +<copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> +<properties> +<title>LoadBalancer HowTo</title> +<author email="mturk@apache.org">Mladen Turk</author> +<date>$Date: 2011-03-07 19:04:44 +0100 (Mon, 07 Mar 2011) $</date> +</properties> +<body> +<section name="Introduction"> +<br/> +<p>A load balancer is a worker that does not directly communicate with Tomcat. +Instead it is responsible for the management of several "real" workers, +called members or sub workers of the load balancer.</p> +<p> +This management includes: +</p> +<ul> +<li> +Instantiating the workers in the web server. +</li> +<li> +Using the worker's load-balancing factor, perform weighted load balancing +(distributing load according to defined strengths of the targets). +</li> +<li> +Keeping requests belonging to the same session executing on the same Tomcat +(session stickyness). +</li> +<li> +Identifying failed Tomcat workers, suspending requests to them and instead +falling-back on other workers managed by the load balancer. +</li> +<li> +Providing status and load metrics for the load balancer itself and all +members via the status worker interface. +</li> +<li> +Allowing to dynamically reconfigure load-balancing via the status worker +interface. +</li> +</ul> +<p> +Workers managed by the same load balancer worker are load-balanced +(based on their configured balancing factors and current request or session load) +and also secured against failure by providing failover to other members of the same +load balancer. So a single Tomcat process death will not "kill" the entire site. +</p> +<p>Some of the features provided by a load balancer are even interesting, when +only working with a single member worker (where load balancing is not possible).</p> + +<subsection name="Basic Load Balancer Properties"> +<p>A worker is configured as a load balancer by setting its worker <code>type</code> +to <b>lb</b>. +</p> +<p> +The following table specifies some properties used to configure a load balancer worker: +</p> +<ul> +<li><b>balance_workers</b> is a comma separated list of names of the member workers of the +load balancer. These workers are typically of type <b>ajp13</b>. The member workers do +not need to appear in the <code>worker.list</code> property themselves, adding the +load balancer to it suffices.</li> +<li><b>sticky_session</b> specifies whether requests with SESSION ID's should be routed +back to the same Tomcat instance that created the session. You can set sticky_session to +<b>False</b> when Tomcat is using a session manager which can share session data across +multiple instances of Tomcat - or if your application is stateless. +By default sticky_session is set to <b>True</b>.</li> +<li><b>lbfactor</b> can be added to each member worker to configure individual +strengths for the members. A higher <code>lbfactor</code> will lead to more +requests being balanced to that worker. The factors must be given by integers and the +load will be distributed proportional to the factors given. Higher factors lead to +more requests.</li> +</ul> + +<source> + # The load balancer worker balance1 will distribute + # load to the members worker1 and worker2 + worker.balance1.type=lb + worker.balance1.balance_workers=worker1, worker2 + worker.worker1.type=ajp13 + worker.worker1.host=myhost1 + worker.worker1.port=8009 + worker.worker2.type=ajp13 + worker.worker1.host=myhost2 + worker.worker1.port=8009 +</source> + +<warn> +Session stickyness is not implemented using a tracking table for sessions. +Instead each Tomcat instance gets an individual name and adds its name at +the end of the session id. When the load balancer sees a session id, it +finds the name of the Tomcat instance and sends the request via the correct +member worker. For this to work you must set the name of the Tomcat instances +as the value of the <code>jvmRoute</code> attribute in the Engine element of +each Tomcat's server.xml. The name of the Tomcat needs to be equal to the name +of the corresponding load balancer member. In the above example, Tomcat on host +"myhost1" needs <code>jvmRoute="worker1"</code>, Tomcat on host "myhost2" +needs <code>jvmRoute="worker2"</code>. +</warn> + +<p>For a complete reference of all load balancer configuration +attributes, please consult the worker <a href="../reference/workers.html">reference</a>. +</p> +</subsection> + +<subsection name="Advanced Load Balancer Worker Properties"> +<p>The load balancer supports complex topologies and failover configurations. +Using the member attribute <code>distance</code> you can group members. +The load balancer will always send a request to a member of lowest distance. +Only when all of those are broken, it will balance to the members of the +next higher configured distance. This allows to define priorities between +Tomcat instances in different data center locations. +</p> +<p>When working with shared sessions, either by using session replication +or a persisting session manager (e.g. via a database), one often splits +up the Tomcat farm into replication groups. In case of failure of a member, +the load balancer needs to know, which other members share the session. +This is configured using the <code>domain</code> attribute. All workers +with the same domain are assumed to share the sessions.</p> +<p>For maintenance purposes you can tell the load balancer to not +allow any new sessions on some members, or even not use them at all. +This is controlled by the member attribute <code>activation</code>. +The value <b>Active</b> allows normal use of a member, <b>disabled</b> +will not create new sessions on it, but still allow sticky requests, +and <b>stopped</b> will no longer send any requests to the member. +Switching the activation from "active" to "disabled" some time before +maintenance will drain the sessions on the worker and minimize disruption. +Depending on the usage pattern of the application, draining will take from +minutes to hours. Switching the worker to stopped immediately before +maintenance will reduce logging of false errors by mod_jk.</p> +<p>Finally you can also configure hot spare workers by using +<code>activation</code> set to <b>disabled</b> in combination with +the attribute <code>redirect</code> added to the other workers:</p> + +<source> + # The advanced router LB worker + worker.list=router + worker.router.type=lb + worker.router.balance_workers=worker1,worker2 + + # Define the first member worker + worker.worker1.type=ajp13 + worker.worker1.host=myhost1 + worker.worker1.port=8009 + # Define preferred failover node for worker1 + worker.worker1.redirect=worker2 + + # Define the second member worker + worker.worker2.type=ajp13 + worker.worker2.host=myhost2 + worker.worker2.port=8009 + # Disable worker2 for all requests except failover + worker.worker2.activation=disabled +</source> + +<p> +The <code>redirect</code> flag on worker1 tells the load balancer +to redirect the requests to worker2 in case that worker1 has a problem. +In all other cases worker2 will not receive any requests, thus acting +like a hot standby. +</p> + +<p>A final note about setting <code>activation</code> to <b>disabled</b>: +The session id coming with a request is send either +as part of the request URL (<code>;jsessionid=...</code>) or via a cookie. +When using bookmarks or browsers that are running since a long time, +it is possible to send a request carrying an old and invalid session id +pointing at a disabled member. +Since the load balancer does not have a list of valid sessions, it will +forward the request to the disabled member. Thus draining takes longer than +expected. To handle such cases, you can add a Servlet filter to your web +application, which checks the request attribute <code>JK_LB_ACTIVATION</code>. +This attribute contains one of the strings "ACT", "DIS" or "STP". If you +detect "DIS" and the session for the request is no longer active, delete the +session cookie and redirect using a self-referential URL. The redirected +request will then no longer carry session information and thus the load +balancer will not send it to the disabled worker. The request attribute +<code>JK_LB_ACTIVATION</code> has been added in version 1.2.32.</p> +</subsection> + +<subsection name="Status Worker properties"> +<p> +The status worker does not communicate with Tomcat. +Instead it is responsible for the worker management. It is +especially useful when combined with load balancer workers. +</p> +<source> + # Add the status worker to the worker list + worker.list=jkstatus + # Define a 'jkstatus' worker using status + worker.jkstatus.type=status +</source> +<p>Next thing is to mount the requests to the jkstatus worker. For Apache +web servers use the:</p> +<source> + # Add the jkstatus mount point + JkMount /jkmanager/* jkstatus +</source> +<p>To obtain a higher level of security use the:</p> +<source> + # 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> +</source> + +</subsection> + +</section> + +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/project.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/project.xml new file mode 100644 index 00000000..b513a8aa --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/project.xml @@ -0,0 +1,81 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<project name="Apache Tomcat Connector Documentation - Generic HowTo" + href="http://tomcat.apache.org/"> + + <title>The Apache Tomcat Connector - Generic HowTo</title> + + <logo href="/images/tomcat.gif"> + The Apache Tomcat Connector - Generic HowTo + </logo> +<body> + + <menu name="Links"> + <item name="Docs Home" href="../index.html"/> + </menu> + + <menu name="Reference Guide"> + <item name="workers.properties" href="../reference/workers.html"/> + <item name="uriworkermap.properties" href="../reference/uriworkermap.html"/> + <item name="Status Worker" href="../reference/status.html"/> + <item name="Apache HTTP Server" href="../reference/apache.html"/> + <item name="IIS" href="../reference/iis.html"/> + </menu> + + <menu name="Generic HowTo"> + <item name="For the impatient" href="../generic_howto/quick.html"/> + <item name="All about workers" href="../generic_howto/workers.html"/> + <item name="Timeouts" href="../generic_howto/timeouts.html"/> + <item name="Load Balancing" href="../generic_howto/loadbalancers.html"/> + <item name="Reverse Proxy" href="../generic_howto/proxy.html"/> + </menu> + + <menu name="Webserver HowTo"> + <item name="Apache HTTP Server" href="../webserver_howto/apache.html"/> + <item name="IIS" href="../webserver_howto/iis.html"/> + <item name="Netscape/SunOne/Sun" href="../webserver_howto/nes.html"/> + </menu> + + <menu name="AJP Protocol Reference"> + <item name="AJPv13" href="../ajp/ajpv13a.html"/> + <item name="AJPv13 Extension Proposal" href="../ajp/ajpv13ext.html"/> + </menu> + + <menu name="Miscellaneous Documentation"> + <item name="Frequently asked questions" href="../miscellaneous/faq.html"/> + <item name="Changelog" href="../miscellaneous/changelog.html"/> + <item name="Current Tomcat Connectors bugs" href="http://issues.apache.org/bugzilla/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Tomcat+Connectors&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0="/> + <item name="Contribute documentation" href="../miscellaneous/doccontrib.html"/> + <item name="JK Status Ant Tasks" href="../miscellaneous/jkstatustasks.html"/> + <item name="Reporting Tools" href="../miscellaneous/reporttools.html"/> + <item name="Old JK/JK2 documentation" href="http://tomcat.apache.org/connectors-doc-archive/jk2/index.html"/> + </menu> + + <menu name="News"> + <item name="2011" href="../news/20110701.html"/> + <item name="2010" href="../news/20100101.html"/> + <item name="2009" href="../news/20090301.html"/> + <item name="2008" href="../news/20081001.html"/> + <item name="2007" href="../news/20070301.html"/> + <item name="2006" href="../news/20060101.html"/> + <item name="2005" href="../news/20050101.html"/> + <item name="2004" href="../news/20041100.html"/> + </menu> + +</body> +</project> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/proxy.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/proxy.xml new file mode 100644 index 00000000..69c60fd5 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/proxy.xml @@ -0,0 +1,347 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="proxy.html"> + + &project; +<copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> +<properties> +<title>Reverse Proxy HowTo</title> +<author email="rjung@apache.org">Rainer Jung</author> +<date>$Date: 2011-03-07 16:17:11 +0100 (Mon, 07 Mar 2011) $</date> +</properties> +<body> +<section name="Introduction"> +<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> +</section> +<section name="Typical Problems"> +<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> +</section> +<section name="AJP as a Solution"> +<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: <code>getLocalName()</code> and <code>getLocalAddr</code>. +This is also equal to <code>getServerName()</code>, unless a <code>Host</code> header +is contained in the request. In this case the server name is taken from that header. +</li> +<li>local port: <code>getLocalPort()</code> +This is also equal to <code>getServerPort()</code>, unless a <code>Host</code> 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: <code>getRemoteAddr()</code> +</li> +<li>client port: <code>getRemotePort()</code> +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, <code>getRemotePort()</code> +will incorrectly return 0 or -1. As a workaround you can forward the remote port by setting +<code>JkEnvVar REMOTE_PORT</code> and then either using +<code>request.getAttribute("REMOTE_PORT")</code> instead of <code>getRemotePort()</code> +or wrapping the request using a filter and overriding <code>getRemotePort()</code> with +<code>request.getAttribute("REMOTE_PORT")</code>. +</li> +<li>client host: <code>getRemoteHost()</code> +</li> +<li>authentication type: <code>getAuthType()</code> +</li> +<li>remote user: <code>getRemoteUser()</code>, +if <code>tomcatAuthentication="false"</code> +</li> +<li>protocol: <code>getProtocol()</code> +</li> +<li>HTTP method: <code>getMethod()</code> +</li> +<li>URI: <code>getRequestURI()</code> +</li> +<li>HTTPS used: <code>isSecure()</code>, <code>getScheme()</code> +</li> +<li>query string: <code>getQueryString()</code> +</li> +</ul> +The following additional SSL-related data will be made available by Apache and forwarded by mod_jk only +if you set <code>SSLOptions +StdEnvVars</code>. For the certificate information you also need +to set <code>SSLOptions +ExportCertData</code>. +<ul> +<li>SSL cipher: <code>getAttribute(javax.servlet.request.cipher_suite)</code> +</li> +<li>SSL key size: <code>getAttribute(javax.servlet.request.key_size)</code>. +Can be disabled using <code>JkOptions -ForwardKeySize</code>. +</li> +<li>SSL client certificate: <code>getAttribute(javax.servlet.request.X509Certificate)</code>. +If you want the whole certificate chain, then you need to also set <code>JkOptions ForwardSSLCertChain</code>. +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: <code>getAttribute(javax.servlet.request.ssl_session)</code>. +This is for Tomcat, it has not yet been standardized. +</li> +</ul> +</p> +</section> +<section name="Fine Tuning"> +<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 <code>X-Forwareded-for</code> 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 +<code>JkOptions ForwardLocalAddress</code>. +</p> +</section> +<section name="Tomcat AJP Connector Settings"> +<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 <code>server.xml</code> +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 <code>getServerName()</code> +</li> +<li>proxyPort: server port as returned by <code>getServerPort()</code> +</li> +<li>scheme: protocol scheme as returned by <code>getScheme()</code> +</li> +<li>secure: set to "true", if you wish <code>isSecure()</code> 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> +</section> +<section name="URL Handling"> +<br/> +<subsection name="URL Rewriting"> +<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 <code>/myapp</code>, +marketing prefers short URLs, so want the application to be directly available under +<code>http://www.mycompany.com/</code>. 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> +<source> +RedirectMatch ^/$ http://www.mycompany.com/myapp/ +</source> +<p>Your application will then be available under <code>http://www.mycompany.com/</code>, +and each visitor will be immediately redirected to the real URL +<code>http://www.mycompany.com/myapp/</code> +</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 +<code>/myapp</code>. 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"><code>mod_rewrite</code></a> +to add <code>/myapp</code> to all requests before forwarding to the backend: +</p> +<source> +# Don't forget the PT flag! (pass through) +RewriteRule ^/(.*) http://www.mycompany.com/myapp/$1 [PT] +</source> +<p>2. Use <a href="http://httpd.apache.org/docs/2.2/mod/mod_headers.html"><code>mod_headers</code></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 <code>Location</code>. +We rewrite the Location headers of our responses: +</p> +<source> +# Keep protocol, server and port if present, +# but insert our webapp name before the rest of the URL +Header edit Location ^([^/]*//[^/]*)?/(.*)$ $1/myapp/$2 +</source> +<p>3. Use <code>mod_headers</code> 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 <code>Set-Cookie</code>. +We rewrite the Set-Cookie headers of our responses: +</p> +<source> +# Fix the cookie path +Header edit Set-Cookie "^(.*; Path=/)(.*)" $1/myapp/$2 +</source> +<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/"><code>mod_proxy_html</code></a>, +<a href="http://httpd.apache.org/docs/2.2/mod/mod_substitute.html"><code>mod_substitute</code></a> +or <a href="http://blogs.sun.com/basant/entry/using_mod_sed_to_filter"><code>mod_sed</code></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> +<source> +# Add a context prefix to all requests ... +/=/myapp/ +# ... or change some prefix ... +/oldapp/=/myapp/ +</source> +<p>and then put the name of the file in the <code>rewrite_rule_file</code> entry of the registry or your +<code>isapi_redirect.properties</code> file. In you <code>uriworkermap.properties</code> 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 '<code>~</code>', indicates, that you are using a regular expression: +</p> +<source> +# Use a regular expression rewrite +~/oldapps([0-9]*)/=/newapps$1/ +</source> +<p>There is no support for Steps 2 (rewriting redirect responses) or 3 (rewriting cookie paths). +</p> +</subsection> +<subsection name="URL Encoding"> +<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, <code>/./</code> is replaced by <code>/</code>, +<code>/XXX/../</code> is replaced by <code>/</code> 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 +<code>JkOptions</code> (Apache httpd) or <code>uri_select</code> (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 <code>ForwardURIProxy</code> +(Apache httpd) or <code>proxy</code> (ISAPI) and it is strongly recommended to keep the default +and remove all old explicit settings. +</p> +</subsection> +</section> +<section name="Request Attributes"> +<br/> +<p> +You can also add more attributes to any request you are forwarding when using Apache httpd. +For this use the <code>JkEnvVar</code> 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> +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/quick.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/quick.xml new file mode 100644 index 00000000..68277226 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/quick.xml @@ -0,0 +1,170 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="quick.html"> + + &project; +<copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> +<properties> +<title>Quick Start HowTo</title> +<author email="hgomez@apache.org">Henri Gomez</author> +<date>$Date: 2010-03-15 16:26:00 +0100 (Mon, 15 Mar 2010) $</date> +</properties> +<body> +<section name="Introduction"> +<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> +</section> + +<section name="Minimum workers.properties"> +<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> +<source> + + # 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 + +</source> +</p> +</section> + +<section name="Minimum Apache web server configuration"> +<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> +<source> + + # 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 + +</source> +</p> +</section> + +<section name="Minimum IIS web server configuration"> +<p> + A separate <a href="../webserver_howto/iis.html">HowTo for the IIS web server</a> is available. +</p> +<todo> +More information to be added! +</todo> +</section> + +<section name="Minimum NES/iPlanet/Sun web server configuration"> +<p> + A separate <a href="../webserver_howto/nes.html">HowTo for the Netscape/iPlanet/Sun web server</a> is available. +<todo> +More information to be added? +</todo> +</p> +</section> + + +<section name="Test your configuration"> +<p> + (Re)start the web server and browse to the <a href="http://localhost/examples/">http://localhost/examples/</a> +</p> + +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/timeouts.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/timeouts.xml new file mode 100644 index 00000000..12208e1a --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/timeouts.xml @@ -0,0 +1,407 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="timeouts.html"> + + &project; +<copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> +<properties> +<title>Timeouts HowTo</title> +<author email="rjung@apache.org">Rainer Jung</author> +<date>$Date: 2009-03-22 00:11:39 +0100 (Sun, 22 Mar 2009) $</date> +</properties> +<body> +<section name="Introduction"> +<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> +<warn> +Do not set timeouts to extreme values. Very small timeouts will likely +be counterproductive. +</warn> +<warn> +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. +</warn> +</section> + +<section name="JK Timeout Attributes"> +<br/> +<subsection name="CPing/CPong"> +<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> +</subsection> + +<subsection name="Low-Level TCP Timeouts"> +<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 <code>socket_timeout</code> is in seconds, and +<code>socket_connect_timeout</code> in milliseconds. +</p> +</subsection> + +<subsection name="Connection Pools and Idle Timeouts"> +<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> +</subsection> + +<subsection name="Firewall Connection Dropping"> +<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> +</subsection> + +<subsection name="Reply Timeout"> +<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> +<warn> +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. +</warn> +<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> +</subsection> +</section> + +<section name="Load Balancer Error Detection"> +<br/> +<subsection name="Local and Global Error States"> +<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> +</subsection> +<subsection name="Error Escalation Time"> +<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> +</subsection> +</section> + +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/workers.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/workers.xml new file mode 100644 index 00000000..0c97d0c1 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/generic_howto/workers.xml @@ -0,0 +1,445 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="workers.html"> + + &project; +<copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> +<properties> +<title>Workers HowTo</title> +<author email="hgomez@apache.org">Henri Gomez</author> +<author email="shachor@il.ibm.com">Gal Shachor</author> +<author email="mturk@apache.org">Mladen Turk</author> +<date>$Date: 2010-01-28 20:47:58 +0100 (Thu, 28 Jan 2010) $</date> +</properties> +<body> +<section name="Introduction"> +<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> +</section> + +<section name="Defining Workers"> +<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> + +<source> + # the list of workers + worker.list= worker1, worker2 +</source> + +<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> + +<subsection name="Workers Type"> +<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>jni</td><td>DEPRECATED: This worker knows how to forward requests to in-process Tomcat workers using JNI.</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> + +<source> + # 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 +</source> + +</subsection> + +</section> + +<section name="Setting Worker Properties"> +<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: + +<subsection name="ajp12 Worker properties"> +<p><warn> +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. +</warn></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> + +<source> + # 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 +</source> + +<p> +Notes: In the ajpv12 protocol, connections are created, used and then closed at each request. +The default port for ajp12 is 8007 +</p> + +</subsection> + +<subsection name="ajp13 Worker properties"> +<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> + + +<source> + # 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/* +</source> + +<p> +Notes: In the ajpv13 protocol, the default port is 8009 +</p> + +</subsection> + +<subsection name="lb Worker properties"> +<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> + +<source> + # The worker balance1 while use "real" workers worker1 and worker2 + worker.balance1.balance_workers=worker1, worker2 +</source> + +</subsection> + +<subsection name="Status Worker properties"> +<p> +The status worker does not communicate with Tomcat. +Instead it is responsible for the load balancer management. +</p> +<source> + # Add the status worker to the worker list + worker.list=jkstatus + # Define a 'jkstatus' worker using status + worker.jkstatus.type=status +</source> +<p>Next thing is to mount the requests to the jkstatus worker. For Apache +web servers use the:</p> +<source> + # Add the jkstatus mount point + JkMount /jkmanager/* jkstatus +</source> +<p>To obtain a higher level of security use the:</p> +<source> + # 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> +</source> + +</subsection> + +<subsection name="Property file macros"> +<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> + +<source> + # 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 +</source> + +</subsection> + +<subsection name="Hierarchical property configuration"> +<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> + +<source> + # 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 +</source> + +<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> + +<source> + # 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 +</source> + +</subsection> + +</section> + +<section name="A sample worker.properties"> +<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> + +<source> + # 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 +</source> + +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/add.gif b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/add.gif Binary files differnew file mode 100644 index 00000000..0774d074 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/add.gif diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/code.gif b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/code.gif Binary files differnew file mode 100644 index 00000000..d27307b5 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/code.gif diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/design.gif b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/design.gif Binary files differnew file mode 100644 index 00000000..f5db0a9f --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/design.gif diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/docs.gif b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/docs.gif Binary files differnew file mode 100644 index 00000000..d64a4a18 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/docs.gif diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/fix.gif b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/fix.gif Binary files differnew file mode 100644 index 00000000..d59ad642 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/fix.gif diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/jakarta-logo.gif b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/jakarta-logo.gif Binary files differnew file mode 100644 index 00000000..049cf822 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/jakarta-logo.gif diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/printer.gif b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/printer.gif Binary files differnew file mode 100644 index 00000000..5021187b --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/printer.gif diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/tomcat.gif b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/tomcat.gif Binary files differnew file mode 100644 index 00000000..f2aa6f86 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/tomcat.gif diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/update.gif b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/update.gif Binary files differnew file mode 100644 index 00000000..31e22abb --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/update.gif diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/void.gif b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/void.gif Binary files differnew file mode 100644 index 00000000..e565824a --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/images/void.gif diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/index.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/index.xml new file mode 100644 index 00000000..915133e4 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/index.xml @@ -0,0 +1,297 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="index.html"> + + &project; + + <properties> + <author email="mturk@apache.org">Mladen Turk</author> + <author email="rjung@apache.org">Rainer Jung</author> + <title>Documentation Index</title> + </properties> + +<body> + +<section name="Introduction"> + +<p>This is the top-level entry point of the documentation bundle for the +<strong>Apache Tomcat Connectors</strong> + +</p> +<p>Select one of the links from the navigation menu (to the left) to drill +down to the more detailed documentation that is available. Each available +manual is described in more detail below.</p> + +</section> + +<section name="Headlines"> +<br /> +<ul> + +<li><a href="news/20110701.html#8 July - JK-1.2.32 released">8 July 2011 - <b>JK-1.2.32 released</b></a> +<p>The Apache Tomcat team is proud to announce the immediate availability + of Tomcat Connectors 1.2.32 Stable. This release contains mainly bug fixes +</p> +<p>Download the <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.32/tomcat-connectors-1.2.32-src.tar.gz">JK 1.2.32 release sources</a> + | <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.32/tomcat-connectors-1.2.32-src.tar.gz.asc">PGP signature</a> +</p> +<p>Download the <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/binaries/">binaries</a> for selected platforms. +</p> +</li> + +<li><a href="news/20100101.html#1 November - JK-1.2.31 released">1 November 2010 - <b>JK-1.2.31 released</b></a> +<p>The Apache Tomcat team is proud to announce the immediate availability + of Tomcat Connectors 1.2.31 Stable. This release contains mainly bug fixes +</p> +<p>Download the <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.31/tomcat-connectors-1.2.31-src.tar.gz">JK 1.2.31 release sources</a> + | <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.31/tomcat-connectors-1.2.31-src.tar.gz.asc">PGP signature</a> +</p> +<p>Download the <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/binaries/">binaries</a> for selected platforms. +</p> +</li> + +<li><a href="news/20100101.html#1 March - JK-1.2.30 released">1 March 2010 - <b>JK-1.2.30 released</b></a> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.30 Stable. This release contains mainly bug fixes +</p> +<p>Download the <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.30/tomcat-connectors-1.2.30-src.tar.gz">JK 1.2.30 release sources</a> + | <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.30/tomcat-connectors-1.2.30-src.tar.gz.asc">PGP signature</a> +</p> +<p>Download the <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/binaries/">binaries</a> for selected platforms. +</p> +</li> +<li><a href="news/20090301.html#22 March - JK-1.2.28 released">22 March 2009 - <b>JK-1.2.28 released</b></a> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.28 Stable. This release contains mainly bug fixes and some small <a href="news/20090301.html#22 March - JK-1.2.28 released">improvements</a>. +</p> +<p>Download the <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.28/tomcat-connectors-1.2.28-src.tar.gz">JK 1.2.28 release sources</a> + | <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.28/tomcat-connectors-1.2.28-src.tar.gz.asc">PGP signature</a> +</p> +<p>Download the <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/binaries/">binaries</a> for selected platforms. +</p> +</li> +<li><a href="news/20081001.html#28 October - JK-1.2.27 released">28 October 2008 - <b>JK-1.2.27 released</b></a> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.27 Stable. This release contains interesting <a href="news/20081001.html#28 October - JK-1.2.27 released">improvements</a>. +</p> +<p>Download the <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.27/tomcat-connectors-1.2.27-src.tar.gz">JK 1.2.27 release sources</a> + | <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.27/tomcat-connectors-1.2.27-src.tar.gz.asc">PGP signature</a> +</p> +<p>Download the <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/binaries/">binaries</a> for selected platforms. +</p> +</li> +<li><a href="news/20070301.html#20071221.1">21 December 2007 - <b>JK-1.2.26 released</b></a> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.26 Stable. +</p> +<p>Download the <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.26/tomcat-connectors-1.2.26-src.tar.gz">JK 1.2.26 release sources</a> + | <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.26/tomcat-connectors-1.2.26-src.tar.gz.asc">PGP signature</a> +</p> +<p>Download the <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/binaries/">binaries</a> for selected platforms. +</p> +</li> +<li><a href="news/20070301.html#20070807.1">7 August 2007 - <b>JK-1.2.25 released</b></a> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.25 Stable. +</p> +<p>Download the <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.25/tomcat-connectors-1.2.25-src.tar.gz">JK 1.2.25 release sources</a> + | <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/source/jk-1.2.25/tomcat-connectors-1.2.25-src.tar.gz.asc">PGP signature</a> +</p> +<p>Download the <a href="http://www.apache.org/dist/tomcat/tomcat-connectors/jk/binaries/">binaries</a> for selected platforms. +</p> +</li> +</ul> +</section> + +<section name="Reference Guide"> +<br /> +<ul> +<li><a href="reference/workers.html"><b>workers.properties</b></a> +<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>This page contains detailed description of all workers.properties +directives. +</p> +</li> + +<li><a href="reference/uriworkermap.html"><b>uriworkermap.properties</b></a> +<p> +The forwarding of requests from the web server to tomcat gets configured by defining mapping rules. +The so-called <b>uriworkermap</b> file is a mechanism of defining those rules. +</p> +</li> + +<li><a href="reference/status.html"><b>Status Worker</b></a> +<p> +The status worker is a builtin management worker. It displays state information +and can also be used to dynamically reconfigure JK. +</p> +</li> + +<li><a href="reference/apache.html"><b>Apache</b></a> +<p>This page contains detailed description of all directives related to +Apache web server. +</p> +</li> + +<li><a href="reference/iis.html"><b>IIS</b></a> +<p>This page contains detailed description of all IIS directives. +</p> +</li> + +</ul> +</section> + +<section name="Generic HowTo"> +<br /> +<ul> + +<li><a href="generic_howto/quick.html"><b>Quick Start</b></a> +<p>This page describes the configuration files used by JK on the +Web Server side for the 'impatients'. +</p> +</li> +<li><a href="generic_howto/workers.html"><b>All about workers</b></a> +<p>This page contains an overview about the various aspects of defining +and using workers. +</p> +</li> +<li><a href="generic_howto/timeouts.html"><b>Timeouts</b></a> +<p>This page describes the possible timeout settings you can use. +</p> +</li> +<li><a href="generic_howto/loadbalancers.html"><b>Load Balancing</b></a> +<p>This page contains an introduction on load balancing with JK. +</p> +</li> +<li><a href="generic_howto/proxy.html"><b>Reverse Proxy</b></a> +<p>This page contains an introduction to reverse proxies, how JK +handles this situation and how you can influence the JK proxying behaviour. +</p> +</li> + +</ul> +</section> + +<section name="Webserver HowTo"> +<br /> +<p>These pages contain detailed descriptions of how to build and +install JK for the various web servers. +</p> +<ul> + +<li><a href="webserver_howto/apache.html"><b>Apache HTTP Server</b></a> +</li> +<li><a href="webserver_howto/iis.html"><b>IIS</b></a> +</li> +<li><a href="webserver_howto/nes.html"><b>Netscape/SunOne/Sun</b></a> +</li> + +</ul> +</section> + +<section name="AJP Protocol Reference"> +<br /> +<ul> +<li><a href="ajp/ajpv13a.html"><b>AJPv13</b></a> +<p>This page describes the Apache JServ Protocol version 1.3 (hereafter +<b>ajp13</b>). +</p> +</li> +<li><a href="ajp/ajpv13ext.html"><b>AJPv13 Extension Proposal</b></a> +<p>This page describes an extension proposal for ajp13. +</p> +</li> +</ul> + +</section> + +<section name="Miscellaneous documentation"> +<br /> +<ul> +<li><a href="miscellaneous/faq.html"><b>Frequently asked questions</b></a> +<p> +</p> +</li> +<li><a href="miscellaneous/changelog.html"><b>Changelog</b></a> +<p> +This page contains the detailed list of all changes made in each version of JK. +</p> +</li> +<li><a href="http://issues.apache.org/bugzilla/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Tomcat+Connectors&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0="> +<b>Current Tomcat Connectors bugs</b></a> +<p>This is the Bugzilla Bug List related to Tomcat Connectors. +</p> +</li> +<li><a href="miscellaneous/doccontrib.html"><b>Contribute documentation</b></a> +<p> +This page describes, how to contribute to the JK documentation. +</p> +</li> +<li><a href="miscellaneous/jkstatustasks.html"><b>JK Status Ant Tasks</b></a> +<p> +This page describes ant tasks to automate JK management via the status worker. +</p> +</li> +<li><a href="miscellaneous/reporttools.html"><b>Reporting Tools</b></a> +<p> +This page contains information, on some report analysis scripts contained in the JK distribution. +</p> +</li> +<li><a href="http://tomcat.apache.org/connectors-doc-archive/jk2/index.html"> +<b>Old JK/JK2 documentation archive.</b></a> +<p>Here you can find old JK and JK2 documentation. +</p> +</li> +</ul> + +</section> + +<section name="News"> +<br /> +<p>Release news from various years. +</p> + +<ul> +<li><a href="news/20110701.html"><b>2011</b></a> +</li> +<li><a href="news/20100101.html"><b>2010</b></a> +</li> +<li><a href="news/20090301.html"><b>2009</b></a> +</li> +<li><a href="news/20081001.html"><b>2008</b></a> +</li> +<li><a href="news/20070301.html"><b>2007</b></a> +</li> +<li><a href="news/20060101.html"><b>2006</b></a> +</li> +<li><a href="news/20050101.html"><b>2005</b></a> +</li> +<li><a href="news/20041100.html"><b>2004</b></a> +</li> + +</ul> +</section> + +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/changelog.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/changelog.xml new file mode 100644 index 00000000..f9db9868 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/changelog.xml @@ -0,0 +1,2157 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="changelog.html"> + + &project; + + <properties> + <author email="mturk@apache.org">Mladen Turk</author> + <author email="rjung@apache.org">Rainer Jung</author> + <author email="hgomez@apache.org">Henri Gomez</author> + <author email="timw@apache.org">Tim Whittington</author> + <title>Changelog</title> + </properties> + +<body> + +<section name="Preface"> + <p> + This is the Changelog for Tomcat Connectors. This changelog + does not contain all updates and fixes to the Tomcat connectors (yet). + It should contain fixes made only after November 10th 2004, when the + new documentation project for JK was started. + </p> +</section> +<section name="Changes between 1.2.31 and 1.2.32"> + <br /> + <subsection name="Native"> + <changelog> + <fix> + <bug>51417</bug>: Fix worker busy detection by querying the + worker endpoint. Abandoned connections can leave a worker + in busy state without decrementing busy counter. (mturk) + </fix> + <fix> + <bug>50339</bug>: Fix whitespace trimming when parsing attribute + lists. (rjung) + </fix> + <fix> + <bug>41263</bug>: Support Servlet API getRemotePort(). + Works for Tomcat 5.5.28, 6.0.20 and 7.0.0 and Apache and ISAPI + plugins. (rjung) + </fix> + <fix> + <bug>41923</bug>: AJP: Close AJP connection to Tomcat on client write + error when recovery_options 4 is specified, aborting the response + write on the Tomcat side. (timw) + </fix> + <update> + AJP: Cap the lingering bytes that will be read + when shutting down an AJP socket at 32k to prevent CPU spikes + in the web server when a client aborts on a large response body. + Also reduce total linger time to 2s. (timw) + </update> + <fix> + <bug>50839</bug>: AJP: Fix 30sec CPU spike due to incorrect counting + of lingering bytes causing a busy loop when a client aborts + connection during a response write. + Fixes regression in 1.2.31. (timw) + </fix> + <add> + LB: Forward worker activation state as request attribute + "JK_LB_ACTIVATION". Possible values are "ACT" (active), + "DIS" (disabled) and "STP" (stopped). (rjung) + </add> + <fix> + HTTPD: Forward WWW-Authenticate from backend when status is 401 + and server generated error pages are used. (rjung) + </fix> + <fix> + <bug>50363</bug>: IIS: Prevent chunk encoding of empty message + bodies for 204, 205 and 304 responses. (timw) + </fix> + <fix> + <bug>50975</bug>: IIS: Fix hanging of Transfer-Encoding: chunked + requests when Content-Length header is present in request as well. + Also addresses situation where IIS appears to create a Content-Length + header for a small chunk encoded request when none was present in the + original request. (timw) + </fix> + <fix> + <bug>47679</bug>: IIS: stop truncation of request headers when + ISAPI redirector used as an extension without the corresponding + filter installed. (timw) + </fix> + <fix> + NSAPI: Use lower case header names for responses. + Otherwise the web server might add chunked transfer encoding header + in addition to our content length header. + </fix> + <update> + Docs: Improve load balancer documentation. (rjung) + </update> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.30 and 1.2.31"> + <br /> + <subsection name="Native"> + <changelog> + <fix> + <bug>49413</bug>: AJP13: Drop flush packets send by the backend + after the response has been finished. (rjung) + </fix> + <update> + AJP: Log the local and remote socket address. (mturk) + </update> + <update> + Watchdog: Move the maintain workers outside the critical + section allowing other threads to use the connection + pool during maintenance. (mturk) + </update> + <update> + Common: Add svn revision to init log message. (rjung) + </update> + <fix> + Common: Don't destroy errno during trace logging. (rjung) + </fix> + <update> + Apache: Add support for Apache 2.3/2.4. (rjung) + </update> + <update> + Apache: Added version number resource for mod_jk.so on Windows. (timw) + </update> + <update> + <bug>48501</bug>: IIS: Added rotatelogs style log rotation to ISAPI + Redirector. (timw) + </update> + <fix> + <bug>38895</bug>: IIS: Use RAW headers instead of CGI headers by default + to prevent conversion of underscores '_' to hyphens '-' in header names. + Old behaviour can be enabled by defining USE_CGI_HEADERS. (timw) + </fix> + <fix> + <bug>49511</bug>: IIS: Do not override IIS log information when subsequent + requests on a keep-alive connection are not mapped into the ISAPI Redirector. (timw) + </fix> + <fix> + Docs: Document SSLOptions needed for SSL information forwarding. (rjung) + </fix> + <update> + Docs: Grammar and style improvements and clarification about serving + static content by IIS. + Patch provided by André Warnier. (rjung) + </update> + <fix> + Docs: Update subversion paths used in docs. (rjung) + </fix> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.28 and 1.2.30"> + <br /> + <subsection name="Native"> + <changelog> + <update> + Apache: Improve compatibility with Apache 2.3. (rjung) + </update> + <fix> + <bug>46632</bug>: Apache: Do not register child cleanup for + our pools. (mturk) + </fix> + <fix> + <bug>46893</bug>: Apache: Log warning only if JkShmSize was actually + set in the configuration. (mturk) + </fix> + <update> + IIS: Include optional chunking support. Off by default. (mturk) + </update> + <fix> + <bug>48763</bug>: IIS: Do not send Content-Length when using chunked encoding + or length larger 4GB. (mturk) + </fix> + <fix> + <bug>48223</bug>: IIS: Propagate correct backend error code to IIS. (rjung) + </fix> + <fix> + <bug>47867</bug>: IIS: crash during startup, when compiled with VS2008 + and workers.properties contains unsupported properties. + Patch provided by Indrek Juhani (rjung) + </fix> + <fix> + <bug>47628</bug>: IIS: Fix deadlock when restarting the Application Pool + caused by not releasing the critical section lock. + Patch provided by Bret Prucha. (mturk) + </fix> + <fix> + IIS/NSAPI: Correct log file flushing after each line. (mturk) + </fix> + <add> + NSAPI: Add Microsoft Visual C++ Makefile. (mturk) + </add> + <update> + AJP: Improve socket shutdown handling. (mturk) + </update> + <update> + AJP: Ensure we never reuse a non reusable socket. (mturk) + </update> + <update> + AJP: Tolerate a single excess packet when waiting for cpong. (mturk) + </update> + <update> + AJP: Check protocol correctness more strictly. (mturk) + </update> + <update> + <bug>48410</bug>: AJP: Use poll instead select so we can work with more + then 1024 sockets. (mturk) + </update> + <fix> + <bug>46503</bug>: AJP/Status: Garbage data in worker domain and route. (mturk) + </fix> + <fix> + <bug>48276</bug>: AJP: When worker contact cannot be resolved mark the + worker as disabled instead failing to start the server. (mturk) + </fix> + <fix> + <bug>48169</bug>: AJP: Improve CGI interoperability by closing all + sockets during EXEC. (mturk) + </fix> + <add> + Status: Add number of open backend connections to status worker. + This feature is experimental, the displayed value might not be + accurate. (mturk) + </add> + <update> + <bug>47224</bug>: Status: When address gets changed invalidate + all opened sockets in the endpoint cache. This will cause new + backend connections to get opened using new address. (mturk) + </update> + <fix> + <bug>48305</bug>: Status: Do not show "secret" property when + doing dump. (mturk) + </fix> + <fix> + <bug>45610</bug>: Status: Don't accept requests with + empty value for sub worker parameter. (rjung) + </fix> + <fix> + <bug>45610</bug>: Status: Fix erroneous unsetting of + sticky_session and sticky_session_force when updating other + load balancer attributes via the status worker. (rjung) + </fix> + <fix> + <bug>47222</bug>: Status: Add ping_timeout to the shared memory + and allow dynamic configuration. (mturk) + </fix> + <fix> + Status: Remove duplicate "errors" line in property view of + AJP13 workers that are part of a load balancer. (rjung) + </fix> + <fix> + LB: Fix route logging. (rjung) + </fix> + <update> + Logging: Automatically detect size of thread id for logging. (rjung) + </update> + <update> + Logging: Add optional log file locking for Windows when defining + JK_LOG_LOCKING. (mturk) + </update> + <update> + Configuration: Update example configuration. (rjung) + </update> + <update> + Docs: Update information about tools needed to create a release. (rjung) + </update> + <fix> + <bug>47983</bug>: Docs: Fix typo in example config + which breaks startup. (rjung) + </fix> + <update> + Build: Force copy of automake files. (rjung) + </update> + <update> + Build: Tomcat code repository structure cleanup reflected in documentation + and build script. (rjung, mturk) + </update> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.27 and 1.2.28"> + <br /> + <subsection name="Native"> + <changelog> + <add> + Apache: Add more environment variables to overwrite request + information. Useful in case a proxy is in front of Apache and sends + us original request information e.g. via custom headers. (rjung) + </add> + <update> + Apache: No longer preallocate entries for JK request log. (rjung) + </update> + <fix> + <bug>46352</bug>: Apache: Fix crash when using SetHandler jakarta-servlet + in VHost without any JkMount. Crash due to incorrect initialization + of mount extensions. (rjung) + </fix> + <fix> + Apache: JkWatchdogInterval had wrong interval calculation + causing a 10 times higher watchdog interval then configured. (mturk) + </fix> + <fix> + Apache: Activate forwarding of SSL key size by default. (rjung) + </fix> + <fix> + <bug>46169</bug>: Apache 1.3: Backport use_server_errors mount extension. (rjung) + </fix> + <fix> + <bug>46763</bug>: Apache 2.0: Survive the log mutex during graceful + restart. Patch provided by Eiji Takahashi. (mturk) + </fix> + <fix> + <bug>46416</bug>: Apache 2.0 on Windows: Include mstcipip.h even if + the apr doesn't include it. (mturk) + </fix> + <update> + IIS: Update uriworkermap.properties file on + a regular interval. This requires both worker_mount_reload + and watchdog_interval to be defined. (mturk) + </update> + <update> + IIS: Remove obsolete entries from registry file. (mturk) + </update> + <fix> + <bug>46579</bug>: IIS: Use local environment table instead environment + variables for setting the JKISAPI_PATH and JKISAPI_NAME. (mturk) + </fix> + <update> + LB: Add new property error_escalation_time to fine tune + escalation of local errors to global errors. (rjung) + </update> + <update> + LB: If the sticky session affinity mark contains a dot, treat the + part before the dot as the domain name. This allows to have full node + session affinity with domain failover. (mturk) + </update> + <fix> + LB: make forced recovery work with local error states. (rjung) + </fix> + <fix> + LB: Only update error state and error time, if we actually have a new state. (rjung) + </fix> + <fix> + LB: Set global worker state to error when we reach max_reply_timeouts, + or fail_on_status triggered hard error. (rjung) + </fix> + <update> + AJP: Add a new error type JK_AJP_PROTOCOL_ERROR. (mturk) + </update> + <update> + AJP: Allow worker ports lower or equal to 1024. (rjung) + </update> + <update> + AJP: Improve some AJP error log messages. (mturk) + </update> + <update> + Status: Allow changing worker address and port of AJP workers. + The address is resolved on next request for that worker. (mturk) + </update> + <update> + Status: Allow update actions to show error messages in the result page. (rjung) + </update> + <update> + Status: Refactor update actions. (rjung) + </update> + <update> + Status: Do not redirect to the show or list page, if an error occured + during an action. (rjung) + </update> + <update> + Status: Include error time in display. (rjung) + </update> + <update> + Status: Remove redundant port information from worker display. + Rename address column and remove its explanation from the legend. (rjung) + </update> + <update> + Status: Optimize forced uriworkermap.properties reload. (mturk) + </update> + <fix> + Status: Fix crash in text display. (rjung) + </fix> + <fix> + Status: Show - Edit - Show always ends in single lb member show, + even when started from all members lb show. (rjung) + </fix> + <fix> + Status: Wildcards in sub worker names were broken for update actions. (rjung) + </fix> + <fix> + Status: Add use_server_errors to map display. (rjung) + </fix> + <update> + SHM: Move locking into the data pull and push methods. (rjung) + </update> + <update> + JNI: Deprecate JNI workers. (rjung) + </update> + <fix> + Netware: Missing define for MAX_PATH. Patch by Guenter Knauf. (rjung) + </fix> + <update> + Docs: Add a new HowTo page about reverse proxies. (rjung) + </update> + <update> + Docs: Add an explanation of local error states to the timeouts documentation. (rjung) + </update> + <update> + Docs: Clarify relation between socket_timeout and socket_connect_timeout. (rjung) + </update> + <update> + Docs: Clarify IIS URL rewrite feature. (rjung) + </update> + <fix> + <bug>46834</bug>,<bug>46734</bug>: Docs: Fix a couple of missing or broken links. (markt,rjung) + </fix> + <fix> + Docs: Add 2008 news to main page and menues. (mturk, rjung) + </fix> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.26 and 1.2.27"> + <br /> + <subsection name="Native"> + <changelog> + <fix> + <bug>46109</bug>: Decay reply_timeouts even when lb method is + busyness. Also reset reply_timeouts during forced recovery. (rjung) + </fix> + <update> + AJP13: Recycle connection if previous request didn't complete. (mturk) + </update> + <update> + Maintain should not run multiple times in parallel. (mturk) + </update> + <fix> + Apache: Fix small memory leak during restart. (mturk) + </fix> + <update> + Improve signal handling during socket shutdown. (mturk) + </update> + <add> + URI Map: Add debug dump function for uri worker map. (rjung) + </add> + <update> + Add revision number to version info for non-release builds. (rjung) + </update> + <add> + IIS: Optionally allow chunked encoding for responses. + At the moment only usable, if build with ISAPI_ALLOW_CHUNKING + defined. Based on patch by Tim Whittington. (rjung) + </add> + <update> + IIS: Optionally use raw headers instead of CGI + headers. Fixes problem "underscore=dash" problem in + header names. At the moment only available, if build with USE_RAW_HEADERS + defined. (rjung) + </update> + <update> + IIS: Optionally improve IIS 5.1 compatibility. + At the moment only available, if build with AUTOMATIC_AUTH_NOTIFICATION + defined. Based on patch by Tim Whittington. (rjung) + </update> + <fix> + IIS: Fix memory corruption due to parallel initialization + by multiple threads. (rjung) + </fix> + <update> + Windows: Use non-default socket keepalive interval. (mturk) + </update> + <add> + IIS: Add environment variables JKISAPI_PATH and JKISAPI_NAME. (mturk) + </add> + <add> + Added socket_connect_timeout directive for setting the + connect timeout for the socket. This enables to have low + connection timeout but higher operational timeouts. (mturk) + </add> + <fix> + AJP13: + [<a href="http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5519"><b>CVE-2008-5519</b></a>] + Always send initial POST packet even if the client + disconnected after sending request but before providing + POST data. In that case or in case the client broke the + connection in a middle of read send an zero size packet + informing container about broken client connection. (mturk) + </fix> + <add> + AJP13: Added connection_acquire_timeout directive for setting the + absolute timeout the worker will wait for a free endpoint. (mturk) + </add> + <update> + Apache: Allow to set path parameter used when doing JkStripSession. (mturk) + </update> + <update> + Refactor retries implementation and change semantics of retries attributes. (mturk) + </update> + <update> + Status: Allow showing only a single member for a load balancer. (rjung) + </update> + <update> + Status: Add display of seconds since last statistics reset and access and + transfer rates. (rjung) + </update> + <add> + AJP13: Add a configurable retry_interval time. (rjung) + </add> + <update> + Documentation: Enhance description of connection_pool_size. (rjung) + </update> + <update> + IIS: Refactor error page generation. (mturk) + </update> + <fix> + IIS: SERVER_NAME variable can be the same for + multiple different server instances if requests + are handled according to the ip:port combination. + Use INSTANCE_ID variable to which the request + belongs instead. (mturk) + </fix> + <add> + Allow forwarding server error pages. This can be done + on per-uri basis using new use_server_errors extension. + (mturk) + </add> + <add> + Added session_cookie and session_path for configuring + default session identifiers. (mturk) + </add> + <update> + Use max_packet_size also as TCP send and receive buffer size. (mturk) + </update> + <update> + Apache: Do not allow Apache to start in multi-threaded mode if mod_jk + was only build for single threaded server (prefork). (mturk) + </update> + <fix> + <bug>45812</bug>: Add done() service method that + causes sending EOS bucket for Apache httpd 2.x. + This allows filter chain to work properly. (mturk) + </fix> + <add> + Added connection_ping_interval, ping_timeout and ping_mode directives. + (mturk) + </add> + <fix> + Apache: Use correct ld flags provided by apxs when building module. + Prevents some crashes on AIX for httpd 1.3 module. (rjung) + </fix> + <fix> + Documentation: "val" attribute numbering in status worker + needs to start with 0 instead of 1. (rjung) + </fix> + <update> + Documentation: Remove JNI parameters from sample configuration + in the workers generic howto. (rjung) + </update> + <fix> + <bug>45026</bug>: For Apache httpd 2.x add "Unknown Reason" + as the reason phrase, if we get an empty one from the backend. + Otherwise httpd 2.x returns status 500. (rjung) + </fix> + <fix> + Build: Fix Cygwin build. (rjung) + </fix> + <update> + Documentation: Add info to docs, that variables sent via JkEnvVar + are not listed in request.getAttributeNames(). (rjung) + </update> + <add> + Add watchdog background thread for Apache 2.x and IIS + doing internal maintenance (idle connection checks, backend probing). + See JkWatchdogInternal (Apache) and watchdog_interval (IIS). (mturk) + </add> + <update> + Change log level of some messages from error to info. (mturk) + </update> + <fix> + Documentation: Fix docs for worker attribute "secret". (rjung) + </fix> + <update> + Detect correct plugin name for various web servers via additional + preprocessor defines. (rjung) + </update> + <fix> + LB: Do not put loadbalancer node in error state if there is opened + channel. This fixes the bug when new connection fails due to + busyness, causing opened connections fail stickyness. + This brings back per-node busy counter and private state array + for each request. We can mark the state as error for failover to + work while still operating and reporting node as OK if there are + opened working connections. (mturk) + </fix> + <fix> + <bug>44738</bug>: Fix merging of JkOption ForwardURI* between virtual hosts. + Patch contributed by Toshihiro Sasajima. (rjung) + </fix> + <add> + URI Map: Add extension attributes to uri worker map. + Allowed are reply_timeout, active/disabled/stopped + and fail_on_status. + Usage currently only implemented for httpd and IIS. (rjung+mturk) + </add> + <fix> + URI Map: Make dynamic reloading atomic and free memory + not needed any longer. (rjung) + </fix> + <add> + Configure: Don't use post httpd 2.2.0 API functions when building + with new --enable-api-compatibility configure switch. (rjung) + </add> + <fix> + Apache: JkAutoAlias does not work in combination with JkMountCopy + if there are no JkMount in virtual host. (rjung) + </fix> + <update> + LB: Optimize state macros to improve performance. (rjung) + </update> + <add> + Apache: Allow dynamic setting of reply timeout using the environment + variable JK_REPLY_TIMEOUT. (rjung) + </add> + <add> + Status: Add manageability for ajp parameters of ajp + workers and ajp lb members. (rjung) + </add> + <update> + Status: Change parameter names of update action to + make them more easily distinguishable from other parameters. (rjung) + </update> + <add> + Status: Add ajp worker statistics also for + workers, that are not lb members. (rjung) + </add> + <update> + AJP: Refactor factories, move ajp13/ajp14 common parts into + ajp_factory. (rjung) + </update> + <update> + Status: Only sync shm worker config values of the workers + for which we changed values. (rjung) + </update> + <fix> + Status: Set lb_factor instead of distance. (rjung) + </fix> + <update> + Status: Minor layout changes, use drop down instead of multiple + text links. (rjung) + </update> + <update> + SHM: Use local copies of read mostly attributes of lb sub workers + in lb and status worker. (rjung) + </update> + <update> + Status: Add "dump" action to dump our initial configuration. (rjung) + </update> + <update> + Status: Use property table to decide which cmd action uses which + output elements. (rjung) + </update> + <update> + Common: Include original configuration map in worker_env + to make it available for workers, e.g. the status worker. (rjung) + </update> + <update> + LB: Refactor "route" return for httpd note. Don't use a + member of the worker_record, because that's not thread safe. (rjung) + </update> + <update> + Common: Refactor "retries", remove from service and jk_worker, + move into ajp worker instead. (rjung) + </update> + <update> + SHM: Use distinct structs for lb and ajp13 in shm. + Improves type safety and saves a few bytes. (rjung) + </update> + <update> + SHM: Remove unused attributes. (rjung) + </update> + <update> + SHM: Automatically determine shm size for all web servers. (rjung) + </update> + <update> + SHM: Make open/attach logging consistent for all web servers. (rjung) + </update> + <update> + Status: Include server local time in output. (rjung) + </update> + <fix> + <bug>44116</bug>: Fix handling of multiple JSESSIONID cookies. (rjung) + </fix> + <fix> + <bug>37850</bug>: Use thread safe localtime_r where appropriate. (rjung) + </fix> + <fix> + Use thread safe strtok_r on more platforms, especially AIX. (rjung) + </fix> + <update> + Status: Improve XSS hardening. (rjung) + </update> + <update> + <bug>35303</bug>: Move initialization of service members with defaults from + web server specific code to our generic jk_init_ws_service() function. (rjung) + </update> + <fix> + <bug>36385</bug>: Add missing prepost CPing/CPong directly after connect + in case prepost CPing is used, but no connect CPing. (rjung) + </fix> + <update> + <bug>37322</bug>: Apache: Enhance robustness of message formating + in jk_error_exit(). (rjung) + </update> + <fix> + <bug>44147</bug>: Multiple load balancing workers problem. (rjung) + </fix> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.25 and 1.2.26"> + <br /> + <subsection name="Native"> + <changelog> + <fix> + <bug>42003</bug>: Allocate memory instead using fixed size from + the stack. (mturk) + </fix> + <fix> + <bug>43229</bug>: Load balancer does not do fail over after + reply timeouts. (rjung) + </fix> + <fix> + JKStatus: Repair detailed Apache httpd version display. + This was broken for httpd version 2.2.4+. (rjung) + </fix> + <update> + LB/AJP: Refactoring of jk_connect.c, jk_ajp_common.c, + jk_lb_worker.c (rjung) + </update> + <fix> + Configure: Repair broken apxs auto-detection. (rjung) + </fix> + <update> + Configure: Remove trace logging from compiled code + via new --disable-trace configure switch. (rjung) + </update> + <update> + Common: Maintain idle connections in decreasing (LRU) + slot order. (rjung) + </update> + <update> + Apache: Create JK_WORKER_ROUTE and JK_REQUEST_DURATION notes for + access log even if no JkRequestLogFormat is set. (rjung) + </update> + <update> + JKStatus: Enhance URI to worker map listing for Apache httpd. + We now list maps for all virtual servers and not only + the one, in which JKStatus itself was called. (rjung) + </update> + <update> + JKStatus: Enhance URI to worker map listing. + Update stale uriworkermap.properties immediately. (rjung) + </update> + <fix> + <bug>43873</bug>: Fix small memory leak occuring during httpd restart. (rjung) + </fix> + <update> + Common: Allow '*' for the worker name in exclusion rules (resp. JkUnMount) + which will override all workers. (rjung) + </update> + <fix> + <bug>42038</bug>: Correct overlay of mounts and unmounts for IIS. (rjung) + </fix> + <fix> + <bug>43684</bug>: Replace JkMountFile by JkMountFileReload in + uriworkermap.properties docs. (rjung) + </fix> + <update> + Apache: Add new value "All" for JkMountCopy. (rjung) + </update> + <fix> + <bug>43516</bug>: Memory leak for Apache httpd module + of size 8KB for every virtual host without JK directive + after each restart. (rjung) + </fix> + <update> + Apache: Cleanup init and destroy of server configuration. (rjung) + </update> + <update> + Apache: Remove global configuration items from per server + configuration. (rjung) + </update> + <update> + Apache: Remove unused attributes secret_key and + automount/JkAutoMount. (rjung) + </update> + <update> + Cleanup of jk_uri_worker_map. (rjung) + </update> + <update> + Documentation: Small additions to JkShmFile documentation. + Contributed by Gerhardus Geldenhuis. (rjung) + </update> + <fix> + AJP13: Ignore flush packets before we received the response headers. (rjung) + </fix> + <fix> + Fix crash during startup when using worker configuration inheritance + (attribute "reference") and log level debug. (rjung) + </fix> + <fix> + AJP13: Match header names exactly against pre defined constants. Avoid + possible confusion with custom header names using a standard header name + as a prefix. (rjung) + </fix> + <fix> + jkstatus: Fix correct parameter validation at JkStatusUpdateTask and + JkStatusUpdateLoadbalancerTask ant tasks. Reported by Christian Mittendorf. (pero) + </fix> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.24 and 1.2.25"> + <br /> + <subsection name="Native"> + <changelog> + <update> + IIS: Fix shm shutdown behaviour. (rjung) + </update> + <update> + General: fail_on_status used in a load balancer can optionally + do fail over without putting the failed worker in error state. (rjung) + </update> + <update> + NSAPI: Improve build description for Unix. (rjung) + </update> + <update> + NSAPI: Add initialization startup message containing JK version. (rjung) + </update> + <fix> + General: Declare static functions as static. (jim) + </fix> + <update> + Documentation: Clarify fail_on_status behaviour. (rjung) + </update> + <fix> + General: Do fail_on_status before returning the response headers. (rjung) + </fix> + <update> + NSAPI: Fix shm shutdown behaviour. (rjung) + </update> + <update> + NSAPI: Set return status even if request ended with an error. (rjung) + </update> + <update> + NSAPI: Allow using without shm_file on WIN32 and Netware. (rjung) + </update> + <fix> + NSAPI: Fix Crash of nsapi for log level debug and unset refect_unsafe. (rjung) + </fix> + <update> + NSAPI: Improve Solaris and Linux Makefiles for nsapi build. (rjung) + </update> + <fix> + Build: Improve pid_t type detection during configure on Solaris. (rjung) + </fix> + <update> + Build: Experimental build support for gcc on WIN32 and Netware. (fuankg) + </update> + <update> + Build: Makefile optimizations for Apache httpd 1.3/Netware . (fuankg) + </update> + <fix> + General: Fix missing flush bug introduced in 1.2.24. (rjung) + </fix> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.23 and 1.2.24"> + <br /> + <subsection name="Native"> + <changelog> + <update> + Documentation: Improved workers.properties description in the + reference guide. (rjung) + </update> + <update> + Documentation: Add a HowTo about the various timeouts. rjung) + </update> + <update> + Logging: add milliseconds to the default timestamp format, + if we have gettimeofday(). (rjung) + </update> + <update> + Apache: add milliseconds (%Q) and microseconds (%q) as possible + JkLogStampFormat conversion specifiers. This does not use strftime(), + but needs gettimeofday(). (rjung) + </update> + <update> + IIS & Sun: Log service failures also, if return code is negative. (rjung) + </update> + <fix> + <bug>42849</bug>: Abort startup of Apache httpd 1.3 in case + mod_jk initialization failed. We already do the same + for Apache httpd 2.x. (rjung) + </fix> + <fix> + <bug>42849</bug>: Refuse to operate with IIS in case the + initialization failed. Instead requesting isapi_redirect.dll + 500 will be returned to the user. This is as closest as it + can get to Apache Httpd where we refuse to start the server + in case of fatal initialization errors. (mturk) + </fix> + <fix> + Load Balancer: Fix a deadlock in lb worker, which was exposed on Solaris + for threaded Apache MPMs. (rjung) + </fix> + <update> + Logging: handle LWP IDs as 32 Bit unsigned. Try to make + it work, although pthread IDs are opaque. (rjung) + </update> + <update> + JkStatus: Added manipulation of max_reply_timeouts. (rjung) + </update> + <update> + LB, Status: Add feature max_reply_timeouts, to make lb tolerant against + occasional long running requests. (rjung) + </update> + <update> + JkStatus: Added OK/IDLE as the successor of N/A. (rjung) + </update> + <update> + Status worker: Renamed runtime states. All states have a major + state (OK or ERR) and a substate. Changed the name N/A to OK/IDLE. + Added docs about the meaning of the states to the status worker + page in the reference guide. + No new states have been added to code. (rjung) + </update> + <update> + Common: Add recovery options for recovering idempotent http methods + HEAD and GET. (rjung) + </update> + <fix> + Correct documentation for worker attributes retries and + recovery_options. (rjung) + </fix> + <fix> + Make writing log lines and line endings more atomic. (rjung) + </fix> + <update> + Common: Refactored and unified jk_map_read_prop* and jk_map_load_prop* + for all use cases. (rjung) + </update> + <update> + Common/Apache/IIS/Netscape: Add an option to check decoded URLs for + potentially malicious constructions. (rjung) + </update> + <update> + IIS: Document auth_complete and uri_select. (rjung) + </update> + <update> + Apache/IIS/Netscape: Change the default forwarding encoding to the new + proxy method. (jfclere, rjung) + </update> + <update> + Common: Optionally reencode URIs before forwarding to the backend. + Based on the URI reencoding done bei httpd mod_proxy. (jfclere, rjung) + </update> + <update> + Common: auto-detect correct print format for pid_t. + This fixes at least compiler warnings on Solaris. (rjung) + </update> + <fix> + <bug>42608</bug>: Handle Content-length as unsigned 64Bit + to allow for huge up- and downloads. (rjung) + </fix> + <update> + Apache: Add forwarding uri to debug log. (rjung) + </update> + <update> + Docs: Clarify relation between worker names and jvmRoute for load balancing. (rjung) + </update> + <fix> + Use initial zero timeout for jk_is_socket_connected. The resulting + detection is the same but offers a huge performance increase + with mod_jk. In most cases the Operating System does not favor + the 1 microsecond timeout, but it rather rounds that up to much + higher value (frequency of interrupt timer which on most systems + defaults to 100Hz). + Patch provided by David McLaughlin. (mturk) + </fix> + <update> + NSAPI: Check correct log file and shm file configuration during startup. (rjung) + </update> + <fix> + NSAPI: Add support for the general options concerning retries, flushing + and connection persistance. (rjung) + </fix> + <fix> + NSAPI: fix crashes due to use of mount attribute in workers.properties. + Changed initialization order. (rjung) + </fix> + <fix> + Improved handling of libtool and discrepancies between CC env variable and + CC used during apache build by configure script. (rjung) + </fix> + <fix> + Always build with thread support, unless flag --enable-prefork + is set during for configure. (rjung) + </fix> + <update> + Use snprintf/vsnprintf from ap_snprintf.c for platforms other + than Windows, which might lack snprintf/vsnprintf implementations + when NOT build for Apache httpd 2.x/APR (e.g. Sub Web Server) + or without using configure. (fuankg) + </update> + <update> + Imported ap_snprintf() from Apache 1.3. (fuankg) + </update> + <fix> + Fix incorrect log object cleanup during statup, + leading to crashes at least on iSeries. (rjung) + </fix> + <update> + Add jk_stat() and jk_file_exists() as wrapper functions. + i5/OS V5R4 expects filename in ASCII for fopen but requires them + in EBCDIC for stat(). (hgomez) + </update> + <update> + i5/OS (AS/400) V5R4 port where Apache 2.0 modules should now use UTF8. (hgomez) + </update> + <update> + Docs: Add comments on i5/OS build for V5R4 and previous releases. (hgomez) + </update> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.22 and 1.2.23"> + <br /> + <subsection name="Native"> + <changelog> + <update> + [<a href="http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2007-0450"><b>CVE-2007-0450</b></a>] + and + [<a href="http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2007-1860"><b>CVE-2007-1860</b></a>]: + Change the default value of JkOptions to ForwardURICompatUnparsed. + The old default value was ForwardURICompat. + This should make URL interpretation between Apache httpd and + Tomcat consistent (prevent double decoding problems). (rjung) + </update> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.21 and 1.2.22"> + <br /> + <subsection name="Native"> + <changelog> + <fix> + Refactor line endings logging to make it correct for all + platforms and webservers. (mturk) + </fix> + <update> + Added command line windows make files. (mturk) + </update> + <update> + Allow fail_on_status directive to be multi line. (mturk) + </update> + <fix> + <bug>42076</bug>: Fix name of new option from ForwardCertChain to + ForwardSSLCertChain as documented. (rjung) + </fix> + <fix> + Docs: Fix a couple of typos, change format of a few tables, + fix links to news pages. (rjung) + </fix> + <fix> + Fix correct URL for TC 6 examples in new IIS rewrite.properties + configuration example file. (rjung) + </fix> + <fix> + Add svn properties to several files. (rjung) + </fix> + <update> + Add TC 6 examples to uriworkermap.properties in config examples. (rjung) + </update> + <update> + Allow multiple status codes for fail_on_status directive. + The status codes can be delimited by space or comma characters. (mturk) + </update> + <update> + IIS. Added pcre like regular expressions for url rewrite rules. (mturk) + </update> + <fix> + <bug>41922</bug>: Apache 1.3. Enable JkEnvVar. (mturk) + </fix> + <update> + Apache. Add --enable-flock configure parameter for explicit + compilation of faster flock() system calls for OS supporting + those calls. By default the fcntl system call for locking will + be used that is a little bit slower but it can work on NFS + mounted volumes as well. (mturk) + </update> + <fix> + <bug>41562</bug>: Add Debug logging for read from client in ISAPI Redirector. + Contributed by Tim Whittington. (mturk) + </fix> + <update> + Apache. Add ForwardSSLCertChain JkOption. + Contributed by Patrik Schnellmann. (mturk) + </update> + <fix> + IIS. Do not forbid access to web-inf or meta-inf if there is + no mapped worker. This allows to have resource with those names + that are outside mapped contexts. (mturk) + </fix> + <update> + Apache. Use process id for creating shared memory name and delete shared + memory and shared memory lock files on exit. (mturk) + </update> + <fix> + IIS. Fix Keep-Alive regression introduced in 1.2.21. (mturk) + </fix> + <update> + Delete unused check for empty init_map during startup. (rjung) + </update> + <fix> + <bug>41770</bug>: Fix startup error if no JkWorkersFile is used. (rjung) + </fix> + <update> + Use JK_TRUE/JK_FALSE instead of OK/!OK as return values in init_jk(). (rjung) + </update> + <update> + Minor adjustments to apache startup log messages (when to use STDERR, remove + deprecated NOERRNO flag, shm warning and warnings for usage of default files). (rjung) + </update> + <update> + Replace APR precompiler directive by httpd mpm_query to detect MPM threading. + Add a debug log message about auto-detected pool size. (rjung) + </update> + <fix> + Make MMN check easier to understand and a little more precise + (for new ap_get_server_banner()/ap_get_server_description()). + We use the new API only for Apache httpd 2.3. This way our binaries are not + tightly coupled to a minor 2.0 version, and we don't use ap_get_server_banner() + any way. (rjung) + </fix> + <fix> + Use the full description string ap_get_server_description() instead of + the truncated info from ap_get_server_banner(), because this info gets used internally + (status worker display and ajp14 backend communication) and is not send back to the + normal user. (rjung) + </fix> + <fix> + <bug>41757</bug>: Document the "--enable-prefork" flag of configure. (rjung) + </fix> + <update> + Enhance log messages for failures when parsing attribute maps. (rjung) + </update> + <fix> + Correct log message during worker initialization, in case remote host could not be + resolved. We logged the default host name "localhost" instead of the configured one. (rjung) + </fix> + <fix> + <bug>41770</bug>: Fix the second part of the bug: local_worker and local_worker_only + is missing from the list of deprecated attributes (and not supported either), so prevents + the web server from startup. (rjung) + </fix> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.20 and 1.2.21"> + <br /> + <subsection name="Native"> + <changelog> + <fix> + [<a href="http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2007-0774"><b>CVE-2007-0774</b></a>]: + A denial of service and critical remote code execution vulnerability. + Caused by buffer overflow in map_uri_to_worker() when URL were longer that 4095 bytes. + Reported by ZDI (www.zerodayintiative.com). + Please note this issue only affected versions 1.2.19 and 1.2.20 of the + Apache Tomcat JK Web Server Connector and not previous versions. + Tomcat 5.5.20 and Tomcat 4.1.34 + included a vulnerable version in their source packages. + Other versions of Tomcat were not affected. + </fix> + <add> + Check the worker. parameters and don't start if the parameter is not a valid one. (jfclere) + </add> + <add> + <bug>41439</bug>: Allow session IDs to get stripped off URLs of static + content in Apache by adding JkStripSession + directive (configurable per vhost). (mturk) + </add> + <add> + Change semantics of empty defaults for JkEnvVar variables. + Until 1.2.19: not allowed. In 1.2.20: send variables as empty strings, if + neither set to non empty in config, nor during runtime. + Starting with 1.2.21: If config has no second argument only send + variable if set (even when set to empty string) during runtime. + Allows good combination with condition attribute in tomcat access log. (rjung) + </add> + <fix> + <bug>41610</bug>: Fix incorrect detection of missing Content-Length + header leading to duplicate headers. Contributed by Boris Maras. (rjung) + </fix> + <fix> + Better build support for SunONE (Netscape/iPlanet) webservers. (jim) + </fix> + <add> + Add warning if duplicate map keys are read and are not allowed, + e.g. when parsing uriworkermap.properties. (rjung) + </add> + <fix> + Don't concat worker names, if uriworkermap.properties has a duplicate + pattern, instead overwrite the worker. (rjung) + </fix> + <fix> + Log deprecation message even in duplication case. (rjung) + </fix> + <fix> + uriworkermap.properties: Fix off-by-one problem when deleting + URL mapping during reloading of uriworkermap.properties. (rjung) + </fix> + <add> + <bug>41439</bug>: Allow session IDs to get stripped off URLs of static + content in IIS (configurable). (rjung) + </add> + <add> + <bug>41333</bug>: Refactoring isapi_plugin configuration reading. (rjung) + </add> + <add> + <bug>41332</bug>: Add some more errno logging and unify the format. (rjung) + </add> + <add> + JkStatus: Improved logging by adding status worker name to messages. + Added messages to the recover worker action. (rjung) + </add> + <add> + JkStatus: Refactoring searching for workers and sub workers. (rjung) + </add> + <add> + <bug>41318</bug>: Add configuration to make status worker user + name checks case insensitive. (rjung) + </add> + <add> + JkStatus: Add estimated time until next global maintenance to other + mime types and adopt jkstatus ant task. (rjung) + </add> + <add> + JkStatus: Show estimated time until next global maintenance. + Change displayed time until next recovery to a min/max pair. (rjung) + </add> + <add> + JkStatus: Allow a user of a read/write status worker to switch it + to and from read_only mode temporarily. (rjung) + </add> + <fix> + JkStatus: Do not show read/write commands in a read_only status worker. (rjung) + </fix> + <add> + JkStatus: Allow lb sub workers in error state to be marked for recovery + administratively from the status worker. (rjung) + </add> + <add> + Load Balancer: Do not try to recover multiple times in parallel. + Use additional runtime states "PROBE" and "FORCED". (rjung) + </add> + <fix> + JkStatus: Improve data synchronization between different processes. (rjung) + </fix> + <fix> + <bug>41381</bug>: Fix segfault in feature fail_on_status + (wrong order of log arguments). Patch by Juri Haberland. (rjung) + </fix> + <fix> + Use correct windows line endings for log file on WIN32 platform. (rjung) + </fix> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.19 and 1.2.20"> + <br /> + <subsection name="Native"> + <changelog> + <add> + JkStatus Ant Task documentation page. (pero/rjung) + </add> + <add> + JkStatus Ant Tasks: Add new tasks for update and reset. (pero) + </add> + <update> + JkStatus Ant Tasks: Update for new xml status format. (pero) + </update> + <update> + Allow integer and string values when setting enumeration/boolean + attributes via status worker update action. (rjung) + </update> + <add> + Docs: New reference guide page for status worker. (rjung) + </add> + <update> + Docs: Renaming the config dir to reference and using the title + Reference Guide in the docs. (rjung) + </update> + <update> + Added retry_on_status for workers directive. (mturk) + </update> + <update> + Status Worker: Add directive to make property prefix + and good/bad rule configurable. (rjung) + </update> + <update> + Status Worker: Omit lb members when att=nosw. (rjung) + </update> + <update> + Status Worker: New command cmd=version for a short version output. (rjung) + </update> + <update> + Status Worker: New output stype mime=prop produces property lists. (rjung) + </update> + <fix> + Apache: Fix incorrect handling of JkEnvVar when Vars are set multiple times. (rjung) + </fix> + <update> + Renamed jvm_route to route. Deprecated jvm_route, but still use it as fallback + when parsing the worker configuration. (rjung) + </update> + <update> + IIS: Make uriworkermap file reload check interval configurable. (mturk) + </update> + <update> + Apache: Make uriworkermap file reload check interval configurable. (rjung) + </update> + <update> + Status Worker: Add directives for customizing the XML + output (ns, xmlns, doctype). (mturk) + </update> + <add> + Docs: New page with description of uriworkermap. (rjung) + </add> + <update> + Docs: Added short description of max_packet_size to worker + reference. (rjung) + </update> + <update> + Status Worker: All functions accessible also for xml and txt + mime types (list, show, update, reset). (rjung) + </update> + <update> + Status Worker: New global health indicators for load balancers + named bad (error, recovering or stopped), degraded (busy or disabled) + and good (the rest, active and OK or N/A). (rjung) + </update> + <update> + Status Worker: New edit page, to change one attribute for all + members of a load balancer. (rjung) + </update> + <update> + Status Worker: Standard logging for status worker. (rjung) + </update> + <update> + Status Worker: code refactoring. (rjung) + </update> + <update> + Status Worker: New attribute user (list) denies access, if + the request user in the sense of remote_user is not in this list. + Empty list = no deny (rjung) + </update> + <update> + Status Worker: New attribute read_only disables the parts + of the status worker, that change states and configurations. (rjung) + </update> + <fix> + <bug>36121</bug>: Don't change main uri when mod_jk serves + included uri. (markt) + </fix> + <update> + Apache VHosts: Merge JkOptions +base - -base + +vhost - -vhost. (rjung) + </update> + <update> + Apache Docs: Adding requirements, context information, default values and + inheritance rules to the Apache config documentation. (rjung) + </update> + <update> + Status Worker: Add source type to status worker, remove the redundant "context" + column in the map listing (context=uri). (rjung) + </update> + <update> + uriworkermap: On reload of the file, all old entries from the previous file + version get deleted, before the new ones are being read. (rjung) + </update> + <fix> + Keep normal maps and exclusion maps internally separate. Don't treat them + as the same when adding a rule. (rjung) + </fix> + <update> + Status Worker: Display mapping rules also for non-lb workers and in global view. (rjung) + </update> + <update> + Apache VHosts: Use the vhost log files instead of the main log. (rjung) + </update> + <update> + Apache VHosts: Allow individual timestamp formats by refactoring the formatting + method. (rjung) + </update> + <update> + Apache VHosts: Adding all missing config items to the virtual host level. + Don't overwrite the settings from the global server, but inherit them + in case they are not set in the virtual host. (rjung) + </update> + <update> + Apache: remove unnecessary function names from log messages. (rjung) + </update> + <update> + Apache: add a default log file location and a message, if the default gets used. (rjung) + </update> + <update> + Apache: add missing JK_IS_DEBUG_LEVEL() (rjung) + </update> + <update> + Apache VHosts: Allow JkWorkersFile, JKWorkerProperty, JkShmFile and JkShmFileSize + only in global virtual server. (rjung) + </update> + <update> + Add some more jk_close_socket() and reduce log level for some info messages. (rjung) + </update> + <update> + Load Balancer: Added the Sessions strategy. Contributed by Takayuki Kaneko. (rjung) + </update> + <update> + Docs: Minor enhancements and syncing with more recent versions. (rjung) + </update> + <fix> + <bug>40997</bug>: Separate uri mappings from their '!' + counterpart when checking for duplicates in uriworkermap + reloading. (rjung) + </fix> + <fix> + <bug>40877</bug>: Make sure the shared memory is reset on + attach for multiple web server child processes. (mturk) + </fix> + <update> + IIS: Added shm_size property to be able to deal with over 64 + workers configurations. (mturk) + </update> + <update> + IIS: Increase default thread count to 250, so its the same as Apache Httpd + default configuration. (mturk) + </update> + <fix> + <bug>40966</bug>: Fix socket descriptor checks on windows. (mturk) + </fix> + <fix> + <bug>40965</bug>: Initialize missing service parameters. (mturk) + </fix> + <fix> + <bug>40938</bug>: Fix releasing of rewrite map. + Thanks to Chris Adams for spotting that. (mturk) + </fix> + <update> + Apache: Added +FlushHeader JkOptions. (mturk) + </update> + <update> + Added explicit flush when AJP body packet size is zero. (mturk) + </update> + <fix> + <bug>40856</bug>: Fixing case sensitivity bug in URL mapping. (rjung) + </fix> + <fix> + <bug>40793</bug>: Documentation: Improvements to Apache HowTo provided by + Paul Charles Leddy. (markt) + </fix> + <fix> + <bug>40774</bug>: Fixing wrong recursion termination. This one restricted the + "reference" feature unintentionally to 20 workers. (rjung) + </fix> + <fix> + <bug>40716</bug>: Adding "reference" feature to IIS and Netscape. (rjung) + </fix> + <fix> + Documentation: Corrected SetEnvIf syntax in JK_WORKER_NAME example. (rjung) + </fix> + <fix> + Documentation: Added forgotten STATE and ACTIVATION notes for load balancer logging in Apache. (rjung) + </fix> + <update> + Apache: Use instdso.sh instead libtool: libtool does not work on HP-UX for example. (jfclere) + </update> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.18 and 1.2.19"> + <br /> + <subsection name="Native"> + <changelog> + <update> + Docs: Add SetHandler and new env var to Apache config docs. (rjung) + </update> + <update> + Apache 1.3: Backport "no-jk" feature. (rjung) + </update> + <update> + Apache: Add an environment variable to make SetHandler "jakarta-servlet" more + useful. The variable is JK_WORKER_NAME, but can be changed by the + new directive JkWorkerIndicator. (rjung) + </update> + <fix> + LB: Don't use single worker shortcut, if the single worker is being diabled. (rjung) + </fix> + <fix> + Status worker: Add short explanation of activation and error states to legend. (rjung) + </fix> + <fix> + Docs: Add meaning of zero timeout values for various timeouts + in workers.properties. (rjung) + </fix> + <fix> + LB: Cleanup of Mladens forced recovery. (rjung) + </fix> + <fix> + LB: Do not change lb_value for recovering workers to max, if + we are using BUSYNESS method. (rjung) + </fix> + <fix> + Apache: Since 1.2.14 mod_jk failed to detect client abort. (rjung) + </fix> + <fix> + Docs: Corrected description of JkEnvVar. (rjung) + </fix> + <fix> + Solaris: Detect filio.h in configure to make the new connection detection + build on solaris (r432825). (rjung) + </fix> + <update> + Add feature to force the recovery of workers that are + member of loadbalancer if all the members are in error + state. This fixes the time gap where 503 was returned + caused by recovery_timeout although the backend was + ready to handle the requests. (mturk) + </update> + <update> + Docs: Seperate deprecated directives in their own table. (rjung) + </update> + <update> + Docs: Allow "-" and "_" in worker names. (rjung) + </update> + <update> + Allow multiple lines with attributes "balance_workers" and "mount". (rjung) + </update> + <fix> + Make jk_is_some_property match more precisely. (rjung) + </fix> + <update> + JkStatus: Make refresh interval changeable. (rjung) + </update> + <fix> + JkStatus: Adjust display of recover time wrt. global maintenance. (rjung) + </fix> + <update> + LB: Resetting worker state from OK to NA, if worker has been idle + too long. (rjung) + </update> + <fix> + Avoid compiler warnings concerning the use of lb_*_type arrays. + Use functions instead. (rjung) + </fix> + <update> + Added %R JkRequestLogFormat option for Apache 1 and Apache 2. (mturk) + </update> + <update> + Allow changing jvm Route from status manager. (mturk) + </update> + <fix> + Do not retun 400 if Tomcat fails in the midle of the post + request. Return 500 insted. (mturk) + </fix> + <update> + LB: Combine ok/error/recovering/busy runtime states into a single scalar. (rjung) + </update> + <update> + LB: Combine active/disabled/stopped configuration states into a single scalar. (rjung) + </update> + <update> + LB: Add several Apache notes to enable standard logging for load balancer results. (rjung) + </update> + <update> + LB: Reorganisation of the main load balancer service loop. (rjung) + </update> + <update> + Implement hierarchical worker configuration via attribute "reference". (rjung) + </update> + <update> + Log deprecated properties. (rjung) + </update> + <fix> + IIS: Fix simple_rewrite for the cases where the + rewritten url is larger then the original one. (mturk) + </fix> + <update> + New JkOption "DisableReuse" to disable connection persistence. (jim) + </update> + <update> + LB: Move sessionid retrieval out of get_most_suitable_worker into service. (rjung) + </update> + <update> + Code cleanup for all service methods (use TRACE, JK_LOG_NULL_PARAMS, null pointer checks). (rjung) + </update> + <update> + JKSTATUS: add refresh link. No refresh for updates. Redirect to list view after update. (rjung) + </update> + <update> + Add new hook add_log_items into servers. (rjung) + </update> + <update> + APACHE httpd: Rename apache logging notes. (rjung) + </update> + <update> + LB: Rename lock and method constants. Add constants for defaults. (rjung) + </update> + <fix> + Default log level should be INFO and not DEBUG. + Default log level should be the same for all server types. (rjung) + </fix> + <fix> + Make rewrite_rule_map and log_level as non mandatory + directives for isapi_redirect. (mturk) + </fix> + <fix> + <bug>40107</bug>: Rewrite is_socket_connected function. + Non blocking socket is not used any more. (mturk) + </fix> + <update> + Allow building with VS2005 without too many warnings. (mturk) + </update> + <fix> + Decide by MMN, which piped log API we should use. + mod_jk 1.2.18 broke compilation with Apache 1.3 pre 1.3.28. (rjung) + </fix> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.17 and 1.2.18"> + <br /> + <subsection name="Native"> + <changelog> + <fix> + Using socklen_t in getsockopt. Also introducing jk_sock_t. (mturk) + </fix> + <update> + Allow recovery wait time below 60 seconds (new minimum is 1 second). (mturk) + </update> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.16 and JK 1.2.17"> + <br /> + <subsection name="Native"> + <changelog> + <fix> + Fix hanging jk status worker when certain attributes are being updated + due to double locking. (rjung) + </fix> + <update> + Allow JkMount to behave like uriworkermap.properties + by parsing pipe symbol as two directive marker. (mturk) + </update> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.15 and JK 1.2.16"> + <br /> + <subsection name="Native"> + <changelog> + <update> + Added simple rewrite capability for IIS. Although simple it + will fulfill most needs. (mturk) + </update> + <update> + Added RECOVER_ABORT_IF_CLIENTERROR recovery_option that closes + the connection if client connection is broken during the request. (mturk) + </update> + <update> + Renamed cache_timeout directive to connection_pool_timeout. (mturk) + </update> + <update> + Added connection_pool_minsize directive. (mturk) + </update> + <update> + Deprecate recycle_timeout directive. (mturk) + </update> + <update> + Corrected some HTML syntax bugs in output of status worker. (rjung) + </update> + <update> + Added the refresh=n parameter to the status worker. It will update the display every n seconds. (rjung) + </update> + <update> + Balancer: Add attribute distance to balanced workers to express preferences between workers. (rjung) + </update> + <update> + Balancer: Add attribute jvm_route to balanced workers to be able to use the same target in different balancers. (rjung) + </update> + <update> + Status: Add lb_mult to status. (rjung) + </update> + <update> + Balancer: Make different balancing strategies work in a similar way (use lb_value, use decay during global maintenance, use integer factors for weights. (rjung) + </update> + <update> + Balancer: Improve locking. (rjung) + </update> + <update> + Balancer: Workers start slower after recovering. (rjung) + </update> + <update> + Balancer: Make different balancing strategies work in a similar way (use lb_value, use decay during global maintenance, use integer factors lb_mult for weights). (rjung) + </update> + <update> + Balancer: Move recovery check to global maintenance. (rjung) + </update> + <update> + Balancer: Add global maintenance method, that is called in only one process. (rjung) + </update> + <update> + Extend our use of autoconf to find a 32Bit and a 64Bit unsigned type and their printf formats. (rjung) + </update> + <update> + Logging: piped loggers for JkLogFile and Apache 1.3. (rjung) + </update> + <update> + Logging: Add PID to log lines for each log level apart from REQUEST. (rjung) + </update> + <update> + Logging: flush buffered logs to keep lines in correct order. Output final newline together with log message. (rjung) + </update> + <update> + Reducing shm size. (rjung) + </update> + <update> + Only log removing of old worker, when we actually do it. (rjung) + </update> + <fix> + <bug>37469</bug>: Fix shared memory close for forked childs. + The shared memory will be closed by the parent process. (mturk) + </fix> + <fix> + <bug>37332</bug>: Fix potential misuse of buffer length with + snprintf functions. (mturk) + </fix> + <fix> + <bug>38859</bug>: + [<a href="http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2006-7197"><b>CVE-2006-7197</b></a>] + Protect mod_jk against buggy or malicious + AJP servers in the backend. Patch provided by Ruediger Pluem. (mturk) + </fix> + <fix> + <bug>38889</bug>: Use worker map sorting depending on the path + elements, to comply with Servlet spec. Patch provided by + Steve Revilak. (mturk) + </fix> + <update> + <bug>36138</bug>: Added Busyness lb method. Patch provided + by Chris Lamprecht. (mturk) + </update> + <fix> + Fix pessimistic locking mode. The patch correctly handles the + burst load, by syncing the access to the shared memory data. (mturk) + </fix> + <fix> + <bug>38806</bug>: Reclycle worker even if it is disabled. + This fixes hot-standby workers in error state. (mturk) + </fix> + <fix> + <bug>37167</bug>: Allow building with BSD-ish like make. (mturk) + </fix> + <fix> + ISAPI plugin (isapi_redirect.dll) did not provide correct request data + for IIS + to include in the IIS log. (markt) + </fix> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.14 and 1.2.15"> + <br /> + <subsection name="Native"> + <changelog> + <fix> + Fix AJP13 Cookie2 parsing. Cookie2 was always send as Cookie. + Patch provided by Andre Gebers. (mturk) + </fix> + <fix> + <bug>35862</bug>: NSAPI plugin attempts to read freed memory and attempts to + dereference a null pointer. Patch provided by Brian Kavanagh. (markt) + </fix> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.13 and 1.2.14"> + <br /> + <subsection name="Native"> + <changelog> + <fix> + Fix lb for worker mpm's with cachesize set to lower number then + ThreadsPerChild is. If retries is set to value larger then 3 sleep for + 100 ms on each attempt. This enables to tune the connection cache, + and serialize incoming connections instead returning busy if connection + count is larger then cachesize. (mturk) + </fix> + <fix> + <bug>36525</bug>: Solaris core dump. (mturk) + </fix> + <fix> + <bug>36102</bug>: Worker actions do not persist. (mturk) + </fix> + <fix> + <bug>35864</bug>: Status worker doesn't list workers. + Patch provided by Martin Goldhahn. (mturk) + </fix> + <fix> + <bug>35809</bug>: JkMountCopy don't work for Apache 2.0 Patch provided by + Christophe Dubach. (mturk) + </fix> + <fix> + <bug>35298</bug>: Multiple JK/ISAPI redirectors on a single IIS site are not supported + Patch provided by Tim Whittington. (mturk) + </fix> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.12 and 1.2.13"> + <br /> + <subsection name="Native"> + <changelog> + <fix> + <bug>34397</bug>: Emergency was handled as Error. (jfclere) + </fix> + <fix> + <bug>34474</bug>: // in URL were not handled correctly with Apache-1.3. (jfclere) + </fix> + <fix> + Use 64 bits int for transferred/read bytes. + </fix> + <update> + Added JkOptions +FlushPackets used to optimize memory + usage when sending large data. (mturk) + </update> + <update> + Added lock directive for load balancer that allows more acurate + load balancing in case of burst load. (mturk) + </update> + <update> + Added worker.maintain directive to allow customizing default 10 + second timeout. On busy servers this value needs to be set on + higher value. (mturk) + </update> + <fix> + Fix for NetWare compiler to deal with different types between AP13 + and AP2 SDKs. (fuankg) + </fix> + <update> + Emit much more legible user.dmp crash analysis output for WIN32. (wrowe) + </update> + <fix> + <bug>34558</bug>: Fix first failover request. (mturk) + </fix> + </changelog> + </subsection> +</section> + +<section name="Changes between 1.2.11 and 1.2.12"> + <br /> + <subsection name="Native"> + <changelog> + <update> + Added ForwardLocallAddres JkOptions flag for passing local instead remote + address. Useful for remote addr valve. (mturk) + </update> + <fix>Fix that worker not used, when stopped flag is true. (pero) + </fix> + <update> + Add loadbalance default worker secret attribute to the documentation (pero) + </update> + </changelog> + </subsection> +</section> + +<section name="Changes between 1.2.10 and 1.2.11"> + <br /> + <subsection name="Native"> + <changelog> + <fix>Backport SC_M_JK_STORED from JK2 for passing arbitrary + methods instead failing the request. (mturk) + </fix> + <fix>Added missing SEARCH and ACL http methods. (mturk) + </fix> + <update> + Add worker secret attribute to the documentation (pero) + </update> + <update> + Add a stopped flag to worker configuration. Set flag True and + complete traffic to worker is stopped. + Also update the Ant JkStatusUpdateTask at Tomcat 5.5.10 release. + Only usefull in a replicated session cluster.(pero) + </update> + <update>Added worker maintain function that will maintain all + the workers instead just the current one. This enables to recycle + the connections on all workers. (mturk) + </update> + <update>Use shutdown when recycling connections instead hard + breaking the socket. (mturk) + </update> + <update>Add unique directives checking. The directives if + unique are now overwritten instead concatenated. (mturk) + </update> + <update>Allow multiple worker.list directives. (mturk) + </update> + <fix> + <bug>34577</bug>: For IIS log original request instead loging + the request for ISAPI extension. (mturk) + </fix> + <fix> + <bug>34558</bug>: Make sure the returned status codes are the same + for ajp and lb workers. (mturk) + </fix> + <fix> + <bug>34423</bug>: Use APR_USE_FLOCK_SERIALIZE for setting log lock + on platforms like FreeBSD. Patch provided by Allan Saddi. (mturk) + </fix> + <fix> + <bug>33843</bug>: Fix obtaining LDFLAGS that were used for building + Apache HTTPD. Patch provided by Beat Kneubuehl. (mturk) + </fix> + <fix> + <bug>34358</bug>: Enable load balancer method configuration. (glenn) + </fix> + <fix> + <bug>34357</bug>: In some situations Apache 2 mod_jk could segfault + when the JkAutoAlias directive is used. (glenn) + </fix> + <update> + Add --enable-prefork to the documentation (pero) + </update> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.9 and 1.2.10"> + <br /> + <subsection name="Native"> + <changelog> + <update>Set default shared memory to 64K instead 1M. (mturk) + </update> + <fix>Do not mark the worker in error state if headers are + larger then AJP13 limit. (mturk) + </fix> + <update> + On Series you should use the latest PTF for Apache 2.0 + (which is now 2.0.52) and ad minima SI17402/SI17061 or cumulative + including them. (hgomez) + </update> + <update> + Change the xml status format to xml attribute syntax (pero) + </update> + <fix> + <bug>33248</bug>: Fix builds where apxs defines multiple + directories for APR includes. (mturk) + </fix> + <fix> + <bug>32696</bug>: Return 404 instead 403 when WEB-INF is requested + to comply with Servlet spec. (mturk) + </fix> + <update>Added ANT task for managing jkstatus. (pero) + </update> + <update> + If socket_timeout is set, check if socket is alive before + sending any request to Tomcat. (mturk) + </update> + <update> + Added JkMountFile for Apache web servers. This file can contain + uri mappings in the form (/url=worker), and is checked for + updates at regular 60 second interval. (mturk) + </update> + <update> + Added status worker for managing worker runtime data using + web page. (mturk) + </update> + <update> + Added load balancer method directive that is used for setting + the algorithm used for balancing workers. Method can be either + Request (default) or Traffic. (mturk) + </update> + <update> + Added shared memory to allow dynamic configuration. Shared memory + is needed only for unix platform and web servers having multiple + child processes. For Apache web server two new directives has been + added (JkShmFile and JkShmSize). (mturk) + </update> + <update> + Added textupdate mode to status worker to handle remote updates + from ant tasks.(pero) + </update> + <fix> + <bug>33562</bug>: Fix Reply_timeout when recovery_options + is larger than 1. Patch provided by Takashi Satou. (mturk) + </fix> + <fix> + <bug>33308</bug>: Fix segfaults when ForwardDirectories is enabled + with Apache 1.3 + </fix> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.7 and 1.2.8"> + <br /> + <subsection name="Native"> + <changelog> + <update> + Allow anyone to debug and diagnose stack dumps using windbg or any + other debugging tool, and (if they add the .pdb files to their + installation) to make sense of dr watson logs. + Patch provided by William A. Rowe (wrowe) + </update> + <fix> + Fix in_addr_t usage by using the real struct ignoring typedef. + Patch provided by William A. Rowe (wrowe) + </fix> + <fix> + Fix url rewriting by restoring the in place uri from which the + jsessionid was removed. (mturk) + </fix> + <update> + Make load balancer algorithm thread safe by introducing mutex + to the load balancer worker. (mturk) + </update> + <fix> + Fix sending error pages for IIS to client by adding Content-Type header + using correct api function call. (mturk) + </fix> + <fix> + <bug>32696</bug>: Prevent IIS from crushing when web-inf url was requested. (mturk) + </fix> + <update> + Use default cachesize for servers that support discovering the number of + threads per child process. (mturk). + </update> + <fix> + Fix Apache content-length header parsing using case insensitive compare. (billbarker) + </fix> + <fix> + Fix parsing AJP headers using case insensitive compare. (mturk) + </fix> + <fix> + Use infinite socket timeout if socket_timeout is set to zero or less then zero. (mturk) + </fix> + <update> + Change <b>balanced_workers</b> to <b>balance_workers</b> but keep + backward compatibility preserving the old directive. (mturk). + </update> + <fix> + Fix ajp initialization for workers with cache_size set to zero. (mturk) + </fix> + <update> + <bug>32317</bug>: Making mod_jk replication aware (Clustering Support). + Patch provided by Rainer Jung. (mturk). + </update> + <fix> + <bug>31132</bug>: Core dump when JkLogFile is missing from conf. (mturk) + </fix> + </changelog> + </subsection> +</section> +<section name="Changes between 1.2.6 and 1.2.7"> + <br /> + <subsection name="Native"> + <changelog> + <update> + Added new property named recover_time that can be used to change the + default 60 second recover time. (mturk) + </update> + <update> + Added custom retries for worker, so we don't depend on default setting. + If set to a number grater then 3, it will sleep for 100ms on retry greater + then 3 and then try again. (mturk) + </update> + <update> + Added JkWorkerProperty directive that enables omiting workers.properties file. + For example: JkWorkerProperty worker.ajp13a.port=8009. (mturk) + </update> + <fix> + Check all JSESSIONID cookies for a valid jvmRoute. If you have multiple Tomcats + with overlapping domains, then you can get multiple cookies without a defined order. + This will route correctly as long as the different domains don't have any + Tomcats in common. (billbarker) + </fix> + <update> + Added JkUnMount directive for negative mappings that works as opposite to JkMount directives. + It is used for blocking of particular URL or content type. (mturk) + </update> + <update> + Added wildchar match uri mappings. One can now use JkMount to + map /app/*/servlet/* or /app?/*/*.jsp. (mturk) + </update> + <update> + Rewrite the logging by adding Trace options. (mturk) + </update> + <update> + Added socket_timeout property that sets the timeout + for the socket itself. (mturk) + </update> + <fix> + Changed socket_timeout property to recycle_timeout. This better + explains what the directive actually does. (mturk) + </fix> + <fix> + Changed the load balancer algorithm. + The idea behind this new scheduler is the following: + lbfactor is <i>how much we expect this worker to work</i>, + or <i>the worker's work quota</i>. + lbstatus is <i>how urgent this worker has to work to fulfill its quota + of work</i>. We distribute each worker's work quota to the worker, and then look + which of them needs to work most urgently (biggest lbstatus). This + worker is then selected for work, and its lbstatus reduced by the + total work quota we distributed to all workers. Thus the sum of all + lbstatus does not change.(*) + If some workers are disabled, the others will + still be scheduled correctly. (mturk) + </fix> + </changelog> + </subsection> +</section> +<section name="JK 2"> +<p>JK2 has been put in maintainer mode and no further development will take place. +The reason for shutting down JK2 development was the lack of developers interest. +Other reason was lack of users interest in adopting JK2, caused by configuration +complexity when compared to JK. +</p> +</section> + +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/doccontrib.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/doccontrib.xml new file mode 100644 index 00000000..5108a85f --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/doccontrib.xml @@ -0,0 +1,337 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="doccontrib.html"> + + &project; +<copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> +<properties> +<title>How to Contribute to the Documentation</title> +<author email="rsowders@usgs.gov">Robert Sowders</author> +<date>$Date: 2010-03-15 16:27:18 +0100 (Mon, 15 Mar 2010) $</date> +</properties> +<body> +<section name="Introduction"> +<p> + This document describes how you can easily contribute to the +documentation. I'm going to try to make it easy for everyone to help out with +the documentation of Tomcat, more specifically the documentation for the +connectors. This is written from a windows user perspective as I believe they +will most benefit from it. For people using Unix it should be easy for them to +apply these steps. Just substitute Unix syntax where needed. +</p> +<p> + The documentation is produced using xml with xsl style sheets. This +effectivly seperates the content of the documents from the style, so all that +contributers need to worry about the content. It is much easier to use than +html. +</p> +<p> + It's all really quite simple. Here is what you will need: +<ul> +<li> +<b>A recent version of Ant</b> +</li> +<li> +<b>The source code for the connectors from subversion</b> +</li> +<li> +<b>Any ascii text editor</b> +</li> +</ul> +</p> +</section> +<section name="Getting Started Step by Step"> +<p> + After you get these tools they are simple to set up. +</p> + <subsection name="STEP 1. Get Ant"> +<p> + Install <a href="http://ant.apache.org/">Ant</a>. The only advice I +have is to choose a simple installation path. Now set an environment variable +for ANT_HOME, and then add the location of the Ant/bin directory to your PATH +variable. Consult your Operating system documentation for information on how +to do this. When you are finished verify that you can run ant from the command +line. +</p> +<p> + Ant is used to build the documentation, among other things, and it must be +able to see a file called <b>build.xml</b>. This file is located in the +<b>xdocs</b> directory. In the +<b>build.xml</b> file there is a target named <b>all</b> that will be used to build +the docs. +</p> +</subsection> +<subsection name="STEP 2. Get the sources"> +<p> + Get the sources for +<a href="http://svn.apache.org/repos/asf/tomcat/jk/trunk/">tomcat-connectors</a> +from the subversion repository. If you'll +be editing from a windows platform you will need a windows subversion client. There +are several available. I like <a href="http://tortoisesvn.tigris.org/">turtoiseSVN</a>. +Unix users should install the subversion client of their choice, +if they don't already have one. +</p> +<p> + You are ready to download the sources now. Change directory to the +location where you want your repository to be. For simplicity we will call this +your <b>SVN_HOME</b>. Mine is located in C:\build. +</p> +<p> + Run the following command to <b>checkout</b> the sources for the first time. +You should only need to do this once. +<screen> +<read> </read> +<read>C:\build\>svn checkout http://svn.apache.org/repos/asf/tomcat/jk/trunk/ +tomcat-connectors</read> +<read> </read> +</screen> +</p> +<p> + You should now be watching all the downloads come in. Now that you have +the sources on your machine the hard part is over. From now on, to update your +sources all you have to do is cd into any directory in your repository and run +the <b>svn update</b> command. + <screen> +<note> To update your xdocs directory simply cd into the xdocs directory +and:</note> +<read>C:\build\tomcat-connectors\>cd xdocs</read> +<read>C:\build\tomcat-connectors\xdocs\>svn update</read> +</screen> +</p> +</subsection> +<subsection name="STEP 3. Test your build environment"> +<p> + Open a command prompt window and cd to the directory where you downloaded +the source. Now cd into the xdocs directory so that <b>Ant</b> can see the +<b>build.xml</b> file. Then from a command prompt, run the following: +<screen> +<read> </read> +<read>C:\build\tomcat-connectors>cd xdocs</read> +<read>C:\build\tomcat-connectors\xdocs>ant all</read> +<read> </read> +</screen> +</p>. +<p> + You should see the ant compiler messages scrolling by rapidly and then stop +with the following: +<screen> +<read>[style] Transforming into C:\build\tomcat-connectors\build\docs\news\printer></read> +<read>[style] Processing C:\build\tomcat-connectors\xdocs\news\20041100.xml +to</read> +<read>C:\build\tomcat-connectors\build\docs\news/20041100.html</read> +<read>[style] Loading stylesheet C:\build\tomcat-connectors\xdocs\style.xsl</read> +<read>[style] Processing C:\build\tomcat-connectors\xdocs\news\20050101.xml +to</read> +<read>C:\build\tomcat-connectors\build\docs\news/20050101.html</read> +<read>[style] Processing C:\build\tomcat-connectors\xdocs\news\20060101.xml +to</read> +<read>C:\build\tomcat-connectors\build\docs\news/20060101.html</read> +<read>[style] Transforming into C:\build\tomcat-connectors\build\docs></read> +<read>[style] Processing C:\build\tomcat-connectors\xdocs\index.xml +to</read> +<read>C:\build\tomcat-connectors\build\docs\index.html</read> +<read>[style] Loading stylesheet C:\build\tomcat-connectors\xdocs\style.xsl</read> +<read> </read> +<read>BUILD SUCCESSFUL</read> +<read>Total time: 10 seconds</read> +<read>C:\build\tomcat-connectors></read> +</screen> +</p> +<p> + All the xml files present in the xdocs directory structure were transformed +to html and copied to the <b>SVN_HOME\tomcat-connectors\build\docs</b> +directory. Open one of the +html files in your browser and see how it looks. +</p> +</subsection> +<subsection name="STEP 4. The editing process."> +<p> + I find it easier to use two windows while doing my updates. One I call my +<b>build</b> window. I keep this one in the <b>SVN_HOME\tomcat-connectors\xdocs</b> +directory and I only run two commands in this window: +<screen> +<read> </read> +<note> First I run</note> +<read>ant clean</read> +<note> Then I run</note> +<read>ant all</read> +<read> </read> +</screen> +</p> +<p> + My second window I call my <b>edit</b> window and I keep that one in the +<b>SVN_HOME\tomcat-connectors\xdocs</b> directory where I'm doing my +edits, diffs and svn updates. +</p> +<p> + Before you start editing you should always update your local repository to +prevent conflicts. +<screen> +<note> You only need to update the xdocs directory</note> +<read>C:\build\tomcat-connectors>cd xdocs</read> +<read>C:\build\tomcat-connectors\xdocs></read> +<read>C:\build\tomcat-connectors\xdocs>svn update</read> +</screen> +</p> +<p> + Now that your repository is up to date you can begin editing. Find +something in the documentation to edit. When you find something remember the +name of the file. In your <b>edit</b> window find and edit the xml source file +with the same name. After you are done return to the <b>build</b> window, and +in the <b>SVN_HOME\tomcat-connectors\xdocs</b> directory run: +<screen> +<read> </read> +<read>C:\build\tomcat-connectors\xdocs> ant clean</read> +<read> </read> +</screen> +</p> +<p> + This will delete all the previous html files and make the area ready for +updated material. Now to make fresh documents that incorporate your changes +run: +<screen> +<read> </read> +<read>C:\build\tomcat-connectors\xdocs>ant all</read> +<read> </read> +</screen> +</p> +<p> + Use your browser to view the edits you just made, they will be in the +<b>SVN_HOME\tomcat-connectors\build\docs</b> sub-tree. If it looks +good and is ready to go, +all that is left to do is to create a patch and submit it. +</p> +</subsection> +<subsection name="STEP 5. Creating a patch and submitting it."> +<p> + From your <b>edit</b> window cd into the directory that contains the xml +file you are working on, and run the <b>svn update</b> command. For example, +to produce a diff of the index.xml file and call it patch.txt, you +would cd into the directory containing the index.xml file and: +<screen> +<read>C:\build\tomcat-connectors\xdocs\>svn diff index.xml > +patch.txt.</read> +<read> </read> +</screen> +</p> +<p> + Now that you have your patch you are ready to send it in. +</p> +<p> + Patches to the documentation are handled just like a bug report. You +should submit your patches to <a +href="http://issues.apache.org/bugzilla/">http://issues.apache.org/bugzilla/</a> + and include a good one line subject. If this is your first time to use the +bug database then you should read <a +href="http://issues.apache.org/bugzilla/bugwritinghelp.html">http://issues.apach +e.org/bugzilla/bugwritinghelp.html.</a> You will need to create a user +account. At the web site paste your patch into the web form and don't forget +to describe what it is your patch is for. Sooner or later a someone with +commit privileges will review your suggestion. +</p> +</subsection> +</section> +<section name="Subversion Basics"> +<p> + After you have checked out the sources the first time it is much easier to +use subversion. You can cd into any directory of the repository and run <b>svn +update</b> to get the latest sources for that directory. For editing +purposes you should always update your repository before you start editing to +reduce conflicts. +</p> +<p> + You will need to run <b>svn diff</b> to generate patches for submission. +Again cd into the directory containing the file you are editing and run <b>svn +diff name_of_the_file_you_edited > patch.txt</b> to generate a patch for +submission. +</p> +<p> + Pay attention to the terminal window during the update. +</p> +<p> + Lines begining with a <b>A</b> indicate files that have been added. +</p> +<p> + Lines begining with a <b>D</b> indicate files that have been deleted. +</p> +<p> + Lines begining with a <b>U</b> mean the local copy was patched to update it +to the current version in the master repository. +</p> +<p> + Lines begining with a <b>G</b> mean your local copy is different from the +master copy, and the changes were successfully merged into your copy. +</p> +<p> + Lines begining with a <b>C</b> mean there was a conflict in merging the +changes and you need to review the file and merge the changes manually. Search +for >>>> and merge the changes. +</p> +<p> + Lines begining with a <b>?</b> indicate files that reside on your local +system which are not part of the repository. You will normally see this when +you are creating new files for submission. +</p> +</section> + +<section name="Updating Web site"> +<p> + Only Committers are able to update the web site (http://tomcat.apache.org/connectors-doc/). + To do it: + <ul> + <li>Connect to people.apache.org.</li> + <li>umask 002</li> + <li>Copy the changed files to /www/tomcat.apache.org/connectors-doc/.</li> + <li>or use ant from a checkout tomcat/jk/trunk/xdocs repository:<br /> + ant -Dbuild.dir=/www/tomcat.apache.org -Ddist.name=connectors-doc + </li> + <li>The changes need around 4 hours to be synced to tomcat.apache.org.</li> + </ul> +</p> +</section> +<section name="Guides and Resources"> +<p> + A little help to get you started if you need it +</p> +<ul> +<li> +<a href="http://www.xml.org/xml/resources_focus_beginnerguide.shtml">XML +Beginner's Guide</a> +</li> +<li> +<a href="http://issues.apache.org/bugzilla/">Bugzilla</a> +</li> +<li> +<a href="http://issues.apache.org/bugwritinghelp.html">Bugzilla Bug +Writing Guide</a> +</li> +<li> +<a href="http://ant.apache.org/">Ant</a> +</li> +<li> +<a href="http://subversion.tigris.org/">Subversion Home</a> +</li> +<li> +<a href="http://svn.apache.org/repos/asf/tomcat/jk/trunk/xdocs/">JK Docs repository</a> +</li> +</ul> +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/faq.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/faq.xml new file mode 100644 index 00000000..8525f815 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/faq.xml @@ -0,0 +1,324 @@ +<?xml version="1.0"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="faq.html"> + + &project; +<copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> +<properties> +<title>FAQ</title> +<author email="hgomez@apache.org">Henri Gomez</author> +<date>$Date: 2009-03-05 12:42:14 +0100 (Thu, 05 Mar 2009) $</date> +</properties> +<body> +<section name="General"> +<p> +General Informations and FAQ about JK +</p> +<subsection name="Where can I get help/support for JK ?"> +<p> +The primary mechanism for support is through the JK +documentation included in the doc directory. +Documentation is also available on the Apache Tomcat web site devoted to the +<a href="http://tomcat.apache.org/connectors-doc/"> +Apache Tomcat Connectors Project</a> +For additional help, the best resource is the Tomcat Users Discussion list. +You should start by searching +<a href="http://mail-archives.apache.org/mod_mbox/tomcat-users/"> +the mail list archive</a> +before you post questions to the list. +If you are unable to locate the answer to your question in the archive, +you can post questions about JK to the user list for assistance. +Make sure that you include the version of your Webserver, +that you are using as well as the platform you are running on +and go +<a href="http://tomcat.apache.org/lists.html"> +here</a> +to determine how to subscribe to tomcat mailing list. +</p> +</subsection> + +<subsection name="I can't find JK anywhere. Where is it?"> +<p> +Now that JK moved to the <b>tomcat-connectors</b> repository, +the source and the binaries for JK can be downloaded from a mirror at the +<a href="http://tomcat.apache.org/download-connectors.cgi"> +Tomcat Connectors (mod_jk, mod_jk2) Downloads</a> page. +</p> +</subsection> + +<subsection name="What's the difference between JK and mod_jk ?"> +<br /> +<p> +<b>JK</b> is a project covering web-servers to Tomcat connectors, +whereas <b>mod_jk</b> is the <a href="../webserver_howto/apache.html">Apache module</a> developed in JK. +</p> + +<p> +<a href="../webserver_howto/iis.html">IIS webserver</a>support is implemented on JK, using a redirector +called <b>isapi redirector</b>. +</p> + +<p> +<a href="../webserver_howto/nes.html">Netscape/SunONE/Sun webserver</a>webserver support is implemented on JK, using a redirector +called <b>nsapi redirector</b>. +</p> + +</subsection> + +<subsection name="Where can I get more information ?"> +<p> +For <b>JK 1.2.x</b>, you should read : +</p> + +<ul> + +<li> +<a href="../generic_howto/quick.html">For the impatient</a> +</li> + +<li> +<a href="../webserver_howto/apache.html">Apache and JK</a> +</li> + +<li> +<a href="../webserver_howto/iis.html">IIS and JK</a> +</li> + +<li> +<a href="../webserver_howto/nes.html">Netscape/SunONE/Sun and JK</a> +</li> + +<li> +<a href="../generic_howto/workers.html">Workers configuration</a> +</li> +</ul> + +<p> +For more detailed information, have a look at the Reference Guide. +You could also try searching the mailing list archives for "JK" or look at the source. +</p> +</subsection> + +<subsection name="Which protocol should I use? Ajp12 or Ajp13?"> +<p> +<a href="../ajp/ajpv13a.html">Ajp13</a> is a newer protocol, it's faster, and it works better with SSL. +You almost certainly want to use it now that <strong>ajp12 is deprecated</strong>. +</p> +<p> +Also ajp13 is supported by all Apache Tomcat including 3.2.x , 3.3.x, 4.0.x, 4.1.x, 5.0.x, 5.5.x +and the new tomcat 6. +</p> + +<p> +Others Servlet engines like <b>jetty</b> have support for Ajp13. +</p> +</subsection> + +<subsection name="I've got a firewall between my web server and Tomcat which drops ajp13 connections after some time"> +<p> +Ajp13 uses persistant connections where the traffic could be null if there is no request to be sent to Tomcat. +Firewalls use to drop inactive connections and will make your web server and Tomcat think the connection is valid. +</p> +<p> +Starting with JK 1.2.0, a <b>socket_keepalive</b> property as been added to ajp13 settings, and you should take a look at +it in <a href="../generic_howto/workers.html">Workers HowTo</a> and +<a href="../reference/workers.html">workers.properties reference</a>. +If nothing else helps, you can try <b>JkOptions +DisableReuse</b>, but this will have strong performance implications. +</p> +</subsection> + +<subsection name="Under heavy load, I've got many threads in Tomcat even if my Apache Web Server handles much of the load"> +<p> +Under heavy load, Apache Web Server creates many children to handle the load, +which will in turn create many connections +to Tomcat to forward the requests they should handle. +Apache Web Server will normally kill the children/threads when the load decreases. +But if the load is still there and even if only Apache handles the requests, +ie static contents, the children are kept and with them all the ajp13 connections, +even if they are no more used. +</p> +<p> +To close connections after some time of inactivity you can use <b>connection_pool_timeout</b>, +for more informations refer to <a href="../reference/workers.html">workers.properties reference</a>. +</p> +</subsection> + +</section> + +<section name="Apache"> +<p> +Informations and FAQ about mod_jk and Apache Web Servers. +</p> +<subsection name="Whenever I restart Tomcat, Apache locks up!"> +<p> +The Ajp13 protocol keeps an open socket between Tomcat and Apache. +Release of mod_jk present in J-T-C handles the network failure. +But with very ancient releases of mod_jk, you may have to restart Apache as well. +</p> +</subsection> + +<subsection name="Why do there exist two files mod_jk.so (-eapi ad -noeapi) in download directories for Apache 1.3?"> +<p> +Many versions of Apache use a modified API, known at Extended API, developed for use with the +<a href="http://www.modssl.org">mod_ssl module</a>. Starting with Apache 2.0 there is no more difference. +</p> + +<p> +For example, Apache 1.3 present in certains recent Linux distributions include the +<b>mod_ssl</b> module. +</p> + +<p> +So if you got such 'Extended Apache', you need to use <b>mod_jk.so-eapi</b>. +</p> + +<p> +You should use <b>mod_jk.so-noeapi</b> only for 'Standard Apache' (ie without mod_ssl). +</p> + +<p> +It's wise to avoid using EAPI modules on STD API Apache or to use standard API modules on EAPI Apache. +Allways be sure to have the <b>mod_jk.so</b> witch match your version of Apache +</p> +</subsection> + +<subsection name="What's that message about 'garbled DSO ?'"> +<p> +It's related to Apache EAPI, the message <code>'mod_jk.so is garbled - perhaps this is not an Apache module DSO ?'</code> +just told you, that your're trying to install a mod_jk.so DSO module that was compiled on an Apache using EAPI, +like apache-mod_ssl or apache from Redhat distro 6.2/7.0 but your system use the standard apache with normal API. +</p> +</subsection> + +<subsection name="And the message about 'module might crash under EAPI!"> +<p> +Also related to EAPI, the message <code>'[warn] Loaded DSO /usr/lib/apache/mod_jk.so uses plain Apache 1.3 API, +this module might crash under EAPI! (please recompile it with -DEAPI)'</code>, the mod_jk.so was compiled under normal +Apache with standard API and you try to install the module on an Apache using EAPI. +</p> +</subsection> + +<subsection name="APXS is getting an error during the build of mod_jk, like rc=0 or rc=255. I tried all of the steps in the build section, what do I do now ?"> +<p> +APXS is a Perl script that is created when you build the Apache web server from source. +Chances are that if you are getting these errors and you obtained Apache as a binary distribution, +that APXS is not configured correctly for your system. +Your best bet is to get the Apache source from http://httpd.apache.org and build it yourself. +Use the following for a basic build (read the Apache docs for other options): +<screen> +<type>cd /usr/local/src</type><br/> +<type>gzip -dc apache_1.3.19.tar.gz|tar xvf -</type><br/> +<type>cd apache_1.3.19</type><br/> +<type>./configure --prefix=/usr/local/apache \</type><br/> +<type> --enable-module=most \</type><br/> +<type> --enable-shared=max</type><br/> +<type>make</type><br/> +<type>make install</type><br/> +</screen> +</p> +<p> +Note: The above steps assume that you downloaded the Apache source and placed it in your /usr/local/src directory. +</p> +</subsection> + +<subsection name="Apache 2.0 complains about incorrect module version"> +<p> +Since Apache 2.0 API still change often, the Apache 2.0 teams decide to put in headers of compiled modules the +Apache 2.0 version used to compile the module. This check is called Magic Module Number bump. +</p> +<p> +At start time Apache 2.0 check that version in modules headers and stop if it detect that a module was compiled +for another Apache 2.0 version. As such you should allways use modules compiled for the same Apache 2.0 version. +This check may be removed if the future. +</p> +</subsection> + +<subsection name="Does it work for Apache 2.2?"> +<p> +mod_jk works well with Apache 2.2. You need a binary module compiled for version 2.2 of the Apache web server. +A binary compiled for version 2.0 will not work. +</p> +<p> +Important parts of the functionality of mod_jk have been reimplemented as Apache httpd modules mod_proxy_ajp +and mod_proxy_balancer. These are part of the standard distributoin of Apache 2.2. The new modules do not contain +all features of mod_jk, but you get them automatically with every Apache 2.2. +</p> +</subsection> + +<subsection name="JNI doesn't work with Apache 1.3"> +<warn>JNI workers have been deprecated. They will likely not work. Do not use them.</warn> +<p> +JNI support requires a multi-threaded environment which is not the general case for Apache 1.3. +You should verify if Apache 1.3 has been build with thread support and if not you could add the +the pthreads library to your <b>httpd.conf</b> file. +</p> + +<source> + # Add pthread to Apache in httpd.conf + LoadModule "/usr/lib/libpthreads.so" +</source> + +<p> +Also keep in mind that JNI is suited for multi-threaded servers and you should consider upgrading +to Apache 2.x to support JNI. +</p> +</subsection> + +<subsection name="JNI report that JVM couldn't be started under Linux"> +<warn>JNI workers have been deprecated. They will likely not work. Do not use them.</warn> +<p> +Under Linux, you should set some environment variables BEFORE launching your Apache server : +</p> + +<screen> +<read>export LD_LIBRARY_PATH=$jre/bin:$jre/bin/classic:$LD_LIBRARY_PATH</read> +</screen> + +<p> +Also some Linux distributions have enabled a GLIBC feature called 'floating stacks' which may not works with kernel +less than 2.4.10 on SMP machines. You should disable floating stacks by exporting an environment variable : +</p> + +<screen> +<read>export LD_ASSUME_KERNEL=2.2.5</read> +</screen> + +<p> +You could have to update your service scripts, ie <b>/etc/rc.d/init.d/httpd</b>, to set these env vars +before your httpd server starts. +</p> +</subsection> + +<subsection name="Mixed errors when building via configure"> +<p> +configure assume you have some GNU tools already installed and configured for your system, and ad minima <b>libtool</b>. +</p> +<p> +Also some systems may have mixed cc and gcc setup which may make you puzzled when trying to link an Apache built with native +c compiler with a jk/jk2 build with gcc. +</p> +<p> +In case the make processing doesn't work as expected, you should use a GNU make <b>gmake</b>. +</p> +</subsection> + +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/jkstatustasks.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/jkstatustasks.xml new file mode 100644 index 00000000..290dec4d --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/jkstatustasks.xml @@ -0,0 +1,218 @@ +<?xml version="1.0"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="jkstatustasks.html"> + + &project; + +<copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> + +<properties> +<title>Status Worker Ant Tasks</title> +<author>Peter Rossbach</author> +<date>$Date: 2008-03-26 00:47:22 +0100 (Wed, 26 Mar 2008) $</date> +</properties> + +<body> + +<section name="Introduction"> +<p>Since version 1.2.19 the JK release contains additional ant tasks. +They can be used to manage the JK web server plugins via the special status worker. +</p> +</section> + +<section name="Manage JK with remote Ant Tasks"> + +<subsection name="Simple antlib integration"> +<p> +<source> +<?xml version="1.0" encoding="UTF-8"?> + +<project name="modjk-status" + xmlns:jk="urn:org-apache-jk-status" + default="status" basedir="."> + + <property name="profile" value=""/> + <property file="jkstatus${profile}.properties"/> + <property file="jkstatus.properties.default"/> + + <path id="jkstatus.classpath"> + <fileset dir="${catalina.home}/bin"> + <include name="commons-logging-api-*.jar"/> + </fileset> + <pathelement location="${catalina.home}/server/lib/catalina-ant.jar"/> + <pathelement location="../dist/tomcat-jkstatus-ant.jar"/> + <pathelement location="${catalina.home}/server/lib/tomcat-util.jar"/> + </path> + + <typedef resource="org/apache/jk/status/antlib.xml" + uri="urn:org-apache-jk-status" classpathref="jkstatus.classpath"/> + + <target name="status" > + <jk:status url="${jkstatus.url}" + username="${jkstatus.username}" + password="${jkstatus.password}" + resultproperty="worker" + echo="off" + failOnError="off"/> + <echoproperties prefix="worker" /> + </target> +</project> +</source> +</p> +</subsection> + +<subsection name="Test Result"> +<p> +<source> +[echoproperties] #Ant properties +[echoproperties] #Sun Dec 10 20:40:21 CET 2006 +[echoproperties] worker.node01.lbmult=1 +[echoproperties] worker.loadbalancer.lock=Optimistic +[echoproperties] worker.node02.transferred=0 +[echoproperties] worker.loadbalancer.sticky_session=false +[echoproperties] worker.node01.distance=0 +[echoproperties] worker.node01.client_errors=0 +[echoproperties] worker.node02.lbmult=1 +[echoproperties] worker.node01.port=7309 +[echoproperties] worker.node01.elected=0 +[echoproperties] worker.loadbalancer.good=2 +[echoproperties] worker.loadbalancer.method=Sessions +[echoproperties] worker.server.port=2090 +[echoproperties] worker.loadbalancer.map.2.type=Wildchar +[echoproperties] worker.node02.route=node02 +[echoproperties] worker.node01.route=node01 +[echoproperties] worker.node01.lbvalue=0 +[echoproperties] worker.node01.lbfactor=1 +[echoproperties] worker.node01.max_busy=0 +[echoproperties] worker.node01.busy=0 +[echoproperties] worker.node01.redirect= +[echoproperties] worker.node02.distance=0 +[echoproperties] worker.loadbalancer.name=loadbalancer +[echoproperties] worker.loadbalancer.sticky_session_force=false +[echoproperties] worker.node02.state=N/A +[echoproperties] worker.node01.state=N/A +[echoproperties] worker.node01.transferred=0 +[echoproperties] worker.loadbalancer.map.length=2 +[echoproperties] worker.node01.type=ajp13 +[echoproperties] worker.node01.address=127.0.0.1\:7309 +[echoproperties] worker.result.type=OK +[echoproperties] worker.loadbalancer.member_count=2 +[echoproperties] worker.loadbalancer.map_count=2 +[echoproperties] worker.loadbalancer.mtime_to_maintenance_min=12 +[echoproperties] worker.loadbalancer.mtime_to_maintenance_max=75 +[echoproperties] worker.node02.lbfactor=1 +[echoproperties] worker.node02.max_busy=0 +[echoproperties] worker.jk_version=mod_jk/1.2.21-dev +[echoproperties] worker.loadbalancer.bad=0 +[echoproperties] worker.node02.redirect= +[echoproperties] worker.node01.host=localhost +[echoproperties] worker.node02.activation=ACT +[echoproperties] worker.loadbalancer.map.1.source=JkMount +[echoproperties] worker.loadbalancer.retries=2 +[echoproperties] worker.node02.elected=0 +[echoproperties] worker.loadbalancer.map.2.source=JkMount +[echoproperties] worker.node02.port=7409 +[echoproperties] worker.loadbalancer.length=2 +[echoproperties] worker.node02.lbvalue=0 +[echoproperties] worker.loadbalancer.degraded=0 +[echoproperties] worker.loadbalancer.map.1.type=Wildchar +[echoproperties] worker.loadbalancer.map.2.uri=/myapps* +[echoproperties] worker.node02.client_errors=0 +[echoproperties] worker.length=1 +[echoproperties] worker.node01.domain=d20 +[echoproperties] worker.loadbalancer.recover_time=60 +[echoproperties] worker.server.name=localhost +[echoproperties] worker.node02.domain= +[echoproperties] worker.result.message=Action finished +[echoproperties] worker.node02.busy=0 +[echoproperties] worker.node01.readed=0 +[echoproperties] worker.node01.errors=0 +[echoproperties] worker.node02.address=127.0.0.1\:7409 +[echoproperties] worker.node02.readed=0 +[echoproperties] worker.loadbalancer.busy=0 +[echoproperties] worker.web_server=Apache/2.0.59 (Unix) mod_jk/1.2.21-dev +[echoproperties] worker.node02.errors=0 +[echoproperties] worker.node02.type=ajp13 +[echoproperties] worker.loadbalancer.map.1.uri=/ClusterTest* +[echoproperties] worker.node01.activation=ACT +[echoproperties] worker.loadbalancer.max_busy=0 +[echoproperties] worker.loadbalancer.type=lb +[echoproperties] worker.node02.host=localhost +</source> +</p> +</subsection> + +<subsection name="Update Load Balancer"> +<p> +<source> + <target name="updatelb" > + <jk:updateloadbalancer url="${jkstatus.url}" + username="${jkstatus.username}" + password="${jkstatus.password}" + loadbalancer="loadbalancer" + method="Busyness" + retries="2" + recoverWaitTime="60" + lock="Optimistic" + forceStickySession="false" + stickySession="false"/> + </target> +</source> +</p> +</subsection> + +<subsection name="Update Worker"> +<p> +<source> + <target name="updatew" > + <jk:updateworker url="${jkstatus.url}" + username="${jkstatus.username}" + password="${jkstatus.password}" + loadbalancer="loadbalancer" + worker="node01" + lbfactor="2" + activation="Active" + redirect="" + domain="" + route="node01" + distance="0"/> + </target> +</source> +</p> +</subsection> + +<subsection name="Reset Worker"> +<p> +<source> + <target name="reset" > + <jk:reset url="${jkstatus.url}" + username="${jkstatus.username}" + password="${jkstatus.password}" + loadbalancer="loadbalancer" + worker="node01" + /> + </target> +</source> +</p> +</subsection> + +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/project.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/project.xml new file mode 100644 index 00000000..00188659 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/project.xml @@ -0,0 +1,81 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<project name="Apache Tomcat Connector Documentation - Miscellaneous Documentation" + href="http://tomcat.apache.org/"> + + <title>The Apache Tomcat Connector - Miscellaneous Documentation</title> + + <logo href="/images/tomcat.gif"> + The Apache Tomcat Connector - Miscellaneous Documentation + </logo> +<body> + + <menu name="Links"> + <item name="Docs Home" href="../index.html"/> + </menu> + + <menu name="Reference Guide"> + <item name="workers.properties" href="../reference/workers.html"/> + <item name="uriworkermap.properties" href="../reference/uriworkermap.html"/> + <item name="Status Worker" href="../reference/status.html"/> + <item name="Apache HTTP Server" href="../reference/apache.html"/> + <item name="IIS" href="../reference/iis.html"/> + </menu> + + <menu name="Generic HowTo"> + <item name="For the impatient" href="../generic_howto/quick.html"/> + <item name="All about workers" href="../generic_howto/workers.html"/> + <item name="Timeouts" href="../generic_howto/timeouts.html"/> + <item name="Load Balancing" href="../generic_howto/loadbalancers.html"/> + <item name="Reverse Proxy" href="../generic_howto/proxy.html"/> + </menu> + + <menu name="Webserver HowTo"> + <item name="Apache HTTP Server" href="../webserver_howto/apache.html"/> + <item name="IIS" href="../webserver_howto/iis.html"/> + <item name="Netscape/SunOne/Sun" href="../webserver_howto/nes.html"/> + </menu> + + <menu name="AJP Protocol Reference"> + <item name="AJPv13" href="../ajp/ajpv13a.html"/> + <item name="AJPv13 Extension Proposal" href="../ajp/ajpv13ext.html"/> + </menu> + + <menu name="Miscellaneous Documentation"> + <item name="Frequently asked questions" href="../miscellaneous/faq.html"/> + <item name="Changelog" href="../miscellaneous/changelog.html"/> + <item name="Current Tomcat Connectors bugs" href="http://issues.apache.org/bugzilla/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Tomcat+Connectors&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0="/> + <item name="Contribute documentation" href="../miscellaneous/doccontrib.html"/> + <item name="JK Status Ant Tasks" href="../miscellaneous/jkstatustasks.html"/> + <item name="Reporting Tools" href="../miscellaneous/reporttools.html"/> + <item name="Old JK/JK2 documentation" href="http://tomcat.apache.org/connectors-doc-archive/jk2/index.html"/> + </menu> + + <menu name="News"> + <item name="2011" href="../news/20110701.html"/> + <item name="2010" href="../news/20100101.html"/> + <item name="2009" href="../news/20090301.html"/> + <item name="2008" href="../news/20081001.html"/> + <item name="2007" href="../news/20070301.html"/> + <item name="2006" href="../news/20060101.html"/> + <item name="2005" href="../news/20050101.html"/> + <item name="2004" href="../news/20041100.html"/> + </menu> + +</body> +</project> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/reporttools.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/reporttools.xml new file mode 100644 index 00000000..b5162abd --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/reporttools.xml @@ -0,0 +1,91 @@ +<?xml version="1.0"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="reporttools.html"> + + &project; +<copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> +<properties> +<title>Reporting Tools</title> +<author>Glenn Nielsen</author> +<date>$Date: 2009-10-18 16:13:42 +0200 (Sun, 18 Oct 2009) $</date> +</properties> +<body> +<section name="Reporting Tools"> +<p> +The mod_jk source distribution contains two perl scripts in the +tools/reports directory which can be used to analyze the mod_jk +logs, save statistical data, and generate report graphs. +</p> + +<p><code>tomcat_trend.pl log_dir archive_dir</code></p> +<p> +Script for analyzing mod_jk.log data when logging tomcat request data using +the <code>JkRequestLogFormat</code> Apache mod_jk configuration. +Generates statistics for request latency and errors. Archives the generated +data to files for later use in long term trend graphs and reports. +</p> + +<p><code>tomcat_reports.pl archive_dir reports_dir</code></p> +<p> +Script for generating reports and graphs using statistical data generated +by the <code>tomcat_trend.pl</code> script. + +The following graphs are created: +<ul> + <li>tomcat_request.png - Long term trend graph of total number of tomcat + requests handled.</li> + <li>tomcat_median.png - Long term overall trend graph of tomcat request + latency median.</li> + <li>tomcat_deviation.png - Long term overall trend graph of tomcat request + mean and standard deviation.</li> + <li>tomcat_error.png - Long term trend graph of requests rejected by tomcat. + Shows requests rejected when tomcat has no request processors available. + Can be an indicator that tomcat is overloaded or having other scaling + problems.</li> + <li>tomcat_client.png - Long term trend graph of requests forward to tomcat + which were aborted by the remote client (browser). You will normally see + some aborted requests. High numbers of these can be an indicator that + tomcat is overloaded or there are requests which have very high latency.</li> +</ul> +</p> + +<p> +A great deal of statistical data is generated but at this time +only long term trend graphs are being created and no reports. +This is only a start. Many more graphs and reports could be +generated from the data. Please consider contributing back any +new reports or graphs you create. Thanks. +</p> + +<p> +These perl scripts depend upon the following perl modules and libraries: +<ul> + <li>GD 1.8.x graphics library <a href="http://www.boutell.com/gd/"> + http://www.boutell.com/gd/</a></li> + <li>GD 1.4.x perl module</li> + <li>GD Graph perl module</li> + <li>GD TextUtil perl module</li> + <li>StatisticsDescriptive perl module</li> +</ul> +</p> +</section> + +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20041100.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20041100.xml new file mode 100644 index 00000000..03a4296f --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20041100.xml @@ -0,0 +1,161 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="20041100.html"> + + &project; + + <properties> + <author email="general.AT.tomcat.DOT.apache.DOT.org">Apache Jakarta Project</author> + <title>2004 News and Status</title> + </properties> + +<body> + +<section name="2004 News & Status"> +<br /> +<!-- +<a name="2004****.1"> +<h3></h3> +</a> +<hr size="1" noshade="noshade" /> +--> +<a name="20041224.1"> +<h3>17 December - JK-1.2.8 released</h3> +</a> +<p>The Apache Jakarta Tomcat team is proud to announce the immediate availability +of Jakarta Tomcat Connectors 1.2.8. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs during testing this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> +<a name="20041218.1"> +<h3>17 December - JK-1.2.8-rc-1 released</h3> +</a> +<p>The Apache Jakarta Tomcat team is proud to announce the immediate availability +of Jakarta Tomcat Connectors 1.2.8-rc-1 (Relase Canditate 1). +</p> +<p> +We expect it to be ratified as a Stable release when the vote takes place +in the next week. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs during testing this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> +<a name="20041213.1"> +<h3>13 December - JK-1.2.7-beta-3 released</h3> +</a> +<p>The Apache Jakarta Tomcat team is proud to announce the immediate availability +of Jakarta Tomcat Connectors 1.2.7-beta-3. The release contains a fix to few configuration +problems detected with JK-1.2.7-beta-2 version. +</p> +<p> +We expect it to be ratified as a Stable release when the vote takes place +in the next week. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs during testing this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> +<a name="20041207.1"> +<h3>7 December - JK-1.2.7-beta-2 released</h3> +</a> +<p>The Apache Jakarta Tomcat team is proud to announce the immediate availability +of Jakarta Tomcat Connectors 1.2.7-beta-2. The release contains a fix to few compilation +problems detected with JK-1.2.7-beta version. This release also introduces a new +<b>domain</b> concept clustering support. See <bug>32317</bug> for details. +</p> +<p> +We expect it to be ratified as a Stable release when the vote takes place +in the next two weeks. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs during testing this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> + +<a name="20041130.1"> +<h3>30 November - JK-1.2.7-beta released</h3> +</a> +<p>The Apache Jakarta Tomcat team is proud to announce the immediate availability +of Jakarta Tomcat Connectors 1.2.7-beta. The release contains a significant number +of bug fixes and new features. +</p> +<p> +We expect it to be ratified as a Stable release when the vote takes place +in the next two weeks. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<warn> +Since release 1.2.7 the <b>socket_timeout</b> property has been renamed to +<b>recycle_timeout</b>. +The socket_timeout now sets the real timeout for socket operations. +</warn> +<p>If you find any bugs during testing this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> + +<hr size="1" noshade="noshade" /> + +<a name="20041115.1"> +<h3>15 November - JK2 is officially unsupported</h3> +</a> +<p>JK2 has been put in maintainer mode and no further development will take place. +The reason for shutting down JK2 development was the lack of developers interest. +Other reason was lack of users interest in adopting JK2, caused by configuration +complexity when compared to JK. +</p> +<p>The latest official JK2 release is 2.0.4. +</p> +<p>JK2 will have it's successor within core Apache2.1/2.2 distribution. +We have developed new <b>proxy_ajp</b> that is an addition to +the mod_proxy and uses Tomcat's AJP protocol stack. It is developped in httpd-2.1 +and integrated in it. We have also developed a new <b>proxy_balancer</b> module +for load balancing http and ajp protocol stacks. +</p> +<p>JK will be fully supported for all other web servers. The next JK release is +planned for the end of November. Lots of code from JK2 has been ported to JK +</p> +<hr size="1" noshade="noshade" /> + +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20050101.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20050101.xml new file mode 100644 index 00000000..a7fc9eec --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20050101.xml @@ -0,0 +1,174 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="20050101.html"> + + &project; + + <properties> + <author email="general.AT.tomcat.DOT.apache.DOT.org">Apache Jakarta Project</author> + <title>2005 News and Status</title> + </properties> + +<body> + +<section name="2005 News & Status"> +<br /> +<!-- +<a name="2004****.1"> +<h3></h3> +</a> +<hr size="1" noshade="noshade" /> +--> +<a name="20051108.1"> +<h3>8 November - JK-1.2.15 released</h3> +</a> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Jakarta Tomcat Connectors 1.2.15. This is Stable release and it contains +few bug fixes found in 1.2.14 version. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> + +<a name="20050713.1"> +<h3>13 July - JK-1.2.14 released</h3> +</a> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Jakarta Tomcat Connectors 1.2.14. This is Stable release and it contains +few bug fixes found in 1.2.13 version. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> +<a name="20050516.1"> +<h3>7 May - JK-1.2.13 released</h3> +</a> +<p>The Apache Jakarta Tomcat team is proud to announce the immediate availability +of Jakarta Tomcat Connectors 1.2.13. This is development release and contains +few bug fixes found in 1.2.12 version. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> +<a name="20050507.1"> +<h3>7 May - JK-1.2.12 released</h3> +</a> +<p>The Apache Jakarta Tomcat team is proud to announce the immediate availability +of Jakarta Tomcat Connectors 1.2.12 The release contains a significant number +of bug fixes and new features. +</p> +<p> +We expect it to be ratified as a Stable release when the vote takes place +in the next week. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> +<a name="20050429.1"> +<h3>29 April - JK-1.2.11 released</h3> +</a> +<p>The Apache Jakarta Tomcat team is proud to announce the immediate availability +of Jakarta Tomcat Connectors 1.2.11 The release contains a significant number +of bug fixes and new features. +</p> +<p> +This version has not been released. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> +<a name="20050330.1"> +<h3>30 March - JK-1.2.10 released</h3> +</a> +<p>The Apache Jakarta Tomcat team is proud to announce the immediate availability +of Jakarta Tomcat Connectors 1.2.10 The release contains a significant number +of bug fixes and new features. +</p> +<p> +We expect it to be ratified as a Stable release when the vote takes place +in the next two weeks. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<warn> +Since release 1.2.10 the <b>JkShmFile</b> property has been added for +Apache 1.3.x and Apache 2.x web servers on UNIX and LINUX platforms. +Load balancer will not work properly if this directive is not present. +</warn> +<p>If you find any bugs while using this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> +<a name="20050318.1"> +<h3>18 March - JK-1.2.9-beta released</h3> +</a> +<p>The Apache Jakarta Tomcat team is proud to announce the immediate availability +of Jakarta Tomcat Connectors 1.2.9-beta. The release contains a significant number +of bug fixes and new features. +</p> +<p> +We expect it to be ratified as a Stable release when the vote takes place +in the next two weeks. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<warn> +Since release 1.2.9 the <b>JkShmFile</b> property has been added for +Apache 1.3.x and Apache 2.x web servers on UNIX and LINUX platforms. +Load balancer will not work properly if this directive is not present. +</warn> +<p>If you find any bugs during testing this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> + +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20060101.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20060101.xml new file mode 100644 index 00000000..e7f54076 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20060101.xml @@ -0,0 +1,110 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="20060101.html"> + + &project; + + <properties> + <author email="general.AT.tomcat.DOT.apache.DOT.org">Apache Tomcat Connectors Project</author> + <title>2006 News and Status</title> + </properties> + +<body> + +<section name="2006 News & Status"> +<br /> +<a name="20061210.1"> +<h3>10 December - JK-1.2.20 released</h3> +</a> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.20. This is a stable release adding new features +and a few bug fixes to version 1.2.19. +Furthermore the documentation has been reorganised. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> + +<a name="20060917.1"> +<h3>17 September - JK-1.2.19 released</h3> +</a> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.19. This is a stable release adding some features +and a few bug fixes to version 1.2.18. +Furthermore the non-functional code trees for isapi and domino have been removed. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> + +<a name="20060720.1"> +<h3>13 July - JK-1.2.18 released</h3> +</a> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.18. This is a stable release adding +a few bug fixes to the not released 1.2.17 version. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> + +<a name="20060708.1"> +<h3>JK-1.2.17 not released</h3> +</a> +<p>Version 1.2.17 of Tomcat Connectors 1.2.17 has not been released +due to a bug in the types chosen for socket arguments. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<hr size="1" noshade="noshade" /> + +<a name="20060606.1"> +<h3>JK-1.2.16 not released</h3> +</a> +<p>Version 1.2.16 of Tomcat Connectors 1.2.16 has not been released +due to a bug in the jk status worker. This version adds some features +and a few bug fixes to the 1.2.15 version. Furthermore some worker attributes +have been <a href="../reference/workers.html">deprecated</a>. +</p> +<p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<hr size="1" noshade="noshade" /> + +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20070301.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20070301.xml new file mode 100644 index 00000000..9083b018 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20070301.xml @@ -0,0 +1,117 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="20070301.html"> + + &project; + + <properties> + <author email="general.AT.tomcat.DOT.apache.DOT.org">Apache Tomcat Connectors Project</author> + <title>2007 News and Status</title> + </properties> + +<body> + +<section name="2007 News & Status"> +<br /> +<a name="20071221.1"> +<h3>21 December - JK-1.2.26 released</h3> +</a> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.26. This is a stable release adding few new features +and some bug fixes. +</p><p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%206">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> +<a name="20070807.1"> +<h3>7 August - JK-1.2.25 released</h3> +</a> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.25. This is a stable release adding new features +and a few bug fixes. +</p><p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%206">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> +<a name="20070727.1"> +<h3>27 July - JK-1.2.24 released</h3> +</a> +<p><b>This release has been withdrawn.</b> +</p> +<hr size="1" noshade="noshade" /> +<a name="20070518.1"> +<h3>18 May - JK-1.2.23 released</h3> +</a> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.23. This is a stable release adding new features +and a few bug fixes to version 1.2.23. +</p><p> +It fixes an <a href="http://tomcat.apache.org/security-jk.html">Important vulnerability</a>. +</p><p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> +<a name="20070417.1"> +<h3>17 April - JK-1.2.22 released</h3> +</a> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.22. This is a stable release adding new features +and a few bug fixes to version 1.2.22. +</p><p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> +<a name="20070301.1"> +<h3>1 March - JK-1.2.21 released</h3> +</a> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.21. This is a stable release adding new features +and a few bug fixes to version 1.2.20. +</p><p> +It fixes a <a href="http://tomcat.apache.org/security-jk.html">Critical vulnerability</a> introduced in version 1.2.19 +</p><p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="http://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%205">Bugzilla</a> +Bug Report. When entering bug select <b>Native:JK</b> Component. +</p> +<hr size="1" noshade="noshade" /> + +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20081001.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20081001.xml new file mode 100644 index 00000000..f622abf4 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20081001.xml @@ -0,0 +1,188 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="20081001.html"> + + &project; + + <properties> + <author email="dev.AT.tomcat.DOT.apache.DOT.org">Apache Tomcat Connectors Project</author> + <title>2008 News and Status</title> + </properties> + +<body> + +<section name="2008 News & Status"> +<br /> +<subsection name="28 October - JK-1.2.27 released"> +<a name="20081028.1"></a> +<br /> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.27. This is a stable release adding lots of new features +and some bug fixes. +</p><p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="https://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%20Connectors">Bugzilla</a> +Bug Report. +</p> +<p> +The most important new features in this version are: +</p> +<h3>Watchdog Thread for Periodic Tasks</h3> +<p> +The connector has to run some periodic tasks independant of +request processing. Examples are probing or closing down idle backend +connections, adjusting load numbers and recovering workers from error state. +</p> +<p> +Before version 1.2.27 these tasks were done inside the request processing loop. +When a new request came in and the task was due, the thread handling the +request first executed the internal task and then handled the request. +If there were no requests coming in, the tasks would not run. If any of +the tasks took unexpectedly long, the response time of the request waiting +for the finishing of the task went up. +</p> +<p> +Starting with this release you can configure a separate watchdog thread inside +the web server to run all those tasks independantly of request processing. +This new feature is avaliable for the connector when used with Apache httpd 2.x +or with Microsoft IIS. To keep the behaviour of the new version consistent +with previous releases, this feature is turned off by default. +You can activate the watchdog thread via +<a href="../reference/apache.html"><code>JkWatchdogInterval</code></a> +for Apache or +<a href="../reference/iis.html"><code>watchdog_interval</code></a> +for IIS. +</p> +<h3>Connection Probing</h3> +<p> +In previous releases connection probing (checking whether connections still work) +could only be done immediately after a new connection was established and +directly before sending each request. Since we now have the watchdog +thread available, we also added a periodic probing option, which you +can activate with the worker attribute +<a href="../reference/workers.html"><code>ping_mode</code></a>. +This will also be useful as a protection against the infamous firewall +idle connection drop. +</p> +<p> +The older attributes <code>connect_timeout</code> and <code>prepost_timeout</code> +still exist and work the same way they did in previous releases. +Since there are now three different probing options, we recommend to migrate +your configuration to the newer attributes <code>ping_mode</code>, +<code>ping_timeout</code> and <code>connection_ping_interval</code>. +</p> +<h3>Mount Extensions</h3> +<p> +Usually one defines workers and mounts for the connector. +A worker defines a backend we want to talk to and the configuration parameters of the +communication, connection pools etc. The mounts define which URIs we want to forward to +which worker (so we also call a mount an URI map rule). +In version 1.2.27 you can overwrite certain worker parameter per mount. +</p> +<p> +One easy to understand example is reply timeouts. Until this release you had to specify +a reply timeout for the whole worker. But reply times depend a lot on the type of +request. So normally you want to define a general reply timeout and +for some special URLs you need to relax the reply timeout, because you know those +URLs take much longer to process (like e.g. reporting or other compute intensive tasks). +</p> +<p> +Another possible case is the activation status. You might use a load balancer worker to +forward requests to certain webapps in a farm of Tomcat nodes. If you wanted +to update some webapp on one node, you previously had to stop forwarding requests for +all webapps on this Tomcat node. What was not possible until now, was stopping forwarding +requests restricted to the webapp and the node you wanted to update. +</p> +<p> +Starting with this release, you can add so-called +<a href="../reference/uriworkermap.html#Rule extensions">rule extensions</a> +to your uriworkermap file to influence worker parameters per mount. This will +work for all Apache versions and for IIS. Remember, that +the uriworkermap file automatically gets reloaded after changes without web server +restart. +</p> +<h3>Improved IIS support</h3> +<p> +We improved IIS support im various ways. It is now possible to use +multiple IIS 6 application pools with the ISAPI redirector. +</p> +<p> +Furthermore some improvements were added as compile time features. +The most notable one is chunked encoding support, which was a major +refactoring and is therefore still considered experimental. You can +download binaries with and without chunked encoding support. In future +versions, chunked encoding will likely be availabe in all builds. +</p> +<p> +Another new feature is an elegant way of configuring error page redirects. +All new features are documented on the documentation page about +<a href="../reference/iis.html">configuring IIS</a>. +</p> +<h3>Enhanced Status Worker</h3> +<p> +The +<a href="../reference/status.html">status worker</a> +now can also manage and show statistics for AJP workers that +are not part of a load balancer. Other improvements are the new <code>dump</code> +action, the integration of the new configuration attributes, showing average +request and transfer rates since the last statistics reset and the ability to +display only a single member of a load balancer. +</p> +<p> +Unfortunately we had to change +<a href="../reference/status.html#Data Parameters for the standard Update Action">some request parameters</a> +used for the <code>update</code> action of the status worker. +</p> +<h3>Miscellaneous Improvements</h3> +<p> +Further enhancements are: +<ul> +<li> +Configurable session stickyness indicator: cookie name and URL path +parameter name can be freely chosen instead of the servlet spec compliant +<code>JSESSIONID</code> and <code>;jsessionid</code>. +</li> +<li> +Automatically determining the size of the shared memory segment needed +to accommodate all workers. +</li> +<li> +New connection establishment timeout <code>socket_connect_timeout</code>. +</li> +<li> +New timeout <code>connection_acquire_timeout</code> for acquiring a free connection from +the pool. +</li> +<li> +Improved retry handling by adjusting the meaning of the attribute <code>retries</code> for +AJP workers and for load balancers and by adding the new <code>retry_interval</code>. +</li> +<li> +Allowing the web server to provide error pages instead of Tomcat. +</li> +</ul> +</p> +</subsection> +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20090301.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20090301.xml new file mode 100644 index 00000000..93efc664 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20090301.xml @@ -0,0 +1,93 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="20090301.html"> + + &project; + + <properties> + <author email="dev.AT.tomcat.DOT.apache.DOT.org">Apache Tomcat Connectors Project</author> + <title>2009 News and Status</title> + </properties> + +<body> + +<section name="2009 News & Status"> +<br /> +<subsection name="22 March - JK-1.2.28 released"> +<a name="20090322.1"></a> +<br /> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.28. This is a stable release concentrating mainly on +some bug fixes. +</p><p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="https://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%20Connectors">Bugzilla</a> +Bug Report. +</p> +<p> +The most important new features in this version are: +</p> +<h3>Better Error Detection for Load Balancer Workers</h3> +<p> +Local and global error states have been improved. You can fine tune the +behaviour with the new "error_escalation_time" attribute +(see the <a href="../generic_howto/timeouts.html">timeouts documentation</a>). +</p> +<h3>Dynamic Address and Port Change Using the Status Worker</h3> +<p> +The status worker now allows you to change the address and the port +of an AJP13 worker on the fly. You can e.g. provision dummy workers with a port +equal to "0", which will be automatically put into stopped mode during startup. +Later, when you want to actually use thse workers, you set their address and +port to the final values. +</p> +<p> +Note that already existing connections will go on using the old +address and port. This will be improved in future versions. +</p> +<h3>New Data in Status Worker Display</h3> +<p> +The status worker display now also contains the timestamp of the last +worker errors. +</p> +<h3>Improved Proxy Flexibility</h3> +<p> +You can now overwrite more request metadata before the request gets send to the backend. +This is helpful in case there are other reverse proxies in front of your web server. +A new <a href="../generic_howto/proxy.html">documentation page</a> explains this in detail. +</p> +<h3>Improved IIS Support</h3> +<p> +IIS support has been improved especially when using mutltiple application pools. +Furthermore you can now configure the ISAPI plugin to update the uriworkermap.properies +file on a regular interval using the watchdog thread. +</p> +<h3>JNI Worker Deprecation</h3> +<p> +Workers of type jni are broken since a long time. Since there is no more +use for them, they have been deprecated now, and will be removed in a future release. +</p> +</subsection> +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20100101.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20100101.xml new file mode 100644 index 00000000..3d2f92e5 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20100101.xml @@ -0,0 +1,93 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="20100101.html"> + + &project; + + <properties> + <author email="dev.AT.tomcat.DOT.apache.DOT.org">Apache Tomcat Connectors Project</author> + <title>2010 News and Status</title> + </properties> + +<body> + +<section name="2010 News & Status"> +<br /> +<subsection name="1 November - JK-1.2.31 released"> + <a name="20101101.1"></a> + <br /> + <p>The Apache Tomcat team is proud to announce the immediate availability + of Tomcat Connectors 1.2.31. This is a stable release concentrating mainly on + some bug fixes. + </p><p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. + </p> + <p>If you find any bugs while using this release, please fill in the + <a href="https://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%20Connectors">Bugzilla</a> + Bug Report. + </p> +</subsection> + +<br /> +<subsection name="1 March - JK-1.2.30 released"> +<a name="20100301.1"></a> +<br /> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.30. This is a stable release concentrating mainly on +some bug fixes. +</p><p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="https://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%20Connectors">Bugzilla</a> +Bug Report. +</p> +</subsection> + +<br /> +<subsection name="1 March - JK-1.2.29 withdrawn"> +<a name="20100301.2"></a> +<br /> +<p>Tomcat Connectors 1.2.29 has been withdrawn because of regression inside +Microsoft IIS connector. +</p> +</subsection> + +<br /> +<subsection name="26 February - JK-1.2.29 released"> +<a name="20100226.3"></a> +<br /> +<p>The Apache Tomcat team is proud to announce the immediate availability +of Tomcat Connectors 1.2.29. This is a stable release concentrating mainly on +some bug fixes. +</p><p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. +</p> +<p>If you find any bugs while using this release, please fill in the +<a href="https://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%20Connectors">Bugzilla</a> +Bug Report. +</p> + +</subsection> +</section> +</body> +</document> + diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20110701.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20110701.xml new file mode 100644 index 00000000..deee9eec --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/20110701.xml @@ -0,0 +1,53 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="20110701.html"> + + &project; + + <properties> + <author email="dev.AT.tomcat.DOT.apache.DOT.org">Apache Tomcat Connectors Project</author> + <title>2011 News and Status</title> + </properties> + +<body> + +<section name="2011 News & Status"> +<br /> + +<subsection name="8 July - JK-1.2.32 released"> + <a name="20110701.1"></a> + <br /> + <p>The Apache Tomcat team is proud to announce the immediate availability + of Tomcat Connectors 1.2.32. This is a stable release concentrating mainly on + some bug fixes. + </p><p> + Please see the <a href="../miscellaneous/changelog.html">ChangeLog</a> for a full list of changes. + </p> + <p>If you find any bugs while using this release, please fill in the + <a href="https://issues.apache.org/bugzilla/enter_bug.cgi?product=Tomcat%20Connectors">Bugzilla</a> + Bug Report. + </p> +</subsection> + +</section> +</body> +</document> + diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/project.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/project.xml new file mode 100644 index 00000000..ca53a6c2 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/news/project.xml @@ -0,0 +1,81 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<project name="Apache Tomcat Connector Documentation - News" + href="http://tomcat.apache.org/"> + + <title>The Apache Tomcat Connector - News</title> + + <logo href="/images/tomcat.gif"> + The Apache Tomcat Connector - News + </logo> +<body> + + <menu name="Links"> + <item name="Docs Home" href="../index.html"/> + </menu> + + <menu name="Reference Guide"> + <item name="workers.properties" href="../reference/workers.html"/> + <item name="uriworkermap.properties" href="../reference/uriworkermap.html"/> + <item name="Status Worker" href="../reference/status.html"/> + <item name="Apache HTTP Server" href="../reference/apache.html"/> + <item name="IIS" href="../reference/iis.html"/> + </menu> + + <menu name="Generic HowTo"> + <item name="For the impatient" href="../generic_howto/quick.html"/> + <item name="All about workers" href="../generic_howto/workers.html"/> + <item name="Timeouts" href="../generic_howto/timeouts.html"/> + <item name="Load Balancing" href="../generic_howto/loadbalancers.html"/> + <item name="Reverse Proxy" href="../generic_howto/proxy.html"/> + </menu> + + <menu name="Webserver HowTo"> + <item name="Apache HTTP Server" href="../webserver_howto/apache.html"/> + <item name="IIS" href="../webserver_howto/iis.html"/> + <item name="Netscape/SunOne/Sun" href="../webserver_howto/nes.html"/> + </menu> + + <menu name="AJP Protocol Reference"> + <item name="AJPv13" href="../ajp/ajpv13a.html"/> + <item name="AJPv13 Extension Proposal" href="../ajp/ajpv13ext.html"/> + </menu> + + <menu name="Miscellaneous Documentation"> + <item name="Frequently asked questions" href="../miscellaneous/faq.html"/> + <item name="Changelog" href="../miscellaneous/changelog.html"/> + <item name="Current Tomcat Connectors bugs" href="http://issues.apache.org/bugzilla/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Tomcat+Connectors&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0="/> + <item name="Contribute documentation" href="../miscellaneous/doccontrib.html"/> + <item name="JK Status Ant Tasks" href="../miscellaneous/jkstatustasks.html"/> + <item name="Reporting Tools" href="../miscellaneous/reporttools.html"/> + <item name="Old JK/JK2 documentation" href="http://tomcat.apache.org/connectors-doc-archive/jk2/index.html"/> + </menu> + + <menu name="News"> + <item name="2011" href="../news/20110701.html"/> + <item name="2010" href="../news/20100101.html"/> + <item name="2009" href="../news/20090301.html"/> + <item name="2008" href="../news/20081001.html"/> + <item name="2007" href="../news/20070301.html"/> + <item name="2006" href="../news/20060101.html"/> + <item name="2005" href="../news/20050101.html"/> + <item name="2004" href="../news/20041100.html"/> + </menu> + +</body> +</project> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/project.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/project.xml new file mode 100644 index 00000000..0b0bc3a4 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/project.xml @@ -0,0 +1,81 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<project name="Apache Tomcat Connector Documentation" + href="http://tomcat.apache.org/"> + + <title>The Apache Tomcat Connector</title> + + <logo href="/images/tomcat.gif"> + The Apache Tomcat Connector + </logo> +<body> + + <menu name="Links"> + <item name="Docs Home" href="index.html"/> + </menu> + + <menu name="Reference Guide"> + <item name="workers.properties" href="reference/workers.html"/> + <item name="uriworkermap.properties" href="reference/uriworkermap.html"/> + <item name="Status Worker" href="reference/status.html"/> + <item name="Apache HTTP Server" href="reference/apache.html"/> + <item name="IIS" href="reference/iis.html"/> + </menu> + + <menu name="Generic HowTo"> + <item name="For the impatient" href="generic_howto/quick.html"/> + <item name="All about workers" href="generic_howto/workers.html"/> + <item name="Timeouts" href="generic_howto/timeouts.html"/> + <item name="Load Balancing" href="generic_howto/loadbalancers.html"/> + <item name="Reverse Proxy" href="generic_howto/proxy.html"/> + </menu> + + <menu name="Webserver HowTo"> + <item name="Apache HTTP Server" href="webserver_howto/apache.html"/> + <item name="IIS" href="webserver_howto/iis.html"/> + <item name="Netscape/SunOne/Sun" href="webserver_howto/nes.html"/> + </menu> + + <menu name="AJP Protocol Reference"> + <item name="AJPv13" href="ajp/ajpv13a.html"/> + <item name="AJPv13 Extension Proposal" href="ajp/ajpv13ext.html"/> + </menu> + + <menu name="Miscellaneous Documentation"> + <item name="Frequently asked questions" href="miscellaneous/faq.html"/> + <item name="Changelog" href="miscellaneous/changelog.html"/> + <item name="Current Tomcat Connectors bugs" href="http://issues.apache.org/bugzilla/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Tomcat+Connectors&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0="/> + <item name="Contribute documentation" href="miscellaneous/doccontrib.html"/> + <item name="JK Status Ant Tasks" href="miscellaneous/jkstatustasks.html"/> + <item name="Reporting Tools" href="miscellaneous/reporttools.html"/> + <item name="Old JK/JK2 documentation" href="http://tomcat.apache.org/connectors-doc-archive/jk2/index.html"/> + </menu> + + <menu name="News"> + <item name="2011" href="news/20110701.html"/> + <item name="2010" href="news/20100101.html"/> + <item name="2009" href="news/20090301.html"/> + <item name="2008" href="news/20081001.html"/> + <item name="2007" href="news/20070301.html"/> + <item name="2006" href="news/20060101.html"/> + <item name="2005" href="news/20050101.html"/> + <item name="2004" href="news/20041100.html"/> + </menu> + +</body> +</project> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/apache.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/apache.xml new file mode 100644 index 00000000..e4ad0360 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/apache.xml @@ -0,0 +1,1119 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="apache.html"> + + &project; + + <properties> + <author email="mturk@apache.org">Mladen Turk</author> + <title>Configuring Apache</title> + </properties> + +<body> + +<section name="Configuration Directives"> +<p> +Most of the directives are allowed once in the global part of the Apache httpd +configuration and once in every <VirtualHost> elements. Exceptions from this rule are +explicitly listed in the table below. +</p> +<p> +Most values are inherited from the main server to the virtual hosts. +Since version 1.2.20 they can be overwritten in the virtual hosts. +Exceptions from this rule are again explicitly listed in the table below. +See especially JkMountCopy. +</p> +<warn> +Warning: If Apache httpd and Tomcat are configured to serve content from +the same filing system location then care must be taken to ensure that httpd is +not able to serve inappropriate content such as the contents of the WEB-INF +directory or JSP source code. +</warn> +<p> +This could occur if the httpd DocumentRoot +overlaps with a Tomcat Host's appBase or the docBase of any Context. It could +also occur when using the httpd Alias directive with a Tomcat Host's appBase or +the docBase of any Context. +</p> +<p> +Here are the all directives supported by Apache: +</p> +<attributes name="Directive"> +<attribute name="JkWorkersFile" required="false"><p> +The name of a worker file for the Tomcat servlet containers. +<br/> +This directive is only allowed once. It must be put into +the global part of the configuration. +<br/> +If you don't use the JkWorkerProperty directives, then you must +define your workers with a valid JkWorkersFile. There is no default +value. +</p></attribute> +<attribute name="JkWorkerProperty" required="false"><p> +Enables setting worker properties inside Apache configuration file. +The syntax is the same as in the JkWorkersFile (usually workers.properties). +Simply prefix each line with "JkWorkerProperty" to put it directly into +the Apache httpd config files. +<br/> +This directive is allowed multiple times. +It must be put into the global part of the configuration. +<br/> +If you don't use the JkWorkerProperty directives, then you must +define your workers with a valid JkWorkersFile. There is no default +value. +<br/> +This directive is available in jk1.2.7 version and later. +</p></attribute> +<attribute name="JkShmFile" required="false"><p> +Shared memory file name. Used only on unix platforms. +The shm file is used by balancer and status workers. +<br/> +This directive is only allowed once. It must be put into +the global part of the configuration. +<br/> +The default value is logs/jk-runtime-status. +It is highly recommended that the shm file be placed on a local +drive and not an NFS share. +</p> +<p> +The shared memory contains configuration and runtime information for load balancer +workers and their members. It is need in order that all apache children +<ul> +<li>share the same status information for load balancing members (OK, ERROR, ...),</li> +<li>share the information about load taken by the individual workers,</li> +<li>share the information for the parts of the configuration, which are changeable +during runtime by status workers.</li> +</ul> +</p> +</attribute> +<attribute name="JkShmSize" required="false"><p> +Size of the shared memory file name. +<br/> +This directive is only allowed once. It must be put into +the global part of the configuration. +<br/> +The default value depends on the platform. It is usually less than 64KB. +</p></attribute> +<p>Starting with version 1.2.27 the size of the shared memory is determined +automatically, even for large numbers of workers. This attribute is not +needed any longer.</p> +<attribute name="JkMountFile" required="false"><p> +File containing multiple mappings from a context to a Tomcat worker. +It is usually called uriworkermap.properties. +<br/> +For inheritance rules, see: JkMountCopy. +<br/> +There is no default value. +</p></attribute> +<attribute name="JkMountFileReload" required="false"><p> +This directive configures the reload check interval in seconds. +The JkMountFile is checked periodically for changes. +A changed file gets reloaded automatically. If you set +this directive to "0", reload checking is turned off. +<br/> +The default value is 60 seconds. +<br/> +This directive has been added in version 1.2.20 of mod_jk. +</p></attribute> +<attribute name="JkMount" required="false"><p> +A mount point from a context to a Tomcat worker. +<br/> +This directive is allowed multiple times. +It is allowed in the global configuration and in VirtualHost. +You can also use it inside Location with a different syntax. +Inside Location, one omits the first argument (path), +which gets inherited from the Location. +<br/> +By default JkMount entries are not inherited from the global +server to other VirtualHosts or between VirtualHosts. +For the complete inheritance rules, see: JkMountCopy. +</p></attribute> +<attribute name="JkUnMount" required="false"><p> +An exclusion mount point from a context to a Tomcat worker. +All exclusion mounts are checked after mapping a request +to a tomcat worker. If the request maps also to an exclusion, +it will not be forwarded to tomcat, and instead be served locally. +<br/> +This directive is allowed multiple times. +It is allowed in the global configuration and in VirtualHost. +You can also use it inside Location with a different syntax. +Inside Location, one omits the first argument (path), +which gets inherited from the Location. +For inheritance rules, see: JkMountCopy. +<br/> +This directive is available in jk1.2.7 version and later. +</p></attribute> +<attribute name="JkAutoAlias" required="false"><p> +Automatically Alias webapp context directories into the Apache +document space. +<br/> +Care should be taken to ensure that only static content is served via httpd as a +result of using this directive. Any static content served by httpd will bypass any +security constraints defined in the application's web.xml. +<br/> +For inheritance rules, see: JkMountCopy. +<br/> +There is no default value. +</p></attribute> +<attribute name="JkMountCopy" required="false"><p> +If this directive is set to "On" in some virtual server, +the mounts from the global server will be copied to this +virtual server, more precisely all mounts defined by JkMount +or JkUnMount. The Mounts defined by JkMountFile and JkAutoAlias +will only be inherited, if the VirtualHost does not define +it's own JkMountFile or JkAutoAlias. +<br/> +If you want all vhost to inherit mounts from the main server, +you can set JkMountCopy to 'All' in the main server. +<br/> +This directive is only allowed inside VirtualHost (with value "On") +and in the global server (with value "All"). +<br/> +The default is Off, so no mounts will be inherited from the global +server to any VirtualHost. +<br/> +Starting with version 1.2.26 you can also set it to "All" in the +global virtual server. This will switch the default to On. +</p></attribute> +<attribute name="JkWorkerIndicator" required="false"><p> +Name of the Apache environment variable that can be used to set worker names +in combination with SetHandler jakarta-servlet. +<br/> +This directive is only allowed once per virtual server. +It is allowed in the global configuration and in VirtualHost. +<br/> +The default value is JK_WORKER_NAME. +</p></attribute> +<attribute name="JkWatchdogInterval" required="false"><p> +This directive configures the watchdog thread interval in seconds. +The workers are maintained periodically by a background thread +running periodically every watchdog_interval seconds. Worker maintenance +checks for idle connections, corrects load status and is able +to detect backend health status. +<br/> +The maintenance only happens, if since the last maintenance at +least <a href="workers.html"><code>worker.maintain</code></a> +seconds have passed. So setting the JkWatchdogInterval +much smaller than <code>worker.maintain</code> is not useful. +<br/> +The default value is 0 seconds, meaning the watchdog thread +will not be created, and the maintenance is done in combination +with normal requests instead. +<br/> +This directive is only allowed once. It must be put into +the global part of the configuration. +<br/> +This directive has been added in version 1.2.27 of mod_jk. +It is available only for httpd 2.x and above using APR libraries +including thread support. +</p></attribute> +<attribute name="JkLogFile" required="false"><p> +Full or server relative path to the Tomcat Connector module log file. +It will also work with pipe, by using a value of the form "| ...". +<br/> +The default value is logs/mod_jk.log. +<br/> +Pipes are supported for Apache 1.3 only since version 1.2.16. +The default value exists only since version 1.2.20. +</p></attribute> +<attribute name="JkLogLevel" required="false"><p> +The Tomcat Connector module log level, can be debug, info, warn +error or trace. +<br/> +The default value is info. +</p></attribute> +<attribute name="JkLogStampFormat" required="false"><p> +The Tomcat Connector module <b>date</b> log format, using an +extended strftime syntax. +This format will be used for the time stamps in the JkLogFile. +The maximum length of the format is 63 characters. +<br/> +Starting with version 1.2.24 of mod_jk you can also use %Q +for adding milliseconds to the log and %q for microseconds. +These conversion specifiers are an extension to strftime. +They will only work on platforms with a gettimeofday() function. +You can use %Q and %q only once in the pattern and also not both +together in the same pattern. +<br/> +The default value is "[%a %b %d %H:%M:%S %Y] " and beginning +with version 1.2.24 on platforms with a gettimeofday() +function it is "[%a %b %d %H:%M:%S.%Q %Y] ". +</p></attribute> +<attribute name="JkRequestLogFormat" required="false"><p> +Request log format string. See detailed description below. +<br/> +There is no default value. Without defining a value, the request logging +is turned off. +</p></attribute> +<attribute name="JkExtractSSL" required="false"><p> +Turns on SSL processing and information gathering by mod_jk +<br/> +The default value is On. +<br/> +In order to make SSL data available for mod_jk in Apache, you need to +set <code>SSLOptions +StdEnvVars</code>. For the certificate information you also need +to add <code>SSLOptions +ExportCertData</code>. +</p> +<p> + Specifically, mod_jk will export the following environment variables from + Apache httpd to Tomcat under these request attributes as per the + Servlet Specification 3.0, section 3.8: +</p> +<table> + <tr><th>Env Var</th><th>Request Attribute Name</th><th>Type</th><th>Example</th></tr> + <tr> + <td>SSL_CIPHER<br/>(or <code>JkKEYSIZEIndicator</code>)</td> + <td>javax.servlet.request.cipher_suite</td> + <td>java.lang.String</td> + <td>DHE-RSA-AES256-SHA</td> + </tr> + <tr> + <td>SSL_CIPHER_USEKEYSIZE<br/>(or <code>JkKEYSIZEIndicator</code>)</td> + <td>javax.servlet.request.key_size</td> + <td>java.lang.Integer</td> + <td>256</td> + </tr> + <tr> + <td>SSL_SESSION_ID<br/>(or <code>JkSESSIONIndicator</code>)</td> + <td>javax.servlet.request.ssl_session</td> + <td>java.lang.String</td> + <td>905...32E (a hex string)</td> + </tr> + <tr> + <td>SSL_CLIENT_CERT_CHAIN_<i>n</i><br/>(or <code>JkCERTCHAINPrefix</code><i>n</i>)</td> + <td>javax.servlet.request.X509Certificate</td> + <td>java.security.X509Certificate[]</td> + <td>(A chain of certs in ascending order of trust, the first one being + ths client's certificate, the second being the signer of that + certificate, and so on)</td> + </tr> +</table> +<p> + For all other SSL-related variables, use <code>JkEnvVar</code> for each + variable you want. Please note that, like <code>JkEnvVar</code>, these + variables are available from the request <i><b>attributes</b></i>, not as + environment variables or as request headers. +</p> +</attribute> +<attribute name="JkHTTPSIndicator" required="false"><p> +Name of the Apache environment variable that contains SSL indication. +<br/> +The default value is "HTTPS". +</p></attribute> +<attribute name="JkCERTSIndicator" required="false"><p> +Name of the Apache environment variable that contains SSL client certificates. +<br/> +The default value is "SSL_CLIENT_CERT". +</p></attribute> +<attribute name="JkCIPHERIndicator" required="false"><p> +Name of the Apache environment variable that contains SSL client cipher. +<br/> +The default value is "SSL_CIPHER". +</p></attribute> +<attribute name="JkCERTCHAINPrefix" required="false"><p> +Name of the Apache environment (prefix) that contains SSL client chain certificates. +<br/> +The default value is "SSL_CLIENT_CERT_CHAIN_". +</p></attribute> +<attribute name="JkSESSIONIndicator" required="false"><p> +Name of the Apache environment variable that contains SSL session. +<br/> +The default value is "SSL_SESSION_ID". +</p></attribute> +<attribute name="JkKEYSIZEIndicator" required="false"><p> +Name of the Apache environment variable that contains SSL key size in use. +<br/> +The default value is "SSL_CIPHER_USEKEYSIZE". +</p></attribute> +<attribute name="JkLocalNameIndicator" required="false"><p> +Name of the Apache environment variable which can be used to overwrite +the forwarded local name. +Use this only if you need to adjust the data (see the +<a href="../generic_howto/proxy.html">proxy</a> documentation). +<br/> +The default value is "JK_LOCAL_NAME". +<br/> +This directive has been added in version 1.2.28 of mod_jk. +</p></attribute> +<attribute name="JkLocalPortIndicator" required="false"><p> +Name of the Apache environment variable which can be used to overwrite +the forwarded local port. +Use this only if you need to adjust the data (see the +<a href="../generic_howto/proxy.html">proxy</a> documentation). +<br/> +The default value is "JK_LOCAL_PORT". +<br/> +This directive has been added in version 1.2.28 of mod_jk. +</p></attribute> +<attribute name="JkRemoteHostIndicator" required="false"><p> +Name of the Apache environment variable which can be used to overwrite +the forwarded remote (client) host name. +Use this only if you need to adjust the data (see the +<a href="../generic_howto/proxy.html">proxy</a> documentation). +<br/> +The default value is "JK_REMOTE_HOST". +<br/> +This directive has been added in version 1.2.28 of mod_jk. +</p></attribute> +<attribute name="JkRemoteAddrIndicator" required="false"><p> +Name of the Apache environment variable which can be used to overwrite +the forwarded remote (client) IP address. +Use this only if you need to adjust the data (see the +<a href="../generic_howto/proxy.html">proxy</a> documentation). +<br/> +The default value is "JK_REMOTE_ADDR". +<br/> +This directive has been added in version 1.2.28 of mod_jk. +</p></attribute> +<attribute name="JkRemotePortIndicator" required="false"><p> +Name of the Apache environment variable which can be used to overwrite +the forwarded remote (client) IP address. +Use this only if you need to adjust the data (see the +<a href="../generic_howto/proxy.html">proxy</a> documentation). +<br/> +The default value is "JK_REMOTE_PORT". +<br/> +This directive has been added in version 1.2.32 of mod_jk. +</p></attribute> +<attribute name="JkRemoteUserIndicator" required="false"><p> +Name of the Apache environment variable which can be used to overwrite +the forwarded user name. +Use this only if you need to adjust the data (see the +<a href="../generic_howto/proxy.html">proxy</a> documentation). +<br/> +The default value is "JK_REMOTE_USER". +<br/> +This directive has been added in version 1.2.28 of mod_jk. +</p></attribute> +<attribute name="JkAuthTypeIndicator" required="false"><p> +Name of the Apache environment variable which can be used to overwrite +the forwarded authentication type. +Use this only if you need to adjust the data (see the +<a href="../generic_howto/proxy.html">proxy</a> documentation). +<br/> +The default value is "JK_AUTH_TYPE". +<br/> +This directive has been added in version 1.2.28 of mod_jk. +</p></attribute> +<attribute name="JkOptions" required="false"><p> +Set one of more options to configure the mod_jk module. See below for +details about this directive. +<br/> +This directive can be used multiple times per virtual server. +<br/> +The default value is "ForwardURIProxy" since version 1.2.24. +It was "ForwardURICompatUnparsed" in version 1.2.23 and +"ForwardURICompat" until version 1.2.22. +</p></attribute> +<attribute name="JkEnvVar" required="false"><p> +Adds a name and an optional default value of environment variable +that should be sent to servlet-engine as a request attribute. +If the default value is not given explicitly, the variable +will only be send, if it is set during runtime. +<br/> +The default is empty, so no additional variables will be sent. +<br/> +This directive can be used multiple times per virtual server. +The settings will be merged between the global server and any +virtual server. +<br/> +You can retrieve the variables on Tomcat as request attributes +via request.getAttribute(attributeName). Note that the variables +send via JkEnvVar will not be listed in request.getAttributeNames(). +<br/> +Empty default values are supported since version 1.2.20. +Not sending variables with empty defaults and empty runtime value +has been introduced in version 1.2.21. +</p></attribute> +<attribute name="JkStripSession" required="false"><p> +If this directive is set to On in some virtual server, +the session IDs <code>;jsessionid=...</code> will be +removed for non matched URLs. +<br/> +This directive is only allowed inside VirtualHost. +<br/> +The default is Off. +<br/> +This directive has been introduced in version 1.2.21. +<br/>With version 1.2.27 and later this directive can have optional +session ID identifier. If not specified it defaults to +<code>;jsessionid</code>. +</p> +</attribute> + +</attributes> +</section> + +<section name="Configuration Directives Types"> +<p> +We'll discuss here the mod_jk directive types. +</p> + +<subsection name="Define workers"> +<p> +<b>JkWorkersFile</b> specify the location where mod_jk will find the workers definitions. +Take a look at <a href="workers.html">Workers documentation</a> for detailed description. + +<source> + JkWorkersFile /etc/httpd/conf/workers.properties +</source> + +<br/> +<br/> +</p> + +</subsection> + +<subsection name="Logging"> +<p> +<b>JkLogFile</b> specify the location where mod_jk is going to place its log file. +</p> + +<source> + JkLogFile /var/log/httpd/mod_jk.log +</source> + +<p> +Since JK 1.2.3 for Apache 2.x and JK 1.2.16 for Apache 1.3 this can also +be used for piped logging: +</p> + +<source> + JkLogFile "|/usr/bin/rotatelogs /var/log/httpd/mod_jk.log 86400" +</source> + +<p> +<b>JkLogLevel</b> +set the log level between : +</p> + +<ul> +<li> +<b>info</b> log will contain standard mod_jk activity (default). +</li> +<li> +<b>warn</b> log will contain non fatal error reports. +</li> +<li> +<b>error</b> log will contain also error reports. +</li> +<li> +<b>debug</b> log will contain all information on mod_jk activity +</li> +<li> +<b>trace</b> log will contain all tracing information on mod_jk activity +</li> +</ul> + +<source> + JkLogLevel info +</source> + +<p> +<code>info</code> should be your default selection for normal operations. +<br/> +<br/> +</p> + +<p> +<b>JkLogStampFormat</b> will configure the date/time format found on mod_jk log file. +Using the strftime() format string it's set by<br /> +default to <b>"[%a %b %d %H:%M:%S %Y]"</b> +</p> + +<source> + JkLogStampFormat "[%a %b %d %H:%M:%S %Y] " +</source> + +<p> +<br/> +<br/> +</p> + +<p> +<b>JkRequestLogFormat</b> will configure the format of mod_jk individual request logging. +Request logging is configured and enabled on a per virtual host basis. +To enable request logging for a virtual host just add a JkRequestLogFormat config. +The syntax of the format string is similar to the Apache LogFormat command, +here is a list of the available request log format options: +</p> + +<p> +<attributes name="Options"> + <attribute name="%b" required="false">Bytes sent, excluding HTTP headers (CLF format)</attribute> + <attribute name="%B" required="false">Bytes sent, excluding HTTP headers</attribute> + <attribute name="%H" required="false">The request protocol</attribute> + <attribute name="%m" required="false">The request method</attribute> + <attribute name="%p" required="false">The canonical Port of the server serving the request</attribute> + <attribute name="%q" required="false">The query string (prepended with a ? if a query string exists, otherwise an empty string)</attribute> + <attribute name="%r" required="false">First line of request</attribute> + <attribute name="%s" required="false">Request HTTP status code</attribute> + <attribute name="%T" required="false">Request duration, elapsed time to handle request in seconds '.' micro seconds</attribute> + <attribute name="%U" required="false">The URL path requested, not including any query string.</attribute> + <attribute name="%v" required="false">The canonical ServerName of the server serving the request</attribute> + <attribute name="%V" required="false">The server name according to the UseCanonicalName setting</attribute> + <attribute name="%w" required="false">Tomcat worker name</attribute> + <attribute name="%R" required="false">Real worker name</attribute> +</attributes> + +<source> + JkRequestLogFormat "%w %V %T" +</source> + +<br/> +<br/> +</p> + +<p> +You can also log mod_jk information using the Apache standard module <b>mod_log_config</b>. +The module sets several notes in the Apache httpd notes table. +Most of them are are only useful in combination with a load balancer worker. +</p> + +<p> +<attributes name="Note"> + <attribute name="JK_WORKER_NAME" required="false">Name of the worker selected by the URI mapping</attribute> + <attribute name="JK_WORKER_TYPE" required="false">Type of the worker selected by the URI mapping</attribute> + <attribute name="JK_WORKER_ROUTE" required="false">Actual worker name selected by the URI mapping (usually a member of the load balancer).<br/> + Before version 1.2.26 only available if JkRequestLogFormat is set.</attribute> + <attribute name="JK_REQUEST_DURATION" required="false">Request duration in seconds and microseconds.<br/> + Before version 1.2.26 only available if JkRequestLogFormat is set.</attribute> + <attribute name="JK_LB_FIRST_NAME" required="false">Load-Balancer: Name of the first worker tried</attribute> + <attribute name="JK_LB_FIRST_TYPE" required="false">Load-Balancer: Type of the first worker tried</attribute> + <attribute name="JK_LB_FIRST_ACCESSED" required="false">Load-Balancer: Access count for the first worker tried</attribute> + <attribute name="JK_LB_FIRST_READ" required="false">Load-Balancer: Bytes read for the first worker tried</attribute> + <attribute name="JK_LB_FIRST_TRANSFERRED" required="false">Load-Balancer: Bytes transferred for the first worker tried</attribute> + <attribute name="JK_LB_FIRST_ERRORS" required="false">Load-Balancer: Error count for the first worker tried</attribute> + <attribute name="JK_LB_FIRST_BUSY" required="false">Load-Balancer: Busy count for the first worker tried</attribute> + <attribute name="JK_LB_FIRST_ACTIVATION" required="false">Load-Balancer: Activation state for the first worker tried</attribute> + <attribute name="JK_LB_FIRST_STATE" required="false">Load-Balancer: Error state for the first worker tried</attribute> + <attribute name="JK_LB_LAST_NAME" required="false">Load-Balancer: Name of the last worker tried</attribute> + <attribute name="JK_LB_LAST_TYPE" required="false">Load-Balancer: Type of the last worker tried</attribute> + <attribute name="JK_LB_LAST_ACCESSED" required="false">Load-Balancer: Access count for the last worker tried</attribute> + <attribute name="JK_LB_LAST_READ" required="false">Load-Balancer: Bytes read for the last worker tried</attribute> + <attribute name="JK_LB_LAST_TRANSFERRED" required="false">Load-Balancer: Bytes transferred for the last worker tried</attribute> + <attribute name="JK_LB_LAST_ERRORS" required="false">Load-Balancer: Error count for the last worker tried</attribute> + <attribute name="JK_LB_LAST_BUSY" required="false">Load-Balancer: Busy count for the last worker tried</attribute> + <attribute name="JK_LB_LAST_ACTIVATION" required="false">Load-Balancer: Activation state for the last worker tried</attribute> + <attribute name="JK_LB_LAST_STATE" required="false">Load-Balancer: Error state for the last worker tried</attribute> +</attributes> + +<source> + LogFormat "%h %l %u %t \"%r\" %>s %b %{JK_WORKER_NAME}n %{JK_LB_FIRST_NAME}n \ + %{JK_LB_FIRST_BUSY}n %{JK_LB_LAST_NAME}n %{JK_LB_LAST_BUSY}n" mod_jk_log + CustomLog logs/access_log mod_jk_log +</source> + +<br/> +<br/> +</p> + +</subsection> + +<subsection name="Forwarding"> +<p> +The directive JkOptions allow you to set many forwarding options which will enable (+) +or disable (-) following option. Without any leading signs, options will be enabled. +<br/> +<br/> +</p> + +<p> +The four following options <b>+ForwardURIxxx</b> are mutually exclusive. +Exactly one of them is required, a negative sign prefix is not allowed with them. +The default value is "ForwardURIProxy" since version 1.2.24. +It was "ForwardURICompatUnparsed" in version 1.2.23 and +"ForwardURICompat" until version 1.2.22. +You can turn the default off by switching on one of the other two options. +You should leave this at it's default value, unless you have a very good +reason to change it. +<br/> +<br/> +</p> + +<p> +All options are inherited from the global server to virtual hosts. +Options that support enabling (plus options) and disabling (minus options), +are inherited in the following way: +<br/> +<br/> +options(vhost) = plus_options(global) - minus_options(global) + plus_options(vhost) - minus_options(vhost) +<br/> +<br/> +</p> + +<p> +Using JkOptions <b>ForwardURIProxy</b>, the forwarded URI +will be partially reencoded after processing inside Apache httpd and +before forwarding to Tomcat. This will be compatible with local +URL manipulation by mod_rewrite and with URL encoded session ids. + +<source> + JkOptions +ForwardURIProxy +</source> + +<br/> +<br/> +</p> + +<p> +Using JkOptions <b>ForwardURICompatUnparsed</b>, the forwarded URI +will be unparsed. It's spec compliant and secure. +It will always forward the original request URI, so rewriting +URIs with mod_rewrite and then forwarding the rewritten URI +will not work. + +<source> + JkOptions +ForwardURICompatUnparsed +</source> + +<br/> +<br/> +</p> + +<p> +Using JkOptions <b>ForwardURICompat</b>, the forwarded URI will +be decoded by Apache httpd. Encoded characters will be decoded and +explicit path components like ".." will already be resolved. +This is less spec compliant and is <b>not safe</b> if you are using +prefix JkMount. This option will allow to rewrite URIs with +mod_rewrite before forwarding. + +<source> + JkOptions +ForwardURICompat +</source> + +<br/> +<br/> +</p> + +<p> +Using JkOptions <b>ForwardURIEscaped</b>, the forwarded URI will +be the encoded form of the URI used by ForwardURICompat. +Explicit path components like ".." will already be resolved. +This will not work in combination with URL encoded session IDs, +but it will allow to rewrite URIs with mod_rewrite before forwarding. + +<source> + JkOptions +ForwardURIEscaped +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>RejectUnsafeURI</b> will block all +URLs, which contain percent signs '%' or backslashes '\' +after decoding. +<br/> +<br/> +</p> +<p> +Most web apps do not use such URLs. Using the option RejectUnsafeURI, you +can block several well known URL encoding attacks. By default, this option +is not set. +</p> +<p> +You can also realise such a check with mod_rewrite, which is more powerful +but also slightly more complicated. + +<source> + JkOptions +RejectUnsafeURI +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>ForwardDirectories</b> is used in conjunction with <b>DirectoryIndex</b> +directive of Apache web server. As such mod_dir should be available to Apache, +statically or dynamically (DSO) +<br/> +<br/> +</p> + +<p> +When DirectoryIndex is configured, Apache will create sub-requests for +each of the local-url's specified in the directive, to determine if there is a +local file that matches (this is done by stat-ing the file). +</p> + +<p> +If ForwardDirectories is set to false (default) and Apache doesn't find any +files that match, Apache will serve the content of the directory (if directive +Options specifies Indexes for that directory) or a <code>403 Forbidden</code> response (if +directive Options doesn't specify Indexes for that directory). +</p> + +<p> +If ForwardDirectories is set to true and Apache doesn't find any files that +match, the request will be forwarded to Tomcat for resolution. This is used in +cases when Apache cannot see the index files on the file system for various +reasons: Tomcat is running on a different machine, the JSP file has been +precompiled etc. +</p> + +<p>Note that locally visible files will take precedence over the +ones visible only to Tomcat (i.e. if Apache can see the file, that's the one +that's going to get served). This is important if there is more then one type of +file that Tomcat normally serves - for instance Velocity pages and JSP pages. + +<source> + JkOptions +ForwardDirectories +</source> +<br/> +<br/> +</p> + +<p> +JkOptions <b>ForwardLocalAddress</b>, you ask mod_jk to send the local address, +of the Apache web server instead remote client address. This can be used by +Tomcat remote address valve for allowing connections only from registered Apache +web servers. + +<source> + JkOptions +ForwardLocalAddress +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>FlushPackets</b>, you ask mod_jk to flush Apache's connection +buffer after each AJP packet chunk received from Tomcat. This option can have +a strong performance penalty for Apache and Tomcat as writes are performed +more often than would normally be required (ie: at the end of each +response). + +<source> + JkOptions +FlushPackets +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>FlushHeader</b>, you ask mod_jk to flush Apache's connection +buffer after the response headers have been received from Tomcat. + +<source> + JkOptions +FlushHeader +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>DisableReuse</b>, you ask mod_jk to close connections immediately +after their use. Normally mod_jk uses persistent connections and pools idle +connections to reuse them, when new requests have to be sent to Tomcat. +</p> + +<p> +Using this option will have a strong performance penalty for Apache and Tomcat. +Use this only as a last resort in case of unfixable network problems. +If a firewall between Apache and Tomcat silently kills idle connections, +try to use the worker attribute socket_keepalive in combination with an appropriate +TCP keepalive value in your OS. + +<source> + JkOptions +DisableReuse +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>ForwardKeySize</b>, you ask mod_jk, when using ajp13, to forward also the SSL Key Size as +required by Servlet API 2.3. +This flag shouldn't be set when servlet engine is Tomcat 3.2.x (on by default). + +<source> + JkOptions +ForwardKeySize +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>ForwardSSLCertChain</b>, you ask mod_jk, when using ajp13, +to forward SSL certificate chain (off by default). +Mod_jk only passes the <code>SSL_CLIENT_CERT</code> to the AJP connector. This is not a +problem with self-signed certificates or certificates directly signed by the +root CA certificate. However, there's a large number of certificates signed by +an intermediate CA certificate, where this is a significant problem: A servlet +will not have the possibility to validate the client certificate on its own. The +bug would be fixed by passing on the <code>SSL_CLIENT_CERT_CHAIN</code> to Tomcat via the AJP connector. +<br/> +This directive exists only since version 1.2.22. +<source> + JkOptions +ForwardSSLCertChain +</source> + +<br/> +<br/> +</p> + +<p> +The directive <b>JkEnvVar</b> allows you to forward environment variables +from Apache server to Tomcat engine. +You can add a default value as a second parameter to the directive. +If the default value is not given explicitly, the variable +will only be send, if it is set during runtime. +<br/> +The variables can be retrieved on the Tomcat side as request attributes +via request.getAttribute(attributeName). +Note that the variables send via JkEnvVar will not be listed +in request.getAttributeNames(). +<br/> +<br/> +The variables are inherited from the global server to virtual hosts. + +<source> + JkEnvVar SSL_CLIENT_V_START undefined +</source> +<br/> +<br/> +</p> + +</subsection> + +<subsection name="Assigning URLs to Tomcat"> +<p> +If you have created a custom or local version of mod_jk.conf-local as noted above, +you can change settings such as the workers or URL prefix. +</p> +<p> +<b>JkMount</b> directive assign specific URLs to Tomcat. +In general the structure of a JkMount directive is: +</p> + +<source> + JkMount [URL prefix] [Worker name] +</source> + +<source> + # send all requests ending in .jsp to worker1 + JkMount /*.jsp worker1 + # send all requests ending /servlet to worker1 + JkMount /*/servlet/ worker1 + # send all requests jsp requests to files located in /otherworker will go worker2 + JkMount /otherworker/*.jsp worker2 +</source> + +<p> +You can use the JkMount directive at the top level or inside <VirtualHost> +sections of your httpd.conf file. +</p> +<p><b>JkUnMount</b> directive acts as an opposite to JkMount and blocks access +to a particular URL. The purpose is to be able to filter out the particular content +types from mounted context. The following example mounts /servlet/* +context, but all .gif files that belongs to that context are not served. +</p> +<source> + # send all requests ending with /servlet to worker1 + JkMount /servlet/* worker1 + # do not send requests ending with .gif to worker1 + JkUnMount /servlet/*.gif worker1 +</source> +<p> +JkUnMount takes precedence over JkMount directives, meaning that the JK +will first try to mount and then checks, if there is an exclusion defined by a +JkUnMount. A JkUnMount overrides a JkMount only, if the worker names in the +JkMount and in the JkUnMount are the same. +</p> +<p> +The following example will block all .gif files although there is a JkMount for them: +</p> +<source> + # do not send requests ending with .gif to worker1 + JkUnMount /*.gif worker1 + # The .gif files will not be mounted cause JkUnMount takes + # precedence over JkMount directive + JkMount /servlet/*.gif worker1 +</source> +<p> +Starting with version 1.2.26 of JK you can apply a JkUnMount to any worker, +by using the star character '*' as the worker name in the JkUnMount. +More complex patterns in JkUnMount worker names are not allowed. +</p> +<source> + # Mapping the webapps myapp1 and myapp2: + /myapp1/*=worker1 + /myapp2/*=worker2 + # Exclude the all subdirectories static for all workers: + !/*/static/*=* + # Exclude some suffixes for all workers: + !*.html=* +</source> +<p> +<b>JkAutoAlias</b> directive automatically <b>Alias</b> webapp context directories into +the Apache document space. It enables Apache to serve a static context while Tomcat +serving dynamic context. This directive is used for convenience so that you don't +have to put an apache Alias directive for each application directory inside Tomcat's +webapp directory. For security reasons is is strongly recommended that JkMount +is used to pass all requests to Tomcat by default and JkUnMount is used to +explicitly exclude static content to be served by httpd. It should also be noted +that content served by httpd will bypass any security constraints defined in the +application's web.xml. +</p> +<source> + # enter the full path to the tomcat webapps directory + JkAutoAlias /opt/tomtact/webapps +</source> +<p>The following example shows how to serve a dynamic context by +Tomcat and static using Apache. The webapps directory has to +be accessible by apache.</p> + +<source> + # enter the full path to the tomcat webapps directory + JkAutoAlias /opt/tomtact/webapps + + # Mount 'servlets-examples' directory. It's physical location + # is assumed to be in the /opt/tomtact/webapps/servlets-examples + # ajp13w is a worker defined in the workers.properties + JkMount /servlets-examples/* ajp13w + + # Unmount desired static content from servlets-examples webapp. + # This content will be served by the httpd directly. + JkUnMount /servlets-examples/*.gif ajp13w + JkUnMount /servlets-examples/*.jpg ajp13w +</source> +<p>Note that you can have a single JkAutoAlias directive per virtual +host inside your httpd.conf +</p> +<p> +<b>JkWorkerProperty</b> is a new directive available from JK 1.2.7 +version. It is a convenient method for setting directives that are +usually set inside <b>workers.propeties</b> file. The parameter for +that directive is raw line from workers.properties file. +</p> +<source> + # Just like workers.properties but exact line is prefixed + # with JkWorkerProperty + + # Minimal jk configuration + JkWorkerProperty worker.list=ajp13w + JkWorkerProperty worker.ajp13w.type=ajp13 + JkWorkerProperty worker.ajp13w.host=localhost + JkWorkerProperty worker.ajp13w.port=8009 +</source> +<p> +<b>JkMountFile</b> is a new directive available from JK 1.2.9 +version. It is used for dynamic updates of mount points at runtime. +When the mount file is changed, JK will reload it's content. +</p> +<source> + # Load mount points + + JkMountFile conf/uriworkermap.properties +</source> +<p>If the mount point uri starts with an exclamation mark '!' +it defines an exclusion in the same way JkUnMount does. +If the mount point uri starts with minus sign '-' +the mount point will only be disabled. A disabled mount can be reenabled +by deleting the minus sign and waiting for the JkMountFile to reload. +An exclusion can be disabled by prefixing it with a minus sign. +</p> +<source> + # Sample uriworkermap.properties file + + /servlets-examples/*=ajp13w + # Do not map .jpeg files + !/servlets-examples/*.jpeg=ajp13w + # Make jsp examples initially disabled + -/jsp-examples/*=ajp13w +</source> +<p>At run time you can change the content of this file. For example +removing minus signs will enable the previously disabled uri mappings. +You can add any number of new entries at runtime that reflects the newly deployed +applications. Apache will reload the file and update the mount +points within 60 second interval. +</p> +<p> +There is no way to delete entries by dynamic reloading, but you can disable or +exclude mappings. +<br/> +<br/> +</p> + +</subsection> + +<subsection name="Using SetHandler and Environment Variables"> +<p> +Alternatively to the mod_jk specific directives, you can also use +SetHandler and environment variables to control, which requests +are being forwarded via which worker. This gives you more flexibility, +but the results might be more difficult to understand. If you mix both +ways of defining the forwards, in general to mod_jk directives will win. +</p> +<p> +<b>SetHandler jakarta-servlet</b> forces requests to be handled by mod_jk. +If you neither specify any workers via JkMount and the related directives, +not via the environment variable described below, +the first worker in the list of all worker will be chosen. You can use SetHandler +for example in Location blocks or with Apache 2.2 also in RewriteRule. +</p> +<p> +In order to control the worker using <b>SetEnvIf</b> or <b>RewriteRule</b> +for more complex rules, you can set the environment variable <b>JK_WORKER_NAME</b> +to the name of your chosen target worker. This enables you to decide on +the chosen worker in a more flexible way, including dependencies on cookie values. +This feature has been added in version 1.2.19 of mod_jk. +</p> +<p> +In order to use another variable than <b>JK_WORKER_NAME</b>, you can set the name +of this variable via the <b>JkWorkerIndicator</b> directive. +</p> +<p> +You can also define exclusions from mod_jk forwards by setting the environment +variable <b>no-jk</b>. +</p> +<source> + # Automatically map all encoded urls + <Location *;jsessionid=> + SetHandler jakarta-servlet + SetEnv JK_WORKER_NAME my_worker + </Location> + + # Map all subdirs to workers via naming rule + # and exclude static content. + <Location /apps/> + SetHandler jakarta-servlet + SetEnvIf REQUEST_URI ^/apps/([^/]*)/ JK_WORKER_NAME=$1 + SetEnvIf REQUEST_URI ^/apps/([^/]*)/static no-jk + </Location> +</source> +<p> +Finally, starting with version 1.2.27 you can use the environment variable +<b>JK_REPLY_TIMEOUT</b> to dynamically set a reply timeout. +</p> +</subsection> + </section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/iis.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/iis.xml new file mode 100644 index 00000000..0539c454 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/iis.xml @@ -0,0 +1,387 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="iis.html"> + + &project; + + <properties> + <author email="mturk@apache.org">Mladen Turk</author> + <title>Configuring IIS</title> + </properties> + +<body> + +<section name="Requirements"> +<p> +The Tomcat redirector requires three entities: + +<ul> +<li> +<b>isapi_redirect.dll</b> - The IIS server plugin, either obtain a pre-built DLL or build it yourself (see the build section). +</li> +<li> +<b>workers.properties</b> - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). +A sample workers.properties can be found under the conf directory. +</li> +<li> +<b>uriworkermap.properties</b> - A file that maps URL-Path patterns to workers. +A sample uriworkermap.properties can be found under the conf directory as well. +</li> +</ul> +</p> + +<p> +The installation includes the following parts: + +<ul> +<li> +Configuring the ISAPI redirector with a default /examples context and checking that you can serve servlets with IIS. +</li> +<li> +Adding more contexts to the configuration. +</li> +</ul> +</p> +</section> +<section name="Registry settings"> +<p> +ISAPI redirector reads configuration from the registry, create a new registry key named : +</p> +<p> +<b>"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0"</b> +</p> +<attributes name="Key Name"> +<attribute name="extension_uri" required="true"><p> +A string value pointing to the ISAPI extension <b>/jakarta/isapi_redirect.dll</b> +</p></attribute> +<attribute name="log_file" required="false"><p> +A value pointing to location where log file will be created. +(for example <b>c:\tomcat\logs\isapi.log</b>) +<br/>If one of the log rotation settings (<b>log_rotationtime</b> or <b>log_filesize</b>) are specified then the actual log file name is based on this setting. +If the log file name includes any '%' characters, then it is treated as a format string for <code>strftime(3)</code>, +e.g. <b>c:\tomcat\logs\isapi-%Y-%m-%d-%H_%M_%S.log</b>. Otherwise, the suffix <em>.nnnnnnnnnn</em> is automatically added and is the time in seconds. +A full list of format string substitutions can be found in the <a href="http://httpd.apache.org/docs/2.0/programs/rotatelogs.html">Apache rotatelogs documentation</a> +</p></attribute> +<attribute name="log_level" required="false"><p> +A string value for log level +(can be debug, info, warn, error or trace).</p> +<p>This directive was added in version 1.2.31</p> +</attribute> +<attribute name="log_rotationtime" required="false"><p> +The time between log file rotations in seconds. +Setting this to 0 (the default) disables log rotation based on time.</p> +<p>This directive was added in version 1.2.31</p> +</attribute> +<attribute name="log_filesize" required="false"><p> +The maximum log file size in megabytes, after which the log file will be rotated. Setting this to 0 (the default) disables log rotation based on file size. +<br/>The value can have an optional <b>M</b> suffix, i.e. both <b>5</b> and <b>5M</b> will rotate the log file when it grows to 5MB. +<br/>If <b>log_rotationtime</b> is specified, then this setting is ignored. +</p></attribute> +<attribute name="worker_file" required="true"><p> +A string value which is the full path to workers.properties file +(for example <b>c:\tomcat\conf\workers.properties</b>) +</p></attribute> +<attribute name="worker_mount_file" required="true"><p> +A string value which is the full path to uriworkermap.properties file +(for example <b>c:\tomcat\conf\uriworkermap.properties</b>) +</p></attribute> +<attribute name="rewrite_rule_file" required="false"><p> +A string value which is the full path to rewrite.properties file +(for example <b>c:\tomcat\conf\rewrite.properties</b>) +</p></attribute> +<attribute name="shm_size" required="false"><p> +A DWORD value size of the shared memory. Set this value to be +the number of all defined workers * 400. +(Set this value only if you have <b>more</b> then <b>64</b> workers) +</p> +<p>This directive has been added in version 1.2.20</p> +<p>Starting with version 1.2.27 the size of the shared memory is determined +automatically, even for large numbers of workers. This attribute is not +needed any longer.</p> +</attribute> +<attribute name="worker_mount_reload" required="false"><p> +A DWORD value specifying the time in seconds upon which the +<b>worker_mount_file</b> will be reloaded. +</p> +<p>This directive has been added in version 1.2.20</p> +</attribute> +<attribute name="strip_session" required="false"><p> +A string value representing a boolean. If it is set to true, +URL session suffixes of the form ";jsessionid=..." get stripped of URLs, +even if the are served locally by the web server. +</p> +<p> +A true value can be represented by the string "1" or any string starting +with the letters "T" or "t". A false value will be assumed for "0" +or any string starting with "F" or "f". The default value is false. +</p> +<p>This directive has been added in version 1.2.21</p> +</attribute> +<attribute name="auth_complete" required="false"><p> +A DWORD value representing "0" or "1". This is needed because +of minor incompatibilities with IIS 5.1. +</p> +<p> +By default its value is 1, which means we use the SF_NOTIFY_AUTH_COMPLETE +event. If you set this to 0, then we use SF_NOTIFY_PREPROC_HEADERS. +This might be needed for IIS 5.1 when handling requests using the +PUT HTTP method. +</p> +<p>This directive has been added in version 1.2.21</p> +</attribute> +<attribute name="uri_select" required="false"><p> +A string value which influences, how URIs are decoded and re-encoded +between IIS and Tomcat. You should leave this at it's default value, +unless you have a very good reason to change it. +</p> +<p> +If the value is "parsed", the forwarded URI +will be decoded and explicit path components like ".." will already +be resolved. This is less spec compliant and is <b>not safe</b> +if you are using prefix forwarding rules. +</p> +<p> +If the value is "unparsed", the forwarded URI +will be the original request URI. It's spec compliant and also +the safest option. Rewriting the URI and then forwarding the rewritten +URI will not work. +</p> +<p> +If the value is "escaped", the forwarded URI +will be the re-encoded form of the URI used by "parsed". +Explicit path components like ".." will already be resolved. +This will not work in combination with URL encoded session IDs. +</p> +<p> +If the value is "proxy", the forwarded URI +will be a partially re-encoded form of the URI used by "parsed". +Explicit path components like ".." will already be resolved. +and problematic are re-encoded. +</p> +<p>The default value since version 1.2.24 is "proxy". Before it was "parsed".</p> +</attribute> +<attribute name="reject_unsafe" required="false"><p> +A string value representing a boolean. If it is set to true, +URLs containing percent signs '%' or backslashes '\' +after decoding will be rejected. +</p> +<p> +Most web apps do not use such URLs. By enabling "reject_unsafe" you +can block several well known URL encoding attacks. +</p> +<p> +A true value can be represented by the string "1" or any string starting +with the letters "T" or "t". A false value will be assumed for "0" +or any string starting with "F" or "f". The default value is false. +</p> +<p>This directive has been added in version 1.2.24</p> +</attribute> +<attribute name="watchdog_interval" required="false"><p> +A DWORD value representing the watchdog thread interval in seconds. +The workers are maintained periodically by a background thread +running periodically every watchdog_interval seconds. Worker maintenance +checks for idle connections, corrects load status and is able +to detect backend health status. +</p> +<p> +The maintenance only happens, if since the last maintenance at +least <a href="workers.html"><code>worker.maintain</code></a> +seconds have passed. So setting the watchdog_interval +much smaller than <code>worker.maintain</code> is not useful. +</p> +<p> +The default value is 0 seconds, meaning the watchdog thread +will not be created, and the maintenance is done in combination +with normal requests instead. +</p> +<p>This directive has been added in version 1.2.27</p> +</attribute> +<attribute name="error_page" required="false"><p> +A string value representing the error page url redirection when +backend returns non-200 response. This directive can be used +to customise the error messages returned from backend server. +</p> +<p>The url must point to a valid server url and can contain +format string number <code>(%d)</code> that can be used to +separate the pages by error number. The redirect url in that +case is formatted by replacing <code>%d</code> from +<code>error_page</code> to returned error number. +</p> +<p>This directive has been added in version 1.2.27</p> +</attribute> +<attribute name="enable_chunked_encoding" required="false"><p> +A string value representing a boolean. If it is set to true, +chunked encoding is supported by the server. +</p> +<p> +A true value can be represented by the string "1" or any string starting +with the letters "T" or "t". A false value will be assumed for "0" +or any string starting with "F" or "f". The default value is false. +</p> +<warn>This option is considered experimental and its support +must be compile time enabled. Use <code>isapi_redirect.dll</code> +with chunked support enabled. +</warn> +<p>This directive has been added in version 1.2.27</p> +</attribute> +</attributes> +</section> +<section name="Using a properties file for configuration"> +<p> +The ISAPI redirector can read it's configuration from a properties file instead of the registry. +This has the advantage that you can use multiple ISAPI redirectors with independent configurations on the same server. +The redirector will check for the properties file during initialisation, and use it in preference to the registry if present. +</p> +<p> +Create a properties file in the same directory as the ISAPI redirector called <b>isapi_redirect.properties</b> i.e. with the same name as the ISAPI redirector DLL but with a <em>.properties</em> extension. A sample isapi_redirect.properties can be found under the conf directory. +</p> +<p> +The property names and values in the properties file are the same as for the registry settings described above. For example: +</p> +<p> +<source> +# Configuration file for the Jakarta ISAPI Redirector + +# The path to the ISAPI Redirector Extension, relative to the website +# This must be in a virtual directory with execute privileges +extension_uri=/jakarta/isapi_redirect.dll + +# Full path to the log file for the ISAPI Redirector +log_file=c:\tomcat\logs\isapi_redirect.log + +# Log level (debug, info, warn, error or trace) +log_level=info + +# Full path to the workers.properties file +worker_file=c:\tomcat\conf\workers.properties + +# Full path to the uriworkermap.properties file +worker_mount_file=c:\tomcat\conf\uriworkermap.properties +</source> +</p> +<p> + Notes: + <ul> + <li> + Back-slashes - '\' - are not escape characters. + </li> + <li> + Comment lines begin with '#'. + </li> + </ul> +</p> +<p>Starting with version 1.2.27 two environment variables are +dynamically added to the environment that can be used inside +<code>.properties</code> files. + <ul> + <li>JKISAPI_PATH - Full path to the ISAPI Redirector. + </li> + <li>JKISAPI_NAME - Name of the ISAPI Redirector dll without extension + </li> + </ul> +</p> +<p><source> +# Use the logs in the installation path of ISAPI Redirector +log_file=$(ISAPI_PATH)\$(ISAPI_NAME).log +</source></p> +</section> + +<section name="Log file rotation"> +<p> +The ISAPI redirector with version 1.2.31 can perform log rotation, with configuration and behaviour similar to the +<a href="http://httpd.apache.org/docs/2.0/programs/rotatelogs.html">rotatelogs</a> program provided with Apache HTTP Server. +</p> +<p> +To configure log rotation, configure a <b>log_file</b>, and one of the <b>log_rotationtime</b> or <b>log_filesize</b> options. +If both are specified, the <b>log_rotationtime</b> will take precedence, and <b>log_filesize</b> will be ignored. +<br/>For example, to configure daily rotation of the log file: +</p> +<source> +# Configuration file for the Jakarta ISAPI Redirector +... + +# Full path to the log file for the ISAPI Redirector +log_file=c:\tomcat\logs\isapi_redirect.%Y-%m-%d.log + +# Log level (debug, info, warn, error or trace) +log_level=info + +# Rotate the log file every day +log_rotationtime=86400 + +... +</source> +<p> +Or to configure rotation of the log file when it reaches 5MB in size: +</p> +<source> +# Configuration file for the Jakarta ISAPI Redirector +... + +# Full path to the log file for the ISAPI Redirector +log_file=c:\tomcat\logs\isapi_redirect.%Y-%m-%d-%H.log + +# Log level (debug, info, warn, error or trace) +log_level=info + +# Rotate the log file at 5 MB +log_filesize=5M + +... +</source> +<p> +The log will be rotated whenever the configured limit is reached, but only if the log file name would change. If you configure + a log file name with <code>strftime(3)</code> format codes in it, then ensure it specifies the same granularity + as the rotation time configured, e.g. <b>%Y-%m-%d</b> if rotating daily (<b>log_rotationtime=86400</b>). +<br/>See the <a href="http://httpd.apache.org/docs/2.0/programs/rotatelogs.html">rotatelogs</a> documentation for more examples. +</p> + +</section> + +<section name="Using a simple rewrite rules"> +<p> +The ISAPI redirector with version 1.2.16 can do a simple URL rewriting. Although not +as powerful as Apache Httpd's mod_rewrite, it allows a simple exchange of request URIs +</p> +<p> +The rule is in the form original-url-prefix=forward-url-prefix. For example: +</p> +<source> +# Simple rewrite rules, making /jsp-examples +# and /servlets-examples available under shorter URLs +/jsp/=/jsp-examples/ +/servlets/=/servlets-examples/ +</source> +<p> +You can also use regular expressions, if you prefix the rule with a tilde <code>~</code>: +</p> +<source> +# Complex rewrite rule, adding "-examples" +# to the first path component of all requests +~/([^/]*)=/$1-examples +</source> +<p> +Note that uriworkermap.properties must use the URLs before rewriting. +</p> +</section> + +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/project.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/project.xml new file mode 100644 index 00000000..f5d56447 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/project.xml @@ -0,0 +1,81 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<project name="Apache Tomcat Connector Documentation - Reference Guide" + href="http://tomcat.apache.org/"> + + <title>The Apache Tomcat Connector - Reference Guide</title> + + <logo href="/images/tomcat.gif"> + The Apache Tomcat Connector - Reference Guide + </logo> +<body> + + <menu name="Links"> + <item name="Docs Home" href="../index.html"/> + </menu> + + <menu name="Reference Guide"> + <item name="workers.properties" href="../reference/workers.html"/> + <item name="uriworkermap.properties" href="../reference/uriworkermap.html"/> + <item name="Status Worker" href="../reference/status.html"/> + <item name="Apache HTTP Server" href="../reference/apache.html"/> + <item name="IIS" href="../reference/iis.html"/> + </menu> + + <menu name="Generic HowTo"> + <item name="For the impatient" href="../generic_howto/quick.html"/> + <item name="All about workers" href="../generic_howto/workers.html"/> + <item name="Timeouts" href="../generic_howto/timeouts.html"/> + <item name="Load Balancing" href="../generic_howto/loadbalancers.html"/> + <item name="Reverse Proxy" href="../generic_howto/proxy.html"/> + </menu> + + <menu name="Webserver HowTo"> + <item name="Apache HTTP Server" href="../webserver_howto/apache.html"/> + <item name="IIS" href="../webserver_howto/iis.html"/> + <item name="Netscape/SunOne/Sun" href="../webserver_howto/nes.html"/> + </menu> + + <menu name="AJP Protocol Reference"> + <item name="AJPv13" href="../ajp/ajpv13a.html"/> + <item name="AJPv13 Extension Proposal" href="../ajp/ajpv13ext.html"/> + </menu> + + <menu name="Miscellaneous Documentation"> + <item name="Frequently asked questions" href="../miscellaneous/faq.html"/> + <item name="Changelog" href="../miscellaneous/changelog.html"/> + <item name="Current Tomcat Connectors bugs" href="http://issues.apache.org/bugzilla/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Tomcat+Connectors&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0="/> + <item name="Contribute documentation" href="../miscellaneous/doccontrib.html"/> + <item name="JK Status Ant Tasks" href="../miscellaneous/jkstatustasks.html"/> + <item name="Reporting Tools" href="../miscellaneous/reporttools.html"/> + <item name="Old JK/JK2 documentation" href="http://tomcat.apache.org/connectors-doc-archive/jk2/index.html"/> + </menu> + + <menu name="News"> + <item name="2011" href="../news/20110701.html"/> + <item name="2010" href="../news/20100101.html"/> + <item name="2009" href="../news/20090301.html"/> + <item name="2008" href="../news/20081001.html"/> + <item name="2007" href="../news/20070301.html"/> + <item name="2006" href="../news/20060101.html"/> + <item name="2005" href="../news/20050101.html"/> + <item name="2004" href="../news/20041100.html"/> + </menu> + +</body> +</project> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/status.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/status.xml new file mode 100644 index 00000000..5c2a1f23 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/status.xml @@ -0,0 +1,584 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="status.html"> + + &project; + + <properties> + <author email="rjung@apache.org">Rainer Jung</author> + <title>Status Worker Reference</title> + </properties> + +<body> + +<section name="Introduction"> +<br/> +<p> +Tomcat Connectors has a special type of worker, the so-called status worker. +The status worker does not forward requests to Tomcat instances. Instead it allows +to retrieve status and configuration information at runtime, +and furthermore to change many configuration items dynamically. This can be done +via a simple embedded web interface. +</p> +<p> +The status worker is especially powerful, when used together with load balancing workers. +</p> +<p> +This document does not explain the HTML user interface of the status worker. +Until now it is very simple, so just go ahead and use it. This doc instead +tries to explain the less obvious features of the status worker. We also will give a +complete coverage of the various request parameters and their meaning, so that you can +include the status worker in your automation scripts. +</p> +<p> +The documentation of the status worker starts with <b>jk 1.2.20</b> +</p> +</section> + +<section name="Usage Patterns"> +<br/> +<subsection name="Actions"> +<br/> +<p> +The status worker knows about six actions. +<ul> +<li> +<b>list</b>: lists the configurations and runtime information of all configured workers. +The output will be grouped by global information first (version data), then load balancer +information, after that AJP worker information and finally the legend. For load balancers, +there will be a summary part, and after that details for each member worker. For all workers, +we also include the URL mappings (forward definitions). +</li> +<li> +<b>show</b>: the same as list, but only shows data for one chosen worker +</li> +<li> +<b>edit</b>: produces a form to edit configuration data for a chosen worker. There is a +special subtype of "edit", that makes it easy to change one attribute for all members of +a load balancer, e.g. their activation state. +</li> +<li> +<b>update</b>: commit changes made in an edit form. <b>Caution</b>: the changes will not be +persisted to the configuration files. As soon as your restart your web server, all changes +made through the status worker will be lost! On the other hand, the changes done by the status +worker will be applied during runtime without a restart of the web server. +</li> +<li> +<b>reset</b>: reset all runtime statistics for a worker. +</li> +<li> +<b>recover</b>: Mark a member of a load balancer, that is in error state, for immediate recovery. +</li> +<li> +<b>version</b>: only show version information of the web server and the JK software +</li> +<li> +<b>dump</b>: list the original workers configuration. <b>Caution</b>: the dump will only contain +the configuration that was used during startup. Any changes applied later by the dynamic management +interface of the status worker itself will not be contained in this dump. +The dump action has been added in version 1.2.27. +</li> +</ul> +</p> +</subsection> + +<subsection name="Output Format"> +<br/> +<p> +For most actions you can choose between 4 output formats. +<ul> +<li> +<b>HTML</b>: Used interactively with a browser +</li> +<li> +<b>XML</b>: Mostly useful for automation, when your scripting environment is XML friendly. +This format has rich structure information, but does not work line based, so you would really +like to use it together with XML tools. +</li> +<li> +<b>Properties</b>: This format is a line based format, that conforms to the rules of Java +property files. Most structure information is contained in the hierarchical key. For information, +that is of configuration nature, the format should produce lines very similar to the ones you can +use in workers.properties. It will not produce a complete configuration file! +</li> +<li> +<b>Text</b>: A simple textual output format. +</li> +</ul> +The "edit" action does only make sense for the HTML output type. +</p> +</subsection> + +<subsection name="User Interface Features"> +<br/> +<p> +In the HTML view, there is an <b>automatic refresh</b> feature, implemented via the meta refresh +option of HTML. Once you start the automatic refresh, the UI will will respect it for all actions +except edit, update and maintain. Even if you navigate through one of those, the automatic refresh +will start again as soon as you come back to one of the other actions. +</p> +<p> +Many parts of the HTML page can be minimised, if they are not interesting for you. There are a couple +of "Hide" links, which will collapse parts of the information. The feature exists for the following +blocks of information: +<ul> +<li> +<b>Legend</b>: Do not show the legend for the information presented in "list" and "show" actions +</li> +<li> +<b>URI mappings</b>: Do not show the URI mapping for the workers +</li> +<li> +<b>Load Balancing Workers</b>: Do not show workers of type "lb" +</li> +<li> +<b>AJP Workers</b>: Do not show workers of type ajp +</li> +<li> +<b>Balancer Members</b>: Do not show detailed information concerning each member of load balancers +</li> +<li> +<b>Load Balancer Configuration</b>: Do not show configuration data for load balancers +</li> +<li> +<b>Load Balancer Summary</b>: Do not show status summary for load balancers +</li> +<li> +<b>AJP Configuration</b>: Do not show configuration data for ajp workers load balancer members +</li> +</ul> +The last three minimisation features have been added in version 1.2.27. +</p> +</subsection> + +<subsection name="Special Considerations concerning URL Maps and Virtual Hosts"> +<br/> +<p> +<b>Note: </b>The following restriction has been removed starting with version 1.2.26. +</p> +<p> +The Apache module mod_jk makes use of the internal Apache httpd infrastructure concerning +virtual hosts. The downside of this is, that the status worker can only show URL maps, for +the virtual host it is defined in. It is not able to reach the configuration objects +for other virtual hosts. Of course you can define a status worker in any virtual host you +are using. All information presented apart from the URL maps will be the same, independent +of the virtual host the status worker has been called in. +</p> +</subsection> + +<subsection name="Logging"> +<br/> +<p> +The status worker will log changes made to the configuration with log level "info" to the usual +JK log file. Invalid requests will be logged with log level "warn". If you want to report some +broken behaviour, log file content of level "debug" or even "trace" will be useful. +</p> +</subsection> + +</section> + +<section name="Configuration"> +<br/> +<subsection name="Basic Configuration"> +<br/> +<p> +The basic configuration of a status worker is very similar to that of a usual ajp worker. +You need to specify a name for the worker, and the URLs you want to map to it. The first +part of the configuration happens in the workers.properties file. We define a worker named +mystatus of type status: +<source> +worker.list=mystatus +worker.mystatus.type=status +</source> +Then we define a URL, which should be mapped to this worker, i.e. the URL we use +to reach the functionality of the status worker. You can use any method mod_jk supports +for the web server of your choice. Possibilities are maps inside uriworkermap.properties, +an additional mount attribute in workers.properties, or in Apache JkMount. Here's an +example for a uriworkermap.properties line: +<source> +/private/admin/mystatus=mystatus +</source> +The URI pattern is case sensitive. +</p> +<p> +As you will learn in the following sections, the status worker is very powerful. You should +use the usual authentication and authorisation methods of your web server to secure this URL. +</p> +<p> +You can also define multiple instances of the status worker, by using different names and URL mappings. +For instance you might want to configure them individually +and then allow special groups of people to use them +</p> +</subsection> + +<subsection name="Output Customisation"> +<br/> +<p> +There are a couple of attributes for the workers.properties entries, which allow to customise +various aspects of the output of the status worker. +</p> +<p> +The attribute <b>css</b> can be set to the URL of a stylesheet: +<source> +worker.mystatus.css=/private/admin/static/mystatus.css +</source> +When writing HTML output, the status worker then includes the line +<source> +<link rel="stylesheet" type="text/css" href="/private/admin/static/mystatus.css" /> +</source> +There is no sample stylesheet included with the mod_jk release, and by default the attribute css +is empty, so no stylesheet reference will be included in the pages. The HTML code +of the status worker output pages does not include any class attributes. If you like to contribute a +stylesheet or improvements to the HTML layout, please contact us on the tomcat developers list. +</p> +<p> +The properties output format can be customised via the attribute <b>prefix</b>. The names of all +properties the status worker does output, will begin with this prefix. The default is "worker". +</p> +<p> +Several attributes influence the format when writing XML output. +The attribute <b>ns</b> allows to set a namespace prefix, that will be used for every status worker+element. +The default is "jk:". Setting it to "-" disables the namespace prefix. +</p> +<p> +With the attribute xmlns you can map the prefix to a namespace URL. The default value +is xmlns:jk="http://tomcat.apache.org". Setting it to "-" disables the output of the URL. +</p> +<p> +Finally you can specify an XML document type via the attribute doctype. The specified string will +be inserted at the beginning of the document, directly after the xml header. The default is empty. +</p> +</subsection> + +<subsection name="Securing Access"> +<br/> +<p> +We urge you to use the builtin access control features of your web server to control +access to the status worker URLs you have chosen. Nevertheless two configuration +attributes of status workers are helpful. The attribute "read_only" disables all features of +the status worker, that can be used to change configurations or runtime status of the other workers. +A read_only status worker will not allow access to the edit, update, reset or recover actions. +The default value is "False", ie. read/write. To enable read_only you need to set it to "True". +</p> +<p> +You could configure two status workers, one has read_only and will be made available to a larger +admin group, the other one will be used fully featured, but only by fewer people: +<source> +worker.list=jk-watch +worker.jk-watch.type=status +worker.jk-watch.read_only=True +worker.jk-watch.mount=/user/status/jk +worker.list=jk-manage +worker.jk-manage.type=status +worker.jk-manage.mount=/admin/status/jk +</source> +Starting with version 1.2.21, a read/write status worker can also be switched temporarily +into read-only mode by the user via a link in the HTML GUI. The user can always switch it +back to read/write. Only a status worker configured as read-only via the "read_only" attribute +is completely safe from applying any changes. +</p> +<p> +The other attribute you can use is <b>user</b>. By default this list is empty, which means +no limit on the users. You can set "user" to a comma separated list of user names. If your +web server is configured such that it sends the user names with the request, the status worker +will check, if the name attached with the request is contained in it's "user" list. +</p> +<p> +The user list can be split over multiple occurrences of the "user" attribute. +</p> +<p> +By default, the user names are matched case sensitively. Starting with version 1.2.21 you can set +the attribute <b>user_case_insensitive</b> to "True". Then the comparison will be made case insensitive. +</p> +</subsection> + +<subsection name="Service Availability Rating"> +<br/> +<p> +For load balancing workers the status worker shows some interesting overview information. +It categorises the members of the load balancer into the classes "good", "bad" and degraded". +This feature can be combined with external escalation procedures. Depending on your global +system design and your operating practises your preferred categorisation might vary. +</p> +<p> +The categorisation is based on the activation state of the workers (active, disabled or stopped), +which is a pure configuration state, and the runtime state +(OK or ERR with possible substates idle, busy, recovering, probing, and forced recovery) +which only depends on the runtime situation. +</p> +<p> +The runtime substates have the following meaning: +<ul> +<li> +<b>OK (idle)</b>: This worker didn't receive any request since the last balancer +maintenance. By default balancer maintenance runs every 60 seconds. The +worker should be OK, but since we didn't have to use it for some time, we +can't be sure. This state has been called N/A before version 1.2.24. +</li> +<li> +<b>OK (busy)</b>: All connections for this worker are in use for requests. +</li> +<li> +<b>ERROR (recovering)</b>: The worker was in error state for some time and is now +marked for recovery. The next request suitable for this worker will use it. +</li> +<li> +<b>ERROR (probing)</b>: After setting the worker to recovering, we received a request +suitable for this worker. This request is now using the worker. +</li> +<li> +<b>ERROR (forced recovery)</b>: The worker is in error, but we don't have an alternative +worker, so we keep using it. +</li> +</ul> +</p> +<p> +By default the status worker groups into "good" all members, that have activation "active" and +runtime state not equal to "error" with empty substate. +The "bad" group consists of the members, that have either activation +"stopped", or are in runtime state "error" with empty substate. +</p> +<p> +Workers that fit neither of the two groups, are considered to be "degraded". +</p> +<p> +You can define other rules for the grouping into good, bad and degraded. +The two attributes "good" and "bad" can be populated by a comma-separated list ob single characters or +dot-separated pairs. Each character stands for the first character of one of the possible states "active", +"disabled", "stopped", "ok", "idle", "busy", "recovering" and "error". The additional states "probing" +and "forced recovery" are always rated equivalent to "recovering". +Comma-separated entries will be combined +with logical "or", if you combine a configuration and a runtime state with a dot. the are combined with logical +"and". So the default value for "good" is "a.o,a.i,a.b,a.r", for "bad" it is "e,s". +</p> +<p> +The status worker first tries to match against the "bad" definitions, if this doesn't succeed +it tries to match against "good", and finally it chooses "degraded", if no "bad" or "good" match +can be found. +</p> +</subsection> +</section> + +<section name="Request Parameters"> +<br/> +<p> +This section should help you building automation scripts based on the jk status +management interface. This interface is stable in the sense, that we only expect +to add further parameters in the future. Existing parameters from previous versions +will keep their original semantics. We also expect the output formats XML, Properties +and Text to be kept stable. So please use those, if you want to parse status worker +output in your automation scripts. +</p> +<subsection name="Actions"> +<br/> +<p> +The action is determined by the parameter <b>cmd</b>. It can have the values "list", "show", +"edit", "update", "reset", "recover", "version" and "dump". If you omit the <b>cmd</b> parameter, +the default "list" will be used. +All actions except for "list", "refresh", "version" and "dump" need additional parameters. +</p> +<p> +The action "dump" has been added in version 1.2.27. +</p> +</subsection> +<subsection name="Output Format"> +<br/> +<p> +The format is determined by the parameter <b>mime</b>. It can have the values "html", "xml", +"txt" and "prop". If you omit the <b>mime</b> parameter, the default "html" +will be used. The action "edit" (the edit form) does only make sense for "mime=html". +</p> +</subsection> +<subsection name="Worker Selection"> +<br/> +<p> +Actions that operate on a single worker need one or two additional parameters to select +this worker. The parameter <b>w</b> contains the name of the worker from the worker list. +If an action operates on a member (sub worker) of a load balancer, the parameter <b>w</b> +contains the name of the load balancer worker, and the additional parameter <b>sw</b> contains the +name of the sub worker. +</p> +</subsection> +<subsection name="Automatic Refresh"> +<br/> +<p> +During automatic refresh, the parameter <b>re</b> contain the refresh interval in seconds. +If you omit this parameter, automatic refresh will be off. +</p> +</subsection> +<subsection name="Hide Options"> +<br/> +<p> +The parameter <b>opt</b> contains a bit mask of activated options. The default is 0, so +by default no options are activated. The following options exist: +<ul> +<li> +<b>0x0001</b>: hide members of lb workers +</li> +<li> +<b>0x0002</b>: hide URL maps +</li> +<li> +<b>0x0004</b>: hide the legend +</li> +<li> +<b>0x0008</b>: hide load balancer workers +</li> +<li> +<b>0x0010</b>: hide ajp workers +</li> +<li> +<b>0x0020</b>: only allow read_only actions for a read/write status worker. +</li> +<li> +<b>0x0040</b>: hide load balancer configuration +</li> +<li> +<b>0x0080</b>: hide load balancer status summary +</li> +<li> +<b>0x0100</b>: hide configuration for ajp and load balancer member workers +</li> +</ul> +Values 0x0040-0x0100 have been added in version 1.2.27. +</p> +</subsection> +<subsection name="Data Parameters for the standard Update Action"> +<br/> +<p> +You can use the edit action with a final click to the update button, to change settings of workers. +But you can also make direct calls to the update action. The following request parameters +contain the configuration information, you want to change. First the list for load balancer workers: +<ul> +<li> +<b>vlr</b>: retries (number) +</li> +<li> +<b>vlt</b>: recover_time (seconds) +</li> +<li> +<b>vlee</b>: error_escalation_time (seconds) +</li> +<li> +<b>vlx</b>: max_reply_timeouts (number) +</li> +<li> +<b>vls</b>: sticky_session (0/f/n/off=off, 1/t/y/on=on; case insensitive) +</li> +<li> +<b>vlf</b>: sticky_session_force (0/f/n/off=off, 1/t/y/on=on; case insensitive) +</li> +<li> +<b>vlm</b>: method (0/r="Requests", 1/t="Traffic", 2/b="Busyness", 3/s="Sessions"; case insensitive, only first character is used) +</li> +<li> +<b>vll</b>: lock (0/o="Optimistic", 1/p="Pessimistic"; case insensitive, only first character is used) +</li> +</ul> +And now the list of parameters you can use to change settings for load balancer members: +<ul> +<li> +<b>vwa</b>: activation flag (0/a="active", 1/d="disabled", 2/s="stopped"; case insensitive, only first character is used) +</li> +<li> +<b>vwf</b>: load balancing factor (integer weight) +</li> +<li> +<b>vwn</b>: route for use with sticky sessions (string) +</li> +<li> +<b>vwr</b>: redirect to define simple failover rules (string) +</li> +<li> +<b>vwc</b>: domain to tell JK about your replication design (string) +</li> +<li> +<b>vwd</b>: distance to express preferences (integer) +</li> +</ul> +Finally the list of parameters you can use to change settings for ajp workers and ajp load balancer members: +<ul> +<li> +<b>vahst</b>: host (string) +</li> +<li> +<b>vaprt</b>: port (number) +</li> +<li> +<b>vacpt</b>: connection_pool_timeout (number) +</li> +<li> +<b>vact</b>: connect_timeout (number) +</li> +<li> +<b>vapt</b>: prepost_timeout (number) +</li> +<li> +<b>vart</b>: reply_timeout (number) +</li> +<li> +<b>var</b>: retries (number) +</li> +<li> +<b>varo</b>: recovery_options (number) +</li> +<li> +<b>vamps</b>: max_packet_size (number) +</li> +</ul> +Note that changing the host name or port will only take effect for new connections. +Already established connections to the old address will still be used. +Nevertheless this feature is interesting, because you can provision load balancer +members with port "0", which will automatically be stopped during startup. Later +when you know the final names and ports, you can set them and they will be +automatically activated. +</p> +<p> +The leading character "v" has been added to the parameters in version 1.2.27. +Changing settings for ajp workers has also been introduced in version 1.2.27. +</p> +<p> +For the details of all parameters, we refer to the <a href="workers.html">workers.properties Reference</a>. +</p> +</subsection> +<subsection name="Aspect Editing for Load Balancer Members"> +<br/> +<p> +You can use the edit action to edit all settings for a load balancer or for a +member of a load balancer respectively on one page. If you want to edit one +configuration aspect for all members of a load balancer simultaneously, this +will be triggered by the parameter <b>att</b>. The value of the parameter indicates, +which aspect you want to edit. The list is the same as in the previous section, +except for "vahst" and "vaprt": +"vwa", "vwf", "vwn", "vwr", "vwc", "vwd", "vacpt", "vact", "vapt", "vart", "var", +"varo" and "vamps". But here you +need to put the name into the parameter <b>att</b>, instead of using it as a request +parameter name. +</p> +<p> +The values of the common aspect for all the load balancer members will be given +in parameters named "val0", "val1", .... +</p> +</subsection> +</section> + +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/uriworkermap.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/uriworkermap.xml new file mode 100644 index 00000000..f9a83dea --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/uriworkermap.xml @@ -0,0 +1,422 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="uriworkermap.html"> + + &project; + + <properties> + <author email="rjung@apache.org">Rainer Jung</author> + <author email="mturk@apache.org">Mladen Turk</author> + <title>uriworkermap.properties configuration</title> + </properties> + +<body> + +<section name="Introduction"> +<br/> +<p> +The forwarding of requests from the web server to tomcat gets configured by defining mapping rules. +Such a rule maps requests to workers. The request part of the map is described by a URI pattern, +the worker by it's worker name. +</p> +<p> +The so-called <b>uriworkermap</b> file is a mechanism of defining rules, +which works for all web servers. There exist also other web server specific configuration +options for defining rules, which will be mostly discussed on the reference pages for +configuring tomcat connectors for the individual web servers. +</p> +<p> +The name of the file is usually uriworkermap.properties, +although this is configurable in the web server. +Please consult the web server specific documentation pages on +how to enable the uriworkermap file. +</p> +<p> +The main features supported by the uriworkermap file are +<ul> +<li> +Support for comments in the rule file. +</li> +<li> +Exact and wildchar matches, shortcuts to map a directory and all including content. +</li> +<li> +Exclusion rules, disabling of rules and rule priorities. +</li> +<li> +Rule extensions, modifying worker behaviour per rule. +</li> +<li> +Virtual host integration: uri mapping rules can be expressed per virtual host. +The details are web server specific though. +</li> +<li> +Dynamic reloading: The file gets checked periodically for changes. +New versions are automatically reloaded without web server restarts. +</li> +<li> +Integration with the status worker. +</li> +</ul> +The following sections describe these aspects in more detail. +</p> +</section> + +<section name="Syntax"> +<br/> +<subsection name="Line format"> +<br/> +<p> +The file has a line based format. There are no continuation characters, +so each rule needs to be defined on a single line. Each rule is a pair consisting +of a URI pattern and a worker name, combined by an equals sign '=': +<source> + /myapp=myworker +</source> +The URI pattern is case sensitive. +</p> +</subsection> +<subsection name="Comments, white space"> +<br/> +<p> +All text after and including the character '#' gets ignored and can be used for comments. +Leading and trailing white space gets trimmed around the URI pattern and also around the worker name. +The following definitions are all equivalent: +<source> + # This is a white space example + /myapp=myworker + /myapp=myworker + /myapp = myworker +</source> +</p> +</subsection> + +<subsection name="URI patterns"> +<br/> +<p> +Inside the URI pattern three special characters can be used, '*', '?' and '|'. +The character '*' is a wildchar that matches any number of arbitrary characters +in the URI, '?' matches exactly one character. +Each URI pattern has to start with the character '/', or with '*' or with '?', +optionally prefixed by any combination of the modifiers '!' and '-' (see next section). +<source> + # Mapping the URI /myapp1 and everything under /myapp1/: + /myapp1=myworker-a + /myapp1/*=myworker-a + # Mapping all URI which end with a common suffix: + *.jsp=myworker + *.do=myworker +</source> +Since the first case of mapping a certain location and everything inside +it is very common, the character '|' gives a handy shortcut: +<source> + # Mapping the URI /myapp1 and everything under /myapp1/: + /myapp1|/*=myworker-a +</source> +The pattern 'X|Y' is exactly equivalent to the two maps 'X' and 'XY'. +</p> +</subsection> +</section> + +<section name="Exclusion, Disabling and Priorities"> +<br/> + +<subsection name="Exclusions and rule disabling"> +<br/> +<p> +Exclusion rules allows to define exclusions from URI rules, which would forward +requests to tomcat. If the exclusion rule matches, the request will not be forwarded. +This is usually used to serve static content by the web server. +A rule is an exclusion rule, if it is suffixed with '!': +<source> + # Mapping the URI /myapp and everything under /myapp/: + /myapp|/*=myworker + # Exclude the subdirectory static: + !/myapp/static|/*=myworker + # Exclude some suffixes: + !*.html=myworker +</source> +An exclusion rule overrides a normal mapping rule only, if the worker names in the +normal rule and in the exclusion rule are the same. Starting with version 1.2.26 of JK +you can apply an exclusion rule to any worker, by using the star character '*' as +the worker name in the exclusion rule. +More complex patterns in exclusion worker names are not allowed. +<source> + # Mapping the webapps /myapp1 and /myapp2: + /myapp1|/*=myworker1 + /myapp2|/*=myworker2 + # Exclude the all subdirectories static for all workers: + !/*/static|/*=* + # Exclude some suffixes for all workers: + !*.html=* +</source> +</p> +<p> +Rule disabling comes into play, if your web server merges rules from various sources, +and you want to disable any rule defined previously. Since the uriworkermap file gets +reloaded dynamically, you can use this to temporarily disable request forwarding: +A rule gets disabled, if it is suffixed with '-': +<source> + # We are not in maintenance. + # The maintenance rule got defined somewhere else. + -/*=maintenance +</source> +Exclusion rules can get disabled as well, then the rule starts with '-!'. +</p> +</subsection> + +<subsection name="Mapping priorities"> +<br/> +<p> +The most restrictive URI pattern is applied first. More precisely the URI patterns are +sorted by the number of '/' characters in the pattern (highest number first), and +rules with equal numbers are sorted by their string length (longest first). +</p> +<p> +If both distinctions still do not suffice, then the defining source of the rule is considered. +Rules defined in uriworkermap.properties come first, before rules defined by JkMount (Apache) +and inside workers.properties using the mount attribute. +</p> +<p> +All disabled rules are ignored. Exclusion rules are applied after all normal rules +have been applied. +</p> +<p> +There is no defined behaviour, for the following configuration conflict: +using literally the same URI pattern in the same defining source but with +different worker targets. +</p> +</subsection> +</section> + +<section name="Rule extensions"> +<br/> +<p> +Rule extensions were added in version 1.2.27 and are not available in earlier versions. +</p> +<subsection name="Syntax"> +<br/> +<p> +Rule extensions are additional attributes, that can be attached to any rule. +They are added at the end of the rule, each extension separated by a semicolon: +<source> + # This is an extension example, + # setting a reply_timeout of 1 minute + # only for this mapping. + /myapp=myworker;reply_timeout=60000 + # + # This is an example using multiple extensions + /myapp=myloadbalancer;reply_timeout=60000;stopped=member1 +</source> +Attributes set via rule extensions always overwrite conflicting +configurations in the worker definition file. +</p> +</subsection> +<subsection name="Extension reply_timeout"> +<br/> +<p> +The extension <code>reply_timeout</code> sets a reply timeout for a single mapping rule. +<source> + # Setting a reply_timeout of 1 minute + # only for this mapping. + /myapp=myworker;reply_timeout=60000 +</source> +It overrides any <code>reply_timeout</code> defined for the worker. The extension allows +to set a reasonable default reply timeout to the worker, and a more relaxed +reply timeout to URLs, which are known to start time intensive tasks. +For a general description of reply timeouts see the +<a href="../generic_howto/timeouts.html#Reply Timeout">timeouts</a> documentation. +</p> +</subsection> +<subsection name="Extensions active/disabled/stopped"> +<br/> +<p> +The extensions <code>active</code>, <code>disabled</code>, and <code>stopped</code> +can be used in a load balancer mapping rule to set selected members +of the load balancer into a special activation state. +<source> + # Stop forwarding only for member1 of loadbalancer + /myapp=myloadbalancer;stopped=member1 +</source> +Multiple members must be separated by commas or white space: +<source> + # Stop forwarding for member01 and member02 of loadbalancer + # Disable forwarding for member21 and member22 of loadbalancer + /myapp=myloadbalancer;stopped=member01,member02;disabled=member21,member22 +</source> +For the precise meaning of the activation states see the description of +<a href="../reference/workers.html#Advanced Worker Directives">activation</a>. +</p> +</subsection> +<subsection name="Extension fail_on_status"> +<br/> +<p> +The extension <code>fail_on_status</code> can be used in any rule: +<source> + # Send 503 instead of 404 and 500, + # and if we get a 503 also set the worker to error + /myapp=myworker;fail_on_status=-404,-500,503 +</source> +Multiple status codes must be separated by commas. +For the precise meaning of the attribute see the description of +<a href="../reference/workers.html#Advanced Worker Directives">fail_on_status</a>. +</p> +</subsection> +<subsection name="Extension use_server_errors"> +<br/> +<p> +The extension <code>use_server_errors</code> allows to let the web server +send an error page, instead of the backend (e.g. Tomcat) error page. +This is useful, if one wants to send customized error pages, but those are +not part of all web applications. They can then be put onto the web server. +</p> +<p> +The value of <code>use_server_errors</code> is a positive number. +Any request send to the backend, that returns with an http status +code bigger or equal to <code>use_server_errors</code>, will +be answered to the client with the error page of the web server +for this status code. +<source> + # Use web server error page for all errors + /myapp=myworker;use_server_errors=400 + # Use web server error page only for technical errors + /myotherapp=myworker;use_server_errors=500 +</source> +</p> +</subsection> +</section> + +<section name="Virtual host integration"> +<br/> + +<subsection name="IIS"> +<br/> +<p> +When using IIS you can restrict individual rules to special virtual hosts +by prefixing the URI pattern with the virtual host information. +The rules is that the url must be prefixed with the host name. +<source> + # Use www.foo.org as virtual host + /www.foo.org/myapp/*=myworker + # Use www.bar.org as virtual host + /www.bar.org/myapp/*=myworker + # Normal mapping + /mysecondapp/*=myworker +</source> +</p> +<p> +Note that /mysecondapp/* will be mapped to all virtual hosts present. +In case one needs to prevent the mappings to some particular virtual host then +the exclusion rule must be used +<source> + # Make sure the myapp is accessible by all virtual hosts + /myapp/*=myworker + # Disable mapping myapp for www.foo.org virtual host + !/www.foo.org/myapp/*=myworker +</source> +</p> +</subsection> + +<subsection name="Apache httpd"> +<br/> +<p> +For Apache you can define individual uriworkermap files per virtual host. +The directive JkMountFile can be used in the main server and in each virtual host. +If a virtual host does not use JkMountfile, but JkMountCopy is set to 'On', +then it inherits the JkMountFile from the main server. If you want all vhost to inherit +mounts from the main server, you can set JkMountCopy to 'All' in the main server. +</p> +</subsection> +</section> + +<section name="Dynamic reloading"> +<br/> +<p> +When a request is being processed, tomcat connectors check the file modification time +of the uriworkermap file. To keep the performance penalty low, this happens only, +if the last check happened at least n seconds ago. +</p> +<p> +For Apache you can configure the interval "n" using the directive JkMountFileReload, +for IIS you would use the attribute worker_mount_reload. +The default value is 60 seconds. A value of "0" turns off the reloading. +</p> +<p> +If the file changed, it gets reloaded completely. If there exist rules coming +from other sources than the uriworkermap file (e.g. the workers.properties mount +attribute or JkMount with Apache httpd), the new uriworkermap file gets dynamically +merged with these ones exactly like when you do a web server restart. +</p> +<p> +Until version 1.2.19 reloading behaved slightly differently: it continuously added +the full contents of the uriworkermap file to the rule mapping. The merging rules +were, that duplicated got eliminated and old rules could be disabled, by defining the +rule as disabled in the new file. Rules never got deleted. +</p> +</section> + +<section name="Status worker integration"> +<br/> +<p> +The configuration view of the status worker also shows the various mapping rules. +After each worker's configuration, the rules are listed, that forward to this worker. +The list contains four columns: +<ul> +<li> +the name of the virtual server +</li> +<li> +the URI pattern, prefixed with '-' for a disabled pattern and '!' for an exclusion pattern +</li> +<li> +the type of the rule: Exact or Wildchar +</li> +<li> +and the source of the rule definition: 'worker definition' for the workers.properties file (mount attribute), +'JkMount' for Apache httpd JkMount and it's relatives and finally 'uriworkermap' for the uriworkermap file. +</li> +</ul> +</p> +<p> +<b>Note: </b>The following restriction has been removed starting with version 1.2.26. +<br/> +For Apache httpd, there is an important subtlety: the request going to the status worker +gets executed in the context of some server (main or virtual). The status worker will only show the +mapping rules, that are defined for this server (main or virtual). +<br/> +Until version 1.2.25 the list contained three columns: +<ul> +<li> +the type of the rule: Exact or Wildchar, eventually prefixed with Disabled or Unmount (for exclusion rules) +</li> +<li> +the URI pattern +</li> +<li> +and the source of the rule definition: 'worker definition' for the workers.properties file (mount attribute), +'JkMount' for Apache httpd JkMount and it's relatives and finally 'uriworkermap' for the uriworkermap file. +</li> +</ul> +</p> +</section> + +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/workers.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/workers.xml new file mode 100644 index 00000000..543112cf --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/reference/workers.xml @@ -0,0 +1,1155 @@ +<?xml version="1.0"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="workers.html"> + + &project; + + <properties> + <author email="mturk@apache.org">Mladen Turk</author> + <title>workers.properties configuration</title> + </properties> + +<body> + +<section name="Introduction"> +<br/> +<p> +A <b>Tomcat worker</b> is a Tomcat instance that is waiting to execute servlets or any other content +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... +</p> +<p> +Tomcat workers are defined in a properties file dubbed <b>workers.properties</b> and this tutorial +explains how to work with it. +</p> +</section> + +<section name="Configuration File Basics"> +<br/> +<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> + +<subsection name="Format, Comments, Whitespace"> +<br/> +<p> +The lines in the file define properties. The general format is +</p> +<p><strong><name>=<value></strong></p> +<p> +</p> +Dots are used as part of the name to represent a configuration hierarchy. +<p> +Invalid directives will be logged during web server startup and prevent the web server +from working properly. Some directives have been deprecated. Although they will +still work, you should replace them by their +<a href="#Deprecated Worker Directives">successors</a>. +</p> +<p> +Some directives are allowed multiple times. This will be explicitly +noted in the tables below. +</p> +<p> +Whitespace at the beginning and the end of a property name or value gets ignored. +Comments can be placed in any line and start with a hash sign '#'. +Any line contents behind the hash sign get ignored. +</p> +</subsection> + +<subsection name="Global Properties"> +<br/> +<p> +These directives have global scope. +</p> +<directives> +<directive name="worker.list" default="ajp13" required="true"> +A comma separated list of workers names that the JK will use. When starting up, +the web server plugin will instantiate the workers whose name appears in the +worker.list property, these are also the workers to whom you can map requests. +<p> +This directive can be used multiple times. +</p> +</directive> +<directive name="worker.maintain" default="60" required="false"> +Worker connection pool maintain interval in seconds. If set to the positive +value JK will scan all connections for all workers specified in worker.list +directive and check if connections needs to be recycled. +<p> +Furthermore any load balancer does a global maintenance every worker.maintain +seconds. During global maintenance load counters are decayed and workers +in error are checked for recover_time. +</p> +<p> +This feature has been added in <b>jk 1.2.13</b>. +</p> +</directive> +</directives> +</subsection> + +<subsection name="Worker Properties"> +<br/> +<p> +Each worker configuration directive consists of three words separated by a dot: +</p> +<p><strong>worker.<worker name>.<directive>=<value></strong></p> +<p> +The first word is always <b>worker</b>. +The second word is the worker name you can choose. In the case of load-balancing, +the worker name has an additional meaning. Please consult the +<a href="../generic_howto/loadbalancers.html">Load Balancer HowTo</a>. +</p> +<warn> +The name of the worker can contain only the alphanumeric characters +<b>[a-z][A-Z][0-9][_\-]</b> and is case sensitive. +</warn> +</subsection> + +<subsection name="Variables, Environment Variables"> +<br/> +<p> +You can define and use variables in the workers.properties file. +To define a variable you use the syntax: +</p> +<p><strong><variable_name>=<value></strong></p> +<p> +Dots are allowed in the variable name, but you have to be careful +not to use variable names, that clash with standard directives. +Therefore variable names should never start with "worker.". +</p> +<p> +To use a variable, you can insert "$(variable_name)" at any place +on the value side of a property line. If a variable has not been +defined before its use, we will search the process environment for +a variable with the same name and use their value. +</p> +</subsection> + +<subsection name="Property Inheritance"> +<br/> +<p>Often one wants to use the same property values for various workers. +To reduce duplication of configuration lines and to ease the maintenance of +the file, you can inherit properties from one worker to another, or even +from a template to real workers. +</p> +<p> +The directive "reference" allows to copy configurations between workers +in a hierarchical way. If worker castor sets <b>worker.castor.reference=worker.pollux</b> +then it inherits all properties of <b>pollux</b>, except for the ones that +are explicitly set for <b>castor</b>. +</p> +<p> +Please note, that the value of the directive is not only the name of the referred worker, +but the complete prefix including "worker.". +</p> +<p> +To use a template worker simply define it like a real worker, but do not add it +to the "worker.list" or as a member to any load balancer. Such a template worker +does not have to contain mandatory directives. This approach is especially useful, +if one has a lot of balanced workers in a load balancer +and these workers share most of their properties. You can set all of these properties +in a template worker, e.g. using the prefix "worker.template1", and then simply +reference those common properties in all balanced workers. +</p> +<p> +References can be used to inherit properties over multiple hops in a hierarchical way. +</p> +<p> +This feature has been added in <b>jk 1.2.19</b>. +</p> +</subsection> +</section> + +<section name="List of All Worker Directives"> +<br/> +<subsection name="Mandatory Directives"> +<br/> +<p>Mandatory directives are the one that each worker <b>must</b> contain. Without them the worker will +be unavailable or will misbehave. Those directives will be marked with a <strong>strong</strong> font in the following tables. +</p> +<directives> +<directive name="type" default="ajp13" required="true"> +Type of the worker (can be one of ajp13, ajp14, jni, lb or status). The type of the worker +defines the directives that can be applied to the worker. +<p>AJP13 worker is the preferred worker type that JK uses for communication +between web server and Tomcat. This type of worker uses sockets as communication +channel. For detailed description of the AJP13 protocol stack browse to +<a href="../ajp/ajpv13a.html">AJPv13 protocol specification</a> +</p> +<warn>JNI workers have been deprecated. They will likely not work. Do not use them.</warn> +</directive> +</directives> +</subsection> + +<subsection name="Connection Directives"> +<br/> +<p>Connection directives defines the parameters needed to connect and maintain +the connections pool of persistent connections between JK and remote Tomcat. +</p> +<directives> + +<directive name="host" default="localhost" required="false"> +Host name or IP address of the backend Tomcat instance. The remote Tomcat must +support the ajp13 protocol stack. The host name can have a <b>port</b> number +embedded separated by the colon (':') character. +</directive> + +<directive name="port" default="8009" required="false"> +Port number of the remote Tomcat instance listening for defined protocol requests. +The default value depends on the worker type. For AJP13 workers the default port is +<b>8009</b>, while for AJP14 type of worker that value is <b>8011</b>. +</directive> + +<directive name="socket_timeout" default="0" required="false"> +Socket timeout in seconds used for the communication channel between JK and remote host. +If the remote host does not respond inside the timeout specified, JK will generate an error, +and retry again. If set to zero (default) JK will wait for an infinite amount of time +on all socket operations. +</directive> + +<directive name="socket_connect_timeout" default="socket_timeout*1000" required="false"> +Socket connect timeout in milliseconds used for the communication channel between JK and remote host. +If the remote host does not respond inside the timeout specified, JK will generate an error, +and retry again. +<p> +Note that <code>socket_timeout</code> is in seconds, and +<code>socket_connect_timeout</code> in milliseconds, +so in absolute terms the default <code>socket_connect_timeout</code> is +equal to <code>"socket_timeout</code>. +</p> +<p> +This feature has been added in <b>jk 1.2.27</b>. +</p> +</directive> + +<directive name="socket_keepalive" default="False" required="false"> +This directive should be used when you have a firewall between your webserver +and the Tomcat engine, who tend to drop inactive connections. This flag will tell the Operating System +to send <code>KEEP_ALIVE</code> messages on inactive connections (interval depend on global OS settings, +generally 120 minutes), and thus prevent the firewall to cut inactive connections. +To enable keepalive set this property value to <b>True</b>. +<p> +The problem with Firewall cutting inactive connections is that sometimes, neither webserver or Tomcat +have information about the cut and couldn't handle it. +</p> +</directive> + +<directive name="ping_mode" default="" required="false"> +This flag determines, under which conditions established +connections are probed to ensure they are still working. +The probe is done with an empty AJP13 packet (CPing) and +expects to receive an appropriate answer (CPong) within +some timeout. +<p> +The value of the flag can be any combination of the following +flags (multiple values are combined without any separators): +</p> +<p><b>C</b> (connect): If set, the connection will +be probed once after connecting to the backend. The timeout +can be set by <code>connect_timeout</code>. If it is not set, +the value of <code>ping_timeout</code> will be used instead. +</p> +<p><b>P</b> (prepost): If set, the connection will +be probed before sending each request to the backend. The timeout +can be set by <code>prepost_timeout</code>. If it is not set, +the value of <code>ping_timeout</code> will be used instead. +</p> +<p><b>I</b> (interval): If set, the connection will +be probed during the regular internal maintenance cycle, +but only if it is idle longer than +<code>connection_ping_interval</code>. The timeout +can be set by <code>ping_timeout</code>. +</p> +<p><b>A</b> If set, all of the above probes will be used. +</p> +<p> +This feature has been added in <b>jk 1.2.27</b>. Connect and +prepost probing were already available via <code>connect_timeout</code> +and <code>prepost_timeout</code> since version <b>jk 1.2.6</b>. +</p> +</directive> + +<directive name="ping_timeout" default="10000" required="false"> +Timeout in milliseconds used when waiting for the CPong answer of a +CPing connection probe. The activation of the probes is done via +<code>ping_mode</code>. The timeouts for <code>ping_mode</code> +connect and prepost can be overwritten individually via +<code>connect_timeout</code> and <code>prepost_timeout</code>. +<p> +For compatibility reasons, CPing/CPong is also used, whenever +<code>connect_timeout</code> or <code>prepost_timeout</code> are set, +even if <code>ping_mode</code> is empty. +</p> +<p> +This feature has been added in <b>jk 1.2.27</b>. +</p> +</directive> + +The usage depend on the <code>ping_mode</code> flags used. +directive <code>connection_ping_interval</code> was not set, the +value of <code>(ping_timeout/1000) * 10</code> will be used as +<code>connection_ping_interval</code> value. + +<directive name="connection_ping_interval" default="0 / (ping_timeout/1000)*10" required="false"> +When using interval connection probing, connections idle for longer than this +interval in seconds are probed by CPing packets whether they still work. +<p>Interval probing can be activated either by <code>ping_mode</code>, +or by setting <code>connection_ping_interval</code> to some value bigger +than zero. If you activate interval probing via <code>ping_mode</code>, +then the default value of <code>connection_ping_interval</code> is +<code>(ping_timeout/1000) * 10</code>. Note that <code>ping_timeout</code> +is in milliseconds, and <code>connection_ping_interval</code> in seconds, +so in absolute terms the default <code>connection_ping_interval</code> is +10 times <code>ping_timeout</code>. +</p> +<p> +This feature has been added in <b>jk 1.2.27</b>. +</p> +</directive> + +<directive name="connection_pool_size" default="see text" required="false"> +This defines the number of connections made to the AJP backend that +are maintained as a connection pool. +It will limit the number of those connection that each web server child +process can made. +<p> +Connection pool size property is only used for multi threaded +web servers such as Apache, IIS and Netscape/Sun. The connection_pool_size property +needs to reflect the number of requests one web server process should +be able to send to a backend in parallel. Usually this is the same as +the number of threads per web server process. JK will discover +this number for the Apache web server automatically and set the pool size to +this value. For IIS the default value is 250 (before version 1.2.20: 10), +for Netscape/Sun the default value is 1. +</p> +<p>We strongly recommend adjusting this value for IIS and the Netscape/Sun +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 activity without performance problems, and then add some +percentage depending on your growth rate. 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> +<warn>Do not use connection_pool_size with values higher then 1 on <b>Apache 2.x prefork</b> or <b>Apache 1.3.x</b>!</warn> +</directive> + +<directive name="connection_pool_minsize" default="(pool+1)/2" required="false"> +Minimum size of the connection pool that will be maintained. +<p> +Its default value is (connection_pool_size+1)/2. +</p> +<warn>Do not use connection_pool_size with values higher then 1 on <b>Apache 2.x prefork</b> or <b>Apache 1.3.x</b>!</warn> +<p> +This feature has been added in <b>jk 1.2.16</b>. +</p> +</directive> + +<directive name="connection_pool_timeout" default="0" required="false"> +Cache timeout property should be used with <b>connection_pool_minsize</b> to specify how many seconds JK should keep +an inactive socket in cache before closing it. This property should be used to reduce the number of threads +on the Tomcat web server. The default value zero disables the closing (infinite timeout). +<p> +Each child could open an ajp13 connection if it has to forward a request to Tomcat, creating +a new ajp13 thread on Tomcat side. +</p> +<p> +The problem is that after an ajp13 connection is created, the child won't drop it +until killed. And since the webserver will keep its childs/threads running +to handle high-load, even it the child/thread handle only static contents, you could +finish having many unused ajp13 threads on the Tomcat side. +</p> +<p> +You should keep this time interval in sync with the <b>connectionTimeout</b> attribute +of your AJP connector in Tomcat's server.xml. Note however, that the value +for mod_jk is given in seconds, the one in server.xml has to use milliseconds. +</p> +</directive> + +<directive name="connection_acquire_timeout" default="retries*retry_interval" required="false"> +Timeout the worker will wait for a free socket in cache before giving up. +<p> +Its default value is <b>retries * retry_interval</b>. +</p> +<p> +This feature has been added in <b>jk 1.2.27</b>. +</p> +</directive> + +<directive name="lbfactor" default="1" required="false"> +Only used for a member worker of a load balancer. +<p> +The integer number lbfactor (load-balancing factor) is +<i>how much we expect this worker to work</i>, or +<i>the worker's work quota</i>. Load balancing factor is compared with other workers +that makes the load balancer. For example if one worker has lb_factor 5 times higher then +other worker, then it will receive five times more requests. +</p> +</directive> + +</directives> + +</subsection> + +<subsection name="Load Balancing Directives"> +<br/> +<p>Load balancer is a virtual worker that does not really communicate with Tomcat workers. +Instead it is responsible for the management of several "real" workers. +The worker is supposed to be a load balancer if it's worker type is <b>lb</b>. +See worker's <b>type</b> directive. +</p> +<p>Loadbalancer directives define the parameters needed to create the workers that are +connecting to a remote cluster of backend Tomcat servers. Each cluster node has to +have a worker defined. +</p> +<p> +Load balancer 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 fall-backing 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. +</p> +<warn> +If you want to use session stickiness, you must set different jvmRoute attributes +in the Engine element in Tomcat's server.xml. Furthermore the names of the workers +which are managed by the balancer have to be equal to the jvmRoute of the Tomcat +instance they connect with. +</warn> +<p> +The restriction on the worker names can be lifted, if you use the route attribute for the workers. +</p> +<p> +The following table specifies properties that the lb worker can accept: +</p> + +<directives> +<directive name="balance_workers" default="" required="true"> +A comma separated list of workers that the load balancer +need to manage. +<p> +This directive can be used multiple times for the same load balancer. +</p> +<p> +This directive replaces old <b>balanced_workers</b> directive and +can be used only with mod_jk versions 1.2.7 and up. +</p> +<warn>As long as these workers should only be used via the load balancer worker, +there is no need to also put them into the <b>worker.list</b> property.</warn> +</directive> + +<directive name="sticky_session" default="True" required="false"> +Specifies whether requests with SESSION ID's should be routed back to the same +Tomcat worker. If sticky_session is set to <b>True</b> or <b>1</b> sessions are sticky, otherwise +sticky_session is set to <b>False</b>. Set sticky_session to <b>False</b> when Tomcat +is using a Session Manager which can persist session data across multiple +instances of Tomcat. +</directive> + +<directive name="sticky_session_force" default="False" required="false"> +Specifies whether requests with SESSION ID's for workers that are in error state +should be rejected. If sticky_session_force is set to <b>True</b> or <b>1</b> +and the worker that matches that SESSION ID is in error state, client will +receive 500 (Server Error). If set to <b>False</b> or <b>0</b> failover on +another worker will be issued with loosing client session. This directive is +used only when you set <b>sticky_session=True</b>. +<p> +This feature has been added in <b>jk 1.2.9</b>. +</p> +</directive> + +<directive name="method" default="Request" required="false"> +Specifies what method load balancer is using for electing the best worker. +Please note, that session stickiness and perfect load balancing are +conflicting targets, especially when the number +of sessions is small, or the usage of sessions is extremely varying +For huge numbers of sessions this usually is not a problem. +<p> +Some methods note, that they aggregate in a sliding time window. They add up +accesses, and on each run of the global maintain method, the load counters +get divided by 2. Usually this happens once a minute, depending on the +setting of worker.maintain. The value of the load counters can be inspected +using the status worker. +</p> +<p> +If method is set to <b>R[equest]</b> the balancer will use number of requests +to find the best worker. Accesses will be distributed according to the +lbfactor in a sliding time window. This is the default value and should be +working well for most applications. +</p> +<p> +If method is set to <b>S[ession]</b> the balancer will use number of sessions +to find the best worker. Accesses will be distributed according to the +lbfactor in a sliding time window. Because the balancer does not keep any state, +it actually does not know the number of sessions. Instead it counts each request +without a session cookie or URL encoding as a new session. This method will neither +know, when a session is being invalidated, nor will it correct its load numbers +according to session timeouts or worker failover. This method should be used, +if sessions are your limiting resource, e.g. when you only have limited memory +and your sessions need a lot of memory. +</p> +<p> +If set to <b>T[raffic]</b> the balancer will use +the network traffic between JK and Tomcat to find the best worker. +Accesses will be distributed according to the lbfactor in a sliding time window. +This method should be used, if network to and from the backends is your +limiting resource. +</p> +<p> +If set to <b>B[usyness]</b> the balancer will +pick the worker with the lowest current load, based on how many requests the +worker is currently serving. This number is divided by the workers lbfactor, +and the lowest value (least busy) worker is picked. This method is especially +interesting, if your request take a long time to process, like for a download +application. +</p> +<p> +This feature has been added in <b>jk 1.2.9</b>. +The Session method has been added in <b>jk 1.2.20</b>. +</p> +</directive> + +<directive name="lock" default="Optimistic" required="false"> +Specifies what lock method the load balancer will use for synchronising +shared memory runtime data. +If lock is set to <b>O[ptimistic]</b> balancer will not use shared memory lock +to find the best worker. If set to <b>P[essimistic]</b> balancer will use +shared memory lock. The balancer will work more accurately in case of +Pessimistic locking, but can slow down the average response time. +<p> +This feature has been added in <b>jk 1.2.13</b>. +</p> +</directive> + +<directive name="retries" default="2" required="false"> +<warn>This directive also exists for normal workers. +For those it has a <a href="#Advanced Worker Directives">different meaning</a>.</warn> +If the load balancer can not get a valid member worker or in case of failover, +it will try again a number of times given by <b>retries</b>. +Before each retry, it will make a pause define by <b>retry_interval</b> directive. +<p> +Until version <b>1.2.16</b> the default value was 3. +</p> +</directive> + +</directives> + +</subsection> + +<subsection name="Status Worker Directives"> +<br /> +<p> +The status worker does not communicate with Tomcat. +Instead it is responsible for the load balancer management. +</p> +<directives> +<directive name="css" default="" required="false"> +Specifies the url for cascading stylesheet to use. +</directive> +<directive name="read_only" default="False" required="false"> +A status worker with read_only=True will not allow any operations, +that change the runtime state or configuration of the other workers. +These are edit/update/reset/recover. +<p> +This feature has been added in <b>jk 1.2.20</b>. +</p> +</directive> +<directive name="user" default="" required="false"> +It is a list of users +which gets compared to the user name authenticated by the web server. +If the name is not contained in this list, access is denied. Per +default the list is empty and then access is allowed to anybody. +<p> +This directive can be used multiple times. +</p> +<p> +This feature has been added in <b>jk 1.2.20</b>. +</p> +</directive> +<directive name="user_case_insensitive" default="False" required="false"> +By default, the user names are matched case sensitively. You can set +user_case_insensitive=True to make the comparison case insensitive. +This may be especially useful on the Windows platform. +<p> +This feature has been added in <b>jk 1.2.21</b>. +</p> +</directive> +<directive name="good" default="a.o,a.n,a.b,a.r" required="false"> +For every load balancer worker, the status worker shows a summary +of the state of its members. There are three such states, +"good", "bad" and "degraded". +<p> +These states are determined depending on the activation of the members +(active, disabled, stopped) and their runtime state +(ok, n/a, busy, recovering, probing, forced recovery, error). +By default, members are assumed to be "good", if their activation +is "active" and their runtime state is not "error". +</p> +<p> +You can change this mapping, by assigning a list of values to the +attribute "good". Each value gives a possible match for the members, +and one match suffices. Each value is either a single character, or two +characters combined with a dot ".". The single characters are the +first characters in the words "active", "disabled", "stopped", +"ok", "na", "busy", "recovering", "error". The additional states "probing" +and "forced recovery" are always rated equivalent to "recovering". +If a value consists only +of a single character, then all members with this activation or runtime +state will be assumed good. A combination of an activation and a runtime +state concatenated with a dot "." does only apply to a member, that has +exactly this activation and state. +</p> +<p> +Members of a load balancer will first be matched against the state "bad", +if they don't match, the state "good" will be tried, and if they +still don't match, their state will be "degraded". +</p> +<p> +This directive can be used multiple times. +</p> +<p> +This feature has been added in <b>jk 1.2.20</b>. +</p> +</directive> +<directive name="bad" default="s,e" required="false"> +See: "good". +<p> +By default, members are assumed to be "bad", if their activation +is "stopped" or their runtime state is "error". +</p> +<p> +This directive can be used multiple times. +</p> +<p> +This feature has been added in <b>jk 1.2.20</b>. +</p> +</directive> +<directive name="prefix" default="worker" required="false"> +The prefix, which will be used by the status worker +when producing properties output (mime=prop). +Each property key will be prefixed by this value. +<p> +This feature has been added in <b>jk 1.2.20</b>. +</p> +</directive> +<directive name="ns" default="jk:" required="false"> +This directive can be used to customise the XML output from the +status worker. If set to <b>-</b> no namespace will be used. +<p> +This feature has been added in <b>jk 1.2.20</b>. +</p> +</directive> +<directive name="xmlns" default="" required="false"> +This directive can be used to customise the XML output from the +status worker. If set to <b>-</b> no xmlns will be used. +<p> +Default value is set to xmlns:jk="http://tomcat.apache.org" +</p> +<p> +This feature has been added in <b>jk 1.2.20</b>. +</p> +</directive> +<directive name="doctype" default="" required="false"> +This directive can be used to customise the XML output from the +status worker. This value will be inserted to the output xml +after the xml header. +<p> +This feature has been added in <b>jk 1.2.20</b>. +</p> +</directive> + +</directives> +</subsection> + +<subsection name="Advanced Worker Directives"> +<br /> +<p> +This table lists more advanced configuration options. Most of them only apply to +some types of workers. We use the abbreviations <b>AJP</b> for ajp13/ajp14 workers +used directly via the workers.list, <b>LB</b> for load balancer workers, +and <b>SUB</b> for the workers used indirectly in a load balancer worker +as a sub worker or member. +</p> +<advanceddirectives> +<directive name="connect_timeout" workers="AJP,SUB" default="0" required="false"> +Connect timeout property told webserver to send a PING request on ajp13 connection after +connection is established. The parameter is the delay in milliseconds to wait for the PONG reply. +The default value zero disables the timeout (infinite timeout). +<p> +This features has been added in <b>jk 1.2.6</b> to avoid problem with hung Tomcat's and require ajp13 +ping/pong support which has been implemented on Tomcat <b>3.3.2+, 4.1.28+ and 5.0.13+</b>. +Disabled by default. +</p> +</directive> + +<directive name="prepost_timeout" workers="AJP,SUB" default="0" required="false"> +Prepost timeout property told webserver to send a PING request on ajp13 connection before +forwarding to it a request. The parameter is the delay in milliseconds to wait for the PONG reply. +The default value zero disables the timeout (infinite timeout). +<p> +This features has been added in <b>jk 1.2.6</b> to avoid problem with hung Tomcat's and require ajp13 +ping/pong support which has been implemented on <b>Tomcat 3.3.2+, 4.1.28+ and 5.0.13+</b>. +Disabled by default. +</p> +</directive> + +<directive name="reply_timeout" workers="AJP,SUB" default="0" required="false"> +The parameter is the number of milliseconds to wait for success during a read event. +So this is not a timeout for the complete answer time of a request, but only +for the maximum time between two packets received from Tomcat. Usually the longest +pause is between sending the request and getting the first packet of the response. +<p> +If the timeout passes without any data received from Tomcat, the webserver will +no longer wait for the rest of the response and send an error to the client (browser). +Usually this does not mean, that the request is also aborted on the Tomcat backend. +If the worker is a member of a load balancer, the load balancer might place the +worker into an error state and retry the request on another member. +See also <b>max_reply_timeouts</b>, <b>retries</b> and <b>recovery_options</b>. +</p> +<p> +By default (value zero) the webserver will wait forever which could be an issue for you. +If you set a reply_timeout, adjust it carefully if you have long running servlets. +</p> +<p> +The reply_timeout can be overwritten using the Apache httpd environment variable +JK_REPLY_TIMEOUT. +</p> +<p> +This features has been added in <b>jk 1.2.6</b> to avoid problem with hung Tomcat's and works on all +servlet engines supporting ajp13. The variable JK_REPLY_TIMEOUT has been added in version <b>1.2.27</b>. +</p> +</directive> + +<directive name="retries" workers="AJP,SUB" default="2" required="false"> +<warn>This directive also exists for load balancer workers. +For those it has a <a href="#Load Balancing Directives">different meaning</a>.</warn> +The maximum number of times that the worker will send a request to Tomcat +in case of a communication error. Each retry will be done over another +connection. The first time already gets counted, so retries=2 means +one retry after error. Before a retry, the worker waits for a configurable +sleeping time. +<p> +See also the attribute <b>recovery_options</b> for a more fine-grained control +of retries and <b>retry_interval</b> for the sleep time configuration. +</p> +<p> +Until version <b>1.2.16</b> the default value was 3. +</p> +</directive> + +<directive name="retry_interval" workers="AJP,SUB" default="100" required="false"> +The amount of time in milliseconds the worker sleeps before doing any retry. +<p> +This features has been added in <b>jk 1.2.27</b>. +</p> +</directive> + +<directive name="recovery_options" workers="AJP,SUB" default="0" required="false"> +Recovery options influence, how we should handle retries, +in case we detect a problem with Tomcat. +How often we will retry is controlled by the attribute <b>retries</b>. +<p> +This attribute is a bit mask. The following bits are allowed:<br/> +1: don't recover if Tomcat failed after getting the request<br/> +2: don't recover if Tomcat failed after sending the headers to client<br/> +4: close the connection to Tomcat, if we detect an error when writing back +the answer to the client (browser)<br/> +8: always recover requests for HTTP method HEAD (even if Bits 1 or 2 are set)<br/> +16: always recover requests for HTTP method GET (even if Bits 1 or 2 are set)<br/> +</p> +<p> +This features has been added in <b>jk 1.2.6</b>. +Option 4 has been added in version <b>1.2.16</b>, +options 8 and 16 in version <b>1.2.24</b>. +</p> +</directive> + +<directive name="fail_on_status" workers="AJP,SUB" default="0" required="false"> +Set this value to the HTTP status code that will cause a worker to fail +if returned from Servlet container. Use this directive to deal with +cases when the servlet container can temporary return non-200 responses +for a short amount of time, e.g during redeployment. +<p> +The error page, headers and status codes of the original response will not be send back +to the client. Instead the request will result in a 503 response. +If the worker is a member of a load balancer, the member will +be put into an error state. Request failover and worker recovery will be handled +with the usual load balancer procedures. +</p> +<p> +This feature has been added in <b>jk 1.2.20</b>. +</p> +<p> +Starting with <b>jk 1.2.22</b> it is possible to define multiple +status codes separated by space or comma characters. +For example: <code>worker.xxx.fail_on_status=500,503</code> +</p> +<p> +Starting with <b>jk 1.2.25</b> you can also tell the load +balancer to not put a member into an error state, if a +response returned with one of the status codes in +fail_on_status. This feature gets enabled, by putting a minus sign in +front of those status codes. +For example: <code>worker.xxx.fail_on_status=-404,-500,503</code> +</p> +</directive> + +<directive name="max_packet_size" workers="AJP,SUB" default="8192" required="false"> +This attribute sets the maximal AJP packet size in Bytes. +The maximum value is 65536. If you change it from the default, +you <b>must</b> also change the packetSize attribute of your AJP +connector on the Tomcat side! The attribute packetSize is only available +in Tomcat 5.5.20+ and 6.0.2+. +<p> +Normally it is not necessary to change the maximum packet size. Problems +with the default value have been reported when sending certificates or +certificate chains. +</p> +<p> +This feature has been added in <b>jk 1.2.19</b>. +</p> +</directive> + +<directive name="mount" workers="AJP,LB" default="" required="false"> +Space delimited list of uri maps the worker should handle. It is only used, +if the worker is included in worker.list. +<p> +This directive can be used multiple times for the same worker. +</p> +</directive> + +<directive name="secret" workers="AJP,LB,SUB" default="" required="false"> +You can set a secret keyword on the Tomcat AJP Connector. Then only requests +from workers with the same secret keyword will be accepted. +<p> +Use <b>request.secret="secret key word"</b> in your Tomcat AJP Connector configuration. +</p> +<p> +If you set a secret on a load balancer, all its members will inherit this secret. +</p> +<p> +This feature has been added in <b>jk 1.2.12</b>. +</p> +</directive> + +<directive name="max_reply_timeouts" workers="LB" default="0" required="false"> +If you use a <b>reply_timeout</b> for the members of a load balancer worker, +and you want to tolerate a few requests taking longer than reply_timeout, +you can set this attribute to some positive value. +<p> +Long running requests will still time out after reply_timeout milliseconds waiting for +data, but the corresponding member worker will only be put into an error state, +if more than <b>max_reply_timeouts</b> requests have timed out. +More precisely, the counter for those bad requests will be divided by two, +whenever the load balancer does its internal maintenance (by default every 60 +seconds). +</p> +<p> +This features has been added in <b>jk 1.2.24</b> to make <b>reply_timeout</b> less +sensitive for sporadic long running requests. +</p> +</directive> + +<directive name="recover_time" workers="LB" default="60" required="false"> +The recover time is the time in seconds the load balancer will not try +to use a worker, after it went into error state. Only after this time has passed, +a worker in error state will be marked as in recovering, so that it will be +tried for new requests. +<p> +This interval is not checked every time a request is being processed. +Instead it is being checked during global maintenance. The time between two +runs of global maintenance is controlled by worker.maintain. +</p> +<p> +Do not set recover_time to a very short time unless you understand the implications. +Every recovery attempt for a worker in error is done by a real request! +</p> +</directive> + +<directive name="error_escalation_time" workers="LB" default="recover_time / 2" required="false"> +Setting a member of a load balancer into an error state is quite serious. E.g. +it means that if you need stickyness, all access to the sessions of the +respective node is blocked. +<p> +Some types of error detection do not provide a precise information, whether +a node is completely broken or not. In those cases an LB will not immediately +put the node into the error state. Only when there have been no successful +responses for <b>error_escalation_time</b> seconds after such an error, +will the node be put into error state. +</p> +<p> +This features has been added in <b>jk 1.2.28</b>. +</p> +</directive> + +<directive name="activation" workers="SUB" default="Active" required="false"> +Using this directive, a balanced worker of a load balancer +can be configured as disabled or stopped. A disabled worker only gets +requests, which belong to sessions for that worker. A stopped +worker does not get any requests. Users of a stopped worker will +loose their sessions, unless session replication via clustering is used. +<p> +Use <b>d</b> or <b>D</b> to disable and <b>s</b> or <b>S</b> to stop. +If this directive is not present the deprecated directives +"disabled" or "stopped" are used. +</p> +<p> +This flag can be changed at runtime using status worker. +</p> +<p> +This feature has been added in <b>jk 1.2.19</b>. +</p> +</directive> + +<directive name="route" workers="SUB" default="worker name" required="false"> +Normally the name of a balanced worker in a load balancer is equal to the jvmRoute +of the corresponding Tomcat instance. If you want to include a worker corresponding +to a Tomcat instance into several load balancers with different balancing configuration +(e.g. disabled, stopped) you can use this attribute. +<p> +Define a separate worker per lb and per Tomcat instance with an arbitrary worker name and +set the route attribute of the worker equal to the jvmRoute of the target Tomcat instance. +</p> +<p> +If this attribute is left empty, the name of the worker will be used. +</p> +<p> +This attribute can be changed at runtime using status worker. +</p> +<p> +If the route name contains a period, the part before the first period will be +used as domain name, unless domain is set explicitly. +</p> +<p> +This feature has been added in <b>jk 1.2.16</b>.<br/> +The automatic domain rule has been added in <b>jk 1.2.20</b>.<br/> +The attribute has been renamed from jvm_route to route in <b>jk 1.2.20</b>. +</p> +</directive> + +<directive name="distance" workers="SUB" default="0" required="false"> +An integer number to express preferences between +the balanced workers of an lb worker. +A load balancer will never choose some balanced worker +in case there is another usable worker with lower distance. +<p> +Only in case all workers below a given distance are in error, disabled or stopped, +workers of a larger distance are eligible for balancing. +</p> +<p> +This feature has been added in <b>jk 1.2.16</b>. +</p> +</directive> + +<directive name="domain" workers="SUB" default="" required="false"> +Domain directive can be used only when the worker is a member of the load balancer. +Workers that share the same domain name are treated as single worker. If sticky_session +is used, then the domain name is used as session route. +<p> +This directive is used for large system with more then 6 Tomcats, to be able +to cluster the Tomcats in two groups and thus lowering the session replication +transfer between them. +</p> +<p> +This feature has been added in <b>jk 1.2.8</b>. +</p> +</directive> + +<directive name="redirect" workers="SUB" default="" required="false"> +Set to the name of the preferred failover worker. If worker matching +SESSION ID is in error state then the redirect worker will be used instead. +It will be used even if being disabled, thus offering hot standby. +<p> +If you explicitly set a route via the "route" attribute, you must set "redirect" +to this route of the preferred failover worker and not to its name. +</p> +<p> +This feature has been added in <b>jk 1.2.9</b>. +</p> +</directive> + +<directive name="session_cookie" workers="LB" default="JSESSIONID" required="false"> +The name of the cookie that contains the routing identifier needed for session stickyness. +The routing identifier is everything after a "." character in the value of the cookie. +<p> +This feature has been added in <b>jk 1.2.27</b>. +</p> +</directive> + +<directive name="session_path" workers="LB" default=";jsessionid" required="false"> +The name of the path parameter that contains the routing identifier needed for +session stickyness. The routing identifier is everything after a "." character in the value +of the path parameter. +<p> +This feature has been added in <b>jk 1.2.27</b>. +</p> +</directive> + +</advanceddirectives> +</subsection> + +<subsection name="Deprecated Worker Directives"> +<br/> +<p>The following directives have been deprecated in the past. We include their documentation +in case you need to use an older version of mod_jk. We urge you to update and not use +them any more. Please migrate your existing configurations. +</p> +<deprecations> +<directive name="cachesize" successor="connection_pool_size" default="see text" required="false"> +<warn>This directive has been deprecated since 1.2.16.</warn> +Cachesize defines the number of connections made to the AJP backend that +are maintained as a connection pool. +It will limit the number of those connection that each web server child +process can make. +<p> +Cachesize property is used only for multi threaded +web servers such as Apache 2.0 (worker), IIS and Netscape. The cachesize property +should reflect the number of threads per child process. JK will discover +the number of threads per child process on Apache 2 web server with worker-mpm and set +its default value to match the ThreadsPerChild Apache directive. For IIS the default +value is 10. For other web servers than Apache or IIS this value has to be set manually. +</p> +<warn>Do not use cachesize with values higher then 1 on <b>Apache 2.x prefork</b> or <b>Apache 1.3.x</b>!</warn> +</directive> + +<directive name="cache_timeout" successor="connection_pool_timeout" default="0" required="false"> +<warn>This directive has been deprecated since 1.2.16.</warn> +Cache timeout property should be used with <b>cachesize</b> to specify how to time JK should keep +an open socket in cache before closing it. This property should be used to reduce the number of threads +on the Tomcat web server. +<p> +Each child could open an ajp13 connection if it have to forward a request to Tomcat, creating +a new ajp13 thread on Tomcat side. +</p> +<p> +The problem is that after an ajp13 connection is created, the child won't drop it +until killed. And since the webserver will keep its childs/threads running +to handle high-load, even it the child/thread handle only static contents, you could +finish having many unused ajp13 threads on the Tomcat side. +</p> +</directive> + +<directive name="recycle_timeout" successor="connection_pool_timeout" default="0" required="false"> +<warn>This directive has been deprecated since 1.2.16.</warn> +The number of seconds that told webserver to cut an ajp13 connection after some time of +inactivity. When choosing an endpoint for a request and the assigned socket is open, it will be +closed if it was not used for the configured time. +It's a good way to ensure that there won't too old threads living on Tomcat side, +with the extra cost you need to reopen the socket next time a request be forwarded. +This property is very similar to <b>cache_timeout</b> but works also in non-cache mode. +If set to value zero (default) no recycle will took place. +</directive> + +<directive name="balanced_workers" successor="balance_workers" default="" required="true"> +<warn>This directive has been deprecated since 1.2.7.</warn> +A comma separated list of workers that the load balancer +need to manage. +</directive> + +<directive name="disabled" successor="activation" default="False" required="false"> +<warn>This directive has been deprecated since 1.2.19.</warn> +If set to <b>True</b> or <b>1</b> the worker will be disabled if member +of load balancer. This flag can be changed at runtime using status worker. +<p> +This feature has been added in <b>jk 1.2.9</b>. +</p> +</directive> + +<directive name="stopped" successor="activation" default="False" required="false"> +<warn>This directive has been deprecated since 1.2.19.</warn> +If set to <b>True</b> or <b>1</b> the worker will be stopped if member +of load balancer. The flag is needed for stop complete traffic of a sticky session +worker. It is only useful, when you have a cluster that replicated the sessions. +This flag can be changed at runtime using status worker. +<p> +This feature has been added in <b>jk 1.2.11</b>. +</p> +</directive> + +<directive name="jvm_route" successor="route" default="worker name" required="false"> +<warn>This directive has been deprecated since 1.2.20.</warn> +Normally the name of a balanced worker in a load balancer is equal to the jvmRoute +of the corresponding Tomcat instance. If you want to include a worker corresponding +to a Tomcat instance into several load balancers with different balancing configuration +(e.g. disabled, stopped) you can use this attribute. +<p> +Define a separate worker per lb and per Tomcat instance with an arbitrary worker name and +set the jvm_route attribute of the worker equal to the jvmRoute of the target Tomcat instance. +</p> +<p> +If this attribute is left empty, the name of the worker will be used. +</p> +<p> +This attribute can be changed at runtime using status worker. +</p> +<p> +This feature has been added in <b>jk 1.2.16</b>. +</p> +</directive> + +</deprecations> +</subsection> + +</section> + +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/style.css b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/style.css new file mode 100644 index 00000000..ecd0eb81 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/style.css @@ -0,0 +1,73 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +div.screen { + margin: 10px 0px 10px 20px; + font-size: smaller; + color: #ffffff; +} +div.example { + background-color: #e5ecf3; + color: #000; + padding: 0.5em; + margin: 1em 2em 1em 1em; +} +pre { + font-family: "Courier New", Courier, monospace; + font-weight: normal; + font-style: normal; + font-size: smaller; +} +em.screen { + font-weight: normal; + font-style: normal; + color: #c0c0c0; +} +p.screen { + background-color: #000000; + border-style: none; + color: #c0c0c0; + margin-left: 10px; + margin-right: 0px; + text-align: left; +} +b.screen { + font-weight: normal; + font-style: normal; + color: #c0c0c0; +} +code.screen { + background-color: #000000; + border-style: none; + color: #c0c0c0; + margin-left: 10px; + margin-right: 0px; + text-align: left; +} +b.code { + font-weight: normal; + font-style: normal; + color: #023264; +} +p.todo { + background-color: #ffffff; + border-style: none; + color: #000000; + margin-left: 20px; + margin-right: 10px; + text-align: justify; + font-size: smaller; +} diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/style.xsl b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/style.xsl new file mode 100644 index 00000000..392396f5 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/style.xsl @@ -0,0 +1,710 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<!-- Content Stylesheet for "tomcat-docs" Documentation --> + +<!-- $Id: style.xsl 1054603 2011-01-03 13:03:43Z rjung $ --> + +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + version="1.0"> + + + <!-- Output method --> + <xsl:output method="html" + encoding="iso-8859-1" + indent="no"/> + + + <!-- Defined parameters (overrideable) --> + <xsl:param name="home-name" select="'Apache Tomcat'"/> + <xsl:param name="home-href" select="'http://tomcat.apache.org/'"/> + <xsl:param name="home-logo" select="'/images/tomcat.gif'"/> + <xsl:param name="printer-logo" select="'/images/printer.gif'"/> + <xsl:param name="relative-path" select="'.'"/> + <xsl:param name="void-image" select="'/images/void.gif'"/> + <xsl:param name="project-menu" select="'menu'"/> + <xsl:param name="standalone" select="''"/> + <xsl:param name="buglink" select="'http://issues.apache.org/bugzilla/show_bug.cgi?id='"/> + + <!-- Defined variables (non-overrideable) --> + <xsl:variable name="body-bg" select="'#ffffff'"/> + <xsl:variable name="body-fg" select="'#000000'"/> + <xsl:variable name="body-link" select="'#525D76'"/> + <xsl:variable name="banner-bg" select="'#525D76'"/> + <xsl:variable name="banner-fg" select="'#ffffff'"/> + <xsl:variable name="sub-banner-bg" select="'#828DA6'"/> + <xsl:variable name="sub-banner-fg" select="'#ffffff'"/> + <xsl:variable name="source-color" select="'#023264'"/> + <xsl:variable name="attributes-color" select="'#023264'"/> + <xsl:variable name="table-th-bg" select="'#039acc'"/> + <xsl:variable name="table-td-bg" select="'#a0ddf0'"/> + + <!-- Process an entire document into an HTML page --> + <xsl:template match="document"> + <html> + <head> + <title><xsl:value-of select="project/title"/> - <xsl:value-of select="properties/title"/></title> + <xsl:for-each select="properties/author"> + <xsl:variable name="name"> + <xsl:value-of select="."/> + </xsl:variable> + <xsl:variable name="email"> + <xsl:value-of select="@email"/> + </xsl:variable> + <meta name="author" value="{$name}"/> + <meta name="email" value="{$email}"/> + </xsl:for-each> + <link href="{$relative-path}/style.css" type="text/css" rel="stylesheet"/> + </head> + + <body bgcolor="{$body-bg}" text="{$body-fg}" link="{$body-link}" + alink="{$body-link}" vlink="{$body-link}"> + + <table border="0" width="100%" cellspacing="4"> + + <xsl:comment>PAGE HEADER</xsl:comment> + <tr><td colspan="2"> + + <xsl:comment>TOMCAT LOGO</xsl:comment> + <xsl:variable name="alt"> + <xsl:value-of select="$home-name"/> + </xsl:variable> + <xsl:variable name="href"> + <xsl:value-of select="$home-href"/> + </xsl:variable> + <xsl:variable name="src"> + <xsl:value-of select="$relative-path"/><xsl:value-of select="$home-logo"/> + </xsl:variable> + <a href="{$href}"> + <img src="{$src}" align="left" alt="{$alt}" border="0"/> + </a> + <xsl:if test="project/logo"> + <xsl:variable name="alt"> + <xsl:value-of select="project/logo"/> + </xsl:variable> + <xsl:variable name="home"> + <xsl:value-of select="project/@href"/> + </xsl:variable> + <xsl:variable name="src"> + <xsl:value-of select="$relative-path"/><xsl:value-of select="project/logo/@href"/> + </xsl:variable> + + <xsl:comment>APACHE LOGO</xsl:comment> + <a href="http://www.apache.org/"> + <img src="http://www.apache.org/images/asf-logo.gif" + align="right" alt="Apache Logo" border="0"/> + </a> + + </xsl:if> + + </td></tr> + + <xsl:comment>HEADER SEPARATOR</xsl:comment> + <tr> + <td colspan="2"> + <hr noshade="noshade" size="1"/> + </td> + </tr> + + <tr> + + <!-- Don't generate a menu if styling printer friendly docs --> + <xsl:if test="$project-menu = 'menu'"> + <xsl:comment>LEFT SIDE NAVIGATION</xsl:comment> + <td width="20%" valign="top" nowrap="true"> + <xsl:apply-templates select="project/body/menu"/> + </td> + </xsl:if> + + <xsl:comment>RIGHT SIDE MAIN BODY</xsl:comment> + <td width="80%" valign="top" align="left"> + <table border="0" width="100%" cellspacing="4"> + <tr> + <td align="left" valign="top"> + <h1><xsl:value-of select="project/title"/></h1> + <h2><xsl:value-of select="properties/title"/></h2> + </td> + <td align="right" valign="top" nowrap="true"> + <!-- Add the printer friendly link for docs with a menu --> + <xsl:if test="$project-menu = 'menu'"> + <xsl:variable name="src"> + <xsl:value-of select="$relative-path"/><xsl:value-of select="$printer-logo"/> + </xsl:variable> + <xsl:variable name="url"> + <xsl:value-of select="/document/@url"/> + </xsl:variable> + <small> + <a href="printer/{$url}"> + <img src="{$src}" border="0" alt="Printer Friendly Version"/> + <br />print-friendly<br />version + </a> + </small> + </xsl:if> + <xsl:if test="$project-menu != 'menu'"> + <xsl:variable name="void"> + <xsl:value-of select="$relative-path"/><xsl:value-of select="$void-image"/> + </xsl:variable> + <img src="{$void}" width="1" height="1" vspace="0" hspace="0" border="0"/> + </xsl:if> + </td> + </tr> + </table> + <xsl:apply-templates select="body/section"/> + </td> + + </tr> + + <xsl:comment>FOOTER SEPARATOR</xsl:comment> + <tr> + <td colspan="2"> + <hr noshade="noshade" size="1"/> + </td> + </tr> + + <xsl:comment>PAGE FOOTER</xsl:comment> + <tr><td colspan="2"> + <div align="center"><font color="{$body-link}" size="-1"><em> + Copyright © 1999-2011, Apache Software Foundation + </em></font></div> + </td></tr> + + </table> + </body> + </html> + + </xsl:template> + + + <!-- Process a menu for the navigation bar --> + <xsl:template match="menu"> + <p><strong><xsl:value-of select="@name"/></strong></p> + <ul> + <xsl:apply-templates select="item"/> + </ul> + </xsl:template> + + + <!-- Process a menu item for the navigation bar --> + <xsl:template match="item"> + <xsl:variable name="href"> + <xsl:value-of select="@href"/> + </xsl:variable> + <li><a href="{$href}"><xsl:value-of select="@name"/></a></li> + </xsl:template> + + + <!-- Process a documentation section --> + <xsl:template match="section"> + <xsl:variable name="name"> + <xsl:value-of select="@name"/> + </xsl:variable> + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <!-- Section heading --> + <tr><td bgcolor="{$banner-bg}"> + <font color="{$banner-fg}" face="arial,helvetica.sanserif"> + <a name="{$name}"> + <strong><xsl:value-of select="@name"/></strong></a></font> + </td></tr> + <!-- Section body --> + <tr><td><blockquote> + <xsl:apply-templates/> + </blockquote></td></tr> + </table> + </xsl:template> + + + <!-- Process a documentation subsection --> + <xsl:template match="subsection"> + <xsl:variable name="name"> + <xsl:value-of select="@name"/> + </xsl:variable> + <table border="0" cellspacing="0" cellpadding="2" width="100%"> + <!-- Subsection heading --> + <tr><td bgcolor="{$sub-banner-bg}"> + <font color="{$sub-banner-fg}" face="arial,helvetica.sanserif"> + <a name="{$name}"> + <strong><xsl:value-of select="@name"/></strong></a></font> + </td></tr> + <!-- Subsection body --> + <tr><td><blockquote> + <xsl:apply-templates/> + </blockquote></td></tr> + </table> + </xsl:template> + + + <!-- Process a source code example --> + <xsl:template match="source"> + <xsl:variable name="void"> + <xsl:value-of select="$relative-path"/><xsl:value-of select="$void-image"/> + </xsl:variable> + <div class="example"><pre> + <xsl:value-of select="."/> + </pre> + </div> + </xsl:template> + + + <!-- Process an attributes list with nested attribute elements --> + <xsl:template match="attributes"> + <table border="1" cellpadding="5"> + <tr> + <th width="20%" bgcolor="{$attributes-color}"> + <xsl:choose> + <xsl:when test="@name != ''"> + <font color="#ffffff"><xsl:value-of select="@name"/></font> + </xsl:when> + <xsl:otherwise> + <font color="#ffffff">Attribute</font> + </xsl:otherwise> + </xsl:choose> + </th> + <th width="80%" bgcolor="{$attributes-color}"> + <font color="#ffffff">Description</font> + </th> + </tr> + <xsl:for-each select="attribute"> + <tr> + <td align="left" valign="center"> + <xsl:if test="@required = 'true'"> + <strong><code><xsl:value-of select="@name"/></code></strong> + </xsl:if> + <xsl:if test="@required != 'true'"> + <code><xsl:value-of select="@name"/></code> + </xsl:if> + </td> + <td align="left" valign="center"> + <xsl:apply-templates/> + </td> + </tr> + </xsl:for-each> + </table> + </xsl:template> + + <!-- Process a directives list with nested directive elements --> + <xsl:template match="directives"> + <table border="1" cellpadding="5"> + <tr> + <th width="15%" bgcolor="{$attributes-color}"> + <font color="#ffffff">Directive</font> + </th> + <th width="10%" bgcolor="{$attributes-color}"> + <font color="#ffffff">Default</font> + </th> + <th width="75%" bgcolor="{$attributes-color}"> + <font color="#ffffff">Description</font> + </th> + </tr> + <xsl:for-each select="directive"> + <tr> + <td align="left" valign="center"> + <xsl:if test="@required = 'true'"> + <strong><code><xsl:value-of select="@name"/></code></strong> + </xsl:if> + <xsl:if test="@required != 'true'"> + <code><xsl:value-of select="@name"/></code> + </xsl:if> + </td> + <xsl:choose> + <xsl:when test="@default != ''"> + <td align="center" valign="center"> + <code><xsl:value-of select="@default"/></code> + </td> + </xsl:when> + <xsl:otherwise> + <td align="center" valign="center"> + <code>-</code> + </td> + </xsl:otherwise> + </xsl:choose> + <td align="left" valign="center"> + <xsl:apply-templates/> + </td> + </tr> + </xsl:for-each> + </table> + </xsl:template> + + <!-- Process an advanced directives list with nested directive elements --> + <xsl:template match="advanceddirectives"> + <table border="1" cellpadding="5"> + <tr> + <th width="10%" bgcolor="{$attributes-color}"> + <font color="#ffffff">Directive</font> + </th> + <th width="10%" bgcolor="{$attributes-color}"> + <font color="#ffffff">Worker Type</font> + </th> + <th width="8%" bgcolor="{$attributes-color}"> + <font color="#ffffff">Default</font> + </th> + <th width="72%" bgcolor="{$attributes-color}"> + <font color="#ffffff">Description</font> + </th> + </tr> + <xsl:for-each select="directive"> + <tr> + <td align="left" valign="center"> + <xsl:if test="@required = 'true'"> + <strong><code><xsl:value-of select="@name"/></code></strong> + </xsl:if> + <xsl:if test="@required != 'true'"> + <code><xsl:value-of select="@name"/></code> + </xsl:if> + </td> + <xsl:choose> + <xsl:when test="@workers != ''"> + <td align="left" valign="center"> + <code><xsl:value-of select="@workers"/></code> + </td> + </xsl:when> + <xsl:otherwise> + <td align="left" valign="center"> + <code>?</code> + </td> + </xsl:otherwise> + </xsl:choose> + <xsl:choose> + <xsl:when test="@default != ''"> + <td align="center" valign="center"> + <code><xsl:value-of select="@default"/></code> + </td> + </xsl:when> + <xsl:otherwise> + <td align="center" valign="center"> + <code>-</code> + </td> + </xsl:otherwise> + </xsl:choose> + <td align="left" valign="center"> + <xsl:apply-templates/> + </td> + </tr> + </xsl:for-each> + </table> + </xsl:template> + + <!-- Process a deprecations list with nested directive elements --> + <xsl:template match="deprecations"> + <table border="1" cellpadding="5"> + <tr> + <th width="15%" bgcolor="{$attributes-color}"> + <font color="#ffffff">Directive</font> + </th> + <th width="15%" bgcolor="{$attributes-color}"> + <font color="#ffffff">Successor</font> + </th> + <th width="10%" bgcolor="{$attributes-color}"> + <font color="#ffffff">Default</font> + </th> + <th width="60%" bgcolor="{$attributes-color}"> + <font color="#ffffff">Description</font> + </th> + </tr> + <xsl:for-each select="directive"> + <tr> + <td align="left" valign="center"> + <code><xsl:value-of select="@name"/></code> + </td> + <xsl:choose> + <xsl:when test="@successor != ''"> + <td align="center" valign="center"> + <code><xsl:value-of select="@successor"/></code> + </td> + </xsl:when> + <xsl:otherwise> + <td align="center" valign="center"> + <code>-</code> + </td> + </xsl:otherwise> + </xsl:choose> + <xsl:choose> + <xsl:when test="@default != ''"> + <td align="center" valign="center"> + <code><xsl:value-of select="@default"/></code> + </td> + </xsl:when> + <xsl:otherwise> + <td align="center" valign="center"> + <code>-</code> + </td> + </xsl:otherwise> + </xsl:choose> + <td align="left" valign="center"> + <xsl:apply-templates/> + </td> + </tr> + </xsl:for-each> + </table> + </xsl:template> + + <!-- Fix relative links in printer friendly versions of the docs --> + <xsl:template match="a"> + <xsl:variable name="href" select="@href"/> + <xsl:choose> + <xsl:when test="$standalone = 'standalone'"> + <xsl:apply-templates/> + </xsl:when> + <xsl:when test="$project-menu != 'menu' and starts-with(@href,'../')"> + <a href="../{$href}"><xsl:apply-templates/></a> + </xsl:when> + <xsl:when test="$project-menu != 'menu' and starts-with(@href,'./') and contains(substring(@href,3),'/')"> + <a href=".{$href}"><xsl:apply-templates/></a> + </xsl:when> + <xsl:when test="$project-menu != 'menu' and not(contains(@href,'//')) and not(starts-with(@href,'/')) and not(starts-with(@href,'#')) and contains(@href,'/')"> + <a href="../{$href}"><xsl:apply-templates/></a> + </xsl:when> + <xsl:when test="$href != ''"> + <a href="{$href}"><xsl:apply-templates/></a> + </xsl:when> + <xsl:otherwise> + <xsl:variable name="name" select="@name"/> + <a name="{$name}"><xsl:apply-templates/></a> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + + <!-- Warning --> + <xsl:template match="warn"> + <p> + <font color="#ff0000"> + <xsl:apply-templates/> + </font> + </p> + </xsl:template> + + <!-- Changelog related tags --> + <xsl:template match="changelog"> + <table border="0" cellpadding="2" cellspacing="2"> + <xsl:apply-templates/> + </table> + </xsl:template> + + <xsl:template match="changelog/add"> + <tr> + <xsl:variable name="src"><xsl:value-of select="$relative-path"/>/images/add.gif</xsl:variable> + <td valign="top"><img alt="add" class="icon" src="{$src}"/></td> + <td><xsl:apply-templates/></td> + </tr> + </xsl:template> + + <xsl:template match="changelog/update"> + <tr> + <xsl:variable name="src"><xsl:value-of select="$relative-path"/>/images/update.gif</xsl:variable> + <td valign="top"><img alt="update" class="icon" src="{$src}"/></td> + <td><xsl:apply-templates/></td> + </tr> + </xsl:template> + + <xsl:template match="changelog/design"> + <tr> + <xsl:variable name="src"><xsl:value-of select="$relative-path"/>/images/design.gif</xsl:variable> + <td valign="top"><img alt="design" class="icon" src="{$src}"/></td> + <td><xsl:apply-templates/></td> + </tr> + </xsl:template> + + <xsl:template match="changelog/docs"> + <tr> + <xsl:variable name="src"><xsl:value-of select="$relative-path"/>/images/docs.gif</xsl:variable> + <td valign="top"><img alt="docs" class="icon" src="{$src}"/></td> + <td><xsl:apply-templates/></td> + </tr> + </xsl:template> + + <xsl:template match="changelog/fix"> + <tr> + <xsl:variable name="src"><xsl:value-of select="$relative-path"/>/images/fix.gif</xsl:variable> + <td valign="top"><img alt="fix" class="icon" src="{$src}"/></td> + <td><xsl:apply-templates/></td> + </tr> + </xsl:template> + + <xsl:template match="changelog/scode"> + <tr> + <xsl:variable name="src"><xsl:value-of select="$relative-path"/>/images/code.gif</xsl:variable> + <td valign="top"><img alt="code" class="icon" src="{$src}"/></td> + <td><xsl:apply-templates/></td> + </tr> + </xsl:template> + + <!-- Process an attributes list with nested attribute elements --> + <xsl:template match="status"> + <table border="1" cellpadding="5"> + <tr> + <th width="15%" bgcolor="{$attributes-color}"> + <font color="#ffffff">Priority</font> + </th> + <th width="50%" bgcolor="{$attributes-color}"> + <font color="#ffffff">Action Item</font> + </th> + <th width="25%" bgcolor="{$attributes-color}"> + <font color="#ffffff">Volunteers</font> + </th> + <xsl:for-each select="item"> + <tr> + <td align="left" valign="center"> + <xsl:value-of select="@priority"/> + </td> + <td align="left" valign="center"> + <xsl:apply-templates/> + </td> + <td align="left" valign="center"> + <xsl:value-of select="@owner"/> + </td> + </tr> + </xsl:for-each> + </tr> + </table> + </xsl:template> + + <!-- Link to a bug report --> + <xsl:template match="bug"> + <xsl:variable name="link"><xsl:value-of select="$buglink"/><xsl:value-of select="text()"/></xsl:variable> + <a href="{$link}"><xsl:apply-templates/></a> + </xsl:template> + + + <xsl:template match="code"> + <b class="code"><xsl:apply-templates select="text()"/></b> + </xsl:template> + + <xsl:template match="todo"> + <p class="todo"> + This paragraph has not been written yet, but <b>you</b> can contribute to it. + <xsl:if test="string-length(@note) > 0"> + The original author left a note attached to this TO-DO item: + <b><xsl:value-of select="@note"/></b> + </xsl:if> + </p> + </xsl:template> + + <!-- Screens --> + + <xsl:template match="screen"> + <p class="screen"> + <div align="left"> + <table width="80%" border="1" cellspacing="0" cellpadding="2" bgcolor="#000000"> + <tr> + <td bgcolor="#000000" align="left"> + <xsl:apply-templates select="note|wait|type|typedos|type5250|typenext|read"/> + </td> + </tr> + </table> + </div> + </p> + </xsl:template> + + <xsl:template match="note"> + <div class="screen"> + <xsl:value-of select="text()"/> + </div> + </xsl:template> + + <xsl:template match="wait"> + <div class="screen">[...]</div> + </xsl:template> + + <xsl:template match="type"> + <code> + <nobr> + <em class="screen"> + <xsl:text>[user@host] ~</xsl:text> + <xsl:if test="string-length(@dir) > 0"> + <xsl:text>/</xsl:text> + <xsl:value-of select="@dir"/> + </xsl:if> + <xsl:text> $ </xsl:text> + </em> + <xsl:if test="string-length(text()) > 0"> + <b class="screen"><xsl:value-of select="text()"/></b> + </xsl:if> + </nobr> + </code> + <br/> + </xsl:template> + + <xsl:template match="typedos"> + <code> + <nobr> + <em class="screen"> + <xsl:text>c:\</xsl:text> + <xsl:if test="string-length(@dir) > 0"> + <xsl:text>/</xsl:text> + <xsl:value-of select="@dir"/> + </xsl:if> + <xsl:text>></xsl:text> + </em> + <xsl:if test="string-length(text()) > 0"> + <b class="screen"><xsl:value-of select="text()"/></b> + </xsl:if> + </nobr> + </code> + <br/> + </xsl:template> + + <xsl:template match="type5250"> + <code> + <nobr> + <em class="screen"> + <xsl:text>===></xsl:text> + </em> + <xsl:if test="string-length(text()) > 0"> + <b class="screen"><xsl:value-of select="text()"/></b> + </xsl:if> + </nobr> + </code> + <br/> + </xsl:template> + + <xsl:template match="typenext"> + <code> + <nobr> + <em class="screen"> + <xsl:text> </xsl:text> + </em> + <xsl:if test="string-length(text()) > 0"> + <b class="screen"><xsl:value-of select="text()"/></b> + </xsl:if> + </nobr> + </code> + <br/> + </xsl:template> + + <xsl:template match="read"> + <code class="screen"> + <nobr> + <xsl:apply-templates select="text()|enter"/> + </nobr> + </code> + <br/> + </xsl:template> + + <xsl:template match="enter"> + <b class="screen"><xsl:value-of select="text()"/></b> + </xsl:template> + + + + <!-- Process everything else by just passing it through --> + <xsl:template match="*|@*"> + <xsl:copy> + <xsl:apply-templates select="@*|*|text()"/> + </xsl:copy> + </xsl:template> + +</xsl:stylesheet> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/apache.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/apache.xml new file mode 100644 index 00000000..7e35b0e9 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/apache.xml @@ -0,0 +1,1287 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="apache.html"> + + &project; +<copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> +<properties> +<title>Apache HTTP Server HowTo</title> +<author email="hgomez@apache.org">Henri Gomez</author> +<author email="shachor@il.ibm.com">Gal Shachor</author> +<date>$Date: 2011-06-30 21:16:43 +0200 (Thu, 30 Jun 2011) $</date> +</properties> +<body> +<section name="Introduction"> +<p> +This document explains how to connect Tomcat to the popular open source web server, Apache httpd. +There is actually three versions of Apache HTTP Server, 1.3, 2.0 and 2.2 and all can be used with mod_jk, +the Tomcat redirector module. +</p> + +<p> +It is recommended that you also read the +<a href="../generic_howto/workers.html">Workers HowTo</a> document +to learn how to setup the working entities between your web server and Tomcat Engines. +For more detailed configuration information consult the Reference Guide for +<a href="../reference/worker.html">workers.properties</a>, +<a href="../reference/uriworkermap.html">uriworkermap</a> +and <a href="../reference/apache.html">Apache</a>. +</p> + +<p><b>Waring: If Apache HTTP Server and Tomcat are configured to serve content from +the same filing system location then care must be taken to ensure that httpd is +not able to serve inappropriate content such as the contents of the WEB-INF +directory or JSP source code.</b> This could occur if the httpd DocumentRoot +overlaps with a Tomcat Host's appBase or the docBase of any Context. It could +also occur when using the httpd Alias directive with a Tomcat Host's appBase or +the docBase of any Context. +</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> + +<subsection name="Document Conventions and Assumptions"> +<p> +${tomcat_home} is the root directory of tomcat. +Your Tomcat installation should have the following subdirectories: + +<ul> +<li> +${tomcat_home}\conf - Where you can place various configuration files +</li> +<li> +${tomcat_home}\webapps - Containing example applications +</li> +<li> +${tomcat_home}\bin - Where you place web server plugins +</li> +</ul> +</p> +<p> +In all the examples in this document ${tomcat_home} will be <b>/var/tomcat3</b>. +A <a href="../generic_howto/workers.html">worker</a> is defined to be a tomcat process that accepts work from the Apache server. +</p> +</subsection> + +<subsection name="Supported Configuration"> +<p> +The mod_jk module was developed and tested on: +<ul> +<li> +Linux, FreeBSD, AIX, HP-UX, MacOS X, Solaris and should works on major Unixes platforms +supporting Apache 1.3 and/or 2.0/2.2 +</li> +<li> +WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs), Win2K and WinXP and Win98 +</li> +<li> +Cygwin (until you have an apache server and autoconf/automake support tools) +</li> +<li> +Netware +</li> +<li> +i5/OS V5R4 (System I) with Apache HTTP Server 2.0.58. Be sure to have the latest Apache PTF installed. +</li> +<li> +Tomcat 3.2.x, Tomcat 3.3.x, Tomcat 4.0.x, Tomcat 4.1.x, Tomcat 5.0.x, Tomcat 5.5.x and Tomcat 6. +</li> +</ul> +</p> + +<p> +The redirector uses <b>ajp12</b> and <b>ajp13</b> to send requests to the Tomcat containers. There is also an option to use Tomcat in process, +more about the in-process mode can be found in the in process howto. +</p> +</subsection> + +<subsection name="Who support ajp protocols ?"> +<p> +The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x. +</p> + +<p> +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, 5 and 5.5 and Tomcat 6. +</p> + +<p> +Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol. +</p> + +<p> +Others servlet engines such as <b>jetty</b> have support for ajp13 protocol +</p> + +</subsection> + +<subsection name="How does it work ?"> +<p> +In a nutshell a web server is waiting for client HTTP requests. +When these requests arrive the server does whatever is needed to serve the +requests by providing the necessary content. +</p> + +<p> +Adding a servlet container may somewhat change this behaviour. +Now the web server needs also to perform the following: +</p> + +<ul> +<li> +Load the servlet container adaptor library and initialise it (prior to serving requests). +</li> +<li> +When a request arrives, it needs to check and see if a certain request belongs to a servlet, +if so it needs to let the adaptor take the request and handle it. +</li> +</ul> + +<p> +The adaptor on the other hand needs to know what requests it is going to serve, +usually based on some pattern in the request URL, and to where to direct these requests. +</p> + +<p> +Things are even more complex when the user wants to set a configuration that uses virtual hosts, +or when they want multiple developers to work on the same web server +but on different servlet container JVMs. +We will cover these two cases in the advanced sections. +</p> + +</subsection> + +</section> + +<section name="Obtaining mod_jk"> +<p> +mod_jk can be obtained in two formats - binary and source. +Depending on the platform you are running your web server on, a binary version of mod_jk may be available. +</p> + +<p> +It is recommended to use the binary version if one is available. +If the binary is not available, follow the instructions for building mod_jk from source. +The mod_jk source can be downloaded from a mirror +<a href="http://tomcat.apache.org/download-connectors.cgi"> +here</a> +</p> + +<p> +The binaries for mod_jk are now available for several platforms. +The binaries are located in subdirectories by platform. +</p> + +<p> +For some platforms, such as Windows, this is the typical way of obtaining mod_jk +since most Windows systems do not have C compilers. +</p> + +<p> +For others, the binary distribution of mod_jk offers simpler installation. +</p> + +<p> +For example JK 1.2.x can be downloaded from a mirror +<a href="http://tomcat.apache.org/download-connectors.cgi"> +here</a> (look for JK 1.2 Binary Releases). The "JK 1.2 Binary Releases" link contains binary version for a variety of +operating systems for both Apache 1.3 and Apache 2. +</p> + +</section> + +<section name="Installation"> +<p> +mod_jk requires two entities: + +<ul> +<li> +<b>mod_jk.xxx</b> - The Apache HTTP Server module, depending on your operating system, it will be mod_jk.so, mod_jk.nlm or +or MOD_JK.SRVPGM (see the build section). +</li> +<li> +<b>workers.properties</b> - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). +A sample workers.properties can be found under the conf directory in the source download. +</li> +</ul> +</p> + +<p> +Also as with other Apache HTTP Server modules, mod_jk should be first installed on the modules directory of your +Apache webserver, ie : /usr/lib/apache and you should update your <b>httpd.conf</b> file. +</p> + + +<subsection name="Disabling old mod_jserv"> +<p> +If you've previously configured Apache to use <b>mod_jserv</b>, remove any <b>ApJServMount</b> directives +from your httpd.conf. +</p> + +<p>If you're including <b>tomcat-apache.conf</b> or <b>tomcat.conf</b>, you'll want to remove them as well - +they are specific to <b>mod_jserv</b>. +</p> + +<p> +The mod_jserv configuration directives are not compatible with mod_jk ! +</p> +</subsection> + +<subsection name="Using Tomcat auto-configure"> +<p> +The auto-configure works only for a single Tomcat running on the same machine where Apache HTTP Server is running. +The simplest way to configure Apache HTTP Server to use mod_jk is to turn on the Apache HTTP Server auto-configure setting +in Tomcat and put the following include directive at the end of your Apache httpd.conf file +(make sure you replace $TOMCAT_HOME with the correct path for your Tomcat installation: +</p> + +<source> + #To be added at the end of your httpd.conf + Include $TOMCAT_HOME/conf/jk/mod_jk.conf-auto +</source> + +<p> +Note: this file may also be generated as $TOMCAT_HOME/conf/auto/mod_jk.conf +</p> + +<p> +This will tell Apache HTTP Server to use directives in the <b>mod_jk.conf-auto</b> file in +the Apache configuration. This file is created by enabling the Apache +auto-configuration by creating your workers.properties file at +$TOMCAT_HOME/conf/jk/workers.properties and adding the listener to the Engine +element in the server.xml file as per the following example. +<b>Please note that this example is specific to Tomcat 5.x, unlike other sections of this document + which also apply to previous Tomcat branches.</b> +</p> +<source> + ... + <Engine ...> + ... + <Listener className="org.apache.jk.config.ApacheConfig" modJk="/path/to/mod_jk.so" /> + ... + </Engine> + ... +</source> + +<p> +Then restart Tomcat and mod_jk.conf should be generated. For more information on +this topic, please refer to the API documentation at the +<a href="http://tomcat.apache.org/tomcat-5.5-doc/catalina/docs/api/org/apache/jk/config/ApacheConfig.html"> +Tomcat docs website</a>. +</p> + +</subsection> + +<subsection name="Custom mod_jk configuration"> +<p> +You should use custom configuration when : +</p> +<ul> +<li> +You couldn't use <b>mod_jk.conf-auto</b> since Tomcat engine isn't on the same machine that your Apache web server, +ie when you have an Apache in front of a Tomcat Farm. +</li> +<li> +Another case for custom configuration is when your Apache is in front of many different Tomcat engines, +each one having it's own configuration, a general case in ISP hosting +</li> +<li> +Also all Apache webmaster will retain custom configuration to be able to tune the settings +to their real needs. +</li> +</ul> + +</subsection> + +<subsection name="Simple configuration example"> +<p> +Here is a simple configuration: +</p> + +<source> + # Load mod_jk module + LoadModule jk_module libexec/mod_jk.so + # Declare the module for <IfModule directive> (remove this line on Apache 2.0.x) + AddModule mod_jk.c + # Where to find workers.properties + JkWorkersFile /etc/httpd/conf/workers.properties + # Where to put jk shared memory + JkShmFile /var/log/httpd/mod_jk.shm + # Where to put jk logs + 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 servlet for context /examples to worker named worker1 + JkMount /examples/servlet/* worker1 + # Send JSPs for context /examples to worker named worker1 + JkMount /examples/*.jsp worker1 +</source> + +</subsection> +</section> + +<section name="mod_jk Directives"> +<p> +We'll discuss here the mod_jk directives and details behind them +</p> + +<subsection name="Define workers"> +<p> +<b>JkWorkersFile</b> specify the location where mod_jk will find the workers definitions. + +<source> + JkWorkersFile /etc/httpd/conf/workers.properties +</source> + +<br/> +<br/> +</p> +</subsection> + +<subsection name="Logging"> +<p> +<b>JkLogFile</b> specify the location where mod_jk is going to place its log file. +</p> + +<source> + JkLogFile /var/log/httpd/mod_jk.log +</source> + +<p> +Since JK 1.2.3 for Apache 2.0/2.2 and JK 1.2.16 for Apache 1.3 this can also +be used for piped logging: +</p> + +<source> + JkLogFile "|/usr/bin/rotatelogs /var/log/httpd/mod_jk.log 86400" +</source> + +<p> +<b>JkLogLevel</b> +set the log level between : +</p> + +<ul> +<li> +<b>info</b> log will contains standard mod_jk activity (default). +</li> +<li> +<b>error</b> log will contains also error reports. +</li> +<li> +<b>debug</b> log will contains all information on mod_jk activity +</li> +</ul> + +<source> + JkLogLevel info +</source> + +<p> +<code>info</code> should be your default selection for normal operations. +<br/> +<br/> +</p> + +<p> +<b>JkLogStampFormat</b> will configure the date/time format found on mod_jk logfile. +Using the strftime() format string it's set by default to <b>"[%a %b %d %H:%M:%S %Y]"</b> +</p> + +<source> + JkLogStampFormat "[%a %b %d %H:%M:%S %Y] " +</source> + +<p> +<br/> +<br/> +</p> + +<p> +<b>JkRequestLogFormat</b> will configure the format of mod_jk individual request logging. +Request logging is configured and enabled on a per virtual host basis. +To enable request logging for a virtual host just add a JkRequestLogFormat config. +The syntax of the format string is similar to the Apache LogFormat command, +here is a list of the available request log format options: +</p> + +<p> +<table> + <tr><th>Options</th><th>Description</th></tr> + <tr><td>%b</td><td>Bytes sent, excluding HTTP headers (CLF format)</td></tr> + <tr><td>%B</td><td>Bytes sent, excluding HTTP headers</td></tr> + <tr><td>%H</td><td>The request protocol</td></tr> + <tr><td>%m</td><td>The request method</td></tr> + <tr><td>%p</td><td>The canonical Port of the server serving the request</td></tr> + <tr><td>%q</td><td>The query string (prepended with a ? if a query string exists, otherwise an empty string)</td></tr> + <tr><td>%r</td><td>First line of request</td></tr> + <tr><td>%s</td><td>Request HTTP status code</td></tr> + <tr><td>%T</td><td>Request duration, elapsed time to handle request in seconds '.' micro seconds</td></tr> + <tr><td>%U</td><td>The URL path requested, not including any query string.</td></tr> + <tr><td>%v</td><td>The canonical ServerName of the server serving the request</td></tr> + <tr><td>%V</td><td>The server name according to the UseCanonicalName setting</td></tr> + <tr><td>%w</td><td>Tomcat worker name</td></tr> + <tr><td>%R</td><td>Session route name (available with 1.2.19 and up)</td></tr> +</table> + +<source> + JkRequestLogFormat "%w %V %T" +</source> + +<br/> +<br/> +</p> + +</subsection> + +<subsection name="Forwarding"> +<p> +The directive JkOptions allow you to set many forwarding options which will enable (+) +or disable (-) following option. Without any leading signs, options will be enabled. +<br/> +<br/> +</p> + +<p> +The four following options <b>+ForwardURIxxx</b> are mutually exclusive. +Exactly one of them is required, a negative sign prefix is not allowed with them. +The default value is "ForwardURIProxy" since version 1.2.24. +It was "ForwardURICompatUnparsed" in version 1.2.23 and +"ForwardURICompat" until version 1.2.22. +You can turn the default off by switching on one of the other two options. +You should leave this at it's default value, unless you have a very good +reason to change it. +<br/> +<br/> +</p> + +<p> +All options are inherited from the global server to virtual hosts. +Options that support enabling (plus options) and disabling (minus options), +are inherited in the following way: +<br/> +<br/> +options(vhost) = plus_options(global) - minus_options(global) + plus_options(vhost) - minus_options(vhost) +<br/> +<br/> +</p> + +<p> +Using JkOptions <b>ForwardURIProxy</b>, the forwarded URI +will be partially reencoded after processing inside Apache httpd and +before forwarding to Tomcat. This will be compatible with local +URL manipulation by mod_rewrite and with URL encoded session ids. + +<source> + JkOptions +ForwardURIProxy +</source> + +<br/> +<br/> +</p> + +<p> +Using JkOptions <b>ForwardURICompatUnparsed</b>, the forwarded URI +will be unparsed. It's spec compliant and secure. +It will always forward the original request URI, so rewriting +URIs with mod_rewrite and then forwarding the rewritten URI +will not work. + +<source> + JkOptions +ForwardURICompatUnparsed +</source> + +<br/> +<br/> +</p> +<p> +Using JkOptions <b>ForwardURICompat</b>, the forwarded URI will +be decoded by Apache httpd. Encoded characters will be decoded and +explicit path components like ".." will already be resolved. +This is less spec compliant and is <b>not safe</b> if you are using +prefix JkMount. This option will allow to rewrite URIs with +mod_rewrite before forwarding. + +<source> + JkOptions +ForwardURICompat +</source> + +<br/> +<br/> +</p> +<p> +Using JkOptions <b>ForwardURIEscaped</b>, the forwarded URI will +be the encoded form of the URI used by ForwardURICompat. +Explicit path components like ".." will already be resolved. +This will not work in combination with URL encoded session IDs, +but it will allow to rewrite URIs with mod_rewrite before forwarding. + +<source> + JkOptions +ForwardURIEscaped +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>RejectUnsafeURI</b> will block all +URLs, which contain percent signs '%' or backslashes '\' +after decoding. +<br/> +<br/> +</p> +<p> +Most web apps do not use such URLs. Using the option RejectUnsafeURI, you +can block several well known URL encoding attacks. By default, this option +is not set. +</p> +<p> +You can also realise such a check with mod_rewrite, which is more powerful +but also slightly more complicated. + +<source> + JkOptions +RejectUnsafeURI +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>ForwardDirectories</b> is used in conjunction with <b>DirectoryIndex</b> +directive of Apache web server. As such mod_dir should be available to Apache, +statically or dynamically (DSO) +<br/> +<br/> +</p> + +<p> +When DirectoryIndex is configured, Apache will create sub-requests for +each of the local-url's specified in the directive, to determine if there is a +local file that matches (this is done by stat-ing the file). +</p> + +<p> +If ForwardDirectories is set to false (default) and Apache doesn't find any +files that match, Apache will serve the content of the directory (if directive +Options specifies Indexes for that directory) or a <code>403 Forbidden</code> response (if +directive Options doesn't specify Indexes for that directory). +</p> + +<p> +If ForwarDirectories is set to true and Apache doesn't find any files that +match, the request will be forwarded to Tomcat for resolution. This is used in +cases when Apache cannot see the index files on the file system for various +reasons: Tomcat is running on a different machine, the JSP file has been +precompiled etc. +</p> + +<p>Note that locally visible files will take precedence over the +ones visible only to Tomcat (i.e. if Apache can see the file, that's the one +that's going to get served). This is important if there is more then one type of +file that Tomcat normally serves - for instance Velocity pages and JSP pages. + +<source> + JkOptions +ForwardDirectories +</source> +<br/> +<br/> +</p> + +<p> +JkOptions <b>ForwardLocalAddress</b>, you ask mod_jk to send the local address, +of the Apache web server instead remote client address. This can be used by +Tomcat remote address valve for allowing connections only from registered Apache +web servers. + +<source> + JkOptions +ForwardLocalAddress +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>FlushPackets</b>, you ask mod_jk to flush Apache's connection +buffer after each AJP packet chunk received from Tomcat. This option can have +a strong performance penalty for Apache and Tomcat as writes are performed +more often than would normally be required (ie: at the end of each +response). + +<source> + JkOptions +FlushPackets +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>FlushHeader</b>, you ask mod_jk to flush Apache's connection +buffer after the response headers have been received from Tomcat. + +<source> + JkOptions +FlushHeader +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>DisableReuse</b>, you ask mod_jk to close connections immediately +after their use. Normally mod_jk uses persistent connections and pools idle +connections to reuse them, when new requests have to be sent to Tomcat. +</p> + +<p> +Using this option will have a strong performance penalty for Apache and Tomcat. +Use this only as a last resort in case of unfixable network problems. +If a firewall between Apache and Tomcat silently kills idle connections, +try to use the worker attribute socket_keepalive in combination with an appropriate +TCP keepalive value in your OS. + +<source> + JkOptions +DisableReuse +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>ForwardKeySize</b>, you ask mod_jk, when using ajp13, to forward also the SSL Key Size as +required by Servlet API 2.3. +This flag shouldn't be set when servlet engine is Tomcat 3.2.x (off by default). + +<source> + JkOptions +ForwardKeySize +</source> + +<br/> +<br/> +</p> + +<p> +JkOptions <b>ForwardSSLCertChain</b>, you ask mod_jk, when using ajp13, +to forward SSL certificate chain (off by default). +Mod_jk only passes the <code>SSL_CLIENT_CERT</code> to the AJP connector. This is not a +problem with self-signed certificates or certificates directly signed by the +root CA certificate. However, there's a large number of certificates signed by +an intermediate CA certificate, where this is a significant problem: A servlet +will not have the possibility to validate the client certificate on its own. The +bug would be fixed by passing on the <code>SSL_CLIENT_CERT_CHAIN</code> to Tomcat via the AJP connector. +<br/> +This directive exists only since version 1.2.22. +<source> + JkOptions +ForwardSSLCertChain +</source> + +<br/> +<br/> +</p> + +<p> +The directive <b>JkEnvVar</b> allows you to forward environment variables +from Apache server to Tomcat engine. +You can add a default value as a second parameter to the directive. +If the default value is not given explicitly, the variable +will only be send, if it is set during runtime. +<br/> +The variables can be retrieved on the Tomcat side as request attributes +via request.getAttribute(attributeName). +Note that the variables send via JkEnvVar will not be listed +in request.getAttributeNames(). +<br/> +<br/> +The variables are inherited from the global server to virtual hosts. + +<source> + JkEnvVar SSL_CLIENT_V_START undefined +</source> +<br/> +<br/> +</p> + +</subsection> + +<subsection name="Assigning URLs to Tomcat"> +<p> +If you have created a custom or local version of mod_jk.conf-local as noted above, +you can change settings such as the workers or URL prefix. +</p> + +<p> +<b>JkMount</b> directive assign specific URLs to Tomcat. +In general the structure of a JkMount directive is: +</p> + +<source> JkMount [URL prefix] [Worker name]</source> + +<source> + # send all requests ending in .jsp to worker1 + JkMount /*.jsp worker1 + # send all requests ending /servlet to worker1 + JkMount /*/servlet/ worker1 + # send all requests jsp requests to files located in /otherworker will go worker2 + JkMount /otherworker/*.jsp worker2 +</source> + +<p> +You can use the JkMount directive at the top level or inside <VirtualHost> sections of your httpd.conf file. +</p> +</subsection> + +<subsection name="Configuring Apache to serve static web application files"> +<p> +If the Tomcat Host appBase (webapps) directory is accessible by the Apache web server, +Apache can be configured to serve web application context directory static files instead +of passing the request to Tomcat. +</p> + +<p> +Caution: For security reasons is is strongly recommended that JkMount is used to +pass all requests to Tomcat by default and JkUnMount is used to explicitly +exclude static content to be served by httpd. It should also be noted that +content served by httpd will bypass any security constraints defined in the +application's web.xml. +</p> + +<p>Use Apache's <b>Alias</b> directive to map a single web application context directory into Apache's +document space for a VirtualHost: +</p> + +<source> + # Static files in the examples webapp are served by apache + Alias /examples /vat/tomcat3/webapps/examples + # All requests go to worker1 by default + JkMount /* worker1 + # Serve html, jpg and gif using httpd + JkUnMount /*.html worker1 + JkUnMount /*.jpg worker1 + JkUnMount /*.gif worker1 +</source> + +<p> +Starting with mod_jk 1.2.6 for Apache 2.0/2.2 and 1.2.19 for Apache 1.3, it's possible to exclude some URL/URI from +jk processing by setting the env var <b>no-jk</b>, for example with the SetEnvIf Directive. +</p> + +<p> +You could use <b>no-jk</b> env var to fix problem with mod_alias or mod_userdir +directive when jk and alias/userdir URLs matches. +</p> + +<source> + # All URL goes to tomcat except the one containing /home + <VirtualHost *:80> + ServerName testxxx.mysys + DocumentRoot /www/testxxx/htdocs + + # Use SetEnvIf to st no-jk when /home/ is encountered + SetEnvIf Request_URI "/home/*" no-jk + + # Now /home will goes to /home/dataxxx/ + Alias /home /home/dataxxx/ + + <Directory "/home/dataxxx"> + Options Indexes MultiViews + AllowOverride None + Order allow,deny + Allow from all + </Directory> + + JkMount /* myssys-xxx + + </VirtualHost> +</source> + + +<p> +Use the mod_jk <b>JkAutoAlias</b> directive to map all web application context directories +into Apache's document space. +</p> + +<p> +Attempts to access the WEB-INF or META-INF directories within a web application context +or a Web Archive *.war within the Tomcat Host appBase (webapps) directory will fail with an +<code>HTTP 403, Access Forbidden</code> +</p> + +<source> + # Static files in all Tomcat webapp context directories are served by apache + JkAutoAlias /var/tomcat3/webapps + + # All requests go to worker1 by default + JkMount /* ajp13 + # Serve html, jpg and gif using httpd + JkUnMount /*.html ajp13 + JkUnMount /*.jpg ajp13 + JkUnMount /*.gif ajp13 +</source> + +<p> +If you encoded all your URLs to contain the session id +(<code>;jsessionid=...</code>), and you later decide, you want to +move part of the content to Apache httpd, you can tell +mod_jk to strip off all session ids from URLs for +those requests, that do not get forwarded via mod_jk. +</p> + +<p> +You enable this feature by setting JkStripSession to On. +It can be enabled individually for virtual servers. The default +value is Off. +</p> + +</subsection> +</section> + +<section name="Building mod_jk on Unix"> +<p> +The mod_jk build use the widely used configure system. +</p> +<subsection name="Prepare your mod_jk configure from subversion"> +In case you get source from subversion, ie without an existing configure script, +you should have autoconf for configuration and installation. +<p> +To create tomcat-connectors's autoconf script, you will need libtool +1.5.2, automake 1.10 and autoconf 2.59 or newer. The use of more recent +versions is encouraged, e.g. for reliable detection of the features of +recent version of operating systems. +</p><p> +Those tools will not be required if you are just using a package downloaded from apache.org, +they are only required for developers. +</p> +<p> +To create the configure script just type : + +<screen> +<type>./buildconf.sh</type> +</screen> +</p> +</subsection> + +<subsection name="Using configure to build mod_jk"> +<p>Here's how to use configure to prepare mod_jk for building, just type: +<source> +./configure [autoconf arguments] [tomcat-connectors arguments] +</source> +</p> + +<p> +You could set <b>CFLAGS</b> and <b>LDFLAGS</b> to add some platform specifics: +</p> + +<screen> +<type>LDFLAGS=-lc ./configure -with-apxs=/home2/local/apache/bin/apxs</type> +</screen> + +<p> +If you want to build mod_jk for different version of Apache httpd, like 1.3, 2.0 and 2.2, +you need to go through the full build process for each of them. +Please note, that httpd 2.0 and 2.2 modules are <b>not</b> compatible. The mod_jk directory +used is "apache-2.0" in both cases, but you need to compile separately. +<ul> +<li> +use configure and indicate the correct Apache httpd apxs location (--with-apxs) +</li> +<li> +use make +</li> +<li> +copy the resulting mod_jk.so binary from the apache-1.3 or apache-2.0 subdirectory +to the Apache httpd modules location. +</li> +<li> +make clean (to remove all previously compiled object files) +</li> +<li> +Start over with the apxs location for your next Apache httpd version. +</li> +</ul> + +</p> +</subsection> + +<subsection name="configure arguments"> +<p> +<table> + <tr valign="top"><th>Apache related parameters</th><th></th></tr> + <tr valign="top"> + <td>--with-apxs[=FILE]</td> + <td>FILE is the location of the apxs tool. Default is finding apxs in PATH. +It builds a shared Apache module. It detects automatically the Apache version. +(2.0/2.2 and 1.3)</td> + </tr> + <tr valign="top"><td>--with-apache=DIR</td> + <td>DIR is the path where apache sources are located. +The apache sources should have been configured before configuring mod_jk. +DIR is something like: /home/apache/apache_1.3.19 +It builds a static Apache module.</td> + </tr> + <tr valign="top"><td>--enable-EAPI</td> + <td>This parameter is needed when using Apache-1.3 and mod_ssl, otherwise you will get the error message: +"this module might crash under EAPI!" when loading mod_jk.so in httpd. +Not needed when --with-apxs has been used</td> +</tr> + <tr valign="top"><td>--enable-prefork</td> + <td> +In case you build mod_jk for a multi-threaded Apache httpd 2.0/2.2 MPM (Multi-Processing Module), +some areas of mod_jk code need to be synchronised to make it thread-safe. +Because configure can not easily detect, whether your are using a multi-threaded MPM, +mod_jk by default is always build thread-safe for Apache httpd 2.0/2.2. +If you are sure, that your MPM is not multi-threaded, you can use "--enable-prefork" +to force the removal of the synchronisation code (thus increasing performance a bit). +For instance, the prefork MPM is not multi-threaded. For Apache httpd 1.3 +this flag will be set automatically.</td> +</tr> + <tr valign="top"><td>--disable-trace</td> + <td> +When using log level "trace", mod_jk traces a lot of function calls with +"enter" and "exit" log messages. Even if the log level is not "trace", +comparing the log levels to decide about logging has some performance +impact.<br/> +If you use "--disable-trace", then the trace log code doesn't get compiled +into the module binary and you might save some cycles during execution.<br/> +Even with "--disable-trace" logging debug messages with debug log level +will still be possible.</td> +</tr> + <tr valign="top"><td>--enable-api-compatibility</td> + <td> +Only use httpd API functions available in all httpd production releases +of the chosen major httpd release branch. This improves binary +compatibility of module builds with httpd releases older than the release +against mod_jk is build (only between minor httpd versions).</td> +</tr> + <tr valign="top"><td>--enable-flock</td> + <td> +In case the operating system supports flock system call use this flag to enable this +faster locks that are implemented as system call instead emulated by GNU C library.<br/> +However those locks does not work on NFS mounted volumes, so you can use +"--enable-flock" during compile time to force the flocks() calls.</td> +</tr> + +</table> +<br/> +<table> + <tr valign="top"><th>DEPRECATED: JNI related parameters</th><th></th></tr> + <tr valign="top"><td>--enable-jni</td> + <td>Build the JNI worker and so the build process will require +some information about your Java Environment</td> + </tr> + <tr valign="top"><td>--with-java-home=DIR</td> + <td>DIR is the patch to the JDK root directory. Something like: /opt/java/jdk12</td> + </tr> + <tr valign="top"><td>--with-os-type=SUBDIR</td><td>SUBDIR is the os-type subdirectory, + configure should guess it correctly.</td> + </tr> + <tr valign="top"><td>--with-arch-type=SUBDIR</td><td>SUBDIR is the arch subdirectory, + configure should guess it correctly.</td> + </tr> + <tr valign="top"><td>--with-java-platform=VAL</td><td>VAL is the Java platform 1 is 1.1.x and 2 is for 1.2 and higher, + configure should guess it correctly.</td> + </tr> +</table> +</p> +<warn>The JNI option has been deprecated. It will likely not work. Do not use it.</warn> +</subsection> + +<subsection name="Examples of configure use"> + +<screen> +<note>Apache 1.3 and 2.0/2.2 build</note> +<type>./configure --with-apxs=/usr/sbin/apxs</type><br/> +<type>make</type><br/> +<type>cp ./apache-1.3/mod_jk.so /usr/lib/apache</type><br/> +<type>make clean</type><br/> +<type>./configure --with-apxs=/usr/sbin/apxs2</type><br/> +<type>make</type><br/> +<type>cp ./apache-2.0/mod_jk.so /usr/lib/apache2</type><br/> +</screen> + +<screen> +<note>Apache 2.0/2.2 build with JNI support</note> +<type>./configure --with-apxs2=/opt/apache2/bin/apxs \</type> +<typenext>--with-java-home=${JAVA_HOME} --with-java-platform=2 \</typenext> +<typenext>--enable-jni</typenext><br/> +</screen> +<warn>The JNI option has been deprecated. It will likely not work. Do not use it.</warn> +</subsection> + +</section> + +<section name="Building mod_jk for Apache on Windows NT/2K/XP"> +<p> +The module was developed using Visual C++ version 6.0, so having this environment is a prerequisite +if you want to perform a custom build. +</p> +<p> +The steps that you need to take are: +</p> +<ul> +<li> +Change directory to the apache 1.3 or apache 2.0 source directory depending on your version of Apache. +</li> +<li> +If you want to build mod_jk for Apache 1.3, set an <b>APACHE1_HOME</b> environment variable which points +to where your Apache 1.3 is installed. +A mod_jk module for Apache 2.0 build will require <b>APACHE2_HOME</b> environment variable to be set. +</li> +<li> +Copy mod_jk.so to Apache's modules directory. +</li> +</ul> +<p> +An example on how to build mod_jk for Apache 1.3: +</p> +<screen> +<note>Set location for Apache 1.3 sources</note> +<typedos>set APACHE1_HOME=c:\apache13</typedos> +<note>Change directory to the mod_jk module for Apache 1.3</note> +<typedos>cd c:\home\apache\jk\native\apache-1.3</typedos> +<note>Build the sources using MSDEV</note> +<typedos>MSDEV mod_jk.dsp /MAKE ALL</typedos> +<note>Copy the dll to your apache modules directory</note> +<typedos>cp release\mod_jk.so c:\apache13\modules\</typedos> +</screen> + +<p> +An example on how to build mod_jk for Apache 2.0: +</p> +<screen> +<note>Set location for Apache 2.0 sources</note> +<typedos>set APACHE2_HOME=c:\apache20</typedos> +<note>Change directory to the mod_jk module for Apache 2.0</note> +<typedos>cd c:\home\apache\jk\native\apache-2.0</typedos> +<note>Build the sources using MSDEV</note> +<typedos>MSDEV mod_jk.dsp /MAKE ALL</typedos> +<note>Copy the dll to your apache modules directory</note> +<typedos>cp release\mod_jk.so c:\apache20\modules\</typedos> +</screen> + +<p> +If msdev is not in your path, enter the full path to msdev.exe. +Also, ApacheCore.lib is expected to exist in the <b>${APACHEX_HOME}\src\CoreD</b> and +<b>${APACHEX_HOME}\src\CoreR</b> directories before linking will succeed. +You will need to build enough of the Apache source to create these libraries. +This will build both release and debug versions of the redirector plug-in (mod_jk). +An alternative will be to open mod_jk.dsp in msdev and build it using the build menu. +</p> +</section> + +<section name="Building mod_jk for Apache on System I - i5/OS (OS400)"> +<p> +Since OS400 V4R5, System I (AS/400) has used Apache 2.0 as their primary web server, +replacing the old IBM webserver. +It's now possible to build mod_jk on System I thanks to the help of the IBM +Rochester Labs which has provided information and patches to adapt mod_jk to i5/OS. +</p> +<p> +You should have at least Apache 2.0.58 (product 5722DG1), a C Compiler and IFS. +Apache 2.0.58 is provided with the most recent set of PTFs for the iSeries Apache +server, which can be found at <a href="http://www.ibm.com/servers/eserver/iseries/software/http/"> +http://www.ibm.com/servers/eserver/iseries/software/http/</a> +</p> +<p> +The all latest Apache 2 for i5/OS V5R3 (or V5R4) is now 2.0.58 (as of 2007/04/17). +Be sure to have the latest PTFs loaded if you want to make use of jk 1.2.15 and higher. +NB: The latest mod_jk known to work on i5/OS V5R3 was 1.2.19. +</p> +<p> +New in i5/OS V5R4, UTF is required, also for Apache modules, as such Apache modules do not require +translations to/from EBCDIC but works should be done to port mod_jk 1.2.23 (and higher) to V5R4. + +From the V5R4 Infocenter : + +As of i5/OS(tm) V5R4, modules must be recompiled with a UTF locale. This creates an environment where locale-dependent C runtime functions assume +that string data is encoded in UTF-8. Any hardcoded constants can be encoded in UTF-8 by adding a #pragma convert(1208) statement in the module. +Additionally, input data from the client will no longer be converted to EBCDIC but will be passed as-is. +Output data sent from the module is not converted either so it must be encoded in ASCII or UTF8 as required. +APR and HTTP APIs as of V5R4, expect data in UTF-8. Note that several APIs have additional functions that allow a CCSID to be set to +indicate the encoding of the parameters being passed. Conversion functions between UTF-8 and EBCDIC have been added. +Be sure to review APIs used by your module to be aware of current changes. + +</p> +<p> +To configure mod_jk on System I use the CL source provided with the mod_jk source. +</p> +<ul> +<li> +Get the latest mod_jk source and untar it on a Windows or Unix boxes +</li> +<li> +Create a directory in IFS, ie /home/apache +</li> +<li> +Send the whole jk source directory to System I directory via FTP. +</li> +<li> +Then go to the System I command line : +</li> +</ul> +<screen> +<note>Create mod_jk library</note> +<type5250>CRTLIB MOD_JK TEXT(‘Apache mod'jk tomcat connector module')</type5250> +<note>Create service program source file</note> +<type5250>CRTSRCPF MOD_JK/QSRVSRC TEXT(‘Service program source file’)</type5250> +<note>Create the CL build program source file</note> +<type5250>CRTSRCPF FILE(MOD_JK/QCLSRC) TEXT(‘Build program source file’)</type5250> +<note>Edit the service program source file</note> +<type5250>STRSEU MOD_JK/QSRVSRC MOD_JK</type5250> +</screen> +<p> +In the edited file, specify that only jk_module should be exported : +<screen> +<note> Columns . . : 1 71 Edit MOD_JK/QSRVSRC </note> +<note> SEU==> MOD_JK </note> +<note> *************** Beginning of data ************************************* </note> +<note>0001.00 STRPGMEXP PGMLVL(*CURRENT) </note> +<note>0002.00 EXPORT SYMBOL("jk_module") </note> +<note>0003.00 ENDPGMEXP </note> +<note> ****************** End of data **************************************** </note> +</screen> +</p> +<p> +You could start to build all the modules of mod_jk (cases for V5R4 or previous releases): +</p> +<screen> +<note>Copy the CL build program source for i5/OS before V5R4 from IFS</note> +<type5250>CPYFRMSTMF FROMSTMF('/home/apache/jk/native/apache-2.0/bldjk.qclsrc') +</type5250> +<note>TOMBR('/QSYS.LIB/MOD_JK.LIB/QCLSRC.FILE/BLDJK.MBR') MBROPT(*REPLACE)</note> +<note>Build the CL build program</note> +<type5250>CRTCLPGM PGM(MOD_JK/BLDJK) SRCFILE(MOD_JK/QCLSRC) TEXT('Apache mod_jk build program')</type5250> +<note>Launch the build</note> +<type5250>CALL MOD_JK/BLDJK</type5250><br/> +<note>If the build if successfull, copy the new mod_jk module</note> +<type5250>CRTDUPOBJ OBJ(MOD_JK) FROMLIB(MOD_JK) OBJTYPE(*SRVPGM) TOLIB(QHTTPSVR) NEWOBJ(MOD_JK)</type5250> +</screen> +<screen> +<note>Copy the CL build program source for i5/OS V5R4 from IFS</note> +<type5250>CPYFRMSTMF FROMSTMF('/home/apache/jk/native/apache-2.0/bldjk54.qclsrc') +</type5250> +<note>TOMBR('/QSYS.LIB/MOD_JK.LIB/QCLSRC.FILE/BLDJK54.MBR') MBROPT(*REPLACE)</note> +<note>Build the CL build program for i5/OS V5R4</note> +<type5250>CRTCLPGM PGM(MOD_JK/BLDJK54) SRCFILE(MOD_JK/QCLSRC) TEXT('Apache mod_jk build program') TGTRLS(*CURRENT)</type5250> +<note>Launch the build for i5/OS V5R4</note> +<type5250>CALL MOD_JK/BLDJK54</type5250><br/> +<note>If the build if successfull, copy the new mod_jk module</note> +<type5250>CRTDUPOBJ OBJ(MOD_JK) FROMLIB(MOD_JK) OBJTYPE(*SRVPGM) TOLIB(QHTTPSVR) NEWOBJ(MOD_JK)</type5250> +</screen> +<p> +Next, you should restart your Apache 2.0 instance and enjoy this piece of OpenSource on System I. +</p> +<screen> +<note>ENDTCPSVR SERVER(*HTTP) HTTPSVR(MYSERVER)</note> +<note>STRTCPSVR SERVER(*HTTP) HTTPSVR(MYSERVER)</note> +</screen> +</section> + +<section name="Building mod_jk for Apache on MacOS/X"> +<p> +Mac OS X (10.2.x) build notes : +</p> +<p> +Assuming that you are root : +</p> +<screen> +<note>For Apache 1.3:</note> +<type>./configure --with-apxs=/usr/sbin/apxs</type> +<type>cd apache-1.3</type> +<type>make -f Makefile.apxs</type> +<type>cp mod_jk.so /etc/libexec/httpd</type> + +<note>For Apache 2.0:</note> +<type>./configure --with-apxs=/usr/local/apache2/bin/apxs</type> +<note>(you should point to the directory where you installed Apache 2.0)</note> +<type>cd apache-2.0</type> +<type>make -f Makefile.apxs install</type> +</screen> +</section> + +<section name="Getting mod_jk linked statically with Apache"> +<p> +mod_jk allows to install mod_jk in the Apache source tree to get a statically +linked mod_jk. Having mod_jk in the httpd executable brings some performance +improvements. The configure option --with-apache prepare mod_jk to install it +in the Apache source tree. +The option --with-apache works both for Apache-1.3 and Apache-2.0. +The examples below show how to get mod_jk in the httpd process. +</p> + +<subsection name="Installation in Apache-2.0"> +<screen> +<note> /home/apache20/httpd-2.0.43 is the directory where the httpd-2.0 sources +are located. </note> +<type>./configure --with-apache=/home/apache20/httpd-2.0.43</type><br/> +<type>make</type><br/> +<note>Install the mod_jk library and other files in +/home/apache20/httpd-2.0.43/modules: </note> +<type>make install</type><br/> +<note> It is not possible to configure Apache directly because the config.m4 of mod_jk must +be added to the configure of httpd-2.0. </note> +<type>cd /home/apache20/httpd-2.0.43</type> +<type>sh buildconf</type> +<type>configure ... --with-mod_jk</type> +<type>make</type> +<type>make install</type><br/> +</screen> +<p> +The enable-jk=share and enable-jk=static are not supported. --with-mod_jk only +allow static linking of mod_jk. +</p> +</subsection> + +<subsection name="Installation in Apache-1.3"> +<screen> +<note> /home/apache/apache_1.3.27 is the directory where the apache-1.3 sources +are located. </note> +<type>./configure --with-apache=/home/apache/apache_1.3.27</type><br/> +<type>make</type><br/> +<note>Install the libjk library, mod_jk.c, includes and other files in +/home/apache/apache_1.3.27/src/modules/jk: </note> +<type>make install</type><br/> +<note> Configure in the Apache sources: </note> +<type>cd /home/apache/apache_1.3.27</type> +<type>configure ... --enable-module=dir --disable-shared=dir \</type> +<typenext> --activate-module=src/modules/jk/libjk.a \</typenext> +<typenext> --disable-shared=jk</typenext> +<type>make</type> +<type>make install</type><br/> +</screen> +<p> +The --enable-shared=jk is also working and builds a dso file. +</p> +<screen> +<note> Just change the configure in the Apache sources: </note> +<type>configure ... --enable-module=dir --enable-shared=dir \</type> +<typenext> --activate-module=src/modules/jk/libjk.a \</typenext> +<typenext> --enable-shared=jk</typenext> +</screen> +</subsection> + +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/iis.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/iis.xml new file mode 100644 index 00000000..e79c1611 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/iis.xml @@ -0,0 +1,729 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="iis.html"> + + &project; +<copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> +<properties> +<title>IIS HowTo</title> +<author email="hgomez@apache.org">Henri Gomez</author> +<author email="shachor@il.ibm.com">Gal Shachor</author> +<author email="yoavs@apache.org">Yoav Shapira</author> +<date>$Date: 2010-03-15 16:40:37 +0100 (Mon, 15 Mar 2010) $</date> +</properties> +<body> +<section name="Introduction"> +<p> +This document explains how to set up IIS to cooperate with Tomcat. +</p> + +<p> +Normally IIS can not execute Servlets and Java Server Pages (JSPs), +configuring IIS to use the JK ISAPI redirector plugin will let IIS send servlet and +JSP requests to Tomcat (and this way, serve them to clients). +</p> + +<p> +It is recommended that you also read the +<a href="../generic_howto/workers.html">Workers HowTo</a> document +to learn how to setup the working entities between your web server and Tomcat Engines. +For more detailed configuration information consult the Reference Guide for +<a href="../reference/workers.html">workers.properties</a>, +<a href="../reference/uriworkermap.html">uriworkermap</a> +and <a href="../reference/iis.html">IIS</a>. +</p> + + +<subsection name="Document Conventions and Assumptions"> +<p> +${tomcat_home} is the root directory of tomcat. +Your Tomcat installation should have the following subdirectories: + +<ul> +<li> +${tomcat_home}\conf - Where you can place various configuration files +</li> +<li> +${tomcat_home}\webapps - Containing example applications +</li> +<li> +${tomcat_home}\bin - Where you place web server plugins +</li> +</ul> +</p> +<p> +In all the examples in this document ${tomcat_home} will be <b>c:\tomcat</b>. +A worker is defined to be a tomcat process that accepts work from the IIS server. +</p> +</subsection> + + +<subsection name="Supported Configuration"> +<p> +The IIS-Tomcat redirector was developed and tested on: +<ul> +<li> +WinNT4.0-i386 SP4/SP5/SP6a (should be able to work with other service packs), Win2K and WinXP and Win98 +</li> +<li> +IIS4.0 and PWS4.0 (numerous people have working IIS 5 and IIS 6 configurations) +</li> +<li> +Tomcat 3.2 and later, Tomcat 4.x, Tomcat 5 and 5.5 and Tomcat 6 +</li> +</ul> +</p> + +<p> +The redirector uses <b>ajp12</b> and <b>ajp13</b> to send requests to the Tomcat containers. There is also an option to use Tomcat in process, +more about the in-process mode can be found in the in process howto. +</p> +</subsection> + +<subsection name="IIS 5 and 6 Notes"> +<p> +There are extra steps you need to take for configuring Tomcat with IIS 5 and 6. Please see the appropriate links from +<a href="http://wiki.apache.org/tomcat/Tomcat/Links">Tomcat Useful Links</a>. +</p> +</subsection> + +<subsection name="IIS 7 notes"> +<p> +There is a known bug in IIS that may result in incomplete log messages. See <a +href="https://issues.apache.org/bugzilla/show_bug.cgi?id=45769">bug 45769</a> +for further details. +</p> +</subsection> + +<subsection name="Who support ajp protocols ?"> +<p> +The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x. +</p> + +<p> +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, 5 and 5.5 and Tomcat 6. +</p> + +<p> +Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol. +</p> + +<p> +Others servlet engines such as <b>jetty</b> have support for ajp13 protocol +</p> + +</subsection> + +<subsection name="How does it work ?"> +<p> +<ol> +<li> +The IIS-Tomcat redirector is an IIS plugin (filter + extension), IIS load the redirector plugin and calls its +filter function for each in-coming request. +</li> +<li> +The filter then tests the request URL against a list of URI-paths held inside uriworkermap.properties, +If the current request matches one of the entries in the list of URI-paths, +the filter transfers the request to the extension. +</li> +<li> +The extension collects the request parameters and forwards them to the appropriate worker using the defined +protocol like <b>ajp13</b>. +</li> +<li> +The extension collects the response from the worker and returns it to the browser. +</li> +</ol> +</p> +</subsection> + +</section> + +<section name="Installation"> +<p> +A pre-built version of the ISAPI redirector server plugin, isapi_redirect.dll, is available under +the win32/i386 directory of tomcat-connectors distribution. +For those using Netscape as your browser, try downloading a zip version of the file, if available. +There can be problems using Netscape to download DLL files. + +You can also build a copy locally from the source present in tomcat-connectors distribution. + +The Tomcat redirector requires three entities: + +<ul> +<li> +<b>isapi_redirect.dll</b> - The IIS server plugin, either obtain a pre-built DLL or build it yourself (see the build section). +</li> +<li> +<b><a href="../reference/workers.html">workers.properties</a></b> - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). +A sample workers.properties can be found under the conf directory. +</li> +<li> +<b><a href="../reference/uriworkermap.html">uriworkermap.properties</a></b> - A file that maps URL-Path patterns to workers. +A sample uriworkermap.properties can be found under the conf directory as well. +</li> +</ul> +</p> + +<p> +The installation includes the following parts: + +<ul> +<li> +Configuring the ISAPI redirector with a default /examples context and checking that you can serve servlets with IIS. +</li> +<li> +Adding more contexts to the configuration. +</li> +</ul> +</p> + +</section> + +<section name="Configuring the ISAPI Redirector"> +<p> +In this document I will assume that isapi_redirect.dll is placed in +<b>c:\tomcat\bin\win32\i386\isapi_redirect.dll</b> and +that the properties files which you created are in <b>c:\tomcat\conf</b>. +</p> +<p> +<ol> +<li> +In the registry, create a new registry key named +<b>"HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0"</b> +</li> +<li> +Add a string value with the name <b>extension_uri</b> and a value of <b>/jakarta/isapi_redirect.dll</b> +</li> +<li> +Add a string value with the name <b>log_file</b> and a value pointing to where you want your +log file to be (for example <b>c:\tomcat\logs\isapi.log</b>). +</li> +<li> +Add a string value with the name <b>log_level</b> and a value for your log level +(can be debug, info, error or emerg). +</li> +<li> +Add a string value with the name <b>worker_file</b> and a value which is the full path +to your workers.properties file (for example <b>c:\tomcat\conf\workers.properties</b>) +</li> +<li> +Add a string value with the name <b>worker_mount_file</b> and a value which is the full path +to your uriworkermap.properties file (for example <b>c:\tomcat\conf\uriworkermap.properties</b>) +</li> +<li> +Using the IIS management console, add a new virtual directory to your IIS/PWS web site. +The name of the virtual directory must be jakarta. +Its physical path should be the directory where you placed isapi_redirect.dll +(in our example it is c:\tomcat\bin\win32\i386). +While creating this new virtual directory assign it with execute access. +</li> +<li> +Using the IIS management console, add isapi_redirect.dll as a filter in your IIS/PWS web site. +The name of the filter should reflect its task (I use the name tomcat), +its executable must be our c:\tomcat\bin\win32\i386\isapi_redirect.dll. +For PWS, you'll need to use regedit and add/edit the <b>"Filter DLLs"</b> key under +<b>HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters</b>. +This key contains a "," separated list of dlls (full paths) - +you need to insert the full path to isapi_redirect.dll. +</li> +<li> +If you're using IIS 6.0 you must also do the following: +<br /> +Using the IIS management console, add the Jakarta Isapi Redirector to the Web +Service Extensions. +<ol> +<li>Right-click on Web Service Extensions and choose Add a new Web Service +Extension.</li> +<li>Enter tomcat for the Extension Name.</li> +<li>Add the isapi_redirect.dll to the required files.</li> +<li>Check the Set extension status to Allowed.</li> +<li>Click on OK.</li> +</ol> +</li> +<li> +Restart IIS (stop + start the IIS service), make sure that the tomcat filter is marked with a green up-pointing arrow. +Under Win98 you may need to <b>cd WINDOWS\SYSTEM\inetsrv</b> and type PWS /stop +( the DLL and log files are locked - even if you click the stop button, +PWS will still keep the DLLs in memory. ). Type pws to start it again. +</li> +</ol> +</p> +<p> +That's all, you should now start Tomcat and ask IIS to serve you the /examples context. +Try <a href="http://localhost/examples/jsp/index.html">http://localhost/examples/jsp/index.html</a> for example and +execute some of the JSP examples. +</p> +<p> +If this does not work successfully, refer to the Troubleshooting section below for help on correcting the problem. +</p> + +<subsection name="Adding additional Contexts"> +<p> +The examples context is useful for verifying your installation, +but you will also need to add your own contexts. Adding a new context requires two operations: +</p> +<p> +<ol> +<li> +Adding the context to Tomcat (I am not going to talk about this). +</li> +<li> +Adding the context to the ISAPI redirector. +</li> +</ol> +</p> +<p> +Adding a context to the ISAPI redirector is simple, all you need to do is to edit +your uriworkermap.properties and to add a line that looks like: +</p> + +<source> + /context/*=worker_name +</source> + +<p> +Workers and their name are defined in workers.properties, by default workers.properties comes +with a single pre-configured worker named <b>"defworker"</b> so you can use it. +As an example, if you want to add a context named "shop", the line that you should add to +uriworkermap.properties will be: +</p> + +<source> + /shop/*=defworker +</source> + +After saving uriworkermap.properties restart IIS and it will serve the new context. +<p> +The above should be all you need for IIS to pass through to Tomcat any request for any URI which corresponds +to a Tomcat context (webapp). +</p> +</subsection> + +<subsection name="Advanced Context Configuration"> +<p> +If your webiste is very busy (more than 100 requests/second, or more than 100 simultaneous client connections), +it might sometimes be desirable to have IIS serve static content (html, gif, jpeg etc.) directly, +even if these files are part of a context served by Tomcat. Allowing IIS to serve such files directly may + avoid the small overhead consisting of passing the request to Tomcat via the redirector, and may free up + Tomcat somewhat, by using it only to process requests that only Tomcat can handle (e.g. requests to JSP pages and java servlets). +</p> +<p> +For example, consider the html and gif files in the examples context : you could serve these files directly +with IIS; there is no need to serve them from the Tomcat process. +</p> +<warn>However, you should be very careful when you implement the following configuration style, because by doing so you are +in fact providing a "back-door" to IIS, and allowing it to serve files out of a Tomcat context without Tomcat's knowledge, +thus bypassing any security +restrictions which Tomcat itself and the Tomcat context (webapp) may place on those files.</warn> +<p> +Making IIS serve static files that are part of the Tomcat contexts requires the following: +<ol> +<li> +Configuring IIS to know about the Tomcat contexts +</li> +<li> +Configuring the redirector to leave the static files for IIS +</li> +</ol> +</p> + +<p> +Adding a Tomcat context to IIS requires the addition of a new IIS virtual directory that covers the Tomcat context. +For example adding a /example IIS virtual directory that covers the c:\tomcat\webapps\examples directory. +</p> + +<p> +Configuring the redirector is somewhat harder, you will need to specify the exact +URL-Path pattern(s) which you want Tomcat to handle (usually only JSP files and servlets). +This requires a change to the uriworkermap.properties : + +<source> + For the examples context it requires to replace the following line + /examples/*=defworker + with the following two lines + /examples/*.jsp=defworker + /examples/servlet/*=defworker +</source> +</p> + +<p> +As you can see the second configuration is more explicit, it actually instruct the redirector +to redirect only requests to resources under /examples/servlet/ and resources under /examples/ +whose name ends with .jsp. +</p> + +<p> +You can even be more explicit and provide lines such as: + +<source> + /example/servletname=defworker +</source> +</p> + +<p> +that instructs the redirector to redirect all requests whose URL-path matches the leading string "/example/servletname" +to the worker named defworker. +</p> + +</subsection> + +<subsection name="Protecting the content of your Tomcat contexts"> +<p>Once again, be aware that by allowing IIS to access the content of your Tomcat context directly, you are +potentially bypassing Tomcat's protection of that content. You should thus make sure to protect this content +at the IIS level if needed, by using the corresponding IIS management console functions. +</p> +<p> +In particular, each servlet application (context) has a special directory named WEB-INF, +which contains sensitive configuration data and Java classes, and which should always be kept hidden from web users. +Using the IIS management console it is possible to protect the WEB-INF directory from user access, but considering that +this is a general requirement, and considering that it is easy to forget to implement this protection +at the IIS level, the redirector plugin does it automatically for you, and it will reject any request +which contains WEB-INF in its URL-path. +</p> +</subsection> + +<subsection name="Advanced Worker Configuration"> +<p> +Sometimes you may want to serve different contexts with different Tomcat processes +(for example to spread the load among different machines). +To achieve such a goal you will need to define several workers and assign each context to its own worker. +</p> +<p> +Defining additional workers is done in the workers.properties file. This file includes two types of entries: +</p> + +<p> +<source> + # An entry that lists all the workers defined + worker.list=worker1, worker2 + # Entries that define the host and port associated with each of these workers + worker.worker1.host=localhost + worker.worker1.port=8009 + worker.worker1.type=ajp13 + worker.worker2.host=otherhost + worker.worker2.port=8009 + worker.worker2.type=ajp13 +</source> +</p> + +<p> +The above example defined two workers, now we can use these workers to serve two different contexts +each with its own worker: +<source> + example uriworkermap.properties fragment + /examples/*=worker1 + /webpages/*=worker2 +</source> +</p> + +<p> +As you can see the <b>examples</b> context is served by <b>worker1</b> while the +<b>webpages</b> context is served by <b>worker2</b>. +</p> + +<p> +More information on using and configuring workers in the <a href="../generic_howto/workers.html">Workers HowTo</a> +and in the <a href="../reference/workers.html">worker.properties configuration reference</a>. +</p> + +</subsection> + +</section> + +<section name="Building ISAPI redirector"> +<p> +The redirector was developed using Visual C++ Ver.6.0, so having this environment is a prerequisite if you want +to perform a custom build. You should also have the IIS developer SDK. + +The steps that you need to take are: +<ul> +<li> +Change directory to the isapi plugins source directory. +</li> +<li> +Make the source with MSDEV +</li> +</ul> +<screen> +<note>Change directory to the isapi plugins source directory</note> +<typedos>cd c:\home\apache\jk\iis</typedos> +<note>Build the sources using MSDEV</note> +<typedos>MSDEV isapi.dsp /MAKE ALL</typedos> +</screen> +</p> +<p> +If msdev is not in your path, enter the full path to msdev.exe. +This will build both release and debug versions of the redirector plugin. +An alternative will be to open the isapi workspace file (isapi.dsw) in msdev and +build it using the build menu. +</p> +</section> + +<section name="Troubleshooting"> +<p> +It is easy to have the ISAPI redirector not work the first time you try to install it. +</p> +<p> +If this happens to you, here are some steps to follow to try to correct the problem. +</p> +<p> +These steps aren't guaranteed to cover all possible problems, +but they should help find the typical mistakes. +</p> +<p> +If you make any corrections during these steps, restart the IIS service as described above in the last step +of the installation, then retry the step. +</p> + +<p>To enable error tracking, make sure web site activity is being logged. +For PWS 4.0 make sure "Save Web Site Activity Log" is checked in the Advanced Options of the Personal Web Manager. +</p> + +<p> +Note: These steps assume your <b>worker_mount_file</b> setting points to an unmodified copy of the +<b>uriworkermap.properties</b> file.<br/> +Results may be misleading if <b>worker_mount_file</b> points to a modified <b>uriworkermap.properties</b> +or the <b>uriworkermap.properties-auto</b> file.<br/> +It is also assumed that the <b>"/examples" context</b> works correctly if you access Tomcat directly. +</p> + +<subsection name="Win98"> +<p> +Start the IIS service and Tomcat. +</p> +<p> +Check for the presence of the ISAPI redirector log file you specified in the log_file setting. +If not found, verify the following: +</p> +<ul> +<li> +Check the "Filter DLLs" setting in the "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\W3SVC\Parameters" +key and make sure the path is correct. +</li> +<li> +Check the spelling of the "HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0" key. +Case isn't important, but an incorrect letter will prevent the isapi_redirect.dll from finding its registry settings. +</li> +<li> +Check the log_file setting for typos, name and data. Also insure the directory in which the log file will appear already exists. +</li> +If the above are set correctly, the ISAPI redirector should be able to create the log file. +</ul> +<p> +Invoke the URL <a href="http://localhost/examples/jsp/index.html">http://localhost/examples/jsp/index.html</a> +in your browser. +Case is important in Tomcat. The characters following "localhost" in the URL must be lower case. +If the page fails to appear, stop the IIS service (required to view the IIS log file). +Then examine the last line in the IIS log file in found in SYSTEM/LogFiles/W3SVC1 : +</p> +<p> +If the last line contains: +</p> +<source> + GET "/examples/jsp/index.html HTTP/1.1" 404 +</source> +<p> +then the ISAPI redirector is not recognising that it should be handling requests for the "/examples" context. +Check the following: +</p> +<ul> +<li> +Check the extension_uri name for typos. +</li> +<li> +Check the worker_file setting for typos, name and data. +</li> +<li> +Check the worker_mount_file setting typos, name and data. +</li> +If these are set correctly, the ISAPI redirector should recognise that it should handle requests for the "/examples" context. +</ul> + +<p>If the last line contains something like: +</p> + +<source> + GET "/jakarta/isapi_redirect.dll HTTP1.1" +</source> + +<p> +then the ISAPI redirector is recognising that it should handle the request, +but is not successful at getting Tomcat to service the request. +</p> + +<p> +You should check the HTTP error code following GET "/..." : +</p> + +<source> + Error 404 + GET "/..." 404 +</source> + +<ul> +<li> +Make sure you entered the URL correctly. +</li> +<li> +Make sure the virtual directory created was called "jakarta". +It should display in Personal Web Manager as "/jakarta" (without the quotes). +</li> +<li> +Make sure the extension_uri data begins with "/jakarta/" (without the quotes). +</li> +</ul> + +<source> + Error 500 + GET "/..." 500 +</source> + +<ul> +<li> +Make sure that "isapi_redirect.dll" follows "/jakarta/" in the extension_uri setting. +</li> +<li> +Check the workers.properties file and make sure the port setting for worker.ajp12.port is the same as the port specified in the server.xml for the "Apache AJP12 support". +</li> +</ul> + +<source> + Error 200 or 403 + GET "/..." 200 + GET "/..." 403 +</source> + +<ul> +<li> +Make sure you have checked Execute Access +for the jakarta virtual directory in the Advanced Options of the Personal Web Manager. +</li> +</ul> + +<p> +If the above settings are correct, the index.html page should appear in your browser. +You should also be able to click the Execute links to execute the JSP examples. +</p> + +</subsection> + +<subsection name="WinNT/Win2K/WinXP"> +<p> +Start the World Wide Web Publishing Service and Tomcat. +</p> +<p> +Check for the presence of the ISAPI redirector log file you specified in the log_file setting. +If not found, check the following: +</p> +<ul> +<li> +Check the "executable" you set for the filter in the IIS Management Console and make sure the path is correct. +</li> +<li>Check the spelling of the "HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0" key. +Case isn't important, but an incorrect letter will prevent the isapi_redirect.dll from finding its registry settings. +</li> +<li> +Check the log_file setting for typos, name and data. Also insure the directory in which the log file will appear already exists. +</li> +If the above are set correctly, the ISAPI redirector should be able to create the log file. +</ul> + +<p> +Check the tomcat filter you added and make sure its status shows a green upward-pointing arrow. +If not, check the following: +</p> +<ul> +<li> +Check the worker_file setting for typos, name and data. +</li> +<li> +Check the worker_mount_file setting typos, name and data. +</li> +If the above are set correctly, the green upward-pointing arrow should appear, even if the other settings are wrong. +</ul> + +<p> +Invoke the URL <a href="http://localhost/examples/jsp/index.html">http://localhost/examples/jsp/index.html</a> +in your browser. Case is important in Tomcat. The characters following "localhost" in the URL must be lower case. +If the page fails to appear, examine the last line in the IIS server log file in found in SYSTEM32/LogFiles/W3SVC1. +</p> + +<p> +The last line should contain something like: GET "/jakarta/isapi_redirect.dll HTTP1.1", +which indicates the ISAPI redirector is recognising that it should handle the request. +</p> + +<p> +You should check the HTTP error code following GET "/..." : +</p> + +<source> + Error 404 + GET "/..." 404 +</source> + +<ul> +<li> +Make sure you entered the URL correctly. +</li> +</ul> + +<source> + Error 500 + GET "/..." 500 +</source> + +<ul> +<li> +Make sure the virtual directory created was called "jakarta". +</li> +<li> +Make sure that the extension_uri setting is correct. +</li> +<li> +Check the workers.properties file and make sure the port setting for worker.ajp12.port is the same as the port specified in the server.xml for the "Apache AJP12 support". +</li> +</ul> + +<source> + Error 200 or 403 + GET "/..." 200 + GET "/..." 403 +</source> + +<ul> +<li> +Make sure you have checked Execute Access for the jakarta virtual directory in the +Advanced Options of the Personal Web Manager. +</li> +</ul> + +<p> +If the above settings are correct, the index.html page should appear in your browser. +You should also be able to click the Execute links to execute the JSP examples. +</p> +</subsection> + + +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/nes.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/nes.xml new file mode 100644 index 00000000..6f86efde --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/nes.xml @@ -0,0 +1,521 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE document [ + <!ENTITY project SYSTEM "project.xml"> +]> +<document url="nes.html"> + + &project; +<copyright> + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +</copyright> +<properties> +<title>SunOne -- Netscape/iPlanet HowTo</title> +<author email="hgomez@apache.org">Henri Gomez</author> +<author email="jim@apache.org">Jim Jagielski</author> +<author email="shachor@il.ibm.com">Gal Shachor</author> +<author email="mturk@apache.org">Mladen Turk</author> +<date>$Date: 2009-04-07 23:11:25 +0200 (Tue, 07 Apr 2009) $</date> +</properties> +<body> +<section name="Introduction"> +<p> +This document explains how to set up Sun ONE Web Server previously known as +Netscape web servers to cooperate with Tomcat. +</p> + +<p> +Normally the Sun ONE Web Servers come with their own Servlet engine, +but you can also configure them to send servlet and JSP requests to Tomcat +using the NSAPI redirector plugin. +</p> + +<p> +It is recommended that you also read the <a href="../generic_howto/workers.html">Workers HowTo</a> document +to learn how to setup the working entities between your web server and Tomcat Engines. +</p> + + +<subsection name="Document Conventions and Assumptions"> +<p> +${tomcat_home} is the root directory of tomcat. +Your Tomcat installation should have the following subdirectories: + +<ul> +<li> +${tomcat_home}\conf - Where you can place various configuration files +</li> +<li> +${tomcat_home}\webapps - Containing example applications +</li> +<li> +${tomcat_home}\bin - Where you place web server plugins +</li> +</ul> +</p> +<p> +In all the examples in this document ${tomcat_home} will be <b>c:\tomcat</b>. +A worker is defined to be a tomcat process that accepts work from the Sun ONE Web Server. +</p> +</subsection> + + +<subsection name="Supported Configuration"> +<p> +The NSAPI-Tomcat redirector was developed and tested on: +<ul> +<li> +WINNT 2000/XP/2003 (should be able to work with other service packs) and some Unixes +</li> +<li> +Sun ONE Web Server 6.1 +</li> +<li> +Tomcat 4.1.x , Tomcat 5.0.x and Tomcat 5.5.x +</li> +</ul> +</p> + +<p> +The redirector uses <b>ajp12</b> and <b>ajp13</b> to send requests to the Tomcat containers. +There is also an option to use Tomcat in process, +more about the in-process mode can be found in the in process howto. +</p> +</subsection> + +<subsection name="Who support ajp protocols ?"> +<p> +The ajp12 protocol is only available in Tomcat 3.2.x and 3.3.x. +</p> + +<p> +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.0.x, 4.1.x, 5.0.x, 5.5.x and 6. +</p> + +<p> +Of course Tomcat 3.2.x and 3.3.x also support ajp13 protocol. +</p> + +<p> +Others servlet engines such as <b>jetty</b> have support for ajp13 protocol +</p> + +</subsection> + + +<subsection name="How does it work ?"> +<p> +<ol> +<li> +The NSAPI-Tomcat redirector is an Netscape service step plugin, +Netscape load the redirector plugin and calls its service handler +function for request that are assigned to the "servlet" configuration object. +</li> +<li> +For each in-coming request Netscape will execute the set of NameTrans directives +that we added to obj.conf, the assign-name function will check if it's from +parameter matches the request URL. +</li> +<li> +If a match is found, assign-name will assign the servlet object name to the request. +This will cause Netscape to send the request to the servlet configuration object. +</li> +<li> +Netscape will execute our jk_service extension. The extension collects the +request parameters and forwards them to the appropriate worker using the ajp13 protocol +(the worker="defworker" parameter in jk_service inform it that the worker for this request is named <b>defworker</b>). +the workers properties files, <b>workers.properties</b>, will indicate that defworker use ajp13 protocol. +</li> +<li> +The extension collects the response from the worker and returns it to the browser. +</li> +</ol> +</p> +</subsection> + +</section> + +<section name="Installation"> +<p> +A pre-built version of the NSAPI redirector, nsapi_redirect.dll, may be available under +the win32/i386 directory of tomcat-connectors distribution. +For those using Netscape as your browser, try downloading a zip version of the file, if available. + +You can also build a copy locally from the source present in tomcat-connectors distribution. + + +The Tomcat redirector requires two entities: +<ul> +<li> +nsapi_redirect.dll (Windows) -or- nsapi_redirector.so (Unix) - The NSAPI server plugin, either obtain a pre-built DLL/so or build it yourself +(see the build section). +</li> +<li> +workers.properties - A file that describes the host(s) and port(s) used by the workers (Tomcat processes). +A sample workers.properties can be found under the conf directory. +</li> +</ul> + +The installation includes the following parts: + +<ul> +<li> +Configuring the NSAPI redirector with a default /examples context and checking that you can serve servlets +with Netscape. +</li> +<li> +Adding more contexts to the configuration. +</li> +</ul> + +</p> +</section> + +<section name="Configuring the NSAPI Redirector"> +<p> +In this document we'll assume that nsapi_redirect.dll is placed in +<b>c:\jk\lib\nsapi_redirect.dll</b>, the properties file is in<b>c:\jk\conf</b> +and you created a log directory <b>c:\jk\logs</b> +</p> + +<ul> +<li> +If the built in servlet support is working disable it. +</li> +<li> +Add the redirector plugin into the Netscape server configuration. +Edit your server <b>magnus.conf</b> and add the following lines: +</li> +</ul> + +<source> + + Init fn="load-modules" funcs="jk_init,jk_service" shlib="c:/jk/lib/nsapi_redirect.dll" shlib_flags="(global|now)" + Init fn="jk_init" worker_file="c:/jk/conf/workers.properties" log_level="debug" log_file="c:/jk/logs/nsapi.log" shm_file="c:/jk/logs/jk_shm" +</source> +<ul> +<li> +Edit your server <b>obj.conf</b> and add the following lines: +</li> +</ul> +<source> + + + In the default object NameTrans section + <Object name="default"> + + NameTrans fn="assign-name" from="/servlets-examples(|/*)" name="jknsapi" + NameTrans fn="assign-name" from="/jsp-examples(|/*)" name="jknsapi" + .... + </Object> + + Create a new configuration object by adding the following lines to the end of the obj.conf file + + <Object name="jknsapi"> + ObjectType fn=force-type type=text/plain + Service fn="jk_service" method="*" worker="worker1" + </Object> +</source> + +<ul> +<li> +Edit your worker definition file <b>workers.properties</b>. You should at least choose a connection pool size: +</li> +</ul> + +<source> + #An entry that lists all the workers defined. For example: + worker.list=worker1 + + # Entries that define the host and port associated with these workers. + worker.worker1.host=localhost + worker.worker1.port=8009 + worker.worker1.type=ajp13 + worker.worker1.connection_pool_size=50 +</source> + +<ul> +<li> +Restart Web Server (stop and start the server) +</li> +</ul> + +<p> +That's all, now you should start tomcat and ask for http://server:port/servlets-examples/ +</p> +<warn> +The file <b>obj.conf</b> seems to be sensitive to leading white space in lines, especially in +the <b>Object</b> element. Make sure you have no leading white space (no indentation) +on any line of this file. +</warn> + +<subsection name="Adding additional Contexts"> +<p> +The examples context is useful for verifying your installation, but you will also need to add your own contexts. +Adding a new context requires two operations: +</p> +<ul> +<li> +Adding the context to Tomcat (I am not going to talk about this). +</li> +<li> +Assigning the NSAPI redirector to handle this context. +</li> +</ul> + +<p> +Assigning the NSAPI redirector to handle this context is simple, +all you need to do is to edit <b>obj.conf</b> and add a NameTrans line that looks like: +</p> + +<source> + NameTrans fn="assign-name" from="/<context name>/*" name="jknsapi" +</source> + +<p> +After saving <b>obj.conf</b> restart Netscape and it will serve the new context. +</p> +</subsection> + +<subsection name="Advanced Context Configuration"> +<p> +Sometimes it is better to have Netscape serve the static pages (html, gif, jpeg etc.) +even if these files are part of a context served by Tomcat. For example, consider the html and gif files in the examples context, there is no need to serve them from the Tomcat process, Netscape will suffice. +</p> +<p> +Making Netscape serve static files that are part of the Tomcat contexts requires the following: +</p> +<ul> +<li> +Configuring Netscape to know about the Tomcat contexts +</li> +<li> +Make sure that the WEB-INF directory is protected from access. +</li> +<li> +Configuring Netscape to assign the NSAPI redirector only specific requests that requires JSP/Servlet handling. +</li> +</ul> + +<p> +Adding a Tomcat context to Netscape requires the addition of a new Netscape virtual directory +that covers the Tomcat context. +</p> + +<p> +For example, adding a /example Netscape virtual directory that +covers the <b>c:\tomcat\webapps\examples</b> directory. +</p> + +<p> +To add a new virtual directory add the following line to your <b>obj.conf</b>: +</p> + +<source> + NameTrans fn=pfx2dir from=/examples dir="c:/tomcat/webapps/examples" +</source> + +<p> +WEB-INF protection requires some explanation; Each servlet application (context) has a special directory named <b>WEB-INF</b>, +this directory contains sensitive configurations data and Java classes and must be kept hidden from web users. +WEB-INF can be protected by adding the following line to the PathCheck section in the default configuration object: +</p> + +<source> + PathCheck fn="deny-existence" path="*/WEB-INF/*" + + This line instructs the Netscape server to reject any request with a URL that contain the path /WEB-INF/. +</source> + +<p> +Configuring Netscape to assign the NSAPI redirector only specific requests is somewhat harder, +you will need to specify the exact URL-Path pattern(s) that you want Tomcat to handle +(usually only JSP files and servlets). +</p> + +<p> +This requires a change to NameTrans portion of <b>obj.conf</b>. +</p> + +<source> + For the examples context it requires to replace the following line: + + NameTrans fn="assign-name" from="/examples/*" name="jknsapi" + + with the following two lines: + + NameTrans fn="assign-name" from="/examples/jsp/*.jsp" name="jknsapi" + NameTrans fn="assign-name" from="/examples/servlet/*" name="jknsapi" +</source> + +<p> +As you can see the second configuration is more explicit, it actually instructs +Netscape to assign the redirector with only requests to resources under +<b>/examples/servlet/</b> and resources under <b>/examples/</b> whose name ends with <b>.jsp</b>. +</p> + +<p> +You can be even more explicit and provide lines such as: +</p> + +<source> + NameTrans fn="assign-name" from="/examples/servletname" name="jknsapi" + + Instructs Netscape to assign the redirector request whose URL-Path equals /example/servletname +</source> + +</subsection> + +<subsection name="Advanced Worker Configuration"> +<p> +Sometimes you want to serve different contexts with different Tomcat processes +(for example to spread the load among different machines). +To achieve such goal you will need to define several workers and assign each context with its own worker. +</p> + +<p> +Defining workers is done in <b>workers.properties</b>, this file includes two types of entries: +</p> + +<source> + #An entry that lists all the workers defined. For example: + worker.list=worker1,worker2 + + # Entries that define the host and port associated with these workers. + worker.worker1.host=localhost + worker.worker1.port=8009 + worker.worker1.type=ajp13 + + worker.worker2.host=otherhost + worker.worker2.port=8009 + worker.worker2.type=ajp13 +</source> + +<p> +The above examples defined two workers, now we can use these workers to serve two different +contexts each with it's own worker. +Submitting requests to different workers is accomplished by using multiple Service directives +in the servlet configuration Object, each with a different path pattern parameter. +</p> + +<p> +For example, if we want to submit the <b>/examples</b> context to the worker named <b>worker1</b> and the +<b>/webpages</b> context to the worker named <b>worker2</b> we should use the following configuration: +</p> + +<source> + <Object name="jknsapi"> + ObjectType fn=force-type type=text/plain + Service fn="jk_service" worker="worker1" path="/examples/*" + Service fn="jk_service" worker="worker2" path="/webpages/*" + Service fn="jk_service" worker="worker1" + </Object> +</source> + +<p> +More informations on using and configuring workers in the <a href="../generic_howto/workers.html">Workers HowTo</a> +and in the <a href="../reference/workers.html">worker.properties configuration reference</a>. + +</p> +</subsection> + +</section> + +<section name="Building NSAPI DLL redirector for Windows"> +<p> +The redirector was developed using Visual C++ Ver.6.0, so having this environment is a prereq if you want +to perform a custom build. You should also have NES developer SDK + +The steps that you need to take are: +<ul> +<li> +Change directory to the nsapi plugins source directory. +</li> +<li> +Edit <b>nsapi.dsp</b> and update the include and library path to reflect your own Netscape server installation +(search for a <b>/I compiler</b> option and <b>/libpath</b> linker option) +</li> +<li> +Make the source with MSDEV +</li> +</ul> +<screendos> +<notedos>Change directory to the nsapi plugins source directory</notedos> +<typedos>cd c:\home\apache\jk\nsapi</typedos> +<notedos>Build the sources using MSDEV</notedos> +<typedos>MSDEV nsapi.dsp /MAKE ALL</typedos> +</screendos> +</p> +<p> +If msdev is not in your path, enter the full path to msdev.exe. +This will build both release and debug versions of the redirector plugin. +An alternative will be to open the nsapi workspace file (nsapi.dsw) in msdev and +build it using the build menu. +</p> +</section> +<section name="Building NSAPI so plugin redirector for Unix"> +<p> +The redirector requires either gcc (Linux) or gcc or the Sun cc compiler (Solaris). + +The steps that you need to take are: +<ul> +<li> +Change directory to the nsapi plugins source directory (src/native). +</li> +<li> +configure for Netscape/iPlanet/SunONE webserver. +</li> +<li> +Change directory to the nsapi netscape directory (./netstape). +</li> +<li> +Set environment variables JAVA_HOME resp. SUITSPOT_HOME to the location of your Java installation +resp. Netscape server installation. Depending on the web server version, you must add the subdirectory +"plugins" to SUITSPOT_HOME. +The variable is correct, if the file $SUITSPOT_HOME/include/nsapi.h exists. +</li> +<li> +Edit <b>Makefile.solaris</b> resp. <b>Makefile.linux</b> and update the variables according to your needs. +In the Solaris Makefile, you need to switch the commented lines in order to use the Sun compiler cc +instead of GNU gcc. +</li> +<li> +Make the source with gmake. +</li> +</ul> +<screendos> +<notedos>Change directory to the nsapi plugins source directory</notedos> +<typedos>cd /usr/local/src/tomcat-connectors-xxx-src/native</typedos> +<notedos>configure for Netscape/iPlanet/SunONE webserver</notedos> +<typedos>./configure --enable-netscape</typedos> +<notedos>Change directory to the nsapi netscape directory</notedos> +<typedos>cd netscape</typedos> +<notedos>Set JAVA_HOME (ksh example)</notedos> +<typedos>export JAVA_HOME=/path/to/my/java</typedos> +<notedos>Set SUITSPOT_HOME (ksh example)</notedos> +<typedos>export SUITSPOT_HOME=/path/to/my/netscape/server</typedos> +<notedos>Edit the Makefile</notedos> +<typedos>vi Makefile.solaris</typedos> +<notedos>Make the source with gmake</notedos> +<typedos>gmake -f Makefile.solaris</typedos> +</screendos> +</p> +<p> +After the build, you will have the required nsapi_redirector.so plugin. +</p> +</section> +</body> +</document> diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/project.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/project.xml new file mode 100644 index 00000000..16ebf7e3 --- /dev/null +++ b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/webserver_howto/project.xml @@ -0,0 +1,81 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!-- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +<project name="Apache Tomcat Connector Documentation - Webserver HowTo" + href="http://tomcat.apache.org/"> + + <title>The Apache Tomcat Connector - Webserver HowTo</title> + + <logo href="/images/tomcat.gif"> + The Apache Tomcat Connector - Webserver HowTo + </logo> +<body> + + <menu name="Links"> + <item name="Docs Home" href="../index.html"/> + </menu> + + <menu name="Reference Guide"> + <item name="workers.properties" href="../reference/workers.html"/> + <item name="uriworkermap.properties" href="../reference/uriworkermap.html"/> + <item name="Status Worker" href="../reference/status.html"/> + <item name="Apache HTTP Server" href="../reference/apache.html"/> + <item name="IIS" href="../reference/iis.html"/> + </menu> + + <menu name="Generic HowTo"> + <item name="For the impatient" href="../generic_howto/quick.html"/> + <item name="All about workers" href="../generic_howto/workers.html"/> + <item name="Timeouts" href="../generic_howto/timeouts.html"/> + <item name="Load Balancing" href="../generic_howto/loadbalancers.html"/> + <item name="Reverse Proxy" href="../generic_howto/proxy.html"/> + </menu> + + <menu name="Webserver HowTo"> + <item name="Apache HTTP Server" href="../webserver_howto/apache.html"/> + <item name="IIS" href="../webserver_howto/iis.html"/> + <item name="Netscape/SunOne/Sun" href="../webserver_howto/nes.html"/> + </menu> + + <menu name="AJP Protocol Reference"> + <item name="AJPv13" href="../ajp/ajpv13a.html"/> + <item name="AJPv13 Extension Proposal" href="../ajp/ajpv13ext.html"/> + </menu> + + <menu name="Miscellaneous Documentation"> + <item name="Frequently asked questions" href="../miscellaneous/faq.html"/> + <item name="Changelog" href="../miscellaneous/changelog.html"/> + <item name="Current Tomcat Connectors bugs" href="http://issues.apache.org/bugzilla/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=Tomcat+Connectors&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0="/> + <item name="Contribute documentation" href="../miscellaneous/doccontrib.html"/> + <item name="JK Status Ant Tasks" href="../miscellaneous/jkstatustasks.html"/> + <item name="Reporting Tools" href="../miscellaneous/reporttools.html"/> + <item name="Old JK/JK2 documentation" href="http://tomcat.apache.org/connectors-doc-archive/jk2/index.html"/> + </menu> + + <menu name="News"> + <item name="2011" href="../news/20110701.html"/> + <item name="2010" href="../news/20100101.html"/> + <item name="2009" href="../news/20090301.html"/> + <item name="2008" href="../news/20081001.html"/> + <item name="2007" href="../news/20070301.html"/> + <item name="2006" href="../news/20060101.html"/> + <item name="2005" href="../news/20050101.html"/> + <item name="2004" href="../news/20041100.html"/> + </menu> + +</body> +</project> |
