<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ja.xsl"?>
<!-- English Revision: 1213141 -->

<!--
 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.
-->

<modulesynopsis metafile="mod_proxy_balancer.xml.meta">

<name>mod_proxy_balancer</name>
<description>負荷分散のための <module>mod_proxy</module> 拡張</description>
<status>Extension</status>
<sourcefile>mod_proxy_balancer.c</sourcefile>
<identifier>proxy_balancer_module</identifier>
<compatibility>Apache 2.1 以降で使用可能</compatibility>

<summary>
    <p>本モジュールには <module>mod_proxy</module> が<em>必要です</em>。
    本モジュールは <code>HTTP</code> と <code>FTP</code> と <code>AJP13</code>
    プロトコルのロードバランス機能を持っています。</p>

    <p>ですから、 ロードバランスを有効にする場合 <module>mod_proxy</module>
    と <module>mod_proxy_balancer</module> がサーバに組み込まれて
    いなければいけません。</p>

    <note type="warning"><title>警告</title>
      <p><a href="mod_proxy.html#access">
      安全なサーバにする</a>までプロキシ機能は有効にしないでください。
      オープンプロキシサーバはあなた自身のネットワークにとっても、
      インターネット全体にとっても危険です。</p>
    </note>
</summary>
<seealso><module>mod_proxy</module></seealso>

<section id="scheduler">
    <title>ロードバランサのスケジューラのアルゴリズム</title>
    <p>現時点では 3 種類のロードバランサスケジューラアルゴリズムから選べます。
    リクエスト回数によるもの <transnote>Request Counting</transnote>
    、トラフィック量によるもの <transnote>Weighted Traffic Counting</transnote>
    と、処理中リクエスト数によるもの <transnote>Pending Request Counting</transnote>
    とがあります。バランサの設定 <code>lbmethod</code> 値で、どれを使うか指定します。
    詳細は <directive module="mod_proxy">ProxyPass</directive> ディレクティブを
    参照してください。</p>
</section>

<section id="stickyness">
    <title>ロードバランサのスティッキネス</title>
    <p>バランサはスティッキネスをサポートします。リクエストがあるバックエンドに
    プロキシされた時、続く同じユーザからのリクエストは、すべてその同じバックエンドに
    プロキシされるべきです。多くのロードバランサはこの機能をクライアントの
    IP アドレスとバックエンドの対応表を持つことで実現します。
    この方法はクライアントにもバックエンドにも透過に動作しますが、
    次に挙げるいくつかの問題があります。
    もしクライアント自身がプロキシの背後にいる場合、負荷分散が不均一になります。
    もし動的な IP アドレスを持つクライアントのアドレスがセッション中に変わると
    スティッキネスは期待どおりに動作しません。
    もし対応表があふれると、スティッキネスが失われます。</p>
    <p><module>mod_proxy_balancer</module> はスティッキネスを
    2 種類の別手法をもとに実装しています。クッキーと URL エンコーディングのふたつです。
    クッキーはバックエンドもしくは Apache Web サーバ自身により提供されます。
    URL エンコーディングは通常バックエンドにより行われます。</p>
</section>

<section id="example">
    <title>ロードバランサの設定例</title>
    <p>技術的な詳細に入る前に例を示します。以下は、2 台のバックエンドサーバを
    ロードバランスするための <module>mod_proxy_balancer</module> の使い方の一例です:
    </p>

    <example>
    &lt;Proxy balancer://mycluster&gt;<br />
	BalancerMember http://192.168.1.50:80<br />
	BalancerMember http://192.168.1.51:80<br />
    &lt;/Proxy&gt;<br />
    ProxyPass /test balancer://mycluster
    </example>

    <p>別の例として、<module>mod_headers</module> を使ってスティッキネス
    を実現するロードバランサの設定例を示します。バックエンドのサーバが
    適切なセッションクッキーをセットしなくても動作します。
    </p>

    <example>
    Header add Set-Cookie "ROUTEID=.%{BALANCER_WORKER_ROUTE}e; path=/"
           env=BALANCER_ROUTE_CHANGED<br />
    &lt;Proxy balancer://mycluster&gt;<br />
    BalancerMember http://192.168.1.50:80 route=1<br />
    BalancerMember http://192.168.1.51:80 route=2<br />
    ProxySet stickysession=ROUTEID<br />
    &lt;/Proxy&gt;<br />
    ProxyPass /test balancer://mycluster
    </example>
</section>

<section id="requests">
    <title>Request Counting アルゴリズム</title>
    <p><code>lbmethod=byrequests</code> で有効になります。
    このスケジューラの背景にある考え方は、様々なワーカーがそれぞれ、
    設定されている分担リクエスト数をきちんと受け取れるように、
    リクエストを扱うという考え方です。次のように動作します:</p>

    <p><dfn>lbfactor</dfn> は、<em>どの程度ワーカーに仕事を振るか</em>
    つまり<em>ワーカーのクオータ</em>を指します。この値は "分担" 
    量を表す正規化された値です。</p>

    <p><dfn>lbstatus</dfn> は、<em>ワーカーのクオータを満たすために
    どのぐらい急ぎで働かなければならないか</em>を指します。</p>

    <p><dfn>ワーカー</dfn>はロードバランサのメンバで、通常は、
    サポートされるプロトコルのうちの一つを提供しているリモートホストです。
    </p>

    <p>まず個々のワーカーにワーカークオータを割り振り、どのワーカーが最も急ぎで
    働かなければならないか (lbstatus が最大のもの) を調べます。
    次に仕事をするようにこのワーカーを選択し、選択したワーカーの lbstatus 
    から全ワーカーに割り振ったクオータの合計を引きます。ですから、lbstatus の総量は
    結果的に変化しません(*)し、リクエストは期待通りに分散されます。</p>

    <p>あるワーカーが無効になっても、他のものは正常にスケジュールされ続けます。
    </p>

    <example><pre><code>for each worker in workers
    worker lbstatus += worker lbfactor
    total factor    += worker lbfactor
    if worker lbstatus > candidate lbstatus
        candidate = worker

candidate lbstatus -= total factor</code></pre>
    </example>

    <p>バランサを次のように設定した場合:</p>
    
    <table style="data">
    <tr><th>worker</th>
        <th>a</th>
        <th>b</th>
        <th>c</th>
        <th>d</th></tr>
    <tr><th>lbfactor</th>
        <td>25</td>
        <td>25</td>
        <td>25</td>
        <td>25</td></tr>
    <tr><th>lbstatus</th>
        <td>0</td>
        <td>0</td>
        <td>0</td>
        <td>0</td></tr>
    </table>

    <p>そして <var>b</var> が無効になった場合、次のようなスケジュールが
    行われます。</p>

    <table style="data">
    <tr><th>worker</th>
        <th>a</th>
        <th>b</th>
        <th>c</th>
        <th>d</th></tr>
    <tr><th>lbstatus</th>
        <td><em>-50</em></td>
        <td>0</td>
        <td>25</td>
        <td>25</td></tr>
    <tr><th>lbstatus</th>
        <td>-25</td>
        <td>0</td>
        <td><em>-25</em></td>
        <td>50</td></tr>
    <tr><th>lbstatus</th>
        <td>0</td>
        <td>0</td>
        <td>0</td>
        <td><em>0</em></td></tr>
    <tr><td colspan="5">(repeat)</td></tr>
    </table>

    <p>つまりこのようにスケジュールされます: <var>a</var> <var>c</var>
    <var>d</var> <var>a</var> <var>c</var> <var>d</var> <var>a</var>
    <var>c</var> <var>d</var> ... 次の点に注意してください:</p>

    <table style="data">
    <tr><th>worker</th>
        <th>a</th>
        <th>b</th>
        <th>c</th>
        <th>d</th></tr>
    <tr><th>lbfactor</th>
        <td>25</td>
        <td>25</td>
        <td>25</td>
        <td>25</td></tr>
    </table>

    <p>この挙動は、次の設定と全く同じになります:</p>

    <table style="data">
    <tr><th>worker</th>
        <th>a</th>
        <th>b</th>
        <th>c</th>
        <th>d</th></tr>
    <tr><th>lbfactor</th>
        <td>1</td>
        <td>1</td>
        <td>1</td>
        <td>1</td></tr>
    </table>

    <p>と言うのも、<dfn>lbfactor</dfn> の値は全て正規化されたもので、
    他との相対値だからです。次の設定では:</p>

    <table style="data">
    <tr><th>worker</th>
        <th>a</th>
        <th>b</th>
        <th>c</th></tr>
    <tr><th>lbfactor</th>
        <td>1</td>
        <td>4</td>
        <td>1</td></tr>
    </table>

    <p>ワーカー <var>b</var> は、平均して、<var>a</var> と <var>c</var>
    の 4 倍の数のリクエストを受け持つことになります。</p>

    <p>次のような非対称な設定では、こうなると予想されるでしょう:</p>

    <table style="data">
    <tr><th>worker</th>
        <th>a</th>
        <th>b</th></tr>
    <tr><th>lbfactor</th>
        <td>70</td>
        <td>30</td></tr>
    <tr><td colspan="2">&nbsp;</td></tr>
    <tr><th>lbstatus</th>
        <td><em>-30</em></td>
        <td>30</td></tr>
    <tr><th>lbstatus</th>
        <td>40</td>
        <td><em>-40</em></td></tr>
    <tr><th>lbstatus</th>
        <td><em>10</em></td>
        <td>-10</td></tr>
    <tr><th>lbstatus</th>
        <td><em>-20</em></td>
        <td>20</td></tr>
    <tr><th>lbstatus</th>
        <td><em>-50</em></td>
        <td>50</td></tr>
    <tr><th>lbstatus</th>
        <td>20</td>
        <td><em>-20</em></td></tr>
    <tr><th>lbstatus</th>
        <td><em>-10</em></td>
        <td>10</td></tr>
    <tr><th>lbstatus</th>
        <td><em>-40</em></td>
        <td>40</td></tr>
    <tr><th>lbstatus</th>
        <td>30</td>
        <td><em>-30</em></td></tr>
    <tr><th>lbstatus</th>
        <td><em>0</em></td>
        <td>0</td></tr>
    <tr><td colspan="3">(repeat)</td></tr>
    </table>

    <p>スケジュールは 10 スケジュール後に繰り返され、<var>a</var> 7 回と
    <var>b</var> 3 回でまばらに選ばれます。</p>
</section>

<section id="traffic">
    <title>Weighted Traffic Counting アルゴリズム</title>
    <p><code>lbmethod=bytraffic</code> で有効になります。
    このスケジューラの背景にある考え方は、Request Counting 
    と非常に似ていますが、次の違いがあります:</p>

    <p><dfn>lbfactor</dfn> は <em>どれだけのバイト数のトラフィック量を、
    このワーカーに処理してもらいたいか</em> を表します。
    この値も同様に正規化された値で、ワーカー全体のうちでの "分担"
    量を表現しています。リクエスト数を単純に数える代わりに、
    どれだけの転送量を処理したかを数えます。</p>

    <p>次のようにバランサを設定した場合:</p>
    
    <table style="data">
    <tr><th>worker</th>
        <th>a</th>
        <th>b</th>
        <th>c</th></tr>
    <tr><th>lbfactor</th>
        <td>1</td>
        <td>2</td>
        <td>1</td></tr>
    </table>

    <p><var>b</var> には <var>a</var> や <var>c</var> の 2 倍
    処理してほしいということになります。
    <var>b</var> は 2 倍の I/O を処理するという意味になり、
    2 倍のリクエスト数を処理するということにはなりません。
    ですからリクエストとレスポンスのサイズが、
    重み付けと振り分けのアルゴリズムに効いています。</p>

</section>

<section id="busyness">

    <title>Pending Request Counting アルゴリズム</title>

    <p><code>lbmethod=bybusyness</code> で有効になります。このスケジューラは
    現在どのぐらいのリクエストが個々のワーカーにアサインされているかを把握しています。
    新しいリクエストは、最も処理途中のリクエスト数が少ないワーカーに
    自動的に割り振られます。これは、ワーカーが Apache と無関係に入力リクエストを
    キューに溜め込む場合に有効で、キューの長さを同程度に維持しつつも、
    最も早く処理できそうなワーカーに常にリクエストを割り振ります。</p>

    <p>複数のワーカーが最少の処理中リクエスト数で並んだ場合、Request Counting
    アルゴリズムと同じ統計情報（と重み付け）を使って順番を決めます。
    時間が経つと、割り振りの割合は <code>byrequests</code> と似たような
    傾向を示すようになるでしょう。</p>

    <p>このアルゴリズムは Apache HTTP サーバ 2.2.10以降で利用可能です。</p>

</section>

<section id="environment">
    <title>エクスポートされる環境変数</title>
    <p>現在、6 つの環境変数がエクスポートされます:</p>

    <dl>
    <!-- ============= BALANCER_SESSION_STICKY =============== -->
    <dt><var><a name="balancer_session_sticky" id="balancer_session_sticky">BALANCER_SESSION_STICKY</a></var></dt>
    <dd>
    <p>現在のリクエストに使われる <var>stickysession</var> 値になります。
    スティッキーセッションのためのクッキー名もしくはリクエストパラメータ名です。</p>
    </dd>

    <!-- ============= BALANCER_SESSION_ROUTE ================ -->
    <dt><var><a name="balancer_session_route" id="balancer_session_route">BALANCER_SESSION_ROUTE</a></var></dt>
    <dd>
    <p>現在のリクエストをパースして得られる <var>route</var> 値です。</p>
    </dd>

    <!-- ============= BALANCER_NAME ========================= -->
    <dt><var><a name="balancer_name" id="balancer_name">BALANCER_NAME</a></var></dt>
    <dd>
    <p>現在のリクエストが使うバランサ名です。<code>balancer://foo</code>
    のような値です。</p>
    </dd>

    <!-- ============= BALANCER_WORKER_NAME ================== -->
    <dt><var><a name="balancer_worker_name" id="balancer_worker_name">BALANCER_WORKER_NAME</a></var></dt>
    <dd>
    <p>現在のリクエストが使うワーカー名です。<code>http://hostA:1234</code>
    のような値です。</p>
    </dd>

    <!-- ============= BALANCER_WORKER_ROUTE ================= -->
    <dt><var><a name="balancer_worker_route" id="balancer_worker_route">BALANCER_WORKER_ROUTE</a></var></dt>
    <dd>
    <p>現在のリクエストが使うワーカーの <var>route</var> 値です。</p>
    </dd>

    <!-- ============= BALANCER_ROUTE_CHANGED ================= -->
    <dt><var><a name="balancer_route_changed" id="balancer_route_changed">BALANCER_ROUTE_CHANGED</a></var></dt>
    <dd>
    <p>セッションルートとワーカールートが一致しない時 (BALANCER_SESSION_ROUTE != BALANCER_WORKER_ROUTE) 
    あるいは、セッションがまだルートを確立していない時、値が 1 になります。
    スティッキーセッションを使う時、ルートの更新をクライアントに送る必要があるかを
    判断するためにこの環境変数を使えます。</p>
    </dd>
    </dl>

</section>

<section id="balancer_manager">
    <title>バランサマネージャのサポートを有効にする</title>
    <p>このモジュールは <module>mod_status</module> のサービスを
    <em>必要とします</em>。
    バランサマネージャを使うと、バランサのメンバーの動的な更新が
    できます。バランサマネージャを使って、バランス係数 (lbfactor)
    を変更したり、メンバーを変更したり、特定のメンバーを
    オフラインモードにしたりできます。</p>

    <p>ですから、ロードバランサ管理機能を使いたければ、
    <module>mod_status</module> と <module>mod_proxy_balancer</module>
    をサーバに組み込まなければなりません。</p>

    <p>example.com ドメインのブラウザからロードバランサ管理機能を
    使えるようにするには、次のようなコードを <code>httpd.conf</code>
    に追加します。</p>
<example>
    &lt;Location /balancer-manager&gt;<br />
    SetHandler balancer-manager<br />
<br />
    Order Deny,Allow<br />
    Deny from all<br />
    Allow from .example.com<br />
    &lt;/Location&gt;
</example>

    <p>こうすると、<code>http://your.server.name/balancer-manager</code>
    のページ経由で、ウェブブラウザからロードバランサマネージャに
    アクセスできるようになります。</p>
</section>

<section id="stickyness_implementation">
    <title>ロードバランサのスティッキネスの詳細</title>
    <p>クッキーをもとにスティッキネスを使う場合、どのバックエンドに割り振るべきか
    を決めるクッキーの名前を指定する必要があります。
    クッキー名は <directive module="mod_proxy">ProxyPass</directive> または
    <directive module="mod_proxy">ProxySet</directive> のいずれか
    に付与する <var>stickysession</var> 属性で設定します。
    クッキー名は大文字小文字を区別します。
    バランサはそのクッキーの値を取り出し、その値に一致する <var>route</var> 値の
    ワーカーを探します。
    <var>route</var> も <directive module="mod_proxy">ProxyPass</directive>
    または <directive module="mod_proxy">ProxySet</directive>
    のいずれかに設定しなければいけません。
    クッキーはバックエンドによって設定されるか、あるいは
    上記の <a href="#example">例</a> のように Apache Web サーバ自身
    によって設定されます。</p>
    <p>バックエンドの中の一部は少し異なる形式のスティッキネスクッキーを使います。
    たとえば Apache Tomcat がそうです。Tomcat は自身のインスタンス名を
    セッション ID のクッキーの最後に付け加えます。この時、セッション ID
    との区切り文字にドット (<code>.</code>) を使います。
    このため、Apache Web サーバがドットをスティッキネスクッキー値の中に見つけると、
    route を探すためにドット以降の部分のみを使うようにします。
    Tomcat 側で自身のインスタンス名を設定するには、Tomcat の設定ファイル
    <code>conf/server.xml</code> の中の <code>jvmRoute</code> 属性に
    指定する必要があります。値はそれぞれの Tomcat に接続するワーカーの
    <var>route</var> 値と一致させます。
    Tomcat およびサーブレットベースの Java Web アプリサーバが一般に使う
    セッションクッキーの名前は <code>JSESSIONID</code> (すべて大文字) です。
    この名前は設定により変更も可能です。</p>
    <p>スティッキネスを実装するふたつめの手段は URL エンコーディングです。
    Web サーバはリクエストの URL の中からクエリパラメータを探します。
    探すパラメータ名は同じように <var>stickysession</var> 属性で指定します。
    パラメータ値と一致する <var>route</var> 値のワーカーを探します。
    レスポンスに含まれるすべての URL リンクを探しだし書き換えるのは簡単ではないので、
    一般にそれぞれのリンクにクエリパラメータを付け加えるのは、
    そのコンテンツを生成したバックエンドの仕事です。
    時には、<module>mod_substitute</module> を使って Web サーバにこの書き換えを
    させるのが可能な場合もあります。
    ただし、パフォーマンスを落とす可能性があります。</p>
    <p>Java 標準は URL エンコーディングを少し異なる形で実装します。
    URL のパス情報をセミコロン (<code>;</code>) で区切って
    セッション ID を付け加えます。
    クッキーの場合と同じように、 Apache Tomcat はこのパス情報に
    <code>jvmRoute</code> の設定値を含めます。
    Apache にこの種のパス情報を見つけさせるには、
    <directive module="mod_proxy">ProxyPass</directive> あるいは
    <directive module="mod_proxy">ProxySet</directive> の
    <code>scolonpathdelim</code> を <code>On</code> にします。</p>
    <p>最後に、クッキーと URL エンコーディングの両方が指定できることを示します。
    次の例のように、クッキー名と URL パラメータ名を垂直バー (<code>|</code>)
    で区切って指定します:</p>
    <example>
    ProxyPass /test balancer://mycluster stickysession=JSESSIONID|jsessionid scolonpathdelim=On
    &lt;Proxy balancer://mycluster&gt;<br />
    BalancerMember http://192.168.1.50:80 route=node1<br />
    BalancerMember http://192.168.1.51:80 route=node2<br />
    &lt;/Proxy&gt;<br />
    </example>
    <p>もし同じリクエストが、クッキーとリクエストパラメータの両方のルーティング情報を
    提供した場合、リクエストパラメータのほうが使われます。</p>
</section>

<section id="stickyness_troubleshooting">
    <title>ロードバランサのスティッキネスのトラブルシューティング</title>
    <p>もしアプリのセッションが失われてユーザが再ログインしなければいけないなど
    スティッキネス関連のエラーに遭遇したら、
    この原因はバックエンドの応答に支障があったせいか、
    あるいは設定ミスによるものかを最初に切り分けたいでしょう。
    バックエンドの安定性に関して起きうる問題を見つけるには、
    Apache のエラーログにプロキシエラーのメッセージがないか確認してください。</p>
    <p>設定が正しいかを確認するには、最初にスティッキネスを
    クッキーと URL エンコーディングのどちらで行っているかを確認してください。
    次に、<directive module="mod_log_config">LogFormat</directive> を変更して
    アクセスログに適切なデータが残るようにするとよいでしょう。
    次のフィールドが便利です:</p>
    <dl>
    <dt><code>%{MYCOOKIE}C</code></dt>
    <dd><code>MYCOOKIE</code> という名前のクッキーの値。
    この名前は <var>stickysession</var> 属性の指定値と同じはずです。</dd>
    <dt><code>%{Set-Cookie}o</code></dt>
    <dd>これによりバックエンドがセットするクッキーをログに出せます。
    バックエンドが期待するセッションクッキーをセットしているかと、
    どんな値がセットされているかを追跡できます。</dd>
    <dt><code>%{BALANCER_SESSION_STICKY}e</code></dt>
    <dd>ルーティング情報を決めるために使われたクッキー名もしくは
    リクエストパラメータ名。</dd>
    <dt><code>%{BALANCER_SESSION_ROUTE}e</code></dt>
    <dd>リクエスト内に見つかった route 値の情報</dd>
    <dt><code>%{BALANCER_WORKER_ROUTE}e</code></dt>
    <dd>選択されたワーカーの route 値</dd>
    <dt><code>%{BALANCER_ROUTE_CHANGED}e</code></dt>
    <dd>リクエストの route 値がワーカーの route 値と異なる場合に
    <code>1</code> になります。つまり、リクエストはスティッキーとして
    処理されていません。</dd>
    </dl>
    <p>セッションが失われる原因でよくあるものは、セッションタイムアウトですが、
    これは通常バックエンドのサーバで変更可能です。</p>
    <p>ログレベルを <code>debug</code> 以上に設定すると、
    バランサはスティッキネス動作の詳細な情報をエラーログに書き出します。
    これはスティッキネスの問題のトラブルシューティングする簡単な手法ですが、
    高負荷な本番サーバではログの分量が膨大になってしまうかもしれません。</p>
</section>
</modulesynopsis>
