Mercurial > hg > nginx-site

comparison xml/en/docs/stream/ngx_stream_upstream_module.xml @ 1462:e69e4dbcc760

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented OSS stream modules.
author Vladimir Homutov <vl@nginx.com>
date Tue, 21 Apr 2015 13:47:00 +0300
parents f5b5eefc43cb
children 8d134b482cc3
comparison
equal deleted inserted replaced
1461:4e5cab61e548 1462:e69e4dbcc760
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="5"> 12 rev="6">
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.9.0)
18 is used to define groups of servers that can be referenced 18 is used to define groups of servers that can be referenced
19 by the <link doc="ngx_stream_proxy_module.xml" id="proxy_pass"/> 19 by the <link doc="ngx_stream_proxy_module.xml" id="proxy_pass"/>
20 directive. 20 directive.
21 </para> 21 </para>
22 22
23 <para>
24 <note>
25 This module is available as part of our
26 <commercial_version>commercial subscription</commercial_version>.
27 </note>
28 </para>
29
30 </section> 23 </section>
31 24
32 25
33 <section id="example" name="Example Configuration"> 26 <section id="example" name="Example Configuration">
34 27
35 <para> 28 <para>
36 <example> 29 <example>
37 resolver 10.0.0.1;
38
39 upstream <emphasis>backend</emphasis> { 30 upstream <emphasis>backend</emphasis> {
40 zone upstream_backend 64k;
41
42 hash $remote_addr consistent; 31 hash $remote_addr consistent;
43 32
44 server backend1.example.com:12345 weight=5; 33 server backend1.example.com:12345 weight=5;
45 server 127.0.0.1:12345 max_fails=3 fail_timeout=30s; 34 server backend2.example.com:12345;
46 server unix:/tmp/backend2; 35 server unix:/tmp/backend3;
47 server backend3.example.com:12345 resolve; 36
37 server backup1.example.com:12345 backup;
38 server backup2.example.com:12345 backup;
48 } 39 }
49 40
50 server { 41 server {
51 listen 12346; 42 listen 12346;
52 proxy_pass <emphasis>backend</emphasis>; 43 proxy_pass <emphasis>backend</emphasis>;
44 }
45 </example>
46 </para>
47
48 <para>
49 Dynamically configurable group,
50 available as part of our
51 <commercial_version>commercial subscription</commercial_version>:
52 <example>
53 resolver 10.0.0.1;
54
55 upstream <emphasis>dynamic</emphasis> {
56 zone upstream_dynamic 64k;
57
58 server backend1.example.com:12345 weight=5;
59 server backend2.example.com:12345 fail_timeout=5s slow_start=30s;
60 server 192.0.2.1:12345 max_fails=3;
61 server backend3.example.com:12345 resolve;
62
63 server backup1.example.com:12345 backup;
64 server backup2.example.com:12345 backup;
65 }
66
67 server {
68 listen 12346;
69 proxy_pass <emphasis>dynamic</emphasis>;
53 health_check; 70 health_check;
54 } 71 }
55 </example> 72 </example>
56 </para> 73 </para>
57 74
175 </tag-name> 192 </tag-name>
176 <tag-desc> 193 <tag-desc>
177 marks the server as permanently unavailable. 194 marks the server as permanently unavailable.
178 </tag-desc> 195 </tag-desc>
179 196
197 </list>
198 </para>
199
200 <para>
201 Additionally,
202 the following parameters are available as part of our
203 <commercial_version>commercial subscription</commercial_version>:
204 <list type="tag">
205
180 <tag-name id="max_conns"> 206 <tag-name id="max_conns">
181 <literal>max_conns</literal>=<value>number</value> 207 <literal>max_conns</literal>=<value>number</value>
182 </tag-name> 208 </tag-name>
183 <tag-desc> 209 <tag-desc>
184 limits the maximum <value>number</value> of simultaneous connections to the 210 limits the maximum <value>number</value> of simultaneous connections to the
191 </tag-name> 217 </tag-name>
192 <tag-desc> 218 <tag-desc>
193 monitors changes of the IP addresses 219 monitors changes of the IP addresses
194 that correspond to a domain name of the server, 220 that correspond to a domain name of the server,
195 and automatically modifies the upstream configuration 221 and automatically modifies the upstream configuration
196 without the need of restarting nginx (1.7.10). 222 without the need of restarting nginx.
197 <para> 223 <para>
198 In order for this parameter to work, 224 In order for this parameter to work,
199 the <link doc="ngx_stream_core_module.xml" id="resolver"/> directive 225 the <link doc="ngx_stream_core_module.xml" id="resolver"/> directive
200 must be specified in the 226 must be specified in the
201 <link doc="ngx_stream_core_module.xml" id="stream"/> block. 227 <link doc="ngx_stream_core_module.xml" id="stream"/> block.
241 267
242 <directive name="zone"> 268 <directive name="zone">
243 <syntax><value>name</value> <value>size</value></syntax> 269 <syntax><value>name</value> <value>size</value></syntax>
244 <default/> 270 <default/>
245 <context>upstream</context> 271 <context>upstream</context>
246 <appeared-in>1.7.10</appeared-in>
247 272
248 <para> 273 <para>
249 Defines the <value>name</value> and <value>size</value> of the shared 274 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 275 memory zone that keeps the group’s configuration and run-time state that are
251 shared between worker processes. 276 shared between worker processes.
252 Such groups allow changing the group membership 277 </para>
278
279 <para>
280 Additionally,
281 as part of our <commercial_version>commercial subscription</commercial_version>,
282 such groups allow changing the group membership
253 or modifying the settings of a particular server 283 or modifying the settings of a particular server
254 without the need of restarting nginx. 284 without the need of restarting nginx.
255 The configuration is accessible via a special location 285 The configuration is accessible via a special location
256 handled by 286 handled by
257 <link doc="../http/ngx_http_upstream_conf_module.xml" id="upstream_conf"/>. 287 <link doc="../http/ngx_http_upstream_conf_module.xml" id="upstream_conf"/>.
314 <syntax><literal>connect</literal> | 344 <syntax><literal>connect</literal> |
315 <literal>first_byte</literal> | 345 <literal>first_byte</literal> |
316 <literal>last_byte</literal></syntax> 346 <literal>last_byte</literal></syntax>
317 <default/> 347 <default/>
318 <context>upstream</context> 348 <context>upstream</context>
319 <appeared-in>1.7.11</appeared-in>
320 349
321 <para> 350 <para>
322 Specifies that a group should use a load balancing method where a connection 351 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 352 is passed to the server with the least average time and
324 least number of active connections, taking into account weights of servers. 353 least number of active connections, taking into account weights of servers.
333 time to receive the first byte of data is used. 362 time to receive the first byte of data is used.
334 If the <literal>last_byte</literal> is specified, 363 If the <literal>last_byte</literal> is specified,
335 time to receive the last byte of data is used. 364 time to receive the last byte of data is used.
336 </para> 365 </para>
337 366
367 <para>
368 <note>
369 This directive is available as part of our
370 <commercial_version>commercial subscription</commercial_version>.
371 </note>
372 </para>
373
338 </directive> 374 </directive>
339 375
340 376
341 <directive name="health_check"> 377 <directive name="health_check">
342 <syntax>[<value>parameters</value>]</syntax> 378 <syntax>[<value>parameters</value>]</syntax>
343 <default/> 379 <default/>
344 <context>server</context> 380 <context>server</context>
345 <appeared-in>1.7.10</appeared-in>
346 381
347 <para> 382 <para>
348 Enables periodic health checks of the servers in a 383 Enables periodic health checks of the servers in a
349 <link id="upstream">group</link>. 384 <link id="upstream">group</link>.
350 </para> 385 </para>
421 If several health checks are defined for the same group of servers, 456 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 457 a single failure of any check will make the corresponding server be
423 considered unhealthy. 458 considered unhealthy.
424 </para> 459 </para>
425 460
461 <para>
462 <note>
463 This directive is available as part of our
464 <commercial_version>commercial subscription</commercial_version>.
465 </note>
466 </para>
467
426 </directive> 468 </directive>
427 469
428 470
429 <directive name="health_check_timeout"> 471 <directive name="health_check_timeout">
430 <syntax><value>timeout</value></syntax> 472 <syntax><value>timeout</value></syntax>
431 <default>5s</default> 473 <default>5s</default>
432 <context>stream</context> 474 <context>stream</context>
433 <context>server</context> 475 <context>server</context>
434 <appeared-in>1.7.10</appeared-in>
435 476
436 <para> 477 <para>
437 Overrides the 478 Overrides the
438 <link doc="ngx_stream_proxy_module.xml" id="proxy_timeout"/> 479 <link doc="ngx_stream_proxy_module.xml" id="proxy_timeout"/>
439 value for health checks. 480 value for health checks.
440 </para> 481 </para>
441 482
483 <para>
484 <note>
485 This directive is available as part of our
486 <commercial_version>commercial subscription</commercial_version>.
487 </note>
488 </para>
489
442 </directive> 490 </directive>
443 491
444 492
445 <directive name="match"> 493 <directive name="match">
446 <syntax block="yes"><value>name</value> </syntax> 494 <syntax block="yes"><value>name</value> </syntax>
447 <default/> 495 <default/>
448 <context>stream</context> 496 <context>stream</context>
449 <appeared-in>1.7.10</appeared-in>
450 497
451 <para> 498 <para>
452 Defines the named test set used to verify server responses to health checks. 499 Defines the named test set used to verify server responses to health checks.
453 </para> 500 </para>
454 501
528 <link doc="ngx_stream_proxy_module.xml" id="proxy_upstream_buffer"/> 575 <link doc="ngx_stream_proxy_module.xml" id="proxy_upstream_buffer"/>
529 bytes of data obtained from the server are examined. 576 bytes of data obtained from the server are examined.
530 </note> 577 </note>
531 </para> 578 </para>
532 579
580 <para>
581 <note>
582 This directive is available as part of our
583 <commercial_version>commercial subscription</commercial_version>.
584 </note>
585 </para>
586
533 </directive> 587 </directive>
534 588
535 </section> 589 </section>
536 590
537 </module> 591 </module>