mod_substitute: SubstituteInheritBefore

2025-05-27

mod_substituteは、Apache HTTP Serverの出力フィルターモジュールの一つで、サーバーがクライアントに返すレスポンスボディ（HTML、XML、テキストなど）に対して、正規表現や固定文字列を使った検索・置換を実行する機能を提供します。

SubstituteInheritBeforeディレクティブは、このmod_substituteモジュールにおいて、継承された置換ルールが、現在のコンテキスト（例えば<Location>や<Directory>）で定義された置換ルールよりも先に適用されるか、後に適用されるかを制御するために使用されます。

動作の仕組み

Apacheの設定では、階層構造（例: サーバー全体の設定 -> バーチャルホスト -> ディレクトリ -> Location）でディレクティブを定義できます。下位のコンテキストは上位のコンテキストの設定を継承します。

mod_substituteで複数のSubstituteディレクティブが異なるコンテキストで定義されている場合、それらの置換が適用される順序が重要になります。

SubstituteInheritBefore off (デフォルト): この設定が有効な場合（デフォルトの動作）、現在のコンテキスト（子）で定義されたSubstituteルールが、上位のコンテキスト（親）から継承されたSubstituteルールよりも後に適用されます。つまり、子の置換が先に実行され、その結果に対して親の置換が適用されます。これは少し直感に反するように聞こえるかもしれませんが、Apacheの一般的なディレクティブの処理順序に沿っています。
SubstituteInheritBefore on (デフォルトではない): この設定が有効な場合、上位のコンテキスト（親）から継承されたSubstituteルールが、現在のコンテキスト（子）で定義されたSubstituteルールよりも先に適用されます。つまり、親の置換が先に実行され、その結果に対して子の置換が適用されます。

使用例

例えば、以下のような設定があるとします。

<VirtualHost *:80>
    ServerName example.com
    AddOutputFilterByType SUBSTITUTE text/html

    # 親のコンテキスト（VirtualHost）での置換ルール
    Substitute "s/old_text_parent/new_text_parent/i"

    <Location "/mypath/">
        # 子のコンテキスト（Location）での置換ルール
        Substitute "s/old_text_child/new_text_child/i"

        # ここで SubstituteInheritBefore を設定
        # SubstituteInheritBefore on  # または
        # SubstituteInheritBefore off # デフォルト
    </Location>
</VirtualHost>

SubstituteInheritBefore off (デフォルトの場合) /mypath/へのリクエストに対しては、まず<Location "/mypath/">内のSubstitute "s/old_text_child/new_text_child/i"が適用されます。その結果に対して、<VirtualHost>で定義されたSubstitute "s/old_text_parent/new_text_parent/i"が適用されます。
SubstituteInheritBefore on の場合 /mypath/へのリクエストに対しては、まず<VirtualHost>で定義されたSubstitute "s/old_text_parent/new_text_parent/i"が適用されます。その結果に対して、<Location "/mypath/">内のSubstitute "s/old_text_child/new_text_child/i"が適用されます。

なぜこのディレクティブが必要なのか？

複数のSubstituteルールが定義されている場合、その適用順序によって最終的なレスポンスの内容が変わる可能性があります。特に、ある置換の結果が別の置換の対象となるような場合に、この順序制御は非常に重要になります。

例えば、親のルールが特定のタグを置換し、子のルールがその置換後のタグに含まれるテキストをさらに置換したい場合など、意図した通りの処理を行うためにはSubstituteInheritBeforeの制御が必要になります。

SubstituteInheritBeforeは、mod_substituteの置換ルールの適用順序を制御する重要なディレクティブですが、その挙動を理解していないと意図しない結果を招くことがあります。

想定通りの置換が行われない

エラーの症状
定義した置換ルールが全く適用されない、または一部の置換ルールのみが適用され、期待される最終結果にならない。特に、複数のコンテキスト（VirtualHost、Directory、Locationなど）でSubstituteディレクティブを定義している場合に発生しやすいです。

考えられる原因

フィルタチェーンの順序
mod_substituteは出力フィルターとして動作します。他の出力フィルター（例: mod_deflateによる圧縮）がmod_substituteよりも先に適用されてしまうと、mod_substituteが処理すべきコンテンツが既に変更されている、または圧縮されてしまい、置換が機能しないことがあります。
置換ルールの競合
複数の置換ルールが同じ文字列を対象としており、適用順序によって結果が変わってしまう。例えば、親のルールが「A」を「B」に置換し、子のルールが「B」を「C」に置換する場合、順序が逆だと「A」が「C」にならないことがあります。
SubstituteInheritBeforeの設定ミス
onとoffのどちらが適用されるべきか、その意図と設定が一致していない。デフォルトがoff（子のルールが先に適用）であることを理解していない場合、親のルールが先に適用されると誤解している可能性があります。

トラブルシューティング

フィルタチェーンの確認と調整
- AddOutputFilterやSetOutputFilterディレクティブで、SUBSTITUTEフィルターが他のフィルター（特にDEFLATEやGZIPなどの圧縮フィルター）よりも後に適用されるように設定されているかを確認します。一般的には、AddOutputFilterByType SUBSTITUTE text/html のように指定するだけでなく、フィルタチェーンの明確な順序付けが必要になる場合があります。
- 例: AddOutputFilterByType DEFLATE;SUBSTITUTE text/html のように指定すると、DEFLATEの後にSUBSTITUTEが適用されます。
- よくある問題として、ブラウザがAccept-Encoding: gzipヘッダを送信している場合に、Apacheが自動的にmod_deflateを適用し、コンテンツを圧縮してしまうことがあります。この場合、mod_substituteは圧縮されたコンテンツを処理できず、置換が機能しません。
  - 一時的な解決策としては、RequestHeader unset Accept-Encodingを使用することで、ブラウザからの圧縮要求を無視させることができます（ただし、パフォーマンスに影響が出る可能性があります）。
  - より良い解決策は、フィルタチェーンの順序を適切に設定することです。例えば、AddOutputFilterByType INFLATE;SUBSTITUTE;DEFLATE text/html のように、圧縮解除（INFLATE）、置換（SUBSTITUTE）、再圧縮（DEFLATE）の順序でフィルターを適用します。
置換ルールの確認
- 各Substituteディレクティブの正規表現や置換文字列が正しいか確認します。
- 複数のSubstituteルールがある場合、それらが相互に影響し合う可能性があるため、テスト用の文字列を使って単独で動作するか確認します。
- qフラグ（no-flatten）の使用にも注意が必要です。これはパフォーマンス向上に役立ちますが、ある置換の結果が後続の置換のパターンに影響を与えない場合にのみ使用すべきです。デフォルトのfフラグ（flatten）は、置換の結果が後続の置換の対象となる可能性を考慮します。
SubstituteInheritBeforeの確認
- 設定ファイル全体でSubstituteInheritBeforeがどこに定義されているかを確認します。特定のコンテキストで明示的に設定されていない場合、そのコンテキストは最も近い上位のコンテキストのSubstituteInheritBeforeの設定を継承します。
- 意図する適用順序に合わせてonまたはoffを明示的に設定し、動作を確認します。

.htaccessファイルでの問題

エラーの症状
.htaccessファイルでSubstituteディレクティブやSubstituteInheritBeforeディレクティブを設定しても、何も効果がない。

考えられる原因

AllowOverride FileInfoの不足
mod_substituteのディレクティブは、FileInfoオーバーライドが許可されていないと.htaccessで機能しません。

トラブルシューティング

httpd.confまたはバーチャルホスト設定の確認
- 該当するDirectoryコンテキストに対してAllowOverride FileInfoが設定されていることを確認します。AllowOverride Allであれば問題ありませんが、セキュリティ上の理由からAllを避ける場合はFileInfoを明示的に追加する必要があります。

Apacheの起動/再起動時のエラー

エラーの症状
Apacheの起動または再起動時に構文エラーが表示される。

考えられる原因

ディレクティブの記述ミス
スペルミスや構文エラー。
mod_substituteモジュールがロードされていない
SubstituteやSubstituteInheritBeforeディレクティブを使用するには、mod_substituteモジュールがロードされている必要があります。

構文チェック
- apachectl configtest または httpd -t コマンドを実行して、設定ファイルの構文エラーをチェックします。エラーメッセージに示される行番号とディレクティブを確認し、修正します。
モジュールのロード確認
- httpd.confまたは適切な設定ファイルでLoadModule substitute_module modules/mod_substitute.so（またはOSに応じたパス）がコメントアウトされていないことを確認します。

一般的なトラブルシューティングのヒント

curlコマンドでテストする
curl -v http://your.domain.com/path/ のように-vオプションを付けてリクエストを送信すると、HTTPヘッダやレスポンスボディを詳細に確認でき、デバッグに役立ちます。
ブラウザの開発者ツールを使用する
ブラウザの開発者ツール（F12キーで開けることが多い）を使って、サーバーから返される生のレスポンスボディを確認します。これにより、mod_substituteが適用される前の内容や、適用後の内容がどのように変化しているかを確認できます。
段階的に設定を適用する
複雑な置換や複数のコンテキスト設定がある場合、一度に全ての設定を適用するのではなく、シンプルなものから段階的に追加していき、その都度動作確認を行うことで、問題の切り分けが容易になります。
Apacheのエラーログを確認する
問題が発生した場合、error_logファイル（通常は/var/log/httpd/error_logや/var/log/apache2/error.logなど）に詳細な情報が出力されていることが多いです。エラーメッセージや警告メッセージを手がかりに問題を特定します。

ここでは、httpd.conf（またはバーチャルホスト設定ファイル）に記述する設定例を通じて、SubstituteInheritBeforeが置換ルールの適用順序にどのように影響するかを示します。

前提

テスト用のHTMLファイルが用意されていること
mod_substituteモジュールがロードされていること（LoadModule substitute_module modules/mod_substitute.so）

テスト用のHTMLファイル (`test.html`)

<!DOCTYPE html>
<html>
<head>
    <title>Substitute Test</title>
</head>
<body>
    <h1>Welcome to the Test Page</h1>
    <p>This is some initial text.</p>
    <p>The **initial text** is here.</p>
    <p>Another line with **initial text**.</p>
</body>
</html>

このtest.htmlに対して、親コンテキストと子コンテキストで異なる置換ルールを適用し、SubstituteInheritBeforeの設定によって結果がどう変わるかを見ていきます。

例1: `SubstituteInheritBefore off` (デフォルトの挙動)

この設定では、子コンテキストで定義された置換ルールが先に適用され、その結果に対して親コンテキストのルールが適用されます。

Apache設定 (httpd.conf またはバーチャルホスト設定)

# mod_substitute モジュールのロードを確認
LoadModule substitute_module modules/mod_substitute.so

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot "/path/to/your/htdocs" # test.html が置かれているディレクトリ

    # サーバー全体（親コンテキスト）の置換ルール
    # 「old」を「GLOBAL」に置換
    Substitute "s/old/GLOBAL/i"

    # HTMLコンテンツに対してmod_substituteを適用
    AddOutputFilterByType SUBSTITUTE text/html

    <Directory "/path/to/your/htdocs/sub/">
        # ここは /path/to/your/htdocs/sub/ にアクセスした場合に適用される
        # (test.html をこのディレクトリに置くか、エイリアス設定などをしてテスト)

        # デフォルトは off なので、明示的に記述しなくても同じ挙動
        # SubstituteInheritBefore off 

        # 子コンテキストの置換ルール
        # 「text」を「LOCAL」に置換
        Substitute "s/text/LOCAL/i"
    </Directory>

    <Location "/">
        # Root パスへのアクセスに適用される
        # (test.html を DocumentRoot に置く場合)

        # デフォルトは off なので、明示的に記述しなくても同じ挙動
        # SubstituteInheritBefore off

        # 子コンテキストの置換ルール
        # 「text」を「LOCAL」に置換
        Substitute "s/text/LOCAL/i"
    </Location>

</VirtualHost>

期待される出力 (test.html にアクセスした場合)

元のテキスト: The **initial text** is here.
子コンテキストの置換 (s/text/LOCAL/i): The **initial LOCAL** is here.
親コンテキストの置換 (s/old/GLOBAL/i): (このルールはoldという単語を探すが、既にLOCALに置換されているため、何も変更されない)

最終結果

<!DOCTYPE html>
<html>
<head>
    <title>Substitute Test</title>
</head>
<body>
    <h1>Welcome to the Test Page</h1>
    <p>This is some initial LOCAL.</p>
    <p>The **initial LOCAL** is here.</p>
    <p>Another line with **initial LOCAL**.</p>
</body>
</html>

「initial text」の「text」が「LOCAL」に置換され、「old」はどこにも現れないため、「GLOBAL」への置換は行われません。これは、子の置換が親の置換よりも先に行われるためです。

例2: `SubstituteInheritBefore on`

この設定では、親コンテキストで定義された置換ルールが先に適用され、その結果に対して子コンテキストのルールが適用されます。

Apache設定 (httpd.conf またはバーチャルホスト設定)

# mod_substitute モジュールのロードを確認
LoadModule substitute_module modules/mod_substitute.so

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot "/path/to/your/htdocs" # test.html が置かれているディレクトリ

    # サーバー全体（親コンテキスト）の置換ルール
    # 「initial text」を「old content」に置換
    Substitute "s/initial text/old content/i"

    # HTMLコンテンツに対してmod_substituteを適用
    AddOutputFilterByType SUBSTITUTE text/html

    <Location "/">
        # ここで SubstituteInheritBefore を on に設定
        SubstituteInheritBefore on

        # 子コンテキストの置換ルール
        # 「old」を「NEW」に置換
        Substitute "s/old/NEW/i"
    </Location>

</VirtualHost>

期待される出力 (test.html にアクセスした場合)

元のテキスト: The **initial text** is here.
親コンテキストの置換 (s/initial text/old content/i): The **old content** is here.
子コンテキストの置換 (s/old/NEW/i): The **NEW content** is here.

最終結果

<!DOCTYPE html>
<html>
<head>
    <title>Substitute Test</title>
</head>
<body>
    <h1>Welcome to the Test Page</h1>
    <p>This is some NEW content.</p>
    <p>The **NEW content** is here.</p>
    <p>Another line with **NEW content**.</p>
</body>
</html>

「initial text」がまず「old content」に置換され、その結果含まれる「old」がさらに「NEW」に置換されました。これは、親の置換が子の置換よりも先に行われたためです。

`.htaccess`での使用例

.htaccessファイルでもSubstituteInheritBeforeを使用できますが、サーバーのメイン設定ファイルでAllowOverride FileInfoが許可されている必要があります。

.htaccessファイルの内容

# mod_substitute を有効にする (この行はhttpd.confでも設定可能)
AddOutputFilterByType SUBSTITUTE text/html

# 親からの継承ルールを先に適用
SubstituteInheritBefore on

# このディレクトリ固有の置換ルール
Substitute "s/example/sample/i"

この例では、親ディレクトリやバーチャルホストで定義されたSubstituteルールがあれば、それらが.htaccessで定義されたルールよりも先に適用されます。

SubstituteInheritBeforeディレクティブは、複数のApacheコンテキスト（VirtualHost、Directory、Locationなど）でmod_substituteの置換ルールが定義されている場合に、それらの適用順序を制御するために使用されます。

SubstituteInheritBefore on: 親のルールが先に適用され、その結果に子のルールが適用されます。
SubstituteInheritBefore off (デフォルト): 子のルールが先に適用され、その結果に親のルールが適用されます。

mod_substituteが主にHTTPレスポンスのコンテンツ（HTML、テキストなど）のインライン置換に使用されるのに対し、代替方法は異なるレイヤーや目的でコンテンツを操作します。

mod_rewrite (URLの書き換え)

mod_substituteと混同されがちですが、mod_rewriteはURLの書き換えに特化しており、レスポンスボディのコンテンツ自体を操作するものではありません。しかし、状況によってはmod_substituteの代わりにURLの書き換えで問題を解決できる場合があります。

用途

特定の条件に基づくリクエストのブロックやリダイレクト
異なるドメインへのプロキシ（mod_proxyと組み合わせて）
古いURLから新しいURLへのリダイレクト（301 Moved Permanentlyなど）
フレンドリーURLの作成（例: /products?id=123 を /products/123 に）

mod_substituteとの違い

mod_rewriteはリクエストURLやHTTPヘッダーを操作します。コンテンツ自体は変更しません。
mod_substituteはレスポンスボディの文字列を置換します。

代替となるケース

例えば、バックエンドサーバーが返すURLがフロントエンドのURLと異なる場合に、ユーザーがアクセスするURL自体を書き換えたい場合など。ただし、これはmod_proxyとProxyPassReverseを組み合わせることで解決できることが多いです。
もし、Webページ内のハードコードされたURLを置換したいのではなく、リクエストのパスやホスト名を変えたいのであれば、mod_rewriteが適切です。

コード例 (httpd.conf)

# mod_rewrite を有効にする
LoadModule rewrite_module modules/mod_rewrite.so

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot "/var/www/html"

    RewriteEngine On
    # OldPage.html へのアクセスを NewPage.html に内部的に書き換える
    RewriteRule ^/OldPage.html$ /NewPage.html [L]

    # /blog/ のリクエストを内部のブログサーバーにプロキシする
    # この場合、mod_proxy_html や mod_substitute が必要になることも
    # RewriteRule ^/blog/(.*)$ http://internal-blog.example.com/$1 [P,L]
</VirtualHost>

mod_proxy_html (プロキシされたHTMLのリンク書き換え)

mod_proxy_htmlは、リバースプロキシ環境で特に役立つモジュールです。バックエンドサーバーから取得したHTMLコンテンツ内のURLやパスを、フロントエンドのURLに合わせて自動的に書き換えることに特化しています。mod_substituteよりもHTMLの構造を理解しているため、より安全かつ正確な置換が可能です。

用途

HTMLタグの属性（href, src, actionなど）内のURLを効率的に書き換える。
リバースプロキシ環境で、バックエンドから返されるHTML、CSS、JavaScript内のURLをフロントエンドのURLに修正する。

mod_substituteとの違い

mod_proxy_htmlはHTMLパーサーとして動作し、HTMLタグの属性内でのみURLを置換するなど、よりセマンティックな置換が可能です。
mod_substituteは汎用的な文字列置換であり、HTMLの構造を意識しません。そのため、意図しない部分まで置換してしまうリスクがあります。

代替となるケース

JavaScriptやCSSファイル内のURLを、プロキシ経由のアクセスに合わせて修正する必要がある場合。
リバースプロキシの背後にあるアプリケーションが、自身の内部URLをハードコードしてレスポンスを返している場合。

コード例 (httpd.conf)

# mod_proxy_html モジュールのロードを確認
LoadModule proxy_html_module modules/mod_proxy_html.so
LoadModule xml2enc_module modules/mod_xml2enc.so # 依存モジュール

<VirtualHost *:80>
    ServerName frontend.example.com

    ProxyPass "/app/" "http://backend.example.com/"
    ProxyPassReverse "/app/" "http://backend.example.com/"

    <Location "/app/">
        # HTMLコンテンツに対してmod_proxy_htmlを有効化
        ProxyHTMLEnable On
        
        # バックエンドのURLをフロントエンドのURLに書き換えるルール
        ProxyHTMLURLMap "http://backend.example.com/" "/app/"
        ProxyHTMLURLMap "/backend_path/" "/app/frontend_path/" # 必要に応じて詳細なマッピング
    </Location>
</VirtualHost>

mod_sed (より高度なストリーム編集)

mod_sedは、UNIXのsedコマンドと同様の強力なストリーム編集機能を提供するモジュールです。mod_substituteよりも複雑な正規表現や複数の編集コマンドを適用できますが、その分設定は複雑になります。

用途

ファイル全体に対する複数の置換操作を順次適用したい場合。
非常に複雑な正規表現パターンや複数行にわたる置換が必要な場合。

mod_substituteとの違い

mod_sedはストリーム全体を対象とした、より高度なsedスクリプトのような操作が可能です。
mod_substituteは単純な検索置換に特化しており、一行ごとの処理が基本です。

代替となるケース

mod_substituteでは対応できない、非常に複雑なテキスト処理（例: 特定のブロック全体を削除・置換、複数行にまたがるパターンマッチング）が必要な場合。

コード例 (httpd.conf)

# mod_sed モジュールのロードを確認
LoadModule sed_module modules/mod_sed.so

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot "/path/to/your/htdocs"

    # HTMLコンテンツに対してmod_sedを適用
    AddOutputFilterByType SED text/html

    <Location "/">
        # sedコマンドのように、レスポンスボディ全体に対して置換を実行
        # 「text」を「SED_PROCESSED_TEXT」に置換
        Sed "s/text/SED_PROCESSED_TEXT/g"
        
        # 別のsedコマンドを追加して、さらに加工
        # 「initial」を「FINAL」に置換
        Sed "s/initial/FINAL/g"
    </Location>
</VirtualHost>

mod_sedの場合、SubstituteInheritBeforeのような明示的な継承順序制御は通常必要ありません。Sedディレクティブは定義された順序で適用されるか、フィルタチェーン内のSEDフィルタの位置によって適用順序が決定されます。

アプリケーション層での処理

最も柔軟で強力な方法は、Apacheレベルではなく、コンテンツを生成するアプリケーション自体（PHP、Python、Node.jsなど）で置換ロジックを実装することです。

用途

コンテンツ生成の段階で複雑なロジックを適用する必要がある場合。
ユーザーのログイン状態やセッション情報に基づいてコンテンツをパーソナライズする場合。
コンテンツがデータベースやAPIから動的に生成される場合。

mod_substituteとの違い

アプリケーションはデータベースアクセスや外部API連携など、Apache単体では不可能な複雑な処理を伴うことができます。
Apacheモジュールはサーバー全体または特定のパスに対して一律に適用されるのに対し、アプリケーションはより細かい粒度で、かつ動的な条件に基づいてコンテンツを操作できます。

代替となるケース

置換ロジックがビジネスロジックと密接に関連している場合。
Apacheの静的な設定では対応しきれない、非常に動的なコンテンツの操作が必要な場合。

コード例 (PHP)

<?php
// PHPで動的にコンテンツを生成し、文字列置換を行う例
$content = "<p>This is some initial text.</p><p>Another line with initial text.</p>";

// アプリケーション内で文字列を置換
$content = str_replace("initial text", "DYNAMIC CONTENT", $content);
$content = str_replace("text", "PHP_PROCESSED", $content); // さらに別の置換

echo "<!DOCTYPE html>
<html>
<head>
    <title>Application Substitute Test</title>
</head>
<body>
    <h1>Welcome to the Dynamic Page</h1>
    {$content}
</body>
</html>";
?>

各方法の選択肢と考慮事項

方法	特徴	Pros	Cons
`mod_substitute`	レスポンスボディのシンプルな文字列/正規表現置換	設定が比較的簡単、汎用性が高い	HTML構造を意識しない、複雑な置換は不向き
`mod_rewrite`	URLやヘッダーの書き換え	URLの正規化、リダイレクトに最適	コンテンツ自体は変更しない
`mod_proxy_html`	リバースプロキシ環境でのHTML内のURL置換に特化	HTMLセマンティクスを理解、正確な置換	プロキシ環境に限定される
`mod_sed`	高度な正規表現とストリーム編集（`sed`コマンド風）	非常に複雑なテキスト処理に対応	設定が複雑、パフォーマンスへの影響が大きい場合あり
アプリケーション層	コンテンツ生成ロジック内で動的にコンテンツを操作	最も柔軟、ビジネスロジックとの連携が容易	サーバー負荷が増える可能性、アプリケーションの変更が必要

SubstituteInheritBeforeの直接的な代替というよりは、「なぜmod_substituteを使いたいのか？」という根本的なニーズ（コンテンツの変更）に対して、より適切かもしれない別のApacheモジュールやアプローチが存在するという視点でこれらの方法を検討することが重要です。

mod_substitute: SubstituteInheritBefore

動作の仕組み

使用例

なぜこのディレクティブが必要なのか？

想定通りの置換が行われない

.htaccessファイルでの問題

Apacheの起動/再起動時のエラー

一般的なトラブルシューティングのヒント

テスト用のHTMLファイル (test.html)

例1: SubstituteInheritBefore off (デフォルトの挙動)

例2: SubstituteInheritBefore on

.htaccessでの使用例

mod_rewrite (URLの書き換え)

mod_proxy_html (プロキシされたHTMLのリンク書き換え)

mod_sed (より高度なストリーム編集)

アプリケーション層での処理

各方法の選択肢と考慮事項

テスト用のHTMLファイル (`test.html`)

例1: `SubstituteInheritBefore off` (デフォルトの挙動)

例2: `SubstituteInheritBefore on`

`.htaccess`での使用例