Mercurial > hg > nginx-site

comparison xml/en/docs/stream/ngx_stream_upstream_module.xml @ 1450:f5b5eefc43cb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated commercial docs for the upcoming release.
author Ruslan Ermilov <ru@nginx.com>
date Thu, 09 Apr 2015 19:18:54 +0300
parents f5dcc23b214f
children e69e4dbcc760
comparison
equal deleted inserted replaced
1449:c79501e16e26 1450:f5b5eefc43cb
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> 7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8 8
9 <module name="Module ngx_stream_upstream_module" 9 <module name="Module ngx_stream_upstream_module"
10 link="/en/docs/stream/ngx_stream_upstream_module.html" 10 link="/en/docs/stream/ngx_stream_upstream_module.html"
11 lang="en" 11 lang="en"
12 rev="4"> 12 rev="5">
13 13
14 <section id="summary"> 14 <section id="summary">
15 15
16 <para> 16 <para>
17 The <literal>ngx_stream_upstream_module</literal> module (1.7.7) 17 The <literal>ngx_stream_upstream_module</literal> module (1.7.7)
32 32
33 <section id="example" name="Example Configuration"> 33 <section id="example" name="Example Configuration">
34 34
35 <para> 35 <para>
36 <example> 36 <example>
37 resolver 10.0.0.1;
38
37 upstream <emphasis>backend</emphasis> { 39 upstream <emphasis>backend</emphasis> {
40 zone upstream_backend 64k;
41
38 hash $remote_addr consistent; 42 hash $remote_addr consistent;
39 43
40 server backend1.example.com:12345 weight=5; 44 server backend1.example.com:12345 weight=5;
41 server 127.0.0.1:12345 max_fails=3 fail_timeout=30s; 45 server 127.0.0.1:12345 max_fails=3 fail_timeout=30s;
42 server unix:/tmp/backend3; 46 server unix:/tmp/backend2;
47 server backend3.example.com:12345 resolve;
43 } 48 }
44 49
45 server { 50 server {
46 listen 12346; 51 listen 12346;
47 proxy_pass <emphasis>backend</emphasis>; 52 proxy_pass <emphasis>backend</emphasis>;
53 health_check;
48 } 54 }
49 </example> 55 </example>
50 </para> 56 </para>
51 57
52 </section> 58 </section>
70 Example: 76 Example:
71 <example> 77 <example>
72 upstream backend { 78 upstream backend {
73 server backend1.example.com:12345 weight=5; 79 server backend1.example.com:12345 weight=5;
74 server 127.0.0.1:12345 max_fails=3 fail_timeout=30s; 80 server 127.0.0.1:12345 max_fails=3 fail_timeout=30s;
75 server unix:/tmp/backend3; 81 server unix:/tmp/backend2;
82 server backend3.example.com:12345 resolve;
76 83
77 server backup1.example.com:12345 backup; 84 server backup1.example.com:12345 backup;
78 } 85 }
79 </example> 86 </example>
80 </para> 87 </para>
177 limits the maximum <value>number</value> of simultaneous connections to the 184 limits the maximum <value>number</value> of simultaneous connections to the
178 proxied server. 185 proxied server.
179 Default value is zero, meaning there is no limit. 186 Default value is zero, meaning there is no limit.
180 </tag-desc> 187 </tag-desc>
181 188
189 <tag-name id="resolve">
190 <literal>resolve</literal>
191 </tag-name>
192 <tag-desc>
193 monitors changes of the IP addresses
194 that correspond to a domain name of the server,
195 and automatically modifies the upstream configuration
196 without the need of restarting nginx (1.7.10).
197 <para>
198 In order for this parameter to work,
199 the <link doc="ngx_stream_core_module.xml" id="resolver"/> directive
200 must be specified in the
201 <link doc="ngx_stream_core_module.xml" id="stream"/> block.
202 Example:
203 <example>
204 stream {
205 resolver 10.0.0.1;
206
207 upstream u {
208 zone ...;
209 ...
210 server example.com:12345 resolve;
211 }
212 }
213 </example>
214 </para>
215 </tag-desc>
216
182 <tag-name id="slow_start"> 217 <tag-name id="slow_start">
183 <literal>slow_start</literal>=<value>time</value> 218 <literal>slow_start</literal>=<value>time</value>
184 </tag-name> 219 </tag-name>
185 <tag-desc> 220 <tag-desc>
186 sets the <value>time</value> during which the server will recover its weight 221 sets the <value>time</value> during which the server will recover its weight
197 <note> 232 <note>
198 If there is only a single server in a group, <literal>max_fails</literal>, 233 If there is only a single server in a group, <literal>max_fails</literal>,
199 <literal>fail_timeout</literal> and <literal>slow_start</literal> parameters 234 <literal>fail_timeout</literal> and <literal>slow_start</literal> parameters
200 are ignored, and such a server will never be considered unavailable. 235 are ignored, and such a server will never be considered unavailable.
201 </note> 236 </note>
237 </para>
238
239 </directive>
240
241
242 <directive name="zone">
243 <syntax><value>name</value> <value>size</value></syntax>
244 <default/>
245 <context>upstream</context>
246 <appeared-in>1.7.10</appeared-in>
247
248 <para>
249 Defines the <value>name</value> and <value>size</value> of the shared
250 memory zone that keeps the group’s configuration and run-time state that are
251 shared between worker processes.
252 Such groups allow changing the group membership
253 or modifying the settings of a particular server
254 without the need of restarting nginx.
255 The configuration is accessible via a special location
256 handled by
257 <link doc="../http/ngx_http_upstream_conf_module.xml" id="upstream_conf"/>.
202 </para> 258 </para>
203 259
204 </directive> 260 </directive>
205 261
206 262
251 weighted round-robin balancing method. 307 weighted round-robin balancing method.
252 </para> 308 </para>
253 309
254 </directive> 310 </directive>
255 311
312
313 <directive name="least_time">
314 <syntax><literal>connect</literal> |
315 <literal>first_byte</literal> |
316 <literal>last_byte</literal></syntax>
317 <default/>
318 <context>upstream</context>
319 <appeared-in>1.7.11</appeared-in>
320
321 <para>
322 Specifies that a group should use a load balancing method where a connection
323 is passed to the server with the least average time and
324 least number of active connections, taking into account weights of servers.
325 If there are several such servers, they are tried in turn using a
326 weighted round-robin balancing method.
327 </para>
328
329 <para>
330 If the <literal>connect</literal> parameter is specified,
331 time to connect to the upstream server is used.
332 If the <literal>first_byte</literal> parameter is specified,
333 time to receive the first byte of data is used.
334 If the <literal>last_byte</literal> is specified,
335 time to receive the last byte of data is used.
336 </para>
337
338 </directive>
339
340
341 <directive name="health_check">
342 <syntax>[<value>parameters</value>]</syntax>
343 <default/>
344 <context>server</context>
345 <appeared-in>1.7.10</appeared-in>
346
347 <para>
348 Enables periodic health checks of the servers in a
349 <link id="upstream">group</link>.
350 </para>
351
352 <para>
353 The following optional parameters are supported:
354 <list type="tag">
355
356 <tag-name id="interval">
357 <literal>interval</literal>=<value>time</value>
358 </tag-name>
359 <tag-desc>
360 sets the interval between two consecutive health checks,
361 by default, 5 seconds;
362 </tag-desc>
363
364 <tag-name id="fails">
365 <literal>fails</literal>=<value>number</value>
366 </tag-name>
367 <tag-desc>
368 sets the number of consecutive failed health checks of a particular server
369 after which this server will be considered unhealthy,
370 by default, 1;
371 </tag-desc>
372
373 <tag-name id="passes">
374 <literal>passes</literal>=<value>number</value>
375 </tag-name>
376 <tag-desc>
377 sets the number of consecutive passed health checks of a particular server
378 after which the server will be considered healthy,
379 by default, 1;
380 </tag-desc>
381
382 <tag-name id="hc_match">
383 <literal>match</literal>=<value>name</value>
384 </tag-name>
385 <tag-desc>
386 specifies the <literal>match</literal> block configuring the tests that a
387 successful connection should pass in order for a health check to pass;
388 by default, only the ability to connect to the server is checked.
389 </tag-desc>
390
391 </list>
392 </para>
393
394 <para>
395 For example,
396 <example>
397 server {
398 proxy_pass backend;
399 health_check;
400 }
401 </example>
402 will check the ability to connect to each
403 server in the <literal>backend</literal> group every five seconds.
404 When a connection to the server cannot be established,
405 the health check will fail, and the server will
406 be considered unhealthy.
407 Client connections are not passed to unhealthy servers.
408 </para>
409
410 <para>
411 Health checks can also be configured to test data obtained from the server.
412 Tests are configured separately using the <link id="match"/> directive
413 and referenced in the <literal>match</literal> parameter.
414 </para>
415
416 <para>
417 The server group must reside in the <link id="zone">shared memory</link>.
418 </para>
419
420 <para>
421 If several health checks are defined for the same group of servers,
422 a single failure of any check will make the corresponding server be
423 considered unhealthy.
424 </para>
425
426 </directive>
427
428
429 <directive name="health_check_timeout">
430 <syntax><value>timeout</value></syntax>
431 <default>5s</default>
432 <context>stream</context>
433 <context>server</context>
434 <appeared-in>1.7.10</appeared-in>
435
436 <para>
437 Overrides the
438 <link doc="ngx_stream_proxy_module.xml" id="proxy_timeout"/>
439 value for health checks.
440 </para>
441
442 </directive>
443
444
445 <directive name="match">
446 <syntax block="yes"><value>name</value> </syntax>
447 <default/>
448 <context>stream</context>
449 <appeared-in>1.7.10</appeared-in>
450
451 <para>
452 Defines the named test set used to verify server responses to health checks.
453 </para>
454
455 <para>
456 The following parameters can be configured:
457 <list type="tag">
458
459 <tag-name>
460 <literal>send</literal> <value>string</value>;
461 </tag-name>
462 <tag-desc>
463 sends a <value>string</value> to the server;
464 </tag-desc>
465
466 <tag-name>
467 <literal>expect</literal> <literal>~</literal> <value>regexp</value>;
468 </tag-name>
469 <tag-desc>
470 a regular expression that the data obtained from the server should match.
471 The regular expression is specified with the preceding
472 “<literal>~*</literal>” modifier (for case-insensitive matching), or the
473 “<literal>~</literal>” modifier (for case-sensitive matching).
474 </tag-desc>
475
476 </list>
477 </para>
478
479 <para>
480 Health check is passed if:
481 <list type="bullet">
482 <listitem>
483 the connection was successfully established;
484 </listitem>
485
486 <listitem>
487 the <value>string</value> from the <literal>send</literal> parameter,
488 if specified, was sent;
489 </listitem>
490
491 <listitem>
492 the data obtained from the server matched the regular expression
493 from the <literal>expect</literal> parameter, if specified;
494 </listitem>
495
496 <listitem>
497 the time elapsed does not exceed the value specified
498 in the <link id="health_check_timeout"/> directive.
499 </listitem>
500
501 </list>
502 </para>
503
504 <para>
505 Example:
506 <example>
507 upstream backend {
508 zone upstream_backend 10m;
509 server 127.0.0.1:12345;
510 }
511
512 match http {
513 send "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n";
514 expect ~ "200 OK";
515 }
516
517 server {
518 listen 12346;
519 proxy_pass backend;
520 health_check match=http;
521 }
522 </example>
523 </para>
524
525 <para>
526 <note>
527 Only the first
528 <link doc="ngx_stream_proxy_module.xml" id="proxy_upstream_buffer"/>
529 bytes of data obtained from the server are examined.
530 </note>
531 </para>
532
533 </directive>
534
256 </section> 535 </section>
257 536
258 </module> 537 </module>