Mercurial > hg > nginx-site

annotate 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
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
1 <?xml version="1.0"?>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
2
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
3 <!--
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
4 Copyright (C) Nginx, Inc.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
5 -->
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
6
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
8
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
9 <module name="Module ngx_stream_upstream_module"
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
10 link="/en/docs/stream/ngx_stream_upstream_module.html"
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
11 lang="en"
3043
9eadb98ec770 Free nginx: removed commercial version documentation.
Maxim Dounin <mdounin@mdounin.ru>
parents: 2914
diff changeset
12 rev="40">
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
13
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
14 <section id="summary">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
15
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
16 <para>
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
17 The <literal>ngx_stream_upstream_module</literal> module (1.9.0)
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
18 is used to define groups of servers that can be referenced
1405
4569719f4247 Split stream module into stream_core and stream_proxy modules.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1367
diff changeset
19 by the <link doc="ngx_stream_proxy_module.xml" id="proxy_pass"/>
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
20 directive.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
21 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
22
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
23 </section>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
24
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
25
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
26 <section id="example" name="Example Configuration">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
27
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
28 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
29 <example>
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
30 upstream <emphasis>backend</emphasis> {
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
31 hash $remote_addr consistent;
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
32
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
33 server backend1.example.com:12345 weight=5;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
34 server backend2.example.com:12345;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
35 server unix:/tmp/backend3;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
36
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
37 server backup1.example.com:12345 backup;
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
38 server backup2.example.com:12345 backup;
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
39 }
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
40
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
41 server {
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
42 listen 12346;
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
43 proxy_pass <emphasis>backend</emphasis>;
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
44 }
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
45 </example>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
46 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
47
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
48 </section>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
49
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
50
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
51 <section id="directives" name="Directives">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
52
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
53 <directive name="upstream">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
54 <syntax block="yes"><value>name</value></syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
55 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
56 <context>stream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
57
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
58 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
59 Defines a group of servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
60 Servers can listen on different ports.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
61 In addition, servers listening on TCP and UNIX-domain sockets
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
62 can be mixed.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
63 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
64
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
65 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
66 Example:
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
67 <example>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
68 upstream backend {
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
69 server backend1.example.com:12345 weight=5;
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
70 server 127.0.0.1:12345 max_fails=3 fail_timeout=30s;
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
71 server unix:/tmp/backend2;
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
72 server backend3.example.com:12345 resolve;
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
73
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
74 server backup1.example.com:12345 backup;
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
75 }
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
76 </example>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
77 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
78
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
79 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
80 By default, connections are distributed between the servers using a
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
81 weighted round-robin balancing method.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
82 In the above example, each 7 connections will be distributed as follows:
1406
ea73cd9d4cdb Changed stream_upstream examples.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1405
diff changeset
83 5 connections go to <literal>backend1.example.com:12345</literal>
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
84 and one connection to each of the second and third servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
85 If an error occurs during communication with a server, the connection will
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
86 be passed to the next server, and so on until all of the functioning
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
87 servers will be tried.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
88 If communication with all servers fails, the connection will be closed.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
89 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
90
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
91 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
92
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
93
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
94 <directive name="server">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
95 <syntax><value>address</value> [<value>parameters</value>]</syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
96 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
97 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
98
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
99 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
100 Defines the <value>address</value> and other <value>parameters</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
101 of a server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
102 The address can be specified as a domain name or IP address
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
103 with an obligatory port, or as a UNIX-domain socket path
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
104 specified after the “<literal>unix:</literal>” prefix.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
105 A domain name that resolves to several IP addresses defines
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
106 multiple servers at once.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
107 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
108
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
109 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
110 The following parameters can be defined:
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
111 <list type="tag">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
112
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
113 <tag-name id="weight">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
114 <literal>weight</literal>=<value>number</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
115 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
116 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
117 sets the weight of the server, by default, 1.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
118 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
119
1800
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
120 <tag-name id="max_conns">
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
121 <literal>max_conns</literal>=<value>number</value>
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
122 </tag-name>
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
123 <tag-desc>
1801
592f9fa804f6 Added info about shared memory to max_conns.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1800
diff changeset
124 limits the maximum <value>number</value> of simultaneous
592f9fa804f6 Added info about shared memory to max_conns.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1800
diff changeset
125 connections to the proxied server (1.11.5).
1800
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
126 Default value is zero, meaning there is no limit.
1801
592f9fa804f6 Added info about shared memory to max_conns.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1800
diff changeset
127 If the server group does not reside in the <link id="zone">shared memory</link>,
592f9fa804f6 Added info about shared memory to max_conns.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1800
diff changeset
128 the limitation works per each worker process.
1800
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
129 </tag-desc>
9d722e4153ab Documented the "max_conns" parameter as opensource.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1774
diff changeset
130
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
131 <tag-name id="max_fails">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
132 <literal>max_fails</literal>=<value>number</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
133 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
134 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
135 sets the number of unsuccessful attempts to communicate with the server
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
136 that should happen in the duration set by the <literal>fail_timeout</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
137 parameter to consider the server unavailable for a duration also set by the
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
138 <literal>fail_timeout</literal> parameter.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
139 By default, the number of unsuccessful attempts is set to 1.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
140 The zero value disables the accounting of attempts.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
141 Here, an unsuccessful attempt is an error or timeout
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
142 while establishing a connection with the server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
143 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
144
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
145 <tag-name id="fail_timeout">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
146 <literal>fail_timeout</literal>=<value>time</value>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
147 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
148 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
149 sets
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
150 <list type="bullet">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
151
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
152 <listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
153 the time during which the specified number of unsuccessful attempts to
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
154 communicate with the server should happen to consider the server unavailable;
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
155 </listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
156
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
157 <listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
158 and the period of time the server will be considered unavailable.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
159 </listitem>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
160
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
161 </list>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
162 By default, the parameter is set to 10 seconds.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
163 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
164
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
165 <tag-name id="backup">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
166 <literal>backup</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
167 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
168 <tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
169 marks the server as a backup server.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
170 Connections to the backup server will be passed
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
171 when the primary servers are unavailable.
2434
a1f61586779b Listed not supported load balancing methods in upstream backup.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2418
diff changeset
172 <note>
a1f61586779b Listed not supported load balancing methods in upstream backup.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2418
diff changeset
173 The parameter cannot be used along with the
a1f61586779b Listed not supported load balancing methods in upstream backup.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2418
diff changeset
174 <link id="hash"/> and <link id="random"/> load balancing methods.
a1f61586779b Listed not supported load balancing methods in upstream backup.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2418
diff changeset
175 </note>
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
176 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
177
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
178 <tag-name id="down">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
179 <literal>down</literal>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
180 </tag-name>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
181 <tag-desc>
1410
f5dcc23b214f Deleted info about hash and ip_hash from the down parameter.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1406
diff changeset
182 marks the server as permanently unavailable.
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
183 </tag-desc>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
184
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
185 </list>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
186 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
187
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
188 <para>
1817
0160e8784417 Documented behavior of server slow_start with ip_hash and hash.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1809
diff changeset
189 <note>
3043
9eadb98ec770 Free nginx: removed commercial version documentation.
Maxim Dounin <mdounin@mdounin.ru>
parents: 2914
diff changeset
190 If there is only a single server in a group,
9eadb98ec770 Free nginx: removed commercial version documentation.
Maxim Dounin <mdounin@mdounin.ru>
parents: 2914
diff changeset
191 <literal>max_fails</literal> and <literal>fail_timeout</literal> parameters
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
192 are ignored, and such a server will never be considered unavailable.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
193 </note>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
194 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
195
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
196 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
197
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
198
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
199 <directive name="zone">
1495
8d134b482cc3 Documented zone usage with many upstreams.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1462
diff changeset
200 <syntax><value>name</value> [<value>size</value>]</syntax>
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
201 <default/>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
202 <context>upstream</context>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
203
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
204 <para>
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
205 Defines the <value>name</value> and <value>size</value> of the shared
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
206 memory zone that keeps the group’s configuration and run-time state that are
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
207 shared between worker processes.
1495
8d134b482cc3 Documented zone usage with many upstreams.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1462
diff changeset
208 Several groups may share the same zone.
2281
1445fc690c16 Amend the "zone" directive description in stream.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2275
diff changeset
209 In this case, it is enough to specify the <value>size</value> only once.
1462
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
210 </para>
e69e4dbcc760 Documented OSS stream modules.
Vladimir Homutov <vl@nginx.com>
parents: 1450
diff changeset
211
1636
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
212 </directive>
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
213
44c4323144c5 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 1581
diff changeset
214
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
215 <directive name="hash">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
216 <syntax><value>key</value> [<literal>consistent</literal>]</syntax>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
217 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
218 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
219
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
220 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
221 Specifies a load balancing method for a server group
2282
35fd70c12f98 Resynchronized the http and stream upstream module versions.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2281
diff changeset
222 where the client-server mapping is based on the hashed <value>key</value> value.
1744
ab56dcd73af2 Added variables to stream hash, limit_conn_zone, proxy_bind.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1727
diff changeset
223 The <value>key</value> can contain text, variables,
ab56dcd73af2 Added variables to stream hash, limit_conn_zone, proxy_bind.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1727
diff changeset
224 and their combinations (1.11.2).
ab56dcd73af2 Added variables to stream hash, limit_conn_zone, proxy_bind.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1727
diff changeset
225 Usage example:
ab56dcd73af2 Added variables to stream hash, limit_conn_zone, proxy_bind.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1727
diff changeset
226 <example>
ab56dcd73af2 Added variables to stream hash, limit_conn_zone, proxy_bind.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1727
diff changeset
227 hash $remote_addr;
ab56dcd73af2 Added variables to stream hash, limit_conn_zone, proxy_bind.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1727
diff changeset
228 </example>
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
229 Note that adding or removing a server from the group
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
230 may result in remapping most of the keys to different servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
231 The method is compatible with the
2275
d93c8c32df75 Updated links to CPAN search interface.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2274
diff changeset
232 <link url="https://metacpan.org/pod/Cache::Memcached">Cache::Memcached</link>
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
233 Perl library.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
234 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
235
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
236 <para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
237 If the <literal>consistent</literal> parameter is specified,
2274
e28e3d0f0d20 Updated link in the "hash" directive.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2230
diff changeset
238 the <link url="https://www.metabrew.com/article/libketama-consistent-hashing-algo-memcached-clients">ketama</link>
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
239 consistent hashing method will be used instead.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
240 The method ensures that only a few keys
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
241 will be remapped to different servers
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
242 when a server is added to or removed from the group.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
243 This helps to achieve a higher cache hit ratio for caching servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
244 The method is compatible with the
2275
d93c8c32df75 Updated links to CPAN search interface.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2274
diff changeset
245 <link url="https://metacpan.org/pod/Cache::Memcached::Fast">Cache::Memcached::Fast</link>
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
246 Perl library with the <value>ketama_points</value> parameter set to 160.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
247 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
248
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
249 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
250
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
251
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
252 <directive name="least_conn">
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
253 <syntax/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
254 <default/>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
255 <context>upstream</context>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
256
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
257 <para>
2282
35fd70c12f98 Resynchronized the http and stream upstream module versions.
Sergey Kandaurov <pluknet@nginx.com>
parents: 2281
diff changeset
258 Specifies that a group should use a load balancing method where a connection
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
259 is passed to the server with the least number of active connections,
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
260 taking into account weights of servers.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
261 If there are several such servers, they are tried in turn using a
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
262 weighted round-robin balancing method.
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
263 </para>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
264
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
265 </directive>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
266
1450
f5b5eefc43cb Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents: 1410
diff changeset
267
2191
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
268 <directive name="random">
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
269 <syntax>[<literal>two</literal> [<value>method</value>]]</syntax>
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
270 <default/>
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
271 <context>upstream</context>
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
272 <appeared-in>1.15.1</appeared-in>
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
273
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
274 <para>
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
275 Specifies that a group should use a load balancing method where a connection
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
276 is passed to a randomly selected server, taking into account weights
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
277 of servers.
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
278 </para>
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
279
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
280 <para>
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
281 The optional <literal>two</literal> parameter
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
282 instructs nginx to randomly select
2197
03f8a9c5e8ae Updated link in the "random" directive.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2196
diff changeset
283 <link url="https://homes.cs.washington.edu/~karlin/papers/balls.pdf">two</link>
2191
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
284 servers and then choose a server
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
285 using the specified <literal>method</literal>.
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
286 The default method is <literal>least_conn</literal>
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
287 which passes a connection to a server
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
288 with the least number of active connections.
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
289 </para>
2c56f91c304a Documented the "random" directive.
Vladimir Homutov <vl@nginx.com>
parents: 2097
diff changeset
290
2469
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2434
diff changeset
291 </directive>
98fd810c13e0 Updated docs for the upcoming NGINX Plus release.
Ruslan Ermilov <ru@nginx.com>
parents: 2434
diff changeset
292
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
293 </section>
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
294
1772
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
295
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
296 <section id="variables" name="Embedded Variables">
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
297
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
298 <para>
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
299 The <literal>ngx_stream_upstream_module</literal> module
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
300 supports the following embedded variables:
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
301 <list type="tag">
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
302
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
303 <tag-name id="var_upstream_addr"><var>$upstream_addr</var></tag-name>
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
304 <tag-desc>
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
305 keeps the IP address and port,
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
306 or the path to the UNIX-domain socket of the upstream server (1.11.4).
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
307 If several servers were contacted during proxying,
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
308 their addresses are separated by commas, e.g.
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
309 “<literal>192.168.1.1:12345, 192.168.1.2:12345, unix:/tmp/sock</literal>”.
2058
eb58ee50561d Documented upstream name in $upstream_addr.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1947
diff changeset
310 If a server cannot be selected,
eb58ee50561d Documented upstream name in $upstream_addr.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1947
diff changeset
311 the variable keeps the name of the server group.
1772
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
312 </tag-desc>
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
313
2308
956685eb1d43 Reordered $upstream_bytes_ variables aphabetically in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2300
diff changeset
314 <tag-name id="var_upstream_bytes_received"><var>$upstream_bytes_received</var></tag-name>
1773
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
315 <tag-desc>
2308
956685eb1d43 Reordered $upstream_bytes_ variables aphabetically in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2300
diff changeset
316 number of bytes received from an upstream server (1.11.4).
1773
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
317 Values from several connections
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
318 are separated by commas like addresses in the
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
319 <link id="var_upstream_addr">$upstream_addr</link> variable.
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
320 </tag-desc>
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
321
2308
956685eb1d43 Reordered $upstream_bytes_ variables aphabetically in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2300
diff changeset
322 <tag-name id="var_upstream_bytes_sent"><var>$upstream_bytes_sent</var></tag-name>
1773
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
323 <tag-desc>
2308
956685eb1d43 Reordered $upstream_bytes_ variables aphabetically in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 2300
diff changeset
324 number of bytes sent to an upstream server (1.11.4).
1773
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
325 Values from several connections
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
326 are separated by commas like addresses in the
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
327 <link id="var_upstream_addr">$upstream_addr</link> variable.
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
328 </tag-desc>
9c48a717e001 Documented $upstream_bytes_sent, $upstream_bytes_received in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1772
diff changeset
329
1774
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
330 <tag-name id="var_upstream_connect_time"><var>$upstream_connect_time</var></tag-name>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
331 <tag-desc>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
332 time to connect to the upstream server (1.11.4);
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
333 the time is kept in seconds with millisecond resolution.
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
334 Times of several connections
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
335 are separated by commas like addresses in the
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
336 <link id="var_upstream_addr">$upstream_addr</link> variable.
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
337 </tag-desc>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
338
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
339 <tag-name id="var_upstream_first_byte_time"><var>$upstream_first_byte_time</var></tag-name>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
340 <tag-desc>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
341 time to receive the first byte of data (1.11.4);
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
342 the time is kept in seconds with millisecond resolution.
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
343 Times of several connections
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
344 are separated by commas like addresses in the
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
345 <link id="var_upstream_addr">$upstream_addr</link> variable.
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
346 </tag-desc>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
347
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
348 <tag-name id="var_upstream_session_time"><var>$upstream_session_time</var></tag-name>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
349 <tag-desc>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
350 session duration in seconds with millisecond resolution (1.11.4).
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
351 Times of several connections
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
352 are separated by commas like addresses in the
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
353 <link id="var_upstream_addr">$upstream_addr</link> variable.
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
354 </tag-desc>
e1e0c5b27515 Documented $upstream_connect_time, $upstream_first_byte_time, $upstream_session_time.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1773
diff changeset
355
1772
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
356 </list>
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
357 </para>
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
358
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
359 </section>
536dc1885e24 Documented the $upstream_addr variable in stream.
Yaroslav Zhuravlev <yar@nginx.com>
parents: 1744
diff changeset
360
1367
f1e14d87d833 Updated commercial docs for the upcoming release.
Ruslan Ermilov <ru@nginx.com>
parents:
diff changeset
361 </module>