FreeSWITCH的SIP模块mod_sofia详解

mod_sofia模块是FreeSWITCH默认使用的SIP协议栈，FreeSWITCH默认带了三个Profile（也就是三个UA），其配置目录为conf/sip_profiles

一、默认配置

internal Profile该配置默认运行在5060端口，配置文件为sip_profiles/internal.xml，详细参数如下

<profile name="intermal"> #定义了一个名字，该名字不一定要与文件名相同，可以改成任何你喜欢的名字，但是必须记住
#这个名字，因为很多地方会使用到这个名字

#如下，也可以为Profile取个别名
<aliases>
  <alias name="default"/>
</aliases>

#在一个Profile中可以配置多个网关（Gateway），如下装入了相关目录下的配置文件
<gateways>
  <X-PRE-PROCESS cmd="include" data="intermal/*.xml"/>
</gateways>

#定义该Profile所属的域（Domain），name="all"表示查看所有用户目录（conf/direcotory）中定义的Domain
#如果Domain等于某个特定的Domian，则它仅会检查特定的Domain
#alias="true"表示会为所有的Domain取一个别名，放到Profile同等重要的位置，以便后期构造或者查询呼叫字符串时
#能找到正确的用户；parse="true"（注意默认该配置为false）若为true则FreeSWITCH会解析Profile中的所有网关
#注意alias和parse属性都具有排他性，即在多个Profile的情况下，它们的值只能有一个为true，否则会产生冲突
<domains>
  <domain name="all" alias="true" parse="false"/>
</domains>

#其他一些参数的配置格式
<settings>
  <param name="参数名" value="参数值"/>
</settings>

#以下为Profile的几个重要参数

inbound-bypass-media #用于设置入局呼叫是否启用“媒体绕过（Bypass Media）”模式，取值有true 和 false两种
<param name="inbound-bypass-media" value="true"/>

context #设置来话将进入Dialplan中的那个Context进行路由
<param name="context" value="public"/>

dialplan #设置默认的dialplan类型
<param name="dialplan" value="XML"/>

inbound-codec-prefs #设置支持的来话媒体编码，用于编码协商，默认值引用了vars.xml中的global_codec_prefs变量
<param name="inbound-codec-prefs" value="$${global_codec_prefs}"/>

outbound-codec-prefs #设置支持的去话媒体编码，默认值引用了vars.xml中的global_codec_prefs变量
<param name="inbound-codec-prefs" value="$${global_codec_prefs}"/>

rtp-ip #设置RTP的IP地址
<param name="rtp-ip" value="$${local_ip_v4}"/>

sip-ip #设置SIP的IP地址
<param name="sip-ip" value="$${local_ip_v4}"/>

sip-port #设置该Profile启动后监听的SIP端口号，默认引用varl.xml中定义的变量internal_sip_port，默认值是5060
<param name="sip-port" value="$${internal_sip_port}"/>

auth-calls #设置是否对来话进行鉴权，默认是需要鉴权，即所有从该Profile进来的INVITE请求都需经过Digest验证
<param name="auth-calls" value="$${internal_auth-calls}"/>

ext-rtp-ip 和 ext-sip-ip 用于设置NAT环境中公网的RIT IP和SIP IP，该设置会影响SDP中的IP地址
<param name="ext-rtp-ip" value="auto-nat"/>
<param name="ext-sip-ip" value="auto-nat"/>

二、external Profile

该配置默认运行在5080端口中的，其中大部分参数都与sip_profiles/internal.xml中的相同，最大的不同是auth-calls参数，在external.xml中默认值是false，也就是不需要鉴权，任何人都可以往5080端口发送SIP INVITE请求

#配置Gateway

#在FreeSWITCH内部网关的name必须唯一，否则除了第一个网关外，其他的都将被忽略
<gateway name="gw1"></gateway>

#设置网关服务器的地址，若端口不是5060则需要跟上端口号
<param name="realm" value="192.168.17.251:4500"/>

#注意username和password两个参数是必须的，有些网关使用IP地址验证，而不需要用户名和密码，但在FreeSWITCH中也
#必须设置，只是它们的值将被忽略，所以可以随便填写任何值

#用户名
<param name="username" value="username"/>

#密码
<param name="password" value="password"/>

#设置SIP消息中From字段的值，如果省略，则默认与username相同
<param name="from-user" value="cluecon"/>

#设置来话中的分机号，即被叫号码，默认与username相同
<param name="extension" value="cluecom"/>

#如果需要设置代理服务器，则设置该值，默认与realm相同
<param name="register-proxy" value="192.168.17.251:4500"/>

#设置注册时SIP消息中的Expires字段的值，默认为3600秒
<param name="expire-seconds" value="3600"/>

#如果网关不需要注册，则设置为false，默认为true，有些网关必须注册了才能打电话；而有些不需要注册
<param name="register" value="false"/>

#设置SIP消息使用UDP还是TCP来承载
<param name="register-transport" value="udp"/>

#设置如果注册超时，则多少秒后再重新注册
<param name="retry-seconds" value="30"/>

#将主叫号码（要发给对方的）放到SIP的From字段中，默认会放到Remote-Party-ID字段中（有些终端从From字段中获取主叫）
<param name="caller-id-in-from" value="false"/>

#设置在SIP协议中Contact字段中额外的参数，具体的参数需根据实际情况而定，请参考相关的SIP协议或对端设备的要求
<param name="contact-params" value="tport=tcp"/>

#每隔一段时间发送一个SIP OPTIONS消息，如果失败，则会从该网关注销，并将其设置为down状态。通过周期性的发送无关紧要
#的SIP消息，有助于快速发现对方的状态变化，同时也在NAT环境中有助于保持路由器上的NAT映射关系，保持连接畅通
<param name="ping" value="25"/>

三、常用命令

#列出internal SIP Profile的状态
sofia status profile internal

#列出某个Profile上所有已注册用户
sofia status profile internal reg

#过滤某些符合条件
sofia status profile internal reg 1000
sofia status profile internal user 1000

#列出网关状态
sofia status gateway gw1

#以上命令都可以将status用xmlstatus来代替，以列出XML格式的状态，这样比较容易用于其他程序解析

#启动、停止、重启某个Profile的命令
sofia profile internal start #启动
sofia profile internal stop #停止
sofia profile internal restart #重启

#有时候修改了某个Profile的某个参数，不需要重启（重启是影响通话的），可以使用下列命令让FreeSWITCH重读sofia的配置
#注意并不是所有的参数都能生效
sofia profile internal rescan

#添加了一个新的gateway以后，也可以使用rescan指令读取
sofia profile external rescan

#如果是修改了一个网关，则可以先删除该网关，再rescan
sofia profile external killgw gw1
sofia profile external rescan

#下列命令可以指定某个网关立即向外注册或注销
sofia profile external register gw1
sofia profile external unregister

#开启该Profile的SIP跟踪功能抓SIP包
sofia profile internal siptrace on

#有时候，希望将已经注册的用户清理掉，可以使用如下命令，注意此命令只是临时清理，客户端重新注册的话还是可以注册成功的
sofia profile internal flush_inbound_reg 1000@192.168.1.7

#也可以根据call-id来清理
sofia profile internal reg 1000 #通过此命令查找到call-id的值
sofia profile flush_inbound_reg zsfsdfhdfgdfsdfsdfsdfsdf #清楚call-id=zsfsdfhdfgdfsdfsdfsdfsdf的用户

四、抓包及debug

1、抓包

#在是用sofia命令和siptrace子命令进行抓包时，用户经常搞不清该对那个Profile进行抓包，通过如下global参数使命令对所有
#Profile都有效
sofia global siptrace on #开启
sofia global siptrace off #关闭

sofia global capture on
sofia global capture off

2、debug

有时候可能是协议栈更底层的原因引起的问题，由于收到或者发送非法的消息会导致协议栈出错，这可能会使消息丢弃，当然也可能是协议层的bug，在这种情况即使开启了详细的FreeSWITCH日志以及SIP跟踪也查找不到问题的原因，这个时候可以使用如下命令打开更低级别的调试器

#如下，将开启详细的sofia sip底层调试信息，在控制台上打印日志，其中日志级别为0~9
sofia loglevel all 9

#如果你对sofia比较熟悉，也可以开启相关模块的日志，如下仅开启nua的调试信息
sofia loglevel nua 9

#loglevel的其他参数可以在sofia的命令帮助中找到

#在默认情况下sofia的日志是console级别的，它会直接打印到相关信息控制台，而不会写到日志文件中（log/freeswitch.log）
#如果需要将这些日志也写入日志文件中，可以为这些日志制定一个级别，如下分别将sofia的日志映射到debug和notice级别
sofia tracelevel debug
sofia tracelevel notice

sofia loglevel all 0 #最后可以使用此命令关闭调试

五、相关API命令

mod_sofia还提供了一些API命令，这些命令一般用于显示一些相关的信息，如下

sofia_username_of 1000@192.168.1.123 #返回注册用户的username

sofia_contact 1000@192.168.1.123 #返回注册用户的联系地址

sofia_count_reg 1000@192.168.1.123 #在允许多点注册的情况下（开启multiple-registrations）计算有多少客户端注册

sofia_dig 192.168.1.123 #返回其他服务器的服务地址和端口号，类似于DNS的dig

#显示Presence数据，下面命令显示1001处于Online状态
freeswitch@internal> sofia_presence_data status 1001@10.211.55.13
Online

#下面命令列出指定用户的Presence信息
freeswitch@internal> sofia_presence_data list 1001@10.211.55.13
status|rpid|user_agent|network_ip|network_port
Online|Online|Z 3.3.21933 r21903|10.211.55.2|55187
+OK

#列出用户的user_agent信息
freeswitch@internal> sofia_presence_data user_agent 1001@10.211.55.13    
Z 3.3.21933 r21903

Sofia Profile参数众多，修改哪些参数需要重启，哪些不需要？这个问题现在还没有统一的答案，一个基本原则就是能不重启就不重启，但有一些参数比如IP地址、端口号等相关参数，一般是需要重启的，重启Profile前需要先中断现有通话

本文转自：FreeSWITCH的SIP模块mod_sofia详解