ngx_http_upstream_check_module

Add proactive health check for the upstream servers.

This module is not built by default before Tengine-1.4.0, it should be enabled with the --with-http_upstream_check_module configuration parameter.

Examples
http {
    upstream cluster1 {
        # simple round-robin
        server 192.168.0.1:80;
        server 192.168.0.2:80;

        check interval=3000 rise=2 fall=5 timeout=1000 type=http;
        check_http_send "HEAD / HTTP/1.0\r\n\r\n";
        check_http_expect_alive http_2xx http_3xx;
    }

    upstream cluster2 {
        # simple round-robin
        server 192.168.0.3:80;
        server 192.168.0.4:80;

        check interval=3000 rise=2 fall=5 timeout=1000 type=http;
        check_keepalive_requests 100;
        check_http_send "HEAD / HTTP/1.1\r\nConnection: keep-alive\r\n\r\n";
        check_http_expect_alive http_2xx http_3xx;
    }

    server {
        listen 80;

        location /1 {
            proxy_pass http://cluster1;
        }

        location /2 {
            proxy_pass http://cluster2;
        }

        location /status {
            check_status;

            access_log   off;
            allow SOME.IP.ADD.RESS;
            deny all;
        }
    }
}
Directives


Syntax: check interval=milliseconds [fall=count] [rise=count] [timeout=milliseconds] [default_down=true|false] [type=tcp|http|ssl_hello|mysql|ajp] [port=check_port]

Default: If the parameters are omitted, default values are: interval=30000 fall=5 rise=2 timeout=1000 default_down=true type=tcp

Context: upstream

Add health check for the upstream servers.

The parameters' meanings are:



Syntax: check_keepalive_requests request_num

Default: 1

Context: upstream

The directive specifies the number of requests sent on a connection, the default vaule 1 indicates that tengine will certainly close the connection after a request.



Syntax: check_http_send http_packet

Default: "GET / HTTP/1.0\r\n\r\n"

Context: upstream

If the check type is http, the check function will send this http packet to the upstream server. Method "HEAD" is recommended for reducing traffic.

When persistant connection is used, a keep-alive request header should be added to the value of the directive, e.g. "HEAD / HTTP/1.1\r\nConnection: keep-alive\r\n\r\n". In addition, in the case of "GET" method, size of the request uri should not be too large, make sure the transmission can be finished within an interval, otherwise the health check will deduce a conclusion that there is something wrong with the servers or the net.



Syntax: check_http_expect_alive [ http_2xx | http_3xx | http_4xx | http_5xx ]

Default: http_2xx | http_3xx

Context: upstream

These status codes indicate the upstream server's http response is OK and the check response is successful.



Syntax: check_shm_size size

Default: 1M

Context: http

Default size is one megabytes. If you want to check thousands of servers, the shared memory may be not enough, you can enlarge it with this directive.



Syntax: check_status [html|csv|json]

Default: check_status html

Context: location

Display the status of checking servers. This directive should be used in the http block.

You can specify the default display format after Tengine-1.4.0. The formats can be html, csv or json. The default type is html. It also supports to specify the format by the request argument. Suppose your check_status location is '/status', the argument of format can change the display page's format. You can do like this:

/status?format=html
/status?format=csv
/status?format=json

At present, you can fetch the list of servers with the same status by the argument of status. For example:

/status?format=html&status=down
/status?format=csv&status=up

Below it's the sample html page:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Nginx http upstream check status</title>
</head>
<body>
    <h1>Nginx http upstream check status</h1>
    <h2>Check upstream server number: 1, generation: 3</h2>
    <table style="background-color:white" cellspacing="0"        cellpadding="3" border="1">
        <tr bgcolor="#C0C0C0">
            <th>Index</th>
            <th>Upstream</th>
            <th>Name</th>
            <th>Status</th>
            <th>Rise counts</th>
            <th>Fall counts</th>
            <th>Check type</th>
            <th>Check port</th>
        </tr>
        <tr>
            <td>0</td>
            <td>backend</td>
            <td>106.187.48.116:80</td>
            <td>up</td>
            <td>39</td>
            <td>0</td>
            <td>http</td>
            <td>80</td>
        </tr>
    </table>
</body>
</html>

Below it's the sample of csv page:

0,backend,106.187.48.116:80,up,46,0,http,80

Below it's the sample of json page:

{"servers": {
  "total": 1,
  "generation": 3,
  "server": [
   {"index": 0, "upstream": "backend", "name": "106.187.48.116:80", "status": "up", "rise": 58, "fall": 0, "type": "http", "port": 80}
  ]
 }}