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
공통 로그 형식의 로컬 시간