apache/docs/manual/mod/mod_log_config.xml.ja

   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: 579425:723557 (outdated) -->
   5
   6 <!--
   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
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  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.
  21 -->
  22
  23 <modulesynopsis metafile="mod_log_config.xml.meta">
  24
  25 <name>mod_log_config</name>
  26 <description>サーバへのリクエストのロギング</description>
  27 <status>Base</status>
  28 <sourcefile>mod_log_config.c</sourcefile>
  29 <identifier>log_config_module</identifier>
  30
  31 <summary>
  32     <p>
  33     このモジュールはクライアントのリクエストを柔軟にログ収集する機能を
  34     提供します。ログはカスタマイズ可能な書式で書かれ、ファイルに直接
  35     書いたり、外部プログラムに渡したりすることができます。個々のリクエストを
  36     特徴に応じてログに書いたり書かなかったりできるように、条件による
  37     ログ収集も提供されています。</p>
  38
  39     <p>このモジュールは三つのディレクティブ提供します:
  40     ログファイルを作成するための <directive module="mod_log_config"
  41     >TransferLog</directive>,
  42     新しい書式を 定義する <directive module="mod_log_config">LogFormat</directive>,
  43     ログファイルと 書式を一度に定義する <directive module="mod_log_config"
  44     >CustomLog</directive> です。
  45     各リクエストが複数回ログ収集されるようにするために
  46     <directive>TransferLog</directive> ディレクティブと
  47     <directive>CustomLog</directive>
  48     ディレクティブは複数回使用することができます。</p>
  49 </summary>
  50 <seealso><a href="../logs.html">Apache ログファイル</a></seealso>
  51
  52 <section id="formats"><title>カスタムログ書式</title>
  53
  54     <p><directive module="mod_log_config">LogFormat</directive> ディレクティブと
  55     <directive module="mod_log_config">CustomLog</directive>
  56     ディレクティブの書式を指定する引数は文字列です。この文字列を使ってそれぞれの
  57     リクエストがログファイルにログ収集されます。その文字列には
  58     ログファイルにそのまま
  59     書かれる文字列や、それぞれ改行とタブを表す C 言語
  60     形式の制御文字 "\n" と "\t"
  61     とを含めることができます。そのまま出力させたい引用符とバックスラッシュは
  62     バックスラッシュでエスケープする必要があります。</p>
  63
  64     <p>リクエストの特徴そのものは "<code>%</code>"
  65     ディレクティブを書式の文字列に書くことで
  66     ログ収集されます。"%"
  67     ディレクティブはログファイル中では以下のような
  68     値で置換されます:</p>
  69
  70     <table border="1" style="zebra">
  71     <columnspec><column width=".2"/><column width=".8"/></columnspec>
  72     <tr><th>フォーマット文字列</th>
  73         <th>説明</th></tr>
  74
  75     <tr><td><code>%%</code></td>
  76         <td>パーセント記号</td></tr>
  77
  78     <tr><td><code>%a</code></td>
  79         <td>リモート IP アドレス</td></tr>
  80
  81     <tr><td><code>%A</code></td>
  82         <td>ローカル IP アドレス</td></tr>
  83
  84     <tr><td><code>%B</code></td>
  85         <td>レスポンスのバイト数。HTTP ヘッダは除く。</td></tr>
  86
  87     <tr><td><code>%b</code></td>
  88         <td>レスポンスのバイト数。HTTP ヘッダは除く。CLF 書式。
  89         <em>すなわち</em>、1 バイトも送られなかったときは 0 ではなく、
  90         '<code>-</code>' になる</td></tr>
  91
  92     <tr><td><code>%{<var>Foobar</var>}C</code></td>
  93         <td>サーバに送られたリクエスト中のクッキー <var>Foobar</var> の値</td></tr>
  94
  95     <tr><td><code>%D</code></td>
  96         <td>リクエストを処理するのにかかった時間、マイクロ秒単位</td></tr>
  97
  98     <tr><td><code>%{<var>FOOBAR</var>}e</code></td>
  99         <td>環境変数 <var>FOOBAR</var> の内容</td></tr>
 100
 101     <tr><td><code>%f</code></td>
 102         <td>ファイル名</td></tr>
 103
 104     <tr><td><code>%h</code></td>
 105         <td>リモートホスト</td></tr>
 106
 107     <tr><td><code>%H</code></td>
 108         <td>リクエストプロトコル</td></tr>
 109
 110     <tr><td><code>%{<var>Foobar</var>}i</code></td>
 111         <td>サーバに送られたリクエストの <code><var>Foobar</var>:</code>
 112         ヘッダの内容</td></tr>
 113
 114     <tr><td><code>%l</code></td>
 115         <td>(identd からもし提供されていれば) リモートログ名。
 116         これは <module>mod_ident</module> がサーバに存在して、
 117         <directive module="mod_ident">IdentityCheck</directive>
 118         ディレクティブが <code>On</code> に設定されていない限り、
 119         <code>-</code> になります。</td></tr>
 120
 121     <tr><td><code>%m</code></td>
 122         <td>リクエストメソッド</td></tr>
 123
 124     <tr><td><code>%{<var>Foobar</var>}n</code></td>
 125         <td>他のモジュールからのメモ <var>Foobar</var> の内容</td></tr>
 126
 127     <tr><td><code>%{<var>Foobar</var>}o</code></td>
 128         <td>応答の <code><var>Foobar</var>:</code> ヘッダの内容</td></tr>
 129
 130     <tr><td><code>%p</code></td>
 131         <td>リクエストを扱っているサーバの正式なポート</td></tr>
 132
 133     <tr><td><code>%{<var>format</var>}p</code></td>
 134         <td>サーバがリクエストを処理しているポートの公式
 135         <transnote>canonical</transnote> のポート番号か、
 136         サーバの実際のポート番号か、クライアント側の実際のポート番号かです。
 137         format に使える文字列は <code>canonical</code>, <code>local</code>,
 138         <code>remote</code> になります。
 139         </td></tr>
 140
 141     <tr><td><code>%P</code></td>
 142         <td>リクエストを扱った子プロセスのプロセス ID</td></tr>
 143
 144     <tr><td><code>%{<var>format</var>}P</code></td>
 145         <td>リクエストを扱ったワーカーのプロセス ID かスレッド ID。
 146         <var>format</var> として有効な値は <code>pid</code>, <code>tid</code>,
 147         <code>hextid</code> です。<code>hextid</code> を使うには
 148         APR 1.2.0 以降が必要です。
 149         </td></tr>
 150
 151     <tr><td><code>%q</code></td>
 152         <td>問い合せ文字列 (存在する場合は前に <code>?</code> が追加される。
 153         そうでない場合は空文字列)</td></tr>
 154
 155     <tr><td><code>%r</code></td>
 156         <td>リクエストの最初の行</td></tr>
 157
 158     <tr><td><code>%s</code></td>
 159         <td>ステータス。内部でリダイレクトされたリクエストは、元々の
 160          リクエストのステータス --- 最後のステータスは <code>%&gt;s</code>
 161     </td></tr>
 162
 163     <tr><td><code>%t</code></td>
 164         <td>リクエストを受付けた時刻。
 165         CLF の時刻の書式 (標準の英語の書式)</td></tr>
 166
 167     <tr><td><code>%{<var>format</var>}t</code></td>
 168         <td><var>format</var> で与えられた書式による時刻。format は
 169          <code>strftime (3)</code> の
 170          書式である必要がある。(地域化されている可能性がある)</td></tr>
 171
 172     <tr><td><code>%T</code></td>
 173         <td>リクエストを扱うのにかかった時間、秒単位</td></tr>
 174
 175     <tr><td><code>%u</code></td>
 176         <td>リモートユーザ (認証によるもの。ステータス (<code>%s</code>) が
 177         401 のときは意味がないものである可能性がある)
 178     </td></tr>
 179
 180     <tr><td><code>%U</code></td>
 181         <td>リクエストされた URL パス。クエリ文字列は含まない</td></tr>
 182
 183     <tr><td><code>%v</code></td>
 184         <td>リクエストを扱っているサーバの正式な <directive
 185         module="core">ServerName</directive></td></tr>
 186
 187     <tr><td><code>%V</code></td>
 188         <td><directive module="core"
 189         >UseCanonicalName</directive> の設定によるサーバ名</td></tr>
 190
 191     <tr><td><code>%X</code></td>
 192         <td>応答が完了したときの接続ステータス:
 193
 194         <table>
 195         <columnspec><column width=".2"/><column width=".6"/></columnspec>
 196         <tr><td><code>X</code> =</td>
 197             <td>応答が完了する前に接続が異常終了</td></tr>
 198         <tr><td><code>+</code> =</td>
 199             <td>応答が送られた後に接続を持続することが可能</td></tr>
 200         <tr><td><code>-</code> = </td>
 201             <td>応答が送られた後に接続が切られる</td></tr>
 202         </table>
 203
 204         <p>(このディレクティブは Apache
 205         1.3 の後期のバージョンでは <code>%c</code> に割り当てられて
 206         いましたが、これは歴史的に ssl が使用している
 207         <code>%{<var>var</var>}c</code>
 208         構文と衝突していました。)</p></td></tr>
 209
 210     <tr><td><code>%I</code></td>
 211         <td>リクエストとヘッダを含む、受け取ったバイト数。
 212         0 にはならない。
 213         これを使用するためには <module>mod_logio</module> が必要</td></tr>
 214
 215     <tr><td><code>%O</code></td>
 216         <td>ヘッダを含む、送信したバイト数。0 にはならない。
 217         これを使用するためには <module>mod_logio</module> が必要</td></tr>
 218     </table>
 219
 220     <section id="modifiers"><title>修飾子</title>
 221
 222       <p>特定の要素は "%" の直後に HTTP ステータスコードをカンマ区切りで
 223       指定することで、表示を制限することができます。例えば
 224       <code>"%400,501{User-agent}i"</code> では、
 225       400 と 500 番エラーでのみ <code>User-agent</code> をログします。
 226       他のステータスコードでは <code>"-"</code> という文字列が
 227       ログされます。ステータスコードのリストは "<code>!</code>"
 228       で否定を指定することができます :
 229       <code>"%!200,304,302{Referer}i"</code> は、指定された
 230       3 つのコードの<em>どれにも該当しない</em>リクエスト全てで
 231       <code>Referer</code> をログします。</p>
 232
 233       <p>修飾子 "&lt;" と "&gt;" は内部リダイレクトされたリクエストのログに
 234       元のリクエストか最終的なリクエストのどちらを使用するかを
 235       指定するために使います。デフォルトでは、<code>%</code> ディレクティブの
 236       <code>%s, %U, %T, %D, %r</code> は元のリクエストを、他は最終的なリクエストを
 237       使用します。例えば、リクエストの最終ステータスを記録するには
 238       <code>%&gt;s</code> を、内部的に認証されていないリソースへリダイレクトされた
 239       リクエストで元のリクエストで認証されたユーザを記録するためには
 240       <code>%&lt;u</code> を使うことができます。</p>
 241
 242     </section>
 243
 244     <section id="format-notes"><title>その他注意点</title>
 245
 246       <p>セキュリティ上の理由により 2.0.46 より、
 247       <code>%r</code>, <code>%i</code>, <code>%o</code> に入っている、
 248       印字不可能な文字と他の特別な文字は、<code>\x<var>hh</var></code>
 249       という形式の文字列でエスケープされるようになりました。<var>hh</var> は
 250       そのままのバイトの値の 16 進での値です。この規則の例外には、
 251       バックスラッシュを使ってエスケープされる <code>"</code> と <code>\</code> と、
 252       C 形式の表記法が使われる空白文字 (<code>\n</code>, <code>\t</code> など)
 253       があります。2.0.46 以前のバージョンではエスケープ処理は行われませんので、
 254       生ログファイルを扱う際に注意が必要です。</p>
 255
 256       <p>httpd 2.0 では 1.3 とは異なり、<code>%b</code> と <code>%B</code>
 257       フォーマット文字列はクライアントに送信されたバイト数そのものではなく、
 258       HTTP レスポンスのバイト数です (これらは異なるもので、たとえば、
 259       コネクションが途中で破棄された場合や、SSL 使用時に一致しません) 。
 260       <module>mod_logio</module> で提供されている <code>%O</code>
 261       フォーマット文字列で、ネットワーク経由で実際に転送されたバイト数を
 262       記録できます。</p>
 263
 264     </section>
 265
 266     <section id="examples"><title>例</title>
 267
 268       <p>よく使われるフォーマット文字列は:</p>
 269
 270       <dl>
 271         <dt>Common Log Format (CLF)</dt>
 272         <dd><code>"%h %l %u %t \"%r\" %&gt;s %b"</code></dd>
 273
 274         <dt>バーチャルホスト付き Common Log Format</dt>
 275         <dd><code>"%v %h %l %u %t \"%r\" %&gt;s %b"</code></dd>
 276
 277         <dt>NCSA extended/combined ログ書式</dt>
 278         <dd><code>"%h %l %u %t \"%r\" %&gt;s %b \"%{Referer}i\"
 279         \"%{User-agent}i\""</code></dd>
 280
 281         <dt>Referer ログ書式</dt>
 282         <dd><code>"%{Referer}i -&gt; %U"</code></dd>
 283
 284         <dt>Agent (ブラウザ) ログ書式</dt>
 285         <dd><code>"%{User-agent}i"</code></dd>
 286       </dl>
 287     </section>
 288 </section>
 289
 290 <section id="security"><title>セキュリティに関して</title>
 291     <p>ログファイルが保存されているディレクトリがサーバを起動した以外のユーザで
 292     書き込み可能なときにセキュリティの問題が発生する理由の詳細は<a
 293     href="../misc/security_tips.html#serverroot">セキュリティのこつ</a>
 294     を参照してください。</p>
 295 </section>
 296
 297 <directivesynopsis>
 298 <name>BufferedLogs</name>
 299 <description>ディスクに書き出す前にメモリにログエントリをバッファする</description>
 300 <syntax>BufferedLogs On|Off</syntax>
 301 <default>BufferedLogs Off</default>
 302 <contextlist><context>server config</context></contextlist>
 303 <status>Experimental</status>
 304 <compatibility>2.0.41 以降</compatibility>
 305
 306 <usage>
 307     <p><directive>BufferedLogs</directive> ディレクティブを使うと
 308     <module>mod_log_config</module> の挙動が変化して、
 309     複数のログを書き出す際に、それぞれのリクエスト処理後毎に
 310     書き出すのではなく、いったんメモリに蓄えてから、
 311     まとめてディスクに書き出すようになります。
 312     この結果ディスクアクセスがより効率的になり、
 313     高いパフォーマンスの得られるシステムもあるでしょう。
 314     このディレクティブはサーバ全体で一度だけ設定できます;
 315     バーチャルホストごとに設定することはできません。</p>
 316
 317     <note>このディレクティブは実験的なものですので、
 318     使用する際は注意してください。</note>
 319 </usage>
 320 </directivesynopsis>
 321
 322 <directivesynopsis>
 323 <name>CookieLog</name>
 324 <description>クッキングのロギングのためのファイル名を設定する</description>
 325 <syntax>CookieLog <var>filename</var></syntax>
 326 <contextlist><context>server config</context><context>virtual host</context>
 327 </contextlist>
 328 <compatibility>このディレクティブは非推奨</compatibility>
 329
 330 <usage>
 331     <p><directive>CookieLog</directive>
 332     ディレクティブはクッキーのロギングのためのファイル名を
 333     設定します。filename は <directive
 334     module="core">ServerRoot</directive>
 335     からの相対パスです。このディレクティブは <code
 336     >mod_cookies</code> との互換性のためだけに
 337     存在し、使用は推奨されていません。</p>
 338 </usage>
 339 </directivesynopsis>
 340
 341 <directivesynopsis>
 342 <name>CustomLog</name>
 343 <description>ログファイルの名前と書式を設定する</description>
 344 <syntax>CustomLog  <var>file</var>|<var>pipe</var>
 345 <var>format</var>|<var>nickname</var>
 346 [env=[!]<var>environment-variable</var>]</syntax>
 347 <contextlist><context>server config</context><context>virtual host</context>
 348 </contextlist>
 349
 350 <usage>
 351     <p><directive>CustomLog</directive> ディレクティブはサーバへのリクエストを
 352     ログ収集するために使われます。ログの書式が指定され、
 353     環境変数を使ってロギングが条件に応じて行なわれるようにすることもできます。</p>
 354
 355     <p>ログが書かれる場所を指定する最初の引数は以下の二つの形式の値を
 356     とることができます:</p>
 357
 358     <dl>
 359       <dt><var>file</var></dt>
 360       <dd><directive module="core">ServerRoot</directive>
 361       からの相対パスで表されるファイル名。</dd>
 362
 363       <dt><var>pipe</var></dt>
 364       <dd>パイプ文字 "<code>|</code>" と、その後に標準入力からログの
 365       情報を受けとるプログラムへのパスが続いたもの。
 366
 367       <note type="warning"><title>セキュリティ</title>
 368       <p>もしプログラムが使用された場合、
 369       <program>httpd</program> が起動されたユーザとして実行されます。これはサーバが
 370       root によって起動された場合は root になります。プログラムが
 371       安全であるように留意してください。</p>
 372       </note>
 373       <note type="warning"><title>注</title>
 374         <p>Unix でないプラットフォームでファイルのパスを入力しているときは、
 375         使用しているプラットフォームがバックスラッシュの使用を許可していた
 376         として、通常のスラッシュだけを使うように気をつけてください。
 377         一般的に、設定ファイル中では常に普通のスラッシュのみを使うようにする
 378         方が良いです。</p>
 379       </note></dd>
 380     </dl>
 381
 382     <p>二つめの引数はログファイルに何が書かれるかを指定します。
 383     前にある <directive
 384     module="mod_log_config">LogFormat</directive> ディレクティブにより
 385     定義された <var>nickname</var> か、<a href="#formats">ログの書式</a>
 386     のところで説明されている、明示的な <var>format</var> 文字列の
 387     どちらかを指定することができます。</p>
 388
 389     <p>例えば、以下の二つのディレクティブ群は全く同じ効果をもたらします:</p>
 390
 391     <example>
 392       # CustomLog with format nickname<br />
 393       LogFormat "%h %l %u %t \"%r\" %&gt;s %b" common<br />
 394       CustomLog logs/access_log common<br />
 395       <br />
 396       # CustomLog with explicit format string<br />
 397       CustomLog logs/access_log "%h %l %u %t \"%r\" %&gt;s %b"
 398     </example>
 399
 400     <p>三つ目の引数は省略可能で、サーバの環境にある変数があるかないかに
 401     応じてリクエストをログ収集するかどうかを制御するために使うことができます。
 402     指定された<a href="../env.html">環境変数</a>がリクエストに対して
 403     設定されていた場合 ('<code>env=!<var>name</var></code>' 文が使われたときは
 404     設定されていない場合)、リクエストがログ収集されます。</p>
 405
 406     <p>環境変数は <module>mod_setenvif</module> モジュールと
 407     <module>mod_rewrite</module> モジュールの両方もしくは
 408     片方を用いてリクエストごとに設定することができます。
 409     例えば、サーバにあるすべての GIF 画像へのリクエストを別のログファイル
 410     には記録したいけれど、メインログには記録したくない、というときは
 411     以下のものを使うことができます:</p>
 412
 413     <example>
 414       SetEnvIf Request_URI \.gif$ gif-image<br />
 415       CustomLog gif-requests.log common env=gif-image<br />
 416       CustomLog nongif-requests.log common env=!gif-image
 417     </example>
 418
 419     <p>古い RefererIgnore ディレクティブと同じ挙動をさせたい場合は、
 420     次のようにします:</p>
 421
 422     <example>
 423     SetEnvIf Referer example\.com localreferer<br />
 424     CustomLog referer.log referer env=!localreferer
 425     </example>
 426 </usage>
 427 </directivesynopsis>
 428
 429 <directivesynopsis>
 430 <name>LogFormat</name>
 431 <description>ログファイルで使用する書式を設定する</description>
 432 <syntax>LogFormat <var>format</var>|<var>nickname</var>
 433 [<var>nickname</var>]</syntax>
 434 <default>LogFormat "%h %l %u %t \"%r\" %>s %b"</default>
 435 <contextlist><context>server config</context><context>virtual host</context>
 436 </contextlist>
 437
 438 <usage>
 439     <p>このディレクティブはアクセスログファイルの書式を指定します。</p>
 440
 441     <p><directive>LogFormat</directive> ディレクティブは二つの形式のどちらかを
 442     とることができます。最初の形式では一つの引数のみが指定され、
 443     続く <directive>TransferLog</directive>
 444     で指定されたログで使われるログの書式を設定します。この単独の引数では
 445     上の<a href="#formats">カスタムログ書式</a>で説明されているように
 446     <var>format</var> を明示的に指定することができます。
 447     もしくは、下で説明されているように前に <directive>LogFormat</directive>
 448     ディレクティブで定義されたログの書式を <var>nickname</var>を使って
 449     参照することもできます。</p>
 450
 451     <p><directive>LogFormat</directive> ディレクティブの二つめの形式は
 452     <var>format</var> に <var>nickname</var> を与えます。
 453     フォーマット文字列全体を再び書くかわりに、
 454     この <var>nickname</var> を続きの <directive
 455     >LogFormat</directive> ディレクティブや
 456     <directive>CustomLog</directive> ディレクティブで使うことができます。
 457     Nickname を定義する <directive>LogFormat</directive> ディレクティブは
 458     <strong>他には何もしません</strong> -- すなわち、ニックネームを定義
 459     する<em>だけ</em>で、実際に書式を適用してデフォルトにするということは行ないません。
 460     ですから、これは続く <directive module="mod_log_config">TransferLog</directive>
 461     ディレクティブには影響を与えません。
 462     さらに、<directive>LogFormat</directive> ディレクティブは既存の nickname を
 463     使って別の nickname を定義することはできません。Nickname には
 464     パーセント記号 (<code>%</code>) が含まれていてはいけないことにも注意
 465     してください。</p>
 466
 467     <example><title>例</title>
 468       LogFormat "%v %h %l %u %t \"%r\" %&gt;s %b" vhost_common
 469     </example>
 470 </usage>
 471 </directivesynopsis>
 472
 473 <directivesynopsis>
 474 <name>TransferLog</name>
 475 <description>ログファイルの位置を指定</description>
 476 <syntax>TransferLog <var>file</var>|<var>pipe</var></syntax>
 477 <contextlist><context>server config</context><context>virtual host</context>
 478 </contextlist>
 479
 480 <usage>
 481     <p>このディレクティブは、ログ書式を直接指定できないことと、
 482     条件付きロギングが無いことを除くと、<directive module="mod_log_config"
 483     >CustomLog</directive> と全く同じ引数と効果があります。
 484     直接ログ書式を指定する代わりに、ログの書式はそこまでで一番最後に指定された
 485     ニックネームを定義しない
 486     <directive module="mod_log_config">LogFormat</directive> ディレクティブ
 487         で定義されたものを使います。
 488     もし他の書式が全く指定されていないときは Common Log Format
 489     が使われます。</p>
 490
 491     <example><title>例</title>
 492       LogFormat "%h %l %u %t \"%r\" %&gt;s %b \"%{Referer}i\" \"%{User-agent}i\""<br />
 493       TransferLog logs/access_log
 494     </example>
 495 </usage>
 496 </directivesynopsis>
 497
 498 </modulesynopsis>