Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 293:34246e706f48
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> |