Nginx 四層代理功能主要部分文檔

在 Nginx 中，四層的資料被稱為 stream，和四層代理有關的模組主要有：

ngx_stream_core_module：四層代理的準系統模組
ngx_stream_upstream_module：四層代理轉寄到上遊的模組
ngx_stream_proxy_module：四層代理相關配置
其他 stream 相關模組用於如 SSL 支援、geoip 支援、簡單存取控制支援等，本次測試並沒有使用到。

使用的注意事項

Nginx 的四層反代功能較為簡單，其存取控制模組因為來源站點 IP 可以進行偽造，基本不可用於 UDP Flood 的防護。

使用健康檢測功能的前提是他們在一個共用記憶體的 zone 裡，注意各個區塊的層次關係即可，zone 是配置上遊伺服器組共用記憶體的功能，因此 zone 要放在 upstream 區塊。status 命令即監控dashboard 是 ngx_http_status_module 的內容，嚴格來說不是四層代理的部分。

我使用的 UDP 反代配置：

stream {
 
    upstream dns_server {
        zone stream_dns 10m;
        server 127.0.0.1:53;
    }
 
    match dns {
        send \x00\x2a\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x06\x73\x65\x72\x76\x65\x72\x0a\x73\x74\x61\x72\x64\x75\x73\x74\x65\x72\x02\x6d\x65\x00\x00\x01\x00\x01;
        expect ~* \x6a;
    }
 
 
    server {
        listen 10086 udp;
        proxy_pass dns_server;
        error_log  /home/nginx/dns-error.log debug;
        health_check udp match=dns interval=1s;
        status_zone stream_dns;
   }
}

健康檢測頁面配置：

server {
    listen 8080;
 
    root   /usr/share/nginx/html;
 
    location /status {
        status;
    }
    location = /status.html {
    }
}
ngx_stream_core_module

ngx_stream_core_module 模組從1.9.0版本開始提供，預設編譯不包含此模組，需要在編譯參數中加上--with-stream。

文法：listen address:port [ssl] [udp] [backlog=number] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
環境：server

設定接受串連的連接埠和地址，可以只有連接埠號碼，也可以包含IP或主機名稱。

listen 127.0.0.1:12345;
listen *:12345;
listen 12345;     # same as *:12345
listen localhost:12345;
IPV6 地址需要使用中括弧標註：

Shell

listen [::1]:12345;
listen [::]:12345;
1
2
listen [::1]:12345;
listen [::]:12345;
Unix socket 需要使用首碼“Unix:”

listen unix:/var/run/nginx.sock;

ssl 參數所有串連都需要使用 SSL 加密；

udp 參數指定監聽 UDP 連接埠（從1.9.13版本開始支援）；

其他相關參數：

backlog=number 參數設定 listen() 調用的最大等待串連隊列數，預設情況下，backlog 在 BSD 上被設定為-1，在其他平台被設定為511；

bind 參數使用所給的 address:port 產生一個獨立的 bind() 調用，用於使用多個 listen 命令監聽不同地址上的相同連接埠號碼；

ipv6only=on|off 參數，配置 [::] 監聽地址是否接受 IPV4 請求，此選項預設為 on；

reuseport 參數（從1.9.1開始支援）為每個 worker 進程獨立地建立一個監聽的 socket（使用 SO_REUSEPORT），允許核心將入站串連分發到不同 worker 進程，僅支援 Linux3.9+ 和 DragonFly BSD；

so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt] 參數配置 TCP keepalive 特性；

不同的 Server 區塊必須 listen 不同的地址+連接埠組合。

文法：resolver address … [valid=time] [ipv6=on|off];
環境：server

配置解析 upstream 網域名稱所使用的 DNS 伺服器：

resolver 127.0.0.1 [::1]:5353;

地址可以以 IP 或者網域名稱的形式給出，也可以附帶連接埠號碼。預設情況下，nginx 會解析 V4 和 V6 地址，並會在 TTL 時間內緩衝解析結果。

文法：resolver_timeout time;
預設：30秒
環境：stream，server
（從1.11.3版本開始提供）

設定 DNS 解析逾時時間。

文法：server {…}
環境：stream

設定一個獨立的 Server。

文法：stream {…}
環境：main

提供四層代理的 Server 的配置環境，和 http {…} 類似。

文法：tcp_nodelay on | off;
預設：on
環境：stream，server
（從1.9.4版本開始提供）

開啟或關閉 TCP_NODELAY 選項，這個選項將會同時應用於到用戶端和到上遊伺服器的串連。

文法：variables_hash_bucket_size size;
預設：64
環境：stream
（從1.11.2版本開始提供）

設定變數 hash 表的桶大小，詳細設定參見獨立文檔

文法：variables_hash_max_size size;
預設：1024
環境：stream
（從1.11.2版本開始提供）

設定 hash 表的最大大小，詳細設定參見獨立文檔

內建變數，（ngx_stream_core_module 模組從1.11.2開始支援變數）：

$binary_remote_addr：二進位形式的用戶端地址
$bytes_sent：向用戶端發送的位元組數量
$connection：串連序號
$hostname：主機名稱
$msec：以毫秒為解析度的目前時間
$nginx_version：nginx 的版本
$pid：worker 的 PID
$remote_addr：用戶端地址
$remote_port：用戶端連接埠
$server_addr：接受已連線的服務端地址，擷取此變數需要一次 system call，為避免產生 system call 在 listen 命令後指定監聽地址並增加 bind 參數
$server_port：接受已連線的服務端連接埠
$time_iso8601：ISO 8601 格式的本地時間
$time_local：通常日誌格式中的本地時間
ngx_stream_proxy_module

ngx_stream_proxy_module允許被代理的資料流通過 TCP、UDP、Unix socket，從1.9.0版本開始提供。

文法：proxy_bind address [transparent] | off;
環境：stream, server
（從1.9.2版本開始提供）

指定向外的串連通過指定的 IP，參數的值可以包含變數（1.11.2）。參數 off 可以取消從上一級繼承的 proxy_bind 命令的效果,讓系統自動選擇出口 IP。

transparent（透明代理）參數可以發往來源站點（proxied server）的串連的源 IP 為非本地的 IP，如：用戶端的真實 IP。proxy_bind $remote_addr transparent; 為達到這個目的，nginx worker 進程需要以超級使用者權限運行並配置核心路由表以攔截被來源站點發回的網路流量。

文法：proxy_buffer_size size;
預設：16k
環境：stream, server
（從1.9.14版本開始提供）

設定從來源站點讀取資料時候緩衝區的大小，也將同時設定從用戶端讀取資料的緩衝區大小。

文法：proxy_connect_timeout time;
預設：60s;
環境：stream, server

定義和來源站點已經建立的連線逾時時間。

文法：proxy_download_rate rate;
預設：0;
環境：stream, server

從來源站點接受資料的速率限制，rate 的單位是 byte，預設數值為0即沒有限制。這個限制是針對每個串連的，因此在開啟兩個到來源站點的串連時，總速率將會是 rate 值的兩倍。

文法：proxy_next_upstream on | off;
預設：on;
環境：stream, server

當往來源站點的串連無法建立時，是否嘗試將用戶端的串連傳往下一個來源站點。

嘗試串連下一個來源站點的次數和時間都可被限制。

文法：proxy_next_upstream_timeout time;
預設：0;
環境：stream, server

限制串連到下一個來源站點時最大的嘗試時間，預設數值為0 ，即沒有限制。

文法：proxy_next_upstream_tires number;
預設：0;
環境：stream, server

限制串連到下一個來源站點時最大的嘗試次數，預設數值為0 ，即沒有限制。

文法：proxy_pass address;
環境：server

設定來源站點地址，地址可以以網域名稱或 IP 和連接埠的形式出現，如proxy_pass localhost:12345;
，也可以是 Unix socket 如proxy_pass unix:/tmp/stream.socket;。

當網域名稱被解析為多個 IP 時，將使用 round-robin 方式進行輪詢，也可以使用伺服器組（ngx_stream_upstream_module 提供）,如proxy_pass $upstream;

在使用伺服器組的情況下，server name 將首先在伺服器組中搜尋，如無結果則使用 resolver 進行查詢。

文法：proxy_protocol;
預設：off;
環境：stream, server
（從1.9.2版本開始提供）

啟用PROXY proxy_protocol
串連到來源站點。

文法：proxy_response number;
環境：stream, server
（從1.9.3版本開始提供）

在 UDP 代理啟用的情況下，設定從來源站點期望接收的資料報數量，預設情況下接收報文的數量沒有限制，將持續接收響應直到 proxy_timeout 逾時。

文法：proxu_ssl on | off;
預設：off;
環境：stream, server

對和來源站點之間的串連啟用 SSL。

文法：proxy_ssl_certificate file;
環境：stream, server

指定一個 PEM 格式的認證用於進行和來源站點的 SSL 串連認證。

文法：proxy_ssl_certificate_key file;
環境：stream, server

指定一個 PEM 格式的私密金鑰用於進行和來源站點的 SSL 串連認證。

文法：proxy_ssl_ciphers ciphers;
預設：DEAFAULT;
環境：stream, server

指定和來源站點進行握手所使用的加密套件，以 OpenSSL 庫可讀的格式書寫，使用命令openssl ciphers可以查看完整的列表。

文法：proxy_ssl_crl file;
環境：stream, server

指定吊銷認證列表。

文法：proxy_ssl_name name;
預設：host from proxy_pass;
環境：stream, server

用於覆蓋發往來源站點的 SNI 請求中的 server name，該 server name 可以包含變數（自1.11.3版本開始），預設情況下，proxy_pass 參數中的主機名稱將被使用。

文法：proxy_ssl_password_file file;
環境：stream, server

指定私密金鑰的加密口令，每行一個，口令將在載入私密金鑰檔案的時候被依次嘗試。

文法：proxy_ssl_session_reuse on | off;
Default:on;
Context:stream, server

指定和來源站點串連時，SSL session 是否被複用，如果出現“SSL3_GET_FINISHED”錯誤，請嘗試關閉 SSL 會話複用。

文法：proxy_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2];
預設：TLSv1 TLSv1.1 TLSv1.2;
環境：stream, server

和來源站點串連時使用指定的 SSL 協議版本。

文法：proxy_ssl_trusted_certificate file;
環境：stream, server

指定 PEM 格式的可信的 CA 列表用於驗證來源站點的認證有效性。

文法：proxy_ssl_verify on | off;
預設：off;
環境：stream, server

是否啟用和來源站點之間的認證。

文法：proxy_ssl_verify_depth number;
預設：1;
環境：stream, server

指定驗證來源站點認證的憑證鏈結層數。

文法：proxy_timeout time;
預設：10m;
環境：stream, server

指定兩次讀和寫操作的逾時間隔，此設定將同時應用在與用戶端的串連和與來源站點的串連。若在這個時間內沒有資料轉送，串連將被關閉。

文法：proxy_upload_rate rate;
預設：0;
環境：stream, server
（從1.9.3開始提供）

限制從用戶端讀取資料的速率，數字單位是 byte/s，預設值0表示沒有限制。這個數值是針對每個串連的，因此開啟兩個串連時，資料轉送速率將是這個值的兩倍。

ngx_stream_upstream_module

ngx_stream_upstream_module模組出現於1.9.0版本，用於定義可以被proxy_pass所調用的來源站點伺服器組和相關的配置，收費訂閱版本還支援動態配置組和主動健康檢測。

文法：upstream name { … }
環境：stream

定義一組伺服器，伺服器可以監聽不同的連接埠，也可以監聽 TCP 通訊埠和 Unix Socket 的混合搭配：

upstream backend {
    server backend1.example.com:12345 weight=5;
    server 127.0.0.1:12345            max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend2;
    server backend3.example.com:12345 resolve;
 
    server backup1.example.com:12345  backup;
}
預設情況下，入站串連將被 round-robin 演算法均分到每個後端，在上面這個配置了權重的樣本中，平均每7個入站串連有5個將被轉到 backend1，第二和第三個 backend 各接到一個串連；串連如果失敗，將會嘗試下一個 server，全部失敗時串連將被關閉。

文法：server address [parameters];
環境：upstream

定義 server 的地址和參數，地址可以以 IP 或者網域名稱的形式給出，此時連接埠號碼必須指明；也可以使用unix:首碼指明地址是個 Unix socket，如果網域名稱被解析為多個 IP，則被認為是定義了多個伺服器。

參數表：

weight=number 參數指定了加權 round-robin 演算法的權重值。
max_fails=number 參數指定了最大失敗重試次數。
fail_timeout=number 參數同時指定了一次到後端 server 的串連的逾時時間，和一個 server 被認為停用時間。
backup 參數將該 server 標註為備用，在主要伺服器全部停用時候串連將被傳到 backup 伺服器。
down 參數將手動將一台 server 標註為不可用。
max_conns=number 限制向來源站點串連的最大串連數，預設為0，即沒有限制。
resolve 參數監視 server 網域名稱對應的 IP 變化，而不需要在 upstream 中修改伺服器配置也不需要重啟 nginx，本功能要求伺服器組在一個共用記憶體的 zone 中。使用這個參數必須在 stream 區塊裡有至少一個 resolver 命令：
Shell

stream {
    resolver 10.0.0.1;

    upstream u {
        zone ...;
        ...
        server example.com:12345 resolve;
    }
}

service=name 參數將解析 DNS SRV 記錄，要使用這個命令，需要 resolve 參數且 hostname 後不能含有連接埠號碼。
slow_start=time 參數設定了一個被認為是停用 Server 恢複的時間，預設為0，即 slow_start 被關閉
注意，當一個伺服器組裡只有一個伺服器的時候，max_fails fail_timeout slow_start 參數將會被忽略。

文法：zone name [size];
環境：upstream

一個 zone 使用 name 和 size 定義了一個共用的記憶體地區，workers 之間可以共用設定檔和即時狀態，多個伺服器組可以共用一個 zone，因此只需要聲明一個 zone。

另外，作為收費訂閱的一部分，動態配置組允許組內伺服器在不完整重讀設定檔的前提下更換或者修改組內成員，相關配置方式參見upstream_conf in ngx_http_stream_module。

文法：state file;
環境：upstream
（從1.9.7版本開始提供）

指定一個檔案路徑，儲存動態配置組當前配置狀態，目前的版本中這個狀態包括配置組中的伺服器列表和各個伺服器的參數。這個檔案在每次設定檔解析時被載入、upstream 配置變動的時候被更新，注意不應直接對這個檔案進行編輯。

文法：hash key [consistent];
環境：upstream

負載平衡所使用的用戶端-服務端映射的雜湊演算法是基於 key 的，hash key 可以包含文字和變數，如hash $remote_addr。

文法：least_conn;
環境：upstream

使用“最少串連”負載平衡演算法，nginx 將自動選擇串連最少的後端，如果存在多個後端串連數相等，將使用加權的 round-robin 進行選擇。

文法：least_time connect | first_byte | last_byte;
環境：upstream

使用“最快串連”負載平衡演算法，nginx 將選擇速度最快的後端，可以通過參數選擇“最快”的定義是首包時間、傳輸完成時間還是串連建立時間。

文法：health_check [parameters];
環境：server

開啟伺服器組的周期性主動健康檢測功能。

參數表：

interval=time 參數設定了兩次健全狀態檢查的間隔，單位是秒，預設值為5。
fails=number 參數設定了健全狀態檢查連續失敗達到指定次數後，將 Server 標記為不健康。
pass=number 參數設定了健全狀態檢查連續通過達到指定次數後，將 Server 標記為健康。
match=name 參數通過名稱指定某個 match 區塊為健康檢測通過的條件，預設情況下，只會檢測是否可以成功建立 TCP 串連。
port=number 參數定義了進行健康檢測時串連的連接埠號碼，預設情況等於 server 區塊的連接埠號碼。
udp 參數指定了進行 UDP 健康檢測，此時必須指定 match 參數，並提供 send 和 expect 內容。
Shell

server {
    proxy_pass backend;
    health_check;
}

這個配置將會每5秒檢測配置組中的每台伺服器是否可以成功建立 TCP 串連，當串連建立失敗，健康檢測將不會通過並將伺服器標記為不健康的。此時用戶端將不會串連到不健康的伺服器。

健康檢測也可以指定發送的資料內容和期待接收的內容，這部分配置獨立地在 match 命令中設定，並在 health_check 命令的 match 參數中進行引用。

伺服器組必須在同一個共用記憶體地區裡。

如果一個伺服器組設定了多項健全狀態檢查，一項未能通過的檢查就會將整個伺服器組標記為不健康的。

文法：health_check_timeout timeout;
預設：health_check_timeout 5s;
環境：stream, server

對健康檢測操作，以 health_check_timeout 的值覆蓋 proxy_timeout 的值。

文法：match name { … }
環境：stream

以名稱定義一組驗證健康檢測傳回值的測試集。

參數表：

send string 參數定義發送給 server 的字串。
expect string | ~ regex 參數定義了伺服器返回的字串，可以使用正則進行匹配，如“~*”進行大小寫不敏感匹配，使用“~”進行大小寫敏感匹配.
send 和 expect 參數都可以使用“\x”首碼表示16進位字元，如“\x80\x1a”。
當滿足下麵條件時，健康檢測通過：
TCP 串連建立
send 裡的字串成功發送
伺服器響應符合 expect
未超出 health_check_timeout 指定的值
範例：

Shell

upstream backend {
    zone     upstream_backend 10m;
    server   127.0.0.1:12345;
}

match http {
    send     "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n";
    expect ~ "200 OK";
}

server {
    listen       12346;
    proxy_pass   backend;
    health_check match=http;
}