Mercurial > hg > nginx-site

comparison xml/en/docs/stream/ngx_stream_upstream_module.xml @ 3043:9eadb98ec770

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Free nginx: removed commercial version documentation.
author Maxim Dounin <mdounin@mdounin.ru>
date Wed, 14 Feb 2024 20:05:49 +0300
parents 3a2d342533fb
children
comparison
equal deleted inserted replaced
3042:19e4897acb84 3043:9eadb98ec770
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="39"> 12 rev="40">
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.9.0) 17 The <literal>ngx_stream_upstream_module</literal> module (1.9.0)
39 } 39 }
40 40
41 server { 41 server {
42 listen 12346; 42 listen 12346;
43 proxy_pass <emphasis>backend</emphasis>; 43 proxy_pass <emphasis>backend</emphasis>;
44 }
45 </example>
46 </para>
47
48 <para>
49 Dynamically configurable group with
50 periodic <link doc="ngx_stream_upstream_hc_module.xml">health checks</link> is
51 available as part of our
52 <commercial_version>commercial subscription</commercial_version>:
53 <example>
54 resolver 10.0.0.1;
55
56 upstream <emphasis>dynamic</emphasis> {
57 zone upstream_dynamic 64k;
58
59 server backend1.example.com:12345 weight=5;
60 server backend2.example.com:12345 fail_timeout=5s slow_start=30s;
61 server 192.0.2.1:12345 max_fails=3;
62 server backend3.example.com:12345 resolve;
63 server backend4.example.com service=http resolve;
64
65 server backup1.example.com:12345 backup;
66 server backup2.example.com:12345 backup;
67 }
68
69 server {
70 listen 12346;
71 proxy_pass <emphasis>dynamic</emphasis>;
72 health_check;
73 } 44 }
74 </example> 45 </example>
75 </para> 46 </para>
76 47
77 </section> 48 </section>
153 limits the maximum <value>number</value> of simultaneous 124 limits the maximum <value>number</value> of simultaneous
154 connections to the proxied server (1.11.5). 125 connections to the proxied server (1.11.5).
155 Default value is zero, meaning there is no limit. 126 Default value is zero, meaning there is no limit.
156 If the server group does not reside in the <link id="zone">shared memory</link>, 127 If the server group does not reside in the <link id="zone">shared memory</link>,
157 the limitation works per each worker process. 128 the limitation works per each worker process.
158 <note>
159 Prior to version 1.11.5, this parameter was available as part of our
160 <commercial_version>commercial subscription</commercial_version>.
161 </note>
162 </tag-desc> 129 </tag-desc>
163 130
164 <tag-name id="max_fails"> 131 <tag-name id="max_fails">
165 <literal>max_fails</literal>=<value>number</value> 132 <literal>max_fails</literal>=<value>number</value>
166 </tag-name> 133 </tag-name>
217 184
218 </list> 185 </list>
219 </para> 186 </para>
220 187
221 <para> 188 <para>
222 Additionally,
223 the following parameters are available as part of our
224 <commercial_version>commercial subscription</commercial_version>:
225 <list type="tag">
226
227 <tag-name id="resolve">
228 <literal>resolve</literal>
229 </tag-name>
230 <tag-desc>
231 monitors changes of the IP addresses
232 that correspond to a domain name of the server,
233 and automatically modifies the upstream configuration
234 without the need of restarting nginx.
235 The server group must reside in the <link id="zone">shared memory</link>.
236 <para>
237 In order for this parameter to work,
238 the <literal>resolver</literal> directive
239 must be specified in the
240 <link doc="ngx_stream_core_module.xml" id="resolver">stream</link> block
241 or in the corresponding <link id="resolver">upstream</link> block.
242 </para>
243 </tag-desc>
244
245 <tag-name id="service">
246 <literal>service</literal>=<value>name</value>
247 </tag-name>
248 <tag-desc>
249 enables resolving of DNS
250 <link url="https://datatracker.ietf.org/doc/html/rfc2782">SRV</link>
251 records and sets the service <value>name</value> (1.9.13).
252 In order for this parameter to work, it is necessary to specify
253 the <link id="resolve"/> parameter for the server
254 and specify a hostname without a port number.
255 <para>
256 If the service name does not contain a dot (“<literal>.</literal>”), then
257 the <link url="https://datatracker.ietf.org/doc/html/rfc2782">RFC</link>-compliant name
258 is constructed
259 and the TCP protocol is added to the service prefix.
260 For example, to look up the
261 <literal>_http._tcp.backend.example.com</literal> SRV record,
262 it is necessary to specify the directive:
263 <example>
264 server backend.example.com service=http resolve;
265 </example>
266 If the service name contains one or more dots, then the name is constructed
267 by joining the service prefix and the server name.
268 For example, to look up the <literal>_http._tcp.backend.example.com</literal>
269 and <literal>server1.backend.example.com</literal> SRV records,
270 it is necessary to specify the directives:
271 <example>
272 server backend.example.com service=_http._tcp resolve;
273 server example.com service=server1.backend resolve;
274 </example>
275 </para>
276
277 <para>
278 Highest-priority SRV records
279 (records with the same lowest-number priority value)
280 are resolved as primary servers,
281 the rest of SRV records are resolved as backup servers.
282 If the <link id="backup"/> parameter is specified for the server,
283 high-priority SRV records are resolved as backup servers,
284 the rest of SRV records are ignored.
285 </para>
286 </tag-desc>
287
288 <tag-name id="slow_start">
289 <literal>slow_start</literal>=<value>time</value>
290 </tag-name>
291 <tag-desc>
292 sets the <value>time</value> during which the server will recover its weight
293 from zero to a nominal value, when unhealthy server becomes
294 <link doc="ngx_stream_upstream_hc_module.xml" id="health_check">healthy</link>,
295 or when the server becomes available after a period of time
296 it was considered <link id="fail_timeout">unavailable</link>.
297 Default value is zero, i.e. slow start is disabled.
298 <note> 189 <note>
299 The parameter cannot be used along with the 190 If there is only a single server in a group,
300 <link id="hash"/> and <link id="random"/> load balancing methods. 191 <literal>max_fails</literal> and <literal>fail_timeout</literal> parameters
301 </note>
302 </tag-desc>
303
304 </list>
305 </para>
306
307 <para>
308 <note>
309 If there is only a single server in a group, <literal>max_fails</literal>,
310 <literal>fail_timeout</literal> and <literal>slow_start</literal> parameters
311 are ignored, and such a server will never be considered unavailable. 192 are ignored, and such a server will never be considered unavailable.
312 </note> 193 </note>
313 </para> 194 </para>
314 195
315 </directive> 196 </directive>
324 Defines the <value>name</value> and <value>size</value> of the shared 205 Defines the <value>name</value> and <value>size</value> of the shared
325 memory zone that keeps the group’s configuration and run-time state that are 206 memory zone that keeps the group’s configuration and run-time state that are
326 shared between worker processes. 207 shared between worker processes.
327 Several groups may share the same zone. 208 Several groups may share the same zone.
328 In this case, it is enough to specify the <value>size</value> only once. 209 In this case, it is enough to specify the <value>size</value> only once.
329 </para>
330
331 <para>
332 Additionally,
333 as part of our <commercial_version>commercial subscription</commercial_version>,
334 such groups allow changing the group membership
335 or modifying the settings of a particular server
336 without the need of restarting nginx.
337 The configuration is accessible via the
338 <link doc="../http/ngx_http_api_module.xml">API</link> module (1.13.3).
339 <note>
340 Prior to version 1.13.3,
341 the configuration was accessible only via a special location
342 handled by
343 <link doc="../http/ngx_http_upstream_conf_module.xml" id="upstream_conf"/>.
344 </note>
345 </para>
346
347 </directive>
348
349
350 <directive name="state">
351 <syntax><value>file</value></syntax>
352 <default/>
353 <context>upstream</context>
354 <appeared-in>1.9.7</appeared-in>
355
356 <para>
357 Specifies a <value>file</value> that keeps the state
358 of the dynamically configurable group.
359 </para>
360
361 <para>
362 Examples:
363 <example>
364 state /var/lib/nginx/state/servers.conf; # path for Linux
365 state /var/db/nginx/state/servers.conf; # path for FreeBSD
366 </example>
367 </para>
368
369 <para>
370 The state is currently limited to the list of servers with their parameters.
371 The file is read when parsing the configuration and is updated each time
372 the upstream configuration is
373 <link doc="../http/ngx_http_api_module.xml" id="stream_upstreams_stream_upstream_name_servers_">changed</link>.
374 Changing the file content directly should be avoided.
375 The directive cannot be used
376 along with the <link id="server"/> directive.
377 </para>
378
379 <para>
380 <note>
381 Changes made during
382 <link doc="../control.xml" id="reconfiguration">configuration reload</link>
383 or <link doc="../control.xml" id="upgrade">binary upgrade</link>
384 can be lost.
385 </note>
386 </para>
387
388 <para>
389 <note>
390 This directive is available as part of our
391 <commercial_version>commercial subscription</commercial_version>.
392 </note>
393 </para> 210 </para>
394 211
395 </directive> 212 </directive>
396 213
397 214
446 </para> 263 </para>
447 264
448 </directive> 265 </directive>
449 266
450 267
451 <directive name="least_time">
452 <syntax>
453 <literal>connect</literal> |
454 <literal>first_byte</literal> |
455 <literal>last_byte</literal>
456 [<literal>inflight</literal>]</syntax>
457 <default/>
458 <context>upstream</context>
459
460 <para>
461 Specifies that a group should use a load balancing method where a connection
462 is passed to the server with the least average time and
463 least number of active connections, taking into account weights of servers.
464 If there are several such servers, they are tried in turn using a
465 weighted round-robin balancing method.
466 </para>
467
468 <para>
469 If the <literal>connect</literal> parameter is specified,
470 time to
471 <link id="var_upstream_connect_time">connect</link>
472 to the upstream server is used.
473 If the <literal>first_byte</literal> parameter is specified,
474 time to receive the
475 <link id="var_upstream_first_byte_time">first byte</link> of data is used.
476 If the <literal>last_byte</literal> is specified,
477 time to receive the
478 <link id="var_upstream_session_time">last byte</link> of data is used.
479 If the <literal>inflight</literal> parameter is specified (1.11.6),
480 incomplete connections are also taken into account.
481 <note>
482 Prior to version 1.11.6,
483 incomplete connections were taken into account by default.
484 </note>
485 </para>
486
487 <para>
488 <note>
489 This directive is available as part of our
490 <commercial_version>commercial subscription</commercial_version>.
491 </note>
492 </para>
493
494 </directive>
495
496
497 <directive name="random"> 268 <directive name="random">
498 <syntax>[<literal>two</literal> [<value>method</value>]]</syntax> 269 <syntax>[<literal>two</literal> [<value>method</value>]]</syntax>
499 <default/> 270 <default/>
500 <context>upstream</context> 271 <context>upstream</context>
501 <appeared-in>1.15.1</appeared-in> 272 <appeared-in>1.15.1</appeared-in>
515 The default method is <literal>least_conn</literal> 286 The default method is <literal>least_conn</literal>
516 which passes a connection to a server 287 which passes a connection to a server
517 with the least number of active connections. 288 with the least number of active connections.
518 </para> 289 </para>
519 290
520 <para id="random_least_time">
521 The <literal>least_time</literal> method passes a connection to a server
522 with the least average time and least number of active connections.
523 If <literal>least_time=connect</literal> parameter is specified,
524 time to
525 <link id="var_upstream_connect_time">connect</link>
526 to the upstream server is used.
527 If <literal>least_time=first_byte</literal> parameter is specified,
528 time to receive the
529 <link id="var_upstream_first_byte_time">first byte</link> of data is used.
530 If <literal>least_time=last_byte</literal> is specified,
531 time to receive the
532 <link id="var_upstream_session_time">last byte</link> of data is used.
533 <note>
534 The <literal>least_time</literal> method is available as a part of our
535 <commercial_version>commercial subscription</commercial_version>.
536 </note>
537 </para>
538
539 </directive>
540
541
542 <directive name="resolver">
543 <syntax>
544 <value>address</value> ...
545 [<literal>valid</literal>=<value>time</value>]
546 [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>]
547 [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]
548 [<literal>status_zone</literal>=<value>zone</value>]</syntax>
549 <default/>
550 <context>upstream</context>
551 <appeared-in>1.17.5</appeared-in>
552
553 <para>
554 Configures name servers used to resolve names of upstream servers
555 into addresses, for example:
556 <example>
557 resolver 127.0.0.1 [::1]:5353;
558 </example>
559 The address can be specified as a domain name or IP address,
560 with an optional port.
561 If port is not specified, the port 53 is used.
562 Name servers are queried in a round-robin fashion.
563 </para>
564
565 <para id="resolver_ipv6">
566 By default, nginx will look up both IPv4 and IPv6 addresses while resolving.
567 If looking up of IPv4 or IPv6 addresses is not desired,
568 the <literal>ipv4=off</literal> (1.23.1) or
569 the <literal>ipv6=off</literal> parameter can be specified.
570 </para>
571
572 <para id="resolver_valid">
573 By default, nginx caches answers using the TTL value of a response.
574 The optional <literal>valid</literal> parameter allows overriding it:
575 <example>
576 resolver 127.0.0.1 [::1]:5353 valid=30s;
577 </example>
578 <note>
579 To prevent DNS spoofing, it is recommended
580 configuring DNS servers in a properly secured trusted local network.
581 </note>
582 </para>
583
584 <para id="resolver_status_zone">
585 The optional <literal>status_zone</literal> parameter
586 enables
587 <link doc="../http/ngx_http_api_module.xml" id="resolvers_">collection</link>
588 of DNS server statistics of requests and responses
589 in the specified <value>zone</value>.
590 </para>
591
592 <para>
593 <note>
594 This directive is available as part of our
595 <commercial_version>commercial subscription</commercial_version>.
596 </note>
597 </para>
598
599 </directive>
600
601
602 <directive name="resolver_timeout">
603 <syntax><value>time</value></syntax>
604 <default>30s</default>
605 <context>upstream</context>
606 <appeared-in>1.17.5</appeared-in>
607
608 <para>
609 Sets a timeout for name resolution, for example:
610 <example>
611 resolver_timeout 5s;
612 </example>
613 </para>
614
615 <para>
616 <note>
617 This directive is available as part of our
618 <commercial_version>commercial subscription</commercial_version>.
619 </note>
620 </para>
621
622 </directive> 291 </directive>
623 292
624 </section> 293 </section>
625 294
626 295