hgomez 01/06/29 07:49:58 Modified: jk/doc AJPv14.txt Log: Update Ajp14 protocol description. - JkAutoMount directive format changed - We could now request/receive informations for multiple contexts at the same time. Revision Changes Path 1.5 +117 -82 jakarta-tomcat-connectors/jk/doc/AJPv14.txt Index: AJPv14.txt =================================================================== RCS file: /home/cvs/jakarta-tomcat-connectors/jk/doc/AJPv14.txt,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- AJPv14.txt 2001/06/07 13:38:56 1.4 +++ AJPv14.txt 2001/06/29 14:49:56 1.5 @@ -1,7 +1,7 @@ /*************************************************************************** * Description: Proposal for Apache JServ 1.4 * * Author: Henri Gomez <[EMAIL PROTECTED]> * - * Version: $Revision: 1.4 $ * + * Version: $Revision: 1.5 $ * ***************************************************************************/ This document is a proposal of evolution of the current @@ -71,6 +71,9 @@ * Extended env vars passed from web-server to servlet engine. +* Add extra SSL informations needed by Servlet 2.3 API (like SSL_KEY_SIZE) + + Advanced login -------------- @@ -96,7 +99,7 @@ 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). +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. @@ -116,25 +119,30 @@ - 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) | -+---------------------+-----------------------+ ++----------------+------------------+-----------------+ +| 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 | ++------------+--------------+ + +- LOGIN INIT CMD, LOGIN SEED CMD, LOGIN COMP CMD, LOGOK CMD, LOGNOK CMD are 1 byte long. +- MD5, MD5 of RANDOM + SECRET KEY are 32 chars long. +- NEGOCIATION DATA, NEGOCIED DATA, FAILURE CODE are 32 bits long. +- WEB SERVER INFO, SERVLET ENGINE INFO are CString. The secret key will be set by a new propertie in workers.properties : secretkey @@ -151,19 +159,22 @@ 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) | -+----------------------+-----------------------+ ++--------------+----------------------------+ +| SHUTDOWN CMD | MD5 of RANDOM + SECRET KEY | ++--------------+----------------------------+ + ++------------+ +| SHUTOK CMD | ++------------+ + ++-------------+--------------+ +| SHUTNOK CMD | FAILURE CODE | ++-------------+--------------+ + +- SHUTDOWN CMD, SHUTOK CMD, SHUTNOK CMD are 1 byte long. +- MD5 of RANDOM + SECRET KEY are 32 chars long. +- FAILURE CODE is 32 bits long. - Extended Env Vars feature ------------------------- @@ -215,9 +226,9 @@ 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) |... -+----------------------------+-------------------------------------+-----------------------------------------+ ++-------------------+---------------------------+-------------------------------+----+ +| EXTENDED VARS CMD | WEB SERVER ATTRIBUTE NAME | SERVLET ENGINE ATTRIBUTE NAME | ES | ++-------------------+---------------------------+-------------------------------+----+ ie : @@ -244,50 +255,62 @@ vars could be reused in the servlet engine. The cost will be only some more bytes in the AJP traffic. +- EXTENDED VARS CMD is 1 byte long. +- WEB SERVER ATTRIBUTE NAME, SERVLET ENGINE ATTRIBUTE NAME are CString. +- ES is an empty CString. + 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. +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 myworker1 +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. - -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 - +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. - 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 QRY CMD | VIRTUAL HOST NAME | CONTEXTA | CONTEXTB | ES | ++-----------------+-------------------+----------+----------+----+ + ++------------------+-------------------+----------+-------------------+----------+---------------+----+ +| CONTEXT INFO CMD | VIRTUAL HOST NAME | CONTEXTA | URL1 URL2 URL3 ES | CONTEXTB | URL1 URL2 ... | ES | ++------------------+-------------------+----------+-------------------+----------+---------------+----+ + +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 '*'. + +- CONTEXT QRY CMD and CONTEXT INFO CMD are 1 byte long. +- VIRTUAL HOST NAME is a CString, ie an array of chars terminated by a null byte (/0). +- An empty string is just a null byte (/0). +- ES is an empty CString. Indicate end of URI/URLs or end of CONTEXTs. +*) When VirtualMode is not to be used, the VIRTUAL HOST NAME is '*'. + In that case the servlet engine will send all contexts handled. Context informations updates from Servlet engine to Web Server --------------------------------------------------------------- @@ -298,31 +321,35 @@ ie: JkUpdateMount myworker1 -Also in this mode we may have a third parameter to handle the virtual -server to be used. ++--------------------+-------------------+----------+--------+----------+--------+----+ +| CONTEXT UPDATE CMD | VIRTUAL HOST NAME | CONTEXTA | STATUS | CONTEXTB | STATUS | ES | ++--------------------+-------------------+----------+--------+----------+--------+----+ + +- CONTEXT UPDATE CMD, STATUS are 1 byte long. +- VIRTUAL HOST NAME, CONTEXTS are CString. +- ES is an empty CString. Indicate end of CONTEXTs. -ie: JkUpdateMount myworker1 www.myvirtualserver.com +*) When VirtualMode is not in use, the VIRTUAL HOST NAME is '*'. +*) STATUS is one byte indicating if context is UP/DOWN/INVALID -+-----------------------------+---------------------------------+-------------------------+ -| 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. +contexts are UP, DOWN or INVALID (and should be removed). -+----------------------------+----------------------------------+----------------------------+ -| 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) | -+----------------------------------+---------------------------------+----------------------------+------------------+ ++-------------------+--------------------+----------+----------+----+ +| CONTEXT STATE CMD | VIRTUAL HOST NAME | CONTEXTA | CONTEXTB | ES | ++-------------------+--------------------+----------+----------+----+ + ++-------------------------+-------------------+----------+--------+----------+--------+----+ +| CONTEXT STATE REPLY CMD | VIRTUAL HOST NAME | CONTEXTA | STATUS | CONTEXTB | STATUS | ES | ++-------------------------+-------------------+----------+-------------------+--------+----+ + +- CONTEXT STATE CMD, CONTEXT STATE REPLY CMD, STATUS are 1 byte long. +- VIRTUAL HOST NAME, CONTEXTs are CString +- ES is an empty CString *) When VirtualMode is not in use, the VIRTUAL HOST NAME is an empty string. @@ -335,19 +362,26 @@ 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 (16bits) | UNHANDLED MESSAGE (bytes...) | -+-----------------------------+---------------------------------+------------------------------+ ++--------------------+------------------------+-------------------+ +| UNKNOWN PACKET CMD | UNHANDLED MESSAGE SIZE | UNHANDLED MESSAGE | ++--------------------+------------------------+-------------------+ Depending on the message, the sender will report an error and if possible will try to forward the message to another endpoint. +- UNKNOWN PACKET CMD is 1 byte long. +- UNHANDLED MESSAGE SIZE is 16bits long. +- UNHANDLED MESSAGE is an array of byte (length is contained in UNHANDLED MESSAGE SIZE) * added UNHANDLED MESSAGE SIZE (developpment) Verification of connection before sending request ------------------------------------------------- +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. @@ -385,10 +419,11 @@ 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) | -+---------------------+----------------------+ ++------------+-------------+ +| STATUS CMD | STATUS DATA | ++------------+-------------+ +- STATUS CMD and STATUS DATA are one byte long. Conclusion ----------