模块 ngx_stream_core_module

ngx_stream_core_module 模块自 1.9.0 版本起可用。此模块默认不构建，应使用 --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;
    }
}

为服务器将接受连接的套接字设置 address 和 port。可以只指定端口。地址也可以是主机名，例如

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;

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

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

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

自 1.13.11 版本起支持 PROXY 协议版本 2。

listen 指令可以具有几个特定于套接字相关系统调用的附加参数。

fastopen=number

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

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

backlog=number

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

rcvbuf=size

为侦听套接字设置接收缓冲区大小（SO_RCVBUF 选项）（1.11.13）。

sndbuf=size

为侦听套接字设置发送缓冲区大小（SO_SNDBUF 选项）（1.11.13）。

bind

此参数指示为给定的地址:端口对执行单独的 bind() 调用。事实上，如果有多个 listen 指令具有相同的端口但不同的地址，并且其中一个 listen 指令侦听给定端口的所有地址（*:port），nginx 将只 bind() 到 *:port。应当注意，在这种情况下将执行 getsockname() 系统调用以确定接受连接的地址。如果使用 backlog、rcvbuf、sndbuf、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）。

不当使用此选项可能会产生其安全影响。

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

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

so_keepalive=30m::10

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

不同的服务器必须监听不同的 address:port 对。

preread_buffer_size 16k;

指定 预读 缓冲区的 size。

preread_timeout 30s;

指定 预读 阶段的 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 版本之前，此指令作为我们商业订阅的一部分提供。

设置服务器的配置。

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

tcp_nodelay on;

启用或禁用 TCP_NODELAY 选项。此选项对客户端和代理服务器连接均启用。

variables_hash_bucket_size 64;

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

variables_hash_max_size 1024;

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

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

PROXY 协议头中的 TLV (1.23.2)。name 可以是 TLV 类型名称或其数字值。在后一种情况下，该值是十六进制的，应以 0x 为前缀

$proxy_protocol_tlv_alpn
$proxy_protocol_tlv_0x01

还可以通过 TLV 类型名称或其数字值来访问 SSL TLV，两者都以 ssl_ 为前缀

$proxy_protocol_tlv_ssl_version
$proxy_protocol_tlv_ssl_0x21

支持以下 TLV 类型名称

• alpn (0x01) - 通过连接使用的上层协议
• authority (0x02) - 客户端传递的主机名值
• unique_id (0x05) - 唯一的连接 ID
• 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

通用日志格式的本地时间