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;

如果存在 default_server 参数，该服务器将成为指定 address:port 对的默认服务器 (1.25.5)。如果所有指令都没有 default_server 参数，则具有该 address:port 对的第一个服务器将成为此对的默认服务器。

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

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

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

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

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

setfib=number

此参数 (1.25.5) 为监听套接字设置相关的路由表 FIB (SO_SETFIB 选项)。目前仅在 FreeBSD 上有效。

fastopen=number

为监听套接字启用“TCP Fast Open” (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)。

accept_filter=filter

为监听套接字设置接受过滤器名称 (SO_ACCEPTFILTER 选项)，该过滤器在将传入连接传递给 accept() 之前对其进行过滤 (1.25.5)。这仅在 FreeBSD 和 NetBSD 5.0+ 上有效。可能的值有 dataready 和 httpready。

deferred

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

bind

此参数指示对给定的 address:port 对进行单独的 bind() 调用。事实是，如果存在多个具有相同端口但不同地址的 listen 指令，并且其中一个 listen 指令监听给定端口的所有地址 (*:port)，则 nginx 将仅 bind() 到 *: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) 指示为每个 worker 进程创建一个独立的监听套接字（在 Linux 3.9+ 和 DragonFly BSD 上使用 SO_REUSEPORT 套接字选项，或在 FreeBSD 12+ 上使用 SO_REUSEPORT_LB），允许内核在 worker 进程之间分发传入连接。目前仅在 Linux 3.9+、DragonFly BSD 和 FreeBSD 12+ (1.15.1) 上有效。

不恰当使用此选项可能会带来安全隐患。

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;

指定 预读 缓冲区的大小 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 之前，此指令作为我们的商业订阅的一部分提供。

设置虚拟服务器的配置。基于 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;

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

server_names_hash_max_size 512;

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

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

tcp_nodelay on;

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

variables_hash_bucket_size 64;

设置变量哈希表的 bucket 大小。哈希表的设置详情在单独的文档中提供。

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

worker 进程的 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

SSL TLV 也可以通过 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 证书通用名 (Common Name)
• 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

Common Log Format 格式的本地时间