You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by hg...@apache.org on 2001/05/18 16:18:09 UTC
cvs commit: jakarta-tomcat-connectors/jk/src/doc AJPv14.txt
hgomez 01/05/18 07:18:07
Modified: jk/src/doc AJPv14.txt
Log:
Updated AJP14 documentation
Revision Changes Path
1.2 +452 -437 jakarta-tomcat-connectors/jk/src/doc/AJPv14.txt
Index: AJPv14.txt
===================================================================
RCS file: /home/cvs/jakarta-tomcat-connectors/jk/src/doc/AJPv14.txt,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- AJPv14.txt 2001/05/14 09:16:57 1.1
+++ AJPv14.txt 2001/05/18 14:18:01 1.2
@@ -1,437 +1,452 @@
-Proposal for Apache JServ 1.4 - Second Pass
-
-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 second pass include comments from the tomca-dev list
-
-Missing features in AJP13
--------------------------
-
-ajp13 is a good protocol to link a servlet engine like tomcat to a web server like Apache:
-
-* use persistants connections to avoid reconnect time at each request
-* encode many http commands to reduce stream size
-* send to servlet engine many info from web server (like SSL certs)
-
-But ajp13 lacks support for :
-
-* 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)
-
-* 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.
-
-* 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
-
-* 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.
-
-
-AJP14 add-ons to AJP13
-----------------------
-
-
-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'
-
-* Advanced login features at connect time
-
-* Basic authorisation system, where a shared secret key is
- present in web server and servlet engine.
-
-* Basic protocol negociation, just to be sure that if functionnalities are added
- to AJP14 in the future, current implementations will still works.
-
-* Clean handling of 'Unknown packets'
-
-* Extended env vars passed from web-server to servlet engine.
-
-Advanced login
---------------
-
-1) WEB-SERVER send LOGIN INIT CMD + NEGOCIATION DATA + WEB SERVER INFO
-
-2) TOMCAT respond with LOGIN SEED CMD + RANDOM DATA
-
-3) WEB-SERVER calculted the MD5 of RANDOM DATA+SECRET DATA
-
-4) WEB-SERVER send LOGIN COMP CMD + MD5 (SECRET DATA + RANDOM DATA)
-
-5) TOMCAT respond with LOGIN STATUS CMD + NEGOCIED DATA + SERVLET ENGINE INFO
-
-
-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.19 + mod_ssl 2.8.2 + mod_jk 3.3 + 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...).
-
-
-- Messages Stream -
-
-+-------------------------+---------------------------+---------------------------+
-| LOGIN INIT CMD (1 byte) | NEGOCIATION DATA (32bits) | WEB SERVER INFO (CString) |
-+-------------------------+---------------------------+---------------------------+
-
-+-------------------------+---------------------------+
-| LOGIN SEED CMD (1 byte) | MD5 of entropy (32 chars) |
-+-------------------------+---------------------------+
-
-+-------------------------+---------------------------------------+
-| LOGIN COMP CMD (1 byte) | MD5 of RANDOM + SECRET KEY (32 chars) |
-+-------------------------+---------------------------------------+
-
-+--------------------+------------------------+-------------------------------+
-| LOGOK CMD (1 byte) | NEGOCIED DATA (32bits) | SERVLET ENGINE INFO (CString) |
-+--------------------+------------------------+-------------------------------+
-
-+---------------------+-----------------------+
-| LOGNOK CMD (1 byte) | FAILURE CODE (32bits) |
-+---------------------+-----------------------+
-
-The secret key will be set by a new JkSecretKey
-
-ie: JkSecretKey myworker1 myverysecurekey
-
-
-Shutdown feature
-----------------
-
-AJP13 miss a functionnality of AJP12, which is shutdown command.
-A logout will tell servlet engine to shutdown itself.
-
-+-----------------------+---------------------------------------+
-| SHUTDOWN CMD (1 byte) | MD5 of RANDOM + SECRET KEY (32 chars) |
-+-----------------------+---------------------------------------+
-
-+---------------------+
-| SHUTOK CMD (1 byte) |
-+---------------------+
-
-+----------------------+-----------------------+
-| SHUTNOK CMD (1 byte) | FAILURE CODE (32bits) |
-+----------------------+-----------------------+
-
-
-Extended Env Vars feature
--------------------------
-
-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 :
-
-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)
-
-Using short 'web server attribute name' will reduce the
-network traffic.
-
-+----------------------------+-------------------------------------+-----------------------------------------+
-| EXTENDED VARS CMD (1 byte) | WEB SERVER ATTRIBUTE NAME (CString) | SERVLET ENGINE ATTRIBUTE NAME (CString) |...
-+----------------------------+-------------------------------------+-----------------------------------------+
-
-ie :
-
-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 |
-+----+-----------------------------------------+
-
-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.
-
-
-Context informations forwarding for Servlet engine to Web Server
-----------------------------------------------------------------
-
-Just after the LOGON PHASE, the web server will receive (if AJP14_CONTEXT_INFO_NEG is set)
-the list of contexts and URLs 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 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.
-
-The new JkAutoMount is adapted for that purpose. We add a third parameter
-in JkAutoMount to meet these requirement
-
-ie: JkAutoMount myworker1 www.myvirtualserver.com
-
-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.
-
-- Messages Stream -
-
-+--------------------------+---------------------------------+
-| CONTEXT QRY CMD (1 byte) | VIRTUAL HOST NAME (CString (*)) |
-+--------------------------+---------------------------------+
-
-+---------------------------+---------------------------------+-------------------------------+
-| CONTEXT INFO CMD (1 byte) | VIRTUAL HOST NAME (CString (*)) | URL1 [\n] URL2 [\n] URL3 [\n] |
-+---------------------------+---------------------------------+-------------------------------+
-
-*) The CString is a C string, ie an array of chars terminated by a null byte (/0).
- En empty string is just a null byte (/0).
-
-*) When VirtualMode is not to be used, the VIRTUAL HOST NAME is an empty string,
- the servlet engine will then send the whole context present.
-
-
-Context informations updates from Servlet engine to Web Server
----------------------------------------------------------------
-
-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
-
-Also in this mode we may have a third parameter to handle the virtual
-server to be used.
-
-ie: JkUpdateMount myworker1 www.myvirtualserver.com
-
-+-----------------------------+---------------------------------+-------------------------+
-| CONTEXT UPDATE CMD (1 byte) | VIRTUAL HOST NAME (CString (*)) | STATUS UP/DOWN (1 byte) |
-+-----------------------------+---------------------------------+-------------------------+
-
-*) When VirtualMode is not in use, the VIRTUAL HOST NAME is an empty string.
-
-
-Context status query to Servlet engine
---------------------------------------
-
-This query will be used by the web-server to determine if a given
-context is UP or DOWN.
-
-+----------------------------+----------------------------------+----------------------------+
-| CONTEXT STATE CMD (1 byte) | VIRTUAL HOST NAME (CString (*)) | CONTEXT NAME (CString (*)) |
-+----------------------------+----------------------------------+----------------------------+
-
-+----------------------------------+---------------------------------+----------------------------+------------------+
-| CONTEXT STATE REPLY CMD (1 byte) | VIRTUAL HOST NAME (CString (*)) | CONTEXT NAME (CString (*)) | UP/DOWN (1 byte) |
-+----------------------------------+---------------------------------+----------------------------+------------------+
-
-*) When VirtualMode is not in use, the VIRTUAL HOST NAME is an empty string.
-
-
-Handling of unknown packets
----------------------------
-
-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.
-
-+-----------------------------+------------------------------+
-| UNKNOWN PACKET CMD (1 byte) | UNHANDLED MESSAGE (bytes...) |
-+-----------------------------+------------------------------+
-
-Depending on the message, the sender will report an error and if
-possible will try to forward the message to another endpoint.
-
-
-Verification of connection before sending 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 :
-
-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)
-
-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.
-
-+---------------------+----------------------+
-| STATUS CMD (1 byte) | STATUS DATA (1 byte) |
-+---------------------+----------------------+
-
-
-Conclusion
-----------
-
-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.
-
-
-
-Commands and IDs in AJP14
--------------------------
-
-- Commands IDs -
-
-AJP14_LOGINIT_CMD 0x10
-AJP14_LOGSEED_CMD 0x11
-AJP14_LOGCOMP_CMD 0x12
-AJP14_LOGOK_CMD 0x13
-AJP14_LOGNOK_CMD 0x14
-AJP14_CONTEXT_QRY_CMD 0x15
-AJP14_CONTEXT_INFO_CMD 0x16
-AJP14_CONTEXT_UPDATE_CMD 0x17
-AJP14_STATUS_CMD 0x18
-AJP14_SHUTDOWN_CMD 0x19
-AJP14_SHUTOK_CMD 0x1A
-AJP14_SHUTNOK_CMD 0x1B
-AJP14_CONTEXT_STATE_CMD 0x1C
-AJP14_CONTEXT_STATE_REP_CMD 0x1D
-AJP14_UNKNOW_PACKET_CMD 0x1E
-
-- Negociations Flags -
-
-AJP14_CONTEXT_INFO_NEG 0x80000000 /* web-server want context info after login */
-AJP14_CONTEXT_UPDATE_NEG 0x40000000 /* web-server want context updates */
-AJP14_GZIP_STREAM_NEG 0x20000000 /* web-server want compressed stream */
-AJP14_DES56_STREAM_NEG 0x10000000 /* web-server want crypted DES56 stream with secret key */
-AJP14_SSL_VSERVER_NEG 0x08000000 /* Extended info on server SSL vars */
-AJP14_SSL_VCLIENT_NEG 0x04000000 /* Extended info on client SSL vars */
-AJP14_SSL_VCRYPTO_NEG 0x02000000 /* Extended info on crypto SSL vars */
-AJP14_SSL_VMISC_NEG 0x01000000 /* Extended info on misc SSL vars */
-
-AJP14_PROTO_SUPPORT_AJPXX_NEG 0x00FF0000 /* mask of protocol supported */
-AJP14_PROTO_SUPPORT_AJP14_NEG 0x00010000 /* communication could use AJP14 */
-AJP14_PROTO_SUPPORT_AJP15_NEG 0x00020000 /* communication could use AJP15 */
-AJP14_PROTO_SUPPORT_AJP16_NEG 0x00040000 /* communication could use AJP16 */
-...
-
-All others flags must be set to 0 since they are reserved for future use.
-
-- Failure IDs -
-
-AJP14_BAD_KEY_ERR 0xFFFFFFFF
-AJP14_ENGINE_DOWN_ERR 0xFFFFFFFE
-AJP14_RETRY_LATER_ERR 0xFFFFFFFD
-AJP14_SHUT_AUTHOR_FAILED_ERR 0xFFFFFFFC
-
-- Status -
-
-AJP14_CONTEXT_DOWN 0x01
-AJP14_CONTEXT_UP 0x02
-AJP14_CONTEXT_OK 0x03
+/***************************************************************************
+ * Description: Proposal for Apache JServ 1.4 *
+ * Author: Henri Gomez <hg...@slib.fr> *
+ * Version: $Revision: 1.2 $ *
+ ***************************************************************************/
+
+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 third pass include comments from the tomcat-dev list and
+misses discovered during developpment.
+
+Missing features in AJP13
+-------------------------
+
+ajp13 is a good protocol to link a servlet engine like tomcat to a web server like Apache:
+
+* use persistants connections to avoid reconnect time at each request
+* encode many http commands to reduce stream size
+* send to servlet engine many info from web server (like SSL certs)
+
+But ajp13 lacks support for :
+
+* 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)
+
+* 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.
+
+* 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
+
+* 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.
+
+
+AJP14 add-ons to AJP13
+----------------------
+
+
+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'
+
+* Advanced login features at connect time
+
+* Basic authorisation system, where a shared secret key is
+ present in web server and servlet engine.
+
+* Basic protocol negociation, just to be sure that if functionnalities are added
+ to AJP14 in the future, current implementations will still works.
+
+* Clean handling of 'Unknown packets'
+
+* Extended env vars passed from web-server to servlet engine.
+
+Advanced login
+--------------
+
+1) WEB-SERVER send LOGIN INIT CMD + NEGOCIATION DATA + WEB SERVER INFO
+
+2) TOMCAT respond with LOGIN SEED CMD + RANDOM DATA
+
+3) WEB-SERVER calculted the MD5 of RANDOM DATA+SECRET DATA
+
+4) WEB-SERVER send LOGIN COMP CMD + MD5 (SECRET DATA + RANDOM DATA)
+
+5) TOMCAT respond with LOGIN STATUS CMD + NEGOCIED DATA + SERVLET ENGINE INFO
+
+
+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.19 + mod_ssl 2.8.2 + mod_jk 3.3 + 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...).
+
+
+- Messages Stream -
+
++-------------------------+---------------------------+---------------------------+
+| LOGIN INIT CMD (1 byte) | NEGOCIATION DATA (32bits) | WEB SERVER INFO (CString) |
++-------------------------+---------------------------+---------------------------+
+
++-------------------------+---------------------------+
+| LOGIN SEED CMD (1 byte) | MD5 of entropy (32 chars) |
++-------------------------+---------------------------+
+
++-------------------------+---------------------------------------+
+| LOGIN COMP CMD (1 byte) | MD5 of RANDOM + SECRET KEY (32 chars) |
++-------------------------+---------------------------------------+
+
++--------------------+------------------------+-------------------------------+
+| LOGOK CMD (1 byte) | NEGOCIED DATA (32bits) | SERVLET ENGINE INFO (CString) |
++--------------------+------------------------+-------------------------------+
+
++---------------------+-----------------------+
+| LOGNOK CMD (1 byte) | FAILURE CODE (32bits) |
++---------------------+-----------------------+
+
+The secret key will be set by a new JkSecretKey
+
+ie: JkSecretKey myworker1 myverysecurekey
+
+
+Shutdown feature
+----------------
+
+AJP13 miss a functionnality of AJP12, which is shutdown command.
+A logout will tell servlet engine to shutdown itself.
+
++-----------------------+---------------------------------------+
+| SHUTDOWN CMD (1 byte) | MD5 of RANDOM + SECRET KEY (32 chars) |
++-----------------------+---------------------------------------+
+
++---------------------+
+| SHUTOK CMD (1 byte) |
++---------------------+
+
++----------------------+-----------------------+
+| SHUTNOK CMD (1 byte) | FAILURE CODE (32bits) |
++----------------------+-----------------------+
+
+
+Extended Env Vars feature
+-------------------------
+
+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 :
+
+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)
+
+Using short 'web server attribute name' will reduce the
+network traffic.
+
++----------------------------+-------------------------------------+-----------------------------------------+
+| EXTENDED VARS CMD (1 byte) | WEB SERVER ATTRIBUTE NAME (CString) | SERVLET ENGINE ATTRIBUTE NAME (CString) |...
++----------------------------+-------------------------------------+-----------------------------------------+
+
+ie :
+
+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 |
++----+-----------------------------------------+
+
+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.
+
+
+Context informations forwarding for Servlet engine to Web Server
+----------------------------------------------------------------
+
+Just after the LOGON PHASE, the web server will receive (if AJP14_CONTEXT_INFO_NEG is set)
+the list of contexts and URLs 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 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.
+
+The new JkAutoMount is adapted for that purpose. We add a third parameter
+in JkAutoMount to meet these requirement
+
+ie: JkAutoMount myworker1 www.myvirtualserver.com
+
+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.
+
+- Messages Stream -
+
++--------------------------+---------------------------------+
+| CONTEXT QRY CMD (1 byte) | VIRTUAL HOST NAME (CString (*)) |
++--------------------------+---------------------------------+
+
++---------------------------+---------------------------------+-------------------------------+
+| CONTEXT INFO CMD (1 byte) | VIRTUAL HOST NAME (CString (*)) | URL1 [\n] URL2 [\n] URL3 [\n] |
++---------------------------+---------------------------------+-------------------------------+
+
+*) The CString is a C string, ie an array of chars terminated by a null byte (/0).
+ En empty string is just a null byte (/0).
+
+*) When VirtualMode is not to be used, the VIRTUAL HOST NAME is an empty string,
+ the servlet engine will then send the whole context present.
+
+
+Context informations updates from Servlet engine to Web Server
+---------------------------------------------------------------
+
+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
+
+Also in this mode we may have a third parameter to handle the virtual
+server to be used.
+
+ie: JkUpdateMount myworker1 www.myvirtualserver.com
+
++-----------------------------+---------------------------------+-------------------------+
+| CONTEXT UPDATE CMD (1 byte) | VIRTUAL HOST NAME (CString (*)) | STATUS UP/DOWN (1 byte) |
++-----------------------------+---------------------------------+-------------------------+
+
+*) When VirtualMode is not in use, the VIRTUAL HOST NAME is an empty string.
+
+
+Context status query to Servlet engine
+--------------------------------------
+
+This query will be used by the web-server to determine if a given
+context is UP or DOWN.
+
++----------------------------+----------------------------------+----------------------------+
+| CONTEXT STATE CMD (1 byte) | VIRTUAL HOST NAME (CString (*)) | CONTEXT NAME (CString (*)) |
++----------------------------+----------------------------------+----------------------------+
+
++----------------------------------+---------------------------------+----------------------------+------------------+
+| CONTEXT STATE REPLY CMD (1 byte) | VIRTUAL HOST NAME (CString (*)) | CONTEXT NAME (CString (*)) | UP/DOWN (1 byte) |
++----------------------------------+---------------------------------+----------------------------+------------------+
+
+*) When VirtualMode is not in use, the VIRTUAL HOST NAME is an empty string.
+
+
+Handling of unknown packets
+---------------------------
+
+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.
+
++-----------------------------+---------------------------------+------------------------------+
+| UNKNOWN PACKET CMD (1 byte) | UNHANDLED MESSAGE SIZE (32bits) | UNHANDLED MESSAGE (bytes...) |
++-----------------------------+---------------------------------+------------------------------+
+
+Depending on the message, the sender will report an error and if
+possible will try to forward the message to another endpoint.
+
+* added UNHANDLED MESSAGE SIZE (developpment)
+
+
+Verification of connection before sending 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 :
+
+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)
+
+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.
+
++---------------------+----------------------+
+| STATUS CMD (1 byte) | STATUS DATA (1 byte) |
++---------------------+----------------------+
+
+
+Conclusion
+----------
+
+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.
+
+
+
+Commands and IDs in AJP14
+-------------------------
+
+- Commands IDs -
+
+AJP14_LOGINIT_CMD 0x10
+AJP14_LOGSEED_CMD 0x11
+AJP14_LOGCOMP_CMD 0x12
+AJP14_LOGOK_CMD 0x13
+AJP14_LOGNOK_CMD 0x14
+AJP14_CONTEXT_QRY_CMD 0x15
+AJP14_CONTEXT_INFO_CMD 0x16
+AJP14_CONTEXT_UPDATE_CMD 0x17
+AJP14_STATUS_CMD 0x18
+AJP14_SHUTDOWN_CMD 0x19
+AJP14_SHUTOK_CMD 0x1A
+AJP14_SHUTNOK_CMD 0x1B
+AJP14_CONTEXT_STATE_CMD 0x1C
+AJP14_CONTEXT_STATE_REP_CMD 0x1D
+AJP14_UNKNOW_PACKET_CMD 0x1E
+
+- Negociations Flags -
+
+AJP14_CONTEXT_INFO_NEG 0x80000000 /* web-server want context info after login */
+AJP14_CONTEXT_UPDATE_NEG 0x40000000 /* web-server want context updates */
+AJP14_GZIP_STREAM_NEG 0x20000000 /* web-server want compressed stream */
+AJP14_DES56_STREAM_NEG 0x10000000 /* web-server want crypted DES56 stream with secret key */
+AJP14_SSL_VSERVER_NEG 0x08000000 /* Extended info on server SSL vars */
+AJP14_SSL_VCLIENT_NEG 0x04000000 /* Extended info on client SSL vars */
+AJP14_SSL_VCRYPTO_NEG 0x02000000 /* Extended info on crypto SSL vars */
+AJP14_SSL_VMISC_NEG 0x01000000 /* Extended info on misc SSL vars */
+
+AJP14_PROTO_SUPPORT_AJPXX_NEG 0x00FF0000 /* mask of protocol supported */
+AJP14_PROTO_SUPPORT_AJP14_NEG 0x00010000 /* communication could use AJP14 */
+AJP14_PROTO_SUPPORT_AJP15_NEG 0x00020000 /* communication could use AJP15 */
+AJP14_PROTO_SUPPORT_AJP16_NEG 0x00040000 /* communication could use AJP16 */
+...
+
+All others flags must be set to 0 since they are reserved for future use.
+
+- Failure IDs -
+
+AJP14_BAD_KEY_ERR 0xFFFFFFFF
+AJP14_ENGINE_DOWN_ERR 0xFFFFFFFE
+AJP14_RETRY_LATER_ERR 0xFFFFFFFD
+AJP14_SHUT_AUTHOR_FAILED_ERR 0xFFFFFFFC
+
+- Status -
+
+AJP14_CONTEXT_DOWN 0x01
+AJP14_CONTEXT_UP 0x02
+AJP14_CONTEXT_OK 0x03