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

Directives

Syntax:  listen address:port [ssl] [udp] [proxy_protocol] [fastopen=number] [backlog=number] [rcvbuf=size] 
         [sndbuf=size] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
Default: —
Context: server

서버가 요청을 수신하는 소켓에 대해 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 프로토콜을 사용하도록 지정할 수 있습니다.

PROXY 프로토콜 버전 2는 1.13.11버전 이후로 지원됩니다.

listen 명령은 소켓 관련 시스템 호출에 여러 추가 매개변수를 사용할 수 있습니다.

fastopen=number

리스닝 소켓에 대해 “TCP Fast Open“을 활성화하고(1.21.0) 3웨이 핸드셰이크를 아직 완료하지 않은 연결 대기열의 최대 길이를 제한합니다.

서버가 데이터가 포함된 동일한 SYN 패킷 수신을 2회 이상 처리할 수 있을 경우에만 이 기능을 활성화하세요.

backlog=number

listen() 호출에 backlog 매개변수를 설정하여, 대기 중인 연결 대기열의 최대 길이를 제한합니다(1.9.2). 기본적으로 backlog는 FreeBSD, DragonFly BSD, macOS에서 -1로 설정되고, 다른 플랫폼에서는 511로 설정됩니다.

rcvbuf=size

리스닝 소켓에 대해 수신 버퍼 용량(SO_RCVBUF 옵션)을 설정합니다(1.11.13).

sndbuf=size

리스닝 소켓에 대해 전송 버퍼 용량(SO_SNDBUF 옵션)을 설정합니다(1.11.13).

bind

이 매개변수는 특정 주소:포트 쌍에 대해 별도의 bind() 호출을 보냅니다. 포트가 동일하지만 주소가 다른 listen 명령이 여러 개일 경우, listen 명령 중 하나가 특정 포트(*:port)에 대한 모든 주소를 수신하고, nginx는 *:port에만 bind()됩니다. 이 경우, getsockname() 시스템 호출을 보내서 연결을 수신한 주소를 확인해야 합니다. backlog, rcvbuf, sndbuf, ipv6only, reuseport 또는 so_keepalive 매개변수를 사용할 경우, 항상 해당 address:port 쌍에 별도의 bind() 호출을 보냅니다.

ipv6only=on|off

이 매개변수는 (IPV6_V6ONLY 소켓 옵션을 통해) 와일드카드 주소 [::]를 수신하는 IPv6 소켓이 IPv6와 IPv4 연결에서 IPv6 연결만 수락하는지를 결정합니다. 이 매개변수는 기본적으로 활성화됩니다. 시작 시 한 번만 설정할 수 있습니다.

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 keepalive” 동작을 구성합니다. 이 매개변수를 생략할 경우, 운영 체제 설정이 소켓에 적용됩니다. “on” 값으로 설정할 경우, SO_KEEPALIVE 옵션이 소켓에 활성화됩니다. “off” 값으로 설정할 경우, SO_KEEPALIVE 옵션이 소켓이 비활성화됩니다. 일부 운영 체제는 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 쌍을 수신해야 합니다.

Syntax:  preread_buffer_size size;
Default: preread_buffer_size 16k;
Context: stream, server
This directive appeared in version 1.11.5.

preread 버퍼의 size를 지정합니다.

Syntax:  preread_timeout timeout;
Default: preread_timeout 30s;
Context: stream, server
This directive appeared in version 1.11.5.

preread 단계의 timeout을 지정합니다.

Syntax:  proxy_protocol_timeout timeout;
Default: proxy_protocol_timeout 30s;
Context: stream, server
This directive appeared in version 1.11.4.

PROXY 프로토콜 헤더 읽기를 완료할 timeout을 설정합니다. 이 시간 동안 전체 헤더가 전송되지 않을 경우, 연결이 종료됩니다.

Syntax:  resolver address ... [valid=time] [ipv6=on|off] [status_zone=zone];
Default: —
Context: stream, server
This directive appeared in version 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;

DNS 스푸핑을 방지하려면 적절히 보안이 되는 신뢰할 수 있는 로컬 네트워크에 DNS 서버를 구성하는 것이 좋습니다.

선택적 status_zone 매개변수(1.17.1)를 사용하면 지정된 zone에서 요청 및 응답의 DNS 서버 통계를 수집할 수 있습니다. 이 매개변수는 상업용 구독에서 제공합니다.

1.11.3버전 이전에서 이 명령은 상업용 구독에서 제공됩니다.

Syntax:  resolver_timeout time;
Default: resolver_timeout 30s;
Context: stream, server
This directive appeared in version 1.11.3.

이름 변환에 대한 시간제한을 설정합니다. 예를 들어, 다음과 같습니다.

resolver_timeout 5s;

1.11.3버전 이전에서 이 명령은 상업용 구독에서 제공됩니다.

Syntax:  server { ... }
Default: —
Context: stream

서버에 대한 구성을 설정합니다.

Syntax:  stream { ... }
Default: —
Context: main

스트림 서버 명령을 지정한 구성 파일 컨텍스트를 제공합니다.

Syntax:  tcp_nodelay on | off;
Default: tcp_nodelay on;
Context: stream, server
This directive appeared in version 1.9.4.

TCP_NODELAY 옵션 사용을 활성화하거나 비활성화합니다. 이 옵션은 클라이언트와 프록시된 서버 연결에 모두 활성화됩니다.

Syntax:  variables_hash_bucket_size size;
Default: variables_hash_bucket_size 64;
Context: stream
This directive appeared in version 1.11.2.

변수 해시 테이블의 버킷 용량을 설정합니다.

Syntax:  variables_hash_max_size size;
Default: variables_hash_max_size 1024;
Context: stream
This directive appeared in version 1.11.2.

변수 해시 테이블의 최대 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

현재 시간(초), ms 단위까지 표시

$nginx_version

nginx 버전

$pid

작업자 프로세스의 PID

$protocol

클라이언트와 통신하는 데 사용한 프로토콜: TCP 또는 UDP(1.11.4)

$proxy_protocol_addr

PROXY 프로토콜 헤더의 클라이언트 주소(1.11.4)

PROXY 프로토콜은 listen 명령에서 proxy_protocol 매개변수를 설정하여 미리 활성화해야 합니다.

$proxy_protocol_port

PROXY 프로토콜 헤더의 클라이언트 포트(1.11.4)

PROXY 프로토콜은 listen 명령에서 proxy_protocol 매개변수를 설정하여 미리 활성화해야 합니다.

$proxy_protocol_server_addr

PROXY 프로토콜 헤더의 서버 주소(1.17.6)

PROXY 프로토콜은 listen 명령에서 proxy_protocol 매개변수를 설정하여 미리 활성화해야 합니다.

$proxy_protocol_server_port

PROXY 프로토콜 헤더의 서버 포트(1.17.6)

PROXY 프로토콜은 listen 명령에서 proxy_protocol 매개변수를 설정하여 미리 활성화해야 합니다.

$remote_addr

클라이언트 주소

$remote_port

클라이언트 포트

$server_addr

연결을 수락한 서버의 주소

이 변수 값을 계산하려면 일반적으로 시스템 호출을 한 번 보내야 합니다. 시스템 호출을 보내지 않으려면 listen 명령에서 주소를 지정하고 bind 매개변수를 사용해야 합니다.

$server_port

연결을 수락한 서버의 포트

$session_time

세션 시간(초), ms 단위까지 표시(1.11.4);

$status

세션 상태(1.11.4)는 다음 중 하나에 해당합니다.

200

세션이 성공적으로 완료함

400

클라이언트 데이터를 파싱하지 못함(예: PROXY 프로토콜 헤더)

403

금지된 액세스(예: 특정 클라이언트 주소에 액세스가 제한된 경우)

500

내부 서버 오류

502

잘못된 게이트웨이(예: 업스트림 서버를 선택할 수 없거나 도달하지 못한 경우)

503

서비스를 사용할 수 없음(예: 연결 횟수로 액세스 제한)

$time_iso8601

ISO 8601 표준 형식의 로컬 시간

$time_local

공통 로그 형식의 로컬 시간