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

設定伺服器將接受連線的 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 網域 Socket 以 "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 參數設定用於處理資料包的監聽 Socket（1.9.13）。為了在同一個會期中處理來自相同位址和埠的封包，還應指定reuseport參數。

proxy_protocol 參數（1.11.4）允許指定在此埠上接受的所有連線都應使用PROXY 協定。

自 1.13.11 版本起支援 PROXY 協定版本 2。

listen 指令可以有幾個特定於 Socket 相關系統呼叫的其他參數。這些參數可以在任何 listen 指令中指定，但對於給定的 address:port 配對，只能指定一次。

setfib=number

此參數（1.25.5）設定監聽 Socket 的相關路由表，FIB（SO_SETFIB 選項）。目前這僅在 FreeBSD 上有效。

fastopen=number

為監聽 Socket 啟用「TCP 快速開啟」（1.21.0），並限制尚未完成三次握手的連線佇列的最大長度。

除非伺服器可以處理多次接收帶有資料的相同 SYN 封包，否則請勿啟用此功能。

backlog=number

設定 listen() 呼叫中的 backlog 參數，該參數會限制擱置連線佇列的最大長度（1.9.2）。預設情況下，在 FreeBSD、DragonFly BSD 和 macOS 上，backlog 設定為 -1，在其他平台上則設定為 511。

rcvbuf=size

設定監聽 Socket 的接收緩衝區大小（SO_RCVBUF 選項）（1.11.13）。

sndbuf=size

設定監聽 Socket 的傳送緩衝區大小（SO_SNDBUF 選項）（1.11.13）。

accept_filter=filter

設定監聽 Socket 的接受篩選器名稱（SO_ACCEPTFILTER 選項），該篩選器會在將連線傳遞給 accept() 之前篩選傳入連線（1.25.5）。這僅在 FreeBSD 和 NetBSD 5.0+ 上有效。可能的值為 dataready 和 httpready。

deferred

指示在 Linux 上使用延遲的 accept()（TCP_DEFER_ACCEPT Socket 選項）（1.25.5）。

bind

此參數指示為給定的位址：埠號配對進行單獨的 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 Socket 選項）確定監聽萬用字元位址 [::] 的 IPv6 Socket 是僅接受 IPv6 連線，還是同時接受 IPv6 和 IPv4 連線。預設情況下，此參數會開啟。它只能在啟動時設定一次。

reuseport

此參數（1.9.1）指示為每個 Worker 程序建立一個單獨的監聽 Socket（在 Linux 3.9+ 和 DragonFly BSD 上使用 SO_REUSEPORT Socket 選項，或在 FreeBSD 12+ 上使用 SO_REUSEPORT_LB），允許核心在 Worker 程序之間分配傳入連線。目前這僅在 Linux 3.9+、DragonFly BSD 和 FreeBSD 12+ 上有效 (1.15.1)。

不當使用此選項可能會對安全性造成影響。

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

此參數設定監聽 Socket 的「TCP keepalive」行為。如果省略此參數，則作業系統的設定將對 Socket 生效。如果設定為值 "on"，則會為 Socket 開啟 SO_KEEPALIVE 選項。如果設定為值 "off"，則會為 Socket 關閉 SO_KEEPALIVE 選項。某些作業系統支援使用 TCP_KEEPIDLE、TCP_KEEPINTVL 和 TCP_KEEPCNT Socket 選項為每個 Socket 設定 TCP keepalive 參數。在這些系統上（目前為 Linux 2.4+、NetBSD 5+ 和 FreeBSD 9.0-STABLE），可以使用 keepidle、keepintvl 和 keepcnt 參數進行設定。可以省略一個或兩個參數，在這種情況下，將採用對應 Socket 選項的系統預設設定。例如，

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 的（基於 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"，則會插入機器的hostname。

在依名稱搜尋虛擬伺服器時，如果該名稱符合多個指定的變體（例如，萬用字元名稱和規則運算式都符合），則會依照下列優先順序選擇第一個符合的變體

1. 確切的名稱
2. 以星號開頭的最長萬用字元名稱，例如「*.example.com」
3. 以星號結尾的最長萬用字元名稱，例如「mail.*」
4. 第一個符合的規則運算式（依照組態檔案中的出現順序）

server_names_hash_bucket_size 32|64|128;

設定伺服器名稱雜湊表（hash table）的儲存桶大小。預設值取決於處理器的快取行大小。關於設定雜湊表的詳細資訊，請參閱另一個文件。

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

符合通用日誌格式的當地時間