ngx_stream_proxy_module.xml

<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_stream_proxy_module"
        link="/en/docs/stream/ngx_stream_proxy_module.html"
        lang="en"
        rev="38">

<section id="summary">

<para>
The <literal>ngx_stream_proxy_module</literal> module (1.9.0) allows proxying
data streams over TCP, UDP (1.9.13), and UNIX-domain sockets.
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<example>
server {
    listen 127.0.0.1:12345;
    proxy_pass 127.0.0.1:8080;
}

server {
    listen 12345;
    proxy_connect_timeout 1s;
    proxy_timeout 1m;
    proxy_pass example.com:12345;
}

server {
    listen 53 udp reuseport;
    proxy_timeout 20s;
    proxy_pass dns.example.com:53;
}

server {
    listen [::1]:12345;
    proxy_pass unix:/tmp/stream.socket;
}
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="proxy_bind">
<syntax>
    <value>address</value>
    [<literal>transparent</literal>] |
    <literal>off</literal></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>1.9.2</appeared-in>

<para>
Makes outgoing connections to a proxied server originate
from the specified local IP <value>address</value>.
Parameter value can contain variables (1.11.2).
The special value <literal>off</literal> cancels the effect
of the <literal>proxy_bind</literal> directive
inherited from the previous configuration level, which allows the
system to auto-assign the local IP address.
</para>

<para id="proxy_bind_transparent">
The <literal>transparent</literal> parameter (1.11.0) allows
outgoing connections to a proxied server originate
from a non-local IP address,
for example, from a real IP address of a client:
<example>
proxy_bind $remote_addr transparent;
</example>
In order for this parameter to work,
it is usually necessary to run nginx worker processes with the
<link doc="../ngx_core_module.xml" id="user">superuser</link> privileges.
On Linux it is not required (1.13.8) as if
the <literal>transparent</literal> parameter is specified, worker processes
inherit the <literal>CAP_NET_RAW</literal> capability from the master process.
It is also necessary to configure kernel routing table
to intercept network traffic from the proxied server.
</para>

</directive>


<directive name="proxy_bind_dynamic">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.29.3</appeared-in>

<para>
When enabled, makes the <link id="proxy_bind">bind</link> operation
at each connection attempt.
</para>

<para>
<note>
This directive is available as part of our
<commercial_version>commercial subscription</commercial_version>.
</note>
</para>

</directive>


<directive name="proxy_buffer_size">
<syntax><value>size</value></syntax>
<default>16k</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.9.4</appeared-in>

<para>
Sets the <value>size</value> of the buffer used for reading data
from the proxied server.
Also sets the <value>size</value> of the buffer used for reading data
from the client.
</para>

</directive>


<directive name="proxy_connect_timeout">
<syntax><value>time</value></syntax>
<default>60s</default>
<context>stream</context>
<context>server</context>

<para>
Defines a timeout for establishing a connection with a proxied server.
</para>

</directive>


<directive name="proxy_download_rate">
<syntax><value>rate</value></syntax>
<default>0</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.9.3</appeared-in>

<para>
Limits the speed of reading the data from the proxied server.
The <value>rate</value> is specified in bytes per second.
The zero value disables rate limiting.
The limit is set per a connection, so if nginx simultaneously opens
two connections to the proxied server,
the overall rate will be twice as much as the specified limit.
</para>

<para>
Parameter value can contain variables (1.17.0).
It may be useful in cases where rate should be limited
depending on a certain condition:
<example>
map $slow $rate {
    1     4k;
    2     8k;
}

proxy_download_rate $rate;
</example>
</para>

</directive>


<directive name="proxy_half_close">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.21.4</appeared-in>

<para>
Enables or disables closing
each direction of a TCP connection independently (“TCP half-close”).
If enabled, proxying over TCP will be kept
until both sides close the connection.
</para>

</directive>


<directive name="proxy_next_upstream">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>stream</context>
<context>server</context>

<para>
When a connection to the proxied server cannot be established, determines
whether a client connection will be passed to the next server.
</para>

<para>
Passing a connection to the next server can be limited by
<link id="proxy_next_upstream_tries">the number of tries</link>
and by <link id="proxy_next_upstream_timeout">time</link>.
</para>

</directive>


<directive name="proxy_next_upstream_timeout">
<syntax><value>time</value></syntax>
<default>0</default>
<context>stream</context>
<context>server</context>

<para>
Limits the time allowed to pass a connection to the
<link id="proxy_next_upstream">next server</link>.
The <literal>0</literal> value turns off this limitation.
</para>

</directive>


<directive name="proxy_next_upstream_tries">
<syntax><value>number</value></syntax>
<default>0</default>
<context>stream</context>
<context>server</context>

<para>
Limits the number of possible tries for passing a connection to the
<link id="proxy_next_upstream">next server</link>.
The <literal>0</literal> value turns off this limitation.
</para>

</directive>


<directive name="proxy_pass">
<syntax><value>address</value></syntax>
<default/>
<context>server</context>

<para>
Sets the address of a proxied server.
The address can be specified as a domain name or IP address,
and a port:
<example>
proxy_pass localhost:12345;
</example>
or as a UNIX-domain socket path:
<example>
proxy_pass unix:/tmp/stream.socket;
</example>
</para>

<para>
If a domain name resolves to several addresses, all of them will be
used in a round-robin fashion.
In addition, an address can be specified as a
<link doc="ngx_stream_upstream_module.xml">server group</link>.
</para>

<para>
The address can also be specified using variables (1.11.3):
<example>
proxy_pass $upstream;
</example>
In this case, the server name is searched among the described
<link doc="ngx_stream_upstream_module.xml">server groups</link>,
and, if not found, is determined using a
<link doc="ngx_stream_core_module.xml" id="resolver"/>.
</para>

</directive>


<directive name="proxy_protocol">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.9.2</appeared-in>

<para>
Enables the
<link url="http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt">PROXY
protocol</link> for connections to a proxied server.
</para>

</directive>


<directive name="proxy_requests">
<syntax><value>number</value></syntax>
<default>0</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.15.7</appeared-in>

<para>
Sets the number of client datagrams at which
binding between a client and existing UDP stream session is dropped.
After receiving the specified number of datagrams, next datagram
from the same client starts a new session.
The session terminates when all client datagrams are transmitted
to a proxied server and the expected number of
<link id="proxy_responses">responses</link> is received,
or when it reaches a <link id="proxy_timeout">timeout</link>.
</para>

</directive>


<directive name="proxy_responses">
<syntax><value>number</value></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>1.9.13</appeared-in>

<para>
Sets the number of datagrams expected from the proxied server
in response to a client datagram
if the <link doc="ngx_stream_core_module.xml" id="udp">UDP</link>
protocol is used.
The number serves as a hint for session termination.
By default, the number of datagrams is not limited.
</para>

<para>
If zero value is specified, no response is expected.
However, if a response is received and the
session is still not finished, the response will be handled.
</para>

</directive>


<directive name="proxy_session_drop">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.15.8</appeared-in>

<para>
Enables terminating all sessions to a proxied server
after it was removed from the group or marked as permanently unavailable.
This can occur because of
<link doc="ngx_stream_core_module.xml" id="resolver">re-resolve</link>
or with the API
<link doc="../http/ngx_http_api_module.xml" id="deleteStreamUpstreamServer"><literal>DELETE</literal></link>
command.
A server can be marked as permanently unavailable if it is considered
<link doc="ngx_stream_upstream_hc_module.xml" id="health_check">unhealthy</link>
or with the API
<link doc="../http/ngx_http_api_module.xml" id="patchStreamUpstreamServer"><literal>PATCH</literal></link>
command.
Each session is terminated when the next
read or write event is processed for the client or proxied server.
</para>

<para>
<note>
This directive is available as part of our
<commercial_version>commercial subscription</commercial_version>.
</note>
</para>

</directive>


<directive name="proxy_socket_keepalive">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.15.6</appeared-in>

<para>
Configures the “TCP keepalive” behavior
for outgoing connections to a proxied server.
By default, the operating system’s settings are in effect for the socket.
If the directive is set to the value “<literal>on</literal>”, the
<c-def>SO_KEEPALIVE</c-def> socket option is turned on for the socket.
</para>

</directive>


<directive name="proxy_ssl">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>stream</context>
<context>server</context>

<para>
Enables the SSL/TLS protocol for connections to a proxied server.
</para>

</directive>


<directive name="proxy_ssl_alpn">
<syntax><value>protocol</value> ...</syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>1.31.0</appeared-in>

<para>
Specifies the list of protocols to advertise via the
<link url="https://datatracker.ietf.org/doc/html/rfc7301">ALPN</link>
extension when establishing a connection with the proxied server.
For example:
<example>
proxy_ssl_alpn h2 http/1.1;
</example>
</para>

<para>
Parameter value can contain variables:
<example>
proxy_ssl_alpn $ssl_alpn_protocol;
</example>
</para>

</directive>


<directive name="proxy_ssl_certificate">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

<para>
Specifies a <value>file</value> with the certificate in the PEM format
used for authentication to a proxied server.
</para>

<para id="proxy_ssl_certificate_variables">
Since version 1.21.0, variables can be used in the <value>file</value> name.
</para>

</directive>


<directive name="proxy_ssl_certificate_cache">
<syntax><literal>off</literal></syntax>
<syntax>
    <literal>max</literal>=<value>N</value>
    [<literal>inactive</literal>=<value>time</value>]
    [<literal>valid</literal>=<value>time</value>]</syntax>
<default>off</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.27.4</appeared-in>

<para>
Defines a cache that stores
<link id="proxy_ssl_certificate">SSL certificates</link> and
<link id="proxy_ssl_certificate_key">secret keys</link>
specified with <link id="proxy_ssl_certificate_key_variables">variables</link>.
</para>

<para>
The directive has the following parameters:
<list type="tag">

<tag-name id="proxy_ssl_certificate_cache_max">
<literal>max</literal>
</tag-name>
<tag-desc>
sets the maximum number of elements in the cache;
on cache overflow the least recently used (LRU) elements are removed;
</tag-desc>

<tag-name id="proxy_ssl_certificate_cache_inactive">
<literal>inactive</literal>
</tag-name>
<tag-desc>
defines a time after which an element is removed from the cache
if it has not been accessed during this time;
by default, it is 10 seconds;
</tag-desc>

<tag-name id="proxy_ssl_certificate_cache_valid">
<literal>valid</literal>
</tag-name>
<tag-desc>
defines a time during which
an element in the cache is considered valid
and can be reused;
by default, it is 60 seconds.
Certificates that exceed this time will be reloaded or revalidated;
</tag-desc>

<tag-name id="proxy_ssl_certificate_cache_off">
<literal>off</literal>
</tag-name>
<tag-desc>
disables the cache.
</tag-desc>

</list>
</para>

<para>
Example:
<example>
proxy_ssl_certificate       $proxy_ssl_server_name.crt;
proxy_ssl_certificate_key   $proxy_ssl_server_name.key;
proxy_ssl_certificate_cache max=1000 inactive=20s valid=1m;
</example>
</para>

</directive>


<directive name="proxy_ssl_certificate_key">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

<para>
The value
<literal>store</literal>:<value>scheme</value>:<value>id</value>
can be specified instead of the <value>file</value> (1.29.0),
which is used to load a secret key with a specified <value>id</value>
and OpenSSL provider registered URI <value>scheme</value>, such as
<link url="https://datatracker.ietf.org/doc/html/rfc7512"><literal>pkcs11</literal></link>.
</para>

<para>
Specifies a <value>file</value> with the secret key in the PEM format
used for authentication to a proxied server.
</para>

<para id="proxy_ssl_certificate_key_variables">
Since version 1.21.0, variables can be used in the <value>file</value> name.
</para>

</directive>


<directive name="proxy_ssl_ciphers">
<syntax><value>ciphers</value></syntax>
<default>DEFAULT</default>
<context>stream</context>
<context>server</context>

<para>
Specifies the enabled ciphers for connections to a proxied server.
The ciphers are specified in the format understood by the OpenSSL library.
</para>

<para>
The full list can be viewed using the
“<command>openssl ciphers</command>” command.
</para>

</directive>


<directive name="proxy_ssl_conf_command">
<syntax><value>name</value> <value>value</value></syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>1.19.4</appeared-in>

<para>
Sets arbitrary OpenSSL configuration
<link url="https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html">commands</link>
when establishing a connection with the proxied server.
<note>
The directive is supported when using OpenSSL 1.0.2 or higher.
</note>
</para>

<para>
Several <literal>proxy_ssl_conf_command</literal> directives
can be specified on the same level.
These directives are inherited from the previous configuration level
if and only if there are
no <literal>proxy_ssl_conf_command</literal> directives
defined on the current level.
</para>

<para>
<note>
Note that configuring OpenSSL directly
might result in unexpected behavior.
</note>
</para>

</directive>


<directive name="proxy_ssl_crl">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

<para>
Specifies a <value>file</value> with revoked certificates (CRL)
in the PEM format used to <link id="proxy_ssl_verify">verify</link>
the certificate of the proxied server.
When using intermediate certificates, their CRLs should be
specified in the same file.
</para>

</directive>


<directive name="proxy_ssl_key_log">
<syntax>path</syntax>
<default/>
<context>stream</context>
<context>server</context>
<appeared-in>1.27.2</appeared-in>

<para>
Enables logging of proxied server connection SSL keys
and specifies the path to the key log file.
Keys are logged in the
<link url="https://datatracker.ietf.org/doc/html/draft-ietf-tls-keylogfile">SSLKEYLOGFILE</link>
format compatible with Wireshark.
</para>

<para>
<note>
This directive is available as part of our
<commercial_version>commercial subscription</commercial_version>.
</note>
</para>

</directive>


<directive name="proxy_ssl_name">
<syntax><value>name</value></syntax>
<default>host from proxy_pass</default>
<context>stream</context>
<context>server</context>

<para>
Allows overriding the server name used to
<link id="proxy_ssl_verify">verify</link>
the certificate of the proxied server and to be
<link id="proxy_ssl_server_name">passed through SNI</link>
when establishing a connection with the proxied server.
The server name can also be specified using variables (1.11.3).
</para>

<para>
By default, the host part of the <link id="proxy_pass"/> address is used.
</para>

</directive>


<directive name="proxy_ssl_password_file">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

<para>
Specifies a <value>file</value> with passphrases for
<link id="proxy_ssl_certificate_key">secret keys</link>
where each passphrase is specified on a separate line.
Passphrases are tried in turn when loading the key.
</para>

</directive>


<directive name="proxy_ssl_protocols">
<syntax>
    [<literal>SSLv2</literal>]
    [<literal>SSLv3</literal>]
    [<literal>TLSv1</literal>]
    [<literal>TLSv1.1</literal>]
    [<literal>TLSv1.2</literal>]
    [<literal>TLSv1.3</literal>]</syntax>
<default>TLSv1.2 TLSv1.3</default>
<context>stream</context>
<context>server</context>

<para>
Enables the specified protocols for connections to a proxied server.
</para>

<para>
<note>
The <literal>TLSv1.3</literal> parameter is used by default
since 1.23.4.
</note>
</para>

</directive>


<directive name="proxy_ssl_server_name">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>stream</context>
<context>server</context>

<para>
Enables or disables passing of the server name through
<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">TLS
Server Name Indication extension</link> (SNI, RFC 6066)
when establishing a connection with the proxied server.
</para>

</directive>


<directive name="proxy_ssl_session_reuse">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>stream</context>
<context>server</context>

<para>
Determines whether SSL sessions can be reused when working with
the proxied server.
If the errors
“<literal>digest check failed</literal>”
appear in the logs, try disabling session reuse.
</para>

</directive>


<directive name="proxy_ssl_trusted_certificate">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>
<context>server</context>

<para>
Specifies a <value>file</value> with trusted CA certificates in the PEM format
used to <link id="proxy_ssl_verify">verify</link>
the certificate of the proxied server.
</para>

</directive>


<directive name="proxy_ssl_verify">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>stream</context>
<context>server</context>

<para>
Enables or disables verification of the proxied server certificate.
</para>

</directive>


<directive name="proxy_ssl_verify_depth">
<syntax><value>number</value></syntax>
<default>1</default>
<context>stream</context>
<context>server</context>

<para>
Sets the verification depth in the proxied server certificates chain.
</para>

</directive>


<directive name="proxy_timeout">
<syntax><value>timeout</value></syntax>
<default>10m</default>
<context>stream</context>
<context>server</context>

<para>
Sets the <value>timeout</value> between two successive
read or write operations on client or proxied server connections.
If no data is transmitted within this time, the connection is closed.
</para>

</directive>


<directive name="proxy_upload_rate">
<syntax><value>rate</value></syntax>
<default>0</default>
<context>stream</context>
<context>server</context>
<appeared-in>1.9.3</appeared-in>

<para>
Limits the speed of reading the data from the client.
The <value>rate</value> is specified in bytes per second.
The zero value disables rate limiting.
The limit is set per a connection, so if the client simultaneously opens
two connections,
the overall rate will be twice as much as the specified limit.
</para>

<para>
Parameter value can contain variables (1.17.0).
It may be useful in cases where rate should be limited
depending on a certain condition:
<example>
map $slow $rate {
    1     4k;
    2     8k;
}

proxy_upload_rate $rate;
</example>
</para>

</directive>

</section>

</module>