Freeswitch-sofia.conf.xml

Overview

Freeswitch SIP module 설정파일 sofia.conf.xml 내용 정리

Structure

sofia.conf.xml 파일은 다음과 같은 구조로 되어있다. <source lang=xml> <configuration name="sofia.conf" description="sofia endpoint">

 <global_settings>
 ...
 </global_settings>

 <profiles>
   ...
 </profiles>

</configuration> </source>

global_settings

전역 설정을 하는 부분이다. <source lang=xml>

 <global_settings>
   <param name="log-level" value="0"/>
   <param name="auto-restart" value="false"/>
   <param name="debug-presence" value="0"/>
 </global_settings>

</source>

profiles

sofia 모듈에서 사용하는 각각의 프로필을 설정한다.

 <profiles>
   <profile name="example">
     <gateways>
       <gateway name="example-gateway">
         ...
       </gateway>
       ...
     </gateways>

     <aliases>
       <alias name="default"/>
     </aliases>

     <domains>
       <domain name="all" alias="true" parse="false"/>
     </domains>

     <settings>
       ...
     </settings>
   </profile>
 </profiles>

</source>

profile

profile/gateways

gateway 는 속성값 name 을 가지며, 이를 통해 다른 곳에서 해당 gateway 를 참조할 수 있게된다. 각각의 gateway 는 서로 다른 UA로써 작동하게되며 어떻게 목적지까지 도달하는지를 정의하게 된다. 예를 들면, PSTN 연결 방식을 지정할 수도 있으며 혹은 Private SIP Network 가 정의되어 있을 수도 있다. Asterisk 의 Registry 와 비슷한 개념으로 볼 수 있다. <source lang=xml> <gateways>

 <gateway>
   elements...
 </gateway>

 <gateway>
   elements...
 </gateway>

</gateways> </source>

다음은 설정 예제이다. <source lang=xml> <gateway name="gateway012">

 <param name="realm" value="sip.voipcarrier.com" />
 <param name="username" value="WBrandes" />
 <param name="password" value="myvoiceismypassword" />
 <param name="register" value="true" />
 <param name="caller-id-in-from" value="true" />
 <param name="ping" value="5" />
 <param name="ping-max" value="3" />
 <param name="retry-seconds" value="5" />
 <param name="expire-seconds" value="60" />
 <variables>
   <variable name="verbose_sdp" value="true" />
   <variable name="absolute_codec_string" value="PCMU,PCMA" direction="outbound" />
   <variable name="customer_id" value="3532" direction="inbound"/>
 </variables>

</gateway> </source>

여기서 설정한 gateway 를 dialplan 에서 사용하는 방법은 다음과 같다.

sofia/gateway/<gateway_name>/<dialstring>

Parameters

realm

username

Profile setting 에서의 username 과 혼동하지 말것. <source lang=xml> <param name="username" value="foo"/> </source>

password

from-user

from-domain

Use Freeswitch as a client

Freeswitch 는 다른 서버(freeswitch 등)로부터 이벤트를 받아오는 client 로서 작동할 수 있다. 이를 위해서는 gateway 설정에 아래와 같이 subscriptions 섹션을 추가하면 된다. <source lang=xml> <include>

 <gateway name="fs2">
   <param name="realm" value="192.168.7.2"/>
   <param name="username" value="1000"/>
   <param name="password" value="1234"/>
   <param name="register" value="false"/>

   <subscriptions name="x">

     <subscription event="dialog">
       <param name="retry-seconds" value="40"/>
       <param name="expire-seconds" value="60"/>
       <param name="content-type" value="application/dialog-info+xml"/>
       <param name="username-in-request" value="true"/>
     </subscription>

   </subscriptions>
 </gateway>

</include> </source>

profile/settings

Basic settings

debug

sip-trace

SIP detail 로그를 기록한다. <source lang=xml> <param name="sip-trace" value="yes"/> </source>

sip-capture

watchdog-enabled

watchdog-step-timeout

watchdog-event-timeout

context

해당 프로필로 인입된 콜에 적용될 context 를 지정한다. <source lang=xml> <param name="context" value="public"/> </source>

sip-port

port 번호를 지정한다. <source lang=xml> <param name="sip-port" value="$${internal_sip_port}"/> </source>

dialplan

dialplan parameter 는 특별히 중요하다. 가장 단순하게는 XML dialplan 을 사용할 수 있다. XML 설정 시, mod_xml_curl 모듈을 이용해서 freeswitch.xml dialplan 섹션에 설정된 파일 내용을 읽어오게 된다. dialplan 적용시, 설정된 dialplan 내용 중에서 가장 처음 적용가능한 dialplan 내용을 적용하게 된다. <source lang=xml> <param name="dialplan" value="XML"/> </source>

enum lookup 을 사용할 수도 있다(mod_enum 에서 dialplan 을 지원한다면). 이 경우 enum lookup 이 XML dialplan 설정을 덮어쓰게 된다. <source lang=xml> <param name="dialplan" value="enum,XML"/> </source>

순서를 반대로 적용할 경우, XML lookup 이 실패했을 경우에만 enum 설정을 적용하게 된다. <source lang=xml> <param name="dialplan" value="XML,enum"/> </source>

특정 enum root 를 적용할 수도 있다. <source lang=xml> <param name="dialplan" value="enum:foo.com,XML"/> </source>

특정 XML 을 지정할 수도 있다. <source lang=xml> <param name="dialplan" value="XML:/tmp/foo.xml,XML,enum"/> </source>

rtp-ip

RTP Listen IP 주소를 설정한다. 반드시 IP Address로 입력해야 한다. hostname 으로 입력하면 안된다. <source lang=xml> <param name="rtp-ip" value="$${local_ip_v4_or_v6}"/> </source>

sip-ip

SIP listen IP 주소를 설정한다. 반드시 IP Address로 입력해야 한다. hostname 으로 입력하면 안된다. <source lang=xml> <param name="sip-ip" value="$${local_ip_v4_or_v6}"/> </source>

ext-rtp-ip

RTP 패킷(SDP)을 위한 Freeswitch 외부 IP 주소를 입력한다. 만약 freeswitch 가 NAT 안쪽에 있다면 공인 IP 주소를 입력해야 한다. 다음과 같은 값을 입력할 수 있다.

ip address - "12.34.56.78"
a stun server lookup - "stun:stun.server.com"
a DNS name - "host:host.server.com"
auto - Use guessed ip.
auto-nat - Use ip learned from NAT-PMP or UPNP
"$${external_rtp_ip} -

ext-sip-ip

SIP 패킷을 위한 Freeswitch 외부 IP 주소를 입력한다. 만약 freeswitch 가 NAT 안쪽에 있다면 공인 IP 주소를 입력해야 한다. ext-rtp-ip 와 같은 방식으로 입력할 수 있다. <source lang=xml> <param name="ext-sip-ip" value="$${external_sip_ip}"/> </source>

Auth

challenge-realm

realm challenge key 를 설정한다. 기본값은 auto_to 이다.

auto_from - from 항목을 참조하여 SIP realm을 작성한다.
auto_to - to 항목을 참조하여 SIP realm 을 작성한다.
<any_value> - 설정한 값으로 SIP realm 을 작성한다.

If you want URL dialing to work you'll want to set this to auto_from. If you use any other value besides auto_to or auto_from you'll loose the ability to do multiple domains. <source lang=xml> <param name="challenge-realm" value="auto_from"/> </source>

log-auth-failures

인증실패시 해당 내역을 로그로 기록한다(Registration & invite). fail2ban 과 같은 유틸을 사용하고자할 때 유용하다. <source lang=xml> <param name="log-auth-failures" value="false"/> </source>

auth-all-packets

인증된 콜에서 INVITE/REGISTER 패킷 뿐만이아닌 모든 패킷들을 검증한다(관련이슈: https://freeswitch.org/jira/browse/FS-2871). <source lang=xml> <param name="auth-all-packets" value="false"/> </source>

Registration

disable-register

disable register which may be undesirable in a public switch. <source lang=xml> <param name="disable-register" value="true"/> </source>

force-register-domain

all inbound registrations will look in this domain for the users. Comment out to use multiple domains <source lang=xml> <param name="force-register-domain" value="$${domain}"/> </source>

DTMF

rfc2833-pt

dtmf-duration

Codec related options

inbound-codec-prefs

inbound 시 적용할 codec 우선순위를 설정한다. <source lang=xml> <param name="inbound-codec-prefs" value="$${global_codec_prefs}"/> </source>

outbound-codec-prefs

outbound 시 적용할 codec 우선순위를 설정한다. <source lang=xml> <param name="outbound-codec-prefs" value="$${outbound_codec_prefs}"/> </source>

inbound-codec-negotiation

codec negotiation 방식을 설정한다. <source lang=xml> <param name="inbound-codec-negotiation" value="generous"/> </source>

다음의 값들을 설정할 수 있다.

"generous" : permits the remote codec list have precedence and 'win' the codec negotiation and selection process
"greedy" : Freeswitch presence list 에서 설정된 코덱항목으로 codec-negotiation을 진행한다..
"scrooge" : "greedy" 항목보다 더 욕심(?)을 부린다. negotiation 진행중 끝까지 양보를 안하기 때문에 결국에는 상대쪽에서 어쩔수 없이 거짓으로도 코덱 항목을 수용하도록 할 수도 있다.

inbound-late-negotiation

codec negotiation 이 끝나기 전에 dialplan 을 먼저 진행하도록 허용한다. codec 이 결정되지 않은 상태에서 dialplan 을 진행하므로 IVR 과 같은 경우, 안내 음성 일부분이 전달되지 못할 수도 있다. <source lang=xml> <param name="inbound-late-negotiation" value="true"/> </source>

SIP Related options

enable-timer

RFC 4028 SIP Session Timer 를 Enable/Disable 한다. <source lang=xml> <param name="enable-timer" value="false"/> </source>

minimum-session-expires

RFC 4028 에서의 "Min-SE" 값(Sec)을 설정한다. 최소 90 이상이 설정되어야 한다. <source lang=xml> <param name="minimum-session-expires" value="120"/> </source>

session-timeout

세션 타임아웃을 정의한다. 세션 타임아웃 이후에는 re-invite 메시지를 보낸다. 단위는 Second(초)이며, 기본값은 30분 이다. RFC 4028 의 Session-Expires 항목을 정의한다.(The time at which an element will consider the session timed out, if no successful session refresh transaction occurs beforehand) <source lang=xml> <param name="session-timeout" value="1800"/> </source>

RTP Related options

rtp-timer-name

rtp-rewrite-timestamps

만약 RTP stream 을 전달하는 과정에서 timestamp 를 rewrite 할지 안할지를 설정한다. 이 옵션은 설정한 profile 을 사용하는 모든 콜에 적용되며, 각각의 콜 단위로 달리 설정하고자 한다면 rtp_rewrite_timestamps 채널 변수를 이용하면 된다.

이 옵션을 사용하게 되면 timestamp 를 재생성하여 업데이트하게된다. 만약 audio streaming 관련 이슈나 RFC 표준을 너무 따르거나 혹은 따르지 않는 다른 Gateway 와의 통신에 유용할 수 있다.

실제로, Freeswitch 에서 연결된 콜에서 음성이 지연되서 들리는 현상이 있었다. 분석결과 timestamp 와 관련이 있었다. 이 옵션을 "true"로 설정 후 문제가 해결되었다. <source lang=xml> <param name="rtp-rewrite-timestamps" value="true"/> </source>

inbound-zrtp-passthru

end-to-end security association 을 위한 ZRTP client 를 허용한다(late negotiation 도 같이 활성화된다). <source lang=xml> <param name="inbound-zrtp-passthru" value="true"/> </source>

rtp-timeout-sec

RTP timeout 을 설정한다. 여기에 설정된 시간(Second-초)만큼 RTP 패킷이 오가지 않는다면 콜이 끊어졌다고 판단하고 콜을 종료한다. 특별한 경우가 아니라면 session timer 를 사용하길 권장한다. 기본값은 0이며, 0으로 설정될 경우 사용하지 않는다. <source lang=xml> <param name="rtp-timeout-sec" value="300"/> </source>

rtp-hold-timeout-sec

RTP hold timeout 을 설정한다. 여기에 설정된 시간(Second-초)만큼 RTP 패킷이 오가지 않는다면 콜을 hold 상태로 변경한다. 특별한 경우가 아니라면 session timer 를 사용하길 권장한다. 기본값은 0이며, 0으로 설정될 경우 사용하지 않는다. <source lang=xml> <param name="rtp-hold-timeout-sec" value="1800"/> </source>

NATing

aggressive-nat-detection

적극적인 NAT dectection 을 적용한다. SIP Via: header 를 분석하여 SIP From: 내용과 맞지 않으면 NAT 모드를 enable 한다. <source lang=xml> <param name="aggressive-nat-detection" value="true"/> </source>

Presence

manage-presence

Presence 모드를 enable/disable 한다. 만약 presence 를 공유하고자 한다면(dbname 및 presence-hosts 항목 참조), 첫번째 프로필에서 이 항목을 "True" 로 설정하고 shared presence database 를 enable 한다. 그렇게 하면 이후에 따라오는 profile들의 manage-presence 값을 "passive" 로 설정하면 첫번째 profile 에서 설정한 presence database 설정을 공유하게 된다. <source lang=xml> <param name="manage-presence" value="true"/> </source>

presence-hosts

A list of domains that have a shared presence in the database specified in dbname. People who use multiple domains per profile can't use this feature anyway, so you'll want to set it to something like "_DISABLED_" in this case to avoid getting users from similar domains all mashed together. For multiple domains also known as multi-tenant calling 1001 would call all matching users in all domains. Don't use presence-hosts with multi-tenant. <source lang=xml> <param name="presence-hosts" value="$${domain},$${local_ip_v4}"/> </source>

TLS

tls

기본값은 false 이다. 사용하고자 한다면 "true"로 설정하면 된다. <source lang=xml> <param name="tls" value="$${internal_ssl_enable}"/> </source>

tls-only

기본값으로 비활성화되어 있다. 이 기능을 사용하게되면 암호화되지 않는 port 로의 listen 및 connection 을 허용하지 않게된다. 따라서 client 들의 강제적인 tls 사용을 유도함으로써, 취약점 노출과 brute force 에 좀 더 유연하게 대응할 수 있다. <source lang=xml> <param name="tls-only" value="false"/> </source>

tls-bind-params

Additional bind parameters for TLS <source lang=xml> <param name="tls-bind-params" value="transport=tls"/> </source>

tls-sip-port

TLS listen 포트 번호를 설정한다. 기본값으로는 5061 을 사용한다. <source lang=xml> <param name="tls-sip-port" value="$${internal_tls_port}"/> </source>

tls-cert-dir

agent.pem 파일, cafile.pem 파일의 디렉토리 위치를 지정한다. TLS 서버 운영시 필요하다. 기본값으로 "/usr/conf/ssl" 을 사용한다. <source lang=xml> <param name="tls-cert-dir" value="$${internal_ssl_dir}"/> </source>

tls-version

사용하고자하는 TLS 버전을 지정한다("sslv2", "sslv3", "sslv23", "tlsv1", "tlsv1.1", "tlsv1.2"). 기본값은 "tlsv1" 이다. <source lang=xml> <param name="tls-version" value="$${sip_tls_version}"/> </source>

tls-passphrase

만약 agent.pem 파일이 passphrase 로 암호화되어 있다면 복호화하기 위한 키를 설정한다. <source lang=xml> <param name="tls-passphrase" value=""/> </source>

tls-verify-date

If the client/server certificate should have the date on it validated to ensure it is not expired and is currently active. <source lang=xml> <param name="tls-verify-date" value="true"/> </source>

tls-verify-policy

This controls what, if any security checks are done against server/client certificates. Verification is generally checking certificates are valid against the cafile.pem. Set to 'in' to only verify incoming connections, 'out' to only verify outgoing connections, 'all' to verify all connections, also 'in_subjects', 'out_subjects' and 'all_subjects' for subject validation (subject validation for outgoing connections is against the hostname/ip connecting to). Multiple policies can be split with a '|' pipe, for example 'in_subjects|out'. Defaults to none. <source lang=xml> <param name="tls-verify-policy" value="none"/> </source>

tls-verify-depth

인증서 확인기능을 사용할 경우(tls-verify-policy), 허용할 인증서의 체인 단계를 설정한다. 기본값은 2 이다. <source lang=xml> <param name="tls-verify-depth" value="2"/> </source>

tls-verify-in-subjects

subject validation 을 사용할 경우(tls-verify-policy set to 'in_subjects' or 'all_subjects') 허용할 subject list 를 정의한다(구분자 '|'). 오직 인입되는 connection 에 대해서만 유효하며, 밖으로 나가는 connection subject는 항상 hostname/ip 만을 검사한다. <source lang=xml> <param name="tls-verify-in-subjects" value=""/> </source>

Media related options

ETC

forward-unsolicited-mwi-notify

hold-music

record-path

record-template

nonce-ttl

sip auth 에 사용될 TTL for nonce 값을 지정한다. 기본값은 60 이다. <source lang=xml> <param name="nonce-ttl" value="60"/> </source> This parameter is set to 60 seconds if not set here. It's used to determine how long to store the user registration record in the sip_authentication table. The expires field in the sip_authentication table is this value plus the expires set by the user agent.

References