와우자 Custom Property란 무엇인가?

Custom Property는 확장 모듈이나 특정 기능의 세부 동작을 결정하기 위해 사용자가 직접 추가하는 설정값이다. 스트림 이름, 대상 어플리케이션, 파일 경로, 접속 제한과 기능 활성화 여부 등을 지정할 수 있다.

와우자 모듈을 설치하면 Custom Property도 반드시 입력해야 하는가?

모든 모듈이 Custom Property를 요구하는 것은 아니다. 그러나 세부 동작을 설정해야 하는 모듈은 공식 문서에 지정된 프로퍼티를 함께 입력해야 정상적으로 사용할 수 있다.

Custom Property의 Path란 무엇인가?

Path는 프로퍼티가 적용될 설정 파일과 내부 위치를 의미한다. 같은 이름의 프로퍼티라도 잘못된 Path에 입력하면 모듈이 해당 값을 찾지 못할 수 있다.

Custom Property의 Name은 임의로 정해도 되는가?

아니다. Name은 모듈이 설정값을 찾을 때 사용하는 식별자이므로 공식 문서나 README에 제시된 철자와 대소문자를 그대로 입력해야 한다.

Custom Property에서 사용할 수 있는 Type은 무엇인가?

와우자 Custom Property의 Type에는 String, Integer와 Boolean을 사용할 수 있다. XML에서 Type을 생략하면 기본적으로 String으로 처리된다.

Manager에서 Custom Property를 추가하는 방법은?

프로퍼티를 적용할 서버, 가상 호스트 또는 어플리케이션을 선택한 뒤 Properties → Custom → Edit → Add Custom Property 순서로 이동해 Path, Name, Type과 Value를 입력한다.

XML 파일에서 Custom Property를 어디에 추가해야 하는가?

모듈 문서에 지정된 Path의 컨테이너 안에 블록을 추가해야 한다. 파일의 아무 위치에나 추가하면 설정이 적용되지 않을 수 있다.

Custom Property를 저장한 뒤 재시작해야 하는가?

그렇다. 서버 레벨 설정은 일반적으로 와우자 서비스를 재시작해야 하고, 어플리케이션 레벨 프로퍼티는 해당 어플리케이션을 재시작해 적용할 수 있는 경우가 많다.

Manager와 XML 파일에서 입력한 Custom Property의 결과는 같은가?

동일한 Path에 같은 Name, Type과 Value를 입력했다면 기본적으로 같은 설정 결과를 만든다. Manager에서 입력한 값은 해당 XML 설정 위치에 저장된다.

Custom Property가 적용되지 않을 때 무엇을 확인해야 하는가?

Path, Name, Type과 Value가 모듈 문서와 일치하는지, 정확한 설정 범위에 입력했는지, 필요한 재시작을 수행했는지 확인한다. 이후 와우자 로그에서 프로퍼티 누락, 형식 오류와 모듈 초기화 오류를 확인한다.

와우자 설정과 Custom Property 입력 방법

와우자 스트리밍 엔진의 설정 구성과 사용자가 생성하는 커스텀 프로퍼티에 대해 설명한다. 와우자 서버의 기본 설정 파일의 종류와 역할, 사용자 확장 모듈을 사용하기 위해 웹 UI 또는 XML 파일을 직접 수정해 Path·Name·Type·Value 정보를 입력하는 방법을 안내한다.

와우자 스트리밍 엔진의 설정과 프로퍼티(Property)

와우자 스트리밍 엔진(Wowza Streaming Engine, 이하 와우자)에서 제공하는 많은 기능들은 어떻게 동작해야 하는지 정의하는 설정값들을 가지고 있다. 이러한 설정값을 프로퍼티(Property, 속성)라고 부르며, 특히 사용자가 직접 추가하는 설정값은 사용자 정의 프로퍼티(Custom Property, 이후 커스텀 프로퍼티)라고 한다.

와우자의 프로퍼티는 일반적인 프로그램의 Key-Value 설정과 비슷하지만, 값의 이름뿐 아니라 저장할 위치와 자료형까지 함께 지정해 준다.

기본 설정값

기본 설정값은 와우자에 내장된 기능의 동작을 정의하며, 대부분 해당 XML 파일에 이미 존재하는 전용 엘리먼트로 표현된다. 예를 들어 멀티캐스트 스트림을 수신할 네트워크 인터페이스를 지정하는 VHost.xml의 설정은 다음과 같다.

<Incoming>
		 <ReuseAddress>true</ReuseAddress>
		 <ReceiveBufferSize>2048000</ReceiveBufferSize>
		 <SendBufferSize>65000</SendBufferSize>
		 <MulticastBindToAddress>true</MulticastBindToAddress>
		 <MulticastInterfaceAddress>192.168.1.22</MulticastInterfaceAddress>
		 <TrafficClass>0</TrafficClass>
		 <MulticastTimeout>50</MulticastTimeout>
		 <DatagramMaximumPacketSize>4096</DatagramMaximumPacketSize>
		</Incoming>

MulticastInterfaceAddress는 사용자가 추가한 프로퍼티가 아니라 VHost.xml 구조에 기본적으로 정의된 설정 엘리먼트다.

커스텀 프로퍼티

커스텀 프로퍼티는 확장 모듈이나 특정 고급 기능이 요구하는 값을 사용자가 직접 추가하는 설정이다. 와우자 공식 문서에 따르면 커스텀 프로퍼티는 일반적으로 아래의 네 가지 요소로 구성된다.

Path: 프로퍼티가 적용될 서버, 가상 호스트, 어플리케이션 또는 세부 기능의 위치를 지정한다.
Name: 모듈이나 와우자 기능이 설정값을 찾을 때 사용하는 프로퍼티의 이름이다.
Type: 프로퍼티 값의 자료형이다. String, Integer, Boolean을 사용할 수 있다.
Value: 프로퍼티에 실제로 전달할 설정값이다.

사용자가 임의의 이름과 값을 가진 프로퍼티를 저장하는 것 자체는 가능하다. 그러나 해당 프로퍼티를 읽어 처리하는 기능이 없다면 실제 동작에 아무런 영향을 주지 않는다. 따라서 입력 오류를 막기 위해 모듈이나 기능의 매뉴얼에 있는 값을 그대로 복사해 넣어 주는 편이 좋다.

프로퍼티가 저장되는 주요 설정 파일

와우자의 설정은 대부분 기본 설치 경로 아래의 conf 디렉토리에 저장된다. 서버가 시작될 때 이 구성 파일들을 읽으며, 웹 UI를 사용하거나 파일을 직접 수정해 값을 관리할 수 있다. 와우자의 주요 설정 파일들과 그 역할은 다음과 같다.

Server.xml: 서버 전체에 적용되는 프로퍼티, 서버 리스너와 관리 인터페이스 등의 설정을 관리한다.
VHost.xml: 가상 호스트의 네트워크, 포트와 스트리밍 기능 관련 설정을 관리한다.
Application.xml: 특정 어플리케이션의 모듈, 스트림 처리와 사용자 정의 프로퍼티를 관리한다.
MediaCache.xml: 파일 기반 VOD와 관련한 Media Cache 기능과 소스 관련 프로퍼티를 관리한다.
Tune.xml: 와우자 서버의 성능 튜닝 관련 프로퍼티를 관리한다.

이 외에도 StartupStreams.xml, log4j2-config.xml과 Webhooks.json 등의 구성 파일도 존재한다.

와우자 스트리밍 엔진의 프로퍼티 변경 방법

와우자의 프로퍼티 변경 작업은 두 가지 방법으로 진행할 수 있다. 하나는 웹 UI(Streaming Engine Manager)를 사용하는 방법, 또 다른 하나는 서버의 XML 구성 파일을 직접 수정하는 방법이다.

두 방법 모두 궁극적으로는 설정을 저장하고 있는 XML 파일을 수정하는 것을 목적으로 한다. 대부분의 경우 둘 중 어느 것을 선택하더라도 동일한 결과가 나오지만, 몇몇의 경우 웹 UI만으로는 설정할 수 없는 부분이 있기도 하다. 때문에 두 방법을 모두 사용할 수 있어야 한다.

웹 UI를 이용하는 방법

일반적인 운영 환경에서는 웹 UI를 이용하는 방법이 가장 편리하다. XML 구조를 직접 찾지 않아도 되며, 입력한 값은 와우자가 적절한 구성 파일 위치에 저장한다.

웹 UI에 접속해 프로퍼티를 추가할 서버, 가상 호스트 또는 어플리케이션을 선택한다.
하위 탭 중에서 Properties를 선택한다.
Virtual Host Setup Properties
Custom 섹션으로 이동한다.
어플리케이션의 프로퍼티의 Custom 섹션
Edit를 선택한다.
Add Custom Property를 선택한다.
프로퍼티 수정 화면
설정 값을 입력해 주고 Add를 선택해 프로퍼티를 추가한다.
Custom Property를 추가하는 모습
추가할 프로퍼티가 여러 개라면 같은 과정을 반복한다.
Save를 선택해 설정을 저장한다.
안내에 따라 서버 또는 어플리케이션을 재시작한다.

와우자 공식 절차도 기능 또는 어플리케이션 화면에서 Properties → Custom으로 이동한 뒤 Add Custom Property를 이용해 Path, Name, Type과 Value를 입력하고 저장하도록 설명한다.

XML 파일을 수정하는 방법

웹 UI에서 해당 설정 화면을 제공하지 않거나 여러 서버의 설정을 일괄 관리해야 하는 경우에는 XML 파일을 직접 수정할 수 있다. 와우자 서버에 원격으로 접근하거나 서버에서 해당 파일을 직접 열어 수정 후 저장하면 된다.

모듈 안내 문서에서 프로퍼티가 적용될 파일과 Path를 확인한다.
변경할 XML 파일의 원본을 백업한다.
텍스트 편집기로 [install-dir]/conf 아래의 해당 파일을 연다.
Path에 지정된 <Properties> 엘리먼트를 찾는다.
<Properties> 내부에 필요한 <Property> 블록을 추가한다.
Name, Value와 Type의 철자 및 대소문자를 확인한다.
파일을 저장하고 와우자 서버를 재시작한다.
로그와 실제 모듈 동작을 확인한다.

XML 구성 파일에서 Custom Property는 항상 적절한 <Properties> 컨테이너 안에 추가해야 한다.

두 방법의 비교 예시

같은 프로퍼티를 변경하기 위한 두 가지 방법의 비교 예시를 들었다.

기본 프로퍼티의 변경 예
XML 파일 직접수정	웹 UI 이용
/conf/VHost.xml /VHost/HTTPTunnel	Server→VirtualHost→Properties→HTTP Tunnel
`<HTTPTunnel> <KeepAliveTimeout>2000</KeepAliveTimeout> </HTTPTunnel>`	웹 UI에서 변경하는 HTTP Tunnel 기본 프로퍼티

XML 파일 직접수정 웹 UI 이용

/conf/Application.xml
/Application/Properties Application→Properties→Custom

사용자 프로퍼티 추가의 예
XML 파일 직접수정	웹 UI 이용
/conf/Application.xml /Application/Properties	Application→Properties→Custom
`<Property> <Name>duplicateStreamsStreamNames</Name> <Value>MusicBox</Value> <Type>String</Type> </Property> <Property> <Name>duplicateStreamsTargetAppName</Name> <Value>AppToReceive</Value> <Type>String</Type> </Property> <Property> <Name>duplicateStreamsStreamNameSuffix</Name> <Value></Value> <Type>String</Type> </Property>`	웹 UI

<Property>
				 <Name>duplicateStreamsStreamNames</Name>
				 <Value>MusicBox</Value>
				 <Type>String</Type>
				</Property>
				 <Property>
				 <Name>duplicateStreamsTargetAppName</Name>
				 <Value>AppToReceive</Value>
				 <Type>String</Type>
				</Property>
				<Property>
				 <Name>duplicateStreamsStreamNameSuffix</Name>
				 <Value></Value>
				 <Type>String</Type>
				</Property>

설정 저장 후 재시작과 동작 확인

설정이나 프로퍼티를 추가하거나 변경한 뒤에는 설정의 적용 범위에 따라 서버 또는 어플리케이션을 재시작해야 한다.

서버 레벨 프로퍼티: 와우자 스트리밍 엔진 서비스를 전체 재시작한다.
가상 호스트 레벨 프로퍼티: 가상 호스트 또는 서버를 재시작한다.
어플리케이션 레벨 프로퍼티: 해당 어플리케이션을 재시작해 적용할 수 있는 경우가 많다.

본 필자는 가급적 엔진 서비스 자체를 재시작 하는 것을 권한다. 설정을 변경하는 과정에 실수로 다른 영역을 건드릴 수 있기 때문이고, 혹시 모를 오동작을 방지하기 위함이다.

재시작이 완료되었다고 해서 설정이 정상 적용되었다고 단정할 수는 없다. 변경한 설정이 정상적으로 적용되었는가 반드시 확인해야 한다. 대부분 사소한 오타로 인해 문제가 발생하는 경우가 많으니, 적용이 되지 않을 경우 정확한 이름을 입력했는지 확인해 준다.

FAQ

와우자 Custom Property란 무엇인가?: Custom Property는 확장 모듈이나 특정 기능의 세부 동작을 결정하기 위해 사용자가 직접 추가하는 설정값이다. 스트림 이름, 대상 어플리케이션, 파일 경로, 접속 제한과 기능 활성화 여부 등을 지정할 수 있다.
와우자 모듈을 설치하면 Custom Property도 반드시 입력해야 하는가?: 모든 모듈이 Custom Property를 요구하는 것은 아니다. 그러나 세부 동작을 설정해야 하는 모듈은 공식 문서에 지정된 프로퍼티를 함께 입력해야 정상적으로 사용할 수 있다.
Custom Property의 Path란 무엇인가?: Path는 프로퍼티가 적용될 설정 파일과 내부 위치를 의미한다. 같은 이름의 프로퍼티라도 잘못된 Path에 입력하면 모듈이 해당 값을 찾지 못할 수 있다.
Custom Property의 Name은 임의로 정해도 되는가?: 아니다. Name은 모듈이 설정값을 찾을 때 사용하는 식별자이므로 공식 문서나 README에 제시된 철자와 대소문자를 그대로 입력해야 한다.
Custom Property에서 사용할 수 있는 Type은 무엇인가?: 와우자 Custom Property의 Type에는 String, Integer와 Boolean을 사용할 수 있다. XML에서 Type을 생략하면 기본적으로 String으로 처리된다.
Manager에서 Custom Property를 추가하는 방법은?: 프로퍼티를 적용할 서버, 가상 호스트 또는 어플리케이션을 선택한 뒤 Properties → Custom → Edit → Add Custom Property 순서로 이동해 Path, Name, Type과 Value를 입력한다.
XML 파일에서 Custom Property를 어디에 추가해야 하는가?: 모듈 문서에 지정된 Path의 <Properties> 컨테이너 안에 <Property> 블록을 추가해야 한다. 파일의 아무 위치에나 추가하면 설정이 적용되지 않을 수 있다.
Custom Property를 저장한 뒤 재시작해야 하는가?: 그렇다. 서버 레벨 설정은 일반적으로 와우자 서비스를 재시작해야 하고, 어플리케이션 레벨 프로퍼티는 해당 어플리케이션을 재시작해 적용할 수 있는 경우가 많다.
Manager와 XML 파일에서 입력한 Custom Property의 결과는 같은가?: 동일한 Path에 같은 Name, Type과 Value를 입력했다면 기본적으로 같은 설정 결과를 만든다. Manager에서 입력한 값은 해당 XML 설정 위치에 저장된다.
Custom Property가 적용되지 않을 때 무엇을 확인해야 하는가?: Path, Name, Type과 Value가 모듈 문서와 일치하는지, 정확한 설정 범위에 입력했는지, 필요한 재시작을 수행했는지 확인한다. 이후 와우자 로그에서 프로퍼티 누락, 형식 오류와 모듈 초기화 오류를 확인한다.

갱신 내역

2025년 04월 19일 — 최초 게시
2025년 08월 18일 — 1차 수정
2026년 07월 23일 — 2차 수정 및 주소 이전