1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.ja.xsl"?>
4 <!-- English Revision: 669473:1792168 (outdated) -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <modulesynopsis metafile="mod_proxy_ajp.xml.meta">
25 <name>mod_proxy_ajp</name>
26 <description><module>mod_proxy</module> で AJP
27 をサポートするためのモジュール</description>
28 <status>Extension</status>
29 <sourcefile>mod_proxy_ajp.c</sourcefile>
30 <identifier>proxy_ajp_module</identifier>
33 <p>本モジュールには <module>mod_proxy</module> が<em>必要です</em>。
34 <code>Apache JServ Protocol version 1.3</code> (以降 <em>AJP13</em>)
37 <p><code>AJP13</code> プロトコルを扱えるようにするには
38 <module>mod_proxy</module> と <module>mod_proxy_ajp</module>
41 <note type="warning"><title>警告</title>
43 >安全なサーバにする</a>までプロクシ機能は有効にしないでください。
44 オープンプロキシサーバはあなた自身のネットワークにとっても、
45 インターネット全体にとっても危険です。</p>
49 <seealso><module>mod_proxy</module></seealso>
51 <section id="overviewprotocol"><title>プロトコルの概要</title>
52 <p><code>AJP13</code> プロトコルはパケット指向です。
53 可読なプレーンテキスト形式ではなくバイナリ形式になったのは、
55 ウェブサーバはサーブレットコンテナと TCP コネクションで通信します。
56 ソケット生成は重い処理なので、負荷を減らすために、サーブレットコンテナとの
57 TCP 接続を維持し、複数のリクエスト・レスポンス処理サイクルに対して一つの
58 コネクションを使いまわすようになっています。</p>
59 <p>あるリクエストにコネクションが割り当てられると、その処理サイクルが
60 完了するまで他のものに使われることはありません。
61 つまりコネクション上では、リクエストの同時処理は行われません。
62 このため、コネクション両端での実行するコードを簡潔にできる一方で、
63 同時に開くコネクションは多くなっています。</p>
64 <p>サーブレットコンテナへのコネクションを開いた後は、コネクションの状態は
67 <li> Idle <br />コネクション上で処理されているリクエストはありません。</li>
68 <li> Assigned <br />コネクションはリクエストを処理中です。</li>
70 <p>コネクションが特定のリクエストにアサインされると、基本的な情報 (例えば
71 HTTP ヘッダ等) が圧縮された形 (例えば通常の文字列は整数にエンコードされます)
72 で転送されます。詳細は下記の「リクエストパケットの構造」を参照してください。
73 リクエストにボディが存在 <code>(content-length > 0)</code> すれば、
74 基本的な情報の直後に別パケットで転送されます。</p>
75 <p>この時点でおそらく、サーブレットコンテナは処理を開始できるようになります。
76 ですので、次のメッセージをウェブサーバに戻して知らせられるようになります。</p>
78 <li>SEND_HEADERS <br/>ブラウザにヘッダを送信します。</li>
79 <li>SEND_BODY_CHUNK <br/>ブラウザにボディデータのチャンクを送ります。
81 <li>GET_BODY_CHUNK <br/>リクエストのデータを全て受け取り終わっていないときに、
82 残っているデータを受け取ります。パケットにある定まった最大長があり、任意の
83 大きさのデータがリクエストのボディとして含まれうる場合
84 (例えばファイルのアップロードの場合) に必要となります。
85 (注: HTTP のチャンク転送とは関連ありません。)</li>
86 <li>END_RESPONSE <br/>リクエスト処理サイクルを終了します。</li>
88 <p>個々のメッセージはそれぞれ異なるデータパケット形式になっています。
89 後述の「レスポンスパケットの構造」を参照してください。</p>
92 <section id="basppacketstruct"><title>基本パケット構造</title>
93 <p>このプロトコルには XDR から受け継いだ部分が少しありますが、多くの点で
94 異なります (例えば 4 バイトアライメントでないことなど) 。</p>
95 <p>バイトオーダー: 個々のバイトのエンディアンがどうなっているかは、
96 私は詳しくないのですが、リトルエンディアンになっていると思います。
97 XDR 仕様でそうなっているのと、素晴らしいことに sys/socket ライブラリが
98 (C で) そういう風にできているのでそうなのだと思いました。
99 ソケット呼び出しの内部についてより詳しい方がいらっしゃいましたら、
101 <p>プロトコルには 4 つのデータタイプがあります: byte, boolean,
102 integer, string です。</p>
104 <dt><strong>Byte</strong></dt><dd>バイト一つです。</dd>
105 <dt><strong>Boolean</strong></dt>
106 <dd>バイト一つで、<code>1 = true</code>, <code>0 = false</code> です。
107 (C のように) 非零を真として扱ってしまうと、ある場合は動くかもしれませんし、
109 <dt><strong>Integer</strong></dt>
110 <dd><code>0 から 2^16 (32768)</code> の範囲の数字。高次の 2 バイトが
112 <dt><strong>String</strong></dt>
113 <dd>可変長の文字列 (2^16 が長さの上限) 。長さ情報のパケット 2 バイトの後に
114 文字列 (終端文字 '\0' を含む) が続く形式でエンコードされます。
115 エンコードされている長さ情報は最後の '\0' を<strong>カウントしない</strong>
116 ことに注意してください――これは <code>strlen</code> と同様です。
117 これらの終端文字をスキップするために、あまり意味の無いインクリメント文
119 Java の側から見ると少し紛らわしく感じられるかもしれません。
120 こうなった理由はおそらく、Servlet コンテナから返される文字列を読み出す時に、
121 効率よく C のコードを書けるようにする――サーブレットから返される
122 文字列は \0 文字で終端されているので、C のコードではわざわざコピーをせずに、
123 一つのバッファへのリファレンスを取り回すように書くことができる――
125 '\0' 文字がない場合は、C では文字列の規則に合うようにコピーしなければ
129 <section><title>パケットサイズ</title>
130 <p>多くのコードでそうなっているのですが、パケットサイズの最大サイズは
131 <code>8 * 1024 (8K)</code> です。パケットの実際の長さはヘッダに
134 <section><title>パケットヘッダ</title>
135 <p>サーバからコンテナに送出されるパケットは <code>0x1234</code> で始まります。
136 コンテナからサーバに送られるパケットは <code>AB</code> (ASCII コード A と
137 ASCII コード B) で始まります。この二バイトの後に、ペイロード長が (上記の形式で)
138 続きます。このため、ペイロード長の最大値は 2^16 にできるように思えますが、
139 実際にはコードでは最大値は 8K に設定されています。</p>
142 <td colspan="6"><em>パケット形式 (Server->Container)</em></td>
156 <td colspan="2">データ長 (n)</td>
162 <td colspan="6"><em>パケット形式 (Container->Server)</em></td>
176 <td colspan="2">データ長 (n)</td>
180 <p>ほとんどのパケットで、ペイロードの最初のバイトがメッセージの型をエンコード
181 しています。例外はサーバからコンテナに送られるリクエストボディパケットです
182 ――これらは標準的なパケット形式 (<code>0x1234</code> とパケット長)
183 ですが、その後に続くプレフィックスコードがありません。</p>
184 <p>ウェブサーバは次のメッセージをサーブレットコンテナに送出できます。</p>
193 <td>Forward Request</td>
194 <td>リクエスト処理サイクルを後続のデータとともに開始する。</td>
199 <td>ウェブサーバがコンテナに、コンテナを終了するように伝える。</td>
204 <td>ウェブサーバがコンテナに制御を受け持つように伝える
205 (セキュアログインフェーズ) 。</td>
210 <td>ウェブサーバがコンテナに CPong で即座に応答するように伝える。</td>
215 <td>サイズ (2 バイト) とそれに続くボディデータ。</td>
218 <p>基本的なセキュリティを確保するため、ホストされているマシンと同一の
219 マシンからのリクエストに対してのみ、コンテナは実際に <code>Shutdown</code>
221 <p>最初の <code>Data</code> パケットは、<code>Forward Request</code>
222 の直後にウェブサーバから送られます。</p>
223 <p>サーブレットコンテナはウェブサーバに、次のタイプのメッセージを送ることが
233 <td>Send Body Chunk</td>
234 <td>サーブレットコンテナからウェブサーバに
235 (そしておそらくそのままブラウザに)、ボディのチャンクを送る。</td>
239 <td>Send Headers</td>
240 <td>サーブレットコンテナからウェブサーバに (そしておそらくそのままブラウザに)
245 <td>End Response</td>
246 <td>レスポンス (つまりリクエスト処理サイクル) 終了の目印を送る。
251 <td>Get Body Chunk</td>
252 <td>まだ全て転送されていない場合、残っているリクエストのデータを受け取る。
258 <td>CPing リクエストに応答する。</td>
261 <p>上記メッセージは、それぞれ内部構造が異なっています。詳細は下記をご覧ください。
265 <section id="rpacetstruct"><title>リクエストパケット構造</title>
266 <p>サーバからコンテナへ送られるメッセージが
267 <em>Forward Request</em> 型の場合 :</p>
269 AJP13_FORWARD_REQUEST :=
270 prefix_code (byte) 0x02 = JK_AJP13_FORWARD_REQUEST
277 server_port (integer)
279 num_headers (integer)
280 request_headers *(req_header_name req_header_value)
281 attributes *(attribut_name attribute_value)
282 request_terminator (byte) OxFF
284 <p><code>request_headers</code> は次のような構造になっています :
287 sc_req_header_name | (string) [see below for how this is parsed]
289 sc_req_header_name := 0xA0xx (integer)
291 req_header_value := (string)
293 <p><code>属性</code> はオプションで、次のような構造をしています :</p>
295 attribute_name := sc_a_name | (sc_a_req_attribute string)
297 attribute_value := (string)
300 <p>もっとも重要なヘッダは <code>content-length</code> だということに
301 注意してください。コンテナは次のパケットを探すかどうかを、
303 <section><title>Forward Request 要素の詳細な説明
305 <section><title>Request prefix</title>
306 <p>リクエストについては全て、この値は 2 になります。他の Prefix コードの詳細は
309 <section><title>Method</title>
310 <p>HTTP メソッドは 1 バイトにエンコードされます :</p>
312 <tr><td>Command Name</td><td>Code</td></tr>
313 <tr><td>OPTIONS</td><td>1</td></tr>
314 <tr><td>GET</td><td>2</td></tr>
315 <tr><td>HEAD</td><td>3</td></tr>
316 <tr><td>POST</td><td>4</td></tr>
317 <tr><td>PUT</td><td>5</td></tr>
318 <tr><td>DELETE</td><td>6</td></tr>
319 <tr><td>TRACE</td><td>7</td></tr>
320 <tr><td>PROPFIND</td><td>8</td></tr>
321 <tr><td>PROPPATCH</td><td>9</td></tr>
322 <tr><td>MKCOL</td><td>10</td></tr>
323 <tr><td>COPY</td><td>11</td></tr>
324 <tr><td>MOVE</td><td>12</td></tr>
325 <tr><td>LOCK</td><td>13</td></tr>
326 <tr><td>UNLOCK</td><td>14</td></tr>
327 <tr><td>ACL</td><td>15</td></tr>
328 <tr><td>REPORT</td><td>16</td></tr>
329 <tr><td>VERSION-CONTROL</td><td>17</td></tr>
330 <tr><td>CHECKIN</td><td>18</td></tr>
331 <tr><td>CHECKOUT</td><td>19</td></tr>
332 <tr><td>UNCHECKOUT</td><td>20</td></tr>
333 <tr><td>SEARCH</td><td>21</td></tr>
334 <tr><td>MKWORKSPACE</td><td>22</td></tr>
335 <tr><td>UPDATE</td><td>23</td></tr>
336 <tr><td>LABEL</td><td>24</td></tr>
337 <tr><td>MERGE</td><td>25</td></tr>
338 <tr><td>BASELINE_CONTROL</td><td>26</td></tr>
339 <tr><td>MKACTIVITY</td><td>27</td></tr>
341 <p>今後の ajp13 バージョンでは、この一覧にない、今後追加されるメソッドを
344 <section><title>protocol, req_uri, remote_addr, remote_host, server_name,
345 server_port, is_ssl</title>
346 <p>これらはまさに文字通りのものです。どれも必要で、リクエストの毎回につき
349 <section><title>Headers</title>
350 <p><code>request_headers</code> の構造は次のようなものです :
351 まずヘッダの数 <code>num_headers</code> がエンコードされます。
352 次にヘッダ名 <code>req_header_name</code> / 値 <code>req_header_value</code>
353 の組が続きます。効率のため、一般的なヘッダは整数でエンコードして転送します。
354 ヘッダ名が基本ヘッダの一覧に無い場合は、通常通り (文字列として、長さ
355 プレフィックス付きで) 転送されます。一般的なヘッダ
356 <code>sc_req_header_name</code> の一覧とそのコードは次の通りです
357 (どれも大文字小文字を区別します) :</p>
359 <tr><td>名前</td><td>コードの値</td><td>コード名</td></tr>
360 <tr><td>accept</td><td>0xA001</td><td>SC_REQ_ACCEPT</td></tr>
361 <tr><td>accept-charset</td><td>0xA002</td><td>SC_REQ_ACCEPT_CHARSET
363 <tr><td>accept-encoding</td><td>0xA003</td><td>SC_REQ_ACCEPT_ENCODING
365 <tr><td>accept-language</td><td>0xA004</td><td>SC_REQ_ACCEPT_LANGUAGE
367 <tr><td>authorization</td><td>0xA005</td><td>SC_REQ_AUTHORIZATION</td>
369 <tr><td>connection</td><td>0xA006</td><td>SC_REQ_CONNECTION</td></tr>
370 <tr><td>content-type</td><td>0xA007</td><td>SC_REQ_CONTENT_TYPE</td>
372 <tr><td>content-length</td><td>0xA008</td><td>SC_REQ_CONTENT_LENGTH</td>
374 <tr><td>cookie</td><td>0xA009</td><td>SC_REQ_COOKIE</td></tr>
375 <tr><td>cookie2</td><td>0xA00A</td><td>SC_REQ_COOKIE2</td></tr>
376 <tr><td>host</td><td>0xA00B</td><td>SC_REQ_HOST</td></tr>
377 <tr><td>pragma</td><td>0xA00C</td><td>SC_REQ_PRAGMA</td></tr>
378 <tr><td>referer</td><td>0xA00D</td><td>SC_REQ_REFERER</td></tr>
379 <tr><td>user-agent</td><td>0xA00E</td><td>SC_REQ_USER_AGENT</td></tr>
381 <p>これを読み込む Java のコードでは、最初の 2 バイト整数を取り込み、
382 目印になるバイト <code>'0xA0'</code> であれば、ヘッダ名の配列の
383 インデックスを使います。先頭バイトが <code>0xA0</code> でない場合は、
384 先頭 2 バイトは文字列長を表す整数であると解釈し、読み込みはじめます。</p>
385 <p>ヘッダ名の長さは <code>0x9999 (==0xA000 -1)</code> 以上にならないという
386 仮定の下に動いていて、少しあいまいですが合理的な挙動になっています。</p>
387 <note><title>注:</title>
388 <code>content-length</code> ヘッダはとても重要です。
389 存在していて非ゼロであれば、リクエストにはボディがある (例えば POST
390 リクエスト) と推測し、そのボディを取り込むために
391 直後のパケットを入力ストリームから読み込みはじめます。
394 <section><title>属性</title>
395 <p><code>?</code> プレフィックスで始まる属性 (例 <code>?context</code>)
396 は。省略可能です。それぞれ属性の型を示す 1 バイトのコードと、
398 これらは順不同で送ることができます (C のコードは常に下の一覧順に
400 オプションの属性のリストの最後には、特別な終了コードが送られます。
403 <tr><td>Information</td><td>Code Value</td><td>Type Of Value</td><td>Note</td></tr>
404 <tr><td>?context</td><td>0x01</td><td>-</td><td>未実装
406 <tr><td>?servlet_path</td><td>0x02</td><td>-</td><td>未実装
408 <tr><td>?remote_user</td><td>0x03</td><td>String</td><td></td></tr>
409 <tr><td>?auth_type</td><td>0x04</td><td>String</td><td></td></tr>
410 <tr><td>?query_string</td><td>0x05</td><td>String</td><td></td></tr>
411 <tr><td>?jvm_route</td><td>0x06</td><td>String</td><td></td></tr>
412 <tr><td>?ssl_cert</td><td>0x07</td><td>String</td><td></td></tr>
413 <tr><td>?ssl_cipher</td><td>0x08</td><td>String</td><td></td></tr>
414 <tr><td>?ssl_session</td><td>0x09</td><td>String</td><td></td></tr>
415 <tr><td>?req_attribute</td><td>0x0A</td><td>String</td><td>Name (the name of the
416 attribute follows)</td></tr>
417 <tr><td>?ssl_key_size</td><td>0x0B</td><td>Integer</td><td></td></tr>
418 <tr><td>are_done</td><td>0xFF</td><td>-</td><td>request_terminator</td></tr>
420 <p><code>context</code> と <code>servlet_path</code> は現在の C の
421 コードではセットされていません。また、ほとんどの Java のコードでも、
422 このフィールドで何が送られても無視されます (これらのコードの後に文字列が
424 これがバグなのか、単に未実装なのか、歴史的経緯で残っているコードなのか
425 分かりませんが、コネクションの両側ともで見当たりません。</p>
426 <p><code>remote_user</code> と <code>auth_type</code> はおそらく
427 HTTP レベルの認証を参照していて、リモートユーザのユーザ名と認証に使用した
428 タイプ (例 Basic, Digest) についてやり取りします。</p>
429 <p><code>query_string</code>, <code>ssl_cert</code>,
430 <code>ssl_cipher</code>, <code>ssl_session</code>
431 は HTTP と HTTPS の対応する部分を参照します。</p>
432 <p><code>jvm_route</code> はスティッキーセッションのサポート――
433 ロードバランスしている複数のサーバ中の特定の Tomcat インスタンスと、
434 ユーザのセッションとを紐付ける機能――に使われます。</p>
435 <p>この基本属性一覧に無いものについては、<code>req_attribute</code>
436 コード <code>0x0A</code> 経由で属性を何個でも送ることができます。
437 属性の名前と値の文字列の組を、それぞれこのコードの直後に送ります。
438 環境変数はこの方法で伝えられます。</p>
439 <p>最後に属性が全て送信された後に、属性の終端を示す <code>0xFF</code>
440 が送出されます。この信号は属性の一覧の終わりを示すと同時に、リクエスト
445 <section id="resppacketstruct"><title>レスポンスパケット構造</title>
446 <p>コンテナがサーバに送り返すことのできるメッセージ:</p>
448 AJP13_SEND_BODY_CHUNK :=
450 chunk_length (integer)
452 chunk_terminator (byte) Ox00
454 AJP13_SEND_HEADERS :=
456 http_status_code (integer)
457 http_status_msg (string)
458 num_headers (integer)
459 response_headers *(res_header_name header_value)
462 sc_res_header_name | (string) [see below for how this is parsed]
464 sc_res_header_name := 0xA0 (byte)
466 header_value := (string)
468 AJP13_END_RESPONSE :=
473 AJP13_GET_BODY_CHUNK :=
475 requested_length (integer)
477 <section><title>詳細 :</title></section>
478 <section><title>Send Body Chunk</title>
479 <p>チャンクは基本的にはバイナリデータで、ブラウザに直接送られます。</p>
481 <section><title>Send Headers</title>
482 <p>ステータスコードとメッセージが通常の HTTP の通信にはあります (例
483 <code>200</code> と <code>OK</code>)。レスポンスヘッダ名は、
484 リクエストヘッダ名と同様の方法でエンコードされます。
485 コードと文字列の判別方法の詳細に関しては、上記の header_encoding
489 <tr><td>名前</td><td>コードの値</td></tr>
490 <tr><td>Content-Type</td><td>0xA001</td></tr>
491 <tr><td>Content-Language</td><td>0xA002</td></tr>
492 <tr><td>Content-Length</td><td>0xA003</td></tr>
493 <tr><td>Date</td><td>0xA004</td></tr>
494 <tr><td>Last-Modified</td><td>0xA005</td></tr>
495 <tr><td>Location</td><td>0xA006</td></tr>
496 <tr><td>Set-Cookie</td><td>0xA007</td></tr>
497 <tr><td>Set-Cookie2</td><td>0xA008</td></tr>
498 <tr><td>Servlet-Engine</td><td>0xA009</td></tr>
499 <tr><td>Status</td><td>0xA00A</td></tr>
500 <tr><td>WWW-Authenticate</td><td>0xA00B</td></tr>
502 <p>コードかヘッダ文字列の直後には、ヘッダの値がエンコードされます。</p>
504 <section><title>End Response</title>
505 <p>リクエスト処理サイクルの終了を知らせます。<code>reuse</code> フラグが真
506 <code>(==1)</code> の場合、現在使用している TCP コネクションは次の新しい
507 リクエストに使えるようになります。<code>reuse</code> が偽 (C のコードでは
508 1 以外の全て) の場合は、コネクションを閉じることになります。</p>
510 <section><title>Get Body Chunk</title>
511 <p>(ボディのサイズが大きすぎて最初のパケットに収まらない場合や、
512 リクエストがチャンク転送された場合などには、) コンテナはリクエストからの
513 データ読み込み要求をします。サーバ側はそれに対して、最小
514 <code>request_length</code> 最大 <code>(8186 (8 Kbytes - 6))</code>
515 の範囲で、未転送で残っているリクエストボディの大きさのデータを
517 ボディにそれ以上データが残っていない場合 (つまりサーブレットが
518 ボディの最後を超えて読み込もうとした場合) 、サーバは
519 ペイロード長 0 の<em>空パケット</em><code>(0x12,0x34,0x00,0x00)</code>