1Name
2 nginx_http_upstream_check_module - support upstream health check with
3 Nginx
4
5Synopsis
6 http {
7
8 upstream cluster {
9
10 # simple round-robin
11 server 192.168.0.1:80;
12 server 192.168.0.2:80;
13
14 check interval=5000 rise=1 fall=3 timeout=4000;
15
16 #check interval=3000 rise=2 fall=5 timeout=1000 type=ssl_hello;
17
18 #check interval=3000 rise=2 fall=5 timeout=1000 type=http;
19 #check_http_send "HEAD / HTTP/1.0\r\n\r\n";
20 #check_http_expect_alive http_2xx http_3xx;
21 }
22
23 server {
24 listen 80;
25
26 location / {
27 proxy_pass http://cluster;
28 }
29
30 location /status {
31 check_status;
32
33 access_log off;
34 allow SOME.IP.ADD.RESS;
35 deny all;
36 }
37 }
38
39 }
40
41Description
42 Add the support of health check with the upstream servers.
43
44Directives
45 check
46 syntax: *check interval=milliseconds [fall=count] [rise=count]
47 [timeout=milliseconds] [default_down=true|false]
48 [type=tcp|http|ssl_hello|mysql|ajp|fastcgi]*
49
50 default: *none, if parameters omitted, default parameters are
51 interval=30000 fall=5 rise=2 timeout=1000 default_down=true type=tcp*
52
53 context: *upstream*
54
55 description: Add the health check for the upstream servers.
56
57 The parameters' meanings are:
58
59 * *interval*: the check request's interval time.
60
61 * *fall*(fall_count): After fall_count check failures, the server is
62 marked down.
63
64 * *rise*(rise_count): After rise_count check success, the server is
65 marked up.
66
67 * *timeout*: the check request's timeout.
68
69 * *default_down*: set initial state of backend server, default is
70 down.
71
72 * *port*: specify the check port in the backend servers. It can be
73 different with the original servers port. Default the port is 0 and
74 it means the same as the original backend server.
75
76 * *type*: the check protocol type:
77
78 1. *tcp* is a simple tcp socket connect and peek one byte.
79
80 2. *ssl_hello* sends a client ssl hello packet and receives the
81 server ssl hello packet.
82
83 3. *http* sends a http request packet, receives and parses the http
84 response to diagnose if the upstream server is alive.
85
86 4. *mysql* connects to the mysql server, receives the greeting
87 response to diagnose if the upstream server is alive.
88
89 5. *ajp* sends a AJP Cping packet, receives and parses the AJP
90 Cpong response to diagnose if the upstream server is alive.
91
92 6. *fastcgi* send a fastcgi request, receives and parses the
93 fastcgi response to diagnose if the upstream server is alive.
94
95 check_http_send
96 syntax: *check_http_send http_packet*
97
98 default: *"GET / HTTP/1.0\r\n\r\n"*
99
100 context: *upstream*
101
102 description: If you set the check type is http, then the check function
103 will sends this http packet to check the upstream server.
104
105 check_http_expect_alive
106 syntax: *check_http_expect_alive [ http_2xx | http_3xx | http_4xx |
107 http_5xx ]*
108
109 default: *http_2xx | http_3xx*
110
111 context: *upstream*
112
113 description: These status codes indicate the upstream server's http
114 response is ok, the backend is alive.
115
116 check_keepalive_requests
117 syntax: *check_keepalive_requests num*
118
119 default: *check_keepalive_requests 1*
120
121 context: *upstream*
122
123 description: The directive specifies the number of requests sent on a
124 connection, the default vaule 1 indicates that nginx will certainly
125 close the connection after a request.
126
127 check_fastcgi_param
128 Syntax: *check_fastcgi_params parameter value*
129
130 default: see below
131
132 context: *upstream*
133
134 description: If you set the check type is fastcgi, then the check
135 function will sends this fastcgi headers to check the upstream server.
136 The default directive looks like:
137
138 check_fastcgi_param "REQUEST_METHOD" "GET";
139 check_fastcgi_param "REQUEST_URI" "/";
140 check_fastcgi_param "SCRIPT_FILENAME" "index.php";
141
142 check_shm_size
143 syntax: *check_shm_size size*
144
145 default: *1M*
146
147 context: *http*
148
149 description: Default size is one megabytes. If you check thousands of
150 servers, the shared memory for health check may be not enough, you can
151 enlarge it with this directive.
152
153 check_status
154 syntax: *check_status [html|csv|json]*
155
156 default: *none*
157
158 context: *location*
159
160 description: Display the health checking servers' status by HTTP. This
161 directive should be set in the http block.
162
163 You can specify the default display format. The formats can be `html`,
164 `csv` or `json`. The default type is `html`. It also supports to specify
165 the format by the request argument. Suppose your `check_status` location
166 is '/status', the argument of `format` can change the display page's
167 format. You can do like this:
168
169 /status?format=html
170 /status?format=csv
171 /status?format=json
172
173 At present, you can fetch the list of servers with the same status by
174 the argument of `status`. For example:
175
176 /status?format=html&status=down
177 /status?format=csv&status=up
178
179 Below it's the sample html page:
180
181 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN
182 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
183 <title>Nginx http upstream check status</title>
184 <h1>Nginx http upstream check status</h1>
185 <h2>Check upstream server number: 1, generation: 3</h2>
186 <th>Index</th>
187 <th>Upstream</th>
188 <th>Name</th>
189 <th>Status</th>
190 <th>Rise counts</th>
191 <th>Fall counts</th>
192 <th>Check type</th>
193 <th>Check port</th>
194 <td>0</td>
195 <td>backend</td>
196 <td>106.187.48.116:80</td>
197 <td>up</td>
198 <td>39</td>
199 <td>0</td>
200 <td>http</td>
201 <td>80</td>
202
203 Below it's the sample of csv page:
204
205 0,backend,106.187.48.116:80,up,46,0,http,80
206
207 Below it's the sample of json page:
208
209 {"servers": {
210 "total": 1,
211 "generation": 3,
212 "server": [
213 {"index": 0, "upstream": "backend", "name": "106.187.48.116:80", "status": "up", "rise": 58, "fall": 0, "type": "http", "port": 80}
214 ]
215 }}
216
217Installation
218 Download the latest version of the release tarball of this module from
219 github (<http://github.com/yaoweibin/nginx_upstream_check_module>)
220
221 Grab the nginx source code from nginx.org (<http://nginx.org/>), for
222 example, the version 1.0.14 (see nginx compatibility), and then build
223 the source with this module:
224
225 $ wget 'http://nginx.org/download/nginx-1.0.14.tar.gz'
226 $ tar -xzvf nginx-1.0.14.tar.gz
227 $ cd nginx-1.0.14/
228 $ patch -p1 < /path/to/nginx_http_upstream_check_module/check.patch
229
230 $ ./configure --add-module=/path/to/nginx_http_upstream_check_module
231
232 $ make
233 $ make install
234
235Note
236 If you use nginx-1.2.1 or nginx-1.3.0, the nginx upstream round robin
237 module changed greatly. You should use the patch named
238 'check_1.2.1.patch'.
239
240 If you use nginx-1.2.2+ or nginx-1.3.1+, It added the upstream
241 least_conn module. You should use the patch named 'check_1.2.2+.patch'.
242
243 If you use nginx-1.2.6+ or nginx-1.3.9+, It adjusted the round robin
244 module. You should use the patch named 'check_1.2.6+.patch'.
245
246 If you use nginx-1.5.12+, You should use the patch named
247 'check_1.5.12+.patch'.
248
249 If you use nginx-1.7.2+, You should use the patch named
250 'check_1.7.2+.patch'.
251
252 The patch just adds the support for the official Round-Robin, Ip_hash
253 and least_conn upstream module. But it's easy to expand my module to
254 other upstream modules. See the patch for detail.
255
256 If you want to add the support for upstream fair module, you can do it
257 like this:
258
259 $ git clone git://github.com/gnosek/nginx-upstream-fair.git
260 $ cd nginx-upstream-fair
261 $ patch -p2 < /path/to/nginx_http_upstream_check_module/upstream_fair.patch
262 $ cd /path/to/nginx-1.0.14
263 $ ./configure --add-module=/path/to/nginx_http_upstream_check_module --add-module=/path/to/nginx-upstream-fair-module
264 $ make
265 $ make install
266
267 If you want to add the support for nginx sticky module, you can do it
268 like this:
269
270 $ svn checkout http://nginx-sticky-module.googlecode.com/svn/trunk/ nginx-sticky-module
271 $ cd nginx-sticky-module
272 $ patch -p0 < /path/to/nginx_http_upstream_check_module/nginx-sticky-module.patch
273 $ cd /path/to/nginx-1.0.14
274 $ ./configure --add-module=/path/to/nginx_http_upstream_check_module --add-module=/path/to/nginx-sticky-module
275 $ make
276 $ make install
277
278 Note that, the nginx-sticky-module also needs the original check.patch.
279
280Compatibility
281 * The module version 0.1.5 should be compatibility with 0.7.67+
282
283 * The module version 0.1.8 should be compatibility with Nginx-1.0.14+
284
285Notes
286TODO
287Known Issues
288Changelogs
289 v0.3
290 * support keepalive check requests
291
292 * fastcgi check requests
293
294 * json/csv check status page support
295
296 v0.1
297 * first release
298
299Authors
300 Weibin Yao(姚伟斌) *yaoweibin at gmail dot com*
301
302 Matthieu Tourne
303
304Copyright & License
305 This README template copy from agentzh (<http://github.com/agentzh>).
306
307 The health check part is borrowed the design of Jack Lindamood's
308 healthcheck module healthcheck_nginx_upstreams
309 (<http://github.com/cep21/healthcheck_nginx_upstreams>);
310
311 This module is licensed under the BSD license.
312
313 Copyright (C) 2014 by Weibin Yao <yaoweibin@gmail.com>
314
315 Copyright (C) 2010-2014 Alibaba Group Holding Limited
316
317 Copyright (C) 2014 by LiangBin Li
318
319 Copyright (C) 2014 by Zhuo Yuan
320
321 Copyright (C) 2012 by Matthieu Tourne
322
323 All rights reserved.
324
325 Redistribution and use in source and binary forms, with or without
326 modification, are permitted provided that the following conditions are
327 met:
328
329 * Redistributions of source code must retain the above copyright
330 notice, this list of conditions and the following disclaimer.
331
332 * Redistributions in binary form must reproduce the above copyright
333 notice, this list of conditions and the following disclaimer in the
334 documentation and/or other materials provided with the distribution.
335
336 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
337 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
338 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
339 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
340 HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
341 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
342 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
343 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
344 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
345 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
346 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
347
348