<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_stream_set_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Module ngx_stream_set_module

Example Configuration
Directives
     set

The ngx_stream_set_module module (1.19.3) allows
setting a value for a variable.

Example Configuration

server {
    listen 12345;
    set    $true 1;
}

Directives

            Syntax:

            set $variable value;

            Default:

            —

            Context:

            server

Sets a value for the specified variable.
The value can contain text, variables, and their combination.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_stream_split_clients_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Module ngx_stream_split_clients_module

Example Configuration
Directives
     split_clients

The ngx_stream_split_clients_module module (1.11.3) creates
variables suitable for A/B testing, also known as split testing.

Example Configuration

stream {
    ...
    split_clients "${remote_addr}AAA" $upstream {
                  0.5%                feature_test1;
                  2.0%                feature_test2;
                  *                   production;
    }

    server {
        ...
        proxy_pass $upstream;
    }
}

Directives

            Syntax:

            split_clients
    string
    $variable { ... }

            Default:

            —

            Context:

            stream

Creates a variable for A/B testing, for example:

split_clients "${remote_addr}AAA" $variant {
               0.5%               .one;
               2.0%               .two;
               *                  "";
}

The value of the original string is hashed using MurmurHash2.
In the example given, hash values from 0 to 21474835 (0.5%)
correspond to the
value ".one" of the $variant variable,
hash values from 21474836 to 107374180 (2%) correspond to
the value ".two",
and hash values from 107374181 to 4294967295 correspond to
the value "" (an empty string).


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_stream_ssl_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Module ngx_stream_ssl_module

Example Configuration
Directives
     ssl_alpn
     ssl_certificate
     ssl_certificate_cache
     ssl_certificate_compression
     ssl_certificate_key
     ssl_ciphers
     ssl_client_certificate
     ssl_conf_command
     ssl_crl
     ssl_dhparam
     ssl_ecdh_curve
     ssl_ech_file
     ssl_handshake_timeout
     ssl_key_log
     ssl_ocsp
     ssl_ocsp_cache
     ssl_ocsp_responder
     ssl_password_file
     ssl_prefer_server_ciphers
     ssl_protocols
     ssl_reject_handshake
     ssl_session_cache
     ssl_session_ticket_key
     ssl_session_tickets
     ssl_session_timeout
     ssl_stapling
     ssl_stapling_file
     ssl_stapling_responder
     ssl_stapling_verify
     ssl_trusted_certificate
     ssl_verify_client
     ssl_verify_depth
Embedded Variables

The ngx_stream_ssl_module module (1.9.0)
provides the necessary support for a stream proxy server to work with
the SSL/TLS protocol.

This module is not built by default, it should be enabled with the
--with-stream_ssl_module
configuration parameter.

This module requires the
OpenSSL library.

Example Configuration

To reduce the processor load, it is recommended to

set the number of
worker processes
equal to the number of processors,

enable the shared session cache,

disable the built-in session cache,

and possibly increase the session lifetime
(by default, 5 minutes):

worker_processes auto;

stream {

    ...

    server {
        listen              12345 ssl;

        ssl_protocols       TLSv1.2 TLSv1.3;
        ssl_ciphers         AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5;
        ssl_certificate     /usr/local/nginx/conf/cert.pem;
        ssl_certificate_key /usr/local/nginx/conf/cert.key;
        ssl_session_cache   shared:SSL:10m;
        ssl_session_timeout 10m;

        ...
    }

Directives

            Syntax:

            ssl_alpn protocol ...;

            Default:

            —

            Context:

            stream, server

This directive appeared in version 1.21.4.

Specifies the list of supported
ALPN protocols.
One of the protocols must be
negotiated if the client uses ALPN:

map $ssl_alpn_protocol $proxy {
    h2                127.0.0.1:8001;
    http/1.1          127.0.0.1:8002;
}

server {
    listen      12346;
    proxy_pass  $proxy;
    ssl_alpn    h2 http/1.1;
}

            Syntax:

            ssl_certificate file;

            Default:

            —

            Context:

            stream, server

Specifies a file with the certificate in the PEM format
for the given virtual server.
If intermediate certificates should be specified in addition to a primary
certificate, they should be specified in the same file in the following
order: the primary certificate comes first, then the intermediate certificates.
A secret key in the PEM format may be placed in the same file.

Since version 1.11.0,
this directive can be specified multiple times
to load certificates of different types, for example, RSA and ECDSA:

server {
    listen              12345 ssl;

    ssl_certificate     example.com.rsa.crt;
    ssl_certificate_key example.com.rsa.key;

    ssl_certificate     example.com.ecdsa.crt;
    ssl_certificate_key example.com.ecdsa.key;

    ...
}

Only OpenSSL 1.0.2 or higher supports separate
certificate
chains
for different certificates.
With older versions, only one certificate chain can be used.

Since version 1.15.9, variables can be used in the file name
when using OpenSSL 1.0.2 or higher:

ssl_certificate     $ssl_server_name.crt;
ssl_certificate_key $ssl_server_name.key;

Note that using variables implies that
a certificate will be loaded for each SSL handshake,
and this may have a negative impact on performance.

The value
data:$variable
can be specified instead of the file (1.15.10),
which loads a certificate from a variable
without using intermediate files.
Note that inappropriate use of this syntax may have its security implications,
such as writing secret key data to
error log.

It should be kept in mind that due to the SSL/TLS protocol limitations,
for maximum interoperability with clients that do not use
SNI,
virtual servers with different certificates should listen on
different
IP addresses.

            Syntax:

            ssl_certificate_cache off;
ssl_certificate_cache
    max=N
    [inactive=time]
    [valid=time];

            Default:

ssl_certificate_cache off;

            Context:

            stream, server

This directive appeared in version 1.27.4.

Defines a cache that stores
SSL certificates and
secret keys
specified with variables.

The directive has the following parameters:

max

sets the maximum number of elements in the cache;
on cache overflow the least recently used (LRU) elements are removed;

inactive

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;

valid

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;

off

disables the cache.

Example:

ssl_certificate       $ssl_server_name.crt;
ssl_certificate_key   $ssl_server_name.key;
ssl_certificate_cache max=1000 inactive=20s valid=1m;

            Syntax:

            ssl_certificate_compression on | off;

            Default:

ssl_certificate_compression off;

            Context:

            stream, server

This directive appeared in version 1.29.1.

Enables TLS 1.3
compression
of server certificates.

The directive is supported when using OpenSSL 3.2 or higher;
the list of supported compression algorithms is provided by the library.

The directive is supported when using BoringSSL;
the list of supported compression algorithms includes
zlib (1.29.3).

            Syntax:

            ssl_certificate_key file;

            Default:

            —

            Context:

            stream, server

Specifies a file with the secret key in the PEM format
for the given virtual server.

The value
engine:name:id
can be specified instead of the file,
which loads a secret key with a specified id
from the OpenSSL engine name.

The value
store:scheme:id
can be specified instead of the file (1.29.0),
which is used to load a secret key with a specified id
and OpenSSL provider registered URI scheme, such as
pkcs11.

The value
data:$variable
can be specified instead of the file (1.15.10),
which loads a secret key from a variable without using intermediate files.
Note that inappropriate use of this syntax may have its security implications,
such as writing secret key data to
error log.

Since version 1.15.9, variables can be used in the file name
when using OpenSSL 1.0.2 or higher.

            Syntax:

            ssl_ciphers ciphers;

            Default:

ssl_ciphers HIGH:!aNULL:!MD5;

            Context:

            stream, server

Specifies the enabled ciphers.
The ciphers are specified in the format understood by the
OpenSSL library, for example:

ssl_ciphers ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;

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

            Syntax:

            ssl_client_certificate file;

            Default:

            —

            Context:

            stream, server

This directive appeared in version 1.11.8.

Specifies a file with trusted CA certificates in the PEM format
used to verify client certificates and
OCSP responses if ssl_stapling is enabled.

The list of certificates will be sent to clients.
If this is not desired, the ssl_trusted_certificate
directive can be used.

            Syntax:

            ssl_conf_command name value;

            Default:

            —

            Context:

            stream, server

This directive appeared in version 1.19.4.

Sets arbitrary OpenSSL configuration
commands.

The directive is supported when using OpenSSL 1.0.2 or higher.

Several ssl_conf_command directives
can be specified on the same level:

ssl_conf_command Options PrioritizeChaCha;
ssl_conf_command Ciphersuites TLS_CHACHA20_POLY1305_SHA256;

These directives are inherited from the previous configuration level
if and only if there are no ssl_conf_command directives
defined on the current level.

Note that configuring OpenSSL directly
might result in unexpected behavior.

            Syntax:

            ssl_crl file;

            Default:

            —

            Context:

            stream, server

This directive appeared in version 1.11.8.

Specifies a file with revoked certificates (CRL)
in the PEM format used to verify
client certificates.
When using intermediate certificates, their CRLs should be
specified in the same file.

            Syntax:

            ssl_dhparam file;

            Default:

            —

            Context:

            stream, server

Specifies a file with DH parameters for DHE ciphers.

By default no parameters are set,
and therefore DHE ciphers will not be used.

Prior to version 1.11.0, builtin parameters were used by default.

            Syntax:

            ssl_ecdh_curve curve;

            Default:

ssl_ecdh_curve auto;

            Context:

            stream, server

Specifies a curve for ECDHE ciphers.

When using OpenSSL 1.0.2 or higher,
it is possible to specify multiple curves (1.11.0), for example:

ssl_ecdh_curve prime256v1:secp384r1;

The special value auto (1.11.0) instructs nginx to use
a list built into the OpenSSL library when using OpenSSL 1.0.2 or higher,
or prime256v1 with older versions.

Prior to version 1.11.0,
the prime256v1 curve was used by default.

When using OpenSSL 1.0.2 or higher,
this directive sets the list of curves supported by the server.
Thus, in order for ECDSA certificates to work,
it is important to include the curves used in the certificates.

            Syntax:

            ssl_ech_file file;

            Default:

            —

            Context:

            stream, server

This directive appeared in version 1.29.4.

Specifies a file with encrypted ClientHello configuration
(ECHConfig) in the
PEM
format used to enable TLS 1.3
ECH
in shared mode.

The directive is currently supported only when using OpenSSL
ECH
feature branch.

            Syntax:

            ssl_handshake_timeout time;

            Default:

ssl_handshake_timeout 60s;

            Context:

            stream, server

Specifies a timeout for the SSL handshake to complete.

            Syntax:

            ssl_key_log path;

            Default:

            —

            Context:

            stream, server

This directive appeared in version 1.27.2.

Enables logging of client connection SSL keys
and specifies the path to the key log file.
Keys are logged in the
SSLKEYLOGFILE
format compatible with Wireshark.

This directive is available as part of our
commercial subscription.

            Syntax:

            ssl_ocsp on |
        off |
        leaf;

            Default:

ssl_ocsp off;

            Context:

            stream, server

This directive appeared in version 1.27.2.

Enables OCSP validation of the client certificate chain.
The leaf parameter
enables validation of the client certificate only.

For the OCSP validation to work,
the ssl_verify_client directive should be set to
on or optional.

To resolve the OCSP responder hostname,
the resolver directive
should also be specified.

Example:

ssl_verify_client on;
ssl_ocsp          on;
resolver          192.0.2.1;

            Syntax:

            ssl_ocsp_cache
    off |
    [shared:name:size];

            Default:

ssl_ocsp_cache off;

            Context:

            stream, server

This directive appeared in version 1.27.2.

Sets name and size of the cache
that stores client certificates status for OCSP validation.
The cache is shared between all worker processes.
A cache with the same name can be used in several
virtual servers.

The off parameter prohibits the use of the cache.

            Syntax:

            ssl_ocsp_responder url;

            Default:

            —

            Context:

            stream, server

This directive appeared in version 1.27.2.

Overrides the URL of the OCSP responder specified in the
“Authority
Information Access” certificate extension
for validation of client certificates.

Only “http://” OCSP responders are supported:

ssl_ocsp_responder http://ocsp.example.com/;

            Syntax:

            ssl_password_file file;

            Default:

            —

            Context:

            stream, server

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

Example:

stream {
    ssl_password_file /etc/keys/global.pass;
    ...

    server {
        listen 127.0.0.1:12345;
        ssl_certificate_key /etc/keys/first.key;
    }

    server {
        listen 127.0.0.1:12346;

        # named pipe can also be used instead of a file
        ssl_password_file /etc/keys/fifo;
        ssl_certificate_key /etc/keys/second.key;
    }
}

            Syntax:

            ssl_prefer_server_ciphers on | off;

            Default:

ssl_prefer_server_ciphers off;

            Context:

            stream, server

Specifies that server ciphers should be preferred over client ciphers
when the SSLv3 and TLS protocols are used.

            Syntax:

            ssl_protocols
    [SSLv2]
    [SSLv3]
    [TLSv1]
    [TLSv1.1]
    [TLSv1.2]
    [TLSv1.3];

            Default:

ssl_protocols TLSv1.2 TLSv1.3;

            Context:

            stream, server

Enables the specified protocols.

If the directive is specified
on the server level,
the value from the default server can be used.
Details are provided in the
“Virtual
server selection” section.

The TLSv1.1 and TLSv1.2 parameters
work only when OpenSSL 1.0.1 or higher is used.

The TLSv1.3 parameter (1.13.0) works only when
OpenSSL 1.1.1 or higher is used.

The TLSv1.3 parameter is used by default
since 1.23.4.

            Syntax:

            ssl_reject_handshake on | off;

            Default:

ssl_reject_handshake off;

            Context:

            stream, server

This directive appeared in version 1.25.5.

If enabled, SSL handshakes in
the server block will be rejected.

For example, in the following configuration, SSL handshakes with
server names other than example.com are rejected:

server {
    listen               443 ssl default_server;
    ssl_reject_handshake on;
}

server {
    listen              443 ssl;
    server_name         example.com;
    ssl_certificate     example.com.crt;
    ssl_certificate_key example.com.key;
}

            Syntax:

            ssl_session_cache
    off |
    none |
    [builtin[:size]]
    [shared:name:size];

            Default:

ssl_session_cache none;

            Context:

            stream, server

Sets the types and sizes of caches that store session parameters.
A cache can be of any of the following types:

off

the use of a session cache is strictly prohibited:
nginx explicitly tells a client that sessions may not be reused.

none

the use of a session cache is gently disallowed:
nginx tells a client that sessions may be reused, but does not
actually store session parameters in the cache.

builtin

a cache built in OpenSSL; used by one worker process only.
The cache size is specified in sessions.
If size is not given, it is equal to 20480 sessions.
Use of the built-in cache can cause memory fragmentation.

shared

a cache shared between all worker processes.
The cache size is specified in bytes; one megabyte can store
about 4000 sessions.
Each shared cache should have an arbitrary name.
A cache with the same name can be used in several
virtual servers.
It is also used to automatically generate, store, and
periodically rotate TLS session ticket keys (1.23.2)
unless configured explicitly
using the ssl_session_ticket_key directive.

Both cache types can be used simultaneously, for example:

ssl_session_cache builtin:1000 shared:SSL:10m;

but using only shared cache without the built-in cache should
be more efficient.

            Syntax:

            ssl_session_ticket_key file;

            Default:

            —

            Context:

            stream, server

Sets a file with the secret key used to encrypt
and decrypt TLS session tickets.
The directive is necessary if the same key has to be shared between
multiple servers.
By default, a randomly generated key is used.

If several keys are specified, only the first key is
used to encrypt TLS session tickets.
This allows configuring key rotation, for example:

ssl_session_ticket_key current.key;
ssl_session_ticket_key previous.key;

The file must contain 80 or 48 bytes
of random data and can be created using the following command:

openssl rand 80 > ticket.key

Depending on the file size either AES256 (for 80-byte keys, 1.11.8)
or AES128 (for 48-byte keys) is used for encryption.

            Syntax:

            ssl_session_tickets on | off;

            Default:

ssl_session_tickets on;

            Context:

            stream, server

Enables or disables session resumption through
TLS session tickets.

            Syntax:

            ssl_session_timeout time;

            Default:

ssl_session_timeout 5m;

            Context:

            stream, server

Specifies a time during which a client may reuse the
session parameters.

            Syntax:

            ssl_stapling on | off;

            Default:

ssl_stapling off;

            Context:

            stream, server

This directive appeared in version 1.27.2.

Enables or disables
stapling
of OCSP responses by the server.
Example:

ssl_stapling on;
resolver 192.0.2.1;

For the OCSP stapling to work, the certificate of the server certificate
issuer should be known.
If the ssl_certificate file does
not contain intermediate certificates,
the certificate of the server certificate issuer should be
present in the
ssl_trusted_certificate file.

For a resolution of the OCSP responder hostname,
the resolver directive
should also be specified.

            Syntax:

            ssl_stapling_file file;

            Default:

            —

            Context:

            stream, server

This directive appeared in version 1.27.2.

When set, the stapled OCSP response will be taken from the
specified file instead of querying
the OCSP responder specified in the server certificate.

The file should be in the DER format as produced by the
“openssl ocsp” command.

            Syntax:

            ssl_stapling_responder url;

            Default:

            —

            Context:

            stream, server

This directive appeared in version 1.27.2.

Overrides the URL of the OCSP responder specified in the
“Authority
Information Access” certificate extension.

Only “http://” OCSP responders are supported:

ssl_stapling_responder http://ocsp.example.com/;

            Syntax:

            ssl_stapling_verify on | off;

            Default:

ssl_stapling_verify off;

            Context:

            stream, server

This directive appeared in version 1.27.2.

Enables or disables verification of OCSP responses by the server.

For verification to work, the certificate of the server certificate
issuer, the root certificate, and all intermediate certificates
should be configured as trusted using the
ssl_trusted_certificate directive.

            Syntax:

            ssl_trusted_certificate file;

            Default:

            —

            Context:

            stream, server

This directive appeared in version 1.11.8.

Specifies a file with trusted CA certificates in the PEM format
used to verify client certificates and
OCSP responses if ssl_stapling is enabled.

In contrast to the certificate set by ssl_client_certificate,
the list of these certificates will not be sent to clients.

            Syntax:

            ssl_verify_client
    on | off |
    optional | optional_no_ca;

            Default:

ssl_verify_client off;

            Context:

            stream, server

This directive appeared in version 1.11.8.

Enables verification of client certificates.
The verification result is stored in the
$ssl_client_verify variable.
If an error has occurred during the client certificate verification
or a client has not presented the required certificate,
the connection is closed.

The optional parameter requests the client
certificate and verifies it if the certificate is present.

The optional_no_ca parameter
requests the client
certificate but does not require it to be signed by a trusted CA certificate.
This is intended for the use in cases when a service that is external to nginx
performs the actual certificate verification.
The contents of the certificate is accessible through the
$ssl_client_cert variable.

            Syntax:

            ssl_verify_depth number;

            Default:

ssl_verify_depth 1;

            Context:

            stream, server

This directive appeared in version 1.11.8.

Sets the verification depth in the client certificates chain.

Embedded Variables

The ngx_stream_ssl_module module supports variables
since 1.11.2.

$ssl_alpn_protocol

returns the protocol selected by ALPN during the SSL handshake,
or an empty string otherwise (1.21.4);

$ssl_cipher

returns the name of the cipher used
for an established SSL connection;

$ssl_ciphers

returns the list of ciphers supported by the client (1.11.7).
Known ciphers are listed by names, unknown are shown in hexadecimal,
for example:

AES128-SHA:AES256-SHA:0x00ff

The variable is fully supported only when using OpenSSL version 1.0.2 or higher.
With older versions, the variable is available
only for new sessions and lists only known ciphers.

$ssl_client_cert

returns the client certificate in the PEM format
for an established SSL connection, with each line except the first
prepended with the tab character (1.11.8);

$ssl_client_fingerprint

returns the SHA1 fingerprint of the client certificate
for an established SSL connection (1.11.8);

$ssl_client_i_dn

returns the “issuer DN” string of the client certificate
for an established SSL connection according to
RFC 2253 (1.11.8);

$ssl_client_raw_cert

returns the client certificate in the PEM format
for an established SSL connection (1.11.8);

$ssl_client_s_dn

returns the “subject DN” string of the client certificate
for an established SSL connection according to
RFC 2253 (1.11.8);

$ssl_client_serial

returns the serial number of the client certificate
for an established SSL connection (1.11.8);

$ssl_client_sigalg

returns the
signature algorithm
for the client certificate for an established SSL connection (1.29.3).

The variable is supported only when using OpenSSL version 3.5 or higher.
With older versions, the variable value will be an empty string.

The variable is available only for new sessions.

$ssl_client_v_end

returns the end date of the client certificate (1.11.8);

$ssl_client_v_remain

returns the number of days
until the client certificate expires (1.11.8);

$ssl_client_v_start

returns the start date of the client certificate (1.11.8);

$ssl_client_verify

returns the result of client certificate verification (1.11.8):
“SUCCESS”, “FAILED:reason”,
and “NONE” if a certificate was not present;

$ssl_curve

returns the negotiated curve used for
SSL handshake key exchange process (1.21.5).
Known curves are listed by names, unknown are shown in hexadecimal,
for example:

prime256v1

The variable is supported only when using OpenSSL version 3.0 or higher.
With older versions, the variable value will be an empty string.

$ssl_curves

returns the list of curves supported by the client (1.11.7).
Known curves are listed by names, unknown are shown in hexadecimal,
for example:

0x001d:prime256v1:secp521r1:secp384r1

The variable is supported only when using OpenSSL version 1.0.2 or higher.
With older versions, the variable value will be an empty string.

The variable is available only for new sessions.

$ssl_ech_outer_server_name

returns the public server name requested through
SNI
if TLS 1.3 ECH was accepted,
otherwise “” (1.29.4);

$ssl_ech_status

returns the result of TLS 1.3 ECH processing:
“FAILED”,
“BACKEND”,
“GREASE”,
“SUCCESS”, or
“NOT_TRIED” (1.29.4);

The variable is currently supported only when using OpenSSL
ECH feature branch
and is therefore subject to change.
The variable value will otherwise be an empty string.

$ssl_protocol

returns the protocol of an established SSL connection;

$ssl_server_name

returns the server name requested through
SNI;

$ssl_session_id

returns the session identifier of an established SSL connection;

$ssl_session_reused

returns “r” if an SSL session was reused,
or “.” otherwise.

$ssl_sigalg

returns the
signature algorithm
for the server certificate for an established SSL connection (1.29.3).

The variable is supported only when using OpenSSL version 3.5 or higher.
With older versions, the variable value will be an empty string.

The variable is available only for new sessions.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_stream_ssl_preread_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Module ngx_stream_ssl_preread_module

Example Configuration
Directives
     ssl_preread
Embedded Variables

The ngx_stream_ssl_preread_module module (1.11.5) allows
extracting information from the
ClientHello
message without terminating SSL/TLS,
for example, the server name requested through
SNI
or protocols advertised in
ALPN.
This module is not built by default, it should be enabled with the
--with-stream_ssl_preread_module
configuration parameter.

Example Configuration

Selecting an upstream based on server name:

map $ssl_preread_server_name $name {
    backend.example.com      backend;
    default                  backend2;
}

upstream backend {
    server 192.168.0.1:12345;
    server 192.168.0.2:12345;
}

upstream backend2 {
    server 192.168.0.3:12345;
    server 192.168.0.4:12345;
}

server {
    listen      12346;
    proxy_pass  $name;
    ssl_preread on;
}

Selecting an upstream based on protocol:

map $ssl_preread_alpn_protocols $proxy {
    ~\bh2\b           127.0.0.1:8001;
    ~\bhttp/1.1\b     127.0.0.1:8002;
    ~\bxmpp-client\b  127.0.0.1:8003;
}

server {
    listen      9000;
    proxy_pass  $proxy;
    ssl_preread on;
}

Selecting an upstream based on SSL protocol version:

map $ssl_preread_protocol $upstream {
    ""        ssh.example.com:22;
    "TLSv1.2" new.example.com:443;
    default   tls.example.com:443;
}

# ssh and https on the same port
server {
    listen      192.168.0.1:443;
    proxy_pass  $upstream;
    ssl_preread on;
}

Directives

            Syntax:

            ssl_preread on | off;

            Default:

ssl_preread off;

            Context:

            stream, server

Enables extracting information from the ClientHello message at
the preread phase.

Embedded Variables

$ssl_preread_protocol

the highest SSL protocol version supported by the client (1.15.2)

$ssl_preread_server_name

server name requested through SNI

$ssl_preread_alpn_protocols

list of protocols advertised by the client through ALPN (1.13.10).
The values are separated by commas.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_stream_upstream_hc_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Module ngx_stream_upstream_hc_module

Example Configuration
Directives
     health_check
     health_check_timeout
     match

The ngx_stream_upstream_hc_module module (1.9.0)
allows enabling periodic health checks of the servers in a
group.
The server group must reside in the
shared memory.

If a health check fails, the server will be considered unhealthy.
If several health checks are defined for the same group of servers,
a single failure of any check will make the corresponding server be
considered unhealthy.
Client connections are not passed to unhealthy servers
and servers in the “checking” state.

This module is available as part of our
commercial subscription.

Example Configuration

upstream tcp {
    zone upstream_tcp 64k;

    server backend1.example.com:12345 weight=5;
    server backend2.example.com:12345 fail_timeout=5s slow_start=30s;
    server 192.0.2.1:12345            max_fails=3;

    server backup1.example.com:12345  backup;
    server backup2.example.com:12345  backup;
}

server {
    listen     12346;
    proxy_pass tcp;
    health_check;
}

With this configuration, nginx
will check the ability to establish a TCP connection to each server
in the tcp group every five seconds.
When a connection to the server cannot be established,
the health check will fail, and the server will
be considered unhealthy.

Health checks can be configured for the UDP protocol:

upstream dns_upstream {

    zone   dns_zone 64k;

    server dns1.example.com:53;
    server dns2.example.com:53;
    server dns3.example.com:53;
}

server {
    listen       53 udp;
    proxy_pass   dns_upstream;
    health_check udp;
}

In this case, the absence of
ICMP “Destination Unreachable” message is expected
in reply to the sent string “nginx health check”.

Health checks can also be configured to test data obtained from the server.
Tests are configured separately using the match directive
and referenced in the match parameter
of the health_check directive.

Directives

            Syntax:

            health_check [parameters];

            Default:

            —

            Context:

            server

Enables periodic health checks of the servers in a
group.

The following optional parameters are supported:

interval=time

sets the interval between two consecutive health checks,
by default, 5 seconds.

jitter=time

sets the time within which
each health check will be randomly delayed,
by default, there is no delay.

fails=number

sets the number of consecutive failed health checks of a particular server
after which this server will be considered unhealthy,
by default, 1.

passes=number

sets the number of consecutive passed health checks of a particular server
after which the server will be considered healthy,
by default, 1.

mandatory [persistent]

sets the initial “checking” state for a server
until the first health check is completed (1.11.7).
Client connections are not passed to servers in the “checking” state.
If the parameter is not specified,
the server will be initially considered healthy.

The persistent parameter (1.21.1)
sets the initial “up” state for a server after reload
if the server was considered healthy before reload.

match=name

specifies the match block configuring the tests that a
successful connection should pass in order for a health check to pass.
By default, for TCP, only the ability
to establish a TCP connection with the server is checked.
For UDP, the absence of
ICMP “Destination Unreachable” message is expected
in reply to the sent string “nginx health check”.

Prior to version 1.11.7, by default, UDP health check
required a match block with the
send and expect
parameters.

port=number

defines the port used when connecting to a server
to perform a health check (1.9.7).
By default, equals the
server port.

udp

specifies that the UDP protocol should be used for
health checks instead of the default TCP protocol (1.9.13).

            Syntax:

            health_check_timeout timeout;

            Default:

health_check_timeout 5s;

            Context:

            stream, server

Overrides the
proxy_timeout
value for health checks.

            Syntax:

            match name  { ... }

            Default:

            —

            Context:

            stream

Defines the named test set used to verify server responses to health checks.

The following parameters can be configured:

send string;

sends a string to the server;

expect string |
~ regex;

a literal string (1.9.12) or a regular expression
that the data obtained from the server should match.
The regular expression is specified with the preceding
“~*” modifier (for case-insensitive matching), or the
“~” modifier (for case-sensitive matching).

Both send and expect parameters
can contain hexadecimal literals with the prefix “\x”
followed by two hex digits, for example, “\x80” (1.9.12).

Health check is passed if:

the TCP connection was successfully established;

the string from the send parameter,
if specified, was sent;

the data obtained from the server matched the string or regular expression
from the expect parameter, if specified;

the time elapsed does not exceed the value specified
in the health_check_timeout directive.

Example:

upstream backend {
    zone     upstream_backend 10m;
    server   127.0.0.1:12345;
}

match http {
    send     "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n";
    expect ~ "200 OK";
}

server {
    listen       12346;
    proxy_pass   backend;
    health_check match=http;
}

Only the first
proxy_buffer_size
bytes of data obtained from the server are examined.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_stream_upstream_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Module ngx_stream_upstream_module

Example Configuration
Directives
     upstream
     server
     zone
     state
     hash
     least_conn
     least_time
     random
     resolver
     resolver_timeout
Embedded Variables

The ngx_stream_upstream_module module (1.9.0)
is used to define groups of servers that can be referenced
by the proxy_pass
directive.

Example Configuration

upstream backend {
    hash $remote_addr consistent;

    server backend1.example.com:12345  weight=5;
    server backend2.example.com:12345;
    server unix:/tmp/backend3;

    server backup1.example.com:12345   backup;
    server backup2.example.com:12345   backup;
}

server {
    listen 12346;
    proxy_pass backend;
}

Dynamically configurable group with
periodic health checks is
available as part of our
commercial subscription:

resolver 10.0.0.1;

upstream dynamic {
    zone upstream_dynamic 64k;

    server backend1.example.com:12345 weight=5;
    server backend2.example.com:12345 fail_timeout=5s slow_start=30s;
    server 192.0.2.1:12345            max_fails=3;
    server backend3.example.com:12345 resolve;
    server backend4.example.com       service=http resolve;

    server backup1.example.com:12345  backup;
    server backup2.example.com:12345  backup;
}

server {
    listen 12346;
    proxy_pass dynamic;
    health_check;
}

Directives

            Syntax:

            upstream name { ... }

            Default:

            —

            Context:

            stream

Defines a group of servers.
Servers can listen on different ports.
In addition, servers listening on TCP and UNIX-domain sockets
can be mixed.

Example:

upstream backend {
    server backend1.example.com:12345 weight=5;
    server 127.0.0.1:12345            max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend2;
    server backend3.example.com:12345 resolve;

    server backup1.example.com:12345  backup;
}

By default, connections are distributed between the servers using a
weighted round-robin balancing method.
In the above example, each 7 connections will be distributed as follows:
5 connections go to backend1.example.com:12345
and one connection to each of the second and third servers.
If an error occurs during communication with a server, the connection will
be passed to the next server, and so on until all of the functioning
servers will be tried.
If communication with all servers fails, the connection will be closed.

            Syntax:

            server address [parameters];

            Default:

            —

            Context:

            upstream

Defines the address and other parameters
of a server.
The address can be specified as a domain name or IP address
with an obligatory port, or as a UNIX-domain socket path
specified after the “unix:” prefix.
A domain name that resolves to several IP addresses defines
multiple servers at once.

The following parameters can be defined:

weight=number

sets the weight of the server, by default, 1.

max_conns=number

limits the maximum number of simultaneous
connections to the proxied server (1.11.5).
Default value is zero, meaning there is no limit.
If the server group does not reside in the shared memory,
the limitation works per each worker process.

Prior to version 1.11.5, this parameter was available as part of our
commercial subscription.

max_fails=number

sets the number of unsuccessful attempts to communicate with the server
that should happen in the duration set by the fail_timeout
parameter to consider the server unavailable for a duration also set by the
fail_timeout parameter.
By default, the number of unsuccessful attempts is set to 1.
The zero value disables the accounting of attempts.
Here, an unsuccessful attempt is an error or timeout
while establishing a connection with the server.

fail_timeout=time

sets

the time during which the specified number of unsuccessful attempts to
communicate with the server should happen to consider the server unavailable;

and the period of time the server will be considered unavailable.

By default, the parameter is set to 10 seconds.

backup

marks the server as a backup server.
Connections to the backup server will be passed
when the primary servers are unavailable.

The parameter cannot be used along with the
hash and random load balancing methods.

down

marks the server as permanently unavailable.

resolve

monitors changes of the IP addresses
that correspond to a domain name of the server,
and automatically modifies the upstream configuration
without the need of restarting nginx.
The server group must reside in the shared memory.

In order for this parameter to work,
the resolver directive
must be specified in the
stream block
or in the corresponding upstream block.

Prior to version 1.27.3, this parameter was available only as part of our
commercial subscription.

service=name

enables resolving of DNS
SRV
records and sets the service name (1.9.13).
In order for this parameter to work, it is necessary to specify
the resolve parameter for the server
and specify a hostname without a port number.

If the service name does not contain a dot (“.”), then
the RFC-compliant name
is constructed
and the TCP protocol is added to the service prefix.
For example, to look up the
_http._tcp.backend.example.com SRV record,
it is necessary to specify the directive:

server backend.example.com service=http resolve;

If the service name contains one or more dots, then the name is constructed
by joining the service prefix and the server name.
For example, to look up the _http._tcp.backend.example.com
and server1.backend.example.com SRV records,
it is necessary to specify the directives:

server backend.example.com service=_http._tcp resolve;
server example.com service=server1.backend resolve;

Highest-priority SRV records
(records with the same lowest-number priority value)
are resolved as primary servers,
the rest of SRV records are resolved as backup servers.
If the backup parameter is specified for the server,
high-priority SRV records are resolved as backup servers,
the rest of SRV records are ignored.

Prior to version 1.27.3, this parameter was available only as part of our
commercial subscription.

Additionally,
the following parameters are available as part of our
commercial subscription:

slow_start=time

sets the time during which the server will recover its weight
from zero to a nominal value, when unhealthy server becomes
healthy,
or when the server becomes available after a period of time
it was considered unavailable.
Default value is zero, i.e. slow start is disabled.

The parameter cannot be used along with the
hash and random load balancing methods.

If there is only a single server in a group, max_fails,
fail_timeout and slow_start parameters
are ignored, and such a server will never be considered unavailable.

            Syntax:

            zone name [size];

            Default:

            —

            Context:

            upstream

Defines the name and size of the shared
memory zone that keeps the group’s configuration and run-time state that are
shared between worker processes.
Several groups may share the same zone.
In this case, it is enough to specify the size only once.

Additionally,
as part of our commercial subscription,
such groups allow changing the group membership
or modifying the settings of a particular server
without the need of restarting nginx.
The configuration is accessible via the
API module (1.13.3).

Prior to version 1.13.3,
the configuration was accessible only via a special location
handled by
upstream_conf.

            Syntax:

            state file;

            Default:

            —

            Context:

            upstream

This directive appeared in version 1.9.7.

Specifies a file that keeps the state
of the dynamically configurable group.

Examples:

state /var/lib/nginx/state/servers.conf; # path for Linux
state /var/db/nginx/state/servers.conf;  # path for FreeBSD

The state is currently limited to the list of servers with their parameters.
The file is read when parsing the configuration and is updated each time
the upstream configuration is
changed.
Changing the file content directly should be avoided.
The directive cannot be used
along with the server directive.

Changes made during
configuration reload
or binary upgrade
can be lost.

This directive is available as part of our
commercial subscription.

            Syntax:

            hash key [consistent];

            Default:

            —

            Context:

            upstream

Specifies a load balancing method for a server group
where the client-server mapping is based on the hashed key value.
The key can contain text, variables,
and their combinations (1.11.2).
Usage example:

hash $remote_addr;

Note that adding or removing a server from the group
may result in remapping most of the keys to different servers.
The method is compatible with the
Cache::Memcached
Perl library.

If the consistent parameter is specified,
the ketama
consistent hashing method will be used instead.
The method ensures that only a few keys
will be remapped to different servers
when a server is added to or removed from the group.
This helps to achieve a higher cache hit ratio for caching servers.
The method is compatible with the
Cache::Memcached::Fast
Perl library with the ketama_points parameter set to 160.

            Syntax:

            least_conn;

            Default:

            —

            Context:

            upstream

Specifies that a group should use a load balancing method where a connection
is passed to the server with the least number of active connections,
taking into account weights of servers.
If there are several such servers, they are tried in turn using a
weighted round-robin balancing method.

            Syntax:

            least_time
    connect |
    first_byte |
    last_byte
    [inflight];

            Default:

            —

            Context:

            upstream

This directive appeared in version 1.7.11.

Specifies that a group should use a load balancing method where a connection
is passed to the server with the least average time and
least number of active connections, taking into account weights of servers.
If there are several such servers, they are tried in turn using a
weighted round-robin balancing method.

If the connect parameter is specified,
time to
connect
to the upstream server is used.
If the first_byte parameter is specified,
time to receive the
first byte of data is used.
If the last_byte is specified,
time to receive the
last byte of data is used.
If the inflight parameter is specified (1.11.6),
incomplete connections are also taken into account.

Prior to version 1.11.6,
incomplete connections were taken into account by default.

Prior to version 1.31.0,
this directive was available only as part of our
commercial subscription.

            Syntax:

            random [two [method]];

            Default:

            —

            Context:

            upstream

This directive appeared in version 1.15.1.

Specifies that a group should use a load balancing method where a connection
is passed to a randomly selected server, taking into account weights
of servers.

The optional two parameter
instructs nginx to randomly select
two
servers and then choose a server
using the specified method.
The default method is least_conn
which passes a connection to a server
with the least number of active connections.

The least_time method passes a connection to a server
with the least average time and least number of active connections.
If least_time=connect parameter is specified,
time to
connect
to the upstream server is used.
If least_time=first_byte parameter is specified,
time to receive the
first byte of data is used.
If least_time=last_byte is specified,
time to receive the
last byte of data is used.

The least_time method is available as a part of our
commercial subscription.

            Syntax:

            resolver
    address ...
    [valid=time]
    [ipv4=on|off]
    [ipv6=on|off]
    [status_zone=zone];

            Default:

            —

            Context:

            upstream

This directive appeared in version 1.27.3.

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

resolver 127.0.0.1 [::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.

By default, nginx will look up both IPv4 and IPv6 addresses while resolving.
If looking up of IPv4 or IPv6 addresses is not desired,
the ipv4=off (1.23.1) or
the ipv6=off parameter can be specified.

By default, nginx caches answers using the TTL value of a response.
The optional valid parameter allows overriding it:

resolver 127.0.0.1 [::1]:5353 valid=30s;

To prevent DNS spoofing, it is recommended
configuring DNS servers in a properly secured trusted local network.

The optional status_zone parameter (1.17.5)
enables
collection
of DNS server statistics of requests and responses
in the specified zone.
The parameter is available as part of our
commercial subscription.

Since version 1.17.5 and prior to version 1.27.3,
this directive was available only as part of our
commercial subscription.

            Syntax:

            resolver_timeout time;

            Default:

resolver_timeout 30s;

            Context:

            upstream

This directive appeared in version 1.27.3.

Sets a timeout for name resolution, for example:

resolver_timeout 5s;

Since version 1.17.5 and prior to version 1.27.3,
this directive was available only as part of our
commercial subscription.

Embedded Variables

The ngx_stream_upstream_module module
supports the following embedded variables:

$upstream_addr

keeps the IP address and port,
or the path to the UNIX-domain socket of the upstream server (1.11.4).
If several servers were contacted during proxying,
their addresses are separated by commas, e.g.
“192.168.1.1:12345, 192.168.1.2:12345, unix:/tmp/sock”.
If a server cannot be selected,
the variable keeps the name of the server group.

$upstream_bytes_received

number of bytes received from an upstream server (1.11.4).
Values from several connections
are separated by commas like addresses in the
$upstream_addr variable.

$upstream_bytes_sent

number of bytes sent to an upstream server (1.11.4).
Values from several connections
are separated by commas like addresses in the
$upstream_addr variable.

$upstream_connect_time

time to connect to the upstream server (1.11.4);
the time is kept in seconds with millisecond resolution.
Times of several connections
are separated by commas like addresses in the
$upstream_addr variable.

$upstream_first_byte_time

time to receive the first byte of data (1.11.4);
the time is kept in seconds with millisecond resolution.
Times of several connections
are separated by commas like addresses in the
$upstream_addr variable.

$upstream_last_addr

keeps the IP address or the path to the UNIX-domain socket
of the last selected upstream server (1.29.3).

This variable is available as part of our
commercial subscription.

$upstream_session_time

session duration in seconds with millisecond resolution (1.11.4).
Times of several connections
are separated by commas like addresses in the
$upstream_addr variable.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>Module ngx_stream_zone_sync_module</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

Module ngx_stream_zone_sync_module

Example Configuration
Directives
     zone_sync
     zone_sync_buffers
     zone_sync_connect_retry_interval
     zone_sync_connect_timeout
     zone_sync_interval
     zone_sync_recv_buffer_size
     zone_sync_server
     zone_sync_ssl
     zone_sync_ssl_certificate
     zone_sync_ssl_certificate_key
     zone_sync_ssl_ciphers
     zone_sync_ssl_conf_command
     zone_sync_ssl_crl
     zone_sync_ssl_name
     zone_sync_ssl_password_file
     zone_sync_ssl_protocols
     zone_sync_ssl_server_name
     zone_sync_ssl_trusted_certificate
     zone_sync_ssl_verify
     zone_sync_ssl_verify_depth
     zone_sync_timeout
API endpoints
Starting, stopping, removing a cluster node

The ngx_stream_zone_sync_module module (1.13.8)
provides the necessary support for synchronizing contents of
shared memory zones
between nodes of a cluster.
To enable synchronization for a particular zone, a corresponding module
must support this feature.
Currently, it is possible to synchronize HTTP
sticky
sessions, information about
excessive HTTP requests,
and key-value pairs both in
http
and stream.

This module is available as part of our
commercial subscription.

Example Configuration

Minimal configuration:

http {
    ...

    upstream backend {
       server backend1.example.com:8080;
       server backend2.example.com:8081;

       sticky learn
              create=$upstream_cookie_examplecookie
              lookup=$cookie_examplecookie
              zone=client_sessions:1m sync;
    }

    ...
}

stream {
    ...

    server {
        zone_sync;

        listen 127.0.0.1:12345;

        # cluster of 2 nodes
        zone_sync_server a.example.com:12345;
        zone_sync_server b.example.com:12345;

    }

A more complex configuration with SSL enabled
and with cluster members defined by DNS:

...

stream {
    ...

    resolver 127.0.0.1 valid=10s;

    server {
        zone_sync;

        # the name resolves to multiple addresses that correspond to cluster nodes
        zone_sync_server cluster.example.com:12345 resolve;

        listen 127.0.0.1:4433 ssl;

        ssl_certificate     localhost.crt;
        ssl_certificate_key localhost.key;

        zone_sync_ssl on;

        zone_sync_ssl_certificate     localhost.crt;
        zone_sync_ssl_certificate_key localhost.key;
    }
}

Directives

            Syntax:

            zone_sync;

            Default:

            —

            Context:

            server

Enables the synchronization of shared memory zones between cluster nodes.
Cluster nodes are defined using zone_sync_server directives.

            Syntax:

            zone_sync_buffers number size;

            Default:

zone_sync_buffers 8 4k|8k;

            Context:

            stream, server

Sets the number and size of the
per-zone buffers used for pushing zone contents.
By default, the buffer size is equal to one memory page.
This is either 4K or 8K, depending on a platform.

A single buffer must be large enough to hold any entry of each zone being
synchronized.

            Syntax:

            zone_sync_connect_retry_interval time;

            Default:

zone_sync_connect_retry_interval 1s;

            Context:

            stream, server

Defines an interval between connection attempts to another cluster node.

            Syntax:

            zone_sync_connect_timeout time;

            Default:

zone_sync_connect_timeout 5s;

            Context:

            stream, server

Defines a timeout for establishing a connection with another cluster node.

            Syntax:

            zone_sync_interval time;

            Default:

zone_sync_interval 1s;

            Context:

            stream, server

Defines an interval for polling updates in a shared memory zone.

            Syntax:

            zone_sync_recv_buffer_size size;

            Default:

zone_sync_recv_buffer_size 4k|8k;

            Context:

            stream, server

Sets size of a per-connection receive buffer used to parse
incoming stream of synchronization messages.
The buffer size must be equal or greater than one of the
zone_sync_buffers.
By default, the buffer size is equal to
zone_sync_buffers size
multiplied by number.

            Syntax:

            zone_sync_server address [resolve];

            Default:

            —

            Context:

            server

Defines the address of a cluster node.
The address can be specified as a domain name or IP address
with a mandatory port, or as a UNIX-domain socket path
specified after the “unix:” prefix.
A domain name that resolves to several IP addresses defines
multiple nodes at once.

The resolve parameter instructs nginx to monitor
changes of the IP addresses that correspond to a domain name of the node
and automatically modify the configuration
without the need of restarting nginx.

Cluster nodes are specified either dynamically as a single
zone_sync_server directive with
the resolve parameter, or statically as a series of several
directives without the parameter.

Each cluster node should be specified only once.

All cluster nodes should use the same configuration.

In order for the resolve parameter to work,
the resolver directive
must be specified in the
stream block.
Example:

stream {
    resolver 10.0.0.1;

    server {
        zone_sync;
        zone_sync_server cluster.example.com:12345 resolve;
        ...
    }
}

            Syntax:

            zone_sync_ssl on | off;

            Default:

zone_sync_ssl off;

            Context:

            stream, server

Enables the SSL/TLS protocol for connections to another cluster server.

            Syntax:

            zone_sync_ssl_certificate file;

            Default:

            —

            Context:

            stream, server

Specifies a file with the certificate in the PEM format
used for authentication to another cluster server.

            Syntax:

            zone_sync_ssl_certificate_key file;

            Default:

            —

            Context:

            stream, server

Specifies a file with the secret key in the PEM format
used for authentication to another cluster server.

            Syntax:

            zone_sync_ssl_ciphers ciphers;

            Default:

zone_sync_ssl_ciphers DEFAULT;

            Context:

            stream, server

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

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

            Syntax:

            zone_sync_ssl_conf_command name value;

            Default:

            —

            Context:

            stream, server

This directive appeared in version 1.19.4.

Sets arbitrary OpenSSL configuration
commands
when establishing a connection with another cluster server.

The directive is supported when using OpenSSL 1.0.2 or higher.

Several zone_sync_ssl_conf_command directives
can be specified on the same level.
These directives are inherited from the previous configuration level
if and only if there are
no zone_sync_ssl_conf_command directives
defined on the current level.

Note that configuring OpenSSL directly
might result in unexpected behavior.

            Syntax:

            zone_sync_ssl_crl file;

            Default:

            —

            Context:

            stream, server

Specifies a file with revoked certificates (CRL)
in the PEM format used to verify
the certificate of another cluster server.
When using intermediate certificates, their CRLs should be
specified in the same file.

            Syntax:

            zone_sync_ssl_name name;

            Default:

zone_sync_ssl_name host from zone_sync_server;

            Context:

            stream, server

This directive appeared in version 1.15.7.

Allows overriding the server name used to
verify
the certificate of a cluster server and to be
passed through SNI
when establishing a connection with the cluster server.

By default, the host part of the zone_sync_server address is used,
or resolved IP address if the resolve parameter is specified.

            Syntax:

            zone_sync_ssl_password_file file;

            Default:

            —

            Context:

            stream, server

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

            Syntax:

            zone_sync_ssl_protocols
    [SSLv2]
    [SSLv3]
    [TLSv1]
    [TLSv1.1]
    [TLSv1.2]
    [TLSv1.3];

            Default:

zone_sync_ssl_protocols TLSv1.2 TLSv1.3;

            Context:

            stream, server

Enables the specified protocols for connections to another cluster server.

            Syntax:

            zone_sync_ssl_server_name on | off;

            Default:

zone_sync_ssl_server_name off;

            Context:

            stream, server

This directive appeared in version 1.15.7.

Enables or disables passing of the server name through
TLS
Server Name Indication extension (SNI, RFC 6066)
when establishing a connection with another cluster server.

            Syntax:

            zone_sync_ssl_trusted_certificate file;

            Default:

            —

            Context:

            stream, server

Specifies a file with trusted CA certificates in the PEM format
used to verify
the certificate of another cluster server.

            Syntax:

            zone_sync_ssl_verify on | off;

            Default:

zone_sync_ssl_verify off;

            Context:

            stream, server

Enables or disables verification of another cluster server certificate.

            Syntax:

            zone_sync_ssl_verify_depth number;

            Default:

zone_sync_ssl_verify_depth 1;

            Context:

            stream, server

Sets the verification depth in another cluster server certificates chain.

            Syntax:

            zone_sync_timeout timeout;

            Default:

zone_sync_timeout 5s;

            Context:

            stream, server

Sets the timeout between two successive
read or write operations on connection to another cluster node.
If no data is transmitted within this time, the connection is closed.

API endpoints

The synchronization status of a node is available via the
/stream/zone_sync/
endpoint of the API which returns the
following
metrics.

Starting, stopping, removing a cluster node

To start a new node, update a DNS record of a cluster hostname
with the IP address of the new node and start an instance.
The new node will discover other nodes from DNS or static configuration
and will start sending updates to them.
Other nodes will eventually discover the new node using DNS and
start pushing updates to it.
In case of static configuration,
other nodes need to be reloaded in order to send updates to the new node.

To stop a node, send the QUIT signal to the instance.
The node will finish zone synchronization
and gracefully close open connections.

To remove a node, update a DNS record of a cluster hostname
and remove the IP address of the node.
All other nodes will eventually discover that the node is removed,
close connections to the node, and will no longer try to connect to it.
After the node is removed, it can be stopped as described above.
In case of static configuration, other nodes need to be reloaded
in order to stop sending updates to the removed node.


<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>How nginx processes a TCP/UDP session</title><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="../../../css/style_en.css">

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

<input class="side-menu" type="checkbox" id="side-menu">

english

русский

news

about

download

security

documentation

faq

books

community

enterprise

community forum (new)

x.com

blog

njs

ingress controller

gateway fabric

How nginx processes a TCP/UDP session

A TCP/UDP session from a client is processed
in successive steps called phases:

Post-accept

The first phase after accepting a client connection.
The ngx_stream_realip_module
module is invoked at this phase.

Pre-access

Preliminary check for access.
The
ngx_stream_limit_conn_module
and
ngx_stream_set_module
modules are invoked at this phase.

Access

Client access limitation before actual data processing.
At this phase,
the ngx_stream_access_module
module is invoked,
for njs,
the js_access directive
is invoked.

SSL

TLS/SSL termination.
The ngx_stream_ssl_module
module is invoked at this phase.

Preread

Reading initial bytes of data into the
preread buffer
to allow modules such as
ngx_stream_ssl_preread_module
analyze the data before its processing.
For njs,
the js_preread directive
is invoked at this phase.

Content

Mandatory phase where data is actually processed, usually
proxied to
upstream servers,
or a specified value
is returned to a client.
For njs,
the js_filter directive
is invoked at this phase.

Log

The final phase
where the result of a client session processing is recorded.
The ngx_stream_log_module
module is invoked at this phase.