Upstream Probe

The module implements active health probes for stream_upstream.

Configuration Example

server {
    listen ...;

    # ...
    proxy_pass backend;
    upstream_probe_timeout 1s;

    upstream_probe backend_probe
        port=12345
        interval=5s
        test=$good
        essential
        fails=3
        passes=3
        max_response=512k
        mode=onfail
        "send=data:GET / HTTP/1.0\r\n\r\n";
}

Note

According to RFC 2616 (HTTP/1.1) and RFC 9110 (HTTP Semantics), HTTP headers must be separated by a CRLF sequence (rn) rather than just n.

Directives

upstream_probe (PRO)

Added in version 1.4.0: PRO

Syntax	upstream_probe name [port=number] [interval=time] [test=condition] [essential [persistent]] [fails=number] [passes=number] [max_response=size] [mode=always | idle | onfail] [udp] [send=string];
Default	—
Context	server

Defines an active health probe for servers within the upstream group specified in the proxy_pass directive in the same server context where the upstream_probe directive is located.

A server passes the probe if the request to it succeeds, considering all parameter settings of the upstream_probe directive and all parameters that affect how upstreams are used by the server context where it is defined, including the proxy_next_upstream directive.

To make use of the probes, the upstream must have a shared memory zone (zone). One upstream may be configured with several probes.

The following parameters are accepted:

name	Mandatory name of the probe.
port	Alternative port number for the probe request.
interval	Interval between probes. By default — 5s.
test	The condition for the probe, defined as a string of variables. If the variables' substitution yields "" or "0", the probe is not passed.
essential	If set, the initial state of the server is being checked, so the server doesn't receive client requests until the probe is passed.
persistent	Setting this parameter requires enabling essential first; persistent servers that were deemed healthy prior to a configuration reload start receiving requests without being required to pass this probe first.
fails	Number of subsequent failed probes that renders the server unhealthy. By default — 1.
passes	Number of subsequent passed probes that renders the server healthy. By default — 1.
max_response	Maximum memory size for the response. If a zero value is specified, response waiting is disabled. By default — 256k.
mode	Probe mode, depending on the servers' health: always — servers are probed regardless of their state; idle — probes affect unhealthy servers and servers where interval has elapsed since the last client request. onfail — only unhealthy servers are probed. By default — always.
udp	If specified, the UDP protocol is used for probing. By default, TCP is used for probing.
send	Data sent for the check; this can be a string with the prefix data: or a file name with data (specified absolutely or relative to the /usr/local/angie/ directory).

Example:

upstream backend {
    zone backend 1m;

    server a.example.com;
    server b.example.com;
}

map $upstream_probe_response $good {
    ~200    "1";
    default  "";
}

server {
    listen ...;

    # ...
    proxy_pass backend;
    upstream_probe_timeout 1s;

    upstream_probe backend_probe
        port=12345
        interval=5s
        test=$good
        essential
        persistent
        fails=3
        passes=3
        max_response=512k
        mode=onfail
        "send=data:GET / HTTP/1.0\r\n\r\n";
}

Details of probe operation:

• Initially, the server won't receive client requests until it passes all essential probes configured for it, skipping persistent ones if the configuration was reloaded and the server was deemed healthy prior to that. If there are no such probes, the server is considered healthy.

• The server is considered unhealthy and won't receive client requests, if any of the probes configured for it hits fails or the server reaches max_fails.

• For an unhealthy server to be considered healthy again, all probes configured for it must reach their respective passes; after that, max_fails is also considered.

Built-in Variables

The stream_upstream module supports the following built-in variables:

$upstream_probe (PRO)

Name of the currently active upstream_probe.

$upstream_probe_response (PRO)

Contents of the response received during an active probe configured by upstream_probe.