TOPOS 模块
Daniel-Constantin Mierla <miconda@gmail.com>
编辑
Daniel-Constantin Mierla <miconda@gmail.com>
Frederic Gaisnon <frederic.gaisnon@gmail.com>
版权所有 © 2016 FhG FOKUS
版权所有 © 2021 MomentTech
目录
- 管理员指南
- 概述
- 依赖项
2.1. Kamailio 模块
2.2. 外部库或应用程序 - 参数
3.1. storage (str)
3.2. db_url (str)
3.3. mask_callid (int)
3.4. sanity_checks (int)
3.5. branch_expire (int)
3.6. dialog_expire (int)
3.7. clean_interval (int)
3.8. event_callback (str)
3.9. event_mode (int)
3.10. contact_host (str)
3.11. contact_mode (int)
3.12. cparam_name (int)
3.13. xavu_cfg (str)
3.14. xavu_field_a_contact (str)
3.15. xavu_field_b_contact (str)
3.16. xavu_field_contact_host (str)
3.17. rr_update (int)
3.18. context (str)
3.19. methods_nocontact (str)
3.20. header_mode (int)
3.21. methods_noinitial (str)
3.22. version_table (integer)
3.23. methods_update_time (str) - 函数
4.1. tps_set_context(ctx) - 事件路由 (Event Routes)
5.1. event_route[topos:msg-outgoing]
5.2. event_route[topos:msg-sending]
5.3. event_route[topos:msg-incoming]
5.4. event_route[topos:msg-receiving]
示例列表
1.1. 设置 storage 参数
1.2. 设置 db_url 参数
1.3. 设置 mask_callid 参数
... (示例列表标题在文中具体位置翻译)
第 1 章. 管理员指南
1. 概述
本模块通过剥离显示拓扑细节的 SIP 路由头部，为基于 INVITE 的对话提供拓扑隐藏。脚本解释器将获取包含完整内容的 SIP 消息，因此所有现有功能均得以保留。
该模块对配置编写者是透明的。只需加载它即可（如有需要，可调整模块参数）。
它也适用于 SIP MESSAGE 或其他不创建对话的请求（例如 OPTIONS）------ 必须同样对它们使用 record_route()，因为发送到网络的此类消息中不会包含这些头部，而需要它们来了解与各端通信所用的本地地址。本模块也设计用于呈现（基于 SUBSCRIBE 的）对话。
REGISTER 和 PUBLISH 请求将被本模块跳过处理，预期它们会在本地 SIP 服务器上终止。
2. 依赖项
2.1. Kamailio 模块
在加载本模块之前必须加载以下模块：
- rr 模块 - 服务器必须执行路由记录，以确保对话内请求被编码/解码（必须对所有初始请求执行此操作）。
- database 模块 - 用于存储剥离和恢复拓扑的数据。
- topoh 模块 - 在需要 Call-ID 掩码时使用。
2.2. 外部库或应用程序
在加载本模块运行 Kamailio 之前，必须安装以下库或应用程序：
- 无。
3. 参数
3.1. storage (str)
存储的类型，有效的类型包括：
db- 数据库后端redis- Redis 后端htable- htable 模块后端
默认值为 "db"。
示例 1.1. 设置 storage 参数
text
...
modparam("topos", "storage", "redis")
...3.2. db_url (str)
数据库 URL。
默认值为 "mysql://kamailio:kamailiorw@localhost/kamailio"。
示例 1.2. 设置 db_url 参数
text
...
modparam("topos", "db_url", "dbdriver://username:password@dbhost/dbname")
...3.3. mask_callid (int)
是否对 Call-id: 头进行编码。某些 SIP 扩展在 SIP 消息载荷或头部中包含 Call-id，因此在这些情况下不编码 Call-id 是安全的。诸如呼叫转移或会议加入等知名扩展，若要与编码后的 Call-id 协同工作，则需要将其加入处理列表。Topoh 模块的 use_mode 参数应设置为 1。
默认值为 0（不掩码）。
示例 1.3. 设置 mask_callid 参数
text
...
modparam("topos", "mask_callid", 1)
...3.4. sanity_checks (int)
如果设置为 1，topos 模块将绑定 sanity 模块，以对收到的 SIP 请求执行完整性检查（Sanity Checks）。将执行默认的完整性检查。在进行编码/解码之前检查收到的请求格式是否良好是非常有用的。
默认值为 0（不绑定 sanity 模块）。
示例 1.4. 设置 sanity_checks 参数
text
...
modparam("topos", "sanity_checks", 1)
...3.5. branch_expire (int)
删除分支记录的间隔时间（以秒为单位）。
默认值为 180（3分钟）。
示例 1.5. 设置 branch_expire 参数
text
...
modparam("topos", "branch_expire", 300)
...3.6. dialog_expire (int)
删除对话记录的间隔时间（以秒为单位）。请记住，在初始呼叫建立后，对于 re-INVITE 或其他对话内消息，该模块不会更新对话时间戳。因此，请设置一个足够大的值（根据您最长的呼叫持续时间），以防止在重写消息时出现问题。此键值仅对 INVITE 对话起作用。SUBSCRIBE 对话记录的生存期基于 expires 头设置的值。此外，每次 re-SUBSCRIBE 都会更新对话时间戳。
默认值为 10800（3小时）。
示例 1.6. 设置 dialog_expire 参数
text
...
modparam("topos", "dialog_expire", 3600)
...3.7. clean_interval (int)
运行存储记录清理操作的间隔时间（以秒为单位）。
默认值为 60（1分钟）。
示例 1.7. 设置 clean_interval 参数
text
...
modparam("topos", "clean_interval", 30)
...3.8. event_callback (str)
KEMI 配置文件（嵌入式脚本语言如 Lua, Python 等）中用来替代 event_route[...] 块执行的函数名称。
该函数接收一个包含事件名称的字符串参数。
默认值为 'empty'（不为事件执行任何函数）。
示例 1.8. 设置 event_callback 参数
text
...
modparam("topos", "event_callback", "ksr_topos_event")
...
-- Lua 中实现的事件回调函数
function ksr_topos_event(evname)
KSR.info("===== topos module triggered event: " .. evname .. "\n");
return 1;
end
...3.9. event_mode (int)
控制执行哪些 event_route 块。这是一个位掩码：
1 - 执行 event_route[topos:msg-outgoing]；
2 - 执行 event_route[topos:msg-sending]；
4 - 执行 event_route[topos:msg-incoming]；
8 - 执行 event_route[topos:msg-receiving]。
默认值为 3（执行 outgoing 和 sending 两个 event_route 块）。
示例 1.9. 设置 event_mode 参数
text
...
modparam("topos", "event_mode", 2)
...3.10. contact_host (str)
您可能需要控制 topos 添加的 Contact 头的 host 部分。如果设置了 xavu_field_contact_host 参数，此值将被忽略。例如，当在使用 TLS 和 TOPOS 时，远程 UAS 必须能够通过 Contact 头打开一个新的 TLS 套接字。在这种情况下，Contact 头必须包含一个拥有受信任 CA 签名证书的域名。
默认值取自 Record-Route URI。
示例 1.10. 设置 contact_host 参数
text
...
modparam("topos", "contact_host", "proxy.domain.com")
...3.11. contact_mode (int)
控制消息数据在数据库或 redis 服务器中查找键的存储模式。默认使用 Contact user (0)，或者可以使用 Contact URI 参数 (1) 并带有从 SIP 消息中提取的值，或从 AVP 变量 (2) 提取。Contact mode (3) 类似于模式 2，但是用于我们需要更改域名部分的情况。这对于与需要 Contact URI 中有特定 user 部分的网关进行互操作时非常有用。
在模式 (1) 中，A侧的 contact user 取自请求 URI，B侧的 contact user 取自已处理初始 SIP 请求的 Contact 头。
如果您使用模式 (2)，需要配置 xavu_field_a_contact 和 xavu_field_b_contact 参数。此外，在处理初始 SIP 请求期间，您需要为它们赋值。
如果您使用模式 (3)，需要配置 xavu_field_a_contact_host 和 xavu_field_b_contact_host 参数。同样需要为它们赋值。
可以通过 cparam_name 参数自定义 Contact URI 参数的名称。
默认值为 0 - 使用 Contact user。
示例 1.11. 设置 contact_mode 参数
text
...
modparam("topos", "contact_mode", 1)
...3.12. cparam_name (int) (注：英文原文档标为 int，但实际意义和示例都是字符串 str)
用于存储数据库或 redis 服务器中消息查找键的 Contact URI 参数的名称。
此参数仅当 contact_mode 参数设置为 1 或 2 时使用。
默认值为 "tps"。
示例 1.12. 设置 cparam_name 参数
text
...
modparam("topos", "cparam_name", "xyz")
...3.13. xavu_cfg (str)
用于保存模块运行时要使用的特定配置值的根 XAVU 的名称。
注：如果使用了任何以 xavu_field_ 为前缀的其他参数，则必须设置此参数。
默认值为 "NULL"（禁用）。
示例 1.13. 设置 xavu_cfg 参数
text
...
modparam("topos", "xavu_cfg", "_tps_")
modparam("topos", "xavu_field_a_contact", "a_contact")
...
$xavu(_tps_=>a_contact) = "...";
...3.14. xavu_field_a_contact (str)
由 xavu_cfg 指定的根 XAVU 内部的字段名称，用于计算 A端 Contact Header 的 user 部分。此参数仅在 contact_mode (2) 时需要。
默认值为 "NULL"（禁用）。
示例 1.14. 设置 xavu_field_a_contact 参数
text
...
modparam("topos", "xavu_cfg", "_tps_")
modparam("topos", "xavu_field_a_contact", "a_contact")
...
$xavu(_tps_=>a_contact) = "...";
...3.15. xavu_field_b_contact (str)
由 xavu_cfg 指定的根 XAVU 内部的字段名称，用于计算 B端 Contact Header 的 user 部分。此参数仅在 contact_mode (2) 时需要。
默认值为 "NULL"（禁用）。
示例 1.15. 设置 xavu_field_b_contact 参数
text
...
modparam("topos", "xavu_cfg", "_tps_")
modparam("topos", "xavu_field_b_contact", "b_contact")
...
$xavu(_tps_=>b_contact) = "...";
...3.16. xavu_field_contact_host (str)
控制从哪里获取 topos 添加的 Contact 头的 host 部分。此参数允许在运行时从 XAVU 中获取值，它指定了 "xavu_cfg" 指定的 XAVU 内部的字段。如果设置了此参数，将忽略 contact_host 参数。
默认值为空，不设置。
示例 1.16. 设置 xavu_field_contact_host 参数
text
...
modparam("topos", "xavu_cfg", "_tps_")
modparam("topos", "xavu_field_contact_host", "contact_host")
...
$xavu(_tps_=>contact_host) = "kamailio.org";
...3.17. rr_update (int)
如果设置为 1，topos 模块将在 re-invite 时跟踪并更新 record route 的更改。
默认值为 0（不更新对话内的 record route 更改）。
示例 1.17. 设置 rr_update 参数
text
...
modparam("topos", "rr_update", 1)
...3.18. context (str)
设置 topos 实例的全局上下文。
该值最多只能包含 12 个字符。
默认值为 "NULL"（禁用）。
示例 1.18. 设置 context 参数
text
...
modparam("topos", "context", "srvone")
...3.19. methods_nocontact (str)
跳过为其添加 Contact 头的 SIP 方法列表。
默认值为 "BYE,CANCEL,PRACK"。
示例 1.19. 设置 methods_nocontact 参数
text
...
modparam("topos", "methods_nocontact", "CANCEL,PRACK")
...3.20. header_mode (int)
禁用以紧凑形式插入的多个逗号分隔值的头部列表。尽管紧凑形式符合 RFC 标准，但此参数提供了一种可能性，以便为不支持或无法处理紧凑形式头部值的 UA 禁用该形式。可用选项包括：
(1) - 对 Via 头禁用多个逗号分隔值；
(2) - 对 Record-Route 头禁用多个逗号分隔值；
(4) - 对 Route 头禁用多个逗号分隔值。
默认值为 "0"。
示例 1.20. 设置 header_mode 参数
text
...
modparam("topos", "header_mode", 1)
...3.21. methods_noinitial (str)
如果是初始请求（没有 To-tag），则跳过执行 topos 的 SIP 方法列表。
默认值为 "" (无)。
示例 1.21. 设置 methods_noinitial 参数
text
...
modparam("topos", "methods_noinitial", "OPTIONS,NOTIFY")
...3.22. version_table (integer)
如果设置为 0，该模块将跳过检查表版本。
默认值为 "1"（检查表版本）。
示例 1.22. version_table 参数用法
text
...
modparam("topos", "version_table", 0)
...3.23. methods_update_time (str)
处理对话内请求时，应在 topos_d 表中更新对话时间戳 (rectime) 的 SIP 方法列表（逗号分隔）。这允许将特定方法的对话生命周期延长至初始 INVITE 之外。
默认值为 "SUBSCRIBE"。
示例 1.23. 设置 methods_update_time 参数
text
...
modparam("topos", "methods_update_time", "SUBSCRIBE,UPDATE,INVITE")
...4. 函数
4.1. tps_set_context(ctx)
在运行时更新上下文。如果值为空字符串，则重置运行时的上下文。
可以从 ANY_ROUTE（任何路由）调用此函数。
示例 1.24. tps_set_context 用法
text
...
request_route {
...
tps_set_context("srvone");
...
}
...5. 事件路由 (Event Routes)
5.1. event_route[topos:msg-outgoing]
在对发出的 SIP 消息执行拓扑剥离处理之前执行。如果在事件路由内部执行了 drop，那么模块将跳过拓扑剥离的出站部分。
为了提升性能，事件路由使用内部伪造的 SIP 消息 执行（即不对传出消息进行解析），因此 R-URI、头部和正文不反映传出消息的内容。然而，在事件路由内部，变量 $sndto(ip)、$sndto(port) 和 $sndto(proto) 指向 SIP 消息的真实目的地。
示例 1.25. event_route[topos:msg-outgoing] 的用法
text
...
event_route[topos:msg-outgoing] {
if($sndto(ip)=="10.1.1.10") {
drop;
}
}
...5.2. event_route[topos:msg-sending]
在对要发出的 SIP 消息执行拓扑剥离处理之前执行，并且在 event_route[topos:msg-outgoing] 之后执行。如果在事件路由内部执行了 drop，那么模块将跳过拓扑剥离的出站部分。
此事件路由中提供了要发送的 SIP 消息的真实副本 ，因此 R-URI、头部和正文反映了传出 SIP 消息的内容。在事件路由内部，变量 $sndto(ip)、$sndto(port) 和 $sndto(proto) 指向 SIP 消息的真实目的地。
示例 1.26. event_route[topos:msg-sending] 的用法
text
...
event_route[topos:msg-sending] {
if(is_request() and $fU=="alice") {
drop;
}
}
...5.3. event_route[topos:msg-incoming]
在对接收到的 SIP 消息执行拓扑剥离处理之前执行。如果在事件路由内部执行了 drop，那么模块将跳过拓扑剥离的入站部分。
为了提升性能，事件路由使用内部伪造的 SIP 消息 执行（即不对传入消息进行解析），因此 R-URI、头部和正文不反映传入消息的内容。然而，在事件路由内部，变量 $si、$sp 和 $proto 指向 SIP 消息的真实源地址，关键字 src_port 和 dst_port 也是如此。
示例 1.27. event_route[topos:msg-incoming] 的用法
text
...
event_route[topos:msg-incoming] {
if($si=="10.1.1.10") {
drop;
}
}
...5.4. event_route[topos:msg-receiving]
在对已收到的 SIP 消息执行拓扑剥离处理之前执行，并且在 event_route[topos:msg-incoming] 之后执行。如果在事件路由内部执行了 drop，那么模块将跳过拓扑隐藏的入站部分。
此事件路由中提供了传入 SIP 消息的真实副本 ，因此 R-URI、头部和正文反映了传入 SIP 消息的内容。在事件路由内部，变量 $si、$sp 和 $proto 指向 SIP 消息的真实源地址，关键字 src_port 和 dst_port 也是如此。
示例 1.28. event_route[topos:msg-receiving] 的用法
text
...
event_route[topos:msg-receiving] {
if(is_request() and $fU=="alice") {
drop;
}
if($sp==5555 || $si=="1.2.3.4") {
drop;
}
if(src_port==1234 || dst_port==5678) {
drop;
}
}
...