Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 293:34246e706f48

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
English translation of the ngx_http_upstream_module documentation.
author Ruslan Ermilov <ru@nginx.com>
date Wed, 28 Dec 2011 19:01:03 +0000
parents
children 1fb1c077658b
comparison
equal deleted inserted replaced
292:7bc830cc79bb 293:34246e706f48
1 <?xml version="1.0"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="Module ngx_http_upstream_module"
6 link="/en/docs/http/ngx_http_upstream_module.html"
7 lang="en">
8
9 <section id="summary">
10
11 <para>
12 The <literal>ngx_http_upstream_module</literal> module
13 allows to define groups of servers that can be referenced
14 from the <link doc="ngx_http_proxy_module.xml" id="proxy_pass"/> and
15 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/> directives.
16 </para>
17
18 </section>
19
20
21 <section id="example" name="Example Configuration">
22
23 <para>
24 <example>
25 upstream <emphasis>backend</emphasis> {
26 server backend1.example.com weight=5;
27 server backend2.example.com:8080;
28 server unix:/tmp/backend3;
29
30 server backup1.example.com:8080 backup;
31 server backup2.example.com:8080 backup;
32 }
33
34 server {
35 location / {
36 proxy_pass http://<emphasis>backend</emphasis>;
37 }
38 }
39 </example>
40 </para>
41
42 </section>
43
44
45 <section id="directives" name="Directives">
46
47 <directive name="ip_hash">
48 <syntax/>
49 <default/>
50 <context>upstream</context>
51
52 <para>
53 Specifies that a group should use a balancing method where requests
54 are distributed between servers based on client IP addresses.
55 A class C network containing the client IP address is used as a hashing key.
56 The method ensures that requests of the same client will always be
57 passed to the same server except when this server is considered down
58 in which case client requests will be passed to another server and
59 most probably it will also be the same server.
60 </para>
61
62 <para>
63 It is not possible to specify a weight for servers using the
64 <literal>ip_hash</literal> balancing method.
65 If one of the servers needs to be temporarily removed, it should
66 be marked with the <literal>down</literal> parameter in
67 order to preserve the current hashing of client IP addresses.
68 </para>
69
70 <para>
71 Example:
72 <example>
73 upstream backend {
74 ip_hash;
75
76 server backend1.example.com;
77 server backend2.example.com;
78 server backend3.example.com <emphasis>down</emphasis>;
79 server backend4.example.com;
80 }
81 </example>
82 </para>
83
84 </directive>
85
86
87 <directive name="server">
88 <syntax><value>name</value> [<value>parameters</value>]</syntax>
89 <default/>
90 <context>upstream</context>
91
92 <para>
93 Sets a <value>name</value> and other <value>parameters</value> of the server.
94 A <value>name</value> can be a domain name, an address, a port, or a
95 path of the UNIX-domain socket.
96 If a domain name resolves to several addresses, all of them are used.
97 <list type="tag">
98
99 <tag-name><literal>weight</literal>=<value>number</value></tag-name>
100 <tag-desc>
101 sets a weight of the server, by default 1.
102 </tag-desc>
103
104 <tag-name><literal>max_fails</literal>=<value>number</value></tag-name>
105 <tag-desc>
106 sets a number of unsuccessful attempts to communicate with the server
107 during a time set by the <literal>fail_timeout</literal> parameter
108 after which it will be considered down for a period of time also set
109 by the <literal>fail_timeout</literal> parameter.
110 By default, the number of unsuccessful attempts is set to 1.
111 A value of zero disables accounting of attempts.
112 What is considered to be an unsuccessful attempt is configured by the
113 <link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>
114 and <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>
115 directives.
116 The <literal>http_404</literal> state is not considered
117 an unsuccessful attempt.
118 </tag-desc>
119
120 <tag-name><literal>fail_timeout</literal>=<value>time</value></tag-name>
121 <tag-desc>
122 sets
123 <list type="bullet">
124
125 <listitem>
126 a time during which the specified number of unsuccessful attempts to
127 communicate with the server should happen for the server to be
128 considered down;
129 </listitem>
130
131 <listitem>
132 and a period of time the server will be considered down.
133 </listitem>
134
135 </list>
136 By default, timeout is set to 10 seconds.
137 </tag-desc>
138
139 <tag-name><literal>backup</literal></tag-name>
140 <tag-desc>
141 marks the server as a backup server.
142 It will be passed requests when the primary servers are down.
143 </tag-desc>
144
145 <tag-name><literal>down</literal></tag-name>
146 <tag-desc>
147 marks the server as permanently down; used along with
148 the <link id="ip_hash"/> directive.
149 </tag-desc>
150
151 </list>
152 </para>
153
154 <para>
155 Example:
156 <example>
157 upstream backend {
158 server backend1.example.com weight=5;
159 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
160 server unix:/tmp/backend3;
161
162 server backup1.example.com:8080 backup;
163 }
164 </example>
165 </para>
166
167 </directive>
168
169
170 <directive name="upstream">
171 <syntax block="yes"><value>name</value></syntax>
172 <default/>
173 <context>http</context>
174
175 <para>
176 Defines a group of servers.
177 Servers can listen on different ports.
178 In addition, servers listening on TCP and UNIX-domain sockets
179 can be used simultaneously.
180 </para>
181
182 <para>
183 Example:
184 <example>
185 upstream backend {
186 server backend1.example.com weight=5;
187 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
188 server unix:/tmp/backend3;
189 }
190 </example>
191 </para>
192
193 <para>
194 Requests are distributed between servers in a round-robin fashion,
195 taking into account the weights of servers.
196 In the above example, each 7 requests will be distributed as follows:
197 5 requests to <literal>backend1.example.com</literal>
198 and one request to each of second and third servers.
199 If an error occurs when communicating with the server, a request will
200 be passed to the next server, and so on until all of the functioning
201 servers will be tried.
202 If a successful response could not be obtained from any of the servers,
203 the client will be returned the result of contacting the last server.
204 </para>
205
206 </directive>
207
208 </section>
209
210
211 <section id="variables" name="Embedded Variables">
212
213 <para>
214 The <literal>ngx_http_upstream_module</literal> module
215 supports the following embedded variables:
216 <list type="tag">
217
218 <tag-name><var>$upstream_addr</var></tag-name>
219 <tag-desc>
220 keeps an IP address and port of the server,
221 or a path to the UNIX-domain socket.
222 If several servers were contacted during request processing,
223 their addresses are separated by commas, e.g.
224 “<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock</literal>”.
225 If an internal redirect from one server group to another happened
226 using
227 <header>X-Accel-Redirect</header> or
228 <link doc="ngx_http_core_module.xml" id="error_page"/>
229 then these server groups are separated by colons, e.g.
230 “<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80</literal>”.
231 </tag-desc>
232
233 <tag-name><var>$upstream_response_time</var></tag-name>
234 <tag-desc>
235 keeps servers response times in seconds with a milliseconds resolution.
236 Several responses are also separated by commas and colons.
237 </tag-desc>
238
239 <tag-name><var>$upstream_status</var></tag-name>
240 <tag-desc>
241 keeps servers response codes.
242 Several responses are also separated by commas and colons.
243 </tag-desc>
244
245 <tag-name><var>$upstream_http_...</var></tag-name>
246 <tag-desc>
247 keep server response header fields.
248 For example, the <header>Server</header> response header field
249 is made available through the <var>$upstream_http_server</var> variable.
250 Note that only the last server’s response header fields are saved.
251 </tag-desc>
252
253 </list>
254 </para>
255
256 </section>
257
258 </module>