Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 966:95c3c3bbf1ce

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Text review.
author Egor Nikitin <yegor.nikitin@gmail.com>
date Wed, 14 Aug 2013 12:03:41 +0400
parents f3754c623e6b
children fa19bacf6e1e
comparison
equal deleted inserted replaced
965:fadccc156188 966:95c3c3bbf1ce
14 14
15 <section id="summary"> 15 <section id="summary">
16 16
17 <para> 17 <para>
18 The <literal>ngx_http_upstream_module</literal> module 18 The <literal>ngx_http_upstream_module</literal> module
19 allows to define groups of servers that can be referenced 19 is used to define groups of servers that can be referenced
20 from the <link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>, 20 by the <link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>,
21 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>, and 21 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>, and
22 <link doc="ngx_http_memcached_module.xml" id="memcached_pass"/> directives. 22 <link doc="ngx_http_memcached_module.xml" id="memcached_pass"/> directives.
23 </para> 23 </para>
24 24
25 </section> 25 </section>
103 } 103 }
104 </example> 104 </example>
105 </para> 105 </para>
106 106
107 <para> 107 <para>
108 By default, requests are distributed between servers using a 108 By default, requests are distributed between the servers using a
109 weighted round-robin balancing method. 109 weighted round-robin balancing method.
110 In the above example, each 7 requests will be distributed as follows: 110 In the above example, each 7 requests will be distributed as follows:
111 5 requests to <literal>backend1.example.com</literal> 111 5 requests go to <literal>backend1.example.com</literal>
112 and one request to each of second and third servers. 112 and one request to each of the second and third servers.
113 If an error occurs when communicating with the server, a request will 113 If an error occurs during communication with a server, the request will
114 be passed to the next server, and so on until all of the functioning 114 be passed to the next server, and so on until all of the functioning
115 servers will be tried. 115 servers will be tried.
116 If a successful response could not be obtained from any of the servers, 116 If a successful response could not be obtained from any of the servers,
117 the client will be returned the result of contacting the last server. 117 the client will receive the result of the communication with the last server.
118 </para> 118 </para>
119 119
120 </directive> 120 </directive>
121 121
122 122
124 <syntax><value>address</value> [<value>parameters</value>]</syntax> 124 <syntax><value>address</value> [<value>parameters</value>]</syntax>
125 <default/> 125 <default/>
126 <context>upstream</context> 126 <context>upstream</context>
127 127
128 <para> 128 <para>
129 Defines an <value>address</value> and other <value>parameters</value> 129 Defines the <value>address</value> and other <value>parameters</value>
130 of the server. 130 of a server.
131 An address can be specified as a domain name or IP address, 131 The address can be specified as a domain name or IP address,
132 and an optional port, or as a UNIX-domain socket path 132 with an optional port, or as a UNIX-domain socket path
133 specified after the “<literal>unix:</literal>” prefix. 133 specified after the “<literal>unix:</literal>” prefix.
134 If port is not specified, the port 80 is used. 134 If a port is not specified, the port 80 is used.
135 A domain name that resolves to several IP addresses essentially defines 135 A domain name that resolves to several IP addresses defines
136 multiple servers. 136 multiple servers at once.
137 </para> 137 </para>
138 138
139 <para> 139 <para>
140 The following parameters can be defined: 140 The following parameters can be defined:
141 <list type="tag"> 141 <list type="tag">
142 142
143 <tag-name><literal>weight</literal>=<value>number</value></tag-name> 143 <tag-name><literal>weight</literal>=<value>number</value></tag-name>
144 <tag-desc> 144 <tag-desc>
145 sets a weight of the server, by default 1. 145 sets the weight of the server, by default, 1.
146 </tag-desc> 146 </tag-desc>
147 147
148 <tag-name><literal>max_fails</literal>=<value>number</value></tag-name> 148 <tag-name><literal>max_fails</literal>=<value>number</value></tag-name>
149 <tag-desc> 149 <tag-desc>
150 sets a number of unsuccessful attempts to communicate with the server 150 sets the number of unsuccessful attempts to communicate with the server
151 during a time set by the <literal>fail_timeout</literal> parameter 151 that should happen in the duration set by the <literal>fail_timeout</literal>
152 after which it will be considered down for a period of time also set 152 parameter to consider the server down for a duration also set by the
153 by the <literal>fail_timeout</literal> parameter. 153 <literal>fail_timeout</literal> parameter.
154 By default, the number of unsuccessful attempts is set to 1. 154 By default, the number of unsuccessful attempts is set to 1.
155 A value of zero disables accounting of attempts. 155 The zero value disables the accounting of attempts.
156 What is considered an unsuccessful attempt is defined by the 156 What is considered an unsuccessful attempt is defined by the
157 <link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>, 157 <link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>,
158 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>, and 158 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>, and
159 <link doc="ngx_http_memcached_module.xml" id="memcached_next_upstream"/> 159 <link doc="ngx_http_memcached_module.xml" id="memcached_next_upstream"/>
160 directives. 160 directives.
164 <tag-desc> 164 <tag-desc>
165 sets 165 sets
166 <list type="bullet"> 166 <list type="bullet">
167 167
168 <listitem> 168 <listitem>
169 a time during which the specified number of unsuccessful attempts to 169 the time during which the specified number of unsuccessful attempts to
170 communicate with the server should happen for the server to be 170 communicate with the server should happen to consider the server down;
171 considered down;
172 </listitem> 171 </listitem>
173 172
174 <listitem> 173 <listitem>
175 and a period of time the server will be considered down. 174 and the period of time the server will be considered down.
176 </listitem> 175 </listitem>
177 176
178 </list> 177 </list>
179 By default, timeout is set to 10 seconds. 178 By default, the parameter is set to 10 seconds.
180 </tag-desc> 179 </tag-desc>
181 180
182 <tag-name><literal>slow_start</literal>=<value>time</value></tag-name> 181 <tag-name><literal>slow_start</literal>=<value>time</value></tag-name>
183 <tag-desc> 182 <tag-desc>
184 sets the <value>time</value> during which the server will recover its weight 183 sets the <value>time</value> during which the server will recover its weight
255 <para> 254 <para>
256 Specifies that a group should use a load balancing method where requests 255 Specifies that a group should use a load balancing method where requests
257 are distributed between servers based on client IP addresses. 256 are distributed between servers based on client IP addresses.
258 The first three octets of the client IPv4 address, or the entire IPv6 address, 257 The first three octets of the client IPv4 address, or the entire IPv6 address,
259 are used as a hashing key. 258 are used as a hashing key.
260 The method ensures that requests of the same client will always be 259 The method ensures that requests from the same client will always be
261 passed to the same server except when this server is considered down 260 passed to the same server except when this server is considered down.
262 in which case client requests will be passed to another server and 261 In the latter case client requests will be passed to another server.
263 most probably it will also be the same server. 262 Most probably, it will always be the same server as well.
264 <note> 263 <note>
265 IPv6 addresses are supported starting from versions 1.3.2 and 1.2.2. 264 IPv6 addresses are supported starting from versions 1.3.2 and 1.2.2.
266 </note> 265 </note>
267 </para> 266 </para>
268 267
286 </example> 285 </example>
287 </para> 286 </para>
288 287
289 <para> 288 <para>
290 <note> 289 <note>
291 Until versions 1.3.1 and 1.2.2 it was not possible to specify a weight for 290 Until versions 1.3.1 and 1.2.2, it was not possible to specify a weight for
292 servers using the <literal>ip_hash</literal> load balancing method. 291 servers using the <literal>ip_hash</literal> load balancing method.
293 </note> 292 </note>
294 </para> 293 </para>
295 294
296 </directive> 295 </directive>
301 <default/> 300 <default/>
302 <context>upstream</context> 301 <context>upstream</context>
303 <appeared-in>1.1.4</appeared-in> 302 <appeared-in>1.1.4</appeared-in>
304 303
305 <para> 304 <para>
306 Activates cache of connections to upstream servers. 305 Activates the cache for connections to upstream servers.
307 </para> 306 </para>
308 307
309 <para> 308 <para>
310 The <value>connections</value> parameter sets the maximum number of 309 The <value>connections</value> parameter sets the maximum number of
311 idle keepalive connections to upstream servers that are retained in 310 idle keepalive connections to upstream servers that are preserved in
312 the cache per one worker process. 311 the cache of each worker process.
313 When this number is exceeded, the least recently used connections 312 When this number is exceeded, the least recently used connections
314 are closed. 313 are closed.
315 <note> 314 <note>
316 It should be particularly noted that <literal>keepalive</literal> directive 315 It should be particularly noted that the <literal>keepalive</literal> directive
317 does not limit the total number of connections that nginx worker process 316 does not limit the total number of connections to upstream servers
318 can open to upstream servers. 317 that an nginx worker process can open.
319 The <value>connections</value> parameter should be set low enough 318 The <value>connections</value> parameter should be set to a number small enough
320 to allow upstream servers to process additional new incoming 319 to let upstream servers process new incoming connections as well.
321 connections as well.
322 </note> 320 </note>
323 </para> 321 </para>
324 322
325 <para> 323 <para>
326 Example configuration of memcached upstream with keepalive connections: 324 Example configuration of memcached upstream with keepalive connections:
370 368
371 <para> 369 <para>
372 <note> 370 <note>
373 Alternatively, HTTP/1.0 persistent connections can be used by passing the 371 Alternatively, HTTP/1.0 persistent connections can be used by passing the
374 <header>Connection: Keep-Alive</header> header field to an upstream server, 372 <header>Connection: Keep-Alive</header> header field to an upstream server,
375 though this is not recommended. 373 though this method is not recommended.
376 </note> 374 </note>
377 </para> 375 </para>
378 376
379 <para> 377 <para>
380 For FastCGI servers, it is required to set 378 For FastCGI servers, it is required to set
400 </para> 398 </para>
401 399
402 <para> 400 <para>
403 <note> 401 <note>
404 When using load balancer methods other than the default 402 When using load balancer methods other than the default
405 round-robin, it is necessary to activate them before 403 round-robin method, it is necessary to activate them before
406 the <literal>keepalive</literal> directive. 404 the <literal>keepalive</literal> directive.
407 </note> 405 </note>
408 406
409 <note> 407 <note>
410 SCGI and uwsgi protocols do not have a notion of keepalive connections. 408 SCGI and uwsgi protocols do not have a notion of keepalive connections.
581 579
582 <tag-name><literal>status ! 301 302;</literal></tag-name> 580 <tag-name><literal>status ! 301 302;</literal></tag-name>
583 <tag-desc>status is neither 301 nor 302</tag-desc> 581 <tag-desc>status is neither 301 nor 302</tag-desc>
584 582
585 <tag-name><literal>status 200-399;</literal></tag-name> 583 <tag-name><literal>status 200-399;</literal></tag-name>
586 <tag-desc>status is in the 200..399 range</tag-desc> 584 <tag-desc>status is in the range from 200 to 399</tag-desc>
587 585
588 <tag-name><literal>status ! 400-599;</literal></tag-name> 586 <tag-name><literal>status ! 400-599;</literal></tag-name>
589 <tag-desc>status is not in the 400..599 range</tag-desc> 587 <tag-desc>status is not in the range from 400 to 599</tag-desc>
590 588
591 <tag-name><literal>status 301-303 307;</literal></tag-name> 589 <tag-name><literal>status 301-303 307;</literal></tag-name>
592 <tag-desc>status is either 301, 302, 303, or 307</tag-desc> 590 <tag-desc>status is either 301, 302, 303, or 307</tag-desc>
593 591
594 </list> 592 </list>
1003 supports the following embedded variables: 1001 supports the following embedded variables:
1004 <list type="tag"> 1002 <list type="tag">
1005 1003
1006 <tag-name><var>$upstream_addr</var></tag-name> 1004 <tag-name><var>$upstream_addr</var></tag-name>
1007 <tag-desc> 1005 <tag-desc>
1008 keeps an IP address and port of the server, 1006 keeps the IP address and port of the server,
1009 or a path to the UNIX-domain socket. 1007 or the path to the UNIX-domain socket.
1010 If several servers were contacted during request processing, 1008 If several servers were contacted during request processing,
1011 their addresses are separated by commas, e.g. 1009 their addresses are separated by commas, e.g.
1012 “<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock</literal>”. 1010 “<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock</literal>”.
1013 If an internal redirect from one server group to another happened 1011 If an internal redirect from one server group to another happens,
1014 using 1012 initiated by
1015 <header>X-Accel-Redirect</header> or 1013 <header>X-Accel-Redirect</header> or
1016 <link doc="ngx_http_core_module.xml" id="error_page"/> 1014 <link doc="ngx_http_core_module.xml" id="error_page"/>,
1017 then these server groups are separated by colons, e.g. 1015 then the server addresses from different groups are separated by colons, e.g.
1018 “<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80</literal>”. 1016 “<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80</literal>”.
1019 </tag-desc> 1017 </tag-desc>
1020 1018
1021 <tag-name><var>$upstream_cache_status</var></tag-name> 1019 <tag-name><var>$upstream_cache_status</var></tag-name>
1022 <tag-desc> 1020 <tag-desc>
1023 keeps status of accessing a response cache (0.8.3). 1021 keeps the status of accessing a response cache (0.8.3).
1024 The status can be one of “<literal>MISS</literal>”,  1022 The status can be either “<literal>MISS</literal>”, 
1025 “<literal>BYPASS</literal>”, “<literal>EXPIRED</literal>”, 1023 “<literal>BYPASS</literal>”, “<literal>EXPIRED</literal>”,
1026 “<literal>STALE</literal>”, “<literal>UPDATING</literal>” or 1024 “<literal>STALE</literal>”, “<literal>UPDATING</literal>” or
1027 “<literal>HIT</literal>”. 1025 “<literal>HIT</literal>”.
1028 </tag-desc> 1026 </tag-desc>
1029 1027
1030 <tag-name><var>$upstream_response_length</var></tag-name> 1028 <tag-name><var>$upstream_response_length</var></tag-name>
1031 <tag-desc> 1029 <tag-desc>
1032 keeps lengths of responses obtained from upstream servers (0.7.27); 1030 keeps the lengths of responses obtained from the upstream servers (0.7.27);
1033 lengths are kept in bytes. 1031 lengths are kept in bytes.
1034 Several responses are separated by commas and colons 1032 Several response lengths are separated by commas and colons
1035 like in the <var>$upstream_addr</var> variable. 1033 like addresses in the <var>$upstream_addr</var> variable.
1036 </tag-desc> 1034 </tag-desc>
1037 1035
1038 <tag-name><var>$upstream_response_time</var></tag-name> 1036 <tag-name><var>$upstream_response_time</var></tag-name>
1039 <tag-desc> 1037 <tag-desc>
1040 keeps times of responses obtained from upstream servers; 1038 keeps times of responses obtained from upstream servers;
1041 times are kept in seconds with a milliseconds resolution. 1039 times are kept in seconds with a milliseconds resolution.
1042 Several responses are separated by commas and colons 1040 Several response times are separated by commas and colons
1043 like in the <var>$upstream_addr</var> variable. 1041 like addresses in the <var>$upstream_addr</var> variable.
1044 </tag-desc> 1042 </tag-desc>
1045 1043
1046 <tag-name><var>$upstream_status</var></tag-name> 1044 <tag-name><var>$upstream_status</var></tag-name>
1047 <tag-desc> 1045 <tag-desc>
1048 keeps codes of responses obtained from upstream servers. 1046 keeps codes of responses obtained from upstream servers.
1049 Several responses are separated by commas and colons 1047 Several response codes are separated by commas and colons
1050 like in the <var>$upstream_addr</var> variable. 1048 like addresses in the <var>$upstream_addr</var> variable.
1051 </tag-desc> 1049 </tag-desc>
1052 1050
1053 <tag-name><var>$upstream_http_...</var></tag-name> 1051 <tag-name><var>$upstream_http_...</var></tag-name>
1054 <tag-desc> 1052 <tag-desc>
1055 keep server response header fields. 1053 keep server response header fields.
1056 For example, the <header>Server</header> response header field 1054 For example, the <header>Server</header> response header field
1057 is made available through the <var>$upstream_http_server</var> variable. 1055 is available through the <var>$upstream_http_server</var> variable.
1058 The rules of converting header field names to variable names are the same 1056 The rules of converting header field names to variable names are the same
1059 as for variables starting with the 1057 as for the variables that start with the
1060 “<link doc="ngx_http_core_module.xml" id="variables">$http_</link>” prefix. 1058 “<link doc="ngx_http_core_module.xml" id="variables">$http_</link>” prefix.
1061 Only the last server’s response header fields are saved. 1059 Only the last server’s response header fields are saved.
1062 </tag-desc> 1060 </tag-desc>
1063 1061
1064 </list> 1062 </list>