AdmissionWebhooks
Overview
AdmissionWebhooks는 제어 서버(control server)에 쿼리를 보내 퍼블리싱 및 재생 허용(admission) 요청을 제어하는 HTTP 콜백입니다.
사용자는 고객 인증, 퍼블리싱된 스트림 추적, 앱/스트림 이름 숨기기, 로깅 등 다양한 목적으로 AdmissionWebhook을 사용할 수 있습니다.
Configuration
AdmissionWebhooks는 아래와 같이 VirtualHost에서 설정할 수 있습니다.
ControlServerUrl
쿼리를 수신할 HTTP 서버입니다. HTTP 및 HTTPS를 사용할 수 있습니다.
SecretKey
HMAC-SHA1으로 암호화할 때 사용되는 비밀 키입니다. 자세한 내용은 Security 섹션을 참조하십시오.
Timeout
요청 후 응답을 기다리는 시간입니다(밀리초 단위).
Enables
AdmissionWebhooks를 사용할 프로바이더 및 퍼블리셔를 활성화합니다.
제어 서버가 충분히 빠르게 응답하지 않으면 AdmissionWebhooks가 소켓 스레드를 점유할 수 있습니다. 이 상황에서 WorkerCount를 늘리면 여러 스레드에 부하를 분산시킬 수 있지만, 동일한 스레드를 공유하는 다른 세션은 제어 서버가 응답할 때까지 여전히 차단될 수 있습니다.
이 문제를 피하려면 아래 예시와 같이 ThreadPerSocket 옵션을 사용하십시오. 이 옵션은 각 소켓 연결에 대해 전용 스레드를 생성하고 할당하므로, 한 세션이 다른 세션을 차단하지 않습니다.
너무 많은 스레드를 생성하면 컨텍스트 스위칭(context switching) 오버헤드가 증가할 수 있다는 점에 유의하십시오. 따라서 이 옵션은 예상되는 동시 세션 수가 비교적 적은 경우에만 권장됩니다(CPU 코어 수에 따라 다르지만 일반적으로 동시 세션 100개 미만).
Request
Format
인코더가 퍼블리싱을 요청하거나 플레이어가 재생을 요청할 때 AdmissionWebhooks는 구성된 사용자의 제어 서버로 HTTP/1.1 요청 메시지를 보냅니다. 요청 메시지 형식은 다음과 같습니다.
메시지는 POST 방식으로 전송되며 페이로드는 application/json 형식입니다. ControlServer가 이 메시지를 검증할 수 있도록, X-OME-Signature는 페이로드를 HMAC-SHA1으로 암호화하여 얻은 Base64 URL Safe 인코딩 값입니다. X-OME-Signature에 대한 자세한 내용은 Security 섹션을 참조하십시오.
Json 페이로드의 각 요소에 대한 자세한 설명은 다음과 같습니다:
client
연결을 요청한 클라이언트의 정보입니다.
address
서버에 연결된 클라이언트의 IP 주소입니다.
port
서버에 연결된 클라이언트의 포트 번호입니다.
real_ip
프록시 서버가 전달한 클라이언트의 IP 주소입니다.
user_agent (optional)
클라이언트의 User_Agent입니다.
request
클라이언트의 요청에 대한 정보입니다.
direction
incoming : 클라이언트가 스트림 퍼블리싱을 요청합니다.
outgoing : 클라이언트가 스트림 재생을 요청합니다.
protocol
webrtc, srt, rtmp, llhls, thumbnail
status
opening : 클라이언트가 스트림 열기를 요청합니다.
closing : 클라이언트가 스트림을 닫았습니다.
url
클라이언트가 요청한 URL입니다.
new_url (optional)
사용자의 제어 서버에서 리디렉션된 URL입니다 (상태가 "closing"인 경우에만 해당).
time
클라이언트가 요청한 시간입니다(ISO8601 형식).
OME는 다음 순서로 값을 검색하여 real_ip에 설정합니다:
X-REAL-IP 헤더의 값
X-FORWARDED-FOR의 첫 번째 항목 값
실제로 연결된 클라이언트의 IP
Security
제어 서버는 보안상의 이유로 들어오는 HTTP 요청을 검증해야 할 수 있습니다. 이를 위해 AdmissionWebhooks 모듈은 HTTP 요청 헤더에 X-OME-Signature 값을 넣습니다. X-OME-Signature는 구성의 <AdmissionWebhooks><SecretKey>에 설정된 비밀 키를 사용하여 HMAC-SHA1 알고리즘으로 HTTP 요청의 페이로드를 암호화하여 얻은 Base64 URL Safe 인코딩 값입니다.
Conditions that triggers the request
아래와 같이 요청의 트리거 조건은 프로토콜마다 다릅니다.
WebRTC
클라이언트가 Offer SDP를 요청할 때
RTMP
클라이언트가 퍼블리시(publish) 메시지를 보낼 때
SRT
클라이언트가 streamid를 보낼 때
LLHLS
클라이언트가 재생 목록(llhls.m3u8)을 요청할 때
Response for closing status
closing 상태인 엔진은 응답에 매개변수가 필요하지 않습니다. 쿼리에 대해 빈 json 객체로 응답하기만 하면 됩니다.
Response for opening status
Format
ControlServer는 다음 Json 형식으로 응답해야 합니다. 특히 "allowed" 요소는 필수입니다.
allowed (required)
true 또는 false
클라이언트의 요청을 허용하거나 거부합니다.
new_url (optional)
클라이언트를 새 URL로 리디렉션합니다. 그러나 scheme, port, file은 요청과 다를 수 없습니다. host, app, stream만 변경할 수 있습니다. host는 동일한 서버의 다른 가상 호스트로만 변경할 수 있습니다.
lifetime (optional)
클라이언트가 연결(퍼블리싱 또는 재생)을 유지할 수 있는 시간(밀리초)입니다.
0은 무한대를 의미합니다.
HTTP 기반 스트리밍(HLS)은 연결을 유지하지 않으므로 이 값이 적용되지 않습니다.
reason (optional)
allowed가 false인 경우 로그에 출력됩니다.
User authentication and control
new_url은 원래 요청을 다른 앱/스트림으로 리디렉션합니다. 이는 사용자로부터 실제 앱/스트림 이름을 숨기거나 앱/스트림 이름 대신 추가 정보를 삽입하여 사용자를 인증하는 데 사용할 수 있습니다.
예를 들어, ws://domain.com:3333/user_id와 같이 사용자 ID를 삽입하여 WebRTC 스트리밍 URL을 발급할 수 있습니다. 사용자 ID, URL 만료 시간 및 기타 정보를 포함하는 암호화된 값이 있는 URL을 발급하면 더 효과적일 것입니다.
제어 서버가 user_id를 사용하여 사용자에게 재생 권한이 있는지 확인한 후 new_url에 ws://domain.com:3333/app/sport-3으로 응답하면, 사용자는 app/sport-3을 재생할 수 있습니다.
사용자에게 1시간의 재생 권한만 있는 경우, 제어 서버는 lifetime에 3600000을 넣어 응답합니다.
Last updated