SIP模块- mod_sofia
SIP模块是FreeSWITCH的主要模块。
在FreeSWITCH中，实现一些互联协议接口的模块称为Endpoint。FreeSWITH支持很多的Endpoint，如SIP、H232等。那么实现SIP的模块为什么不支持叫mod_sip呢？这是由于FreeSWITCH的Endpoint是一个抽象的概念，你可以用任何的技术来实现。实际上mod_sofia只是对Sofia-SIP库的一个粘合和封装。除Sofia-SIP外，还有很多开源的SIP协议栈，如pjsip、osip等。最初选型的时候，FreeSWITCH的开发团队也对比过许多不同的SIP协议栈，最终选用了Sofia-SIP。FreeSWITCH是一个高度模块化的结构，如果你不喜欢，可以自己实现mod_pjsip或mod_osip等，它们是互不影响的。这也正是FreeSWITCH架构设计的精巧之处。
Sofia-SIP遵循RFC3261标准，因而FreeSWITCH也是。
配置文件
Sofia的配置文件是conf/autoload_configs/sofia.conf.xml，不过，你一般不用直接修改它，因为它实际上直接使用一条预处理指令装入了conf/sip_profiles/目录中的XML文件：
<X-PRE-PROCESS cmd="include"data="../sip_profiles/*.xml"/>
所以，从现在起，可以认为所有的Sofia配置文件都在conf/sip_profiles/中。
Sofia支持多个profile，而一个profile相当于一个SIP UA，在启动后它会监听一个“IP地址:端口”对。读到这里细心的读者或许会发现我们前面的一个错误。我们在讲B2BUA的概念时，实际上只用到了一个profile，也就是一个UA，但我们还是说FreeSWITCH启动了两个UA（一对背靠背的UA）来为alice和bob服务。是的，从物理上来讲，它确实只是一个UA，但由于它同时支持多个Session，在逻辑上就是相当于两个UA，为了不使用读者太纠结于这种概念问题中，我在前面没有太多的分析。但到了本章，你应该非常清楚UA的含义了。
FreeSWITCH默认的配置带了三个profile（也就是三个UA），在这里，我们不讨论IPv6，因此只剩下internal和external两个。internal和external的区别就是一个运行在5060端口上，另一个是在5080端口上。当然，还有其它区别，我们慢慢讲。
internal.xml
internel.xml定义了一个profile，在本节，我们以系统默认的配置逐行来解释：
<profilename="internal">
profile的名字就叫internal，这个名字本身并没有特殊的意义，也不需要与文件名相同，你可以改成任何你喜欢的名字，只是需要记住它，因为很多地方要使用这个名字。
<aliases>
<!-- <aliasname="default"/> -->
</aliases>
如果你喜欢，可以为该profile起一个别名。注意默认是加了注释的，也就是说不起作用。再说一遍，“\<!---->”在XML中的含义是注释。
<gateways>
<X-PRE-PROCESS cmd="include"data="internal/*.xml"/>
</gateways>
即然profile是一个UA，它就可以注册到别的SIP服务器上去，它要注册的SIP服务器就称为Gateway。我们一般不在internal这个profile上使用Gateway，这个留到external时再讲。
<domains>
<!--<domain name="$${domain}"parse="true"/>-->
<domain name="all" alias="true"parse="false"/>
</domains>
定义该profile所属的domain。它可以是IP地址，或一个DNS域名。需要注意，直接在hosts文件中设置的IP-域名可能不好用。
<settings>
settings部分设置profile的参数。
<!--<param name="media-option"value="resume-media-on-hold"/> -->
如果FreeSWITCH是没有媒体（no media）的，那么如果设置了该参数，当你在话机上按下hold键时，FreeSWITCH将会回到有媒体的状态。
那么什么叫有媒体无媒体呢？如下图，bob和alice通过FreeSWITCH使用SIP接通了电话，他们谈话的语音（或视频）数据要通过RTP包传送的。RTP可以像SIP一样经过FreeSWITCH转发，但是，RTP占用很大的带宽，如果FreeSWITCH不需要“偷听”他们谈话的话，为了节省带宽，完全可以让RTP直接在两者间传送，这种情况对FreeSWITCH来讲就是没有media的，在FreeSWITCH中也称bypass media（绕过媒体）。
FreeSWITCH
SIP / \ SIP
/ \
bob ------RTP------ alice
.
AttendedTransfer称为出席转移，它需要media才能完成工作。但如果在执行att-xfer之前没有媒体，该参数能让att-xfer执行时有media，转移结束后再回到bypass media状态。
<!-- <param name="user-agent-string"value="FreeSWITCH Rocks!"/> -->
不用解释，就是设置SIP消息中显示的User-Agent字段。
<param name="debug" value="0"/>
debug级别。
<!-- <param name="shutdown-on-fail"value="true"/> -->
由于各种原因（如端口被占用，IP地址错误等），都可能造成UA在初始化时失败，该参数在失败时会停止FreeSWITCH。
<param name="sip-trace" value="no"/>
是否开启SIP消息跟踪。另外，也可以在控制台上用以下命令开启和关闭sip-trace：
sofia profile internal siptrace on
sofia profile internal siptrace off
.
是否将认证错误写入日志。
<param name="context" value="public"/>
context是dialplan中的环境。在此指定来话要落到dialplan的哪个context环境中。需要指出，如果用户注册到该profile上（或是经过认证的用户，即本地用户），则用户目录（directory）中设置的contex优先级要比这里高。
<param name="rfc2833-pt" value="101"/>
设置SDP中RFC2833的值。RFC2833是传递DTMF的标准。
<param name="sip-port"value="$${internal_sip_port}"/>
监听的SIP端口号，变量internal_sip_port在vars.xml中定义，默认是5060。
<param name="dialplan" value="XML"/>
设置对应默认的dialplan。我们后面会专门讲dialplan。
<param name="dtmf-duration" value="2000"/>
设置DTMF的时长。
<param name="inbound-codec-prefs"value="$${global_codec_prefs}"/>
支持的来话语音编码，用于语音编码协商。global_codec_prefs是在vars.xml中定义的。
<param name="outbound-codec-prefs" value="$${global_codec_prefs}"/>
支持的去话语音编码。
<param name="rtp-timer-name" value="soft"/>
RTP时钟名称
<param name="rtp-ip" value="$${local_ip_v4}"/>
RTP的IP地址，仅支持IP地址而不支持域名。虽然RTP标准说应该域名，但实际情况是域名解析有时不可靠。
<param name="sip-ip" value="$${local_ip_v4}"/>
SIP的IP。不支持域名。
<param name="hold-music"value="$${hold_music}"/>
UA进行hold状态时默认播放的音乐。
<param name="apply-nat-acl" value="nat.auto"/>
使用哪个NAT ACL。
<!-- <param name="extended-info-parsing"value="true"/> -->
扩展INFO解析支持。
<!--<param name="aggressive-nat-detection"value="true"/>-->
NAT穿越，检测SIP消息中的IP地址与实际的IP地址是否相符，详见NAT穿越。
<!--
There are known issues (asserts and segfaults) when 100rel is enabled.
It is not recommended to enable 100rel at this time.
-->
<!--<paramname="enable-100rel" value="true"/>-->
该功能暂时还不推荐使用。
<!--<param name="enable-compact-headers"value="true"/>-->
支持压缩SIP头。
<!--<param name="enable-timer"value="false"/>-->
开启、关闭SIP时钟。
<!--<param name="minimum-session-expires" value="120"/>-->
SIP会话超时值，在SIP消息中设置Min-SE。
<param name="apply-inbound-acl"value="domains"/>
对来话采用哪个ACL。详见ACL。
<param name="local-network-acl"value="localnet.auto"/>
默认情况下，FreeSWITCH会自动检测本地网络，并创建一条localnet.autoACL规则。
<!--<param name="apply-register-acl"value="domains"/>-->
对注册请求采用哪个ACL。
<!--<param name="dtmf-type"value="info"/>-->
DTMF收号的类型。有三种方式，info、inband、rfc2833。
·info方式是采用SIP的INFO消息传送DTMF按键信息的，由于SIP和RTP是分开走的，所以，可能会造成不同步。
·inband是在RTP包中象普通语音数据那样进行带内传送，由于需要对所有包进行鉴别和提取，需要占用更多的资源。
·rfc2833也是在带内传送，但它的RTP包有特殊的标记，因而比inband方式节省资源。它是在RFC2833中定义的。
·<!-- 'true' means every time 'first-only'means on the first register -->
·<!--<paramname="send-message-query-on-register"value="true"/>-->
如何发送请求消息。true是每次都发送，而first-only只是首次注册时发送。
<!--<paramname="caller-id-type" value="rpid|pid|none"/>-->
设置来电显示的类型，rpid将会在SIP消息中设置Remote-Party-ID，而pid则会设置P-*-Identity，如果不需要这些，可以设置成none。
<param name="record-path"value="$${recordings_dir}"/>
录音文件的默认存放路径。
<param name="record-template"value="${caller_id_number}.${target_domain}.${strftime(%Y-%m-%d-%H-%M-%S)}.wav"/>
录音文件名模板。
<param name="manage-presence" value="true"/>
是否支持列席。
<!--<param name="manage-shared-appearance"value="true"/>-->
是否支持SLA - Shared Line Apperance。
<!--<param name="dbname"value="share_presence"/>-->
<!--<param name="presence-hosts"value="$${domain}"/>-->
这两个参数用以在多个profile间共享列席信息。
<!-- This setting is for AAL2 bitpacking on G726 -->
<!-- <param name="bitpacking"value="aal2"/> -->
<!--<param name="max-proceeding"value="1000"/>-->
最大的开放对话（SIP Dialog）数。
<!--session timers for all call to expire after the specified seconds-->
<!--<param name="session-timeout"value="120"/>-->
会话超时时间。
<!-- Can be 'true' or 'contact' -->
<!--<param name="multiple-registrations"value="contact"/>-->
是否支持多点注册，可以是contact或true。开启多点注册后多个UA可以注册上来，有人呼叫这些UA时所有UA都会振铃。
<!--set to 'greedy' if you want your codec list to take precedence -->
<param name="inbound-codec-negotiation"value="generous"/>
SDP中的语音编协商，如果设成greedy，则自己提供的语音编码列表会有优先权.
<!-- if you want to send any special bind params of your own -->
<!--<param name="bind-params"value="transport=udp"/>-->
<!--<param name="unregister-on-options-fail"value="true"/>-->
为了NAT穿越或keep alive，如果FreeSWITCH向其它网关注册时，可以周期性地发一些OPTIONS包，相当于ping功能。该参数说明当ping失败时是否自动取消注册。
<param name="tls"value="$${internal_ssl_enable}"/>
是否支持TLS，默认否。
<!-- additional bind parameters for TLS -->
<param name="tls-bind-params"value="transport=tls"/>
<!-- Port to listen on for TLS requests. (5061 will be used ifunspecified) -->
<param name="tls-sip-port"value="$${internal_tls_port}"/>
<!-- Location of the agent.pem and cafile.pem ssl certificates(needed for TLS server) -->
<param name="tls-cert-dir"value="$${internal_ssl_dir}"/>
<!-- TLS version ("sslv23" (default), "tlsv1").NOTE: Phones may not work with TLSv1 -->
<param name="tls-version"value="$${sip_tls_version}"/>
下面都是与TLS有关的参数，略。
<!--<param name="rtp-autoflush-during-bridge"value="false"/>-->
该选项默认为true。即在桥接电话是是否自动flush媒体数据（如果套接字上已有数据时，它会忽略定时器睡眠，能有效减少延迟）。
<!--<param name="rtp-rewrite-timestamps" value="true"/>-->
是否透传RTP时间戳。
<!--<param name="pass-rfc2833"value="true"/>-->
是否透传RFC2833 DTMF包。
<!--<param name="odbc-dsn"value="dsn:user:pass"/>-->
使用ODBC数据库代替默认的SQLite。
<!--<param name="inbound-bypass-media"value="true"/>-->
将所有来电设置为媒体绕过。
<!--<param name="inbound-proxy-media"value="true"/>-->
将所有来电设置为媒体透传。
<!--Uncomment to let calls hit the dialplan *before* you decide ifthe codec is ok-->
<!--<param name="inbound-late-negotiation"value="true"/>-->
对所有来电来讲，晚协商有助于在协商媒体编码之前，先前电话送到Dialplan，因而在Dialplan中可以进行个性化的媒体协商。
<!-- <param name="accept-blind-reg"value="true"/> -->
该选项允许任何电话注册，而不检查用户和密码及其它设置。
<!-- <param name="accept-blind-auth"value="true"/> -->
与上一条类似，该选项允许任何电话通过认证。
<!-- <param name="suppress-cng" value="true"/>-->
抑制CNG。
<param name="nonce-ttl" value="60"/>
SIP认证中nonce的生存时间。
<!--<param name="disable-transcoding"value="true"/>-->
禁止译码，如果该项为true则在bridge其它电话时，只提供与a-leg兼容或相同的语音编码列表进行协商，以避免译码。
<!--<param name="manual-redirect" value="true"/>-->
允许在Dialplan中进行人工转向。
<!--<param name="disable-transfer"value="true"/> -->
禁止转移。
<!--<param name="disable-register"value="true"/> -->
禁止注册。
<!-- Used for when phones respond to a challenged ACK with methodINVITE in the hash -->
<!--<param name="NDLB-broken-auth-hash"value="true"/>-->
<!-- add a ;received="<ip>:<port>" to thecontact when replying to register for nat handling -->
<!--<param name="NDLB-received-in-nat-reg-contact"value="true"/>-->
<param name="auth-calls"value="$${internal_auth_calls}"/>
是否对电话进行认证。
<!-- Force the user and auth-user to match. -->
<param name="inbound-reg-force-matching-username" value="true"/>
强制用户与认证用户必须相同。
<param name="auth-all-packets" value="false"/>
在认证时，对所有SIP消息都进行认证，而不是仅针对INVITE消息。
<!-- external_sip_ip
Used as the public IP address for SDP.
Can be an one of:
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 orUPNP
-->
<param name="ext-rtp-ip" value="auto-nat"/>
<param name="ext-sip-ip" value="auto-nat"/>
设置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="rtp-timeout-sec"value="300"/>
指定的时间内RTP没有数据传送，则挂机。
<param name="rtp-hold-timeout-sec"value="1800"/>
RTP处理保持状态的最大时长。
<!-- <param name="vad" value="in"/> -->
<!-- <param name="vad" value="out"/> -->
<!-- <param name="vad" value="both"/>-->
语音活动状态检测，有三种可能，可设为入、出，或双向，通常来说“出”（out）是一个比较好的选择。
<!--<param name="alias"value="sip:10.0.1.251:5555"/>-->
给本sip profile设置别名。
<!--all inbound reg will look in this domain for the users -->
<param name="force-register-domain"value="$${domain}"/>
<!--force the domain in subscriptions to this value -->
<param name="force-subscription-domain"value="$${domain}"/>
<!--all inbound reg will stored in the db using this domain -->
<param name="force-register-db-domain"value="$${domain}"/>
<!--force suscription expires to a lower value than requested-->
<!--<param name="force-subscription-expires"value="60"/>-->
以上选项默认是起作用的，这有助于默认的例子更好的工作。它们会在注册及订阅时在数据库中写入同样的域信息。如果你在使用一个FreeSWITCH支持多个域时，不要选这些选项。
<!--<param name="enable-3pcc"value="true"/>-->
该选项有两个值，true或poxy。true则直接接受3pcc来电；如果选proxy，则会一直等待电话应答后才回送接受。
<!-- use at your own risk or if you know what this does.-->
<!--<param name="NDLB-force-rport"value="true"/>-->
在NAT时强制rport。除非你很了解该参数，否则后果自负。
<param name="challenge-realm"value="auto_from"/>
设置SIP Challenge是使用的realm字段是从哪个域获取，auto_from和auto_to分别是从from和to中获取，除了这两者，也可以是任意的值，如freeswitch.org.cn。
<!--<param name="disable-rtp-auto-adjust"value="true"/>-->
大多数情况下，为了更好的穿越NAT，FreeSWITCH会自动调整RTP包的IP地址，但在某些情况下（尤其是在mod_dingaling中会有多个候选IP），FreeSWITCH可能会改变本来正确的IP地址。该参数禁用此功能。
<!--<param name="inbound-use-callid-as-uuid"value="true"/>-->
在FreeSWITCH是，每一个Channel都有一个UUID，该UUID是由系统生成的全局唯一的。对于来话，你可以使用SIP中的callid字段来做UUID.在某些情况下对于信令的跟踪分析比较有用。
<!--<param name="outbound-use-uuid-as-callid"value="true"/>-->
与上一个参数差不多，只是在去话时可以使用UUID作为callid。
<!--<param name="rtp-autofix-timing"value="false"/>-->
RTP自动定时。如果语音质量有问题，可以尝试将该值设成false。
<!--<param name="pass-callee-id"value="false"/>-->
默认情况下FreeSWITCH会设置额外的X- SIP消息头，在SIP标准中，所有X-打头的消息头都是应该忽略的。但并不是所有的实现都符合标准，所以在对方的网关不支持这种SIP头时，该选项允许你关掉它。
<!-- clear clears them all or supply the name to add or the nameprefixed with ~ to remove
valid values:
clear
CISCO_SKIP_MARK_BIT_2833
SONUS_SEND_INVALID_TIMESTAMP_2833
-->
<!--<param name="auto-rtp-bugs"data="clear"/>-->
某些运营商的设备不符合标准。为了最大限度的支持这些设备，FreeSWITCH在这方面进行了妥协。使用该参数时要小心。
<!-- the following can be used as workaround with bogus SRV/NAPTRrecords -->
<!--<param name="disable-srv" value="false" />-->
<!--<param name="disable-naptr" value="false"/>-->
这两个参数可以规避DNS中某些错误的SRV或NAPTR记录。
最后的这几个参数允许根据需要调整sofia库中底层的时钟，一般情况下不需要改动。
<!-- The following can be used to fine-tune timers within sofia'stransport layer
Those settings are for advanced users and can safely be left as-is-->
<!-- Initial retransmission interval (in milliseconds).
Set the T1 retransmission interval used by the SIP transaction engine.
The T1 is the initial duration used by request retransmission timers Aand E (UDP) as well as response retransmission timer G. -->
<!-- <param name="timer-T1" value="500" />-->
<!-- Transaction timeout(defaults to T1 * 64).
Set the T1x64 timeout value used by the SIP transaction engine.
The T1x64 is duration used for timers B, F, H, and J (UDP) by the SIPtransaction engine.
The timeout value T1x64 can be adjusted separately from the initialretransmission interval T1. -->
<!-- <param name="timer-T1X64" value="32000"/> -->
<!-- Maximum retransmission interval (in milliseconds).
Set the maximum retransmission interval used by the SIP transactionengine.
The T2 is the maximum duration used for the timers E (UDP) and G by theSIP transaction engine.
Note that the timer A is not capped by T2. Retransmission interval ofINVITE requests grows exponentially
until the timer B fires. -->
<!-- <param name="timer-T2" value="4000" />-->
<!--
Transaction lifetime (in milliseconds).
Set the lifetime for completed transactions used by the SIP transactionengine.
A completed transaction is kept around for the duration of T4 in orderto catch late responses.
The T4 is the maximum duration for the messages to stay in the networkand the duration of SIP timer K. -->
<!-- <param name="timer-T4" value="4000" />-->
</settings>
</profile>
external.xml
它是另一个UA配置文件，它默认使用端口5080。你可以看到，大部分参数都与internal.xml相同。最大的不同是auth-calls参数。在internal.xml中，auth-calls默认是true；而在external.xml中，默认是false。也就是说，发往5060端口的SIP消息（一般只有INVITE消息）需要认证，而发往5080的消息则不需要认证。我们一般把本地用户都注册到5060上，所以，它们打电话时要经过认证，保证只有在们用户directory中配置的用户能打电话。而5080则不同，任何人均可以向该端口发送SIP请求。
Adding Custom Headers
For instance, you may needP-Charge-Infoto append to your INVITE header, you maydo as follows:
<actionapplication="set"><![CDATA[sip_h_P-Charge-Info=<sip:${caller_id_number}@${domain_name}>;npi=0;noa=3]]></action>
eg:
<action application="set"><![CDATA[sip_h_P-Asserted-Identity=${caller_id_number}]]></action>
