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

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

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 协议。

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

listen 指令可以具有一些特定于套接字相关系统调用的其他参数。这些参数可以在任何 listen 指令中指定，但对于给定的 地址:端口 对只能指定一次。

setfib=编号

此参数 (1.25.5) 设置关联的路由表，FIB (SO_SETFIB 选项) 用于侦听套接字。目前仅在 FreeBSD 上有效。

fastopen=编号

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

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

backlog=编号

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

rcvbuf=大小

设置侦听套接字的接收缓冲区大小 (SO_RCVBUF 选项) (1.11.13)。

sndbuf=大小

设置侦听套接字的发送缓冲区大小 (SO_SNDBUF 选项) (1.11.13)。

accept_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 指令侦听给定端口 (*:端口) 上的所有地址，则 nginx 将仅绑定到 *:端口。需要注意的是，在这种情况下将进行 getsockname() 系统调用以确定接受连接的地址。如果使用了 setfib、fastopen、backlog、rcvbuf、sndbuf、accept_filter、deferred、ipv6only、reuseport 或 so_keepalive 参数，则对于给定的 地址:端口 对，将始终进行单独的 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|[保持空闲]:[保持间隔]:[保持次数]

此参数配置侦听套接字的“TCP 保活”行为。如果省略此参数，则操作系统设置将对套接字生效。如果将其设置为“on”值，则为套接字打开 SO_KEEPALIVE 选项。如果将其设置为“off”值，则为套接字关闭 SO_KEEPALIVE 选项。一些操作系统支持使用 TCP_KEEPIDLE、TCP_KEEPINTVL 和 TCP_KEEPCNT 套接字选项在每个套接字的基础上设置 TCP 保活参数。在这些系统上 (目前，Linux 2.4+、NetBSD 5+ 和 FreeBSD 9.0-STABLE)，可以使用 保持空闲、保持间隔 和 保持次数 参数对其进行配置。可以省略一个或两个参数，在这种情况下，将对相应的套接字选项使用系统默认设置。例如，

so_keepalive=30m::10

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

在 1.25.5 版本之前，不同的服务器必须侦听不同的 地址:端口 对。

preread_buffer_size 16k;

指定 预读 缓冲区的 大小。

preread_timeout 30s;

指定 预读 阶段的 超时。

proxy_protocol_timeout 30s;

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

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

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) 启用在指定的 区域 中 收集 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。有关设置哈希表的详细信息，请参阅单独的文档。

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

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

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 证书的通用名称
• 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

通用日志格式的本地时间