FAQ

Page Discussion History

HttpUpstreamModuleJa

インストール | モジュール | アドオン | 設定 | コミュニティ | その他の情報源

Contents

概要

このモジュールは上位(バックエンド)サーバ間の単純なロードバランサ機能(ラウンドロビン、最小コネクション、クライアントIP)を提供します。

設定例:

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

ディレクティブ

ip_hash

Syntax: ip_hash
Default:
Context: upstream
Reference:ip_hash


This directive causes requests to be distributed between upstreams based on the IP-address of the client.
ハッシュのキーは、クラス C ネットワークアドレスか、クライアントの IPv6 アドレス全体です。IPv6 は 1.3.2 もしくは 1.2.2 以降の ip_hash でサポートされています。 This method guarantees that the client request will always be transferred to the same server. But if this server is considered inoperative, then the request of this client will be transferred to another server. This gives a high probability clients will always connect to the same server.

It is not possible to combine ip_hash and weight methods for connection distribution until nginx 1.3.1 or 1.2.2. If one of the servers must be removed for some time, you must mark that server as *down*.

For example:

upstream backend {
  ip_hash;
  server   backend1.example.com weight=2;
  server   backend2.example.com;
  server   backend3.example.com  down;
  server   backend4.example.com;
}

keepalive

Syntax: keepalive connections
Default:
Context: upstream
Appeared in: 1.1.4
Reference:keepalive


上位サーバに対するコネクションのキャッシュを有効にします。

connections パラメータは、ワーカプロセスごとに保持可能な、上位サーバに対するアイドル状態のキープアライブコネクションの最大数を設定します。この数を超過した場合は、最後に用いられたコネクションがクローズされます。

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 "";
        ...
    }
}

least_conn

Syntax: least_conn
Default:
Context: upstream
Appeared in: 1.3.1
1.2.2
Reference:least_conn


サーバのウェイトを考慮したうえで、アクティブなコネクション数が最小のサーバにリクエストを引き渡すようなロードバランス方式を用いるグループを指定します。該当するサーバが複数存在した場合は、ウェイトを加味したラウンドロビン方式が用いられます。

server

Syntax: server address [ parameters ]
Default:
Context: upstream
Reference:server


サーバの名前とパラメータを指定するディレクティブです。名前としては、ドメイン名、IPアドレス、ポート、UNIXドメインソケットを利用することができます。ドメイン名が複数のIPアドレスに解決される場合、すべてのアドレスが用いられます。

  • weight = NUMBER - weight を 1 以外に設定することで、サーバのウェイトを指定します。
  • max_fails = NUMBER - (fail_timeout で指定された) 時間内にサーバに対する通信の最大試行可能回数。この回数を超えた場合、サーバは停止状態として扱われます。設定されていない場合は 1 回として扱われます。0 を設定することでこのチェックを無効にできます。What is considered a failure is defined by proxy_next_upstream or fastcgi_next_upstream (except http_404 errors which do not count towards max_fails).
  • fail_timeout = TIME - the time during which must occur *max_fails* number of unsuccessful attempts at communication with the server that would cause the server to be considered inoperative, and also the time for which the server will be considered inoperative (before another attempt is made). 設定されていなかった場合は 10 秒になります。 fail_timeout は上位サーバからのレスポンス時間とは無関係です。これを制御したい場合は proxy_connect_timeout もしくは proxy_read_timeout を利用してください。
  • down - サーバが定常的に停止しているものとして扱います。ip_hash ディレクティブでも認識されます。
  • backup - (0.6.7 以降) backup 以外のサーバがすべて停止しているかビジーの時のみこのサーバを利用します (ip_hash ディレクティブで認識することはできません)。

設定例:

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

Attention: If you use only one upstream server nginx set a internal variable to 1, this means that the max_fails & fail_timeout parameter are not handled.

Effect: If nginx can not connect to upstream the request it's gone.

Solution: Use the same server several times

upstream

Syntax: upstream name { ... }
Default:
Context: http
Reference:upstream


This directive describes a set of servers, which can be used in directives proxy_pass and fastcgi_pass as a single entity. They can listen to server on different ports and furthermore, it is possible to simultaneously use a server that listens on both TCP and Unix sockets.

Servers can be assigned different weights. If not specified weight is equal to one.

Example configuration:

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

Requests are distributed according to the servers in round-robin manner with respect of the server weight.
例えば、7リクエストごとに、5リクエストは backend1.example.com に振り分けられ、2 つめと 3 つめのサーバには、各々 1 リクエストが割り当てられます。If with an attempt at the work with the server error occurred, then the request will be transmitted to the following server and then until all workers of server not are tested. If successful answer is not succeeded in obtaining from all servers, then to client will be returned the result of work with the last server.

変数

Since version 0.5.18, it is possible to log via log_module variables.

設定例:

log_format timing '$remote_addr - $remote_user [$time_local]  $request '
  'upstream_response_time $upstream_response_time '
  'msec $msec request_time $request_time';
 
log_format up_head '$remote_addr - $remote_user [$time_local]  $request '
  'upstream_http_content_type $upstream_http_content_type';

$upstream_addr

Address (ip:port or unix:socket-path) of the upstream server that handled the request. If multiple upstream addresses were accessed while processing the request, then the addresses are separated by a comma and space, for example: "192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock". If there was an internal redirect from one server group to another using the "X-Accel-Redirect" or error_page, these groups of servers are separated by a colon with a space on each side, for example: "192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80". Note the spaces: it's a good idea to enclose this in "" in a log format to make parsing easier.

$upstream_cache_status

Appeared in 0.8.3. Possible values:

  • MISS
  • EXPIRED - expired, request was passed to backend
  • UPDATING - expired, stale response was used due to proxy/fastcgi_cache_use_stale updating
  • STALE - expired, stale response was used due to proxy/fastcgi_cache_use_stale
  • HIT

$upstream_status

Upstream server status of the answer. As in $upstream_addr, if more than one upstream server is accessed, the values are separated by commas and colons with spaces.

$upstream_response_time

Response time of upstream server(s) in seconds, with an accuracy of milliseconds. As in $upstream_addr, if more than one upstream server is accessed, the values are separated by commas and colons with spaces.

$upstream_http_$HEADER

Arbitrary HTTP protocol headers, for example:

$upstream_http_host

Bear in mind that if more than one upstream server is accessed, only the header from the last one appears here.

References

Original Documentation