Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 966:95c3c3bbf1ce
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> |