Module ngx_stream_core_module

Example Configuration

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.

Example Configuration

worker_processes auto;

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

events {
    worker_connections  1024;

stream {
    upstream backend {
        hash $remote_addr consistent;

        server weight=5;
        server            max_fails=3 fail_timeout=30s;
        server unix:/tmp/backend3;

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

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


Syntax: listen address:port [ssl] [backlog=number] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
Context: 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 *: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;

The ssl parameter allows specifying that all connections accepted on this port should work in SSL mode.

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

sets the 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 Mac OS X, and to 511 on other platforms.
this parameter instructs to make a separate 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 ipv6only or so_keepalive parameters are used then for a given address:port pair a separate bind() call will always be made.
this parameter determines (via the 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.
this parameter (1.9.1) instructs to create an individual listening socket for each worker process (using the SO_REUSEPORT socket option), allowing a kernel to distribute incoming connections between worker processes. This currently works only on Linux 3.9+ and DragonFly BSD.
Inappropriate use of this option may have its security implications.
this parameter configures the “TCP keepalive” behavior for the listening socket. If this parameter is omitted then the operating system’s settings will be in effect for the socket. If it is set to the value “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 (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.

Different servers must listen on different address:port pairs.

Syntax: resolver address ... [valid=time] [ipv6=on|off];
Context: stream, server

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

resolver [::1]:5353;

An address can be specified as a domain name or IP address, and 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 IPv6 addresses is not desired, 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 [::1]:5353 valid=30s;

This directive is available as part of our commercial subscription.

Syntax: resolver_timeout time;
resolver_timeout 30s;
Context: stream, server

Sets a timeout for name resolution, for example:

resolver_timeout 5s;

This directive is available as part of our commercial subscription.

Syntax: server { ... }
Context: stream

Sets the configuration for a server.

Syntax: stream { ... }
Context: main

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

Syntax: tcp_nodelay on | off;
tcp_nodelay on;
Context: 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.