# Upstream Probe The module implements active health probes for [stream_upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#stream-upstream). ## Configuration Example ```nginx 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 (`\r\n`) rather than just `\n`. ## Directives ### upstream_probe (PRO) | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `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] [`ping`] [`ping_timeout=`time]; | |------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Default | — | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | server | Defines an active health probe for servers within the [upstream](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-upstream) group specified in the [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-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](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#s-proxy-next-upstream) directive. To make use of the probes, the upstream must have a shared memory zone ([zone](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-u-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](https://en.angie.software//angie/docs/configuration/configfile.md#syntax) 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](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 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](https://en.angie.software//angie/docs/configuration/configfile.md#syntax) 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 probe: inline data with the `data:` prefix
or a file path (absolute or relative to `/usr/local/angie/`).

When using a file:

- The [worker process](https://en.angie.software//angie/docs/configuration/modules/core.md#worker-processes) opens and reads
the file on each access; the content is not cached in memory.
- Configuration reload is not required when the file changes;
the new content will be read on the next access.
- Required access permissions: `644` for the file,
`755` for the directory.
- Update files using the move command (`mv`),
not by direct editing. | | `ping` (PRO) | Uses ICMP echo requests instead of TCP/UDP probes.
Requires Angie to be built with `--with-stream_upstream_probe_icmp`.
Not compatible with `test`, `port`,
`udp`, or `send`. | | `ping_timeout` (PRO) | Timeout for waiting for an ICMP echo reply.
By default — `1s`. | Example: ```nginx 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](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-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](https://en.angie.software//angie/docs/configuration/modules/stream/stream_upstream.md#s-max-fails) is also considered. ### upstream_probe_timeout (PRO) | [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | `upstream_probe_timeout` time; | |------------------------------------------------------------------------------------------|----------------------------------| | Default | `upstream_probe_timeout 50s;` | | [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile) | server | Sets the maximum idle [time](https://en.angie.software//angie/docs/configuration/configfile.md#syntax) for a connection established with the server for health probes configured using the [upstream_probe (PRO)](#s-u-upstream-probe) directive; if this limit is exceeded, the connection will be closed. ## Built-in Variables The `stream_upstream` module supports the following built-in variables: ### `$upstream_probe` (PRO) Name of the currently active [upstream_probe](#s-u-upstream-probe). ### `$upstream_probe_response` (PRO) Contents of the response received during an active probe configured by [upstream_probe](#s-u-upstream-probe).