ngx_stream_upstream_check_module

ngx_stream_upstream_check_module

support stream upstream health check (tcp/udp/http), and provide a http interface to get backend-server status"

This module can provide Nginx with active backend server health checks (check types support tcp/udp/http).

See Also

• ngx_healthcheck_module it supports both http/stream's upstream healthcheck.

build

clone nginx code and this module code.

git clone https://github.com/zhouchangxun/nginx/nginx.git git clone https://github.com/zhouchangxun/ngx_stream_upstream_check_module.git

apply patch to nginx source

cd nginx/; git apply ../ngx_stream_upstream_check_module/nginx-stable-1.12+.patch

append option to enable this module

./auto/configure --with-stream --add-module=../ngx_stream_upstream_check_module/

build and install

make && make install

config examples

 stream {
    upstream tcp - cluster {
        # simple round-robin
        server 192.168 .0 .1 : 22 ;
        server 192.168 .0 . 2 : 22 ;
        check interval = 3000 rise = 2 fall = 5 timeout = 5000 default_down = true type = tcp ;
    }
    upstream udp - cluster {
        # simple round-robin
        server 192.168 .0 .3 : 53 ;
        server 192.168 .0 . 4 : 53 ;
        check interval = 3000 rise = 2 fall = 5 timeout = 5000 default_down = true type = udp ;
    }
    upstream http - cluster {
        # simple round-robin
        server 192.168 .0 .5 : 80 ;
        server 192.168 .0 . 6 : 80 ;
        check interval = 3000 rise = 2 fall = 5 timeout = 5000 type = http ;
        check_keepalive_requests 100 ;
        check_http_send "HEAD / HTTP/1.1 r n Connection: keep-alive r n r n " ;
        check_http_expect_alive http_2xx http_3xx ;
    }
    server {
        listen 522 ;
        proxy_pass tcp - cluster ;
    }
    server {
        listen 53 ;
        proxy_pass udp - cluster ;
    }
    server {
        listen 8080 ;
        proxy_pass http - cluster ;
    }
}

http {
    server {
        listen 80 ;
        location / status {
            l4check_status ;
        }
    }
}

Directive

Syntax:

check interval=milliseconds [fall=count] [rise=count] [timeout=milliseconds] [default_down=true|false] [type=tcp|udp|http] [port=check_port]

Default: interval=30000 fall=5 rise=2 timeout=1000 default_down=true type=tcp

Context: stream/upstream

This command can turn on the health check function of the backend server.

Detail description

interval: The interval between health check packets sent to the backend.

fall(fall_count): If the number of consecutive failures reaches fall_count, the server is considered down.

rise(rise_count): If the number of successes reaches rise_count, the server is considered to be up.

timeout: The timeout of the backend health request.

default_down: Sets the server status at the beginning. If it is true, it means that the default is down. If it is false, it is up. The default value is true, which means that the server initially believes that it is unavailable, and it will only be considered healthy after the health check package reaches a certain number of successful times.

type: The type of health check package, now supports the following types

• tcp: A simple tcp connection. If the connection is successful, it means that the backend is normal.
• udp: Simply send udp packets. If you receive an icmp error (host or port is unreachable), it means that the backend is abnormal.
• http: Send HTTP request and determine whether the backend survives by the status of the reply packet of the backend.

port: Specify the check port of the backend server. You can specify the port of the backend server that is different from the real service. For example, the backend provides an application with port 443. You can check the status of port 80 to determine the health status of the backend. The default is 0, which means the same as the port provided by the backend server.

Syntax: check_keepalive_requests request_num

Default: 1

Context: stream/upstream

This instruction can configure the number of requests sent by a connection, and its default value is 1, which means that Nginx closes the connection after completing one request.

Syntax: check_http_send http_packet

Default: "GET / HTTP/1.0rnrn"

Context: stream/upstream

This directive can configure the request content sent by the http health check packet. In order to reduce the amount of data transmitted, it is recommended to use the "HEAD" method.

When using a long connection for health check, you need to add the keep-alive request header to this command, such as: "HEAD / HTTP/1.1rnConnection: keep-alivernrn". At the same time, when using the "GET" method, the size of the requested uri should not be too large to ensure that it can be transferred within 1 interval, otherwise it will be regarded as a backend server or network exception by the health check module.

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

Default: http_2xx | http_3xx

Context: stream/upstream

This directive specifies the successful status of HTTP reply, and by default, the status of 2XX and 3XX is considered healthy.

Syntax : check_shm_size size

Default : 1M

Contex : stream

All backend server health check statuses are stored in shared memory, and this instruction can set the size of shared memory. The default is 1M. If you have more than 1,000 servers and have errors during configuration, you may need to expand the size of the memory.

Syntax: l4check_status [html|csv|json]

Default: l4check_status html

Context: http/server/location