와우자 REST API 활성화 및 curl 사용법 : 초보자도 쉽게 외부 제어

Wowza Streaming Engine(와우자 스트리밍 엔진, 이하 와우자)을 외부에서 제어하기 위한 방법 중 흔히 사용되는 것은 REST API이다. 복잡한 자바 모듈 개발 및 설치 과정 없이, 웹 브라우저, curl, Python등, 사용자가 익숙하게 다룰 수 있는 다양한 도구들을 통해 간편하게 와우자를 제어할 수 있기 때문이다. 특히, 와우자 웹 UI 역시 REST API를 사용하기 때문에 기본 활성화 되어 있어 사용자가 사용하기에 별다른 추가 설정을 할 것이 별로 없다.

이 글에서는 기본 설치된 와우자의 REST API를 사용자가 외부에서 접근 할 수 있도록 설정하고, 윈도우 환경에서 명령줄 도구인 curl 을 사용해 와우자로 요청(Request)을 전송하는 방법을 설명한다.

curl이란?

이야기를 시작하기에 앞서, 먼저 curl에 대해 간단히 소개하고자 한다. curl은 여러 네트워크 프로토콜을 이용해 서버에 데이터를 전송하고, 그 응답을 확인할 수 있는 명령줄 도구로, 일종의 API 테스터라 생각하면 좋겠다.

우리가 사용할 와우자 REST API는 HTTP 프로토콜을 이용해 데이터를 주고 받는다. curl은 HTTP 또는 HTTP 프로토콜을 이용해 원하는 데이터를 전송할 수 있게 해 준다.

리눅스 환경에는 보통 기본 패키지로 설치되어 있으며, 윈도우 환경에서는 윈도우 10 이후 기본 설치 되어 있다. 이 글은 독자 제위가 윈도우 환경에서 curl을 실행하는 것을 가정한다.

윈도우 curl 실행방법

1. Windows+R키를 눌러 실행 대화창을 연다.
2. cmd를 입력해 명령프롬프트를 실행한다.
3. 명령 프롬프트에서 curl --version 이라 입력하고 엔터를 친다.

C:\Users\decteng>curl --version
curl 8.11.1 (Windows) libcurl/8.11.1 Schannel zlib/1.3 WinIDN
Release-Date: 2024-12-11
Protocols: dict file ftp ftps http https imap imaps ipfs ipns mqtt pop3 pop3s smb smbs smtp smtps telnet tftp ws wss
Features: alt-svc AsynchDNS HSTS HTTPS-proxy IDN IPv6 Kerberos Largefile libz NTLM SPNEGO SSL SSPI threadsafe Unicode UnixSockets
C:\Users\decteng>

위의 예시와 같이 curl의 버전 정보가 출력되면 curl이 설치되어 사용할 수 있다는 의미이다. 기본적인 curl 의 사용법은 다음과 같다.

curl -X “GET” “http://아이디:암호@타겟.서버.주소:포트/어쩌구/저쩌구/등등등”

와우자 REST API 사용 방법

Step 1 : REST API 동작 확인

와우자의 REST API가 동작중인지 확인해 본다. 웹 UI 가 동작하고 있다면 당연히 REST API 역시 동작 중인 상태겠으나, curl 사용법도 익히도 통신상태 점검도 할 겸 확인해 보도록 한다. 위에서 설명한 curl 기본 사용법을 참고하여, 와우자 서버에 접근해 보도록 하겠다.

C:\>curl -X "GET" "http://decteng:dectengpw@blogdemo.decteng.com:8087"
<error><success>false</success><code>403</code><message>Your IP address (w.x.y.z) has been blocked</message></error>
//해석 : 니 IP (w.x.y.z)는 접근이 안된다.

위의 모습처럼 응답이 온다면 와우자의 REST API에 정상적으로 접근했다는 의미이다. 만약 응답이 없거나 연결 시간 초과등의 오류가 발생하면 서버의 주소와 포트를, The request requires user authentication라는 메세지를 받았다면 ID 또는 암호를 잘못 입력했다는 의미이다.

기본적인 curl 사용법도 익혔고, 와우자 REST API 접근 가능 여부도 확인 했으니, 이제 와우자의 REST API 설정을 변경해 외부에서도 접근할 수 있도록 설정할 차례이다.

Step 2 : 와우자 Server.xml 수정

와우자 REST API 관련 설정은 와우자의 기본 설치 경로의 conf디렉토리에 있는 Server.xml 파일을 통해 관리된다. 파일을 열어보면 파일의 첫 시작 부분에 REST API 관련 설정 블록이 존재한다.

<RESTInterface>
 <Enable>true</Enable>
 <IPAddress>*</IPAddress>
 <Port>8087</Port>
 <AuthenticationMethod>basic</AuthenticationMethod>
 <PasswordEncodingScheme>bcrypt</PasswordEncodingScheme>
 <DiagnosticURLEnable>true</DiagnosticURLEnable>
  <SSLConfig>
   <Enable>false</Enable>
   <KeyStorePath></KeyStorePath>
   <KeyStorePassword></KeyStorePassword>
   <KeyStoreType>JKS</KeyStoreType>
   <SSLProtocol>TLS</SSLProtocol>
   <Algorithm>SunX509</Algorithm>
   <CipherSuites></CipherSuites>
   <Protocols></Protocols>
  </SSLConfig>
  <IPWhiteList>127.0.0.1</IPWhiteList>
  <IPBlackList></IPBlackList>
  <EnableXMLFile>false</EnableXMLFile>
  <DocumentationServerEnable>false</DocumentationServerEnable>
  <DocumentationServerPort>8089</DocumentationServerPort>
  <DocumentationServerAuthenticationMethod>none</DocumentationServerAuthenticationMethod>
  <Properties>
  </Properties>
</RESTInterface>

이 설정 블록에서 붉은색으로 표시된 <IPWhiteList> 태그 부분이 와우자 REST API 에 접근할 수 있는 IP 주소를 정의하는 부분이다. 아래의 예시를 참고하여 접속을 허용할 IP를 추가해 준다.

<IPWhiteList>127.0.0.1, 123.123.123.123, 172.*.*.*</IPWhiteList>

IP 화이트리스트 설정 시 참고할 사항은,

• 주소는 단일 IP 주소 또는, 와일드 카드* 를 사용하는 IP 대역으로 설정할 수 있다.
• 여러 주소 또는 대역을 지정할 경우 ,로 구분해 준다.
• localhost를 뜻하는 127.0.0.1는 삭제하면 안된다. 이 경우 WEB UI 를 사용하지 못하게 된다.

Server.xml파일 수정을 완료하고 저장한 후, 와우자 서비스를 재시작 해 준다.

Step 3 : 진실의 시간 – 연동 확인

와우자 서비스 재시작 후 curl을 이용해, Step 1 에서 보냈던 요청을 다시 한 번 보내본다.

C:\>curl -X "GET" "http://decteng:dectengpw@blogdemo.decteng.com:8087"
Wowza Streaming Engine 4 Trial Edition (Expires: May 04, 2025) 4.8.25+2 build20231003151257

Step 1의 결과와 다르게, 이번에는 와우자 스트리밍 엔진의 버전 정보가 출력되고 있다. 이는 와우자가 curl 의 요청을 정상적으로 받아들여 처리했음을 의미한다. 이참에 와우자 제어 방법을 소개하며 예시로 들었던 REST API를 이용한 로그 요청도 시험해 보자

C:\>curl -X "GET" "http://decteng:dectengpw@blogdemo.decteng.com:8087/v2/servers/defaultServer/logfiles?order=newsFirst"
<?xml version='1.0' encoding='UTF-8'?><ServerLogFiles serverName="defaultServer">
 <ServerLogFiles id="wowzastreamingengine_access.log" href="%2Fv2%2Fservers%2F_defaultServer_%2Flogfiles%2Fwowzastreamingengine_access.log">
  <FileSize>420551</FileSize>
   <StartDateMS>1744729200000</StartDateMS>
      ... 중략 ...
 <ServerLogFiles id="wowzastreamingengine_stats.log" href="%2Fv2%2Fservers%2F_defaultServer_%2Flogfiles%2Fwowzastreamingengine_stats.log">
   <FileSize>313</FileSize>
   <StartDateMS>1744383600000</StartDateMS>
 </ServerLogFiles>
</ServerLogFiles>
C:\>

와우자 서버의 로그 XML 형태로 반환해 주는 것을 확인할 수 있다.

결론

이제 REST API를 통해 와우자 서버를 마음껏 제어할 수 있게 되었다. 와우자를 제어해야 할 일이 있을때, 웹 UI에 ID치고 암호치고 접속해 수작업으로 설정하는 것이 아니라, 미리 준비해 둔 요청문을 웹브라우저 주소창에 붙여 넣는 것 만으로도 간편하게 명령을 내릴 수 있게 된 것이다.

더 나아가, 독자 제위의 필요에 따라 외부에서 연동할 프로그램을 개발해, 필요한 값을 불러오고 필요한 지시를 내리도록 프로그램을 작성할 수 도 있게 되었다. 자동화 운영이 가능해 지는 것이다. 무엇을 어떻게 사용할 것인가는 독자 제위의 상상력에 달려있다.

와우자의 REST API 설정에 대한 추가적인 정보는 REST API 메뉴얼을 참고하기 바란다.