+ + + + +upstream + + +Specifies that a group should use a balancing method where requests +are distributed between servers based on client IP addresses. +A class C network containing the client IP address is used as a hashing key. +The method ensures that requests of the same client will always be +passed to the same server except when this server is considered down +in which case client requests will be passed to another server and +most probably it will also be the same server. + + + +It is not possible to specify a weight for servers using the +ip_hash balancing method. +If one of the servers needs to be temporarily removed, it should +be marked with the down parameter in +order to preserve the current hashing of client IP addresses. + + + +Example: + +upstream backend { + ip_hash; + + server backend1.example.com; + server backend2.example.com; + server backend3.example.com down; + server backend4.example.com; +} + + + + + + + +name [parameters] + +upstream + + +Sets a name and other parameters of the server. +A name can be a domain name, an address, a port, or a +path of the UNIX-domain socket. +If a domain name resolves to several addresses, all of them are used. + + +weight=number + +sets a weight of the server, by default 1. + + +max_fails=number + +sets a number of unsuccessful attempts to communicate with the server +during a time set by the fail_timeout parameter +after which it will be considered down for a period of time also set +by the fail_timeout parameter. +By default, the number of unsuccessful attempts is set to 1. +A value of zero disables accounting of attempts. +What is considered to be an unsuccessful attempt is configured by the + +and +directives. +The http_404 state is not considered +an unsuccessful attempt. + + +fail_timeout=time + +sets + + + +a time during which the specified number of unsuccessful attempts to +communicate with the server should happen for the server to be +considered down; + + + +and a period of time the server will be considered down. + + + +By default, timeout is set to 10 seconds. + + +backup + +marks the server as a backup server. +It will be passed requests when the primary servers are down. + + +down + +marks the server as permanently down; used along with +the directive. + + + + + + +Example: + +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:8080 backup; +} + + + + + + + +name + +http + + +Defines a group of servers. +Servers can listen on different ports. +In addition, servers listening on TCP and UNIX-domain sockets +can be used simultaneously. + + + +Example: + +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 between servers in a round-robin fashion, +taking into account the weights of servers. +In the above example, each 7 requests will be distributed as follows: +5 requests to backend1.example.com +and one request to each of second and third servers. +If an error occurs when communicating with the server, a request will +be passed to the next server, and so on until all of the functioning +servers will be tried. +If a successful response could not be obtained from any of the servers, +the client will be returned the result of contacting the last server. + + + + +

+ + +The ngx_http_upstream_module module +supports the following embedded variables: + + +$upstream_addr + +keeps an IP address and port of the server, +or a path to the UNIX-domain socket. +If several servers were contacted during request processing, +their addresses are separated by commas, e.g. +“192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock”. +If an internal redirect from one server group to another happened +using +

X-Accel-Redirect

or + +then these server groups are separated by colons, e.g. +“192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80”. + + +$upstream_response_time + +keeps servers response times in seconds with a milliseconds resolution. +Several responses are also separated by commas and colons. + + +$upstream_status + +keeps servers response codes. +Several responses are also separated by commas and colons. + + +$upstream_http_... + +keep server response header fields. +For example, the

Server

response header field +is made available through the $upstream_http_server variable. +Note that only the last server’s response header fields are saved. + + + + + +