ngx_http_upstream_module モジュール

ngx_http_upstream_moduleモジュールは proxy_pass, fastcgi_pass, uwsgi_pass, scgi_passと memcached_pass ディレクティブによって参照されるサーバグループを定義するために使われます。

upstream backend {
    server backend1.example.com       weight=5;
    server backend2.example.com:8080;
    server unix:/tmp/backend3;

    server backup1.example.com:8080   backup;
    server backup2.example.com:8080   backup;
}

server {
    location / {
        proxy_pass http://backend;
    }
}

周期的なhealthチェック を持つ動的な構成可能なグループは商用許可の一部として利用可能です:

resolver 10.0.0.1;

upstream dynamic {
    zone upstream_dynamic 64k;

    server backend1.example.com      weight=5;
    server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
    server 192.0.2.1                 max_fails=3;
    server backend3.example.com      resolve;
    server backend4.example.com      service=http resolve;

    server backup1.example.com:8080  backup;
    server backup2.example.com:8080  backup;
}

server {
    location / {
        proxy_pass http://dynamic;
        health_check;
    }
}

サーバのグループを定義します。サーバは異なるポートでlistenすることができます。更に、サーバのlistenしているTCPとUNIXドメインソケットを混ぜることができます。

例:

upstream backend {
    server backend1.example.com weight=5;
    server 127.0.0.1:8080       max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend3;

    server backup1.example.com  backup;
}

デフォルトでは、重み付けのラウンドロビン バランシング メソッドを使ってリクエストはサーバの間にばらまかされます。上の例では、7つのリクエストが以下のように分配されるでしょう: 5つのリクエストは backend1.example.comへ、2つめと3つめのサーバへ1つのリクエスト。サーバとの通信時にエラーが起きた場合、リクエストは次のサーバへ送られます。全ての機能しているサーバが試されるまでこれが行われます。どのサーバからも成功の応答を受け取ることができなかった場合、クライアントは最後のサーバとの通信の結果を受け取るでしょう。.

サーバのaddressとその他の parameters を定義します。アドレスはドメイン名またはIPアドレス、オプションとしてポート番号、あるいは"unix:"プリフィックスの後で指定されるUNIXドメインソケットで指定されます。ポートが指定されない場合はポート80が使われます。複数のIPアドレスに解決されるドメイン名は一度に複数のサーバを定義します。

次のパラメータを定義することができます:

weight=number

サーバの重み付けを設定します。デフォルトは1。

max_conns=number

プロキシされたサーバへの同時のアクティブな接続の最大数を制限します(1.11.5)。デフォルトの値は0です。制限が無いことを意味します。サーバグループが 共有メモリ内に無い場合は、その制限は各ワーカープロセスごとに動作します。

idle keepalive 接続、複数のworkers および 共有メモリ が有効な場合、プロキシされたサーバへのアクティブおよびアイドルの接続の総数はmax_conns 値を超えるかも知れません。

バージョン 1.5.9からと 1.11.5以前では、このパラメータは商用許可の一部として利用可能でした。

max_fails=number

fail_timeout パラメータによって設定された期間中にサーバが利用できないと見なすためのfail_timeoutパラメータによって設定された期間に起こるはずのサーバとの通信で失敗する試行の回数を設定します。デフォルトでは、不成功の数は1に設定されます。0の値は試行のカウントを無効にします。何を不成功と見なすかは、proxy_next_upstream, fastcgi_next_upstream, uwsgi_next_upstream, scgi_next_upstream と memcached_next_upstream ディレクティブで定義されます。

fail_timeout=time

sets

• サーバが利用不可能だと見なされるために必要な、指定回数のサーバとの通信の失敗の試行が起こる期間
• その間サーバは利用不可能とみなされるでしょう。

デフォルトでは、パラメータは10秒に設定されます。

バックアップ

サーバをバックアップサーバとして印をつけます。プライマリサーバが利用不可の時に、リクエストが渡されます。

down

サーバを永久に利用できないとして印を付けます。

更に、次のパラメータが商用許可の一部として利用可能です:

resolve

ドメイン名に対応するIPアドレスの変更を監視し、nginxの再起動の必要無しにupstream設定の変更を自動的に行います(1.5.12)サーバグループは共有メモリにある必要があります。

このパラメータが動作するには、httpブロックのresolverディレクティブが指定されていなければなりません。例:

http {
    resolver 10.0.0.1;

    upstream u {
        zone ...;
        ...
        server example.com resolve;
    }
}

route=string

サーバのルート名を設定します。

service=name

DNS のSRV レコードの解決を有効にし、サービス nameを設定します (1.9.13)。このパラメータが動作するには、サーバのresolve パラメータを指定し、ポート番号無しのホスト名を指定する必要があります。

サービス名がドット (“.”)を含まない場合、RFC準拠名が作られ、TCPプロトコルがサービスの後に追加されます。例えば、_http._tcp.backend.example.com SRV レコードを調べるには、ディレクティブを指定する必要があります。

server backend.example.com service=http resolve;

サービス名が1つ以上のドットを含む場合、サービスのプリフィックスとサーバー名を結合することで名前が作られます。例えば、_http._tcp.backend.example.com とserver1.backend.example.com SRV レコードを調べるには、以下のディレクティブを指定する必要があります:

server backend.example.com service=_http._tcp resolve;
server example.com service=server1.backend resolve;

最優先 SRV レコード (同じ最小の優先度値のレコード)はプライマリサーバとして解決され、残りのSRVレコードはバックアップサーバとして解決されます。サーバにbackup パラメータが指定された場合は、最優先SRVレコードはバックアップサーバとして解決され、残りのSRVレコードは無視されます。

slow_start=time

健康では無いサーバがhealthyになる時、またはサーバがunavailableと見なされてから一定期間後に利用可能となる時に、サーバの重み付けが0から通常の値になるまでの時間。デフォルト値は0です。つまりslowスタートは無効です。

パラメータはhash および ip_hash ロードバランシング メソッドと一緒に使うことはできません。

グループにサーバが一つだけの場合、max_fails, fail_timeout と slow_startパラメータは無視され、そのようなサーバは利用不可だとは見なされないでしょう。

グループの設定とworkerプロセス間で共有されるランタイムステートを保持する共有メモリ領域のnameと size を定義します。幾つかのグループは同じゾーンを共有するかも知れません。この場合、sizeの指定は一度だけで十分です。

さらに、商用サブスクリプションの一部として、そのようなグループは、グループのメンバーの変更または特定のサーバの設定の変更をnginxの再起動無しに行うことができます。設定は、upstream_confによって処理される特別なlocationを使ってアクセスが可能です。

動的に設定可能なグループの状態を保持する ファイル を指定します。

例:

state /var/lib/nginx/state/servers.conf; # path for Linux
state /var/db/nginx/state/servers.conf;  # path for FreeBSD

状態は現在のところサーバのパラメータとサーバのリストに制限されています。そのファイルは、設定をパースする時と、upstreamの設定が変更される度に更新されます。ファイルの内容を直接変更することは避けなければなりません。ディレクティブは server ディレクティブと一緒に使うことはできません。

configuration reload あるいはbinary upgrade の間の変更は失われるかも知れません。

このディレクティブは商用許可の一部として利用可能です。

クライアント-サーバのマッピングがハッシュ化されたkey 値に基づいているサーバグループのためのロードバランス設定を指定します。keyにはテキスト、変数、それらの組み合わせを含めることができます。グループからサーバを追加または削除することは、ほとんどのキーを異なるサーバに再マッピングすることになることに注意してください。メソッドはCache::MemcachedPerlライブラリと互換性があります。

consistentパラメータはketama consistent ハッシュメソッドが代わりに使われることを指定します。このメソッドはグループからサーバを追加または削除する時に、ほんの少しのキーだけが異なるサーバに再マップされることを保証します。これにより、キャッシュサーバのキャッシュヒットレシオの高さを達成できることができます。このメソッドはketama_points パラメータを160に設定したCache::Memcached::Fast Perl ライブラリと互換性があります。

クライアントIPアドレスに基づいてサーバ間でリクエストが分散されるロードバランスメソッドをグループが使うことを指定します。IPv4アドレスのクライアントの最初の3オクテット、またはIPv6アドレスの全体が、ハッシュキーとして使われます。このメソッドは同じクライアントからのリクエストはサーバが利用不可の場合を除いて常に同じサーバに渡されることを保証します。利用不可の場合、クライアントは他のサーバに渡されるでしょう。ほとんどの場合において、常に同じサーバになるでしょう。

バージョン1.3.2と1.2.2からIPv6アドレスがサポートされています。

サーバの一つを一時的に取り外す必要がある場合は、現在のクライアントIPアドレスのハッシュを保持するために down パラメータで印をつける必要があります。

例:

upstream backend {
    ip_hash;

    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com down;
    server backend4.example.com;
}

バージョン1.3.1と1.2.2まで、ip_hash ロードバランスメソッドを使ってサーバに重み付けを指定することができませんでした。

upstreamサーバへの接続のキャッシュを起動します。

connections パラメータは、それぞれのworkerプロセスのキャシュに保存されるupstreamサーバへのkeepalive接続のidleの最大数を設定します。この数を越えると、最も使われていない接続から削除されます。

keepalive ディレクティブはnginx workerプロセスが開くことができるupstreamサーバへの総接続数を制限するものでは無いことに、特に注意する必要があります。connections パラメータはupstreamサーバが新しくやってくる接続を処理できるような十分に小さな数を設定しなければなりません。

keepalive接続を使ったmemcachedのupstreamの設定例:

upstream memcached_backend {
    server 127.0.0.1:11211;
    server 10.0.0.2:11211;

    keepalive 32;
}

server {
    ...

    location /memcached/ {
        set $memcached_key $uri;
        memcached_pass memcached_backend;
    }

}

HTTPでは、proxy_http_version ディレクティブは"1.1"に設定され、"Connection"ヘッダフィールドは消去されなければなりません:

upstream http_backend {
    server 127.0.0.1:8080;

    keepalive 16;
}

server {
    ...

    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        ...
    }
}

もう一つの方法として、"Connection: Keep-Alive"ヘッダフィールドをupstreamサーバに渡すことでHTTP/1.0 persistent接続を使うことができますが、この方法はお勧めできません。

FastCGIでは、keepalive接続を動作させるためにfastcgi_keep_conn を設定する必要があります:

upstream fastcgi_backend {
    server 127.0.0.1:9000;

    keepalive 8;
}

server {
    ...

    location /fastcgi/ {
        fastcgi_pass fastcgi_backend;
        fastcgi_keep_conn on;
        ...
    }
}

デフォルトのラウンドロビンメソッド以外のロードバランスメソッドを使う場合は、keepalive ディレクティブの前にそれらを動かす必要があります。

SCGI と uwsgi プロトコルにはkeepalive接続の概念はありません。

NTLM 認証を使ったリクエストのプロキシを許可します。一度クライアントが"Negotiate" あるいは "NTLM"で始まる"Authorization"ヘッダフィールドを伴うリクエストが送信すると、upstream接続はそのクライアント接続に拘束されます。以降のクライアントリクエストは認証内容を保持しつつ同じupstream接続を使ってプロキシされるでしょう。

NTLM authentication が動作するには、upstreamサーバへのkeepalive接続が有効である必要があります。 proxy_http_version ディレクティブが "1.1" に設定され、"Connection"ヘッダフィールドが取り除かれていなければなりません。

upstream http_backend {
    server 127.0.0.1:8080;

    ntlm;
}

server {
    ...

    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        ...
    }
}

デフォルトのラウンドロビンメソッド以外のロードバランサメソッドが使われる場合は、ntlm ディレクティブの前にそれらが有効にされていなければなりません。

このディレクティブは商用許可の一部として利用可能です。

リクエストがサーバの重み付けを考慮してもっともアクティブな接続の数が少ないサーバに渡されるロードバランスメソッドをグループが使うように指定します。そのようなサーバがいくつかある場合は、重み付けのラウンドロビンバランスメソッドを使って順番に試されます。

リクエストがサーバの重み付けを考慮して最も平均応答タイムが小さく最もアクティブな接続の数が少ないサーバに渡されるロードバランスメソッドをグループが使うように指定します。そのようなサーバがいくつかある場合は、重み付けのラウンドロビンバランスメソッドを使って順番に試されます。

headerパラメータが指定された場合は、応答ヘッダを受け取る時間が使われます。last_byte パラメータが指定された倍亜は、full responseを受け取る時間が使われます。inflight パラメータが指定された場合 (1.11.6)、不完全なリクエストも考慮に入れられます。

バージョン 1.11.6より前では、不完全なリクエストはデフォルトで考慮に入れられていました。

このディレクティブは商用許可の一部として利用可能です。

リクエストの処理中にupstreamサーバがすぐに選択できない場合は、リクエストはキューに置かれるでしょう。そのディレクティブはキューに同時に入れることができるリクエストの最大数を指定します。キューがいっぱい、あるいは timeout パラメータで指定される時間内にリクエストを渡すサーバが選択できなかった場合は、502 (Bad Gateway)エラーがクライアントに返されるでしょう。

timeout パラメータのデフォルトの値は60 秒です。

デフォルトのラウンドロビンメソッド以外のロードバランサメソッドが使われる場合は、queue ディレクティブの前にそれらが有効にされていなければなりません。

このディレクティブは商用許可の一部として利用可能です。

セッションの相性、同じクライアントからサーバグループ内の同じサーバにリクエストが渡されるようになる、を有効にします。3つのメソッドが利用可能です:

cookie

cookieメソッドが使われた場合、指定されたサーバに関する情報はnginxで生成されたHTTPクッキーの中で渡されます:

upstream backend {
    server backend1.example.com;
    server backend2.example.com;

    sticky cookie srv_id expires=1h domain=.example.com path=/;
}

まだ特定のサーバに紐付けされていないクライアントから来たリクエストは、設定されたバランサメソッドによって選択されたサーバに渡されます。このクッキーのそれ以上のリクエストは、指定されたサーバに渡されます。指定されたサーバがリクエストを処理できない場合は、クライアントがまだ紐付けされていないかのように新しいサーバが選択されます。

最初のパラメータは、設定あるいは検査されるクッキーの名前を設定します。追加のパラメータは以下のようになります:

expires=time

ブラウザがクッキーを保持しなければならない時間を設定します。特別な値max は、クッキーが"31 Dec 2037 23:55:55 GMT"に期限が切れるようにするでしょう。パラメータが指定されていない場合は、クッキーがブラウザのセッションの終わりに期限が切れるようにするでしょう。

domain=domain

クッキーが設定された ドメイン を定義します。パラメータ値は変数を含むことができます (1.11.5)。

httponly

クッキーにHttpOnly 属性を追加します (1.7.11)。

secure

クッキーに Secure 属性を追加します(1.7.11)。

path=path

クッキーが設定されたpath を定義します。

いずれかのパラメータも省略されると、対応するクッキーのフィールドは設定されません。

route

routeメソッドが使われた場合、プロキシされたサーバはクライアントの最初のリクエストの受領書にルートを割り当てます。このクライアントからの連続するリクエストはクッキーまたはURIの中にルーティング情報を入れて運びます。この情報は、リクエストがどのサーバにプロキシされるかを決定するためにserverディレクティブの"route"パラメータと比較されます。"route" パラメータが指定されない場合は、ルート名はIPアドレスとポートのMD5ハッシュ、あるいはUNIXドメインソケットのパスの16進表現でしょう。指定されたサーバがリクエストを処理できない場合は、リクエストにルーティング情報が無いかのように、新しいサーバが指定されたバランシングメソッドによって選択されます。

routeメソッドのパラメータはルーティング情報を含むかも知れない変数を指定します。最初の空では無い変数は、一致するサーバを見つけるために使われます。

例:

map $cookie_jsessionid $route_cookie {
    ~.+\.(?P<route>\w+)$ $route;
}

map $request_uri $route_uri {
    ~jsessionid=.+\.(?P<route>\w+)$ $route;
}

upstream backend {
    server backend1.example.com route=a;
    server backend2.example.com route=b;

    sticky route $route_cookie $route_uri;
}

ここで、ルートはリクエストに"JSESSIONID"クッキーが存在する場合に、そこから取り出されます。もしなければ、URIから取り出されたルートが使われます。

learn

learnメソッド(1.7.1)が使われた場合、nginxはupstreamサーバの応答を解析し、通常HTTPクッキーで渡されるserver-initiatedセッションを記憶します:

upstream backend {
   server backend1.example.com:8080;
   server backend2.example.com:8081;

   sticky learn
          create=$upstream_cookie_examplecookie
          lookup=$cookie_examplecookie
          zone=client_sessions:1m;
}

例では、upstreamサーバは応答の中で"EXAMPLECOOKIE"を設定することでセッションを生成します。このクッキーのそれ以上のリクエストは、同じサーバに渡されます。指定されたサーバがリクエストを処理できない場合は、クライアントがまだ紐付けされていないかのように新しいサーバが選択されます。

パラメータcreate と lookup は、それぞれ新しいセッションがどうやって作成されるか、既存のセッションがどうやって検索されるかを指示します。両方のパラメータが一度以上指定されるかも知れません。その場合は、最初の空では無い変数が使われます。

セッションは共有メモリゾーンに格納され、その 名前 と サイズ は zone パラメータによって設定されます。1メガバイトのゾーンは64ビットプラットフォームで約8000セッションを保持することができます。timeout パラメータによって指定される時間の間アクセスされなかったセッションは、ゾーンから削除されます。デフォルトでは、timeout は10分に設定されます。

このディレクティブは商用許可の一部として利用可能です。

このディレクティブはバージョン1.5.7から廃止されました。新しい構文を持つ等価な sticky ディレクティブが代わりに使われるべきです:

sticky cookie name [expires=time] [domain=domain] [path=path];

ngx_http_upstream_moduleモジュールは以下の埋め込み変数をサポートします:

$upstream_addr

upstreamサーバのIPアドレスとポート、あるいはUNIXドメインソケットのパスを保持します。いくつかのサーバがリクエストの処理中に接点を持つ場合は、それらのアドレスがカンマで区切られます。例えば、"192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock"。一つのグループから他のグループへ、"X-Accel-Redirect"または error_pageによる内部りダイレクトが起きた場合、異なるグループからのサーバのアドレスがコロンで区切られます。例えば、"192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80"。

$upstream_bytes_received

upstreamサーバから受け取ったバイト数 (1.11.4)。複数の接続の値は、$upstream_addr 変数のアドレスと同じようにカンマとコロンで区切られます。

$upstream_cache_status

応答キャッシュへのアクセス状況を保持します(0.8.3)。ステータスは “MISS”, “BYPASS”, “EXPIRED”, “STALE”, “UPDATING”, “REVALIDATED” あるいは “HIT”のいずれかかです。

$upstream_connect_time

upstreamサーバと接続を確立するまでの時間を保持します(1.9.1); 時間はミリ秒の精度の秒数で保持されます。SSLの場合は、ハンドシェイクの時間を含みます。複数の接続時間は$upstream_addr 変数のアドレスと同じようにカンマとコロンで区切られます。

$upstream_cookie_name

"Set-Cookie"応答ヘッダフィールドの中のupstreamサーバによって送信された指定されたnameのクッキー(1.7.1)。最後のサーバの応答からのクッキーのみ保存されます。

$upstream_header_time

upstreamサーバから応答ヘッダを受け取るまでの時間を保持します(1.7.10); 時間はミリ秒の精度の秒数で保持されます。複数の応答時間は$upstream_addr 変数のアドレスと同じようにカンマとコロンで区切られます。

$upstream_http_name

サーバの応答ヘッダフィールドを保持します。例えば、$upstream_http_server変数を使って"Server"応答ヘッダフィールドを利用できます。ヘッダフィールド名と変数名との変換ルールは、"$http_"プリフィックスから始まる変数と同じです。最後のサーバの応答からのヘッダフィールドのみが保存されます。

$upstream_response_length

upstreamサーバから取得した応答の長さを保持します(0.7.27); 長さはバイトで保持されます。複数の応答時間は$upstream_addr 変数のアドレスと同じようにカンマとコロンで区切られます。

$upstream_response_time

upstreamサーバから応答ヘッダを受け取るまでの時間を保持します; 時間はミリ秒の精度の秒数で保持されます。複数の応答時間は$upstream_addr 変数のアドレスと同じようにカンマとコロンで区切られます。

$upstream_status

upstreamサーバから取得したステータスコードを保持します。複数のステータスコードは$upstream_addr 変数のアドレスと同じようにカンマとコロンで区切られます。