モジュール 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 プロトコルを使用するように指定できます。

PROXY プロトコルバージョン 2 は、バージョン 1.13.11 以降でサポートされています。

listen ディレクティブには、ソケット関連のシステムコールに固有の追加パラメータをいくつか指定できます。これらのパラメータは任意のlisten ディレクティブに指定できますが、特定のアドレス:ポートペアに対しては一度だけ指定できます。

setfib=番号

このパラメータ (1.25.5) は、リスニングソケットの関連付けられたルーティングテーブル、FIB (SO_SETFIB オプション) を設定します。現在、FreeBSD でのみ動作します。

fastopen=番号

リスニングソケットの「TCP Fast Open」を有効にし (1.21.0)、3ウェイハンドシェイクをまだ完了していない接続のキューの最大長を制限します。

サーバーが同じ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=フィルタ

accept() に渡す前に受信接続をフィルタリングするリスニングソケットのアクセプタフィルタの名前 (SO_ACCEPTFILTER オプション) を設定します (1.25.5)。これは FreeBSD と NetBSD 5.0 以降でのみ動作します。可能な値はdataready と httpready です。

deferred

Linux で遅延accept() (TCP_DEFER_ACCEPT ソケットオプション) を使用するように指示します (1.25.5)。

bind

このパラメータは、指定されたアドレス:ポートペアに対して個別のbind() 呼び出しを行うように指示します。同じポートをリスンするがアドレスが異なる複数のlisten ディレクティブがあり、あるlisten ディレクティブが指定されたポートのすべてのアドレスをリスンする場合 (*:ポート)、nginx は*:ポートのみにbind() するという事実です。この場合、接続を受け入れたアドレスを決定するために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|[keepidle]:[keepintvl]:[keepcnt]

このパラメータは、リスニングソケットの「TCP キープアライブ」動作を設定します。このパラメータを省略すると、ソケットにはオペレーティングシステムの設定が有効になります。「on」に設定されている場合、ソケットのSO_KEEPALIVE オプションがオンになります。「off」に設定されている場合、ソケットのSO_KEEPALIVE オプションがオフになります。一部のオペレーティングシステムは、TCP_KEEPIDLE、TCP_KEEPINTVL、TCP_KEEPCNT ソケットオプションを使用して、ソケットごとに TCP キープアライブパラメータの設定をサポートしています。そのようなシステム (現在、Linux 2.4 以降、NetBSD 5 以降、および FreeBSD 9.0-STABLE) では、keepidle、keepintvl、およびkeepcnt パラメータを使用して設定できます。1 つまたは 2 つのパラメータを省略できます。その場合、対応するソケットオプションのシステムデフォルト設定が有効になります。例：

so_keepalive=30m::10

アイドルタイムアウト (TCP_KEEPIDLE) を 30 分に設定し、プローブ間隔 (TCP_KEEPINTVL) をシステムデフォルトのままにし、プローブ数 (TCP_KEEPCNT) を 10 プローブに設定します。

バージョン 1.25.5 より前では、異なるサーバーは異なるアドレス:ポートペアでリスンする必要があります。

preread_buffer_size 16k;

preread バッファのサイズを指定します。

preread_timeout 30s;

preread フェーズのタイムアウトを指定します。

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

このような名前はワイルドカード名と呼ばれます。

上記の名前の最初の 2 つは 1 つに組み合わせることができます。

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の種類名または数値を使用できます。数値の場合は16進数で、0xを接頭辞として付ける必要があります。

$proxy_protocol_tlv_alpn
$proxy_protocol_tlv_0x01

SSL TLVにも、ssl_を接頭辞として付けたTLVの種類名または数値でアクセスできます。

$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証明書の検証結果。クライアントが証明書を提示し、正常に検証された場合は0、それ以外の場合は0以外。

listenディレクティブでproxy_protocolパラメータを設定することで、事前にPROXYプロトコルを有効にする必要があります。

$remote_addr

クライアントアドレス

$remote_port

クライアントポート

$server_addr

接続を受け入れたサーバのアドレス

この変数の値を計算するには、通常、システムコールが1回必要です。システムコールを回避するには、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

共通ログ形式のローカル時刻