Module ngx_stream_core_module

• Example Configuration
• Directives
  • listen
  • preread_buffer_size
  • preread_timeout
  • proxy_protocol_timeout
  • resolver
  • resolver_timeout
  • server
  • stream
  • tcp_nodelay
  • variables_hash_bucket_size
  • variables_hash_max_size
• Embedded Variables
  

ngx_stream_core_module模块从 1.9.0 版开始可用。默认情况下未构建此模块，应使用--with-stream配置参数启用它。

Example Configuration

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

Directives

为服务器将在其上接受连接的套接字设置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 protocol。

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

• backlog = number

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

• rcvbuf = size

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

• sndbuf = size

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

• bind

  • 此参数指示对给定的 address：port 对单独进行bind()调用。事实是，如果有多个listen伪指令具有相同的端口但地址不同，并且listen伪指令之一在给定端口(*: port)的所有地址上侦听，则 nginx 只会bind()到*: port。应当注意，在这种情况下将进行getsockname()系统调用，以确定接受连接的地址。如果使用ipv6only或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 socket 选项，在 FreeBSD 12 上使用SO_REUSEPORT_LB)，从而允许内核在工作进程之间分配传入的连接。当前仅在 Linux 3.9，DragonFly BSD 和 FreeBSD 12(1.15.1)上有效。

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

  • 此参数为侦听套接字配置“ TCP keepalive”行为。如果省略此参数，则 os 的设置对套接字有效。如果将其设置为值“ on”，则将为套接字打开SO_KEEPALIVE选项。如果将其设置为值“ off”，则套接字的SO_KEEPALIVE选项将关闭。某些 os 使用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 个探测。

不同的服务器必须侦听不同的address：port对。

该指令出现在 1.11.5 版中。

指定preread缓冲区中的size。

该指令出现在 1.11.5 版中。

指定preread阶段的timeout。

该指令出现在版本 1.11.4 中。

指定一个timeout以读取 PROXY 协议 Headers 以完成。如果在此时间内未传输整个 Headers，则连接将关闭。

该指令出现在 1.11.3 版中。

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

resolver 127.0.0.1 [::1]:5353;

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

默认情况下，nginx 在解析时将同时查找 IPv4 和 IPv6 地址。如果不需要查找 IPv6 地址，则可以指定ipv6=off参数。

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

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

可选的status_zone参数(1.17.1)启用collection的 DNS 服务器统计信息，用于指定zone中的请求和响应。该参数可作为commercial subscription的一部分使用。

该指令出现在 1.11.3 版中。

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

resolver_timeout 5s;

设置服务器的配置。

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

该指令出现在版本 1.9.4 中。

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

该指令出现在 1.11.2 版中。

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

该指令出现在 1.11.2 版中。

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

Embedded Variables

ngx_stream_core_module模块从 1.11.2 开始支持变量。

$binary_remote_addr

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

$bytes_received

• 从客户端收到的字节数(1.11.4)

$bytes_sent

• 发送给客户端的字节数

$connection

• 连接序列号

$hostname

• host name

$msec

• 以秒为单位的当前时间(以毫秒为单位)

$nginx_version

• nginx version

$pid

• 工作进程的 PID

$protocol

• 与客户端通信的协议：TCP或UDP(1.11.4)

$proxy_protocol_addr

• 来自 PROXY 协议 Headers(1.11.4)的客户端地址

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

$proxy_protocol_port

• PROXY 协议 Headers(1.11.4)中的客户端端口

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

$proxy_protocol_server_addr

• PROXY 协议 Headers 中的服务器地址(1.17.6)

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

$proxy_protocol_server_port

• PROXY 协议 Headers 中的服务器端口(1.17.6)

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

$remote_addr

• client address

$remote_port

• client port

$server_addr

• 接受连接的服务器的地址

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

$server_port

• 接受连接的服务器的端口

$session_time

• 会话持续时间，以毫秒为单位，以毫秒为单位(1.11.4)；

$status

• 会话状态(1.11.4)，可以是以下之一：

• 200

  • 会话成功完成

  • 400

    • 客户端数据无法解析，例如PROXY protocolHeaders

  • 403

    • 禁止访问，例如，当访问限制为某些客户地址时

  • 500

    • 内部服务器错误

  • 502

    • 错误的网关，例如，如果无法选择或访问上游服务器。

  • 503

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

$time_iso8601

• ISO 8601 标准格式的当地时间

$time_local

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