Mercurial > hg > nginx-site

comparison xml/en/docs/stream/ngx_stream_upstream_module.xml @ 1367:f1e14d87d833

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 Mon, 01 Dec 2014 13:40:25 +0300
parents
children 4569719f4247
comparison
equal deleted inserted replaced
1366:f3b7ec81b738 1367:f1e14d87d833
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) 2014 Yaroslav Zhuravlev
5 Copyright (C) Nginx, Inc.
6 -->
7
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
9
10 <module name="Module ngx_stream_upstream_module"
11 link="/en/docs/stream/ngx_stream_upstream_module.html"
12 lang="en"
13 rev="1">
14
15 <section id="summary">
16
17 <para>
18 The <literal>ngx_stream_upstream_module</literal> module (1.7.7)
19 is used to define groups of servers that can be referenced
20 by the <link doc="ngx_stream_module.xml" id="proxy_pass"/>
21 directive.
22 </para>
23
24 <para>
25 <note>
26 This module is available as part of our
27 <commercial_version>commercial subscription</commercial_version>.
28 </note>
29 </para>
30
31 </section>
32
33
34 <section id="example" name="Example Configuration">
35
36 <para>
37 <example>
38 stream {
39 upstream backend {
40 hash $remote_addr consistent;
41 server backend1.example.com:8000;
42 server backend2.example.com:8000;
43 server backend3.example.com:8001;
44 }
45
46 server {
47 listen 9000;
48 proxy_pass backend;
49 }
50 }
51 </example>
52 </para>
53
54 </section>
55
56
57 <section id="directives" name="Directives">
58
59 <directive name="upstream">
60 <syntax block="yes"><value>name</value></syntax>
61 <default/>
62 <context>stream</context>
63
64 <para>
65 Defines a group of servers.
66 Servers can listen on different ports.
67 In addition, servers listening on TCP and UNIX-domain sockets
68 can be mixed.
69 </para>
70
71 <para>
72 Example:
73 <example>
74 upstream backend {
75 server backend1.example.com:8080 weight=5;
76 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
77 server unix:/tmp/backend3;
78
79 server backup1.example.com:8080 backup;
80 }
81 </example>
82 </para>
83
84 <para>
85 By default, connections are distributed between the servers using a
86 weighted round-robin balancing method.
87 In the above example, each 7 connections will be distributed as follows:
88 5 connections go to <literal>backend1.example.com</literal>
89 and one connection to each of the second and third servers.
90 If an error occurs during communication with a server, the connection will
91 be passed to the next server, and so on until all of the functioning
92 servers will be tried.
93 If communication with all servers fails, the connection will be closed.
94 </para>
95
96 </directive>
97
98
99 <directive name="server">
100 <syntax><value>address</value> [<value>parameters</value>]</syntax>
101 <default/>
102 <context>upstream</context>
103
104 <para>
105 Defines the <value>address</value> and other <value>parameters</value>
106 of a server.
107 The address can be specified as a domain name or IP address
108 with an obligatory port, or as a UNIX-domain socket path
109 specified after the “<literal>unix:</literal>” prefix.
110 A domain name that resolves to several IP addresses defines
111 multiple servers at once.
112 </para>
113
114 <para>
115 The following parameters can be defined:
116 <list type="tag">
117
118 <tag-name id="weight">
119 <literal>weight</literal>=<value>number</value>
120 </tag-name>
121 <tag-desc>
122 sets the weight of the server, by default, 1.
123 </tag-desc>
124
125 <tag-name id="max_fails">
126 <literal>max_fails</literal>=<value>number</value>
127 </tag-name>
128 <tag-desc>
129 sets the number of unsuccessful attempts to communicate with the server
130 that should happen in the duration set by the <literal>fail_timeout</literal>
131 parameter to consider the server unavailable for a duration also set by the
132 <literal>fail_timeout</literal> parameter.
133 By default, the number of unsuccessful attempts is set to 1.
134 The zero value disables the accounting of attempts.
135 Here, an unsuccessful attempt is an error or timeout
136 while establishing a connection with the server.
137 </tag-desc>
138
139 <tag-name id="fail_timeout">
140 <literal>fail_timeout</literal>=<value>time</value>
141 </tag-name>
142 <tag-desc>
143 sets
144 <list type="bullet">
145
146 <listitem>
147 the time during which the specified number of unsuccessful attempts to
148 communicate with the server should happen to consider the server unavailable;
149 </listitem>
150
151 <listitem>
152 and the period of time the server will be considered unavailable.
153 </listitem>
154
155 </list>
156 By default, the parameter is set to 10 seconds.
157 </tag-desc>
158
159 <tag-name id="backup">
160 <literal>backup</literal>
161 </tag-name>
162 <tag-desc>
163 marks the server as a backup server.
164 Connections to the backup server will be passed
165 when the primary servers are unavailable.
166 </tag-desc>
167
168 <tag-name id="down">
169 <literal>down</literal>
170 </tag-name>
171 <tag-desc>
172 marks the server as permanently unavailable; used along with
173 the <link id="hash"/> directive.
174 </tag-desc>
175
176 <tag-name id="max_conns">
177 <literal>max_conns</literal>=<value>number</value>
178 </tag-name>
179 <tag-desc>
180 limits the maximum <value>number</value> of simultaneous connections to the
181 proxied server.
182 Default value is zero, meaning there is no limit.
183 </tag-desc>
184
185 <tag-name id="slow_start">
186 <literal>slow_start</literal>=<value>time</value>
187 </tag-name>
188 <tag-desc>
189 sets the <value>time</value> during which the server will recover its weight
190 from zero to a nominal value,
191 or when the server becomes available after a period of time
192 it was considered <link id="fail_timeout">unavailable</link>.
193 Default value is zero, i.e. slow start is disabled.
194 </tag-desc>
195
196 </list>
197 </para>
198
199 <para>
200 <note>
201 If there is only a single server in a group, <literal>max_fails</literal>,
202 <literal>fail_timeout</literal> and <literal>slow_start</literal> parameters
203 are ignored, and such a server will never be considered unavailable.
204 </note>
205 </para>
206
207 </directive>
208
209
210 <directive name="hash">
211 <syntax><value>key</value> [<literal>consistent</literal>]</syntax>
212 <default/>
213 <context>upstream</context>
214
215 <para>
216 Specifies a load balancing method for a server group
217 where client-server mapping is based on the hashed <value>key</value> value.
218 Currently, the only supported value for the <literal>key</literal>
219 is the client remote address specified as <literal>$remote_addr</literal>.
220 Note that adding or removing a server from the group
221 may result in remapping most of the keys to different servers.
222 The method is compatible with the
223 <link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached">Cache::Memcached</link>
224 Perl library.
225 </para>
226
227 <para>
228 If the <literal>consistent</literal> parameter is specified,
229 the <link url="http://www.last.fm/user/RJ/journal/2007/04/10/392555/">ketama</link>
230 consistent hashing method will be used instead.
231 The method ensures that only a few keys
232 will be remapped to different servers
233 when a server is added to or removed from the group.
234 This helps to achieve a higher cache hit ratio for caching servers.
235 The method is compatible with the
236 <link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached%3A%3AFast">Cache::Memcached::Fast</link>
237 Perl library with the <value>ketama_points</value> parameter set to 160.
238 </para>
239
240 </directive>
241
242
243 <directive name="least_conn">
244 <syntax/>
245 <default/>
246 <context>upstream</context>
247
248 <para>
249 Specifies that a server group should use a load balancing method
250 where a connection
251 is passed to the server with the least number of active connections,
252 taking into account weights of servers.
253 If there are several such servers, they are tried in turn using a
254 weighted round-robin balancing method.
255 </para>
256
257 </directive>
258
259 </section>
260
261 </module>