# Upstream Probe The module implements active health probes for [Upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#http-upstream). ## Configuration Example ```nginx server { listen ...; location /backend { ... proxy_pass http://backend; upstream_probe backend_probe uri=/probe port=10004 interval=5s test=$good essential fails=3 passes=3 max_body=10m mode=idle; } } ``` ## Directives ### upstream_probe (PRO) | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `upstream_probe` name [`uri=`address] [`port=`number] [`interval=`time] [`method=`method] [`test=`condition] [`essential` [`persistent`]] [`fails=`number] [`passes=`number] [`max_body=`size] [`mode=``always` | `idle` | `onfail`] [`ping`] [`ping_timeout=`time]; | |------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | location | Defines an active health probe for servers within the [upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-upstream) groups that are specified in [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), [uwsgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass), and similar directives in the same `location` context as the `upstream_probe` directive. Angie regularly performs requests according to the specified parameters to each server in the upstream group. A server passes the probe if the request to it succeeds, considering all parameter settings of the `upstream_probe` directive and all parameters that control how upstreams are used by the `location` context where it is defined. This includes the [proxy_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream) and [uwsgi_next_upstream](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-next-upstream) directives, etc., as well as [proxy_set_header](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header) and so on. To use the probes, the upstream must have a shared memory zone ([zone](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#u-zone)). One upstream may be configured with several probes. The following parameters are accepted: | `name` | Mandatory name of the probe. | |----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `uri` | Request URI to be appended to the argument of [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass),
[uwsgi_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass), etc. By default — `/`. | | `port` | Alternative port number for the probe request. | | `interval` | Interval between probes. By default — `5s`. | | `method` | HTTP method of the probe request. By default — `GET`. | | `test` | The condition to be checked during the request; defined as a string with variables.
If variable substitution yields `""` or `"0"`,
the probe fails. | | `essential` | If set, the initial state of the server is subject to verification
and client requests are not forwarded to it until the probe is passed. | | `persistent` | Setting this parameter requires enabling `essential` first;
`persistent` servers that were working prior to a
[configuration reload](https://en.angie.software//angie/docs/configuration/configfile.md#configfile-reloading)
start receiving requests without being required to pass this probe first. | | `fails` | Number of consecutive failed requests that
renders the server unhealthy. By default — 1. | | `passes` | Number of consecutive successful requests that
renders the server healthy. By default — 1. | | `max_body` | Maximum amount of memory for the response body. 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`. | | `ping` (PRO) | Uses ICMP echo requests instead of HTTP probes.
Requires Angie to be built with `--with-http_upstream_probe_icmp`.
Not compatible with `test`, `port`,
`method`, or `uri`. | | `ping_timeout` (PRO) | Timeout for waiting for an ICMP echo reply.
By default — `1s`. | Example: ```nginx upstream backend { zone backend 1m; server backend1.example.com; server backend2.example.com; } map $upstream_status $good { 200 "1"; } server { listen ...; location /backend { ... proxy_pass http://backend; upstream_probe backend_probe uri=/probe port=10004 interval=5s test=$good essential persistent fails=3 passes=3 max_body=10m mode=idle; } } ``` 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 its `fails` threshold or the server itself reaches the [max_fails](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) threshold. - For an unhealthy server to be considered healthy again, *all* probes configured for it must reach their respective `passes` thresholds; after that, the [max_fails](https://en.angie.software//angie/docs/configuration/modules/http/http_upstream.md#max-fails) threshold is considered. ## Built-in Variables The `http_upstream_probe` module supports the following built-in variables: ### `$upstream_probe` (PRO) Name of the currently active [upstream_probe](#u-upstream-probe). ### `$upstream_probe_body` (PRO) Server response body received during an [upstream_probe](#u-upstream-probe); its size is limited by `max_body`.