You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2012/03/25 21:53:01 UTC
svn commit: r1305110 [1/10] - in /tomcat/site/trunk/docs/tomcat-3.3-doc: ./
appdev/ appdev/sample/ appdev/sample/etc/ appdev/sample/lib/
appdev/sample/src/ appdev/sample/web/ appdev/sample/web/images/ images/
Author: markt
Date: Sun Mar 25 19:52:59 2012
New Revision: 1305110
URL: http://svn.apache.org/viewvc?rev=1305110&view=rev
Log:
Add Tomcat 3.3 docs
Added:
tomcat/site/trunk/docs/tomcat-3.3-doc/
tomcat/site/trunk/docs/tomcat-3.3-doc/AJPv13.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/JDBCRealm-howto.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/NT-Service-howto.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/Tomcat-Workers-HowTo.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/Tomcat-on-NetWare-HowTo.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/build.xml.txt (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/contents.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/deployment.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/footer.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/header.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/index.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/installation.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/introduction.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/processes.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/sample/
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/sample/build.bat (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/sample/build.sh (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/sample/build.xml (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/sample/etc/
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/sample/etc/web.xml (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/sample/lib/
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/sample/lib/README (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/sample/src/
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/sample/src/Hello.java (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/sample/web/
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/sample/web/hello.jsp (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/sample/web/images/
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/sample/web/images/tomcat.gif (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/sample/web/index.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/source.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/tomcat.gif (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/web.xml.txt (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/faq
tomcat/site/trunk/docs/tomcat-3.3-doc/images/
tomcat/site/trunk/docs/tomcat-3.3-doc/images/banner.gif (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/images/tomcat.gif (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/in-process-howto.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/index.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/internal.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/mod_jk-howto.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/perfNumbers.txt (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/readme (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/readme-3.3.1
tomcat/site/trunk/docs/tomcat-3.3-doc/readme-3.3.2
tomcat/site/trunk/docs/tomcat-3.3-doc/serverxml.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/style.css (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-apache-howto.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-iis-howto.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-netscape-howto.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-security.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-ssl-howto.html (with props)
tomcat/site/trunk/docs/tomcat-3.3-doc/tomcat-ug.html (with props)
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/AJPv13.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/AJPv13.html?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/AJPv13.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/AJPv13.html Sun Mar 25 19:52:59 2012
@@ -0,0 +1,615 @@
+<HTML>
+<HEAD>
+<!--
+ Copyright 200-2004 The Apache Software Foundation
+
+ Licensed 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.
+-->
+<TITLE>Apache JServ Protocol version 1.3</TITLE>
+</HEAD>
+
+<BODY BGCOLOR="#FFFFFF">
+<H1 ALIGN=CENTER>Apache JServ Protocol version 1.3</H1>
+<P>
+
+<DIV ALIGN=CENTER>
+Dan Milstein, <A HREF="mailto:danmil@shore.net">danmil@shore.net</A>, December 2000.
+</DIV>
+
+<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 mod_jk, and for anyone who wants to
+port the protocol somewhere (into jakarta 4.x, for example).
+
+<P><B>Who Am I?</B>
+
+<BR>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>
+<B>Design Goals</B>
+
+<BR> According to email from Gal Shachor to the jakarta-dev mailing list,
+the original goals of <B>mod_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):
+
+<OL>
+ <LI> Increasing performance (speed, specifically).<P>
+
+ <LI> Adding support for SSL, so that <CODE>isSecure()</CODE> and
+ <CODE>geScheme()</CODE> will function correctly within the servlet
+ container. The client certificates and cipher suite will be
+ available to servlets as request attributes.<P>
+
+</OL>
+
+<P>
+<B>Overview</B>
+
+<BR> 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> 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> Once the web server has opened a connection to the servlet container,
+the connection can be in one of the following states:
+
+<UL>
+ <LI> Idle <BR> No request is being handled over this connection. <P>
+ <LI> Assigned <BR> The connecton is handling a specific request.
+</UL>
+
+<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> 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.<P>
+
+ <LI>SEND_BODY_CHUNK <BR>Send a chunk of body data back to the browser.<P>
+
+ <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).<P>
+
+ <LI>END_RESPONSE <BR> Finish the request-handling cycle.
+</UL>
+
+Each message is accompanied by a differently formatted packet of data. See
+Response Packet Structures below for details.
+
+<BR>
+<BR>
+<HR>
+<BR>
+
+<H2>Basic Packet Structure</H2>
+
+<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>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>There are four data types in the protocol: bytes, booleans, integers and
+strings.
+
+<DL>
+ <DT><B>Byte</B></DT>
+ <DD>A single byte.<P></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.<P></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.<P></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.
+</DL>
+
+<P><B>Packet Size</B> <BR> 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><B>Packet Headers</B>
+
+<BR> Packets sent from the server to the container begin with
+<CDOE>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.
+
+<P>
+
+<TABLE BORDER=1 CELLPADDING=2 CELLSPACING=0 BGCOLOR="#FFFFFF">
+ <TR>
+ <TD COLSPAN=6><B>Packet Format (Server->Container)</B></TD>
+ </TR>
+
+ <TR>
+ <TD BGCOLOR="#C0C0C0">Byte</TD>
+ <TD ALIGN=CENTER>0</TD>
+ <TD ALIGN=CENTER>1</TD>
+ <TD ALIGN=CENTER>2</TD>
+ <TD ALIGN=CENTER>3</TD>
+ <TD ALIGN=CENTER WIDTH=100>4...(n+3)</TD>
+ </TR>
+
+ <TR>
+ <TD BGCOLOR="#C0C0C0">Contents</TD>
+ <TD BGCOLOR="#FF9999">0x12</TD>
+ <TD BGCOLOR="#FF9999">0x34</TD>
+ <TD COLSPAN=2 BGCOLOR="#CCFFCC">Data Length (n)</TD>
+ <TD BGCOLOR="#CCFFFF" ALIGN=CENTER>Data</TD>
+ </TR>
+</TABLE>
+
+<P>
+
+<TABLE BORDER=1 CELLPADDING=2 CELLSPACING=0 BGCOLOR="#FFFFFF">
+ <TR>
+ <TD COLSPAN=6><B>Packet Format (Container->Server)</B></TD>
+ </TR>
+
+ <TR>
+ <TD BGCOLOR="#C0C0C0">Byte</TD>
+ <TD ALIGN=CENTER>0</TD>
+ <TD ALIGN=CENTER>1</TD>
+ <TD ALIGN=CENTER>2</TD>
+ <TD ALIGN=CENTER>3</TD>
+ <TD ALIGN=CENTER WIDTH=100>4...(n+3)</TD>
+ </TR>
+
+ <TR>
+ <TD BGCOLOR="#C0C0C0">Contents</TD>
+ <TD BGCOLOR="#FF9999">A</TD>
+ <TD BGCOLOR="#FF9999">B</TD>
+ <TD COLSPAN=2 BGCOLOR="#CCFFCC">Data Length (n)</TD>
+ <TD BGCOLOR="#CCFFFF" ALIGN=CENTER>Data</TD>
+ </TR>
+</TABLE>
+
+
+<A NAME="prefix-codes"><P></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). The web
+server can send the following messages to the servlet container:
+
+<P>
+<TABLE BORDER=2 CELLSPACING=0 CELLPADDING=5>
+ <TR>
+ <TD ALIGN=CENTER>Code</TD>
+ <TD>Type of Packet</TD>
+ <TD>Meaning</TD>
+ </TR>
+ <TR>
+ <TD ALIGN=CENTER>2</TD>
+ <TD>Forward Request</TD>
+ <TD>Begin the request-processing cycle with the following data</TD>
+ </TR>
+ <TR>
+ <TD ALIGN=CENTER>7</TD>
+ <TD>Shutdown</TD>
+ <TD>The web server asks the container to shut itself down.
+ </TR>
+ <TR>
+ <TD ALIGN=CENTER>8</TD>
+ <TD>Ping</TD>
+ <TD>The web server asks the container to quickly respond with a Pong.
+ </TR>
+</TABLE>
+
+<P>The servlet container can send the following types of messages to the web
+server:
+<P>
+<TABLE BORDER=2 CELLSPACING=0 CELLPADDING=5>
+ <TR>
+ <TD>Code</TD>
+ <TD>Type of Packet</TD>
+ <TD>Meaning</TD>
+ </TR>
+ <TR>
+ <TD ALIGN=CENTER>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>
+ <TR>
+ <TD ALIGN=CENTER>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>
+ <TR>
+ <TD ALIGN=CENTER>5</TD>
+ <TD>End Response</TD>
+ <TD>Marks the end of the response (and thus the request-handling cycle).</TD>
+ </TR>
+ </TR>
+ <TR>
+ <TD ALIGN=CENTER>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>
+ <TR>
+ <TD ALIGN=CENTER>9</TD>
+ <TD>Pong</TD>
+ <TD>Reply to a Ping request.</TD>
+ </TR>
+</TABLE>
+
+<P>Each of the above messages has a different internal structure, detailed below.
+
+<BR>
+<BR>
+<HR>
+<BR>
+
+<H2>Request Packet Structure</H2>
+
+<P>For messages from the server to the container of type "Forward Request":
+
+<PRE>
+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)
+ ?jvm_route (byte string)
+ ?ssl_cert (byte string)
+ ?ssl_cipher (byte string)
+ ?ssl_session (byte string)
+
+ ?attributes *(attribute_name attribute_value)
+ request_terminator (byte)
+
+req_header_name :=
+ sc_req_header_name | (string) [see below for how this is parsed]
+
+sc_req_header_name := 0xA0 (byte)
+
+req_header_value := (string)
+
+attribute_name := (string)
+
+attribute_value := (string)
+
+request_terminator := 0xFF
+</PRE>
+
+Not that the all-important header is "content-length', because it
+determines whether or not the container looks for another packet
+immediately.
+
+<P>Details of above
+
+<DL>
+ <DT><B>request_prefix</B></DT>
+ <DD> For all requests, this will be 2. See
+ above for details on other <A HREF="#prefix-codes">prefix codes</A>.<P>
+ </DD>
+
+ <DT><B>method</B></DT>
+ <DD>The HTTP method, encoded as a single byte:
+ <P>
+ <PRE>
+OPTIONS 1
+GET 2
+HEAD 3
+POST 4
+PUT 5
+DELETE 6
+TRACE 7
+PROPFIND 8
+PROPPATCH 9
+MKCOL 10
+COPY 11
+MOVE 12
+LOCK 13
+UNLOCK 14
+ACL 15
+REPORT 16
+VERSION-CONTROL 17
+CHECKIN 18
+CHECKOUT 19
+UNCHECKOUT 20
+SEARCH 21
+ </PRE>
+ <P>
+ </DD>
+
+ <DT><B>protocol, req_uri, remote_addr, remote_host, server_name, server_port, is_ssl</B></DT>
+ <DD>
+ These are all fairly self-explanatory. Each of these is required, and
+ will be sent for every request.<P>
+ </DD>
+
+ <DT><B>Headers</B></DT>
+ <DD>First, the number of headers is encoded. Then, a series of header
+ name / value 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 and their codes is as follows (all are case-sensitive):
+ <PRE>
+accept 0xA001
+accept-charset 0xA002
+accept-encoding 0xA003
+accept-language 0xA004
+authorization 0xA005
+connection 0xA006
+content-type 0xA007
+content-length 0xA008
+cookie 0xA009
+cookie2 0xA00A
+host 0xA00B
+pragma 0xA00C
+referer 0xA00D
+user-agent 0xA00E
+ </PRE>
+
+ The Java code that reads this grabs the first two-byte integer, and, if
+ <A NAME="header_encoding">it sees an '0xA0'</A> 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>
+
+ 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>
+
+ <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>
+
+ <DT><B>Optional Information</B></DT>
+
+ <DD>The list of 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:
+
+ <PRE>
+context 1 [Not currently implemented]
+servlet_path 2 [Not currently implemented]
+remote_user 3
+auth_type 4
+query_string 5
+jvm_route 6
+ssl_cert 7
+ssl_cipher 8
+ssl_session 9
+
+req_attribute 10
+
+terminator 0xFF
+ </PRE>
+
+ 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>
+
+ 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>
+
+ 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>
+
+ The <CODE>jvm_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>
+
+ Beyond this list of basic attributes, any number of other attributes can
+ be sent via the <CODE>req_attribute</CODE> code (10). 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>
+
+ 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 Packets as a whole.<P>
+ </DD>
+</DL>
+
+The server can also send a <code>shutdown</CODE> packet. To ensure some
+basic security, the container will only actually do the shutdown if the
+request comes from the same machine on which it's hosted. <P>
+
+<HR>
+<BR>
+
+<H2>Response Packet Structures</H2>
+
+<P>For messages which the container can send back to the server.
+
+<PRE>
+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)
+</PRE>
+
+Details:
+
+<DL>
+ <DT><B>Send Body Chunk</B></DT>
+ <DD>The chunk is basically binary data, and is sent directly back to the browser.<P>
+ </DD>
+
+ <DT><B>Send Headers</B></DT>
+ <DD>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:
+
+<PRE>
+Content-Type 0xA001
+Content-Language 0xA002
+Content-Length 0xA003
+Date 0xA004
+Last-Modified 0xA005
+Location 0xA006
+Set-Cookie 0xA007
+Set-Cookie2 0xA008
+Servlet-Engine 0xA009
+Status 0xA00A
+WWW-Authenticate 0xA00B
+</PRE>
+
+ After the code or the string header name, the header value is immediately
+ encoded.<P>
+
+ <DT><B>End Response</B></DT>
+ <DD> 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>
+
+ <DT><B>Get Body Chunk</B></DT>
+ <DD> The container asks for more data from the request (if the body was
+ too large to fit in the first packet sent over). 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 (XXX), and the
+ number of bytes actually left to send from the request body.<P>
+
+ 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, whch is a body packet with a payload length of 0.
+
+</DL>
+
+<P>
+
+<HR>
+
+<H2>Questions I Have</H2>
+
+<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> 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.
+
+
+</BODY>
+</HTML>
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/AJPv13.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/JDBCRealm-howto.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/JDBCRealm-howto.html?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/JDBCRealm-howto.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/JDBCRealm-howto.html Sun Mar 25 19:52:59 2012
@@ -0,0 +1,278 @@
+<html>
+<head>
+<!--
+ Copyright 1999-2004 The Apache Software Foundation
+
+ Licensed 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.
+-->
+<link rel="stylesheet" href="style.css">
+<style type="text/css">
+ td {
+ background-color: #E0E0E0;
+ vertical-align: text-top;
+ }
+ th {
+ background-color: #d0d0d0;
+ }
+ table {
+ width: 75%;
+ background-color: #000000;
+ }
+ </style>
+<title>Working with JDBCRealm</title></head><body>
+<h1>Working with JDBCRealm</h1>
+<h2>What is JDBCRealm?</h2>
+<p>Is an implementation of a tomcat 3.X Realm that use a set of configurable tables inside a RDMS to store user's data, this tables are accessed by means of standard JDBC drivers.<br>
+The passwords can be stored as digested ( using standard Java's MessageDigest ) or in plain form.<br>
+All the parameters, drivers, tables, and columns are user configurable. </p>
+<h2>Example Config for JDBCRealm</h2>
+This is an example of how to set up a JDBC Realm. For this example I used the MySQL JDBC driver.
+<h3>1. Create a database. </h3>
+<blockquote>
+<p> I made the database named "authority"</p>
+</blockquote>
+<h3> 2. Create needed tables. </h3>
+<blockquote>
+<h4> 1. The user table. </h4>
+<blockquote>
+<p>This table needs the user's name and a password field. In the example I use "users" for the table name, "user_name" for the column that holds the user's name, and "user_pass" for the user's password. </p>
+</blockquote>
+<h4>2. The role table. </h4>
+<blockquote>
+<p>This table needs the role's set up that will be in any deployment descriptor that is managed under the container this Realm is in. In the example I use "roles" as the table name and "role_name" as the role's name. NB: This table doesn't get used at all by tomcat. </p>
+</blockquote>
+<h4>3. The role to user table. </h4>
+<blockquote>
+<p>This table joins a set of roles to a single user. In the example the table name is "user_roles", the role's name is "role_name" , and the user's name is assumed to have the same column name as in the user's table ("user_name" in this example. </p>
+<p>Here is the SQL I used to create the tables:
+</p>
+</blockquote>
+</blockquote>
+<table align="center">
+<tr>
+<td>
+<pre>create table users
+(
+ user_name varchar(15) not null primary key,
+ user_pass varchar(15) not null
+);
+
+
+create table roles
+(
+ role_name varchar(15) not null primary key
+);
+
+create table user_roles
+(
+ user_name varchar(15) not null,
+ role_name varchar(15) not null,
+ primary key( user_name, role_name )
+);
+
+</pre>
+</td>
+</tr>
+</table>
+<blockquote>
+<blockquote>
+<p><br>
+Here is sample output from the tables:
+<br>
+<br>
+</p>
+</blockquote>
+</blockquote>
+<table align="center" border="0">
+<tr>
+<td>
+<pre>
+mysql> select * from users;
++-----------+-----------+
+| user_name | user_pass |
++-----------+-----------+
+| tomcat | tomcat |
+| user1 | tomcat |
+| user2 | tomcat |
+| user3 | tomcat |
++-----------+-----------+
+4 rows in set (0.00 sec)
+
+mysql>
+mysql> select * from roles;
++------------+
+| role_name |
++------------+
+| tomcat |
+| role1 |
++------------+
+2 rows in set (0.02 sec)
+
+mysql>
+
+
+mysql> select * from user_roles;
++------------+-----------+
+| role_name | user_name |
++------------+-----------+
+| tomcat | user1 |
+| role1 | user2 |
+| tomcat | tomcat |
+| role1 | tomcat |
++------------+-----------+
+4 rows in set (0.00 sec)
+
+mysql>
+</pre>
+</td>
+</tr>
+
+</table>
+<h3>3. Configure Tomcat </h3>
+<blockquote>
+<p>Add the information to the server.xml file. For this example I used this entry inside: </p>
+</blockquote>
+<table width="100%" border="0" align="center">
+<tr>
+<td>
+<blockquote>
+<p><code><br>
+<JDBCRealm"<br>
+
+ debug="99"
+ driverName="org.gjt.mm.mysql.Driver" <br>
+
+ connectionURL="jdbc:mysql://localhost/authority?user=test;password=test"
+ userTable="users"<br>
+
+ userNameCol="user_name"<br>
+
+ userCredCol="user_pass"<br>
+
+ userRoleTable="user_roles"
+ roleNameCol="role_name" />
+<br>
+</code></p>
+</blockquote>
+</td>
+</tr>
+</table>
+<p>The meaning of the attributes is as follow:</p>
+<table align="center" width="51%">
+<tr>
+<th height="32">
+<p>attribute</p>
+</th>
+<th>Meaning</th>
+</tr>
+
+<tr>
+<td height="32"> driverName</td>
+<td height="32"> The name of the driver needed to connect to the database
+ </td>
+</tr>
+<tr>
+<td height="32">connectionURL</td>
+<td height="32"> The connection URL used to connect to the database
+</td>
+</tr>
+<tr>
+<td height="32">userTable</td>
+<td> The user's tables
+</td>
+</tr>
+<tr>
+<td height="32">userNameCol</td>
+<td> The column in the user's table that contains the name
+</td>
+</tr>
+<tr>
+<td height="32">userCredCol</td>
+<td> The column in the user's table that contains the password
+</td>
+</tr>
+<tr>
+<td height="33">userRoleTable</td>
+<td height="33"> The user's roles table
+</td>
+</tr>
+<tr>
+<td height="32">roleNameCol</td>
+<td> The column in the user's table that contains a role given
+ to a user
+</td>
+</tr>
+
+<tr>
+<td height="32"> connectionName</td>
+<td> The name to use when connecting to the database.
+(Optional)</td>
+</tr>
+<tr>
+<td height="32">connectionPassword</td>
+<td>The password to use when connecting to the database.
+(Optional)
+</td>
+</tr>
+<tr>
+<td height="32">digest </td>
+<td>The algorithm used for digest passwords or "No" for
+ plain passwords, the values can be
+ "MD5", "MD2", "SHA",
+ etc...
+<a href=
+"http://java.sun.com/products/jdk/1.2/docs/guide/security/CryptoSpec.html#AppA"
+>(Optional)</a></td>
+</tr>
+</table>
+<p> </p>
+<p>Done!!
+</p>
+<h2>Using digested passwords</h2>
+
+<p>
+ To use digested password you need to store them digested. To
+ achieve this, you will need to use the same digest strategies that
+ JDBCrealm uses to store the passwords. Iinside JDBCRealm there is a
+ static method with signature <code>final public static String
+ digest(String password,String algorithm)</code>. This method is
+ provided as a tool to be used outside JDBCRealm by an application
+ that wants to generate digested passwords readable by JDBCRealm.
+</p>
+
+<p>
+ The class JDBCRealm contains a main method, so it can be used as an
+ application to generate digests and print them to stdout. Usage
+ is:<br>
+
+ <code>java org.apache.tomcat.modules.aaa.RealmBase -a
+ <<i>algorithm</i>> <<i>password</i>>
+ [<<i>password</i>> ...]</code><br>
+
+ where <<i>algorithm</i>> is a supported message digest
+ algorithm, e.g. MD5, and <<i>password</i>> is a plaintext
+ password to be digested.
+</p>
+<p>
+ Note: the jar where RealmBase class can be found is %TOMCAT_HOME%/lib/container/tomcat_modules.jar
+</p>
+<h2>Hints</h2>
+<p>
+
+ - Make sure that the JDBC driver is in the lib/container directory.
+<br>
+- If you have problem connecting you can specify connectionName and connectionPassword</p>
+<div align="center">$Header: /home/cvspublic/jakarta-tomcat/src/doc/JDBCRealm-howto.html,v 1.7 2004/02/29 22:42:50 billbarker Exp $
+</div>
+</body>
+</html>
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/JDBCRealm-howto.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/NT-Service-howto.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/NT-Service-howto.html?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/NT-Service-howto.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/NT-Service-howto.html Sun Mar 25 19:52:59 2012
@@ -0,0 +1,171 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+ <!-- $Id: NT-Service-howto.html,v 1.7 2004/02/29 22:42:50 billbarker Exp $ -->
+<!--
+ Copyright 1999-2004 The Apache Software Foundation
+
+ Licensed 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.
+-->
+
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+
+ <link rel="stylesheet" href="style.css">
+ <title>Working with the Jakarta NT Service</title>
+
+</head>
+ <body>
+<h1>Working with the Jakarta NT Service</h1>
+<p>By Gal Shachor <tt><<a href="mailto:shachor@il.ibm.com">shachor@il.ibm.com</a>
+ ></tt><br>
+ Modified by Dave Oxley <<a href="mailto:dave@junglemoss.com">dave@junglemoss.com</a>
+ ><br>
+</p>
+<p>The Jakarta NT service is an executable that wraps the Tomcat servlet container
+and executes it in the background as an NT service. To install it you will
+need to:</p>
+<ol>
+ <li>Get a hold on the NT executable (jk_nt_service.exe)</li>
+ <ul>
+ <li>Download the executable from the win32/i386 directory found
+ where you downloaded the <a href="http://jakarta.apache.org/site/binindex.html">
+ Tomcat binary distribution.</a>
+ 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.</li>
+ </ul>
+ <li>Customize a properties file that provides the service with Tomcat
+ information (wrapper.properties).</li>
+ <ul>
+ <li>Locate the wrapper.properties template file in your Tomcat conf/jk
+ directory. </li>
+ <li>Update the wrapper.tomcat_home property to point at your tomcat
+ home.</li>
+ <li>Update the wrapper.java_home property to point at your Java
+ home.</li>
+ </ul>
+ <li>Install jk_nt_service by running it with the -i flag.</li>
+ <ul>
+ <li>Execute jk_nt_service -I <name of service> <optional
+ params> <path to updated wrapper properties></li>
+ <li><name of service> should be a single word (without and
+ spaces) such as Jakarta</li>
+ <li><optional params> are any of the following:</li>
+ <ul>
+ <li>-U <user name> - to set the user the service runs as. Make
+ sure the user has 'Logon as a service right'. The <user name> must
+be in the format DomainName\UserName (e.g. Dev\Administrator for Administrator
+ in the Dev domain or .\Administrator for the local Administrator)</li>
+ <li>-P <user password> - Valid password for the user.</li>
+ <li>-A - Sets the service to startup automatically.</li>
+ <li>-D <service dependancy> - This sets the service that must
+ be started prior to this one. -D <service dependancy> can be specified
+ multiple times. <service dependancy> must be the 'Service Name' not
+ the 'Display Name'.<br>
+ </li>
+ </ul>
+ <li><path to updated wrapper properties> should point to your
+wrapper.properties file (and the service will check it's existence.)</li>
+ <li>For example, valid command lines can be:</li>
+ <ul>
+ <li>jk_nt_service -I Jakarta wrapper.properties</li>
+ <li>jk_nt_service -I Jakarta -U .\Administrator -P password -A -D MSSQLSERVER
+ wrapper.properties</li>
+ </ul>
+ </ul>
+ <li>Start tomcat as a service.</li>
+ <ul>
+ <li>From the command line, execute jk_nt_service -S <name of service>
+ <optional param> where <optional param> is:</li>
+ <ul>
+ <li>-M <machine name> - Remote machine to start the service on.
+ (e.g. jk_nt_service -S Jakarta -M DevBox)<br>
+ </li>
+ </ul>
+ <li>From the command line, execute net start <name of service>
+ (e.g. net start Jakarta)</li>
+ <li>From the NT services applet, highlight your service and press
+ start.</li>
+ </ul>
+ <b>Note:</b> If the log file location in your wrapper.properties file points
+to the <tt>logs</tt> directory, and the <tt>logs</tt> directory doesn't
+yet exist, manually create it before starting the service.
+ <li>Stop Tomcat as a service.</li>
+ <ul>
+ <li>From the command line, execute jk_nt_service -T <name of service>
+ <optional param> where <optional param> is:</li>
+ <ul>
+ <li>-M <machine name> - Remote machine to stop the service on.
+ (e.g. jk_nt_service -T Jakarta -M DevBox)<br>
+ </li>
+ </ul>
+ <li>From the command line, execute net stop <name of service>
+ (e.g. net stop Jakarta)</li>
+ <li>From the NT services applet, highlight your service and press
+ stop.</li>
+ </ul>
+</ol>
+<p><b>Special note</b>: The Tomcat service is using AJPV12 to perform clean
+ shutdown and you should make sure that an AJPV12 connector is defined in
+your server.xml. In the absence of a configured AJPV12 port the Tomcat service
+ will kill Tomcat abruptly (that is murder it) without giving it a chance
+to clean up. </p>
+<p><b>Special note2</b>: Acording to <a href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=2337%22">
+ http://nagoya.apache.org/bugzilla/show_bug.cgi?id=2337</a>
+ , you may have problems with long filenames. You should use the 8.3 format.
+ Thanks to Anthony Dodd for finding this workaround.</p>
+<p><strong>Notice for JDK 1.3 users</strong>: There is a <a href="http://developer.java.sun.com/developer/bugParade/bugs/4323062.html">
+ known problem</a>
+ in JDK 1.3 that affects Java applications being run as Windows NT services.
+ The bug causes the service to terminate when the currently logged in user
+ logs out. The simplest way to work around this problem is to use JDK 1.2.
+ If your application requires JDK 1.3 features then you may want to look
+into <a href="http://www.kcmultimedia.com/javaserv/">javaserv</a>
+ or <a href="http://www.alexandriasc.com/software/JavaService/">JavaService</a>
+ . Users have reported success with both of these packages but there may
+ be others that work as well. </p>
+<p>To remove the installed service, execute jk_nt_service -R <name of service></p>
+<h1>Advance Setup</h1>
+<ol>
+ <li>Modify the Tomcat NT service properties. By default the service
+ will run in manual mode and under the local system user account. To
+modify this, open the NT services applet, highlight your service and
+press startup. A popup window is opened and you will be able to customize
+the service to your satisfaction.</li>
+ <li>Modify the classpath. The classpath is determined by the wrapper.class_path
+ properties, to modify it just add/remove/modify wrapper.class_path
+lines. The complete classpath is calculated by concatenating all the
+ wrapper.class_path lines and putting ";" between them.</li>
+ <li>Execute several Tomcat instances. Say that you want one Tomcat
+ to run for "production" and one for development, you can do that. All
+ you will need to do is to install the Tomcat service twice and under
+ two different names (and with different wrapper.properties file and
+server.xml files). </li>
+ <ul>
+ <li>Make sure that the AJPV12 and HTTP connectors are modified in
+each server.xml file to prevent a clash.</li>
+ <li>Make sure to update the wrapper.shutdown_port property in wrapper.properties
+ to point to the correct AJPV12 shutdown ports (default is 8007).
+ </li>
+ </ul>
+ <li>Modify the command line used to start Tomcat. The Tomcat service
+ is taking all it's command line configuration from wrapper.properties!
+ To customize the command line, edit the property wrapper.cmd_line and
+ make sure that it makes a legal Java command line.</li>
+</ol>
+<h1>Feedback</h1>
+<p>Please send feedback, bug report or any additional information to <tt>
+ <<a href="mailto:tomcat-user@jakarta.apache.org">tomcat-user@jakarta.apache.org</a>
+ > </tt></p>
+</body>
+</html>
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/NT-Service-howto.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/Tomcat-Workers-HowTo.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/Tomcat-Workers-HowTo.html?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/Tomcat-Workers-HowTo.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/Tomcat-Workers-HowTo.html Sun Mar 25 19:52:59 2012
@@ -0,0 +1,617 @@
+<html>
+
+<head>
+ <!-- $Id: Tomcat-Workers-HowTo.html,v 1.4 2004/02/29 22:42:50 billbarker Exp $ -->
+<!--
+ Copyright 1999-2004 The Apache Software Foundation
+
+ Licensed 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.
+-->
+
+ <meta http-equiv=Content-Type content="text/html">
+ <link rel="stylesheet" href=style.css>
+ <style type="text/css">
+ td {
+ background-color: #E0E0E0;
+ vertical-align: text-top;
+ border-top: thick black;
+ border-right: thick black;
+ border-bottom: thick black;
+ border-left: thick black;
+ }
+ th {
+ background-color: #d0d0d0;
+ border-top: thick black;
+ border-right: thick black;
+ border-bottom: thick black;
+ border-left: thick black;
+ }
+ table {
+ width: 75%;
+ border: thick;
+ background-color: #000000;
+ }
+ </style>
+<title>Tomcat Workers HowTo</title>
+</head>
+
+<body>
+<h1>Tomcat workers.properties</h1>
+
+<p>By Gal Shachor <tt><<a href="mailto:shachor@il.ibm.com">
+shachor@il.ibm.com</a>></tt></p>
+
+<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... </p>
+
+<p>Tomcat workers are defined in a properties file dubbed
+workers.properties and this tutorial explains how to work with it.</p>
+
+<h2>Defining Workers</h2>
+
+<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); the file contains entries of the following form:</p>
+
+<p>worker.list=<a comma separated list of worker names></p>
+
+<p>For example, <tt>worker.list= ajp12, ajp13</tt></p>
+
+<p>And </p>
+
+<p>worker.<worker name>.<property>=<property
+value></p>
+
+<p>For example, <tt>worker.local.port=8007</tt></p>
+
+<p>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>
+
+<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 (Tomcat 3.2-dev): </p>
+
+<table>
+ <tr>
+ <th>
+ <p>Worker type</p>
+ </th>
+ <th>
+ <p>Description</p>
+ </th>
+ </tr>
+ <tr>
+ <td bgcolor="#FeFeFe">ajp12</p>
+ </td>
+ <td bgcolor="#FeFeFe">
+ <p>This worker knows how to forward requests to
+ out-of-process Tomcat workers using the ajpv12 protocol.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>ajp13</p>
+ </td>
+ <td>
+ <p>This worker knows how to forward requests to
+ out-of-process Tomcat workers using the ajpv13 protocol.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>jni</p>
+ </td>
+ <td>
+ <p>This worker knows how to forward requests to in-process
+ Tomcat workers using JNI.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>lb</p>
+ </td>
+ <td>
+ <p>This is a load-balancing worker; it knows how to provide
+ round-robin based sticky load balancing with a certain level of
+ fault-tolerance.</p>
+ </td>
+ </tr>
+</table>
+
+<p>Defining workers of a certain type should be done with the
+following property format:</p>
+
+<p>worker.<worker name>.type=<worker type></p>
+
+<p>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
+not contain any space (a good naming convention for queue named should follow
+the Java variable naming rules).</p>
+
+<p>For example:</p>
+
+<table>
+ <tr>
+ <th>
+ <p>Worker definition</p>
+ </th>
+ <th>
+ <p>Meaning</p>
+ </th>
+ </tr>
+ <tr>
+ <td>
+ <p>worker.local.type=ajp12</p>
+ </td>
+ <td>
+ <p>Defines a worker named "local" that uses the ajpv12 protocol
+ to forward requests to a Tomcat process.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>worker.remote.type=ajp13</p>
+ </td>
+ <td>
+ <p>Defines a worker named "remote" that uses the ajpv13 protocol
+ to forward requests to a Tomcat process.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>worker.fast.type=jni</p>
+ </td>
+ <td>
+ <p>Defines a worker named "fast" that uses JNI
+ to forward requests to a Tomcat process.</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>worker.loadbalancer.type=lb</p>
+ </td>
+ <td>
+ <p>Defines a worker named "loadbalancer" that
+ loadbalances several Tomcat processes transparently.</p>
+ </td>
+ </tr>
+</table>
+
+<h2>Setting Worker Properties</h2>
+
+<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>
+
+<p>Each worker has a set of properties that you can set as
+specified in the following subsections:</p>
+
+<h3>ajp12 Worker properties</h3>
+
+<p>The ajp12 typed workers forward requests to out-of-process
+Tomcat workers using the ajpv12 protocol over TCP/IP sockets. The following
+table specifies properties that the ajp12 worker can accept:</p>
+
+<table>
+ <tr>
+ <th>
+ <p>Property name</p>
+ </th>
+ <th>
+ <p>Meaning</p>
+ </th>
+ <th>
+ <p>Example</p>
+ </th>
+ </tr>
+ <tr>
+ <td>
+ <p>port</p>
+ </td>
+ <td>
+ <p>The port where the Tomcat worker is listening for ajp12
+ requests.</p>
+ </td>
+ <td>
+ <p>worker.local.port=8007</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>host</p>
+ </td>
+ <td>
+ <p>The host where the Tomcat worker is listening for ajp12
+ requests.</p>
+ </td>
+ <td>
+ <p>worker.local.host=www.x.com</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>lbfactor</p>
+ </td>
+ <td>
+ <p>When working with a load balancer worker, this is the
+ load-balancing factor for the worker. (More on this in the lb worker section).</p>
+ </td>
+ <td>
+ <p>worker.local.lbfactor=2.5</p>
+ </td>
+ </tr>
+</table>
+
+<h3>ajp13 Worker properties</h3>
+
+<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:</p>
+
+<ol>
+ <li>ajpv13
+ is a more binary protocol and it try to compress some of the request data
+ by coding frequently used strings as small integers.</li>
+ <li>ajpv13
+ reuse open sockets and leaves them open for future requests.</li>
+ <li>ajpv13
+ has special treatment for SSL information so that the container can
+ implement SSL related methods such as isSecure().</li>
+</ol>
+
+
+
+<p>The following table specifies properties that the ajp13
+worker can accept:</p>
+
+<table>
+ <tr>
+ <th>
+ <p>Property name</p>
+ </th>
+ <th>
+ <p>Meaning</p>
+ </th>
+ <th>
+ <p>Example</p>
+ </th>
+ </tr>
+ <tr>
+ <td>
+ <p>port</p>
+ </td>
+ <td>
+ <p>The port where the Tomcat worker is listening for ajp13
+ requests.</p>
+ </td>
+ <td>
+ <p>worker.local13.port=8007</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>host</p>
+ </td>
+ <td>
+ <p>The host where the Tomcat worker is listening for ajp13
+ requests.</p>
+ </td>
+ <td>
+ <p>worker.local13.host=www.x.com</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>lbfactor</p>
+ </td>
+ <td>
+ <p>When working with a load balancer worker, this is the
+ load-balancing factor for the worker. (More on this in the lb worker
+ section).</p>
+ </td>
+ <td>
+ <p>worker.local13.lbfactor=2.5</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>cachesize</p>
+ </td>
+ <td>
+ <p>Specifies the number of open socket connections that the
+ worker will keep. By default this value is 1, but multithreaded web servers
+ such as Apach2.xx, IIS and Netscape will benefit the most by setting this
+ value to a higher level (such as the estimated average concurrent users for
+ Tomcat)</p>
+ </td>
+ <td>
+ <p>worker.local13.cachesize=30</p>
+ </td>
+ </tr>
+</table>
+
+<h3>lb Worker properties</h3>
+
+<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
+ 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>
+
+<p>The following table specifies properties that the lb worker
+can accept:</p>
+
+<table>
+ <tr>
+ <th>
+ <p>Property name</p>
+ </th>
+ <th>
+ <p>Meaning</p>
+ </th>
+ <th>
+ <p>Example</p>
+ </th>
+ </tr>
+ <tr>
+ <td>
+ <p>balanced_workers</p>
+ </td>
+ <td>
+ <p>A comma separated list of workers that the load balancer
+ need to manage. These workers should not appear in the worker.list
+ property.</p>
+ </td>
+ <td>
+ <p>worker.loadbalancer.balanced_workers= local13, local12</p>
+ </td>
+ </tr>
+</table>
+
+<h3>jni Worker properties</h3>
+
+<p>The jni worker opens a JVM inside the web server process and
+executes Tomcat within it (that is in-process). Following that, messages to and
+from the JVM are passed using JNI method calls, this makes the jni worker
+faster then the out-of-process workers that need to communicate to the Tomcat
+workers by writing AJP messages over TCP/IP sockets.</p>
+
+<p>Note: Since the JVM is multithreaded; the jni worker should
+be used only within multithreaded servers such as AOLServer, IIS, Netscape and
+Apache2.0. You should also make sure that the threading scheme used by the web
+servers match the one used to build the jk web server plugin.</p>
+
+<p>Since the jni worker opens a JVM it can accept many
+properties that it forward to the JVM such as the classpath etc. as we can see
+in the following table.</p>
+
+<table>
+ <tr>
+ <th>
+ <p>Property name</p>
+ </th>
+ <th>
+ <p>Meaning</p>
+ </th>
+ <th>
+ <p>Example</p>
+ </th>
+ </tr>
+ <tr>
+ <td>
+ <p>class_path</p>
+ </td>
+ <td>
+ <p>The classpath as used by the in-process JVM. This should
+ point to all Tomcats' jar/file files as well as any class or other jar file
+ that you want to add to the JVM.</p>
+
+ <p>You should remember to also add Javac to the classpath.
+ This can be done in Java2 by adding tools.jar to the classpath. In JDK1.xx
+ you should just add classes.zip.</p>
+
+ <p>The class_path property can be given in multiple lines. In
+ this case the jk environment will concatenate all the classpath entries
+ together by putting path delimiter (":"/";") between the
+ entries.</p>
+ </td>
+ <td>
+ <p>worker.localjni.class_path=path-to-some-jarfile</p>
+ <p>worker.localjni.class_path=path-to-class-directory</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>cmd_line</p>
+ </td>
+ <td>
+ <p>The command line that is handed over to Tomcats' startup
+ code. </p>
+
+ <p>The cmd_line property can be given in multiple lines. In
+ this case the jk environment will concatenate all the cmd_line entries
+ together by putting spaces between the entries.</p>
+ </td>
+ <td>
+ <p>worker.localjni.cmd_line=-config</p>
+ <p>worker.localjni.cmd_line=path-to-tomcats-server.xml-file</p>
+ <p>worker.localjni.cmd_line=-home</p>
+ <p>worker.localjni.cmd_line=-path-to-tomcat-home</p>
+
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>jvm_lib</p>
+ </td>
+ <td>
+ <p>Full path to the JVM implementation library. The jni
+ worker will use this path to load the JVM dynamically.</p>
+ </td>
+ <td>
+ <p>worker.localjni.jvm_lib=full-path-to-jvm.dll</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>stdout</p>
+ </td>
+ <td>
+ <p>Full path to where the JVM write its System.out</p>
+ </td>
+ <td>
+ <p>worker.localjni.stdout=full-path-to-stdout-file</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>stderr</p>
+ </td>
+ <td>
+ <p>Full path to where the JVM write its System.err</p>
+ </td>
+ <td>
+ <p>worker.localjni.stderr=full-path-to-stderr-file</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>sysprops</p>
+ </td>
+ <td>
+ <p>Java system properties for the JVM</p>
+ </td>
+ <td>
+ <p>worker.localjni.sysprops=some-property</p>
+ </td>
+ </tr>
+ <tr>
+ <td>
+ <p>ld_path</p>
+ </td>
+ <td>
+ <p>Additional dynamic libraries path (similar in nature to
+ LD_LIBRARY_PATH)</p>
+ </td>
+ <td>
+ <p>worker.localjni.ld_path=some-extra-dynamic-library-path</p>
+ </td>
+ </tr>
+</table>
+
+<h2>Property file macros</h2>
+
+<p>Starting with Tomcat3.2 you can define "macros" in
+the property files. These macros let you define properties and later on use
+them while constructing other properties. For example the following fragment:</p>
+
+<pre>
+workers.tomcat_home=d:\tomcat
+workers.java_home=d:\sdk\jdk1.2.2
+ps=\
+worker.inprocess.class_path=$(workers.tomcat_home)$(ps)classes
+worker.inprocess.class_path=$(workers.java_home)$(ps)lib$(ps)tools.jar
+</pre>
+
+<p>Will end up with the following values for the
+worker.inprocess.class_path properties</p>
+
+<pre>
+worker.inprocess.class_path= d:\tomcat\classes
+worker.inprocess.class_path=d:\sdk\jdk1.2.2\lib\tools.jar
+</pre>
+
+<h2>The sample worker.properties</h2>
+
+<p>Since coping with worker.properties on your own is not an
+easy thing to do, a sample worker.properties file is bundled along with
+Tomcat3.2-dev (and above). The file is meant to be as <b>generic</b> as
+possible and it uses the property macros extensively.</p>
+
+<p>The sample worker.properties contains the following high
+level definitions:</p>
+
+<ol>
+ <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>A jni
+ worker</li>
+ <li>A lb
+ worker that load balance the ajp12 and ajp13 workers</li>
+</ol>
+
+<p>The ajp12, ajp13 and lb worker definitions can work without
+modifying the file. However to make the jni worker come into life you should
+set the following properties in the file:</p>
+
+<ul>
+ <li>workers.tomcat_home
+ - Have it point to your tomcat_home. E.g. wrkers.tomcat_home=d:\tomcat</li>
+ <li>workers.java_home
+ - Have it point to where you placed your JDK. E.g.
+ workers.java_home=c:\jdk1.2.2</li>
+ <li>ps - Have it point to the file system
+ separator of your OS. E.g. ps=\</li>
+</ul>
+
+<p>When you are done, the default jni worker <b>should</b>
+work.</p>
+
+</body>
+</html>
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/Tomcat-Workers-HowTo.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/Tomcat-on-NetWare-HowTo.html
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/Tomcat-on-NetWare-HowTo.html?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/Tomcat-on-NetWare-HowTo.html (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/Tomcat-on-NetWare-HowTo.html Sun Mar 25 19:52:59 2012
@@ -0,0 +1,352 @@
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <title>Tomcat on NetWare HowTo</title>
+<!-- $Id $ -->
+<!-- Copyright 1999, Apache Software Foundation -->
+<link rel="stylesheet" href="style.css">
+ <style type="text/css">
+ .inlinetd {
+ background-color: #E0E0E0;
+ vertical-align: text-top;
+ border-top: thick black;
+ border-right: thick black;
+ border-bottom: thick black;
+ border-left: thick black;
+ }
+ .inlineth {
+ background-color: #d0d0d0;
+ border-top: thick black;
+ border-right: thick black;
+ border-bottom: thick black;
+ border-left: thick black;
+ }
+ .inlinetable {
+ width: 75%;
+ border: thick;
+ background-color: #000000;
+ }
+ .subsection { margin:20pt; }
+ .note { margin:20pt; padding:5pt; background-color:#e0e0ff; }
+
+ </style>
+</head>
+<body>
+<!-- Banner element, all hail Jakarta! -->
+<table BORDER=0 CELLSPACING=0 CELLPADDING=0 WIDTH="100%" >
+ <tr>
+ <td WIDTH="50%">
+ <a href="http://jakarta.apache.org/index.html">
+ <img SRC="images/banner.gif" ALT="The Jakarta Project" BORDER=0 height=48 width=505>
+ </a>
+ </td>
+ <td WIDTH="50%">
+ <div align=right>
+ <img SRC="images/tomcat.gif" ALT="The mighty Tomcat - Meow!" BORDER=0 height=71 width=100>
+ </div>
+ </td>
+ </tr>
+</table>
+
+<h1>
+Tomcat on NetWare HowTo</h1>
+By Mike Anderson <a href="mailto:mmanders@novell.com">mmanders@novell.com</a>
+<p>This document explains how to setup Tomcat to run on NetWare. Sections
+are provided for running Tomcat standalone, running with the NetWare Enterprise
+Web Server, and running with Apache on NetWare. There is also a section
+describing how to build the web server connectors for NetWare. A lot of
+this is duplicated from the <a href="tomcat-netscape-howto.html">Tomcat
+Netscape HowTo</a> and <a href="mod_jk-howto.html">Working with mod_jk</a>,
+both written by Gal Shachor <a href="mailto:shachor@il.ibm.com">shachor@il.ibm.com</a>
+with NetWare specific information added.
+<h2>
+Table of Contents</h2>
+
+<ul>
+<li>
+<a href="#Document Conventions and Assumptions">Document Conventions and
+Assumptions</a></li>
+
+<li>
+<a href="#Tested Configurations">Tested Configurations</a></li>
+
+<li>
+<a href="#Installation">Installation</a></li>
+
+<ul>
+<li>
+<a href="#Running Tomcat Standalone">Running Tomcat Standalone</a></li>
+
+<li>
+<a href="#Running Tomcat with the NetWare Enterprise Web Server">Running
+Tomcat with the NetWare Enterprise Web Server</a></li>
+
+<li>
+<a href="#Running Tomcat with Apache on NetWare">Running Tomcat with Apache
+on NetWare</a></li>
+
+<li>
+</li>
+</ul>
+
+<li>
+<a href="#Building Tomcat for use on NetWare">Building Tomcat for use on NetWare</a>
+</li>
+</ul>
+
+<h2>
+<a NAME="Document Conventions and Assumptions"></a>Document Conventions
+and Assumptions</h2>
+<tomcat_home> is the root directory of Tomcat. By default this is at
+the root of the SYS: volume (SYS:\jakarta-tomcat-3.3 by default for Tomcat 3.3) but it can be placed anywhere, on any volume.
+Your installation should have the following sub-directories:
+<ol>
+<li>
+<tomcat_home>\conf - Where you can place various configuration files</li>
+
+<li>
+<tomcat_home>\webapps - Contains example applications and is the default
+place for adding your applications</li>
+
+<li>
+<tomcat_home>\bin - Where you place web server connectors and startup
+scripts</li>
+</ol>
+In all the examples in this document, <tomcat_home> will be
+SYS:\jakarta-tomcat-3.3.
+<p>A <b><tt>worker</tt></b> is the tomcat process that accepts work from
+the web server.
+<h2>
+<a NAME="Tested Configurations"></a>Tested Configurations</h2>
+Tomcat and the web server connectors described here have been tested on:
+<ol>
+<li>
+NetWare 5.1 with both the 1.1.7b JVM and the 1.2.2 JVM.</li>
+
+<li>
+NetWare 6 with the 1.2.2 JVM and the 1.3 JVM.</li>
+</ol>
+The connectors have been tested with the <b>ajp12</b> worker and the <b>ajp13</b>
+worker with all JVMs.
+<h2>
+<a NAME="Installation"></a>Installation</h2>
+Builds of Tomcat are available as
+<a href="http://jakarta.apache.org/downloads/binindex.html">binary
+distributions</a> and the web server connectors for NetWare are available
+in the netware/i386 directory relative to the specific build of tomcat.
+The mod_jk.nlm file is the connector for Apache, the nsapi_rd.nlm file
+is the connector for the NetWare Enterprise Web Server, and the jni_conn.nlm
+file is the native method library if you use the <b>jni</b> worker with
+the 1.2.2 or 1.3 JVM. Once you have downloaded the appropriate zip file
+and unzipped it to your NetWare server, you can run Tomcat in standalone
+mode. To run with another web server providing static content, you
+will need to configure the web server appropriately and copy the necessary
+connector(s) to the appropriate directories.
+<br>
+<h3>
+<a NAME="Running Tomcat Standalone"></a>1. Running Tomcat Standalone</h3>
+To run Tomcat standalone, it is easiest to create an NCF file to start
+Tomcat. A sample TOMCAT.NCF could look like this:
+<p>; This is a sample NCF file for starting TOMCAT on NetWare. The TOMCAT_HOME
+<br>; environment variable and the tomcat.home define on the java command
+line
+<br>; should be modified to reflect the directory where you actually install
+<br>; Tomcat.
+<p>envset TOMCAT_HOME=SYS:\jakarta-tomcat-3.3
+<p>envset TOMCAT_CLASSPATH=sys:\java\lib\classes.zip
+<br>envset TOMCAT_CLASSPATH=$TOMCAT_CLASSPATH;$TOMCAT_HOME\lib\tomcat.jar
+<p>; The following command line starts Tomcat with it's own Console Screen
+<br>; that will automatically close (-nsac) with the screen called Tomcat
+<br>; (-snTomcat) and the current working directory set to TOMCAT_HOME
+<br>; (-envCWD=$TOMCAT_HOME)
+<br>java -nsac -snTomcat -envCWD=$TOMCAT_HOME -classpath $TOMCAT_CLASSPATH -Dtomcat.home=SYS:\jakarta-tomcat-3.3 org.apache.tomcat.startup.Main %1 %2 %3 %3 %5 %6 %7 %8 %9
+<p>As the comment states, you will need to make sure that TOMCAT_HOME points
+to the correct directory.
+<p>By putting this NCF file in SYS:\System you can start Tomcat by just
+typing <b><tt>tomcat start</tt></b> at the system console. You can also
+add this to your autoexec.ncf to automatically start Tomcat when your system
+comes up. The %1 ... %9 at the end of the command line allows you also pass in
+additional parameters to Tomcat. Try <b><tt>tomcat help</tt></b> to see
+a base list of parameters available.
+<br>
+<h3>
+<a NAME="Running Tomcat with the NetWare Enterprise Web Server"></a>2.
+Running Tomcat with the NetWare Enterprise Web Server</h3>
+To run Tomcat with the NetWare Enterprise Web Server, you need to download
+nsapi_rd.nlm and copy it to your NetWare server. A good location is <tomcat_home>\bin\netscape\netware\i386.
+You will then need to add the following to your obj.conf file located in
+SYS:\novonyx\suitespot\https-<servername>\config. This will tell the
+NetWare Enterprise Web Server to let Tomcat handle the /servlet/* and /examples/*
+URIs.
+<ol>
+<li>
+If you are currently running the Novell Servlet Gateway, disable it using
+the NetWare Web Manager.</li>
+
+<li>
+In the Init section add the following 2 lines (if you see more than 2 lines,
+your browser is wrapping the lines):</li>
+
+<br><tt>Init fn="load-modules" funcs="jk_init,jk_service" shlib="sys:/jakarta-tomcat-3.3/bin/netscape/netware/i386/nsapi_rd.nlm"</tt>
+<br><tt>Init fn="jk_init" worker_file="sys:/jakarta-tomcat-3.3/conf/jk/workers.properties"
+log_level="debug" log_file="sys:/jakarta-tomcat-3.3/logs/nsapi.log"</tt>
+<li>
+In the default object NameTrans section add the following 3 lines:</li>
+
+<br><tt>NameTrans fn="assign-name" from="/servlet/*" name="Tomcat"</tt>
+<br><tt>NameTrans fn="assign-name" from="/*.jsp" name="Tomcat"</tt>
+<br><tt>NameTrans fn="assign-name" from="/examples/*" name="Tomcat"</tt>
+<li>
+Create a new configuration object by adding the following 4 lines to the
+end of the obj.conf file:</li>
+
+<br><tt><Object name="Tomcat"></tt>
+<br><tt>ObjectType fn="force-type" type="text/plain"</tt>
+<br><tt>Service fn="jk_service" worker="ajp13"</tt>
+<br><tt></Object></tt></ol>
+Now stop and restart the NetWare Enterprise Web Server, make sure that Tomcat is
+running (i.e. run the <b>tomcat.ncf</b> file mentioned in <a href="#Running Tomcat Standalone">Running
+Tomcat Standalone</a>) and you should be
+able to access <a href="http://server:port/examples/"> http://server:port/examples/</a>.
+Additional configuration information can be found in <a href="tomcat-netscape-howto.html">Tomcat
+Netscape HowTo</a>.
+<h3>
+<a NAME="Running Tomcat with Apache on NetWare"></a>3. Running Tomcat with
+Apache on NetWare</h3>
+To run Tomcat with Apache on NetWare, you need to download mod_jk.nlm and
+copy it to you NetWare server. A good location is the modules directory
+under your Apache installation. If you copy mod_jk.nlm there, then
+a base configuration file called mod_jk.conf can be generated by Tomcat that
+has a default set of Apache configuration directives that
+map appropriate URIs from Apache to Tomcat. First, run
+<tt><b>tomcat jkconf</tt></b> (i.e. run the <b>tomcat.ncf</b> file mentioned
+in <a href="#Running Tomcat Standalone">Running Tomcat Standalone</a> with a
+<tt><b>jkconf</tt></b> parameter) to generate the file
+<tomcat_home>/conf/auto/mod_jk.conf. Then add the following line to
+your httpd.conf file, replacing SYS:/jakarta-tomcat-3.3 with the directory
+where Tomcat is installed:
+<p>Include "SYS:/jakarta-tomcat-3.3/conf/auto/mod_jk.conf"</p>
+<p>You can also just copy the appropriate configuration directives from the
+generated mod_jk.conf file to your httpd.conf file. For additional
+information, look in <a href="mod_jk-howto.html">Working with mod_jk</a>.</p>
+<h3>
+<a NAME="Building Tomcat for use on NetWare"></a>Building Tomcat for use
+on NetWare</h3>
+Building the Java portion of Tomcat is the same for any platform.
+First download the <a href="http://jakarta.apache.org/site/sourceindex.html">source</a>,
+unzip it and read the README document. After getting the JDK and other tools
+required for building ( <a href="http://jakarta.apache.org/site/binindex.html">Ant</a>,
+<a href="http://java.sun.com/xml">JAXP</a>, and possibly <a href="http://java.sun.com/products/jsse/">JSSE</a>),
+you just run the Ant command as described in the README. Building
+the native connectors requires MetroWerks CodeWarrior 5 or greater, <a href="ftp://ftp.gnu.org/pub/gnu/make/">GNU
+make (version 3.78.1)</a>, the <a href="http://developer.novell.com/ndk/ws2comp.htm">WinSock
+2 Developer Components for NetWare</a>, WinSock 2 components from the <a href="http://www.microsoft.com/msdownload/platformsdk/setuplauncher.htm">Microsoft
+Platform SDK</a>, the JNI headers from SYS:\java\include\netware (download and
+install the Novell JVM for NetWare <a href="http://developer.novell.com/ndk/jvm.htm">v1.1.7b</a>
+or <a href="http://developer.novell.com/ndk/jvm12.htm">v1.2.2</a> to get these), and the <a href="http://developr.novell.com/ndk/clib.htm">NLM
+and NetWare Libraries for C</a>. Once you have all of the tools and
+SDKs necessary, it is recommended that you install MetroWerks and the NetWare
+SDK components to a common directory structure such as D:\Tools (the default
+in the makefiles.) Next create a directory structure for the MetroWerks
+command line tools that matches what the makefile expects. The final
+Tools directory structure would look something like this:
+<p>D:\Tools
+<br> |
+<br> +CodeWarrior (base directory for MetroWerks
+CodeWarrior installation)
+<br> | |
+<br> | |
+<br> | +5.3 (this
+is optional but it makes it easier to use different versions)
+<br> |
+|
+<br> | +bin (CodeWarrior IDE
+binaries)
+<br> | |
+<br> | ... (all the other CodeWarrior
+directories)
+<br> | |
+<br> | +Tools (location for Command
+Line Tools. See the MW directory structure)
+<br> | |
+<br> | +Novell Support (location
+for Novell Specific files. See the MW directory structure)
+<br> +mw
+<br> | |
+<br> | +5.3 (this
+is optional but it makes it easier to use different versions)
+<br> |
+|
+<br> |
++bin (copy mwccnlm.exe and mwldnlm.exe from \Tools\CodeWarrior\Tools\Command
+Line Tools)
+<br> |
+|
+<br> |
++include (copy all files from \Tools\CodeWarrior\Novell Support\Metrowerks
+Support\Headers and
+<br> |
+|
+\Tools\CodeWarrior\Novell Support\Metrowerks Support\Libraries\MSL C++\Include)
+<br> |
++lib (copy *.lib and *.obj from \Tools\CodeWarrior\Novell Support\Metrowerks
+Support\Libraries\Runtime)
+<br> |
+<br> +nwsdk (All of the NetWare SDK components.
+Change default install directory to D:\Tools instead of C:\Novell)
+<br> |
+<br> +jdk
+<br> |
+<br> +jdk-1_2_2 (JDK installation)
+<p>Once you have the tools set up, here are the environment variables you can
+define to point to your tools and SDKs.
+<div align="left">
+ <table border="0" width="100%">
+ <tr>
+ <td width="29%">Environment Variable Name</td>
+ <td width="71%">Description</td>
+ </tr>
+ <tr>
+ <td width="29%">TOOLPATH</td>
+ <td width="71%">The base path where the tools are install. Defaults
+ to D:\Tools</td>
+ </tr>
+ <tr>
+ <td width="29%">JDKPATH</td>
+ <td width="71%">The base path for the jdk. Defaults to $(TOOLPATH)\jdk\jdk-1_2_2.
+ Copy the JNI headers from your NetWare server's SYS:\java\include\netware
+ directory to $(JDKPATH)\include\netware</td>
+ </tr>
+ <tr>
+ <td width="29%">NOVELLNDK</td>
+ <td width="71%">The base path for the NetWare SDK files. Defaults to
+ $(TOOLPATH)\nwsdk</td>
+ </tr>
+ <tr>
+ <td width="29%">METROWERKSPATH</td>
+ <td width="71%"> The base path for the mw directory structure defined <a href="#Tools Directory Structure">above</a>.
+Defaults to $(TOOLPATH)\mw\5.3</td>
+ </tr>
+ <tr>
+ <td width="29%">WINSOCK_INCDIR</td>
+ <td width="71%">The base path for winsock headers. Defaults to $(NOVELLNDK)\include\winsock.
+ Only needed for the Apache connector.</td>
+ </tr>
+ <tr>
+ <td width="29%">APACHE_SRC</td>
+ <td width="71%">The path to the Apache src directory. Defaults to
+ d:\apache_1.3.19\src.
+ Only needed for the Apache connector.</td>
+ </tr>
+ </table>
+</div>
+<p>Copy the GNUmake executable (referred to a gmake hereafter) to a directory
+that is in your path and change to the directory of the connector that
+you wish to build. If your tools are set up as described above, you
+just need to set the APACHE_SRC environment variable to an appropriate
+directory and type gmake
+-f Makefile.nw in the main directory for the connector you wish to build.
+<br></p>
+</body>
+</html>
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/Tomcat-on-NetWare-HowTo.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/build.xml.txt
URL: http://svn.apache.org/viewvc/tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/build.xml.txt?rev=1305110&view=auto
==============================================================================
--- tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/build.xml.txt (added)
+++ tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/build.xml.txt Sun Mar 25 19:52:59 2012
@@ -0,0 +1,176 @@
+<!--
+ Copyright 1999-2004 The Apache Software Foundation
+
+ Licensed 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.
+-->
+<!-- A "project" describes a set of targets that may be requested
+ when Ant is executed. The "default" attribute defines the
+ target which is executed if no specific target is requested,
+ and the "basedir" attribute defines the current working directory
+ from which Ant executes the requested task. This is normally
+ set to the current working directory.
+-->
+
+
+<project name="My Project" default="compile" basedir=".">
+
+
+<!-- Property Definitions
+
+ Each of the following properties are used by convention in this
+ build file. The values specified can be overridden at run time by
+ adding a "-Dname=value" argument to the command line that invokes Ant.
+ This technique is normally used to copy the values of the ANT_HOME
+ and TOMCAT_HOME environment variables into the "ant.home" and
+ "tomcat.home" properties, which are normally not defined explicitly.
+
+ app.name Base name of this application, used to
+ construct filenames and directories.
+
+ deploy.home The name of the directory into which the
+ deployment hierarchy will be created.
+ Normally, this will be the name of a
+ subdirectory under $TOMCAT_HOME/webapps.
+
+ dist.home The name of the base directory in which
+ distribution files are created.
+
+ dist.src The name of the distribution JAR file
+ containing the application source code,
+ to be stored in the "dist.home" directory.
+ This filename should end with ".jar".
+
+ dist.war The name of the Web ARchive (WAR) file
+ containing our deployable application.
+ This filename should end with ".war".
+
+ javadoc.home The name of the base directory in which
+ the JavaDoc documentation for this application
+ is generated.
+
+ tomcat.home The name of the base directory in which
+ Tomcat has been installed. This value is
+ normally set automatically from the value
+ of the TOMCAT_HOME environment variable.
+
+ In the example below, the application being developed will be deployed
+ to a subdirectory named "myapp", and will therefore be accessible at:
+
+ http://localhost:8080/myapp
+-->
+
+ <property name="app.name" value="myapp"/>
+ <property name="deploy.home" value="${tomcat.home}/webapps/${app.name}"/>
+ <property name="dist.home" value="${deploy.home}"/>
+ <property name="dist.src" value="${app.name}.jar"/>
+ <property name="dist.war" value="${app.name}.war"/>
+ <property name="javadoc.home" value="${deploy.home}/javadoc"/>
+
+
+<!-- The "prepare" target is used to construct the deployment home
+ directory structure (if necessary), and to copy in static files
+ as required. In the example below, Ant is instructed to create
+ the deployment directory, copy the contents of the "web/" source
+ hierarchy, and set up the WEB-INF subdirectory appropriately.
+-->
+
+ <target name="prepare">
+ <mkdir dir="${deploy.home}"/>
+ <copy todir="${deploy.home}">
+ <fileset dir="web"/>
+ </copy>
+ <mkdir dir="${deploy.home}/WEB-INF"/>
+ <copy file="etc/web.xml" tofile="${deploy.home}/WEB-INF/web.xml"/>
+ <mkdir dir="${deploy.home}/WEB-INF/classes"/>
+ <mkdir dir="${deploy.home}/WEB-INF/lib"/>
+ <copy todir="${deploy.home}/WEB-INF/lib">
+ <fileset dir="lib"/>
+ </copy>
+ <mkdir dir="${javadoc.home}"/>
+ </target>
+
+
+<!-- The "clean" target removes the deployment home directory structure,
+ so that the next time the "compile" target is requested, it will need
+ to compile everything from scratch.
+-->
+
+ <target name="clean">
+ <delete dir="${deploy.home}"/>
+ </target>
+
+
+<!-- The "compile" target is used to compile (or recompile) the Java classes
+ that make up this web application. The recommended source code directory
+ structure makes this very easy because the <javac> task automatically
+ works its way down a source code hierarchy and compiles any class that
+ has not yet been compiled, or where the source file is newer than the
+ class file.
+
+ Feel free to adjust the compilation option parameters (debug,
+ optimize, and deprecation) to suit your requirements. It is also
+ possible to base them on properties, so that you can adjust this
+ behavior at runtime.
+
+ The "compile" task depends on the "prepare" task, so the deployment
+ home directory structure will be created if needed the first time.
+-->
+
+ <target name="compile" depends="prepare">
+ <javac srcdir="src" destdir="${deploy.home}/WEB-INF/classes"
+ classpath="${deploy.home}/WEB-INF/classes"
+ debug="on" optimize="off" deprecation="off"/>
+ <copy todir="${deploy.home}/WEB-INF/classes">
+ <fileset dir="src" includes="**/*.properties"/>
+ </copy>
+ </target>
+
+
+<!-- The "javadoc" target is used to create the Javadoc API documentation
+ for the Java classes in this web application. It is assumed that
+ this documentation is included in the deployed application, so the
+ example below generates the Javadoc HTML files in a subdirectory under
+ the deployment home directory. Feel free to customize the options for
+ the JavaDoc task, after consulting the Ant documentation.
+-->
+
+ <target name="javadoc" depends="prepare">
+ <javadoc sourcepath="src" packagenames="*"
+ destdir="${javadoc.home}"/>
+ </target>
+
+
+<!-- The "all" target rebuilds everything by executing the "clean"
+ target first, which forces the "compile" target to compile all
+ source code instead of just the files that have been changed.
+-->
+
+ <target name="all" depends="clean,prepare,compile,javadoc"/>
+
+
+<!-- The "dist" target builds the distribution Web ARchive (WAR) file
+ for this application, suitable for distribution to sites that wish
+ to install your application. It also creates a JAR file containing
+ the source code for this application, if you wish to distribute
+ that separately.
+-->
+
+ <target name="dist" depends="prepare,compile">
+ <jar jarfile="${dist.home}/${dist.src}"
+ basedir="."/>
+ <jar jarfile="${dist.home}/${dist.war}"
+ basedir="${deploy.home}"/>
+ </target>
+
+
+</project>
Propchange: tomcat/site/trunk/docs/tomcat-3.3-doc/appdev/build.xml.txt
------------------------------------------------------------------------------
svn:eol-style = native
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org