Mercurial > hg > nginx-site
comparison xml/en/docs/stream/ngx_stream_upstream_module.xml @ 1367:f1e14d87d833
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> |