Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 533:fb630c3c5039

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Revamped the upstream documentation somewhat.
author Ruslan Ermilov <ru@nginx.com>
date Fri, 08 Jun 2012 19:05:36 +0000
parents 4f907cde0382
children a9e6a8613534
comparison
equal deleted inserted replaced
532:480a4cd56a6a 533:fb630c3c5039
9 <section id="summary"> 9 <section id="summary">
10 10
11 <para> 11 <para>
12 The <literal>ngx_http_upstream_module</literal> module 12 The <literal>ngx_http_upstream_module</literal> module
13 allows to define groups of servers that can be referenced 13 allows to define groups of servers that can be referenced
14 from the <link doc="ngx_http_proxy_module.xml" id="proxy_pass"/> and 14 from the <link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>,
15 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/> directives. 15 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>, and
16 <link doc="ngx_http_memcached_module.xml" id="memcached_pass"/> directives.
16 </para> 17 </para>
17 18
18 </section> 19 </section>
19 20
20 21
42 </section> 43 </section>
43 44
44 45
45 <section id="directives" name="Directives"> 46 <section id="directives" name="Directives">
46 47
48 <directive name="upstream">
49 <syntax block="yes"><value>name</value></syntax>
50 <default/>
51 <context>http</context>
52
53 <para>
54 Defines a group of servers.
55 Servers can listen on different ports.
56 In addition, servers listening on TCP and UNIX-domain sockets
57 can be mixed.
58 </para>
59
60 <para>
61 Example:
62 <example>
63 upstream backend {
64 server backend1.example.com weight=5;
65 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
66 server unix:/tmp/backend3;
67 }
68 </example>
69 </para>
70
71 <para>
72 By default, requests are distributed between servers using a
73 weighted round-robin balancing method.
74 In the above example, each 7 requests will be distributed as follows:
75 5 requests to <literal>backend1.example.com</literal>
76 and one request to each of second and third servers.
77 If an error occurs when communicating with the server, a request will
78 be passed to the next server, and so on until all of the functioning
79 servers will be tried.
80 If a successful response could not be obtained from any of the servers,
81 the client will be returned the result of contacting the last server.
82 </para>
83
84 </directive>
85
86
87 <directive name="server">
88 <syntax><value>address</value> [<value>parameters</value>]</syntax>
89 <default/>
90 <context>upstream</context>
91
92 <para>
93 Defines an <value>address</value> and other <value>parameters</value>
94 of the server.
95 An address can be specified as a domain name or IP address,
96 and an optional port, or as a UNIX-domain socket path
97 specified after the “<literal>unix:</literal>” prefix.
98 If port is not specified, the port 80 is used.
99 A domain name that resolves to several IP addresses essentially defines
100 multiple servers.
101 </para>
102
103 <para>
104 The following parameters can be defined:
105 <list type="tag">
106
107 <tag-name><literal>weight</literal>=<value>number</value></tag-name>
108 <tag-desc>
109 sets a weight of the server, by default 1.
110 </tag-desc>
111
112 <tag-name><literal>max_fails</literal>=<value>number</value></tag-name>
113 <tag-desc>
114 sets a number of unsuccessful attempts to communicate with the server
115 during a time set by the <literal>fail_timeout</literal> parameter
116 after which it will be considered down for a period of time also set
117 by the <literal>fail_timeout</literal> parameter.
118 By default, the number of unsuccessful attempts is set to 1.
119 A value of zero disables accounting of attempts.
120 What is considered to be an unsuccessful attempt is configured by the
121 <link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>,
122 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>, and
123 <link doc="ngx_http_memcached_module.xml" id="memcached_next_upstream"/>
124 directives.
125 The <literal>http_404</literal> state is not considered
126 an unsuccessful attempt.
127 </tag-desc>
128
129 <tag-name><literal>fail_timeout</literal>=<value>time</value></tag-name>
130 <tag-desc>
131 sets
132 <list type="bullet">
133
134 <listitem>
135 a time during which the specified number of unsuccessful attempts to
136 communicate with the server should happen for the server to be
137 considered down;
138 </listitem>
139
140 <listitem>
141 and a period of time the server will be considered down.
142 </listitem>
143
144 </list>
145 By default, timeout is set to 10 seconds.
146 </tag-desc>
147
148 <tag-name><literal>backup</literal></tag-name>
149 <tag-desc>
150 marks the server as a backup server.
151 It will be passed requests when the primary servers are down.
152 </tag-desc>
153
154 <tag-name><literal>down</literal></tag-name>
155 <tag-desc>
156 marks the server as permanently down; used along with
157 the <link id="ip_hash"/> directive.
158 </tag-desc>
159
160 </list>
161 </para>
162
163 <para>
164 Example:
165 <example>
166 upstream backend {
167 server backend1.example.com weight=5;
168 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
169 server unix:/tmp/backend3;
170
171 server backup1.example.com:8080 backup;
172 }
173 </example>
174 </para>
175
176 </directive>
177
178
47 <directive name="ip_hash"> 179 <directive name="ip_hash">
48 <syntax/> 180 <syntax/>
49 <default/> 181 <default/>
50 <context>upstream</context> 182 <context>upstream</context>
51 183
52 <para> 184 <para>
53 Specifies that a group should use a balancing method where requests 185 Specifies that a group should use a load balancing method where requests
54 are distributed between servers based on client IP addresses. 186 are distributed between servers based on client IP addresses.
55 A class C network containing the client IP address is used as a hashing key. 187 The first three octets of the client IPv4 address
188 are used as a hashing key.
56 The method ensures that requests of the same client will always be 189 The method ensures that requests of the same client will always be
57 passed to the same server except when this server is considered down 190 passed to the same server except when this server is considered down
58 in which case client requests will be passed to another server and 191 in which case client requests will be passed to another server and
59 most probably it will also be the same server. 192 most probably it will also be the same server.
60 </para> 193 </para>
80 </para> 213 </para>
81 214
82 <para> 215 <para>
83 <note> 216 <note>
84 Until version 1.3.1 it was not possible to specify a weight for 217 Until version 1.3.1 it was not possible to specify a weight for
85 servers using the <literal>ip_hash</literal> balancing method. 218 servers using the <literal>ip_hash</literal> load balancing method.
86 </note> 219 </note>
87 </para> 220 </para>
88 221
89 </directive> 222 </directive>
90 223
194 </example> 327 </example>
195 </para> 328 </para>
196 329
197 <para> 330 <para>
198 <note> 331 <note>
199 When using load balancer modules other than the default 332 When using load balancer methods other than the default
200 round-robin, it is necessary to activate them before 333 round-robin, it is necessary to activate them before
201 the <literal>keepalive</literal> directive. 334 the <literal>keepalive</literal> directive.
202 </note> 335 </note>
203 336
204 <note> 337 <note>
205 SCGI and uwsgi protocols do not define keepalive connections. 338 SCGI and uwsgi protocols do not have a notion of keepalive connections.
206 </note> 339 </note>
207 </para> 340 </para>
208 341
209 </directive> 342 </directive>
210 343
214 <default/> 347 <default/>
215 <context>upstream</context> 348 <context>upstream</context>
216 <appeared-in>1.3.1</appeared-in> 349 <appeared-in>1.3.1</appeared-in>
217 350
218 <para> 351 <para>
219 Specifies that a group should use a balancing method where a request 352 Specifies that a group should use a load balancing method where a request
220 is passed to the server with the least number of active connections, 353 is passed to the server with the least number of active connections,
221 taking into account weights of servers. 354 taking into account weights of servers.
222 If there are several such servers, they are tried in a 355 If there are several such servers, they are tried using a
223 weighted round-robin fashion. 356 weighted round-robin balancing method.
224 </para>
225
226 </directive>
227
228
229 <directive name="server">
230 <syntax><value>name</value> [<value>parameters</value>]</syntax>
231 <default/>
232 <context>upstream</context>
233
234 <para>
235 Sets a <value>name</value> and other <value>parameters</value> of the server.
236 A <value>name</value> can be a domain name, an address, a port, or a
237 path of the UNIX-domain socket.
238 If a domain name resolves to several addresses, all of them are used.
239 <list type="tag">
240
241 <tag-name><literal>weight</literal>=<value>number</value></tag-name>
242 <tag-desc>
243 sets a weight of the server, by default 1.
244 </tag-desc>
245
246 <tag-name><literal>max_fails</literal>=<value>number</value></tag-name>
247 <tag-desc>
248 sets a number of unsuccessful attempts to communicate with the server
249 during a time set by the <literal>fail_timeout</literal> parameter
250 after which it will be considered down for a period of time also set
251 by the <literal>fail_timeout</literal> parameter.
252 By default, the number of unsuccessful attempts is set to 1.
253 A value of zero disables accounting of attempts.
254 What is considered to be an unsuccessful attempt is configured by the
255 <link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>
256 and <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>
257 directives.
258 The <literal>http_404</literal> state is not considered
259 an unsuccessful attempt.
260 </tag-desc>
261
262 <tag-name><literal>fail_timeout</literal>=<value>time</value></tag-name>
263 <tag-desc>
264 sets
265 <list type="bullet">
266
267 <listitem>
268 a time during which the specified number of unsuccessful attempts to
269 communicate with the server should happen for the server to be
270 considered down;
271 </listitem>
272
273 <listitem>
274 and a period of time the server will be considered down.
275 </listitem>
276
277 </list>
278 By default, timeout is set to 10 seconds.
279 </tag-desc>
280
281 <tag-name><literal>backup</literal></tag-name>
282 <tag-desc>
283 marks the server as a backup server.
284 It will be passed requests when the primary servers are down.
285 </tag-desc>
286
287 <tag-name><literal>down</literal></tag-name>
288 <tag-desc>
289 marks the server as permanently down; used along with
290 the <link id="ip_hash"/> directive.
291 </tag-desc>
292
293 </list>
294 </para>
295
296 <para>
297 Example:
298 <example>
299 upstream backend {
300 server backend1.example.com weight=5;
301 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
302 server unix:/tmp/backend3;
303
304 server backup1.example.com:8080 backup;
305 }
306 </example>
307 </para>
308
309 </directive>
310
311
312 <directive name="upstream">
313 <syntax block="yes"><value>name</value></syntax>
314 <default/>
315 <context>http</context>
316
317 <para>
318 Defines a group of servers.
319 Servers can listen on different ports.
320 In addition, servers listening on TCP and UNIX-domain sockets
321 can be used simultaneously.
322 </para>
323
324 <para>
325 Example:
326 <example>
327 upstream backend {
328 server backend1.example.com weight=5;
329 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
330 server unix:/tmp/backend3;
331 }
332 </example>
333 </para>
334
335 <para>
336 Requests are distributed between servers in a
337 weighted round-robin fashion.
338 In the above example, each 7 requests will be distributed as follows:
339 5 requests to <literal>backend1.example.com</literal>
340 and one request to each of second and third servers.
341 If an error occurs when communicating with the server, a request will
342 be passed to the next server, and so on until all of the functioning
343 servers will be tried.
344 If a successful response could not be obtained from any of the servers,
345 the client will be returned the result of contacting the last server.
346 </para> 357 </para>
347 358
348 </directive> 359 </directive>
349 360
350 </section> 361 </section>