mod_sofia 是 FreeSWITCH 中功能最强大、代码量最庞大的核心模块之一。尽管其详细内容已在《FreeSWITCH权威指南》中全面阐述，本文仅聚焦于 Sofia Profile 的各项配置参数，进行简要梳理与说明。

在 Sofia 配置中，Profile 支持众多可调参数，以下为部分关键选项的解释。其中一些参数为布尔类型，通常取值为 true 或 false，具体含义依上下文而定。

true/yes

media-option：媒体相关选项，支持两个特定值：

resume-media-on-hold

• 当 FreeSWITCH 处于无媒体（No Media/Bypass Media）模式时，若设置了该参数，在终端话机上执行“保持”（hold）操作后，系统将恢复媒体流传输。示例如下：

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（开启），开启后会记录更详细的运行信息以便排查问题。示例如下：

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

sip-trace：决定是否启用 SIP 协议层的消息跟踪功能。开启后可以捕获完整的 SIP 报文交互过程。配置示例如下：

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

此外，也可通过控制台动态启停该功能，使用如下命令：

sofia profile internal siptrace on
    sofia profile internal siptrace off

log-auth-failures：控制认证失败事件是否写入系统日志，便于安全审计与故障分析。

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

context：指定来电进入拨号计划（Dialplan）时默认所属的上下文环境。需要注意的是，如果用户已通过鉴权，则实际生效的是该用户在用户目录中定义的

user_context

参数，其优先级高于此处设置。示例如下：

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

dialplan：设定所使用的拨号计划类型。不同类型的 Dialplan 可影响路由逻辑处理方式。示例如下：

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

dtmf-duration：设置 DTMF 信号的标准持续时间（单位：毫秒），影响按键音识别准确性。示例如下：

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

inbound-codec-prefs：定义来话方向支持的语音编码格式列表，用于 SDP 协商阶段选择最优编解码器。示例如下：

<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 媒体流通信所使用的 IP 地址。确保地址正确以避免媒体不通。示例如下：

<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：指定用于判断 NAT 环境的 ACL 规则集，帮助系统识别来自 NAT 后端的终端设备。示例如下：

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

extended-info-parsing：是否启用对 SIP INFO 方法中扩展数据的解析功能。启用后可用于向 FreeSWITCH 发送事件通知或 API 指令。示例如下：

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

aggressive-nat-detection：启用主动 NAT 检测机制，通过比对 SIP 消息中携带的 IP 地址与实际源地址是否一致，辅助实现 NAT 穿越。详情参见 9.4 节相关内容。

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

enable-100rel：控制是否使用 PRACK 对 SIP 183 Session Progress 消息进行可靠响应确认。适用于复杂信令场景下的会话稳定性保障。示例如下：

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

enable-compact-headers：是否启用 SIP 头部压缩格式。压缩后的头部字段可减小信令包体积，提升传输效率。示例如下：

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

enable-timer：启用 RTP 定时器机制。默认开启状态下，若在指定周期（如 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：用于标识本地网络范围的 ACL 名称，配合 NAT 判断及其他网络策略使用。

false/no

rfc2833-pt：设置 SDP 中 RFC2833 标准 DTMF 事件的 Payload 类型编号。需与对端协商一致。示例如下：

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

sip-port：定义 SIP 信令监听的端口号，通常为 5060（非加密）或 5061（TLS）。配置示例如下：

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

ws-binding：配置 WebSocket 监听地址及端口，主要用于支持 WebRTC 场景下的 SIP over WebSocket 连接。示例如下：

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

wss-binding：设置安全 WebSocket（WSS）的监听地址和端口，需配合有效的 TLS 证书使用。相关证书文件应存放于

/usr/local/freeswitch/certs

目录下，配置参考如下：

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

wss.pem

shutdown-on-fail：当 UA 初始化失败（如端口被占用、IP 配置错误等）时，是否终止整个 FreeSWITCH 服务。谨慎启用，避免意外中断。示例如下：

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

FreeSWITCH 默认会自动识别本地网络环境，并生成一条 localnet.auto ACL 规则，该规则在处理 NAT 穿越时具有重要作用。此外，也支持手动配置其他 ACL 规则以满足特定需求。

apply-register-acl：用于指定注册请求所采用的 ACL 鉴权规则。

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

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

dtmf-type：定义 DTMF 收号的方式，支持 info、inband 和 rfc2833 三种模式。

message-waiting

send-message-query-on-register：控制注册过程中消息的发送行为。

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 Appearance）功能。

<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）可使用同一分机号码进行注册，当有来电呼入时，所有已注册设备将同时振铃。

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

inbound-codeudenegotiation：管理 SDP 中的语音编码协商策略。若设置为

greedy

， 则系统提供的编码列表将具有优先权。

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

bind-params：该参数的值将附加到 Contact 地址之后，用于扩展注册信息。

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

unregister-on-options-fail：决定在 OPTIONS 探测失败后是否取消分机注册状态。

为了实现 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 协议监听的 SIP 端口号。

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

tls-cert-dir：设置存放 TLS 证书的目录路径。

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

sip_tls_version：定义使用的 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 将生成连续的时间戳；否则可能产生不连续的时间戳，部分设备对此较为敏感。

<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，但不进行处理，仅做透明转发。

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

inbound-late-negotiation：是否启用晚协商机制。默认情况下，FreeSWITCH 会在进入拨号计划前完成媒体编码协商。开启此功能后，可先将呼叫送入 Dialplan，在其中进行个性化的媒体编码控制。

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

accept-blind-reg：开启该选项后，允许任何终端无需验证用户名、密码及其他安全设置即可完成注册，存在安全风险，需谨慎使用。

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

auth-calls：控制是否对来电执行鉴权操作。例如：

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

accept-blind-auth：允许所有呼叫通过认证，无需验证凭证。该设置与上一项类似，适用于特定安全策略场景。例如：

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

auth-all-packets：启用后会对所有的 SIP 消息进行身份验证，而不仅限于 INVITE 和 REGISTER 请求。这增强了安全性，但可能增加处理负担。例如：

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

inbound-reg-force-matching-username：开启此选项将强制要求注册请求中的用户名必须与 SIP 认证用户名一致，防止非法账户冒用。例如：

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

challenge-realm：指定在 SIP Challenge 中使用的 realm 字段来源。可以选择从 From 头域（from）或 To 头域（to）中提取，也可以设置为任意字符串值。例如：

realm

auto_from

auto_to

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

suppress-cng：关闭舒适噪声生成（CNG），即不发送静音期间的背景噪声包，减少带宽使用。例如：

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

vad：启用语音活动检测功能，可配置为仅输入方向（in）、输出方向（out）或双向（both）。通常推荐使用输出方向模式以平衡性能和体验。例如：

in

out

both

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

rtp-timeout-sec：定义 RTP 流超时时间（单位：秒）。若在此设定时间内未接收到任何 RTP 数据，则自动挂断通话。例如：

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

rtp-hold-timeout-sec：设置通话保持状态下的最大持续时间（单位：秒）。超过该时间后会自动结束通话。例如：

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

rtp-autofix-timing：在特定情况下自动修正 RTP 时间戳问题，有助于解决因时间同步异常导致的音频失真。例如：

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

disable-rtp-auto-adjust：禁用 FreeSWITCH 自动调整 RTP 包源 IP 地址的功能。虽然系统通常能优化 NAT 穿越，但在多候选 IP 的复杂网络环境中（如 ICE 协商时），可能会误改正确地址。关闭此功能可避免此类问题。例如：

mod_dingaling

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

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：类似于 ext-rtp-ip，用于设置公网侧的 SIP 信令 IP 地址，确保 NAT 后的设备能够被正确路由访问。例如：

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

NDLB-broken-auth-hash：兼容某些终端在响应 Challenge ACK 时错误地在哈希计算中包含 INVITE 方法的问题，允许这类非标准行为通过验证。例如：

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

NDLB-received-in-nat-reg-contact：为提升部分设备在 NAT 下的注册成功率，在 Contact 头部插入特定标识字符串以辅助代理识别真实连接路径。例如：

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

;received="<ip>:<port>"

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

NDLB-force-rport：在 NAT 环境中强制使用 rport 参数进行响应路由。除非明确了解其影响，否则修改可能导致通信异常。例如：

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

disable-transcoding：禁止媒体转码功能。当设置为 true 时，在桥接通话过程中仅提供与主叫方（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：完全禁用注册功能，阻止任何用户向该 SIP 实例注册。例如：

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

force-register-domain：强制所有用户的注册请求统一使用指定的域名（Domain），忽略客户端原始请求中的域信息。例如：

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

force-subscription-domain：使所有订阅请求都使用预设的域名，统一管理订阅上下文。例如：

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

force-register-db-domain：所有经过认证的注册用户信息将以指定域名为基准存入数据库，便于集中管理。例如：

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

force-subscription-expires：设定一个强制性的较短订阅过期时间，提高资源释放效率并降低内存占用。例如：

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

enable-3pcc：控制是否支持第三方控制呼叫（3PCC）。该参数支持两个取值：true 表示立即接受 3PCC 来电；false 则需等待被叫应答后才返回确认响应。例如：

true

proxy

Proxy

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

alias：为当前 Sip Profile 设置一个别名，方便在日志或脚本中引用。例如：

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

nonce-ttl：设定 SIP 认证过程中 nonce 值的有效生存时间（单位：秒），防止重放攻击的同时平衡会话连续性。例如：

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

inbound-use-callid-as-uuid：对于入站呼叫，允许使用 SIP 消息中的 Call-ID 作为该 Channel 的 UUID，便于追踪和分析信令流程。例如：

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

outbound-use-uuid-as-callid：在发起外呼时，将 Channel 的 UUID 用作 SIP 消息中的 Call-ID 字段值，实现唯一标识一致性。例如：

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

在多个FreeSWITCH实例之间，可以通过支持的电话设备或系统传输相关消息，以实现被叫号码的更新。该功能依赖于SIP头域的传递机制，具体可通过配置决定是否启用此功能。

X-FS-Display-Name

X-FS-Display-Number

auto-rtp-bugs：当与某些不符合标准协议的通信设备对接时，为了提升兼容性，FreeSWITCH在RTP处理方面提供了一些特殊适配选项。这些选项通常包括

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

等取值。需要注意的是，使用该参数可能带来潜在风险，应谨慎配置。

disable-srv 和 disable-naptr：这两个配置项用于避免因DNS解析过程中存在错误的SRV记录或NAPTR记录而导致的连接问题。通过关闭对这些记录的查询，可有效提升系统在复杂网络环境下的稳定性。

CISCO_SKIP_MARK_BIT_2833

SONUS_SEND_INVALID_TIMESTAMP_2833