<a id="stream-core"></a>

# Stream Module

The core stream module implements basic functionality for handling TCP and UDP
connections: this includes defining server blocks, traffic routing, configuring
proxying, SSL/TLS support, and managing connections for streaming services, such
as databases, DNS, and other protocols that operate over TCP and UDP.

The other modules in this section extend this functionality, allowing you to
flexibly configure and optimize the stream server for various scenarios and
requirements.

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild),
this module isn't built by default;
it should be enabled with the
`‑‑with‑stream`
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure).
In packages and images from [our repos](https://en.angie.software//angie/docs/installation/index.md#install-packages),
the module is included in the build.

<a id="configuration-example-55"></a>

## Configuration Example

```nginx
worker_processes auto;

error_log /var/log/angie/error.log info;

events {
    worker_connections  1024;
}

stream {
    upstream backend {
        hash $remote_addr consistent;

        server backend1.example.com:12345 weight=5;
        server 127.0.0.1:12345            max_fails=3 fail_timeout=30s;
        server unix:/tmp/backend3;
    }

    upstream dns {
       server 192.168.0.1:53535;
       server dns.example.com:53;
    }

    server {
        listen 12345;
        proxy_connect_timeout 1s;
        proxy_timeout 3s;
        proxy_pass backend;
    }

    server {
        listen 127.0.0.1:53 udp reuseport;
        proxy_timeout 20s;
        proxy_pass dns;
    }

    server {
        listen [::1]:12345;
        proxy_pass unix:/tmp/stream.socket;
    }
}
```

<a id="directives-64"></a>

## Directives

<a id="index-0"></a>

<a id="s-listen"></a>

### listen

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `listen` address[:port] [`ssl`] [`udp`] [`proxy_protocol`] [`setfib=`number] [`fastopen=`number] [`backlog=`number] [`rcvbuf=`size] [`sndbuf=`size] [`accept_filter=`filter] [`deferred`] [`bind`] [`ipv6only=``on` | `off`] [`reuseport`] [`so_keepalive=`on|off|[`keepidle`]:[`keepintvl`]:[`keepcnt`]];   |
|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                                                                                                                                                                                                                            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server                                                                                                                                                                                                                                                                                                       |

Sets the address and port for the socket on which the server will accept connections. It is possible to specify just the port, so Angie listens on all available IPv4 (and IPv6, if enabled) interfaces. The address can also be a hostname, for example:

```nginx
listen 127.0.0.1:12345;
listen *:12345;
listen 12345;     # same as *:12345
listen localhost:12345;
```

IPv6 addresses are specified in square brackets:

```nginx
listen [::1]:12345;
listen [::]:12345;
```

UNIX domain sockets are specified with the `unix:` prefix:

```nginx
listen unix:/var/run/angie.sock;
```

Port ranges are specified with the first and last port separated by a hyphen:

```nginx
listen 127.0.0.1:12345-12399;
listen 12345-12399;
```

#### NOTE
Different servers must listen on different address:port pairs.

| `ssl`            | allows specifying that all connections accepted on this port should work in SSL mode.                                                                                                      |
|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `udp`            | configures a listening socket for working with datagrams. In order to handle packets from the same address and port in the same session, the reuseport parameter should also be specified. |
| `proxy_protocol` | allows specifying that all connections accepted on this port should use the PROXY protocol.                                                                                                |

The `listen` directive can have several additional parameters specific to socket-related system calls.

| `setfib=`number        | sets the associated routing table, FIB (the `SO_SETFIB` option) for<br/>the listening socket. This currently works only on FreeBSD.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `fastopen=`number      | enables "TCP Fast Open" for the listening socket and [limits](https://datatracker.ietf.org/doc/html/rfc7413#section-5.1) the maximum length for the queue of connections that have not yet completed the three-way handshake.<br/><br/>#### WARNING<br/>Do not enable this feature unless the server can handle receiving the [same SYN packet with data](https://datatracker.ietf.org/doc/html/rfc7413#section-6.1) more than once.                                                                                                                                                                                                                                                                                                                        |
| `backlog=`number       | sets the `backlog` parameter in the `listen()` call that<br/>limits the maximum length for the queue of pending connections. By<br/>default, `backlog` is set to `-1` on FreeBSD, DragonFly BSD,<br/>and macOS, and to 511 on other platforms.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `rcvbuf=`size          | sets the receive buffer size (the `SO_RCVBUF` option) for the listening socket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `sndbuf=`size          | sets the send buffer size (the `SO_SNDBUF` option) for the listening socket.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `accept_filter=`filter | sets the name of accept filter (the `SO_ACCEPTFILTER` option) for<br/>the listening socket that filters incoming connections before passing<br/>them to `accept()`. This works only on FreeBSD and NetBSD 5.0+.<br/>Acceptable values are `dataready` and `httpready`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `deferred`             | instructs to use a deferred `accept()` (the<br/>`TCP_DEFER_ACCEPT` socket option) on Linux.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `bind`                 | this parameter instructs to make a separate `bind()` call for a<br/>given address:port pair. The fact is that if there are several<br/>`listen` directives with the same port but different addresses,<br/>and one of the `listen` directives listens on all addresses for the<br/>given port (\*:port), Angie will `bind()` only to \*:port. It should be<br/>noted that the `getsockname()` system call will be made in this case to<br/>determine the address that accepted the connection. If the `setfib`,<br/>`fastopen`, `backlog`, `rcvbuf`, `sndbuf`,<br/>`accept_filter`, `deferred`, `ipv6only`,<br/>`reuseport`, or `so_keepalive` parameters are used then for a<br/>given address:port pair a separate `bind()` call will always be<br/>made. |
| `ipv6only=on` | `off`  | this parameter determines (via the `IPV6_V6ONLY` socket option)<br/>whether an IPv6 socket listening on a wildcard address [::] will accept<br/>only IPv6 connections or both IPv6 and IPv4 connections. This parameter<br/>is turned on by default. It can only be set once on start.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `reuseport`            | this parameter instructs to create an individual listening socket for<br/>each worker process (using the `SO_REUSEPORT` socket option on<br/>Linux 3.9+ and DragonFly BSD, or `SO_REUSEPORT_LB` on FreeBSD 12+),<br/>allowing a kernel to distribute incoming connections between worker<br/>processes. This currently works only on Linux 3.9+, DragonFly BSD, and<br/>FreeBSD 12+.<br/><br/>#### WARNING<br/>Inappropriate use of this option may have its security implications.                                                                                                                                                                                                                                                                         |
| `multipath`            | enables accepting connections via [Multipath TCP](https://en.wikipedia.org/wiki/Multipath_TCP) (MPTCP) protocol,<br/>supported in Linux kernel starting from version 5.6.<br/>This parameter is **incompatible** with `udp`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

`so_keepalive=on` | `off` | [`keepidle`]:[`keepintvl`]:[`keepcnt`]

Configures the "TCP keepalive" behavior for the listening socket.

| `''`   | if this parameter is omitted then the operating system's settings will be in effect for the socket   |
|--------|------------------------------------------------------------------------------------------------------|
| `on`   | the SO_KEEPALIVE option is turned on for the socket                                                  |
| `off`  | the SO_KEEPALIVE option is turned off for the socket                                                 |

Some operating systems support setting of TCP keepalive parameters on a
per-socket basis using the `TCP_KEEPIDLE`, `TCP_KEEPINTVL`, and
`TCP_KEEPCNT` socket options. On such systems (currently, Linux 2.4+,
NetBSD 5+, and FreeBSD 9.0-STABLE), they can be configured using the keepidle,
keepintvl, and keepcnt parameters. One or two parameters may be omitted, in
which case the system default setting for the corresponding socket option will
be in effect.

For example,

```nginx
so_keepalive=30m::10
```

will set the idle timeout (`TCP_KEEPIDLE`) to 30 minutes, leave the probe interval (`TCP_KEEPINTVL`) at its system default, and set the probes count (`TCP_KEEPCNT`) to 10 probes.

<a id="index-1"></a>

<a id="s-preread-buffer-size"></a>

### preread_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `preread_buffer_size` size;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | `preread_buffer_size 16k;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                |

Specifies a size of the [preread](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions) buffer.

<a id="index-2"></a>

<a id="s-preread-timeout"></a>

### preread_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `preread_timeout` timeout;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `preread_timeout 30s;`       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server               |

Specifies a timeout of the [preread](https://en.angie.software//angie/docs/configuration/processing.md#stream-sessions) phase.

<a id="index-3"></a>

<a id="s-proxy-protocol-timeout"></a>

### proxy_protocol_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `proxy_protocol_timeout` timeout;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Default                                                                                  | `proxy_protocol_timeout 30s;`       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                      |

Specifies a timeout for reading the PROXY protocol header to complete. If the entire header is not transmitted within this time, the connection is closed.

<a id="index-4"></a>

<a id="s-resolver"></a>

### resolver

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `resolver` address ... [`valid=`time] [`ipv4=``on` | `off`] [`ipv6=``on` | `off`] [`status_zone=`zone];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| Default                                                                                  | —                                                                                                         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server, upstream                                                                                  |

Configures name servers used to resolve names of upstream servers into addresses, for example:

```nginx
resolver 127.0.0.53 [::1]:5353;
```

The address can be specified as a domain name or IP address, with an optional port. If port is not specified, the port 53 is used. Name servers are queried in a round-robin fashion.

#### NOTE
Prefer a local trusted resolver such as `127.0.0.53` (systemd-resolved)
over a public one (e.g. `8.8.8.8`). Public resolvers expose DNS queries
to third parties and increase susceptibility to cache-poisoning attacks.

#### NOTE
The directive value is inherited by nested blocks
and can be overridden in them if necessary.
Within a single block, the directive may only be specified once.
If it is repeated, the last definition takes effect.

By default, Angie caches answers using the TTL value of a response. If
the `resolver` directive is not specified and no dynamic DNS queries are performed
(for example, when using fixed names in [Proxy](https://en.angie.software//angie/docs/configuration/modules/stream/stream_proxy.md#stream-proxy) without
variables), specifying a resolver is not required: names will be resolved at startup
using the system resolver. The optional `valid` parameter allows
overriding this:

| `valid`   | *optional* parameter allows overriding the response cache validity   |
|-----------|----------------------------------------------------------------------|
```nginx
resolver 127.0.0.53 [::1]:5353 valid=30s;
```

By default, Angie will look up both IPv4 and IPv6 addresses while resolving.

| `ipv4=off`   | disables looking up of IPv4 addresses   |
|--------------|-----------------------------------------|
| `ipv6=off`   | disables looking up of IPv6 addresses   |

<a id="s-resolver-status"></a>

| `status_zone`   | *optional* parameter;<br/>enables the collection of DNS server request and response metrics<br/>([/status/resolvers/<zone>](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-resolvers))<br/>in the specified zone   |
|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

<a id="index-5"></a>

<a id="s-resolver-timeout"></a>

### resolver_timeout

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `resolver_timeout` time;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `resolver_timeout 30s;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server, upstream   |

Sets a timeout for name resolution, for example:

```nginx
```

resolver_timeout 5s;

<a id="index-6"></a>

<a id="s-error-log-user-tag"></a>

### error_log_user_tag

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `error_log_user_tag` value;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | —                             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                |

Adds a session-specific tag to error log records. The value is a [complex value](https://en.angie.software//angie/docs/configuration/configfile.md#syntax)
and can use variables. The directive can be specified multiple times to add multiple tags.
Tags can be matched with `filter=tag:` in [error_log](https://en.angie.software//angie/docs/configuration/modules/core.md#error-log).

<a id="index-7"></a>

<a id="s-server"></a>

### server

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `server` { ... }   |
|------------------------------------------------------------------------------------------|--------------------|
| Default                                                                                  | —                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream             |

Sets the configuration for a server.

<a id="index-8"></a>

<a id="s-server-name"></a>

### server_name

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `server_name` name ...;   |
|------------------------------------------------------------------------------------------|---------------------------|
| Default                                                                                  | `server_name "";`         |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server                    |

Sets names of a virtual server.

#### WARNING
In the `stream` module, the `server_name` directive is based on Server Name
Indication ([SNI](https://en.angie.software//angie/docs/configuration/ssl.md#sni)) and only works with TLS connections. To use it,
you must [configure TLS termination](https://en.angie.software//angie/docs/configuration/ssl.md#ssl-config) or [enable TLS
preread](https://en.angie.software//angie/docs/configuration/modules/stream/stream_ssl_preread.md#stream-ssl-preread) in the corresponding `server` block.

Example configuration:

```nginx
server {
    listen 443 ssl;
    server_name example.com www.example.com;
    ssl_certificate /etc/angie/cert.pem;
    ssl_certificate_key /etc/angie/key.pem;
}
```

The first name becomes the primary server name.

Server names can include an asterisk (`*`)
to replace the first or last part of a name:

```nginx
server {
    server_name example.com *.example.com www.example.*;
}
```

These names are called wildcard names.

You can also use regular expressions in server names by preceding the name with
a tilde (`~`):

```none
server {
    server_name www.example.com ~^www\d+\.example\.com$;
}
```

Regular expressions may include captures that can be used in other directives:

```nginx
server {
    server_name ~^(www\.)?(.+)$;

    proxy_pass www.$2:12345;
}
```

Named captures in regular expressions create variables
that can be used in other directives:

```nginx
server {
    server_name ~^(www\.)?(?<domain>.+)$;

    proxy_pass www.$domain:12345;
}
```

If the directive's parameter is set to `$hostname`, the machine's hostname
is inserted.

When searching for a virtual server by name, if the name matches more than one
of the specified variants (e.g., both a wildcard name and a regular expression
match), the first matching variant will be chosen in the following order of
priority:

- The exact name
- The longest wildcard name starting with an asterisk, e.g.,
  `*.example.com`
- The longest wildcard name ending with an asterisk, e.g., `mail.*`
- The first matching regular expression (in order of appearance in the
  configuration file)

<a id="index-9"></a>

<a id="s-server-names-hash-bucket-size"></a>

### server_names_hash_bucket_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `server_names_hash_bucket_size` size;      |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| Default                                                                                  | `server_names_hash_bucket_size 32|64|128;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                                     |

Sets the bucket size for the server names hash tables. The default value depends
on the size of the processor's cache line.

<a id="index-10"></a>

<a id="s-server-names-hash-max-size"></a>

### server_names_hash_max_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `server_names_hash_max_size` size;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `server_names_hash_max_size 512;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                               |

Sets the maximum size of the server names hash tables.

<a id="index-11"></a>

<a id="s-status-zone"></a>

### status_zone

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `status_zone` zone | key `zone=`zone[:count];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------|
| Default                                                                                  | —                                               |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | server                                          |

Allocates a shared memory zone to collect metrics for
[/status/stream/server_zones/<zone>](https://en.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-stream-server-zones).

Multiple `server` contexts can share the same zone for data collection.

The single-value zone syntax aggregates all metrics for the current context
in one shared memory zone:

```nginx
server {

    listen 80;
    server_name *.example.com;

    status_zone single;
    # ...
}
```

The alternative syntax allows specifying the following parameters:

| key              | A string with variables,<br/>whose value determines the grouping of connections in the zone.<br/>All connections producing identical values after substitution<br/>are grouped together.<br/>If substitution yields an empty value, metrics aren't updated.   |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| zone             | The name of the shared memory zone.                                                                                                                                                                                                                           |
| count (optional) | The maximum number of separate groups for collecting metrics.<br/>If new key values would exceed this limit,<br/>they are grouped under zone instead.<br/><br/>The default value is 1.                                                                        |

In the following example,
all connections with the same `$server_addr` value
are grouped into `host_zone`.
Metrics are collected separately for each unique `$server_addr`
until the number of metric groups reaches 10.
After that, any new `$server_addr` values
will be added to the `server_zone` group:

```nginx
stream {

    upstream backend {
        server 192.168.0.1:3306;
        server 192.168.0.2:3306;
        # ...
    }

    server {

        listen 3306;
        proxy_pass backend;

        status_zone $server_addr zone=server_zone:10;
    }
}
```

The resulting metrics are split between individual servers in the API output.

<a id="index-12"></a>

<a id="s-stream"></a>

### stream

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `stream` { ... }   |
|------------------------------------------------------------------------------------------|--------------------|
| Default                                                                                  | —                  |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | main               |

Provides the configuration file context in which the stream server directives are specified.

<a id="index-13"></a>

<a id="s-tcp-nodelay"></a>

### tcp_nodelay

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `tcp_nodelay` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| Default                                                                                  | `tcp_nodelay on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream, server                |

Enables or disables the use of the `TCP_NODELAY` option. The option is enabled for both client connections and connections to proxied servers.

<a id="index-14"></a>

<a id="s-variables-hash-bucket-size"></a>

### variables_hash_bucket_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `variables_hash_bucket_size` size;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `variables_hash_bucket_size 64;`     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                               |

Sets the bucket size for the variables hash table. The details of setting up hash tables are provided in a separate [document](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes).

<a id="index-15"></a>

<a id="s-variables-hash-max-size"></a>

### variables_hash_max_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `variables_hash_max_size` size;   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | `variables_hash_max_size 1024;`   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                            |

Sets the maximum size of the variables hash table. The details of setting up hash tables are provided in a separate [document](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes).

<a id="stream-core-variables"></a>

## Built-in Variables

The core stream module supports the following built-in variables:

<a id="v-s-angie-version"></a>

### `$angie_version`

Angie version

<a id="v-s-binary-remote-addr"></a>

### `$binary_remote_addr`

client address in a binary form, value's length is always 4 bytes for IPv4 addresses or 16 bytes for IPv6 addresses

<a id="v-s-bytes-received"></a>

### `$bytes_received`

number of bytes received from the client

<a id="v-s-bytes-sent"></a>

### `$bytes_sent`

number of bytes sent to the client

<a id="v-s-connection"></a>

### `$connection`

connection serial number

<a id="v-s-hostname"></a>

### `$hostname`

host name

<a id="v-s-msec"></a>

### `$msec`

current time in seconds with milliseconds resolution

<a id="v-s-nginx-version"></a>

### `$nginx_version`

nginx version

<a id="v-s-pid"></a>

### `$pid`

PID of the worker process

<a id="v-s-protocol"></a>

### `$protocol`

protocol used to communicate with the client: `TCP` or `UDP`

<a id="v-s-proxy-protocol-addr"></a>

### `$proxy_protocol_addr`

client address from the PROXY protocol header.
The PROXY protocol must be previously enabled by setting the proxy_protocol parameter in the [listen](#s-listen) directive.

<a id="v-s-proxy-protocol-port"></a>

### `$proxy_protocol_port`

client port from the PROXY protocol header.
The PROXY protocol must be previously enabled by setting the proxy_protocol parameter in the [listen](#s-listen) directive.

<a id="v-s-proxy-protocol-server-addr"></a>

### `$proxy_protocol_server_addr`

server address from the PROXY protocol header.
The PROXY protocol must be previously enabled by setting the proxy_protocol parameter in the [listen](#s-listen) directive.

<a id="v-s-proxy-protocol-server-port"></a>

### `$proxy_protocol_server_port`

server port from the PROXY protocol header.
The PROXY protocol must be previously enabled by setting the proxy_protocol parameter in the [listen](#s-listen) directive.

<a id="v-s-proxy-protocol-tlv"></a>

### `$proxy_protocol_tlv_<name>`

TLV obtained from the PROXY protocol header. The name can be a TLV type name or its numeric value. In the latter case, the value is specified in hexadecimal and must start with 0x:

```none
$proxy_protocol_tlv_alpn
$proxy_protocol_tlv_0x01
```

SSL TLVs can also be accessed by both TLV type name and its numeric value, both must start with `ssl_`:

```none
$proxy_protocol_tlv_ssl_version
$proxy_protocol_tlv_ssl_0x21
```

The following TLV type names are supported:

* `alpn (0x01)` - upper layer protocol used over the connection
* `authority (0x02)` - host name value passed by the client
* `unique_id (0x05)` - unique connection identifier
* `netns (0x30)` - namespace name
* `ssl (0x20)` - SSL TLV structure in binary format

The following SSL TLV type names are supported:

* `ssl_version (0x21)` - SSL version used in client connection
* `ssl_cn (0x22)` - certificate Common Name
* `ssl_cipher (0x23)` - name of the used cipher
* `ssl_sig_alg (0x24)` - algorithm used to sign the certificate
* `ssl_key_alg (0x25)` - public key algorithm

Also supported is the following special SSL TLV type name:

* `ssl_verify` - client certificate verification result: 0 if the client presented a certificate and it was successfully verified, or non-zero otherwise

The PROXY protocol must be previously enabled by setting the proxy_protocol parameter in the [listen](#s-listen) directive.

<a id="v-s-remote-addr"></a>

### `$remote_addr`

client address

<a id="v-s-remote-port"></a>

### `$remote_port`

client port

<a id="v-s-server-addr"></a>

### `$server_addr`

address of the server which accepted a connection.
Computing a value of this variable usually requires one system call. To avoid a system call, the [listen](#s-listen) directives must specify addresses and use the `bind` parameter.

<a id="v-s-server-port"></a>

### `$server_port`

port of the server which accepted a connection

<a id="v-s-session-time"></a>

### `$session_time`

session duration in seconds with milliseconds resolution

<a id="v-s-status"></a>

### `$status`

session status, can be one of the following:

| `200`   | session completed successfully                                                                                                                                                                     |
|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `400`   | client data could not be parsed, for example, the PROXY protocol header                                                                                                                            |
| `403`   | access forbidden, for example, when access is limited for [certain client addresses](https://en.angie.software//angie/docs/configuration/modules/stream/stream_access.md#stream-access)            |
| `500`   | internal server error                                                                                                                                                                              |
| `502`   | bad gateway, for example, if an upstream server could not be selected or reached                                                                                                                   |
| `503`   | service unavailable, for example, when access is limited by the [number of connections](https://en.angie.software//angie/docs/configuration/modules/stream/stream_limit_conn.md#stream-limit-conn) |

<a id="v-s-time-iso8601"></a>

### `$time_iso8601`

local time in the ISO 8601 standard format

<a id="v-s-time-local"></a>

### `$time_local`

local time in the Common Log Format