[APACHE DOCUMENTATION]

Apache HTTP Server Version 1.3

モジュール mod_rewrite

このモジュールは Apache 1.2 以降のmod_rewrite.c ファイルに含まれます。 これは、リクエストされた URL をルールに基づいて書き換えるエンジンの 機能を提供します。 mod_rewrite はデフォルトではコンパイルされません。 mod_rewrite を使用する為にはコンフィグレーションファイルを 次の行のように構築しなければなりません: 
    AddModule  modules/standard/mod_rewrite.o

Summary

このモジュールはルールに基づいた書き換えエンジン（正規表現の文法に基づいて）を用いて、リクエストされた URL をその都度書き換えを行います。

これは、不正確な一致による無制限な追加のルール条件（HTTP のヘッダーを含むたくさんの変数を操作するため）と、先にある URL の代用による外部のデータベース検索（あるいはプレインテキストテーブル、DBM ハッシュファイルや、外部の処理によって）をサポートします。

次の両方を含む、フルの URL（PATH_INFOパートを含む）を操作します。 per-server文(httpd.conf)とper-dir文(.htaccess) とさらに結果のQUERY_STRINGの一部を生成することができます。 書き換えられた結果は、内部のサブプロセスで読み込むことが出来、外部のリクエストをリダイレクト（変換）するか、内部のProxyを通すことも可能です。

このモジュールは 1996 年の 4 月に独自に書かれたもので、1997 年の 7 月には Apache グループのものとなっています。

Ralf S. Engelschall
rse@engelschall.com
www.engelschall.com

命令

コンフィグレーションの命令

RewriteEngine

 Syntax: RewriteEngine {on,off}
Default: RewriteEngine off
Context: server config, virtual host, per-directory config

RewriteEngine 命令はランタイム書き換えエンジンを有効又は無効にします。 off を設定すると、このモジュールはランタイム処理を行いません。環境変数SCRIPT_URxの更新もしません。

全ての RewriteRule 命令を無効にする為に、この命令を使ってください！

デフォルトでは rewrite コンフィギュレーションは受け継がれていません。これは RewriteOptions inherit が可能にならない限り、それぞれのバーチャルホストで RewriteEngine on 命令を持つ必要があることを意味します。

RewriteOptions

Syntax: RewriteOptions Option ...
Default: -None-
Context: server config, virtual host, per-directory config

RewriteOption 命令は、いくつかの特殊オプションである、現在のper-server またはper-directory コンフィグレーションを設定します。 Option文字列は次のようにできます:

RewriteLog

Syntax: RewriteLog Filename
Default: -None-
Context: server config, virtual host

RewriteLog 命令はサーバで書き換えたアクションを格納するファイル名を設定します。 ファイル名がスラッシュ('/') で始まらない時は、Server Rootからの相対パスとなります。 この命令はサーバの設定につき１つだけ行えます。

書き換え操作のログを行わないようにする際は、 Filenameを /dev/nullにする必要がありません。なぜなら書き換えエンジンは 内部的にログを出力していますが、ログファイルを生成しません。 これはサーバをスローダウンさせ、管理者になにも利益がありません！ ロギングを無効にするにはRewriteLog 命令をを削除するかコメントアウト するか、RewriteLogLevel 0を使用してください！

SECURITY: See the Apache Security Tips document for details on why your security could be compromised if the directory where logfiles are stored is writable by anyone other than the user that starts the server.

Example: 

RewriteLog "/usr/local/var/apache/logs/rewrite.log"

RewriteLogLevel

Syntax: RewriteLogLevel Level
Default: RewriteLogLevel 0
Context: server config, virtual host

RewriteLogLevel 命令は書き換えログの冗長性のレベルを設定します。 デフォルトレベルの 0 は何もロギングしません。9 までまたはそれ以上は、 さらに多くのログ情報が書き出されます。

ログ出力を無効にするには、Level を 0 に設定してください。 これは全ての処理のログを無効にします。

注意: 高いLevel を使用すると劇的にApacheサーバは遅くなります！ 書き換えログファイルはデバッグの時に使用し、少なくとも 2 以下のを使ってください！

Example: 

RewriteLogLevel 3

RewriteMap

Syntax: RewriteMap Mapname {txt,dbm,prg}:Filename
Default: not used per default
Context: server config, virtual host

RewriteMap命令はキー検索を通してフィールドを挿入／代用するためにマッピング機能によってルール代理ストリングの中で使える外部のRewriting Mapを定義します。

Mapnameはマップの名前であって、書き換えルールの代理ストリングスのためにマッピング機能を指定するために使われます。

${ Mapname : LookupKey | DefaultValue }
このような命令がある時 マップMapnameは調べられ、キーLookupKeyは検索されます。もしキーが見つかれば、マップ機能命令はSubstValueによって代わりに割り当てられます。もしキーが見つからなければ、それはDefaultValueによって割り当てられます。

Filenameは次のフォーマットの一つを含んでいる有効な Unix ファイルパスです：

  1. Plain Text Format

    これはいずれかのブランク行、コメント行（'#' で始まっている）を含んでいるアスキーファイルであるか、または

    MatchingKey SubstValue
    対ー行ごとに一つ。適当なエディタを使うか、またはmod_rewriteが分配するsupportディレクトリからmapcollect、mapmergeというプログラムを使って、手動でこのようなファイルを作ることができます。

    txt:と一緒にマップの接頭部をFilenameとして示すこと：以下の例のようなストリング： 

    #
#   map.real-to-user -- maps realnames to usernames
#

Ralf.S.Engelschall    rse   # Bastard Operator From Hell
Dr.Fred.Klabuster     fred  # Mr. DAU


    RewriteMap real-to-host txt:/path/to/file/map.real-to-user

  2. DBM Hashfile Format

    NDBM フォーマットファイルが同じ中身を持っていることを示します。Apache のsupportディレクトリにある、なんらかの NDBM ツールやdbmmanageプログラムを使ってそのようなファイルを作ることが出来ます。

    dbm:stringと一緒にマップの接頭部をFilenameとして示す。

  3. Program Format

    これは検索ファイルではなく、UNIX で実行可能なプログラムです。それを使うために言語を選択して使うことができるが、しかし結果は実行可能な UNIX バイナリーでな ければなりません（すなわち、オブジェクト・コードあるいはマジックのクッキーを持つスクリプトが先頭行として'#!/path/to/interpreter'をうまくいくようにします）。

    このプログラムは一度 Apache サーバの起動時に実行されていて、次にそのstdinとstdoutのファイル・ハンドルの上のエンジンを書き換える情報を出します。それぞれのマップ機能検索のために、それはstdinの上にあるニューラインによって終結されたストリングとして、検索するべきキーを受け取るでしょう。それからそれは、stdoutの上のニューラインによって終結されたストリング、またはそれがだめなら``NULL''の４文字のストリングとして、検索された値を返さなければなりません（すなわち与えられたキーに対応する値がない）。1:1 のマップを実行するような（すなわち、キー＝＝値）平凡なプログラムもあり得ます： 

    #!/usr/bin/perl
$| = 1;
while (<STDIN>) {
    # ...here any transformations
    # or lookups should occur...
    print $_;
}

    しかし以下に気を付けて下さい:

    1. ``プログラムはシンプルかつ単純'' (KISS)にしておいて下さい。なぜなら、ルールが立ち上がっている時、もしこのプログラムがもたもたしていると、Apache サーバの接続を切断することになるからです。
    2. 一つの共通のミスは避けて下さい：stdoutの上で決してバッファに入れられた I/O をしないで下さい！これは deadloop を引き起こすことになります！それゆえ、上記の例の``$|=1''は ...

    prg:stringと一緒にそのようなマップ接頭部をFilenameとして示すこと

RewriteMap命令は以前よりも、もっと多く実行させることができます。それぞれのマッピング機能が、その書き換えているマップファイルを示す一つのRewriteMap命令を使うために。ディレクトリごとの中身のマップをはっきりさせることはできないが、それはもちろん、ディレクトリごとの中身のこのマップを使うことは可能です。

プレインテキストや DBM フォーマットファイルのために、検索キーがマップファイルのmtimeまで in-core でキャッシュされるか、サーバが再起動します。このようにあらゆるリクエストのために使われるルールでマップ機能を持つことが出来ます。これは問題ではありません。なぜなら外部検索はただ一度実行するだけですから！

RewriteBase

Syntax: RewriteBase BaseURL
Default: default is the physical directory path
Context: per-directory config

RewriteBase命令は、ディレクトリごとの書き換えに対してベースの URL を明白に設定します。以下にあるように、RewriteRuleはディレクトリごとのコンフィグファイルで使われることができます(.htaccess)。そこではそれは、ローカルに実行する。すなわち、ローカルなディレクトリの接頭部は、この処理の段階で外され、書き換えルールは残っているものだけに作用します。最後に、それは自動的に付け加えられます。

代理が新しい URL のために立ち上がる時、このモジュールはサーバの処理に URL を再導入しなければなりません。これを可能にするためには、対応する URL 接頭部、または URL ベースが何なのかを知る必要があります。デフォルトでは、この接頭部はそれ自身対応するファイルパスです。しかし、ほとんどのウェブサイトのURLsは物理的なファイル名のパスに対応していないディレクトリなので、この仮定は通常正しくないでしょう！そこで正確な URL 接頭部を指定するために、RewriteBase命令を使わなければなりません。

それで、もしウェブサーバの URLs が物理的なファイルパスに対応していないディレクトリならば、RewriteRule命令を使いたいあらゆる.htaccessファイルでRewriteBaseを使わなければなりません。

Example:

以下のディレクトリごとのコンフィグファイルを仮定します: 

#
#  /abc/def/.htaccess -- per-dir config file for directory /abc/def
#  Remember: /abc/def is the physical path of /xyz, i.e. the server
#            has a 'Alias /xyz /abc/def' directive e.g.
#

RewriteEngine On

#  let the server know that we are reached via /xyz and not
#  via the physical path prefix /abc/def
RewriteBase   /xyz

#  now the rewriting rules
RewriteRule   ^oldstuff\.html$  newstuff.html

上記の例では、/xyz/oldstuff.htmlに対するリクエストが物理的なファイル/abc/def/newstuff.htmlに正確に書き換えています。

Apache ハッカーのために:
以下のリストは内部処理段階についての詳細な情報です： 

Request:
  /xyz/oldstuff.html

Internal Processing:
  /xyz/oldstuff.html     -> /abc/def/oldstuff.html    (per-server Alias)
  /abc/def/oldstuff.html -> /abc/def/newstuff.html    (per-dir    RewriteRule)
  /abc/def/newstuff.html -> /xyz/newstuff.html        (per-dir    RewriteBase)
  /xyz/newstuff.html     -> /abc/def/newstuff.html    (per-server Alias)

Result:
  /abc/def/newstuff.html
これは非常に複雑に見えるが、正確な Apache の内部処理です。なぜなら、ディレクトリごとの書き換えが処理速度を遅くしているからです。それで、それが実行している時、（書き換え）リクエストは Apache kernel の中に再導入されなければなりません。しかし：これは深刻な遠周りのように見える一方、実はそうではありません。なぜなら、この再導入は Apache サーバに対して完全に内部で実行し、同じ手続きが Apache 内部の多くの他の操作によって使われているからです。それで目的と実行が正確であることが確信できます。

RewriteCond

Syntax: RewriteCond TestString CondPattern
Default: -None-
Context: server config, virtual host, per-directory config

RewriteCond命令はルール条件を定義しています。RewriteRule命令の一つかそれ以上前にRewriteCond命令がなければなりません。もしそのパターンが現在の URL の状態と合致していて、そしてこれらの追加条件も適用されるなら、以下の書き換えルールは使われるだけです。

TestStringはプレインテキストに追加する、以下の拡張構造を含むストリングです:

Special Notes:

  1. 変数 SCRIPT_FILENAME と REQUEST_FILENAME は同じ値、すなわちアパッチサーバの内部のrequest_rec構造filenameの領域を含んでいます。前者は一般的な CGI 変数名として知られているが、後者は REQUEST_URI に一貫して対応しています（request_recのuri領域の値を含んでいる）。

  2. 特別なフォーマットがあります: %{ENV:variable}がvariableであればどんな環境変数でも有り得ます。これはアパッチのサーバ処理から内部アパッチ構造と、(もしそこになければ)getenv()によって検索されます。

  3. 特別なフォーマットがあります: %{HTTP:header}はheaderであればどんなHTTP MIME-header名でも有り得ます。これはHTTPリクエストから検索されます。例: %{HTTP:Proxy-Connection}はHTTPヘッダーの``Proxy-Connection:''の値です。

  4. 特別なフォーマットがあります: %{LA-U:url}は-Uのようなlook-aheadsのためのものです。これはurlのファイナル値についてのlook-aheadへの内部サブリクエストとして動きます。

  5. 特別なフォーマットがあります: %{LA-F:file}は-Fのようなlook-aheadsのためのものです。これはファイルのファイナル値についてのlook-aheadへの内部サブリクエストとして動きます。

CondPatternは状態パターン、すなわちTestStringの現在の事例に当てはまる通常表記であり、TestStringは評価されて、その時CondPatternに対して対抗させられます。

注: CondPatternは多少の追記のある標準的なExtended Regular Expressionです：

  1. CondPatternsにはいくつかの特別形があります。本当の通常表記ストリングの代わりに、以下のうちの一つを使うこともできます:

  2. CondPatternsにはいくつかの特別形があります。本当の通常表記ストリングの代わりに、以下のうちの一つを使うこともできます:

    注: これらの全てのテストは、それらを無効にするための('!')ではない文字によって先に付けられます。

さらに、付加することによってCondPatternのために特別なフラッグを設定することができます。

[flags]
as the third argument to the RewriteCond directive. Flags is a comma-separated list of the following flags:

Example:

リクエストの``User-Agent:''というヘッダーによってサイトのホームページを書き換えるために、以下のものを使うことが出来ます： 
RewriteCond  %{HTTP_USER_AGENT}  ^Mozilla.*
RewriteRule  ^/$                 /homepage.max.html  [L]

RewriteCond  %{HTTP_USER_AGENT}  ^Lynx.*
RewriteRule  ^/$                 /homepage.min.html  [L]

RewriteRule  ^/$                 /homepage.std.html  [L]
解説: もしブラウザとして（それ自身が'Mozilla'と認識する）ネットスケープナビゲータを使っているなら、フレーム等を含む最大限のホームページを入手します。もし（ターミナルベースである）Lynx ブラウザを使っているなら、イメージや表等を含まない最小限のホームページを入手します。もしそれ以外のブラウザを使っているなら、標準的なホームページを入手します。

RewriteRule

Syntax: RewriteRule Pattern Substitution
Default: -None-
Context: server config, virtual host, per-directory config

RewriteRule命令は本当の書き換えを行なうのに有効です。この命令は、一度よりも多く実行することができます。それから、それぞれの命令が一つの書き換えルールを定義します。これらのルールの定義状態は重要です。なぜなら作動中にルールを割り当てる時、この状態が使われるからです。

Patternは現在の URL に対して割り当てられた通常表記 (for Apache 1.1.x a System V8 and for Apache 1.2.x a POSIX) であり得ます。ここでこのルールが割り当てられた時、``current''は URL の値を意味します。これはオリジナルのリクエストされた URL ではないかもしれません。なぜなら、その前にルールのいくつかの数が合致していて、それに変更を加えることが有り得るからです。

通常表記のsyntaxについてのいくつかのヒント： 

^           Start of line
$           End of line
.           Any single character
[chars]     One of chars
[^chars]    None of chars

?           0 or 1 of the preceding char
*           0 or N of the preceding char
+           1 or N of the preceding char

\char       escape that specific char
            (e.g. for specifying the chars ".[]()" etc.)

(string)    Grouping of chars (the Nth group can be used on the RHS with $N)

更に、NOT 文字('!')は可能なパターン接頭句である。これはパターンを無効にして、言う効力を与えます。例えば：``if the current URL does NOT match to this pattern''.これは、ネガティブなパターンと合致するのがより良い、特別な場合か、または最新のデフォルトルールとして使われることができます。

注意! パターンを無効にする NOT 文字を使う時、パターンにグループ化されたワイルドカードを用いることは出来ません。これが不可能なのは、グループのためにパターンが合致しなくて、中身がないからです。その結果、もし無効なパターンが使われたら、代用ストリングの$Nを使うことはできません！

Substitution of a rewriting rule is the string which is substituted for (or replaces) the original URL for which Pattern matched. Beside plain text you can use

  1. back-references $N to the RewriteRule pattern
  2. back-references %N to the last matched RewriteCond pattern
  3. server-variables as in rule condition test-strings (%{VARNAME})
  4. mapping-function calls (${mapname:key|default})
後部の記述はPatternに合致したN番目のグループの内容によって置き換えられる$N (N=1..9)という確認です。サーバ変数は RewriteCond命令のTestStringにとって同じようなものです。マッピング機能はRewriteMap命令によって行ない、そこで明白にされます。これら 3 種類の変数は、上記リストの状態で展開されます。

既に上で書かれたように、全ての書き換えルールはSubstitutionに割り当てられます（コンフィグファイルの定義状態で）。URL はSubstitutionによって完全に置き換えられ、書き換え処理はルールがなくなるまで続きます（Lフラッグによる明白な終端がない限りー以下参照）

'-'という特別な代用ストリングは：「代用がない！」ことを示す。愚かに聞こえるでしょうか？いいえ、いくつかの URLs にだけ合致して、代用を行なわない書き換えルールを提供する有効なものです。例えば、 代用が実行するよりも前に、割り当てられた 1 つより多くのパターンを持つことが可能なC(chain) フラッグと関連してです。

One more note: You can even create URLs in the substitution string containing a query string part. Just use a question mark inside the substitution string to indicate that the following stuff should be re-injected into the QUERY_STRING. When you want to erase an existing query string, end the substitution string with just the question mark.

注: 特別な特徴があります。http://thishost[:thisport] という代用フィールドが接頭句である時、mod_rewriteは自動的にそれを外します。この絶対的な外部方向転換の URLs の自動削除は、有効なものであり、ホストネームの部分が生じるマッピング機能と結合して使われる重要な特徴です。これを理解するには、以下の例のセクションの最初の例を見てください。

確認: 所有するサーバに対する無条件の外部方向転換が、http://thishostという接頭句では働かないのは、この特徴のせいです。そのような自己方向転換を完了するためには、Rフラッグを使わなければなりません。(以下参照)

さらに、追記することによってSubstitutionのための特別なフラッグを設定することができます。

[flags]
３番目としてRewriteRule命令に。Flagsは以下のフラッグのコンマで区切られたリストです:

確認：サーバごとのコンフィグレーションファイルの完了した URL にPatternが追加されたことを決して忘れないで下さい。しかし、ディレクトリごとのコンフィグレーションファイルでは、代用が行われた後、ディレクトリごとの接頭句（いつも特定のディレクトリとっては同じ物！）がパターンの一致で自動的にremovedされ、自動的にaddedされます。この特徴は多くの種類の書き換えの基本になっています。なぜなら、この接頭句を外すことなしでは、常に実行可能とは限らない親ディレクトリと一致しなければならないからです。

一つ例外があります：もし代用ストリングが``http://''で始まっていれば、ディレクトリの接頭句は追加されず、外部方向転換やプロキシーのスループット（もしPフラッグが使われていれば！）が働きます!

注意！ディレクトリごとのコンフィフレーションファイルの書き換えエンジンを可能にするためには、これらのファイルで``RewriteEngine On''と可能になった``Option FollowSymLinks''を設定する必要があります。もし管理者がユーザディレクトリのFollowSymLinksの override を不可能にしていれば、書き換えエンジンを使うことはできません。この制限はセキュリティ上必要です。

ここには全ての可能な代用の組み合わせとその意味が記述してあります:

Inside per-server configuration (httpd.conf)
for request ``GET /somepath/pathinfo'':

Given Rule                                      Resulting Substitution
----------------------------------------------  ----------------------------------
^/somepath(.*) otherpath$1                      not supported, because invalid!

^/somepath(.*) otherpath$1  [R]                 not supported, because invalid!

^/somepath(.*) otherpath$1  [P]                 not supported, because invalid!
----------------------------------------------  ----------------------------------
^/somepath(.*) /otherpath$1                     /otherpath/pathinfo

^/somepath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
                                                via external redirection

^/somepath(.*) /otherpath$1 [P]                 not supported, because silly!
----------------------------------------------  ----------------------------------
^/somepath(.*) http://thishost/otherpath$1      /otherpath/pathinfo

^/somepath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
                                                via external redirection

^/somepath(.*) http://thishost/otherpath$1 [P]  not supported, because silly!
----------------------------------------------  ----------------------------------
^/somepath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
                                                via external redirection

^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
                                                via external redirection
                                                (the [R] flag is redundant)

^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
                                                via internal proxy

Inside per-directory configuration for /somepath
(i.e. file .htaccess in dir /physical/path/to/somepath containing RewriteBase /somepath)
for request ``GET /somepath/localpath/pathinfo'':

Given Rule                                      Resulting Substitution
----------------------------------------------  ----------------------------------
^localpath(.*) otherpath$1                      /somepath/otherpath/pathinfo

^localpath(.*) otherpath$1  [R]                 http://thishost/somepath/otherpath/pathinfo
                                                via external redirection

^localpath(.*) otherpath$1  [P]                 not supported, because silly!
----------------------------------------------  ----------------------------------
^localpath(.*) /otherpath$1                     /otherpath/pathinfo

^localpath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
                                                via external redirection

^localpath(.*) /otherpath$1 [P]                 not supported, because silly!
----------------------------------------------  ----------------------------------
^localpath(.*) http://thishost/otherpath$1      /otherpath/pathinfo

^localpath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
                                                via external redirection

^localpath(.*) http://thishost/otherpath$1 [P]  not supported, because silly!
----------------------------------------------  ----------------------------------
^localpath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
                                                via external redirection

^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
                                                via external redirection
                                                (the [R] flag is redundant)

^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
                                                via internal proxy

Example:

We want to rewrite URLs of the form
/ Language /~ Realname /.../ File
into
/u/ Username /.../ File . Language

上記の書き換えマップファイルは/anywhere/map.real-to-userの下に置いてあります。それから、Apache サーバのコンフィグレーションファイルに以下の行を追加することだけをしなければなりません： 

RewriteLog   /anywhere/rewrite.log
RewriteMap   real-to-user               txt:/anywhere/map.real-to-host
RewriteRule  ^/([^/]+)/~([^/]+)/(.*)$   /u/${real-to-user:$2|nobody}/$3.$1

Additional Features

Environment Variables

 This module keeps track of two additional (non-standard) CGI/SSI environment variables named SCRIPT_URL and SCRIPT_URI. These contain the logical Web-view to the current resource, while the standard CGI/SSI variables SCRIPT_NAME and SCRIPT_FILENAME contain the physical System-view.

Notice: These variables hold the URI/URL as they were initially requested, i.e. in a state before any rewriting. This is important because the rewriting process is primarily used to rewrite logical URLs to physical pathnames.

Example: 

SCRIPT_NAME=/v/sw/free/lib/apache/global/u/rse/.www/index.html
SCRIPT_FILENAME=/u/rse/.www/index.html
SCRIPT_URL=/u/rse/
SCRIPT_URI=http://en2.en.sdm.de/u/rse/

Apache HTTP Server Version 1.3

検索文字
このJAPACHE!ニュースグループへ ( japache.mod.rewrite ) | JAPACHE!ニュースについて | JAPACHE!ホームページへ

Index Home The English original manual is here.

このページの情報に関わる、ご質問、お問い合わせは、 japache@infoscience.co.jpまで。