body { background: white; color: black; font-family: sans-serif; line-height: 1.4em; text-align: center; margin: 0; padding: 0; } #banner { background: black; color: #F2F2F2; line-height: 1.2em; padding: .3em 0; box-shadow: 0 5px 10px black; } #banner a { color: #00B140; } #main { text-align: left; margin: 0 auto; min-width: 32em; max-width: 64em; } #menu { float: right; width: 11em; padding: 0 .5em 1em .5em; border-left: 2px solid #DDD; } #content { margin-right: 13.5em; padding: 0 .2em 0 1.5em; } h1 { display: block; font-size: 3em; text-align: left; height: .7em; margin: 0; margin-bottom: .5em; } h1 img { width: 100%; } h2 { text-align: center; } p { text-align: justify; } table.news p { margin-top: 0; } table.news td { vertical-align: baseline; } table.news .date { text-align: right; padding-right: 0.5em; white-space: nowrap; } table.donors td { vertical-align: baseline; } table.donors li { text-align: left; } div.directive { background: #F2F2F2; line-height: 1em; margin: 1em 0 1em -1em; padding: .7em .7em .7em 1em; border-top: 2px solid #DDD; } div.directive th { padding-left: 0; padding-right: .5em; vertical-align: baseline; text-align: left; font-weight: normal; } div.directive td { vertical-align: baseline; } div.directive pre { padding: 0; margin: 0; } div.directive p { margin: .5em 0 0 .1em; font-size: .8em; } a.notrans { color: gray; text-decoration:none; } span.initial { font-size: 200%; float: left; padding-right: 10pt;} ul, ol { margin: .5em 0 1em 1em; padding: 0 .5em; } ol { list-style-position: inside; } li { text-align: justify; padding: .5em 0 0 1px; } .compact li { padding-top: 0; } dl { margin: .5em 0 1em 0; } dt { margin: .5em 0; } .compact dt { margin-bottom: .2em; } dd { margin-left: 1.5em; padding-left: 1px; text-align: justify; } td.list { background: #F2F2F2; } blockquote { margin: 1em 0 1em 1em; padding: .5em; } li blockquote, dd blockquote { margin: .7em 0; } blockquote.note { border: 1px dotted #999; line-height: 1.2em; text-align: justify; } blockquote.example { line-height: 1em; border-left: 1px solid #BBB; } blockquote.example pre { padding: 0; margin: 0; } sup { font-size: 50%; } .video { position: relative; padding-bottom: 56.25%; overflow: hidden; } .video iframe, .video object, .video embed { position: absolute; top:0; left:0; width:100%; height:100%; }
The ngx_stream_core_module
module
is available since version 1.9.0.
This module is not built by default, it should be enabled with the
--with-stream
configuration parameter.
worker_processes auto; error_log /var/log/nginx/error.log info; events { worker_connections 1024; } stream { upstream backend { hash $remote_addr consistent; server backend1.example.com:12345 weight=5; server 127.0.0.1:12345 max_fails=3 fail_timeout=30s; server unix:/tmp/backend3; } upstream dns { server 192.168.0.1:53535; server dns.example.com:53; } server { listen 12345; proxy_connect_timeout 1s; proxy_timeout 3s; proxy_pass backend; } server { listen 127.0.0.1:53 udp reuseport; proxy_timeout 20s; proxy_pass dns; } server { listen [::1]:12345; proxy_pass unix:/tmp/stream.socket; } }
listen
address
:port
[default_server
]
[ssl
]
[udp
]
[proxy_protocol
]
[setfib
=number
]
[fastopen
=number
]
[backlog
=number
]
[rcvbuf
=size
]
[sndbuf
=size
]
[accept_filter
=filter
]
[deferred
]
[bind
]
[ipv6only
=on
|off
]
[reuseport
]
[so_keepalive
=on
|off
|[keepidle
]:[keepintvl
]:[keepcnt
]];
server
Sets the address
and port
for the socket
on which the server will accept connections.
It is possible to specify just the port.
The address can also be a hostname, for example:
listen 127.0.0.1:12345; listen *:12345; listen 12345; # same as *:12345 listen localhost:12345;
IPv6 addresses are specified in square brackets:
listen [::1]:12345; listen [::]:12345;
UNIX-domain sockets are specified with the “unix:
”
prefix:
listen unix:/var/run/nginx.sock;
Port ranges (1.15.10) are specified with the first and last port separated by a hyphen:
listen 127.0.0.1:12345-12399; listen 12345-12399;
The default_server
parameter, if present,
will cause the server to become the default server for the specified
address
:port
pair (1.25.5).
If none of the directives have the default_server
parameter then the first server with the
address
:port
pair will be
the default server for this pair.
The ssl
parameter allows specifying that all
connections accepted on this port should work in SSL mode.
The udp
parameter configures a listening socket
for working with datagrams (1.9.13).
In order to handle packets from the same address and port in the same session,
the reuseport
parameter
should also be specified.
The proxy_protocol
parameter (1.11.4)
allows specifying that all connections accepted on this port should use the
PROXY
protocol.
The PROXY protocol version 2 is supported since version 1.13.11.
The listen
directive
can have several additional parameters specific to socket-related system calls.
These parameters can be specified in any
listen
directive, but only once for a given
address
:port
pair.
setfib
=number
SO_SETFIB
option) for the listening socket.
This currently works only on FreeBSD.
fastopen
=number
Do not enable this feature unless the server can handle receiving the same SYN packet with data more than once.
backlog
=number
backlog
parameter in the
listen()
call that limits
the maximum length for the queue of pending connections (1.9.2).
By default,
backlog
is set to -1 on FreeBSD, DragonFly BSD, and macOS,
and to 511 on other platforms.
rcvbuf
=size
SO_RCVBUF
option) for the listening socket (1.11.13).
sndbuf
=size
SO_SNDBUF
option) for the listening socket (1.11.13).
accept_filter
=filter
SO_ACCEPTFILTER
option) for the listening socket
that filters incoming connections before passing them to
accept()
(1.25.5).
This works only on FreeBSD and NetBSD 5.0+.
Possible values are
dataready
and
httpready.
deferred
accept()
(the TCP_DEFER_ACCEPT
socket option) on Linux (1.25.5).
bind
bind()
call for a given address:port pair.
The fact is that if there are several listen
directives with
the same port but different addresses, and one of the
listen
directives listens on all addresses
for the given port (*:
port
), nginx will
bind()
only to *:
port
.
It should be noted that the getsockname()
system call will be
made in this case to determine the address that accepted the connection.
If the setfib
,
fastopen
,
backlog
, rcvbuf
,
sndbuf
, accept_filter
,
deferred
, ipv6only
,
reuseport
,
or so_keepalive
parameters
are used then for a given
address
:port
pair
a separate bind()
call will always be made.
ipv6only
=on
|off
IPV6_V6ONLY
socket option)
whether an IPv6 socket listening on a wildcard address [::]
will accept only IPv6 connections or both IPv6 and IPv4 connections.
This parameter is turned on by default.
It can only be set once on start.
reuseport
SO_REUSEPORT
socket option on Linux 3.9+ and DragonFly BSD,
or SO_REUSEPORT_LB
on FreeBSD 12+), allowing a kernel
to distribute incoming connections between worker processes.
This currently works only on Linux 3.9+, DragonFly BSD,
and FreeBSD 12+ (1.15.1).
Inappropriate use of this option may have its security implications.
so_keepalive
=on
|off
|[keepidle
]:[keepintvl
]:[keepcnt
]
on
”, the
SO_KEEPALIVE
option is turned on for the socket.
If it is set to the value “off
”, the
SO_KEEPALIVE
option is turned off for the socket.
Some operating systems support setting of TCP keepalive parameters on
a per-socket basis using the TCP_KEEPIDLE
,
TCP_KEEPINTVL
, and TCP_KEEPCNT
socket options.
On such systems (currently, Linux 2.4+, NetBSD 5+, and
FreeBSD 9.0-STABLE), they can be configured
using the keepidle
, keepintvl
, and
keepcnt
parameters.
One or two parameters may be omitted, in which case the system default setting
for the corresponding socket option will be in effect.
For example,
will set the idle timeout (so_keepalive=30m::10
TCP_KEEPIDLE
) to 30 minutes,
leave the probe interval (TCP_KEEPINTVL
) at its system default,
and set the probes count (TCP_KEEPCNT
) to 10 probes.
Before version 1.25.5, different servers must listen on differentaddress
:port
pairs.
preread_buffer_size size
;
preread_buffer_size 16k;
stream
, server
This directive appeared in version 1.11.5.
Specifies a size
of the
preread buffer.
preread_timeout timeout
;
preread_timeout 30s;
stream
, server
This directive appeared in version 1.11.5.
Specifies a timeout
of the
preread phase.
proxy_protocol_timeout timeout
;
proxy_protocol_timeout 30s;
stream
, server
This directive appeared in version 1.11.4.
Specifies a timeout
for
reading the PROXY protocol header to complete.
If no entire header is transmitted within this time,
the connection is closed.
resolver
address
...
[valid
=time
]
[ipv4
=on
|off
]
[ipv6
=on
|off
]
[status_zone
=zone
];
stream
, server
This directive appeared in version 1.11.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.1)
enables
collection
of DNS server statistics of requests and responses
in the specified zone
.
The parameter is available as part of our
commercial subscription.
Before version 1.11.3, this directive was available as part of our commercial subscription.
resolver_timeout time
;
resolver_timeout 30s;
stream
, server
This directive appeared in version 1.11.3.
Sets a timeout for name resolution, for example:
resolver_timeout 5s;
Before version 1.11.3, this directive was available as part of our commercial subscription.
server { ... }
stream
Sets the configuration for a virtual server. There is no clear separation between IP-based (based on the IP address) and name-based (based on the TLS Server Name Indication extension (SNI, RFC 6066)) (1.25.5) virtual servers. Instead, the listen directives describe all addresses and ports that should accept connections for the server, and the server_name directive lists all server names.
server_name name
...;
server_name "";
server
This directive appeared in version 1.25.5.
Sets names of a virtual server, for example:
server { server_name example.com www.example.com; }
The first name becomes the primary server name.
Server names can include an asterisk (“*
”)
replacing the first or last part of a name:
server { server_name example.com *.example.com www.example.*; }
Such names are called wildcard names.
The first two of the names mentioned above can be combined in one:
server { server_name .example.com; }
It is also possible to use regular expressions in server names,
preceding the name with a tilde (“~
”):
server { server_name www.example.com ~^www\d+\.example\.com$; }
Regular expressions can contain captures that can later be used in other directives:
server { server_name ~^(www\.)?(.+)$; proxy_pass www.$2:12345; }
Named captures in regular expressions create variables that can later be used in other directives:
server { server_name ~^(www\.)?(?<domain>.+)$; proxy_pass www.$domain:12345; }
If the directive’s parameter is set to “$hostname
”, the
machine’s hostname is inserted.
During searching for a virtual server by name, if the name matches more than one of the specified variants, (e.g. both a wildcard name and regular expression match), the first matching variant will be chosen, in the following order of priority:
*.example.com
”
mail.*
”
server_names_hash_bucket_size size
;
server_names_hash_bucket_size 32|64|128;
stream
This directive appeared in version 1.25.5.
Sets the bucket size for the server names hash tables. The default value depends on the size of the processor’s cache line. The details of setting up hash tables are provided in a separate document.
server_names_hash_max_size size
;
server_names_hash_max_size 512;
stream
This directive appeared in version 1.25.5.
Sets the maximum size
of the server names hash tables.
The details of setting up hash tables are provided in a separate
document.
stream { ... }
main
Provides the configuration file context in which the stream server directives are specified.
tcp_nodelay on
| off
;
tcp_nodelay on;
stream
, server
This directive appeared in version 1.9.4.
Enables or disables the use of the TCP_NODELAY
option.
The option is enabled for both client and proxied server connections.
variables_hash_bucket_size size
;
variables_hash_bucket_size 64;
stream
This directive appeared in version 1.11.2.
Sets the bucket size for the variables hash table. The details of setting up hash tables are provided in a separate document.
variables_hash_max_size size
;
variables_hash_max_size 1024;
stream
This directive appeared in version 1.11.2.
Sets the maximum size
of the variables hash table.
The details of setting up hash tables are provided in a separate
document.
The ngx_stream_core_module
module supports variables
since 1.11.2.
$binary_remote_addr
$bytes_received
$bytes_sent
$connection
$hostname
$msec
$nginx_version
$pid
$protocol
TCP
or UDP
(1.11.4)
$proxy_protocol_addr
The PROXY protocol must be previously enabled by setting the
proxy_protocol
parameter
in the listen directive.
$proxy_protocol_port
The PROXY protocol must be previously enabled by setting the
proxy_protocol
parameter
in the listen directive.
$proxy_protocol_server_addr
The PROXY protocol must be previously enabled by setting the
proxy_protocol
parameter
in the listen directive.
$proxy_protocol_server_port
The PROXY protocol must be previously enabled by setting the
proxy_protocol
parameter
in the listen directive.
$proxy_protocol_tlv_
name
name
can be a TLV type name or its numeric value.
In the latter case, the value is hexadecimal
and should be prefixed with 0x
:
SSL TLVs can also be accessed by TLV type name or its numeric value, both prefixed by$proxy_protocol_tlv_alpn $proxy_protocol_tlv_0x01
ssl_
:
$proxy_protocol_tlv_ssl_version $proxy_protocol_tlv_ssl_0x21
The following TLV type names are supported:
alpn
(0x01
) -
upper layer protocol used over the connection
authority
(0x02
) -
host name value passed by the client
unique_id
(0x05
) -
unique connection id
netns
(0x30
) -
name of the namespace
ssl
(0x20
) -
binary SSL TLV structure
The following SSL TLV type names are supported:
ssl_version
(0x21
) -
SSL version used in client connection
ssl_cn
(0x22
) -
SSL certificate Common Name
ssl_cipher
(0x23
) -
name of the used cipher
ssl_sig_alg
(0x24
) -
algorithm used to sign the certificate
ssl_key_alg
(0x25
) -
public-key algorithm
Also, the following special SSL TLV type name is supported:
ssl_verify
-
client SSL certificate verification result,
zero if the client presented a certificate
and it was successfully verified, and non-zero otherwise
The PROXY protocol must be previously enabled by setting the
proxy_protocol
parameter
in the listen directive.
$remote_addr
$remote_port
$server_addr
Computing a value of this variable usually requires one system call.
To avoid a system call, the listen directives
must specify addresses and use the bind
parameter.
$server_port
$session_time
$status
200
400
403
500
502
503
$time_iso8601
$time_local