Apache module mod_log_config

### Apache HTTP Server Version 1.3

# mod_log_config モジュール

このモジュールはサーバへのリクエストを Common Log Format やユーザに指定された書式を用いて ログ収集する機能を提供します。

ステータス: Base
ソースファイル: mod_log_config.c
モジュール識別子: config_log_module
互換性: Apache 1.2 より前は extension モジュールでした。

## 概要

このモジュールはクライアントのリクエストを柔軟にログ収集する機能を 提供します。ログはカスタマイズ可能な書式で書かれ、ファイルに直接 書いたり、外部プログラムに渡したりすることができます。個々のリクエストを 特徴に応じてログに書いたり書かなかったりできるように、条件による ログ収集も提供されています。

このモジュールは三つのディレクティブ提供します: ログファイルを作成するための `TransferLog`, 新しい書式を 定義する `LogFormat`, ログファイルと 書式を一度に定義する `CustomLog` です。 各リクエストが複数回ログ収集されるようにするために `TransferLog` ディレクティブと `CustomLog` ディレクティブは複数回使用することができます。

参照: Apache ログファイル。

## ディレクティブ

- CookieLog
- CustomLog
- LogFormat
- TransferLog

## カスタムログ書式

`LogFormat` ディレクティブと `CustomLog` ディレクティブの書式を指定する引数は文字列です。この文字列を使ってそれぞれの リクエストがログファイルにログ収集されます。その文字列には ログファイルにそのまま 書かれる文字列や、それぞれ改行とタブを現す C 言語 形式の制御文字 "\n" と "\t" とを含めることができます。そのまま出力させたい引用符とバックスラッシュは バックスラッシュでエスケープする必要があります。

リクエストの特徴そのものは "`%`" ディレクティブを書式の文字列に書くことで ログ収集されます。"%" ディレクティブはログエントリ中では以下のような 値で置換されます:

    %...a:          リモート IP アドレス
    %...A:          ローカル IP アドレス
    %...B:          HTTP ヘッダ以外の送られたバイト数
    %...b:          HTTP ヘッダ以外の送られたバイト数。CLF 書式。
                    すなわち、1 バイトも送られなかったときは 0 ではなく、'-' になる
    %...c:          応答が終了したときの接続ステータス。
                    'X' = 応答が終了する前に接続が異常終了
                    '+' = 応答が送られた後に接続を持続することが可能
                    '-' = 応答が送られた後に接続は切られる
    %...{FOOBAR}e:  環境変数 FOOBAR の内容
    %...f:          ファイル名
    %...h:          リモートホスト
    %...H           リクエストプロトコル
    %...{Foobar}i:  サーバに送られたリクエストの Foobar: ヘッダの内容
    %...l:          (もしあれば、identd からの) リモートログ名
    %...m           リクエストメソッド
    %...{Foobar}n:  他のモジュールからのメモ "Foobar" の内容
    %...{Foobar}o:  応答の Foobar: ヘッダの内容
    %...p:          リクエストを扱っているサーバの正式なポート
    %...P:          リクエストを扱った子プロセスのプロセス ID
    %...q           問い合せ文字列 (存在する場合は前に ? が追加される。そうでない
                    場合は空文字列)
    %...r:          リクエストの最初の行
    %...s:          ステータス。内部でリダイレクトされたリクエストは、元々の
                    リクエストのステータス --- 最後のステータスは %...>s
    %...t:          時刻。CLF の時刻の書式 (標準の英語の書式)
    %...{format}t:  format で与えられた書式による時刻。format は strftime (3) の
                    書式である必要がある。(地域化されている可能性がある)
    %...T:          リクエストを扱うのにかかった時間、秒単位
    %...u:          リモートユーザ (auth によるもの。ステータス (%s) が 401 のときは
                    意味がない可能性がある)
    %...U:          リクエストされた URL パスで、クエリ文字列は含まない
    %...v:          リクエストを扱っているサーバの正式な ServerName
    %...V:          UseCanonicalName の設定によるサーバ名

"..." は何もないか (例えば、`"%h %u %r %s %b"` のように)、 その項目を含めるかどうかの条件 (もし条件に合わなかったときは その項目は "-" になります) にすることができます。条件の形式は HTTP ステータスコードのリストで、前に "!" を付けることもできます。 ですから、"%400,501{User-agent}i" は 400 エラーと 501 エラー (Bad Request と Not Implemented) のときのみ User-agent: をログ収集します。 "%!200,304,302{Referer}i" は普通のステータスを返さなかった すべてのリクエストで Referer: をログ収集します。

1.3.25 より前のバージョンでは、`%...r`, `%...i`, `%...o` の文字列は エスケープされていなかったことに 注意してください。これは主に Common Log Format からの要求によるものです。 これは、クライアントがログに制御文字を挿入することができるということで、 生のログファイルを扱うときには非常に注意が必要でした。

セキュリティ上の理由により 1.3.25 より印字不可能な文字と 他の特別な文字は、ほとんど `\xhh` という 文字列でエスケープされるようになりました。ここで、hh は そのままのバイトの値の 16 進での値です。この規則の例外には、 バックスラッシュを使ってエスケープされる `"` と `\` と、 C 形式の表記法が使われる空白文字 (`\n`, `\t` など) が あります。

よく使われるフォーマット文字列は:

Common Log Format (CLF)
  `"%h %l %u %t \"%r\" %>s %b"`
バーチャルホスト付き Common Log Format
  `"%v %h %l %u %t \"%r\" %>s %b"`
NCSA extended/combined ログ書式
  `"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""`
Referer ログ書式
  `"%{Referer}i -> %U"`
Agent (ブラウザ) ログ書式
  `"%{User-agent}i"`

`%v` と `%p` にはそれぞれ、 リクエストを扱っているサーバの正規化された ServerName と Port が使われるということに注意してください。 これは UseCanonicalName の 設定に関わらず、常にそうなります。そうしないとどの ホストが実際にリクエストを扱ったのかを知るために、 ログ解析プログラムがバーチャルホストのマッチングをとるアルゴリズム全体を 再実装しなければならなくなるからです。

## セキュリティに関して

ログファイルが保存されているディレクトリがサーバを起動した以外のユーザで 書き込み可能なときにセキュリティの問題が発生する理由の詳細はセキュリティのこつ を参照してください。

## 互換性に関して

- このモジュールは以前の Apache のリリースで配布されていた mod_log_config を基にして、複数のログを扱えるように更新されたものです。 設定可能なログの書式を使うために Apache をビルド し直す必要はなくなりました。
- このモジュールは mod_usertrack により 作られたユーザ追跡用の情報のログ収集を行なうために使われていた `CookieLog` ディレクティブも実装しています。`CookieLog` ディレクティブの使用は非推奨で、 ユーザ追跡用の情報もログ収集するように設定した `CustomLog` を使うことが推奨されています。
- Apache 1.3.5 の時点で、このモジュールは 環境変数 の設定に基づいて条件付きロギングができるようになりました。すなわち、 リクエストがログ収集されるかどうかを任意の環境変数が定義されているか どうかにより変更することができるということです。これは ログファイルごとに設定可能です。
- Apache 1.3.5 から、mod_log_config モジュールは mod_log_referer の `RefererIgnore` 機能も含むようになりました。 `RefererIgnore` の効果は `SetEnvIf` ディレクティブと `CustomLog` の条件付きの設定により達成できます。

## CookieLog ディレクティブ

構文: CookieLog filename
コンテキスト: サーバ設定ファイル、バーチャルホスト
モジュール: mod_cookies
互換性: Apache 1.2 以降でのみ使用可能

CookieLog ディレクティブはクッキーのロギングのためのファイル名を 設定します。filename は ServerRoot からの相対パスです。このディレクティブは mod_cookies との互換性のためだけに 存在し、使用は推奨されていません。

## CustomLog ディレクティブ

構文: CustomLog file|pipe format|nickname [env=[!]environment-variable]
コンテキスト: サーバ設定ファイル、バーチャルホスト
ステータス: Base
互換性: Nickname は Apache 1.3 以降でのみ使用可能。 条件付きロギングは 1.3.5 以降で使用可能。
モジュール: mod_log_config

`CustomLog` ディレクティブはサーバへのリクエストを ログ収集するために使われます。ログの書式が指定され、 環境変数を使ってロギングが条件に応じて行なわれるようにすることもできます。

ログが書かれる場所を指定する最初の引数は以下の二つの形式の値を とることができます:

file
  ServerRoot からの相対パスで表されるファイル名。
pipe
  パイプ文字 "`|`" と、その後に標準入力からログの 情報を受けとるプログラムへのパスが続いたもの。 セキュリティ: もしプログラムが使用された場合、 httpd が起動されたユーザとして実行されます。これはサーバが root によって起動された場合は root になります。プログラムが 安全であるように留意してください。

二つめの引数はログファイルに何が書かれるかを指定します。 前にある LogFormat ディレクティブにより 定義された ニックネーム か、ログの書式 のところで説明されている、明示的なフォーマット文字列の どちらかを指定することができます。

例えば、以下の二つのディレクティブ群は全く同じ効果をもたらします:

         # CustomLog with format nickname
         LogFormat "%h %l %u %t \"%r\" %>s %b" common
         CustomLog logs/access_log common

         # CustomLog with explicit format string
         CustomLog logs/access_log "%h %l %u %t \"%r\" %>s %b"

三つ目の引数は省略可能で、サーバの環境にある変数があるかないかに 応じてリクエストをログ収集するかどうかを制御するために使うことができます。 指定された環境変数がリクエストに対して 設定されていた場合 ('`env=!name`' 文が使われたときは 設定されていない場合)、リクエストがログ収集されます。

環境変数は mod_setenvif モジュールと mod_rewrite モジュールの両方もしくは 片方を用いてリクエストごとに設定することができます。 例えば、サーバにあるすべての GIF 画像へのリクエストを別のログファイル には記録したいけれど、メインログには記録したくない、というときは 以下のものを使うことができます:

        SetEnvIf Request_URI \.gif$ gif-image
        CustomLog gif-requests.log common env=gif-image
        CustomLog nongif-requests.log common env=!gif-image

## LogFormat ディレクティブ

構文: LogFormat format|nickname [nickname]
デフォルト: `LogFormat "%h %l %u %t \"%r\" %>s %b"`
コンテキスト: サーバ設定ファイル、バーチャルホスト
ステータス: Base
互換性: ニックネームは Apache 1.3 以降でのみ使用可能
モジュール: mod_log_config

このディレクティブはアクセスログファイルの書式を指定します。

`LogFormat` ディレクティブは二つの形式のどちらかを とることができます。最初の形式では一つの引数のみが指定され、 続く TransferLog で指定されたログで使われるログの書式を設定します。この単独の引数では 上のカスタムログ書式で説明されているように フォーマットを明示的に指定することができます。 もしくは、下で説明されているように前に `LogFormat` ディレクティブで定義されたログの書式をニックネームを使って 参照することもできます。

`LogFormat` ディレクティブの二つめの形式は フォーマットにニックネームを与えます。 フォーマット文字列全体を再び書くかわりに、 このニックネームを続きの `LogFormat` ディレクティブや CustomLog ディレクティブで使うことができます。 ニックネームを定義する `LogFormat` ディレクティブは 他には何もしません -- すなわち、ニックネームを定義 するだけで、実際に書式を適用してデフォルトにするということは行ないません。 ですから、これは続く TransferLog ディレクティブには影響を与えません。

例:

`LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost_common`

## TransferLogディレクティブ

構文: TransferLog file|pipe
デフォルト: none
コンテキスト: サーバ設定ファイル、バーチャルホスト
ステータス: Base
モジュール: mod_log_config

このディレクティブは、ログ書式を直接指定できないことと、 条件付きロギングが無いことを除くと、CustomLog と全く同じ引数と効果があります。 直接ログ書式を指定する代わりに、ログの書式はそこまでで一番最後に指定された ニックネームを定義しない LogFormat ディレクティブ で定義されたものを使います。 もし他の書式が全く指定されていないときは Common Log Format が使われます。

例:

       LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\""
       TransferLog logs/access_log

### Apache HTTP Server Version 1.3