hgomez 2002/09/10 01:02:50
Modified: jk/xdocs/jk workershowto.xml iishowto.xml aphowto.xml
neshowto.xml domhowto.xml
jk/xdocs/common AJPv14-proposal.xml AJPv13.xml
jk/xdocs faq.xml index.xml
Log:
Fixes typos and styles
Revision Changes Path
1.3 +12 -10 jakarta-tomcat-connectors/jk/xdocs/jk/workershowto.xml
Index: workershowto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-connectors/jk/xdocs/jk/workershowto.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- workershowto.xml 9 Sep 2002 09:56:35 -0000 1.2
+++ workershowto.xml 10 Sep 2002 08:02:49 -0000 1.3
@@ -73,7 +73,7 @@
<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.0):
+Currently the following worker types that exists are (JK 1.2.0):
</p>
<table>
@@ -203,13 +203,13 @@
</p>
<p>
-<b>cachesize</b> property is usefull when you're using jk in multithreaded
+<b>cachesize</b> property is usefull when you're using JK in multithreaded
web servers such as Apache 2.0, IIS and Netscape. They will benefit the most by
setting this value to a higher level (such as the estimated average concurrent
users for Tomcat).
</p>
<p>
-<b>cache_timeout</b> property should be used with <b>cachesize</b> to specify how
to time jk should keep
+<b>cache_timeout</b> 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 WebServer.
</p>
@@ -244,9 +244,11 @@
</p>
<p>
-<b>socket_timeout</b> property told webserver to cut an ajp13 connection after some
time of use.
-It's a good way to ensure that there won't be any unused threads living on Tomcat
side, with the
-extra cost of reopening sockets next time a request be forwarded.
+<b>socket_timeout</b> property 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.
</p>
@@ -323,7 +325,7 @@
Note: Since the JVM is multithreaded; the jni worker should be used only within
multithreaded servers
such as AOLServer, IIS, Netscape and Apache 2.0.<br/>
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.
+used to build the JK web server plugin.
</p>
<p>
@@ -344,7 +346,7 @@
<p>
The <b>class_path</b> property can be given in multiple lines.
-In this case the jk environment will concatenate all the classpath entries together
+In this case the JK environment will concatenate all the classpath entries together
by putting path delimiter (":"/";") between the entries.
</p>
@@ -361,7 +363,7 @@
<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
+In this case the JK environment will concatenate all the cmd_line entries together
by putting spaces
between the entries.
</p>
@@ -458,7 +460,7 @@
<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.
+a sample worker.properties file is bundled along JK.
</p>
<p>
1.3 +1 -1 jakarta-tomcat-connectors/jk/xdocs/jk/iishowto.xml
Index: iishowto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-connectors/jk/xdocs/jk/iishowto.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- iishowto.xml 9 Sep 2002 09:57:10 -0000 1.2
+++ iishowto.xml 10 Sep 2002 08:02:49 -0000 1.3
@@ -13,7 +13,7 @@
<p>
Normally IIS can not execute Servlets and Java Server Pages (JSPs),
-configuring IIS to use the mod_jk redirector plugin will let IIS send servlet and
+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>
1.5 +4 -4 jakarta-tomcat-connectors/jk/xdocs/jk/aphowto.xml
Index: aphowto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-connectors/jk/xdocs/jk/aphowto.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- aphowto.xml 9 Sep 2002 09:57:10 -0000 1.4
+++ aphowto.xml 10 Sep 2002 08:02:49 -0000 1.5
@@ -42,7 +42,7 @@
</p>
<p>
In all the examples in this document ${tomcat_home} will be <b>/var/tomcat3</b>.
-A <a href="jk/workershowto.html">worker</a> is defined to be a tomcat process that
accepts work from the IIS server.
+A <a href="jk/workershowto.html">worker</a> is defined to be a tomcat process that
accepts work from the Apache server.
</p>
</subsection>
@@ -161,7 +161,7 @@
</p>
<p>
-For example mod_jk 1.2.0 could be find <a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/";>
+For example JK 1.2.0 could be find <a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/v1.2.0/bin/";>
here</a> and contains the following:
</p>
@@ -220,7 +220,7 @@
</p>
<p>
-The mod_jserv configuration directives are not compatible with mod_jk!
+The mod_jserv configuration directives are not compatible with mod_jk !
</p>
</subsection>
@@ -793,7 +793,7 @@
<section name="Building mod_jk for Apache on iSeries/OS400">
<p>
-Since OS400 V4R5, iSeries (AS/400) used Apache 2.0 as their primary web server,
replacing the old IBM webserver.
+Since OS400 V4R5, iSeries (AS/400) use Apache 2.0 as their primary web server,
replacing the old IBM webserver.
It's now possible to build mod_jk on iSeries thanks to the help of IBM Rochester
Labs who provided informations and patches
to adapt mod_jk to their Operating System.
</p>
1.3 +1 -1 jakarta-tomcat-connectors/jk/xdocs/jk/neshowto.xml
Index: neshowto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-connectors/jk/xdocs/jk/neshowto.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- neshowto.xml 9 Sep 2002 09:57:10 -0000 1.2
+++ neshowto.xml 10 Sep 2002 08:02:49 -0000 1.3
@@ -42,7 +42,7 @@
</p>
<p>
In all the examples in this document ${tomcat_home} will be
<b>c:\jakarta-tomcat</b>.
-A worker is defined to be a tomcat process that accepts work from the IIS server.
+A worker is defined to be a tomcat process that accepts work from the
Netscape/iPlanet server.
</p>
</subsection>
1.3 +2 -2 jakarta-tomcat-connectors/jk/xdocs/jk/domhowto.xml
Index: domhowto.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-connectors/jk/xdocs/jk/domhowto.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- domhowto.xml 9 Sep 2002 09:57:10 -0000 1.2
+++ domhowto.xml 10 Sep 2002 08:02:49 -0000 1.3
@@ -46,7 +46,7 @@
</p>
<p>
In all the examples in this document ${tomcat_home} will be
<b>c:\jakarta-tomcat</b>.
-A worker is defined to be a tomcat process that accepts work from the IIS server.
+A worker is defined to be a tomcat process that accepts work from the Domino server.
</p>
</subsection>
@@ -415,7 +415,7 @@
<section name="Building for Windows">
<p>
-To compile it you'll need the jk domino source and Microsoft Visual C++ 6.0.
+To compile it you'll need the JK Domino sources and Microsoft Visual C++ 6.0.
</p>
<p>
1.2 +664 -664 jakarta-tomcat-connectors/jk/xdocs/common/AJPv14-proposal.xml
Index: AJPv14-proposal.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-connectors/jk/xdocs/common/AJPv14-proposal.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- AJPv14-proposal.xml 2 Sep 2002 10:49:38 -0000 1.1
+++ AJPv14-proposal.xml 10 Sep 2002 08:02:50 -0000 1.2
@@ -1,664 +1,664 @@
-<?xml version="1.0"?>
-<document>
-<properties>
-<title>AJPv14 Proposal</title>
-<author email="[EMAIL PROTECTED]">Henri Gomez</author>
-</properties>
-
-<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 AJPv13">
-<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 mod_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 mod_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 mod_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="AJPv14 add-ons to AJPv13">
-<p>
-Let's descrive here the features and add-on that will be added to AJP13,
-which will became AJP14. Since this document is a proposal, a resonable level
-of chaos must be expected at start.
-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 AJP14 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
-supported (AJP14/AJP15/AJP16...)
-
-The Web server info will contain web server info and
-connector name (ie Apache 1.3.20 + mod_ssl 2.8.4 + mod_jk 1.2a1 + 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 ajp14 implementation
-on a web-server working with a more advanced ajp14 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.ajp14.port=8009
-worker.ajp14.host=localhost
-worker.ajp14.type=ajp14
-worker.ajp14.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 AJP14 in mod_jk, I really discovered "JkEnvVar".
-The following "Extended Env Vars feature" description may not
-be implemented in AJP14 since allready available in AJP13.
-
-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)
- ?jvm_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 AJP14 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 AJP14_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 AJP14)
-</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 AJP14 protocol is to overcome some of the 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 mod_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 AJP14 Index">
-<p>
-Index of Commands and ID to be added in AJP14 Protocol
-</p>
-
-<subsection name="Commands IDs">
-<p>
-<table>
- <tr><th>Command Name</th><th>Command Number</th></tr>
- <tr><td>AJP14_LOGINIT_CMD</td><td>0x10</td></tr>
- <tr><td>AJP14_LOGSEED_CMD</td><td>0x11</td></tr>
- <tr><td>AJP14_LOGCOMP_CMD</td><td>0x12</td></tr>
- <tr><td>AJP14_LOGOK_CMD</td><td>0x13</td></tr>
- <tr><td>AJP14_LOGNOK_CMD</td><td>0x14</td></tr>
- <tr><td>AJP14_CONTEXT_QRY_CMD</td><td>0x15</td></tr>
- <tr><td>AJP14_CONTEXT_INFO_CMD</td><td>0x16</td></tr>
- <tr><td>AJP14_CONTEXT_UPDATE_CMD</td><td>0x17</td></tr>
- <tr><td>AJP14_STATUS_CMD</td><td>0x18</td></tr>
- <tr><td>AJP14_SHUTDOWN_CMD</td><td>0x19</td></tr>
- <tr><td>AJP14_SHUTOK_CMD</td><td>0x1A</td></tr>
- <tr><td>AJP14_SHUTNOK_CMD</td><td>0x1B</td></tr>
- <tr><td>AJP14_CONTEXT_STATE_CMD</td><td>0x1C</td></tr>
- <tr><td>AJP14_CONTEXT_STATE_REP_CMD</td><td>0x1D</td></tr>
- <tr><td>AJP14_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>AJP14_CONTEXT_INFO_NEG</td><td>0x80000000</td><td>web-server want context
info after login</td></tr>
- <tr><td>AJP14_CONTEXT_UPDATE_NEG</td><td>0x40000000</td><td>web-server want
context updates</td></tr>
- <tr><td>AJP14_GZIP_STREAM_NEG</td><td>0x20000000</td><td>web-server want
compressed stream</td></tr>
- <tr><td>AJP14_DES56_STREAM_NEG</td><td>0x10000000</td><td>web-server want crypted
DES56 stream with secret key</td></tr>
- <tr><td>AJP14_SSL_VSERVER_NEG</td><td>0x08000000</td><td>Extended info on server
SSL vars</td></tr>
- <tr><td>AJP14_SSL_VCLIENT_NEG</td><td>0x04000000</td><td>Extended info on client
SSL vars</td></tr>
- <tr><td>AJP14_SSL_VCRYPTO_NEG</td><td>0x02000000</td><td>Extended info on crypto
SSL vars</td></tr>
- <tr><td>AJP14_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>AJP14_PROTO_SUPPORT_AJPXX_NEG</td><td>0x00FF0000</td><td>mask of protocol
supported</td></tr>
- <tr><td>AJP14_PROTO_SUPPORT_AJP14_NEG</td><td>0x00010000</td><td>communication
could use AJP14</td></tr>
- <tr><td>AJP14_PROTO_SUPPORT_AJP15_NEG</td><td>0x00020000</td><td>communication
could use AJP15</td></tr>
- <tr><td>AJP14_PROTO_SUPPORT_AJP16_NEG</td><td>0x00040000</td><td>communication
could use AJP16</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>AJP14_BAD_KEY_ERR</td><td>0xFFFFFFFF</td></tr>
- <tr><td>AJP14_ENGINE_DOWN_ERR</td><td>0xFFFFFFFE</td></tr>
- <tr><td>AJP14_RETRY_LATER_ERR</td><td>0xFFFFFFFD</td></tr>
- <tr><td>AJP14_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>AJP14_CONTEXT_DOWN</td><td>0x01</td></tr>
- <tr><td>AJP14_CONTEXT_UP</td><td>0x02</td></tr>
- <tr><td>AJP14_CONTEXT_OK</td><td>0x03</td></tr>
-</table>
-</p>
-</subsection>
-
-</section>
-
-</document>
+<?xml version="1.0"?>
+<document>
+<properties>
+<title>AJPv14 Proposal</title>
+<author email="[EMAIL PROTECTED]">Henri Gomez</author>
+</properties>
+
+<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 AJPv13">
+<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="AJPv14 add-ons to AJPv13">
+<p>
+Let's descrive here the features and add-on that will be added to AJP13,
+which will became AJP14. Since this document is a proposal, a resonable level
+of chaos must be expected at start.
+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 AJP14 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
+supported (AJP14/AJP15/AJP16...)
+
+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.0 + 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 ajp14 implementation
+on a web-server working with a more advanced ajp14 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.ajp14.port=8009
+worker.ajp14.host=localhost
+worker.ajp14.type=ajp14
+worker.ajp14.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 AJP14 in JK, I really discovered "JkEnvVar".
+The following "Extended Env Vars feature" description may not
+be implemented in AJP14 since allready available in AJP13.
+
+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)
+ ?jvm_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 AJP14 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 AJP14_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 AJP14)
+</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 AJP14 protocol is to overcome some of the 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 AJP14 Index">
+<p>
+Index of Commands and ID to be added in AJP14 Protocol
+</p>
+
+<subsection name="Commands IDs">
+<p>
+<table>
+ <tr><th>Command Name</th><th>Command Number</th></tr>
+ <tr><td>AJP14_LOGINIT_CMD</td><td>0x10</td></tr>
+ <tr><td>AJP14_LOGSEED_CMD</td><td>0x11</td></tr>
+ <tr><td>AJP14_LOGCOMP_CMD</td><td>0x12</td></tr>
+ <tr><td>AJP14_LOGOK_CMD</td><td>0x13</td></tr>
+ <tr><td>AJP14_LOGNOK_CMD</td><td>0x14</td></tr>
+ <tr><td>AJP14_CONTEXT_QRY_CMD</td><td>0x15</td></tr>
+ <tr><td>AJP14_CONTEXT_INFO_CMD</td><td>0x16</td></tr>
+ <tr><td>AJP14_CONTEXT_UPDATE_CMD</td><td>0x17</td></tr>
+ <tr><td>AJP14_STATUS_CMD</td><td>0x18</td></tr>
+ <tr><td>AJP14_SHUTDOWN_CMD</td><td>0x19</td></tr>
+ <tr><td>AJP14_SHUTOK_CMD</td><td>0x1A</td></tr>
+ <tr><td>AJP14_SHUTNOK_CMD</td><td>0x1B</td></tr>
+ <tr><td>AJP14_CONTEXT_STATE_CMD</td><td>0x1C</td></tr>
+ <tr><td>AJP14_CONTEXT_STATE_REP_CMD</td><td>0x1D</td></tr>
+ <tr><td>AJP14_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>AJP14_CONTEXT_INFO_NEG</td><td>0x80000000</td><td>web-server want context
info after login</td></tr>
+ <tr><td>AJP14_CONTEXT_UPDATE_NEG</td><td>0x40000000</td><td>web-server want
context updates</td></tr>
+ <tr><td>AJP14_GZIP_STREAM_NEG</td><td>0x20000000</td><td>web-server want
compressed stream</td></tr>
+ <tr><td>AJP14_DES56_STREAM_NEG</td><td>0x10000000</td><td>web-server want crypted
DES56 stream with secret key</td></tr>
+ <tr><td>AJP14_SSL_VSERVER_NEG</td><td>0x08000000</td><td>Extended info on server
SSL vars</td></tr>
+ <tr><td>AJP14_SSL_VCLIENT_NEG</td><td>0x04000000</td><td>Extended info on client
SSL vars</td></tr>
+ <tr><td>AJP14_SSL_VCRYPTO_NEG</td><td>0x02000000</td><td>Extended info on crypto
SSL vars</td></tr>
+ <tr><td>AJP14_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>AJP14_PROTO_SUPPORT_AJPXX_NEG</td><td>0x00FF0000</td><td>mask of protocol
supported</td></tr>
+ <tr><td>AJP14_PROTO_SUPPORT_AJP14_NEG</td><td>0x00010000</td><td>communication
could use AJP14</td></tr>
+ <tr><td>AJP14_PROTO_SUPPORT_AJP15_NEG</td><td>0x00020000</td><td>communication
could use AJP15</td></tr>
+ <tr><td>AJP14_PROTO_SUPPORT_AJP16_NEG</td><td>0x00040000</td><td>communication
could use AJP16</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>AJP14_BAD_KEY_ERR</td><td>0xFFFFFFFF</td></tr>
+ <tr><td>AJP14_ENGINE_DOWN_ERR</td><td>0xFFFFFFFE</td></tr>
+ <tr><td>AJP14_RETRY_LATER_ERR</td><td>0xFFFFFFFD</td></tr>
+ <tr><td>AJP14_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>AJP14_CONTEXT_DOWN</td><td>0x01</td></tr>
+ <tr><td>AJP14_CONTEXT_UP</td><td>0x02</td></tr>
+ <tr><td>AJP14_CONTEXT_OK</td><td>0x03</td></tr>
+</table>
+</p>
+</subsection>
+
+</section>
+
+</document>
1.2 +88 -86 jakarta-tomcat-connectors/jk/xdocs/common/AJPv13.xml
Index: AJPv13.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-connectors/jk/xdocs/common/AJPv13.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- AJPv13.xml 29 Aug 2002 11:04:34 -0000 1.1
+++ AJPv13.xml 10 Sep 2002 08:02:50 -0000 1.2
@@ -1,7 +1,7 @@
<?xml version="1.0"?>
<document>
<properties>
- <title>Apache JServ Protocol version 1.3</title>
+ <title>AJPv13</title>
<author email="[EMAIL PROTECTED]">[EMAIL PROTECTED]</author>
<author email="[EMAIL PROTECTED]">Jean-Frederic Clere</author>
</properties>
@@ -20,7 +20,7 @@
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
+make life easier for maintainers of JK, and for anyone who wants to
port the protocol somewhere (into jakarta 4.x, for example).
</p>
@@ -45,7 +45,7 @@
<p>
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
+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):
@@ -352,31 +352,41 @@
<subsection name="method">
<p>
The HTTP method, encoded as a single byte:
+</p>
-<source>
-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
-</source>
+<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>
+
</subsection>
<subsection name="protocol, req_uri, remote_addr, remote_host, server_name,
server_port, is_ssl">
@@ -399,37 +409,21 @@
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>
+ <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
@@ -464,21 +458,22 @@
sent to signal the end of the list of optional attributes. The list of
byte codes is:
</p><p>
-<source>
-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
+<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>jvm_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></td></tr>
+ <tr><td>terminator</td><td>0xFF</td><td></td></tr>
+</table>
-terminator 0xFF
-</source>
</p><p>
The <code>context</code> and <code>servlet_path</code> are not currently
@@ -504,7 +499,7 @@
details.
</p><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
+ 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>
@@ -574,24 +569,31 @@
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>
-<source>
-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
-</source>
-</p><p>
+</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">
1.2 +294 -204 jakarta-tomcat-connectors/jk/xdocs/faq.xml
Index: faq.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-connectors/jk/xdocs/faq.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- faq.xml 2 Sep 2002 10:50:23 -0000 1.1
+++ faq.xml 10 Sep 2002 08:02:50 -0000 1.2
@@ -1,204 +1,294 @@
-<?xml version="1.0"?>
-<document>
-<properties>
-<title>FAQ</title>
-<author email="[EMAIL PROTECTED]">Henri Gomez</author>
-</properties>
-
-<section name="General">
-<p>
-General Informations and FAQ about mod_jk
-</p>
-<subsection name="Where can I get help/support for mod_jk?">
-<p>
-The primary mechanism for support is through the mod_jk
-documentation included in the doc directory.
-Documentation is also available on the Apache Jakarta web site devoted to the
-<a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/doc/index.html";>
-Jakarta Tomcat Connectors Project</a>
-For additional help, the best resource is the Tomcat Users Discussion list.
-You should start by searching
-<a href="http://mikal.org/interests/java/tomcat/index.html";>
-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 mod_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://jakarta.apache.org/site/mail.html";>
-here</a>
-to determine how to subscribe to tomcat mailing list.
-</p>
-</subsection>
-
-<subsection name="I can't find mod_jk anywhere. Where is it?">
-<p>
-Now that mod_jk moved to the jakarta-tomcat-connectors repository,
-the source and binaries for mod_jk are present
-in the <a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/";>
-jakarta-tomcat-connectors directory</a>
-</p>
-</subsection>
-
-<subsection name="Where can I get more information ?">
-<p>
-For mod_jk 1.2.x the <a href="jk/config-howto.html">
-mod_jk-config howto document</a> has considerably more in-depth information.
-For mod_jk 2.0.x the <a href="jk2/configtc.html">
-config tomcat</a> and <a href="jk2/configweb.html">config webserver</a>
-documents have considerably more in-depth information.
-It's worth a look.
-You could also try searching the mailing list archives for "mod_jk" or look at the
source.
-</p>
-</subsection>
-
-<subsection name="Which protocol should I use? Ajp12 or Ajp13?">
-<p>
-<a href="common/AJPv13.html">Ajp13</a> is a newer protocol, it's faster, and it
works better with SSL. You almost certainly want to use it.
-There is more information in the workers.properties howto document, ajp12 is now
deprecated.
-Also ajp13 is supported by all Apache Tomcat including 3.2.x , 3.3.x, 4.0.x, 4.1.x
and the new tomcat 5.
-Others Servlet engine like jetty have support for Ajp13.
-</p>
-</subsection>
-
-<subsection name="I've got a firewall between my WebServer and Tomcat who drop
ajp13 connections after some times">
-<p>
-Ajp13 use persistant connections where the traffic could be null if there is no
request to be sent to Tomcat.
-Firewall used to drop inactive connections and will make your WebServer and Tomcat
think the connection is valid.
-Since mod_jk 1.2.0 a socket_keepalive property as been added to ajp13 settings, and
you should take a look at
-it in workers.properties howto
-</p>
-</subsection>
-
-<subsection name="Under heavy load, I've got many threads in Tomcat even if my
Apache Web Server handle much of the load">
-<p>
-Under heavy load, Apache WebServer create many childs to handle the load, which
will in turn create many connections
-to Tomcat to forward the requests they should handle.
-Apache WebServer will normally kill the childs/threads when the load decrease. But
if the load is still there and
-even if only Apache handle the requests, ie static contents, the childs are kept
and with them the ajp13 connections,
-even if they are no more used.
-Since mod_jk 1.2.0 cache_timeout and socket_timeout properties as been added to
close connections after some time,
-for more informations refer to workers.properties howto
-</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 handle the network failure.
-But with previous release of mod_jk, you may have to restart Apache as well.
-</p>
-</subsection>
-
-<subsection name="Why did exist two files mod_jk.so (-eapi ad -noeapi) in download
dir for Linux ?">
-<p>
-Many versions of Apache use of modified API, known at Extended API. For example,
Apache using mod_ssl or
-Apache present in certains recent Linux distributions. So if you got such 'Extended
Apache',
-you need to use mod_jk.so-eapi, or use mod_jk.so-noeapi for standard Apache.
-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 mod_jk.so for your version of Apache
-</p>
-</subsection>
-
-<subsection name="What's that message about 'garbled DSO ?'">
-<p>
-It's related to Apache EAPI, the message 'mod_jk.so is garbled - perhaps this is
not an Apache module DSO ?'
-just told you are 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 '[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)', 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.
-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="JNI didn't works with Apache 1.3">
-<p>
-JNI support require 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
-LoadModule "/usr/lib/libpthreads.so" in your httpd.conf.
-Also keep in mind that JNI is suited for multi-threaded servers and you should
consider upgrading
-to Apache 2.0 to support JNI.
-</p>
-</subsection>
-
-<subsection name="JNI report that JVM couldn't be started under Linux">
-<p>
-Under Linux, you should set some environment variables BEFORE launching your Apache
server :
-<source>
-export LD_LIBRARY_PATH=$jre/bin:$jre/bin/classic:$LD_LIBRARY_PATH
-</source>
-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 :
-<source>
-export LD_ASSUME_KERNEL=2.2.5
-</source>
-You could have to update your service scripts, ie /etc/rc.d/init.d/httpd, to set
these env vars before your httpd server starts.
-</p>
-</subsection>
-
-</section>
-
-<section name="IIS">
-<p>
-Informations and FAQ about mod_jk and IIS Web Servers.
-</p>
-<todo>
-More informations to be added, Nacho ?
-</todo>
-</section>
-
-<section name="NES/iPlanet">
-<p>
-Informations and FAQ about mod_jk and NES/iPlanet Web Servers.
-</p>
-<todo>
-More informations to be added, Mike ?
-</todo>
-</section>
-
-
-</document>
+<?xml version="1.0"?>
+<document>
+<properties>
+<title>FAQ</title>
+<author email="[EMAIL PROTECTED]">Henri Gomez</author>
+</properties>
+
+<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 Jakarta web site devoted to the
+<a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/doc/index.html";>
+Jakarta Tomcat Connectors Project</a>
+For additional help, the best resource is the Tomcat Users Discussion list.
+You should start by searching
+<a href="http://mikal.org/interests/java/tomcat/index.html";>
+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://jakarta.apache.org/site/mail.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>jakarta-tomcat-connectors</b> repository,
+the source and binaries for JK are present
+in the <a
href="http://jakarta.apache.org/builds/jakarta-tomcat-connectors/jk/release/";>
+jakarta-tomcat-connectors directory</a>
+</p>
+</subsection>
+
+<subsection name="What's the difference between JK and mod_jk ?">
+<p>
+<b>JK</b> is a project covering web-servers to Tomcat connectors,
+whereas <b>mod_jk</b> is the <a href="jk/aphowto.html">Apache module</a> developped
in JK.
+</p>
+
+<p>
+<a href="jk/domhowto.html">Domino webserver</a> support is implemented on JK, using
a redirector
+called <b>dsapi redirector</b>.
+</p>
+
+<p>
+<a href="jk/iishowto.html">IIS webserver</a>support is implemented on JK, using a
redirector
+called <b>isapi redirector</b>.
+</p>
+
+<p>
+<a href="jk/neshowto.html">Netscape/iPlanet 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="jk/aphowto.html">Apache and JK</a>
+</li>
+
+<li>
+<a href="jk/domhowto.html">Domino and JK</a>
+</li>
+
+<li>
+<a href="jk/iishowto.html">IIS and JK</a>
+</li>
+
+<li>
+<a href="jk/neshowto.html">Netscape/iPlanet and JK</a>
+</li>
+
+<li>
+<a href="jk/workershowto.html">Workers configuration</a>
+</li>
+</ul>
+
+<p>
+For <b>JK 2.0.x</b> the <a href="jk2/configtc.html">
+config tomcat</a> and <a href="jk2/configweb.html">config webserver</a>
+documents have considerably more in-depth information.
+It's worth a look.
+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="common/AJPv13.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 ajp12 is deprecated.
+</p>
+<p>
+Also ajp13 is supported by all Apache Tomcat including 3.2.x , 3.3.x, 4.0.x, 4.1.x
and the new tomcat 5.
+</p>
+
+<p>
+Others Servlet engines like <b>jetty</b> have support for Ajp13.
+</p>
+</subsection>
+
+<subsection name="I've got a firewall between my WebServer and Tomcat who drop
ajp13 connections after some times">
+<p>
+Ajp13 use persistant connections where the traffic could be null if there is no
request to be sent to Tomcat.
+Firewall used to drop inactive connections and will make your WebServer 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="jk/workershowto.html">Workers HowTo</a>.
+</p>
+</subsection>
+
+<subsection name="Under heavy load, I've got many threads in Tomcat even if my
Apache Web Server handle much of the load">
+<p>
+Under heavy load, Apache WebServer create many childs to handle the load, which
will in turn create many connections
+to Tomcat to forward the requests they should handle.
+Apache WebServer will normally kill the childs/threads when the load decrease. But
if the load is still there and
+even if only Apache handle the requests, ie static contents, the childs are kept
and with them the ajp13 connections,
+even if they are no more used.
+</p>
+<p>
+Since JK 1.2.0, <b>cache_timeout</b> and <b>socket_timeout</b> properties as been
added to close
+connections after some time of inactivity, for more informations refer to <a
href="jk/workershowto.html">Workers HowTo</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 handle the network failure.
+But with previous release of mod_jk, you may have to restart Apache as well.
+</p>
+</subsection>
+
+<subsection name="Why did exist two files mod_jk.so (-eapi ad -noeapi) in download
dir for Linux ?">
+<p>
+Many versions of Apache use of modified API, known at Extended API, developped for
use with the
+<a href="http://www.modssl.org";>mod_ssl module</a>.
+</p>
+
+<p>
+For example, Apache 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.
+</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="JNI didn't works with Apache 1.3">
+<p>
+JNI support require 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>
+
+<screen>
+<note># Add pthread to Apache in httpd.conf</note>
+<read>LoadModule "/usr/lib/libpthreads.so"</read>
+</screen>
+
+<p>
+Also keep in mind that JNI is suited for multi-threaded servers and you should
consider upgrading
+to Apache 2.0 to support JNI.
+</p>
+</subsection>
+
+<subsection name="JNI report that JVM couldn't be started under Linux">
+<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>
+
+</section>
+
+<section name="IIS">
+<p>
+Informations and FAQ about JK and IIS Web Servers.
+</p>
+<todo>
+More informations to be added, Nacho ?
+</todo>
+</section>
+
+<section name="NES/iPlanet">
+<p>
+Informations and FAQ about JK and NES/iPlanet Web Servers.
+</p>
+<todo>
+More informations to be added, Mike ?
+</todo>
+</section>
+
+
+</document>
1.8 +20 -20 jakarta-tomcat-connectors/jk/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-tomcat-connectors/jk/xdocs/index.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- index.xml 9 Sep 2002 09:13:59 -0000 1.7
+++ index.xml 10 Sep 2002 08:02:50 -0000 1.8
@@ -6,19 +6,19 @@
<author email="[EMAIL PROTECTED]">Henri Gomez</author>
</properties>
-<section name="What's jk ?">
+<section name="What's JK ?">
<p>
-<b>jk</b> is a replacement to the elderly mod_jserv.
+<b>JK</b> is a replacement to the elderly mod_jserv.
It was a completely new Tomcat-Apache plug-in that handles the communication
between Tomcat and Apache.
</p>
<p>
-The newest <b>jk2</b> is a rewrite of <b>jk</b>.
+The newest <b>JK2</b> is a rewrite of <b>JK</b>.
The native part has been completly
restructured and the configuration has been simplified a lot.
</p>
<p>
-jk is more than just an apache module, since it could be used with majors WebServer
:
+JK is more than just an apache module, since it could be used with majors WebServer
:
</p>
<ul>
@@ -38,9 +38,9 @@
</section>
-<section name="Why should I use the jk ?">
+<section name="Why should I use the JK ?">
<p>
-jk was develop to overcome many limitations of its ancestor, <b>mod_jserv</b>.
+JK was develop to overcome many limitations of its ancestor, <b>mod_jserv</b>.
</p>
<p>
@@ -50,43 +50,43 @@
<p>
Where <b>mod_jserv</b> supported only Apache webservers on Unix OS,
-<b>jk</b> supports much more web servers and operating systems through
-via a compatibility layer named the <b>jk library</b>.
-The layered approach provided by the jk library makes it easier to
+<b>JK</b> supports much more web servers and operating systems through
+via a compatibility layer named the <b>JK library</b>.
+The layered approach provided by the JK library makes it easier to
support many different webservers and OS.
</p>
<p>
-jk offer better support for SSL, that's was a problem with mod_jserv which couldn't
+JK offer better support for SSL, that's was a problem with mod_jserv which couldn't
reliably identify whether a request was made via HTTP or HTTPS.
</p>
<p>
-jk can, using the newer Ajpv13 protocol which relay many SSL informations required
by servlet 2.2 and 2.3 specs.
+JK can, using the newer Ajpv13 protocol which relay many SSL informations required
by servlet 2.2 and 2.3 specs.
</p>
<p>
-jk offers a lot of different and flexible communications between a Web Server
+JK offers a lot of different and flexible communications between a Web Server
and the Tomcat Servlet Engine and could be used today with all of the ASF Tomcat
Engines,
<b>3.2.x</b>, <b>3.3.x</b>, <b>4.0.x</b>, <b>4.1.x</b> and <b>5.x</b>
</p>
</section>
-<section name="What's the difference between jk and jk2 ?">
+<section name="What's the difference between JK and JK2 ?">
<p>
-jk2 is a full rewrite of jk and is much more powerfull.
+JK2 is a full rewrite of JK and is much more powerfull.
</p>
<p>
-Even if it works with Apache 1.3, jk2 has been developed with Apache 2.0 in mind,
+Even if it works with Apache 1.3, JK2 has been developed with Apache 2.0 in mind,
and sus is better suited for multi-threaded servers like IIS, NES/iPlanet.
</p>
<p>
-jk2 has a better separation between protocol and physical layer.
-As such jk2 support fast unix-socket, and could be extended to support others
communications
+JK2 has a better separation between protocol and physical layer.
+As such JK2 support fast unix-socket, and could be extended to support others
communications
channels. Better it's suited for JNI and JDK 1.4 fast IO APIs
</p>
<p>
-jk2 could be monitored via special URLs (like mod_status)
+JK2 could be monitored via special URLs (like mod_status)
</p>
</section>
@@ -104,12 +104,12 @@
has a well defined protocol named <b>WARP</b>, does not care about the old
crappy protocols used in Tomcat-3.x and so.
But it would be possible to implement the <b>WARP</b> protocol in
-<b>jk2</b> ;-))
+<b>JK2</b> ;-))
</p>
<p>
The disadvantage is that it requires the <b>Apache Portable Library</b>
which is still only easily available via Apache 2.0 and that it didn't support
-WebServers like IIS, NES/iPlanet or Domino.
+webservers like IIS, NES/iPlanet or Domino.
</p>
</section>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
