=encoding utf-8

=head1 NAME

ngx_stream_proxy_module - Module ngx_stream_proxy_module




=head1



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




=head1 Example Configuration




    
    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;
        proxy_responses 1;
        proxy_timeout 20s;
        proxy_pass dns.example.com:53;
    }
    
    server {
        listen [::1]:12345;
        proxy_pass unix:/tmp/stream.socket;
    }






=head1 Directives

=head2 proxy_bind


B<syntax:> proxy_bind I<I<C<address>> [transparent] E<verbar> C<off>>



B<context:> I<stream>


B<context:> I<server>



This directive appeared in version 1.9.2.





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





The C<transparent> 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:

    
    proxy_bind $remote_addr transparent;


In order for this parameter to work,
it is necessary to run nginx worker processes with the
L<superuser|ngx_core_module> privileges
and configure kernel routing table
to intercept network traffic from the proxied server.







=head2 proxy_buffer_size


B<syntax:> proxy_buffer_size I<I<C<size>>>


B<default:> I<16k>


B<context:> I<stream>


B<context:> I<server>



This directive appeared in version 1.9.4.





Sets the I<C<size>> of the buffer used for reading data
from the proxied server.
Also sets the I<C<size>> of the buffer used for reading data
from the client.







=head2 proxy_connect_timeout


B<syntax:> proxy_connect_timeout I<I<C<time>>>


B<default:> I<60s>


B<context:> I<stream>


B<context:> I<server>





Defines a timeout for establishing a connection with a proxied server.







=head2 proxy_download_rate


B<syntax:> proxy_download_rate I<I<C<rate>>>


B<default:> I<0>


B<context:> I<stream>


B<context:> I<server>



This directive appeared in version 1.9.3.





Limits the speed of reading the data from the proxied server.
The I<C<rate>> 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.







=head2 proxy_next_upstream


B<syntax:> proxy_next_upstream I<C<on> E<verbar> C<off>>


B<default:> I<on>


B<context:> I<stream>


B<context:> I<server>





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





Passing a connection to the next server can be limited by
the number of tries
and by time.







=head2 proxy_next_upstream_timeout


B<syntax:> proxy_next_upstream_timeout I<I<C<time>>>


B<default:> I<0>


B<context:> I<stream>


B<context:> I<server>





Limits the time allowed to pass a connection to the
next server.
The C<0> value turns off this limitation.







=head2 proxy_next_upstream_tries


B<syntax:> proxy_next_upstream_tries I<I<C<number>>>


B<default:> I<0>


B<context:> I<stream>


B<context:> I<server>





Limits the number of possible tries for passing a connection to the
next server.
The C<0> value turns off this limitation.







=head2 proxy_pass


B<syntax:> proxy_pass I<I<C<address>>>



B<context:> I<server>





Sets the address of a proxied server.
The address can be specified as a domain name or IP address,
and a port:

    
    proxy_pass localhost:12345;


or as a UNIX-domain socket path:

    
    proxy_pass unix:/tmp/stream.socket;







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
L<server group|ngx_stream_upstream_module>.





The address can also be specified using variables (1.11.3):

    
    proxy_pass $upstream;


In this case, the server name is searched among the described
L<server groups|ngx_stream_upstream_module>,
and, if not found, is determined using a
L<ngx_stream_core_module>.







=head2 proxy_protocol


B<syntax:> proxy_protocol I<C<on> E<verbar> C<off>>


B<default:> I<off>


B<context:> I<stream>


B<context:> I<server>



This directive appeared in version 1.9.2.





Enables the
L<PROXY
protocol|http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt> for connections to a proxied server.







=head2 proxy_responses


B<syntax:> proxy_responses I<I<C<number>>>



B<context:> I<stream>


B<context:> I<server>



This directive appeared in version 1.9.13.





Sets the number of datagrams expected from the proxied server
in response to the client request
if the L<UDP|ngx_stream_core_module>
protocol is used.
By default, the number of datagrams is not limited:
the response datagrams will be sent
until the L</proxy_timeout> value expires.







=head2 proxy_ssl


B<syntax:> proxy_ssl I<C<on> E<verbar> C<off>>


B<default:> I<off>


B<context:> I<stream>


B<context:> I<server>





Enables the SSLE<sol>TLS protocol for connections to a proxied server.







=head2 proxy_ssl_certificate


B<syntax:> proxy_ssl_certificate I<I<C<file>>>



B<context:> I<stream>


B<context:> I<server>





Specifies a I<C<file>> with the certificate in the PEM format
used for authentication to a proxied server.







=head2 proxy_ssl_certificate_key


B<syntax:> proxy_ssl_certificate_key I<I<C<file>>>



B<context:> I<stream>


B<context:> I<server>





Specifies a I<C<file>> with the secret key in the PEM format
used for authentication to a proxied server.







=head2 proxy_ssl_ciphers


B<syntax:> proxy_ssl_ciphers I<I<C<ciphers>>>


B<default:> I<DEFAULT>


B<context:> I<stream>


B<context:> I<server>





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





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







=head2 proxy_ssl_crl


B<syntax:> proxy_ssl_crl I<I<C<file>>>



B<context:> I<stream>


B<context:> I<server>





Specifies a I<C<file>> with revoked certificates (CRL)
in the PEM format used to verify
the certificate of the proxied server.







=head2 proxy_ssl_name


B<syntax:> proxy_ssl_name I<I<C<name>>>


B<default:> I<host from proxy_pass>


B<context:> I<stream>


B<context:> I<server>





Allows overriding the server name used to
verify
the certificate of the proxied server and to be
passed through SNI
when establishing a connection with the proxied server.
The server name can also be specified using variables (1.11.3).





By default, the host part of the L</proxy_pass> address is used.







=head2 proxy_ssl_password_file


B<syntax:> proxy_ssl_password_file I<I<C<file>>>



B<context:> I<stream>


B<context:> I<server>





Specifies a I<C<file>> with passphrases for
secret keys
where each passphrase is specified on a separate line.
Passphrases are tried in turn when loading the key.







=head2 proxy_ssl_server_name


B<syntax:> proxy_ssl_server_name I<C<on> E<verbar> C<off>>


B<default:> I<off>


B<context:> I<stream>


B<context:> I<server>





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







=head2 proxy_ssl_session_reuse


B<syntax:> proxy_ssl_session_reuse I<C<on> E<verbar> C<off>>


B<default:> I<on>


B<context:> I<stream>


B<context:> I<server>





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







=head2 proxy_ssl_protocols


B<syntax:> proxy_ssl_protocols I<
    [C<SSLv2>]
    [C<SSLv3>]
    [C<TLSv1>]
    [C<TLSv1.1>]
    [C<TLSv1.2>]>


B<default:> I<TLSv1 TLSv1.1 TLSv1.2>


B<context:> I<stream>


B<context:> I<server>





Enables the specified protocols for connections to a proxied server.







=head2 proxy_ssl_trusted_certificate


B<syntax:> proxy_ssl_trusted_certificate I<I<C<file>>>



B<context:> I<stream>


B<context:> I<server>





Specifies a I<C<file>> with trusted CA certificates in the PEM format
used to verify
the certificate of the proxied server.







=head2 proxy_ssl_verify


B<syntax:> proxy_ssl_verify I<C<on> E<verbar> C<off>>


B<default:> I<off>


B<context:> I<stream>


B<context:> I<server>





Enables or disables verification of the proxied server certificate.







=head2 proxy_ssl_verify_depth


B<syntax:> proxy_ssl_verify_depth I<I<C<number>>>


B<default:> I<1>


B<context:> I<stream>


B<context:> I<server>





Sets the verification depth in the proxied server certificates chain.







=head2 proxy_timeout


B<syntax:> proxy_timeout I<I<C<timeout>>>


B<default:> I<10m>


B<context:> I<stream>


B<context:> I<server>





Sets the I<C<timeout>> 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.







=head2 proxy_upload_rate


B<syntax:> proxy_upload_rate I<I<C<rate>>>


B<default:> I<0>


B<context:> I<stream>


B<context:> I<server>



This directive appeared in version 1.9.3.





Limits the speed of reading the data from the client.
The I<C<rate>> 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.