rubbos/app/tomcat-connectors-1.2.32-src/docs/ajp/printer/ajpv13ext.html

   1 <html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>The Apache Tomcat Connector - AJP Protocol Reference - AJPv13 extensions Proposal</title><meta name="author" value="Henri Gomez"><meta name="email" value="hgomez@apache.org"><link href="../../style.css" type="text/css" rel="stylesheet"></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="4"><!--PAGE HEADER--><tr><td colspan="2"><!--TOMCAT LOGO--><a href="http://tomcat.apache.org/"><img src="../../images/tomcat.gif" align="left" alt="Apache Tomcat" border="0"></a><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="http://www.apache.org/images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left"><table border="0" width="100%" cellspacing="4"><tr><td align="left" valign="top"><h1>The Apache Tomcat Connector - AJP Protocol Reference</h1><h2>AJPv13 extensions Proposal</h2></td><td align="right" valign="top" nowrap="true"><img src="../../images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
   2 <p>
   3 This document is a proposal of evolution of the current
   4 Apache JServ Protocol version 1.3, also known as ajp13.
   5 I'll not cover here the full protocol but only the add-on from ajp13.
   6
   7 This nth pass include comments from the tomcat-dev list and
   8 misses discovered during developpment.
   9 </p>
  10 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Missing features in AJP13"><strong>Missing features in AJP13</strong></a></font></td></tr><tr><td><blockquote>
  11 <p>
  12 ajp13 is a good protocol to link a servlet engine like tomcat to a web server like Apache:
  13
  14 <ul>
  15 <li>
  16 use persistants connections to avoid reconnect time at each request
  17 </li>
  18 <li>
  19 encode many http commands to reduce stream size
  20 </li>
  21 <li>
  22 send to servlet engine many info from web server (like SSL certs)
  23 </li>
  24 </ul>
  25 <p>
  26 But ajp13 lacks support for :
  27 </p>
  28 <ul>
  29 <li>
  30   security between web server and servlet engine.
  31   Anybody can connect to an ajp13 port (no login mecanism used)
  32   You could connect, for example with telnet, and keep the remote thread
  33   up by not sending any data (no timeout in connection)
  34 </li>
  35 <li>
  36   context information passed from servlet engine to web server.
  37   Part of the configuration of JK, the web server connector, is to
  38   indicate to the web server which URI to handle.
  39   The mod_jk JkMount directive, told to web server which URI must be
  40   forwarded to servlet engine.
  41   A servlet engine allready knows which URI it handle and TC 3.3 is
  42   allready capable to generate a config file for JK from the list
  43   of available contexts.
  44 </li>
  45 <li>
  46   state update of contexts from servlet engine to web server.
  47   Big site with farm of Tomcat, like ISP and virtuals hosters,
  48   may need to stop a context for admin purposes. In that case the front
  49   web server must know that the context is currently down, to eventually
  50   relay the request to another Tomcat
  51 </li>
  52 <li>
  53   verify state of connection before sending request.
  54   Actually JK send the request to the servlet engine and next wait
  55   for the answer. But one of the beauty of the socket API, is you that
  56   you could write() to a closed connection without any error reporting,
  57   but a read() to a closed connection return you the error code.
  58 </li>
  59 </ul>
  60
  61 </p>
  62 </blockquote></td></tr></table>
  63
  64 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Proposed add-ons to AJP13"><strong>Proposed add-ons to AJP13</strong></a></font></td></tr><tr><td><blockquote>
  65 <p>
  66 Let's descrive here the features and add-on that could be added to AJP13.
  67 Since this document is a proposal, a reasonable level of chaos must be expected at first.
  68 Be sure that discussion on tomcat list will help clarify points, add
  69 features but the current list seems to be a 'minimun vital'
  70
  71 <ul>
  72
  73 <li>
  74 Advanced login features at connect time
  75 </li>
  76
  77 <li>
  78 Basic authorisation system, where a shared secret key is
  79 present in web server and servlet engine.
  80 </li>
  81
  82 <li>
  83 Basic protocol negociation, just to be sure that if functionnalities are added
  84 to AJP13 in the future, current implementations will still works.
  85 </li>
  86
  87 <li>
  88 Clean handling of 'Unknown packets'
  89 </li>
  90
  91 <li>
  92 Extended env vars passed from web-server to servlet engine.
  93 </li>
  94
  95 <li>
  96 Add extra SSL informations needed by Servlet 2.3 API (like SSL_KEY_SIZE)
  97 </li>
  98
  99 </ul>
 100
 101 </p>
 102 </blockquote></td></tr></table>
 103
 104 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Advanced login"><strong>Advanced login</strong></a></font></td></tr><tr><td><blockquote>
 105 <p>
 106
 107 <ol>
 108 <li>
 109 WEB-SERVER send LOGIN INIT CMD + NEGOCIATION DATA + WEB SERVER INFO
 110 </li>
 111 <li>
 112   TOMCAT respond with LOGIN SEED CMD + RANDOM DATA
 113 </li>
 114 <li>
 115   WEB-SERVER calculted the MD5 of RANDOM DATA+SECRET DATA
 116 </li>
 117 <li>
 118   WEB-SERVER send LOGIN COMP CMD + MD5 (SECRET DATA + RANDOM DATA)
 119 </li>
 120 <li>
 121   TOMCAT respond with LOGIN STATUS CMD + NEGOCIED DATA + SERVLET ENGINE INFO
 122 </li>
 123 </ol>
 124
 125 To prevent DOS attack, the servlet engine will wait
 126 the LOGIN CMD only 15/30 seconds and reports the
 127 timeout exception for admins investigation.
 128
 129 The login command will contains basic protocol
 130 negociation information like compressing ability,
 131 crypto, context info (at start up), context update at
 132 run-time (up/down), level of SSL env vars, AJP protocol
 133 level supported (level1/level2/level3...)
 134
 135 The Web server info will contain web server info and
 136 connector name (ie Apache 1.3.26 + mod_ssl 2.8.8 + mod_jk 1.2.1 + mod_perl 1.25).
 137
 138 The servlet engine will mask the negociation mask with it's own
 139 mask (what it can do) and return it when loggin is accepted.
 140
 141 This will help having a basic AJP13 implementation (level 1)
 142 on a web-server working with a more advanced protocol handler on
 143 the servlet engine side or vice-versa.
 144
 145 AJP13 was designed to be small and fast and so many
 146 SSL informations present in the web-server are not
 147 forwarded to the servlet engine.
 148
 149 We add here four negociations flags to provide more
 150 informations on client SSL data (certs), server SSL datas,
 151 crypto used, and misc datas (timeout...).
 152 </p>
 153 </blockquote></td></tr></table>
 154
 155 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Messages Stream"><strong>Messages Stream</strong></a></font></td></tr><tr><td><blockquote>
 156 <p>
 157 <div class="example"><pre>
 158 +----------------+------------------+-----------------+
 159 | LOGIN INIT CMD | NEGOCIATION DATA | WEB SERVER INFO |
 160 +----------------+------------------+-----------------+
 161
 162 +----------------+----------------+
 163 | LOGIN SEED CMD | MD5 of entropy |
 164 +----------------+----------------+
 165
 166 +----------------+----------------------------+
 167 | LOGIN COMP CMD | MD5 of RANDOM + SECRET KEY |
 168 +----------------+----------------------------+
 169
 170 +-----------+---------------+---------------------+
 171 | LOGOK CMD | NEGOCIED DATA | SERVLET ENGINE INFO |
 172 +-----------+---------------+---------------------+
 173
 174 +------------+--------------+
 175 | LOGNOK CMD | FAILURE CODE |
 176 +------------+--------------+
 177 </pre></div>
 178
 179 <ul>
 180 <li>
 181 LOGIN INIT CMD, LOGIN SEED CMD, LOGIN COMP CMD, LOGOK CMD, LOGNOK CMD are 1 byte long.
 182 </li>
 183 <li>
 184 MD5, MD5 of RANDOM + SECRET KEY are 32 chars long.
 185 </li>
 186 <li>
 187 NEGOCIATION DATA, NEGOCIED DATA, FAILURE CODE are 32 bits long.
 188 </li>
 189 <li>
 190 WEB SERVER INFO, SERVLET ENGINE INFO are CString.
 191 </li>
 192 </ul>
 193
 194 The secret key will be set by a new propertie in
 195 workers.properties : secretkey
 196 <div class="example"><pre>
 197 worker.ajp13.port=8009
 198 worker.ajp13.host=localhost
 199 worker.ajp13.type=ajp13
 200 worker.ajp13.secretkey=myverysecretkey
 201 </pre></div>
 202 </p>
 203 </blockquote></td></tr></table>
 204
 205 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Shutdown feature"><strong>Shutdown feature</strong></a></font></td></tr><tr><td><blockquote>
 206 <p>
 207 AJP13 miss a functionnality of AJP12, which is shutdown command.
 208 A logout will tell servlet engine to shutdown itself.
 209 <div class="example"><pre>
 210 +--------------+----------------------------+
 211 | SHUTDOWN CMD | MD5 of RANDOM + SECRET KEY |
 212 +--------------+----------------------------+
 213
 214 +------------+
 215 | SHUTOK CMD |
 216 +------------+
 217
 218 +-------------+--------------+
 219 | SHUTNOK CMD | FAILURE CODE |
 220 +-------------+--------------+
 221 </pre></div>
 222
 223 <ul>
 224 <li>
 225 SHUTDOWN CMD, SHUTOK CMD, SHUTNOK CMD are 1 byte long.
 226 </li>
 227 <li>
 228 MD5 of RANDOM + SECRET KEY are 32 chars long.
 229 </li>
 230 <li>
 231 FAILURE CODE is 32 bits long.
 232 </li>
 233 </ul>
 234
 235 </p>
 236 </blockquote></td></tr></table>
 237
 238 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Extended Env Vars feature"><strong>Extended Env Vars feature</strong></a></font></td></tr><tr><td><blockquote>
 239 <p>
 240 NOTA:
 241
 242 While working on AJP13 in JK, I really discovered "JkEnvVar".
 243 The following "Extended Env Vars feature" description may not
 244 be implemented in extended AJP13 since allready available in original
 245 implementation.
 246
 247 DESC:
 248
 249 Many users will want to see some of their web-server env vars
 250 passed to their servlet engine.
 251
 252 To reduce the network traffic, the web-servlet will send a
 253 table to describing the external vars in a shorter fashion.
 254
 255 We'll use there a functionnality allready present in AJP13,
 256 attributes list :
 257
 258 In the AJP13, we've got :
 259
 260 <div class="example"><pre>
 261 AJP13_FORWARD_REQUEST :=
 262     prefix_code      2
 263     method           (byte)
 264     protocol         (string)
 265     req_uri          (string)
 266     remote_addr      (string)
 267     remote_host      (string)
 268     server_name      (string)
 269     server_port      (integer)
 270     is_ssl           (boolean)
 271     num_headers      (integer)
 272     request_headers *(req_header_name req_header_value)
 273
 274     ?context       (byte string)
 275     ?servlet_path  (byte string)
 276     ?remote_user   (byte string)
 277     ?auth_type     (byte string)
 278     ?query_string  (byte string)
 279     ?route         (byte string)
 280     ?ssl_cert      (byte string)
 281     ?ssl_cipher    (byte string)
 282     ?ssl_session   (byte string)
 283
 284     ?attributes   *(attribute_name attribute_value)
 285     request_terminator (byte)
 286 </pre></div>
 287
 288 Using short 'web server attribute name' will reduce the
 289 network traffic.
 290
 291 <div class="example"><pre>
 292 +-------------------+---------------------------+-------------------------------+----+
 293 | EXTENDED VARS CMD | WEB SERVER ATTRIBUTE NAME | SERVLET ENGINE ATTRIBUTE NAME | ES |
 294 +-------------------+---------------------------+-------------------------------+----+
 295 </pre></div>
 296
 297 ie :
 298
 299 <div class="example"><pre>
 300 JkExtVars S1 SSL_CLIENT_V_START javax.servlet.request.ssl_start_cert_date
 301 JkExtVars S2 SSL_CLIENT_V_END   javax.servlet.request.ssl_end_cert_date
 302 JkExtVars S3 SSL_SESSION_ID     javax.servlet.request.ssl_session_id
 303
 304
 305 +-------------------+----+-------------------------------------------+
 306 | EXTENDED VARS CMD | S1 | javax.servlet.request.ssl_start_cert_date |
 307 +-------------------+----+-------------------------------------------+
 308 +----+-----------------------------------------+
 309 | S2 | javax.servlet.request.ssl_end_cert_date |
 310 +----+-----------------------------------------+
 311 +----+-----------------------------------------+
 312 | S3 | javax.servlet.request.ssl_end_cert_date |
 313 +----+-----------------------------------------+
 314 </pre></div>
 315
 316 During transmission in extended AJP13 we'll see attributes name
 317 containing S1, S2, S3 and attributes values of
 318 2001/01/03, 2002/01/03, 0123AFE56.
 319
 320 This example showed the use of extended SSL vars but
 321 any 'personnal' web-server vars like custom authentification
 322 vars could be reused in the servlet engine.
 323 The cost will be only some more bytes in the AJP traffic.
 324
 325 <ul>
 326 <li>
 327 EXTENDED VARS CMD is 1 byte long.
 328 </li>
 329 <li>
 330 WEB SERVER ATTRIBUTE NAME, SERVLET ENGINE ATTRIBUTE NAME are CString.
 331 </li>
 332 <li>
 333 ES is an empty CString.
 334 </li>
 335 </ul>
 336
 337 </p>
 338 </blockquote></td></tr></table>
 339
 340 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Context informations forwarding for Servlet engine to Web Server"><strong>Context informations forwarding for Servlet engine to Web Server</strong></a></font></td></tr><tr><td><blockquote>
 341 <p>
 342 Just after the LOGON PHASE, the web server will ask for the list of contexts
 343 and URLs/URIs handled by the servlet engine.
 344 It will ease installation in many sites, reduce questions about configuration
 345 on tomcat-user list, and be ready for servlet API 2.3.
 346
 347 This mode will be activated by a new directive JkAutoMount
 348
 349 ie: JkAutoMount examples myworker1 /examples/
 350
 351 If we want to get ALL the contexts handled by the servlet engine, willcard
 352 could be used :
 353
 354 ie: JkAutoMount * myworker1 *
 355
 356 A servlet engine could have many contexts, /examples, /admin, /test.
 357 We may want to use only some contexts for a given worker. It was
 358 done previously, in apache HTTP server for example, by setting by
 359 hand the JkMount accordingly in each [virtual] area of Apache.
 360
 361 If you web-server support virtual hosting, we'll forward also that
 362 information to servlet engine which will only return contexts for
 363 that virtual host.
 364 In that case the servlet engine will only return the URL/URI matching
 365 these particular virtual server (defined in server.xml).
 366 This feature will help ISP and big sites which mutualize large farm
 367 of Tomcat in load-balancing configuration.
 368
 369 <div class="example"><pre>
 370 +-----------------+-------------------+----------+----------+----+
 371 | CONTEXT QRY CMD | VIRTUAL HOST NAME | CONTEXTA | CONTEXTB | ES |
 372 +-----------------+-------------------+----------+----------+----+
 373
 374 +------------------+-------------------+----------+-------------------+----------+---------------+----+
 375 | CONTEXT INFO CMD | VIRTUAL HOST NAME | CONTEXTA | URL1 URL2 URL3 ES | CONTEXTB | URL1 URL2 ... | ES |
 376 +------------------+-------------------+----------+-------------------+----------+---------------+----+
 377 </pre></div>
 378
 379 We'll discover via context-query, the list of URL/MIMES handled by the remove servlet engine
 380 for a list of contextes.
 381 In wildcard mode, CONTEXTA will contains just '*'.
 382
 383 <ul>
 384 <li>
 385 CONTEXT QRY CMD and CONTEXT INFO CMD are 1 byte long.
 386 </li>
 387 <li>
 388 VIRTUAL HOST NAME is a CString, ie an array of chars terminated by a null byte (/0).
 389 </li>
 390 <li>
 391 An empty string is just a null byte (/0).
 392 </li>
 393 <li>
 394 ES is an empty CString. Indicate end of URI/URLs or end of CONTEXTs.
 395 </li>
 396 </ul>
 397
 398 NB:<br>
 399 When VirtualMode is not to be used, the VIRTUAL HOST NAME is '*'.
 400 In that case the servlet engine will send all contexts handled.
 401 </p>
 402 </blockquote></td></tr></table>
 403
 404 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Context informations updates from Servlet engine to Web Server"><strong>Context informations updates from Servlet engine to Web Server</strong></a></font></td></tr><tr><td><blockquote>
 405 <p>
 406 Context update are messages caming from the servlet engine each time a context
 407 is desactivated/reactivated. The update will be in use when the directive JkUpdateMount.
 408 This directive will set the AJP13_CONTEXT_UPDATE_NEG flag.
 409
 410 ie: JkUpdateMount myworker1
 411
 412 <div class="example"><pre>
 413 +--------------------+-------------------+----------+--------+----------+--------+----+
 414 | CONTEXT UPDATE CMD | VIRTUAL HOST NAME | CONTEXTA | STATUS | CONTEXTB | STATUS | ES |
 415 +--------------------+-------------------+----------+--------+----------+--------+----+
 416 </pre></div>
 417
 418 <ul>
 419 <li>
 420 CONTEXT UPDATE CMD, STATUS are 1 byte long.
 421 </li>
 422 <li>
 423 VIRTUAL HOST NAME, CONTEXTS are CString.
 424 </li>
 425 <li>
 426 ES is an empty CString. Indicate end of CONTEXTs.
 427 </li>
 428 </ul>
 429
 430 NB:<br>
 431 When VirtualMode is not in use, the VIRTUAL HOST NAME is '*'.
 432 STATUS is one byte indicating if context is UP/DOWN/INVALID
 433 </p>
 434 </blockquote></td></tr></table>
 435
 436 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Context status query to Servlet engine"><strong>Context status query to Servlet engine</strong></a></font></td></tr><tr><td><blockquote>
 437 <p>
 438 This query will be used by the web-server to determine if a given
 439 contexts are UP, DOWN or INVALID (and should be removed).
 440
 441 <div class="example"><pre>
 442 +-------------------+--------------------+----------+----------+----+
 443 | CONTEXT STATE CMD |  VIRTUAL HOST NAME | CONTEXTA | CONTEXTB | ES |
 444 +-------------------+--------------------+----------+----------+----+
 445
 446 +-------------------------+-------------------+----------+--------+----------+--------+----+
 447 | CONTEXT STATE REPLY CMD | VIRTUAL HOST NAME | CONTEXTA | STATUS | CONTEXTB | STATUS | ES |
 448 +-------------------------+-------------------+----------+-------------------+--------+----+
 449 </pre></div>
 450
 451 <ul>
 452 <li>
 453 CONTEXT STATE CMD, CONTEXT STATE REPLY CMD, STATUS are 1 byte long.
 454 </li>
 455 <li>
 456 VIRTUAL HOST NAME, CONTEXTs are CString
 457 </li>
 458 <li>
 459 ES is an empty CString
 460 </li>
 461 </ul>
 462
 463 NB:<br>
 464 When VirtualMode is not in use, the VIRTUAL HOST NAME is an empty string.
 465 </p>
 466 </blockquote></td></tr></table>
 467
 468 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Handling of unknown packets"><strong>Handling of unknown packets</strong></a></font></td></tr><tr><td><blockquote>
 469 <p>
 470 Sometimes even with a well negocied protocol, we may be in a situation
 471 where one end (web server or servlet engine), will receive a message it
 472 couldn't understand. In that case the receiver will send an
 473 'UNKNOW PACKET CMD' with attached the unhandled message.
 474
 475 <div class="example"><pre>
 476 +--------------------+------------------------+-------------------+
 477 | UNKNOWN PACKET CMD | UNHANDLED MESSAGE SIZE | UNHANDLED MESSAGE |
 478 +--------------------+------------------------+-------------------+
 479 </pre></div>
 480
 481 Depending on the message, the sender will report an error and if
 482 possible will try to forward the message to another endpoint.
 483
 484 <ul>
 485 <li>
 486 UNKNOWN PACKET CMD is 1 byte long.
 487 </li>
 488 <li>
 489 UNHANDLED MESSAGE SIZE is 16bits long.
 490 </li>
 491 <li>
 492 UNHANDLED MESSAGE is an array of byte (length is contained in UNHANDLED MESSAGE SIZE)
 493 </li>
 494 </ul>
 495
 496 NB:<br>
 497 added UNHANDLED MESSAGE SIZE (development)
 498 </p>
 499 </blockquote></td></tr></table>
 500
 501 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Verification of connection before sending request"><strong>Verification of connection before sending request</strong></a></font></td></tr><tr><td><blockquote>
 502 <p>
 503 NOTA: This fonctionality may never be used, since it may slow up the normal process
 504 since requiring on the web-server side an extra IO (read) before forwarding
 505 the request.....
 506
 507 One of the beauty of socket APIs, is that you could write on a half closed socket.
 508 When servlet engine close the socket, the web server will discover it only at the
 509 next read() to the socket.
 510 Basically, in the AJP13 protocol, the web server send the HTTP HEADER and HTTP BODY
 511 (POST by chunk of 8K) to the servlet engine and then try to receive the reply.
 512 If the connection was broken the web server will learn it only at receive time.
 513
 514 We could use a buffering scheme but what happen when you use the servlet engine
 515 for upload operations with more than 8ko of datas ?
 516
 517 The hack in the AJP13 protocol is to add some bytes to read after the end of the
 518 service :
 519
 520 <div class="example"><pre>
 521 EXAMPLE OF DISCUSSION BETWEEN WEB SERVER AND SERVLET ENGINE
 522
 523 AJP HTTP-HEADER (+ HTTP-POST)   (WEB-&gt;SERVLET)
 524
 525 AJP HTTP-REPLY                                  (SERVLET-&gt;WEB)
 526
 527 AJP END OF DISCUSSION                   (SERVLET-&gt;WEB)
 528
 529 ---&gt; AJP STATUS                              (SERVLET-&gt;WEB AJP13)
 530 </pre></div>
 531
 532 The AJP STATUS will not be read by the servlet engine at the end of
 533 the request/response #N but at the begining of the next session.
 534
 535 More at that time the web server could also use OS dependants functions
 536 (or better APR functions) to determine if there is also more data
 537 to read. And that datas could be CONTEXT Updates.
 538
 539 This will avoid the web server sending a request to a
 540 desactivated context. In that case, if the load-balancing is used,
 541 it will search for another servlet engine to handle the request.
 542
 543 And that feature will help ISP and big sites with farm of tomcat,
 544 to updates their servlet engine without any service interruption.
 545
 546 <div class="example"><pre>
 547 +------------+-------------+
 548 | STATUS CMD | STATUS DATA |
 549 +------------+-------------+
 550 </pre></div>
 551
 552 <ul>
 553 <li>
 554 STATUS CMD and STATUS DATA are one byte long.
 555 </li>
 556 </ul>
 557 </p>
 558 </blockquote></td></tr></table>
 559
 560 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Conclusion"><strong>Conclusion</strong></a></font></td></tr><tr><td><blockquote>
 561 <p>
 562 The goal of the extended AJP13 protocol is to overcome some of the original AJP13 limitation.
 563 An easier configuration, a better support for large site and farm of Tomcat,
 564 a simple authentification system and provision for protocol updates.
 565
 566 Using the stable ajp13 implementation in JK (native) and in servlet
 567 engine (java), it's a reasonable evolution of the well known ajp13.
 568 </p>
 569 </blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Commands and IDs in extended AJP13 Index"><strong>Commands and IDs in extended AJP13 Index</strong></a></font></td></tr><tr><td><blockquote>
 570 <p>
 571 Index of Commands and ID to be added in AJP13 Protocol
 572 </p>
 573
 574 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Commands IDs"><strong>Commands IDs</strong></a></font></td></tr><tr><td><blockquote>
 575 <p>
 576 <table>
 577   <tr><th>Command Name</th><th>Command Number</th></tr>
 578   <tr><td>AJP13_LOGINIT_CMD</td><td>0x10</td></tr>
 579   <tr><td>AJP13_LOGSEED_CMD</td><td>0x11</td></tr>
 580   <tr><td>AJP13_LOGCOMP_CMD</td><td>0x12</td></tr>
 581   <tr><td>AJP13_LOGOK_CMD</td><td>0x13</td></tr>
 582   <tr><td>AJP13_LOGNOK_CMD</td><td>0x14</td></tr>
 583   <tr><td>AJP13_CONTEXT_QRY_CMD</td><td>0x15</td></tr>
 584   <tr><td>AJP13_CONTEXT_INFO_CMD</td><td>0x16</td></tr>
 585   <tr><td>AJP13_CONTEXT_UPDATE_CMD</td><td>0x17</td></tr>
 586   <tr><td>AJP13_STATUS_CMD</td><td>0x18</td></tr>
 587   <tr><td>AJP13_SHUTDOWN_CMD</td><td>0x19</td></tr>
 588   <tr><td>AJP13_SHUTOK_CMD</td><td>0x1A</td></tr>
 589   <tr><td>AJP13_SHUTNOK_CMD</td><td>0x1B</td></tr>
 590   <tr><td>AJP13_CONTEXT_STATE_CMD</td><td>0x1C</td></tr>
 591   <tr><td>AJP13_CONTEXT_STATE_REP_CMD</td><td>0x1D</td></tr>
 592   <tr><td>AJP13_UNKNOW_PACKET_CMD</td><td>0x1E</td></tr>
 593 </table>
 594
 595 </p>
 596 </blockquote></td></tr></table>
 597
 598 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Negociations Flags"><strong>Negociations Flags</strong></a></font></td></tr><tr><td><blockquote>
 599 <p>
 600 <table>
 601   <tr><th>Command Name</th><th>Number</th><th>Description</th></tr>
 602   <tr><td>AJP13_CONTEXT_INFO_NEG</td><td>0x80000000</td><td>web-server want context info after login</td></tr>
 603   <tr><td>AJP13_CONTEXT_UPDATE_NEG</td><td>0x40000000</td><td>web-server want context updates</td></tr>
 604   <tr><td>AJP13_GZIP_STREAM_NEG</td><td>0x20000000</td><td>web-server want compressed stream</td></tr>
 605   <tr><td>AJP13_DES56_STREAM_NEG</td><td>0x10000000</td><td>web-server want crypted DES56 stream with secret key</td></tr>
 606   <tr><td>AJP13_SSL_VSERVER_NEG</td><td>0x08000000</td><td>Extended info on server SSL vars</td></tr>
 607   <tr><td>AJP13_SSL_VCLIENT_NEG</td><td>0x04000000</td><td>Extended info on client SSL vars</td></tr>
 608   <tr><td>AJP13_SSL_VCRYPTO_NEG</td><td>0x02000000</td><td>Extended info on crypto SSL vars</td></tr>
 609   <tr><td>AJP13_SSL_VMISC_NEG</td><td>0x01000000</td><td>Extended info on misc SSL vars</td></tr>
 610 </table>
 611
 612 <br>
 613
 614 <table>
 615   <tr><th>Negociation ID</th><th>Number</th><th>Description</th></tr>
 616   <tr><td>AJP13_PROTO_SUPPORT_AJPXX_NEG</td><td>0x00FF0000</td><td>mask of protocol supported</td></tr>
 617   <tr><td>AJP13_PROTO_SUPPORT_AJP13L1_NEG</td><td>0x00010000</td><td>communication could use AJP13 Level 1</td></tr>
 618   <tr><td>AJP13_PROTO_SUPPORT_AJP13L2_NEG</td><td>0x00020000</td><td>communication could use AJP13 Level 2</td></tr>
 619   <tr><td>AJP13_PROTO_SUPPORT_AJP13L3_NEG</td><td>0x00040000</td><td>communication could use AJP13 Level 3</td></tr>
 620 </table>
 621
 622 <br>
 623 All others flags must be set to 0 since they are reserved for future use.
 624
 625 </p>
 626 </blockquote></td></tr></table>
 627
 628 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Failure IDs"><strong>Failure IDs</strong></a></font></td></tr><tr><td><blockquote>
 629 <p>
 630 <table>
 631   <tr><th>Failure Id</th><th>Number</th></tr>
 632   <tr><td>AJP13_BAD_KEY_ERR</td><td>0xFFFFFFFF</td></tr>
 633   <tr><td>AJP13_ENGINE_DOWN_ERR</td><td>0xFFFFFFFE</td></tr>
 634   <tr><td>AJP13_RETRY_LATER_ERR</td><td>0xFFFFFFFD</td></tr>
 635   <tr><td>AJP13_SHUT_AUTHOR_FAILED_ERR</td><td>0xFFFFFFFC</td></tr>
 636 </table>
 637 </p>
 638 </blockquote></td></tr></table>
 639
 640 <table border="0" cellspacing="0" cellpadding="2" width="100%"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Status"><strong>Status</strong></a></font></td></tr><tr><td><blockquote>
 641 <p>
 642 <table>
 643   <tr><th>Failure Id</th><th>Number</th></tr>
 644   <tr><td>AJP13_CONTEXT_DOWN</td><td>0x01</td></tr>
 645   <tr><td>AJP13_CONTEXT_UP</td><td>0x02</td></tr>
 646   <tr><td>AJP13_CONTEXT_OK</td><td>0x03</td></tr>
 647 </table>
 648 </p>
 649 </blockquote></td></tr></table>
 650
 651 </blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
 652         Copyright &copy; 1999-2011, Apache Software Foundation
 653         </em></font></div></td></tr></table></body></html>