update transformation

[apache] / docs / manual / env.xml.ja

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="./style/manual.ja.xsl"?>
<!-- English Revision: 659902:782860 (outdated) -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<manualpage metafile="env.xml.meta">

  <title>Apache の環境変数</title>

  <summary>
    <p>Apache HTTP サーバは<em>環境変数</em>と呼ばれる、名前のついた
    変数に情報を記憶する仕組みを提供しています。この情報はログ収集や
    アクセス制御などのいろいろな操作を制御するために使うことができます。
    これらの変数は CGI スクリプトなどの外部プログラムと通信するためにも
    使われます。この文書はそれらの変数の操作方法と使用方法をいくつか
    紹介します。</p>

    <p>これらの変数は<em>環境変数</em>と呼ばれていますが、オペレーティング
    システムによって制御されている環境変数と同じではありません。
    実際は、これらの変数は Apache の内部構造の中に記憶され、操作されています。
    それらは、CGI や SSI スクリプトに渡されたときだけ、実際の
    オペレーティングシステムの環境変数になります。サーバ自身が
    実行されているオペレーティングシステムの環境を操作したい場合は、
    オペレーティングシステムのシェルが提供している標準の環境変数の
    操作方法を使わなければなりません。</p>
  </summary>

  <section id="setting">
    <title>環境変数の設定</title>
    <related>
      <modulelist>
        <module>mod_env</module>
        <module>mod_rewrite</module>
        <module>mod_setenvif</module>
        <module>mod_unique_id</module>
      </modulelist>
      <directivelist>
        <directive module="mod_setenvif">BrowserMatch</directive>
        <directive module="mod_setenvif">BrowserMatchNoCase</directive>
        <directive module="mod_env">PassEnv</directive>
        <directive module="mod_rewrite">RewriteRule</directive>
        <directive module="mod_env">SetEnv</directive>
        <directive module="mod_setenvif">SetEnvIf</directive>
        <directive module="mod_setenvif">SetEnvIfNoCase</directive>
        <directive module="mod_env">UnsetEnv</directive>
      </directivelist>
    </related>

    <section id="basic-manipulation">
        <title>基本的な環境の操作</title>

        <p>Apache において環境変数を設定する一番基本的な方法は、
        無条件に環境変数を設定する <directive module="mod_env"
        >SetEnv</directive> ディレクティブを使用することです。
        <directive module="mod_env">PassEnv</directive> 
        ディレクティブにより、Apache が起動されたシェルの
        環境変数を渡すこともできます。</p>

    </section>
    <section id="conditional">
        <title>リクエスト毎に条件に基づいて設定する</title>

        <p>より柔軟性を高めるために、mod_setenvif
        で提供されているディレクティブを使用することで、リクエストの
        特性に基づいて環境変数を設定することができます。例えば、特定のブラウザ
        (User-Agent) のリクエストや特定の Referer [意図的な綴りです]
        <transnote>正しい綴りは referrer ですが、HTTP の仕様では Referer
        となっています</transnote>ヘッダが見つかったときのみ変数を設定することができます。
        mod_rewrite の <directive module="mod_rewrite">RewriteRule</directive>
        ディレクティブにおいて環境変数を設定する <code>[E=...]</code>
        オプションを使用することで、
        より柔軟な設定を行なうことができます。</p>

    </section>
    <section id="unique-identifiers">
        <title>一意な識別子</title>

        <p>mod_unique_id は、非常に限られた条件の下で
        「すべて」のリクエストについて、一意であることが保証されている値を環境変数
        <code>UNIQUE_ID</code> に設定します。</p>

    </section>
    <section id="standard-cgi">
        <title>標準 CGI 変数</title>

        <p>Apache の設定ファイルで設定された環境変数とシェルから渡される
        環境変数に加えて、CGI スクリプトと SSI ページには <a
        href="http://cgi-spec.golux.com">CGI の仕様</a>で要求されている、
        リクエストのメタ情報を持った環境変数の組が提供されます。</p>

    </section>
    <section id="caveats">
        <title>いくつかの注意</title>

        <ul>
          <li>環境を操作するディレクティブを使って標準 CGI
          変数を上書きしたり変更したりすることはできません。</li>

          <li>CGI スクリプトを起動するために <program>suexec</program>
          が使用されている場合、CGI スクリプトが起動するために、環境変数は<em
          >安全</em>な環境変数の組に整理されます。
          この安全な環境変数の集合は、コンパイル時に <code>suexec.c</code>
          で定義されます。</li>

          <li>移植性のために、環境変数の名前はアルファベット、
          数字とアンダースコア <transnote>'_'</transnote> だけから成ります。
          さらに、最初の文字は数字であってはいけません。
          この制限に合わない文字は CGI スクリプトと SSI
          ページに渡されるときにアンダースコアに置換されます。</li>
          
          <li><directive module="mod_env">SetEnv</directive> はリクエスト処理の
          段階の中でも遅くに実行されます。つまり
          <directive module="mod_setenvif">SetEnvIf</directive> や
          <directive module="mod_rewrite">RewriteCond</directive>
          などからは、変数がそこで設定されていることがわかりません。</li>
        </ul>
    </section>
  </section>
  <section id="using">
    <title>環境変数の使用</title>

    <related>
      <modulelist>
        <module>mod_authz_host</module>
        <module>mod_cgi</module>
        <module>mod_ext_filter</module>
        <module>mod_headers</module>
        <module>mod_include</module>
        <module>mod_log_config</module>
        <module>mod_rewrite</module>
      </modulelist>
      <directivelist>
        <directive module="mod_authz_host">Allow</directive>
        <directive module="mod_log_config">CustomLog</directive>
        <directive module="mod_authz_host">Deny</directive>
        <directive module="mod_ext_filter">ExtFilterDefine</directive>
        <directive module="mod_headers">Header</directive>
        <directive module="mod_log_config">LogFormat</directive>
        <directive module="mod_rewrite">RewriteCond</directive>
        <directive module="mod_rewrite">RewriteRule</directive>
      </directivelist>
    </related>

    <section id="cgi-scripts">
        <title>CGI スクリプト</title>

        <p>環境変数の主な利用法の一つは、CGI スクリプトに情報を伝えることです。
        上で説明されているように、CGI スクリプトに渡される環境変数は Apache
        の設定により設定される変数に加えて、リクエストの標準のメタ情報を含んでいます。
        詳細は <a href="howto/cgi.html">CGI チュートリアル</a>
        を参照してください。</p>

    </section>
    <section id="ssi-pages">
        <title>SSI ページ</title>

        <p>mod_include の <code>INCLUDES</code> フィルタで処理される
        server-parsed (SSI) ドキュメントでは、<code>echo</code>
        要素を使用すると環境変数が出力されます。
        また、ページのある部分がリクエストの性質に応じて変更されるように、
        環境変数をフロー制御要素で使うことができます。詳細は
        <a href="howto/ssi.html">SSI チュートリアル</a> を参照してください。</p>

    </section>
    <section id="access-control">
        <title>アクセス制御</title>

        <p><code>allow from env=</code> ディレクティブと <code>deny from env=</code>
        ディレクティブを使用して、サーバへのアクセスを環境変数の値で制御することができます。
        <directive module="mod_setenvif">SetEnvIf</directive>
        ディレクティブと組み合わせることで、クライアントの特性に基づいて
        サーバへのアクセス制御を柔軟に行なうことができるようになります。
        たとえば、これらのディレクティブを使用して、特定のブラウザ (User-Agent)
        からのアクセスを拒否することができます。</p>

    </section>
    <section id="logging">
        <title>条件付きログ記録</title>

        <p><directive module="mod_log_config">LogFormat</directive>
        ディレクティブのオプション <code>%e</code>
        を使用することで、環境変数をアクセスログに記録することができます。さらに、
        <directive module="mod_log_config">CustomLog</directive>
        ディレクティブの条件分岐式を使用することで、
        環境変数の値によってリクエストをログに記録するかどうかを決めることができます。
        <directive module="mod_setenvif">SetEnvIf</directive>
        ディレクティブと組み合わせることで、
        どのリクエストをログに記録するかを柔軟に制御することが可能になります。たとえば、
        <code>gif</code> で終わるファイル名へのリクエストはログに記録しない、
        違うサブネットのクライアントからのリクエストだけをログに記録する、
        という選択が可能です。</p>

    </section>
    <section id="response-headers">
        <title>条件付き応答ヘッダ</title>

        <p><directive module="mod_headers">Header</directive>
        ディレクティブは環境変数の存在や不在によってクライアントへの応答に特定の
        HTTP ヘッダを付けるかどうかを決めることができます。
        これにより、たとえば、クライアントからのリクエスト
        にあるヘッダがある場合にのみ特定の応答ヘッダを送る、というようなことが
        できます。</p>

    </section>

    <section id="external-filter">
        <title>外部フィルタの適用</title>

        <p><directive module="mod_ext_filter">ExtFilterDefine</directive>
        ディレクティブを使用して
        <module>mod_ext_filter</module> で設定される外部フィルタは、
        <code>disableenv=</code> と <code>enableenv=</code>
        オプションを使って、環境変数による条件付き適用ができます。</p>
    </section>

    <section id="url-rewriting">
        <title>URL の書き換え</title>

        <p><directive module="mod_rewrite">RewriteCond</directive>
        ディレクティブで<em>評価文字列</em>として
        <code>%{ENV:...}</code> 式を指定することで、mod_rewrite
        の書き換えエンジンが環境変数に基いて条件分岐を行なうことができます。
        mod_rewrite が使用可能な変数で <code>ENV:</code> が前についていない変数は、
        実際は環境変数ではないということに注意してください。
        それらは他のモジュールからは使用できない mod_rewrite 用の特別な変数です。
        </p>
    </section>
  </section>

  <section id="special">
    <title>特別な目的の環境変数</title>

        <p>互換性の問題を解決するために、特定のクライアントと通信しているときは
        Apache の動作を変更できる機構が導入されました。できるだけ柔軟にするために、
        これらの機構は環境変数を定義することで呼び出されます。普通は、
        <directive module="mod_setenvif">BrowserMatch</directive>
        ディレクティブを使いますが、たとえば <directive module="mod_env"
        >SetEnv</directive> ディレクティブや <directive module="mod_env"
        >PassEnv</directive> ディレクティブも使用することができます。</p>

    <section id="downgrade">
        <title>downgrade-1.0</title>

        <p>これを指定することで、リクエストが HTTP/1.0
        より新しいプロトコルの場合でも、HTTP/1.0 として扱われます。</p>

    </section>
    <section id="force-gzip">
        <title>force-gzip</title>
          <p><code>DEFLATE</code> フィルタが使用するように設定されているときに、
          この環境変数はブラウザの accept-encoding の設定を無視して常に
          圧縮された出力を送るようにします。</p>
    </section>
    <section id="force-no-vary">
        <title>force-no-vary</title>

        <p>応答ヘッダがクライアントに送られる前に <code>Vary</code>
        フィールドを取り除きます。
        クライアントの中にはこのフィールドを正しく解釈しないものがあります。
        この変数を設定することでその問題を回避することができます。
        この変数を設定すると、<strong>force-response-1.0</strong>
        が設定されたことになります。</p>

    </section>
    <section id="force-response">
        <title>force-response-1.0</title>

        <p>これが設定されていると、HTTP/1.0 リクエストを発行するクライアントに対しては
        常に HTTP/1.0 で応答するようになります。この機能は、
        元々は AOL のプロキシの問題のために実装されました。HTTP/1.0 クライアントの中には、
        HTTP/1.1 の応答を返されると正しく動作しないものがあるかもしれません。
        この機能を使用することで、そのようなクライアントとの間の互換性問題を解決できます。</p>
    </section>

    <section id="gzip-only-text-html">
        <title>gzip-only-text/html</title>

        <p>これが 1 に設定されると、この変数は <code>text/html</code>
        以外のコンテントタイプに対する、<module>mod_deflate</module>
        提供の <code>DEFLATE</code> 出力フィルタを無効にします。
        また、静的に、既に圧縮されたファイルを使用したい場合、
        (gzip だけでなく、"identity" と異なる全てのエンコードに対して)
        <module>mod_negotiation</module> も変数を評価します。</p>
    </section>

    <section id="no-gzip"><title>no-gzip</title>
        <p>セットされると、<module>mod_deflate</module> の
        <code>DEFLATE</code> フィルタがオフになります。
        そして <module>mod_negotiation</module>
        はエンコードされたリソースを送らないようにします。</p>
    </section>

    <section id="nokeepalive">
        <title>nokeepalive</title>

        <p>これが設定されている場合は、<directive module="core"
        >KeepAlive</directive> を使用しないようにします。</p>

    <section id="prefer-language"><title>prefer-language</title>

        <p><module>mod_negotiation</module> の挙動に影響を与えます。
        (<code>en</code>, <code>ja</code>, <code>x-klingon</code>といった)
        言語タグが格納されていれば、その言語の variant を送信しようとします。
        そのような variant がない場合は、
        通常の<a href="content-negotiation.html">ネゴシエーション</a>処理が
        適用されます。</p>

    </section>

    </section>
    <section id="redirect-carefully">
        <title>redirect-carefully</title>

        <p>これはクライアントへのリダイレクトの送信をサーバがより注意深く
        行なうようにします。
        これは通常、リダイレクトに際してクライアントに
        問題があることが分かっている場合に使われます。この機能は元々は
        マイクロソフトのウェブフォルダのソフトが DAV
        メソッドによるディレクトリのリソースへのリダイレクトの扱いに
        問題がり、それを回避するために実装されました。</p>

    </section>

   <section id="suppress-error-charset">
       <title>suppress-error-charset</title>

    <p><em>Apache 2.2 以降で利用可能</em></p>

    <p>クライアントのリクエストに対する応答としてリダイレクトを送信する際、
    レスポンスにはリダイレクトが自動的に行なえない (行なわれない)
    場合に表示するテキストが含まれます。
    通常、このテキストに合致したキャラクタセット、ISO-8859-1
    でラベル付けをします。</p>
    <p>しかし、リダイレクト先が別の文字セットを使っている場合、
    ある問題のあるブラウザのバージョンでは、
    リダイレクト先の実際の文字セットの代わりに、
    リダイレクト元の文字セットを使ってしまうことがあります。
    その結果、例えば変な描画が行なわれたりして、読めなくなったりします。</p>
    <p>この環境変数を設定することで、リダイレクションテキストに対する
    キャラクタセットの指定を除去しますので、それら問題のあるブラウザでも
    リダイレクト先の文字セットを正しく使うようにできます。</p>

    <note type="warning">
      <title>セキュリティ</title> 

      <p>文字セットを指定せずにエラーページを送信すると、
      クロスサイトスクリプティング <transnote>XSS</transnote>
      攻撃の危険性がでてきます。
      HTTP/1.1 仕様に準拠していなくて、コンテンツの中身から文字セットを
      "推測" しようとするブラウザ (MSIE) が実際にあるからです。
      そのようなブラウザは UTF-7 文字セットを使って簡単に騙すことができます。
      クロスサイトスクリプティング攻撃を防ぐために実装されている
      通常のエスケープ機構が、入力データ中にある UTF-7 で
      エンコードされたコンテンツ (リクエスト URI など) には
      うまく動作しないからです。</p>
    </note>

   </section>

   <section id="proxy"><title>force-proxy-request-1.0, proxy-nokeepalive, proxy-sendchunked, proxy-sendcl</title>

   <p>これらの指示子は <module>mod_proxy</module> の挙動を変更します。
   詳細は <module>mod_proxy</module> のドキュメントをご参照ください。</p>
   </section>

  </section>

  <section id="examples">
    <title>例</title>

    <section id="misbehaving">
        <title>おかしな挙動をするクライアントに対してプロトコルの動作を変更する</title>

        <p>クライアントに関する既知の問題に対処するために、以下の行を
        httpd.conf に入れることを推奨しています。</p>
        <p>古いバージョンの Apache では、クライアントの問題に対応するために
        httpd.conf に次の行を加えるよう推奨されていましたが、
        今となっては、問題としていたクライアントは実際には見かけることは
        なくなってきたので、この設定はもはや必要ないかもしれません。</p>
<example><pre>
#
# The following directives modify normal HTTP response behavior.
# The first directive disables keepalive for Netscape 2.x and browsers that
# spoof it. There are known problems with these browser implementations.
# The second directive is for Microsoft Internet Explorer 4.0b2
# which has a broken HTTP/1.1 implementation and does not properly
# support keepalive when it is used on 301 or 302 (redirect) responses.
#
BrowserMatch "Mozilla/2" nokeepalive
BrowserMatch "MSIE 4\.0b2;" nokeepalive downgrade-1.0 force-response-1.0

#
# The following directive disables HTTP/1.1 responses to browsers which
# are in violation of the HTTP/1.0 spec by not being able to grok a
# basic 1.1 response.
#
BrowserMatch "RealPlayer 4\.0" force-response-1.0
BrowserMatch "Java/1\.0" force-response-1.0
BrowserMatch "JDK/1\.0" force-response-1.0</pre></example>

    </section>
    <section id="no-img-log">
        <title>画像へのリクエストをアクセスログに記録しない</title>

        <p>この例では、画像へのリクエストがアクセスログに現れないようにします。
        これを変更することで、特定のディレクトリのログ収集をやめたり、
        特定のホストからのリクエストのログ収集をやめたりすることが簡単にできます。
        </p>
    <example><pre>
SetEnvIf Request_URI \.gif image-request
SetEnvIf Request_URI \.jpg image-request
SetEnvIf Request_URI \.png image-request
CustomLog logs/access_log common env=!image-request</pre></example>

    </section>
    <section id="image-theft">
        <title>「画像の盗用」を防ぐ</title>

        <p>この例は、別のサーバにいる人が、あなたのサーバにある画像を
        inline 画像として使用することを防ぎます。
        これは推奨されている設定ではありませんが、ある限定された状況では有効です。
        ここでは、すべての画像は <code>/web/images</code>
        というディレクトリにあると仮定します。</p>
    <example><pre>
SetEnvIf Referer "^http://www\.example\.com/" local_referal
# Allow browsers that do not send Referer info
SetEnvIf Referer "^$" local_referal
&lt;Directory /web/images&gt;
   Order Deny,Allow
   Deny from all
   Allow from env=local_referal
&lt;/Directory&gt;</pre></example>

        <p>この手法に関する詳しい情報は ServerWatch にあるチュートリアル
        「<a href="http://www.serverwatch.com/tutorials/article.php/1132731"
        >Keeping Your Images from Adorning Other Sites</a>
        」を参照してください。</p>
    </section>
  </section>
</manualpage>