模块 ngx_stream_core_module

自版本1.9.0起提供ngx_stream_core_module模块。此模块不是默认构建的，应该使用--with-stream配置参数启用它。

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 127.0.0.1:12345;
listen *:12345;
listen 12345;     # same as *:12345
listen localhost:12345;

IPv6地址在方括号中指定：

listen [::1]:12345;
listen [::]:12345;

UNIX域套接字以“unix:”前缀指定：

listen unix:/var/run/nginx.sock;

端口范围（1.15.10）以破折号分隔的第一个和最后一个端口指定：

listen 127.0.0.1:12345-12399;
listen 12345-12399;

如果存在default_server参数，则使服务器成为指定地址:端口对的默认服务器（1.25.5）。如果没有指令具有default_server参数，则具有地址:端口对的第一个服务器将成为此对的默认服务器。

ssl参数允许指定在此端口上接受的所有连接都以SSL模式工作。

udp参数配置用于处理数据报（1.9.13）的监听套接字。为了处理来自相同地址和端口的数据报在同一会话中，还应该指定reuseport参数。

proxy_protocol参数（1.11.4）允许指定在此端口接受的所有连接都应使用PROXY协议。

PROXY协议版本2支持自1.13.11版本以来。

listen指令可以具有几个特定于套接字相关的系统调用的附加参数。这些参数可以在任何listen指令中指定，但对于给定的address：port对只能指定一次。

setfib=number

此参数（1.25.5）设置了关联的路由表，FIB（SO_SETFIB选项）用于监听套接字。目前此功能仅在FreeBSD上有效。

fastopen=number

启用“TCP快速打开”用于监听套接字（1.21.0），并限制了尚未完成三次握手的连接队列的最大长度。

除非服务器能够处理接收带有数据的相同SYN数据包，否则不要启用此功能。

backlog=number

设置了listen()调用中的backlog参数，该参数限制了挂起连接队列的最大长度（1.9.2）。默认情况下，在FreeBSD、DragonFly BSD和macOS上，backlog设置为-1，在其他平台上设置为511。

rcvbuf=size

设置了接收缓冲区大小（SO_RCVBUF选项）用于监听套接字（1.11.13）。

sndbuf=size

设置了发送缓冲区大小（SO_SNDBUF选项）用于监听套接字（1.11.13）。

accept_filter=filter

设置了接受过滤器的名称（SO_ACCEPTFILTER选项）用于监听套接字，在将连接传递给accept()之前过滤传入的连接（1.25.5）。此功能仅在FreeBSD和NetBSD 5.0+上有效。可能的值为dataready和httpready。

deferred

在Linux上（1.25.5），指示使用延迟的accept()（TCP_DEFER_ACCEPT套接字选项）。

bind

此参数指示对给定的地址：端口对进行单独的bind()调用。事实上，如果有几个具有相同端口但不同地址的listen指令，并且其中一个listen指令监听了给定端口的所有地址（*:port），nginx将只绑定到*:port。值得注意的是，在这种情况下，将进行getsockname()系统调用以确定接受连接的地址。如果使用了setfib、fastopen、backlog、rcvbuf、sndbuf、accept_filter、deferred、ipv6only、reuseport或so_keepalive参数，那么对于给定的address:port对，将始终进行单独的bind()调用。

ipv6only=on|off

此参数通过IPV6_V6ONLY套接字选项确定了IPv6套接字在通配地址[::]上是否仅接受IPv6连接还是同时接受IPv6和IPv4连接。此参数默认为打开状态。它只能在启动时设置一次。

reuseport

这个参数（1.9.1）指示为每个工作进程创建一个独立的监听套接字（在 Linux 3.9+ 和 DragonFly BSD 上使用 `SO_REUSEPORT` 套接字选项，或者在 FreeBSD 12+ 上使用 `SO_REUSEPORT_LB`），允许内核在工作进程之间分发传入连接。当前仅在 Linux 3.9+、DragonFly BSD 和 FreeBSD 12+ 上有效（1.15.1）。

不当使用此选项可能具有其安全 [implications](http://man7.org/linux/man-pages/man7/socket.7.html)。

so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]

此参数配置了监听套接字的“TCP keepalive”行为。如果省略此参数，则套接字将使用操作系统的设置。如果设置为值“on”，则为套接字打开 SO_KEEPALIVE 选项。如果设置为值“off”，则为套接字关闭 SO_KEEPALIVE 选项。一些操作系统支持使用 TCP_KEEPIDLE、TCP_KEEPINTVL 和 TCP_KEEPCNT 套接字选项在每个套接字上设置 TCP keepalive 参数。在这些系统上（当前，Linux 2.4+、NetBSD 5+ 和 FreeBSD 9.0-STABLE），可以使用 keepidle、keepintvl 和 keepcnt 参数进行配置。可以省略一个或两个参数，此时将使用相应套接字选项的系统默认设置。例如，

so_keepalive=30m::10

将会将空闲超时（TCP_KEEPIDLE）设置为 30 分钟，保持探测间隔（TCP_KEEPINTVL）保持为其系统默认值，并将探测计数（TCP_KEEPCNT）设置为 10 次探测。

在1.25.5版本之前，不同的服务器必须侦听不同的address：port对。

preread_buffer_size 16k;

指定preread缓冲区的size。

preread_timeout 30s;

指定preread阶段的timeout。

proxy_protocol_timeout 30s;

指定读取PROXY协议头的timeout。如果在此时间内未传输整个头，则关闭连接。

配置用于将上游服务器的名称解析为地址的名称服务器，例如：

resolver 127.0.0.1 [::1]:5353;

地址可以指定为域名或IP地址，可选端口。如果未指定端口，则使用端口53。名称服务器以轮询方式进行查询。

默认情况下，nginx在解析时会查找IPv4和IPv6地址。如果不希望查找IPv4或IPv6地址，则可以指定ipv4=off（1.23.1）或ipv6=off参数。

默认情况下，nginx使用响应的TTL值缓存答案。可选的valid参数允许覆盖它：

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

为了防止DNS欺骗，建议在安全受信任的本地网络中配置DNS服务器。

可选的status_zone参数（1.17.1）启用在指定的zone中收集DNS服务器请求和响应的统计信息。该参数作为我们的商业订阅的一部分提供。

在版本1.11.3之前，此指令作为我们的商业订阅的一部分提供。

resolver_timeout 30s;

设置名称解析的超时时间，例如：

resolver_timeout 5s;

在版本1.11.3之前，此指令作为我们的商业订阅的一部分提供。

设置虚拟服务器的配置。基于IP地址（根据IP地址）和基于名称（根据TLS服务器名称指示扩展（SNI，RFC 6066））（1.25.5）虚拟服务器之间没有明确的分隔。相反，listen指令描述了应接受服务器连接的所有地址和端口，server_name指令列出了所有服务器名称。

server_name "";

设置虚拟服务器的名称，例如：

server {
    server_name example.com www.example.com;
}

第一个名称成为主服务器名称。

服务器名称可以包括用星号（“*”）替换名称的第一个或最后一个部分：

server {
    server_name example.com *.example.com www.example.*;
}

此类名称称为通配符名称。

上述提到的前两个名称可以合并为一个：

server {
    server_name .example.com;
}

还可以在服务器名称中使用正则表达式，在名称前加上波浪号（“~”）：

server {
    server_name www.example.com ~^www\d+\.example\.com$;
}

正则表达式可以包含捕获，稍后可以在其他指令中使用：

server {
    server_name ~^(www\.)?(.+)$;

    proxy_pass www.$2:12345;
}

在正则表达式中命名的捕获创建变量，稍后可以在其他指令中使用：

server {
    server_name ~^(www\.)?(?<domain>.+)$;

    proxy_pass www.$domain:12345;
}

如果指令的参数设置为“$hostname”，则插入计算机的主机名。

在按名称搜索虚拟服务器时，如果名称与指定的多个变体匹配（例如，通配符名称和正则表达式都匹配），将选择第一个匹配的变体，优先顺序如下：

1. 完全匹配的名称
2. 以星号开头的最长通配符名称，例如“*.example.com”
3. 以星号结尾的最长通配符名称，例如“mail.*”
4. 第一个匹配的正则表达式（按配置文件中的出现顺序）

server_names_hash_bucket_size 32|64|128;

设置服务器名称哈希表的桶大小。默认值取决于处理器缓存线的大小。设置哈希表的详细信息在单独的文档中提供。

server_names_hash_max_size 512;

设置服务器名称哈希表的最大size。设置哈希表的详细信息在单独的文档中提供。

提供了指定stream服务器指令的配置文件上下文。

tcp_nodelay on;

启用或禁用TCP_NODELAY选项的使用。该选项对客户端和代理服务器连接都启用。

variables_hash_bucket_size 64;

设置变量哈希表的桶大小。设置哈希表的详细信息在单独的文档中提供。

variables_hash_max_size 1024;

设置变量哈希表的最大 大小。设置哈希表的详细信息在单独的文档中提供。

ngx_stream_core_module 模块支持变量自 1.11.2 起。

$binary_remote_addr

客户端地址以二进制形式表示，对于 IPv4 地址，值的长度始终为 4 个字节，对于 IPv6 地址，值的长度始终为 16 个字节

$bytes_received

从客户端接收的字节数（1.11.4）

$bytes_sent

发送到客户端的字节数

$connection

连接的序列号

$hostname

主机名

$msec

当前时间（秒），带毫秒分辨率

$nginx_version

nginx 版本

$pid

工作进程的 PID

$protocol

与客户端通信所使用的协议：TCP 或 UDP（1.11.4）

$proxy_protocol_addr

来自 PROXY 协议头的客户端地址（1.11.4）

必须先通过在 listen 指令中设置 proxy_protocol 参数来启用 PROXY 协议。

$proxy_protocol_port

来自 PROXY 协议头的客户端端口（1.11.4）

必须先通过在 listen 指令中设置 proxy_protocol 参数来启用 PROXY 协议。

$proxy_protocol_server_addr

来自 PROXY 协议头的服务器地址（1.17.6）

必须先通过在 listen 指令中设置 proxy_protocol 参数来启用 PROXY 协议。

$proxy_protocol_server_port

来自 PROXY 协议头的服务器端口（1.17.6）

必须先通过在 listen 指令中设置 proxy_protocol 参数来启用 PROXY 协议。

$proxy_protocol_tlv_name

来自代理协议头的 TLV（1.23.2）。name 可以是 TLV 类型名称或其数值。在后一种情况下，值是十六进制的，应以 0x 为前缀：

$proxy_protocol_tlv_alpn
$proxy_protocol_tlv_0x01

SSL TLV 也可以通过 TLV 类型名称或其数值访问，都以 ssl_ 为前缀：

$proxy_protocol_tlv_ssl_version
$proxy_protocol_tlv_ssl_0x21

支持以下 TLV 类型名称：

• alpn（0x01） - 连接中使用的上层协议
• authority（0x02） - 客户端传递的主机名值
• unique_id（0x05） - 唯一连接标识符
• netns（0x30） - 命名空间的名称
• ssl（0x20） - 二进制 SSL TLV 结构

支持以下 SSL TLV 类型名称：

• ssl_version（0x21） - 客户端连接中使用的 SSL 版本
• ssl_cn（0x22） - SSL 证书公用名称
• ssl_cipher（0x23） - 使用的密码名称
• ssl_sig_alg（0x24） - 用于签署证书的算法
• ssl_key_alg（0x25） - 公钥算法

还支持以下特殊 SSL TLV 类型名称：

• ssl_verify - 客户端 SSL 证书验证结果，如果客户端提供了证书并且成功验证，则为零，否则为非零

必须先通过在 listen 指令中设置 proxy_protocol 参数来启用 PROXY 协议。

$remote_addr

客户端地址

$remote_port

客户端端口

$server_addr

接受连接的服务器的地址

通常计算此变量的值需要一个系统调用。为避免系统调用，listen 指令必须指定地址并使用 bind 参数。

$server_port

接受连接的服务器的端口

$session_time

会话持续时间，以秒为单位，毫秒分辨率（1.11.4）;

$status

会话状态（1.11.4），可以是以下之一：

200

会话成功完成

400

无法解析客户端数据，例如，PROXY 协议 头

403

访问被拒绝，例如，当访问被限制为某些客户端地址

500

内部服务器错误

502

错误网关，例如，如果无法选择或到达上游服务器。

503

服务不可用，例如，当访问受到连接数限制

$time_iso8601

ISO 8601 标准格式的本地时间

$time_local

通用日志格式中的本地时间