《FreeSWITCH参考手册》

1.20 mod_sofia

mod_sofia是FreeSWITCH中最重量级的模块，不管是代码量还是功能上都很丰富。关于该模块我们已经在《FreeSWITCH权威指南》上详细介绍过了，在此，我们仅来看一下Sofia Profile中的配置参数。

Sofia的Profile有很多参数，下面是一些简要说明，供参考。其中，有的选项是取布尔值的，则一般来说true/yes通用，false/no通用。

media-option：媒体选项。该选项有两个取值。

resume-media-on-hold：如果FreeSWITCH是没有媒体（No Media/Bypass Media）的，那么如果设置了该参数，当你在话机上按下hold键时，FreeSWITCH 将会回到有媒体的状态。如：

bypass-media-after-att-xfer：Attended Transfer译即出席转移，也称协商转，它需要媒体才能完成工作。但如果在执行att-xfer之前没有媒体，该参数能让att-xfer执行时有通过re-INVITE请求要回媒体，等到转移结束后再回到Bypass Media状态。
user-agent-string：该参数设置SIP消息中显示的User-Agent字段。如：

    <param name="user-agent-string" value="FreeSWITCH Rocks!"/>

debug：设置是否启用调试。取值有0和1，如果是1则会输出更多的调试信息。如：

    <param name="debug" value="1"/>

shutdown-on-fail：由于各种原因（如端口被占用，IP地址错误等），都可能造成 UA 在初始化时失败，该参数在失败时会停止FreeSWITCH。如：

    <param name="shutdown-on-fail" value="true"/>

sip-trace：是否开启SIP消息跟踪。如：

    <param name="sip-trace" value="no"/>

另外，也可以在控制台上用以下命令开启和关闭SIP跟踪，如：

    sofia profile internal siptrace on
    sofia profile internal siptrace off

log-auth-failures：是否将认证错误写入日志。

    <param name="log-auth-failures" value="true"/>

context：设置来话到达Dialplan的Context，注意，如果用户鉴权通过，则用户目录中的user_context比该参数优先级要高。如：

    <param name="context" value="public"/>

rfc2833-pt：设置SDP中RFC2833的Payload值。如：

    <param name="rfc2833-pt" value="101"/>

sip-port：设置监听的SIP端口号。如：

    <param name="sip-port" value="5060"/>

ws-binding：设置WebSocket的监听地址和端口号（用于SIP over WebSocket，一般是WebRTC呼叫）。如：

    <param name="ws-binding"  value=":5066"/>

wss-binding：设置安全WebSocket监听地址和端口号。该选择需要相关的安全证书（wss.pem存放在/usr/local/freeswitch/certs目录下）。如：

    <param name="wss-binding" value=":7443"/>

dialplan：设置Dialplan的类型。如：

    <param name="dialplan" value="XML"/>

dtmf-duration：设置DTMF的时长。如：

    <param name="dtmf-duration" value="2000"/>

inbound-codec-prefs：支持的来话语音编码，用于语音编码协商。如：

    <param name="inbound-codec-prefs" value="PCMU,PCMA,H264"/>

outbound-codec-prefs：支持的去话语音编码。用于语音编码协商。如：

    <param name="outbound-codec-prefs" value="$${global_codec_prefs}"/>

rtp-timer-name：RTP定时器名称，其他可先的定时器可以在FreeSWITCH中用『show timers』命令得到。

    <param name="rtp-timer-name" value="soft"/>

rtp-ip：RTP使用的地址。如：

    <param name="rtp-ip" value="$${local_ip_v4}"/>

sip-ip：SIP监听的IP地址。如：

    <param name="sip-ip" value="$${local_ip_v4}"/>

hold-music：UA进入hold状态时默认播放的音乐。如：

    <param name="hold-music" value="$${hold_music}"/>

apply-nat-acl：用于判断哪些IP地址涉及到NAT。如：

    <param name="apply-nat-acl" value="nat.auto"/>

extended-info-parsing：是否启用扩展INFO解析支持，扩展INFO支持可用于向FreeSWITCH发送事件、API命令等。如：

    <param name="extended-info-parsing" value="true"/>

aggressive-nat-detection：用于NAT穿越，检测SIP消息中的IP地址与实际的IP地址是否相符，详见9.4节。

    <param name="aggressive-nat-detection" value="true"/>

enable-100rel：设置是否使用PRACK对SIP 183消息进行证实。如：

    <param name="enable-100rel" value="true"/>

enable-compact-headers：是否压缩SIP头。压缩SIP头域能使用SIP包变小一些。如：

    <param name="enable-compact-headers" value="true"/>

enable-timer：是否启用时钟。默认是启用的。启用时钟后，在指定的时间内（如20ms）如果收不到RTP数据，则返回静音（CNG）数据。如果不启用该功能，则会一直等待直到收到数据。如：

    <param name="enable-timer" value="true"/>

minimum-session-expires：SIP会话超时最小值，在SIP消息中设置Min-SE。如：

    <param name="minimum-session-expires" value="120"/>

apply-inbound-acl：对来话启用哪个ACL进行鉴权。如：

    <param name="apply-inbound-acl" value="domains"/>

local-network-acl：默认情况下，FreeSWITCH会自动检测本地网络，并创建一条localnet.auto ACL规则。在NAT穿越时有用。也可以手工指定其它的ACL。如：

    <param name="local-network-acl" value="localnet.auto"/>

apply-register-acl：对注册请求采用哪个ACL进行鉴权。如：

    <param name="apply-register-acl" value="domains"/>

dtmf-type：DTMF收号的类型。有三种方式，info、inband、rfc2833。如：
send-message-query-on-register：如何发送message-waiting消息。true是每次都发送，而first-only只是首次注册时发送。如：

    <param name="send-message-query-on-register" value="true"/>

caller-id-type：设置主叫号码显示的类型，rpid将会在SIP消息中设置Remote-Party-ID，而pid则会设置P-*-Identity，如果不需要这些，可以设置成none。如：

    <param name="caller-id-type" value="rpid"/>

record-path：录音文件的默认存放路径。如：

    <param name="record-path" value="$${recordings_dir}"/>

record-template：录音文件名模板。如：

    <param name="record-template"
    value="${caller_id_number}.${target_domain}.${strftime(%Y-%m-%d-%H-%M-%S)}.wav"/>

manage-presence：是否支持列席（Presence）。如果不用的话可以关掉以节省资源。如：

    <param name="manage-presence" value="true"/>

manage-shared-appearance：是否支持SLA（Shared Line Apperance）。如：

    <param name="manage-shared-appearance" value="true"/>

与此相关的还有两个参数，分别指定Presence的数据库名称及域，如：

    <param name="dbname" value="share_presence"/
    <param name="presence-hosts" value="$${domain}"/>

bitpacking：设置G726的bitpacking。如：

    <param name="bitpacking" value="aal2"/>

max-proceeding：最大的开放对话（SIP Dialog）数。如：

    <param name="max-proceeding" value="1000"/>

session-timeout：会话超时时间。

    <param name="session-timeout" value="120"/>

multiple-registrations：

是否支持多点注册，取值可以是contact或true。开启多点注册后多个UA可以用同一个分机注册上来，有人呼叫该分机时所有UA都会振铃。

    <param name="multiple-registrations" value="contact"/>

inbound-codec-negotiation：SDP中的语音编协商，如果设成greedy，则自己提供的语音编码列表会有优先权。如：

    <param name="inbound-codec-negotiation" value="generous"/>

bind-params：该参数设置的值会附加在Contact地址上。如：

    <param name="bind-params" value="transport=udp"/>

unregister-on-options-fail：是否在Ping失败后取消分机注册。为了NAT穿越或支持Keep Alive，FreeSWITCH向通过NAT方式注册到它的分机（nat-options-ping）或所有注册到它的分机（all-reg-options-ping）周期性地发一些 OPTIONS包，相当于ping功能。如：

    <param name="unregister-on-options-fail" value="true"/>
    <param name="nat-options-ping" value="true"/>
    <!-- <param name="all-reg-options-ping" value="true"/> -->

tls：是否支持 TLS，默认否。如：

    <param name="tls" value="true"/>

tls-bind-params：设置TLS的其它绑定参数。如：

    <param name="tls-bind-params" value="transport=tls"/>

tls-sip-port：TLS的监听端口号。如：

    <param name="tls-sip-port" value="5061"/>

tls-cert-dir：存放TLS证书的目录。如：

    <param name="tls-cert-dir" value="$${internal_ssl_dir}"/>

sip_tls_versio：使用的TLS版本，有sslv23（默认）或tlsv1两种。如：

    <param name="tls-version" value="sslv23"/>

rtp-autoflush-during-bridge：该选项默认为 true。即在桥接电话是是否自动清空缓存中的媒体数据（如果套接字上已有数据时，它会忽略定时器睡眠，能有效减少延迟）。如：

    <param name="rtp-autoflush-during-bridge" value="false"/>

rtp-rewrite-timestamps：是否重写或透传RTP时间戳。如果透传，FreeSWITCH有时会产生不连续的时间戳，有的设备对此可能比较敏感，该选项可以让FreeSWITCH产生自己的时间戳。如：

    <param name="rtp-rewrite-timestamps" value="true"/>

pass-rfc2833：是否透传RFC2833 DTMF包。如：

    <param name="pass-rfc2833" value="true"/>

odbc-dsn：使用ODBC数据库代替默认的SQLite。如：

    <param name="odbc-dsn" value="dsn:user:pass"/>

inbound-bypass-media：将所有来电设置为媒体绕过模式，即媒体流（RTP）不经过FreeSWITCH。如：

    <param name="inbound-bypass-media" value="true"/>

inbound-proxy-media：将所有来电设置为媒体透传。媒体经过FreeSWITCH但FreeSWITCH不处理，直接转发。如：

    <param name="inbound-proxy-media" value="true"/>

inbound-late-negotiation：是否开启晚协商。默认情况下FreeSWITCH对来话会先协商媒体编码，然后再进入Dialplan。开启晚协商有助于在协商媒体编码之前，先前电话送到 Dialplan，因而在Dialplan中可以进行个性化的媒体协商。

    <param name="inbound-late-negotiation" value="true"/>

accept-blind-reg：该选项允许任何电话注册，而不检查用户和密码及其他设置。如：

    <param name="accept-blind-reg" value="true"/>

accept-blind-auth: 与上一条类似，该选项允许任何呼叫通过认证。如：

    <param name="accept-blind-auth" value="true"/>

suppress-cng：抑制CNG，即不使用静音包。如：

    <param name="suppress-cng" value="true"/>

nonce-ttl：设置SIP认证中nonce的生存时间（秒）。如：

   <param name="nonce-ttl" value="60"/>

disable-transcodin：禁止转码，如果该项为true则在bridge其他电话时，只提供与a-leg兼容或相同的语音编码列表进行协商，以避免引起转码。

    <param name="disable-transcoding" value="true"/>

manual-redirect：允许在Dialplan中进行人工重定向。如：

    <param name="manual-redirect" value="true"/>

disable-transfer：禁止转移。如：


    <param name="disable-transfer" value="true"/>

disable-register：禁止注册。如：

    <param name="disable-register" value="true"/>

NDLB-broken-auth-hash：有一些电话对Chanllenge ACK的回复在哈希值里会有INVITE方法，该选项容忍这种行为。如：

    <param name="NDLB-broken-auth-hash" value="true"/>

<!-- add a ;received="<ip>:<port>" to the contact when replying to register for nat handling -->

NDLB-received-in-nat-reg-contact：为支持某些NAT穿越，在Contact头域中增加;received="<ip>:<port>"字符串。如：

    <param name="NDLB-received-in-nat-reg-contact" value="true"/>

auth-calls：是否对来电进行鉴权。如：

    <param name="auth-calls" value="true"/>

inbound-reg-force-matching-username：强制注册用户与SIP认证用户必须相同。如：

    <param name="inbound-reg-force-matching-username" value="true"/>

auth-all-packets：对所有的SIP消息都进行鉴权，而不是仅仅是针对INVITE和REGISTER消息。如：

    <param name="auth-all-packets" value="false"/>

ext-rtp-ip：在NAT环境中，设置外网RTP IP。该设置会影响SDP中的IP 地址。有以下几种可能：

- 一个IP 地址，如 12.34.56.78
- 一个 stun 服务器，它会使用 stun 协议获得公网 IP， 如 stun:stun.server.com
- 一个 DNS 名称，如 host:host.server.com
- auto ， 它会自动检测 IP 地址
- auto-nat，如果路由器支持NAT-PMP或uPnP，则可以使用这些协议获取公网IP。

如：

    <param name="ext-rtp-ip" value="auto-nat"/>

ext-sip-ip：与上一条类似，设置外网的SIP IP。如：

    <param name="ext-sip-ip" value="auto-nat"/>

rtp-timeout-sec：设置RTP超时值（秒）。指定的时间内RTP没有数据收到，则挂机。如：

    <param name="rtp-timeout-sec" value="300"/>

rtp-hold-timeout-sec：RTP处于保持状态的最大时长（秒）。如：

    <param name="rtp-hold-timeout-sec" value="1800"/>

vad：语音活动状态检测，有三种可能，可设为入（in）、出（out），或双向（both），通常来说out是一个比较好的选择。如：

    <param name="vad" value="out"/>

alias：给Sip Profile设置别名。如：

    <param name="alias" value="sip:10.0.1.251:5555"/>

force-register-domain：对所有用户都强制使用某一域（Domain）。如：

    <param name="force-register-domain" value="$${domain}"/>

force-subscription-domain：对所有订阅都强制使用某一域（Domain）。如：

    <param name="force-subscription-domain" value="$${domain}"/>

force-register-db-domain：对所有经过认证的用户都使用该域（Domain）存入数据库。如：

    <param name="force-register-db-domain" value="$${domain}"/>

force-subscription-expires：强制一个比较短的订阅超时时间。如：

    <param name="force-subscription-expires" value="60"/>

enable-3pcc：是否支持3PCC呼叫。该选项有两个值，true或proxy。 true则直接接受3PCC来电；如果选Proxy，则会一直等待电话应答后才回送接受。

    <param name="enable-3pcc" value="true"/>

NDLB-force-rport：在NAT时强制rport。除非你很了解该参数，否则后果自负。如：

    <param name="NDLB-force-rport" value="true"/>

challenge-realm：设置 SIP Challenge使用的realm字段是从哪个域获取，auto_from和auto_to分别是从From和To中获取，除了这两者，也可以是任意的字符串值，如：

    <param name="challenge-realm" value="freeswitch.org.cn"/>

disable-rtp-auto-adjust：大多数情况下，为了更好的穿越NAT，FreeSWITCH 会自动调整（适应）RTP包的来源IP地址，但在某些情况下（尤其是在mod_dingaling中会有多个候选IP的时候），FreeSWITCH 可能会改变本来正确的IP地址。该参数禁用此功能。

    <param name="disable-rtp-auto-adjust" value="true"/>

inbound-use-callid-as-uuid：在 FreeSWITCH 是，每一个Channel都有一个UUID，该UUID是由系统生成的全局唯一的。对于来话，你可以使用SIP中的Call-ID字段来做UUID，在某些情况下对于信令的跟踪分析比较有用。

    <param name="inbound-use-callid-as-uuid" value="true"/>

outbound-use-uuid-as-callid：与上一个参数差不多，只是在去话时可以使用UUID作为Call-ID。

    <param name="outbound-use-uuid-as-callid" value="true"/>

rtp-autofix-timing：在某些情况下自动修复RTP时间戳。

    <param name="rtp-autofix-timing" value="false"/>

pass-callee-id：在支持的话机或系统间传送相关消息以更新被叫号码（在多个FreeSWITCH实例间使用X-FS-Display-Name和X-FS-Display-NumberSIP头域实现）。可以设置是否支持这种功能。如：

    <param name="pass-callee-id" value="false"/>

auto-rtp-bugs：在跟某些不符合标准设备对接时，为了最大限度的支持这些设备，FreeSWITCH在这方面进行了妥协。可能的取值有CISCO_SKIP_MARK_BIT_2833和SONUS_SEND_INVALID_TIMESTAMP_2833等。使用该参数时要小心。如：
disable-srv或disable-naptr：这两个参数可以规避DNS中某些错误的 SRV 或 NAPTR 记录。如：

最后要讲的这几个参数允许根据需要调整Sofia-SIP库中底层的时钟，一般情况下不需要改动。这几个参数是给高级用户用的，一般来说保持使用默认值即可。更详细的说明请参考FreeSWITCH默认的配置文件中的说明及相关的RFC3261。这些参数和默认值如下：

<param name="timer-T1" value="500" />
<param name="timer-T1X64" value="32000" />
<param name="timer-T2" value="4000" />
<param name="timer-T4" value="4000" />