<?xml version="1.0"?>

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

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

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

<section id="summary">

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

</section>


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

<para>
<example>
worker_processes auto;

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

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;
    }

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

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

</section>


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

<directive name="listen">
<syntax>
    <value>address</value>:<value>port</value>
    [<literal>bind</literal>]
    [<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>]
    [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax>
<default/>
<context>server</context>

<para>
Sets the <value>address</value> and <value>port</value> 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:
<example>
listen 127.0.0.1:12345;
listen *:12345;
listen 12345;     # same as *:12345
listen localhost:12345;
</example>
IPv6 addresses are specified in square brackets:
<example>
listen [::1]:12345;
listen [::]:12345;
</example>
UNIX-domain sockets are specified with the “<literal>unix:</literal>”
prefix:
<example>
listen unix:/var/run/nginx.sock;
</example>

</para>

<para>
The directive supports the following parameters:

<list type="tag">

<tag-name id="bind">
<literal>bind</literal>
</tag-name>
<tag-desc>
this parameter instructs to make a separate <c-func>bind</c-func>
call for a given address:port pair.
The fact is that if there are several <literal>listen</literal> directives with
the same port but different addresses, and one of the
<literal>listen</literal> directives listens on all addresses
for the given port (<literal>*:</literal><value>port</value>), nginx will
<c-func>bind</c-func> only to <literal>*:</literal><value>port</value>.
It should be noted that the <c-func>getsockname</c-func> system call will be
made in this case to determine the address that accepted the connection.
If the <literal>ipv6only</literal>
or <literal>so_keepalive</literal> parameters
are used then for a given
<value>address</value>:<value>port</value> pair
a separate <c-func>bind</c-func> call will always be made.
</tag-desc>

<tag-name id="ipv6only">
<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>
</tag-name>
<tag-desc>
this parameter determines
(via the <c-def>IPV6_V6ONLY</c-def> socket option)
whether an IPv6 socket listening on a wildcard address <literal>[::]</literal>
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.
</tag-desc>

<tag-name id="so_keepalive">
<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]
</tag-name>
<tag-desc>
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 “<literal>on</literal>”, the
<c-def>SO_KEEPALIVE</c-def> option is turned on for the socket.
If it is set to the value “<literal>off</literal>”, the
<c-def>SO_KEEPALIVE</c-def> option is turned off for the socket.
Some operating systems support setting of TCP keepalive parameters on
a per-socket basis using the <c-def>TCP_KEEPIDLE</c-def>,
<c-def>TCP_KEEPINTVL</c-def>, and <c-def>TCP_KEEPCNT</c-def> socket options.
On such systems (currently, Linux 2.4+, NetBSD 5+, and
FreeBSD 9.0-STABLE), they can be configured
using the <value>keepidle</value>, <value>keepintvl</value>, and
<value>keepcnt</value> 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,
<example>so_keepalive=30m::10</example>
will set the idle timeout (<c-def>TCP_KEEPIDLE</c-def>) to 30 minutes,
leave the probe interval (<c-def>TCP_KEEPINTVL</c-def>) at its system default,
and set the probes count (<c-def>TCP_KEEPCNT</c-def>) to 10 probes.
</tag-desc>
</list>
</para>

<para>
Different servers must listen on different
<value>address</value>:<value>port</value> pairs.
</para>

</directive>


<directive name="server">
<syntax block="yes"/>
<default/>
<context>stream</context>

<para>
Sets the configuration for a server.
</para>

</directive>


<directive name="stream">
<syntax block="yes"/>
<default/>
<context>main</context>

<para>
Provides the configuration file context in which the stream server directives
are specified.
</para>

</directive>

</section>

</module>