kamailio siptrace介绍

背景

SIPtrace模块提供存储进来和出去的SIP消息到数据库或者发送到第三方的服务器。两种方式存储信息：

sip_trace(): 记录会话的SIP消息
trace_mode: 自动记录所有的SIP消息

官方文档地址: siptrace, kamailio的版本:

version: kamailio 5.8.5 (x86_64/linux)

重要参数解析

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


modparam("siptrace", "db_url", DBURL)
# 用来追踪消息而不是用户的标志,默认0
modparam("siptrace", "trace_flag", 22)
# 开启追踪功能,默认0
modparam("siptrace", "trace_on", 1)
# 存储用户的AVP,默认NULL
modparam("siptrace", "traced_user_avp", "$avp(user)")
# SIP URL地址,用于发送SIP消息
modparam("siptrace", "duplicate_uri", "sip:10.1.1.1:5888")
# 是否存储到数据库,在这种场景下:只发送SIP消息到duplicate_uri,并不想存储到数据库,可以设置为0
modparam("siptrace", "trace_to_database", 0)
# 本地发送IP地址
modparam("siptrace", "trace_local_ip", "10.1.1.1:5064")
# 是否追踪ACK消息,默认1, 当选择追踪某些ACK消息时,可以设置为0,然后结合event_route[sl:filtered-ack],sip_trace来过滤.
modparam("siptrace", "trace_sl_acks", 0)
# 存储fromip, toip, method,direction到X-Siptrace-*头上, 默认0
modparam("siptrace", "xheaders_write", 0)
# 读取并删除X-Siptrace-*头, 默认0
modparam("siptrace", "xheaders_read", 0)
# HEP模式
modparam("siptrace", "hep_mode_on", 1)
# HEP版本
modparam("siptrace", "hep_version", 3)
# 区分capture agent id,用在HEPv2和HEPv3中
modparam("siptrace", "hep_capture_id", 234)
# 存储到数据库的方式,默认0. 1,"INSERT DELAYED";2,"ASYNC-INSERT";0,"INSERT" 
modparam("siptrace", "trace_db_mode", 1)
# 本地发送trace的SIP URL地址
modparam("siptrace", "send_sock_addr", "sip:10.1.1.2:5000")
#控制追踪的模式,默认0,0,所有模块都初始化;1,只有核心函数模块初始化;2,只有使用flags和functions的模块初始化
modparam("siptrace", "trace_init_mode", 1)
# 追踪模式,默认0,0,不自动镜像或者存储sip信息;1,镜像sip信息到HEP server;2,存储sip信息到数据库;3,镜像SIP消息到duplicate_uri
modparam("siptrace", "trace_mode", 3)
# 默认0, 1,使用外网ip发送sip消息
modparam("siptrace", "data_mode", 1)
# 追踪对话的ACK消息,默认1
modparam("siptrace", "trace_dialog_ack", 1)

重要函数

sip_trace([address][, correlation_id][, mode])

存储或者转发当前的SIP message/transaction/dialog到数据库,mode参数:

当前的message(’m')
当前的transaction(’t')
当前的dialog(’d')

sip_trace_mode(tmode)

设置追踪模式,tmode参数:

“m”/“M” message
“t”/“T” transaction
“d”/“D” dialog

sip_trace_msg(vmsg, saddr, taddr, daddr, corrid)

发送vmsg到 HEP server(daddr), 设置saddr为源地址, taddr为目的地址, corrid为correlation_id。

saddr和taddr为proto:ip:port, daddr为:sip:ip:port

hlog([correlation_id,] message)

发送log事件到HEP3 server

实战

存储到数据库

记录所有：

1
2
3
4


loadmodule "siptrace.so"
modparam("siptrace", "db_url", DBURL)
modparam("siptrace", "trace_on", 1)
modparam("siptrace", "trace_mode", 2)

不需要调用sip_trace(), 所有的信息都能存储到数据表sip_trace中. trace

可以看到,REGISTER, INVITE, BYE等SIP消息都能存储到数据库中,还有direction 字段, 表示当前SIP消息是in还是out. wss也能记录到数据库中。

但是这种记录所有的信息,太频繁了,sip_trace表还得分表, 影响性能。接下来介绍如何只记录指定的SIP消息。

记录指定的SIP消息

追踪所有的,过滤掉不想要的SIP消息

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


loadmodule "siptrace.so"
modparam("siptrace", "db_url", DBURL)
modparam("siptrace", "trace_on", 1)
modparam("siptrace", "trace_mode", 2)
...
event_route[siptrace:msg] {
    if(is_method("OPTIONS")|| is_method("REGISTER")) {
        drop();
    }
}

数据库可以看到REGISTER没被记录到数据库中.

追踪指定的SIP消息

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


loadmodule "siptrace.so"
modparam("siptrace", "db_url", DBURL)
modparam("siptrace", "traced_user_avp", "$avp(user)")
modparam("siptrace", "trace_on", 1)
modparam("siptrace", "trace_init_mode", 0)
...
request_route{
    ...
    route(WITHINDLG);
    ...
    if (is_method("INVITE") && !has_totag()) {
        dlg_manage();
        sip_trace_mode("t");
        sip_trace();
    }
}
route[WITHINDLG] {
    if (!has_totag()) return;
    sip_trace_mode("t");
    ...
}

记录会话的SIP消息: trace

使用sip_trace_mode("d")报错failed to serialize siptrace info! Won't trace dialog!, 数据库中只记录INVITE其他的信令没有,已提issue解答。

注意: trace_mode不要设置成2,不然还是存所有的SIP信息,sip_trace_mode("d")就没有用.

发送到HEP server

hep server

本次的hep server使用的是:hep-connect

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


docker run -d  -p 9060:9060/udp --restart=always \
-e TZ=Asia/Shanghai \
-e LogLevel=debug \
-e DBAddr="172.16.4.111" \
-e DBName="postgres" \
-e DBUser="postgres" \
-e DBPort="5432" \
-e DBPasswd="123456" \
-e MaxBatchItems="100" \
--name hep-connect \
eddiemurphy5/hep-connect:latest

kamailio配置

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


listen=udp:172.16.4.113:5461
# 加载siptrace
loadmodule "siptrace.so"

# hep-connect地址
modparam("siptrace", "duplicate_uri", "sip:172.16.4.111:9060")

# Kamailio本地监听端口, 对应了listen=udp:172.16.4.113:5461
modparam("siptrace", "send_sock_addr", "sip:172.16.4.113:5461")

modparam("siptrace", "hep_mode_on", 1)
modparam("siptrace", "hep_version", 3)
modparam("siptrace", "trace_to_database", 0)
modparam("siptrace", "trace_on", 1)
...
request_route {
    ...
    route(WITHINDLG);
    ...
    if (is_method("INVITE") && !has_totag()) {
        dlg_manage();
        sip_trace_mode("t");
    }
}

route[WITHINDLG] {
        if (!has_totag()) return;
        sip_trace_mode("t");
        ...
}

说明几点配置问题:

trace_to_database要设置成0,不然需要配置数据库
sip_trace_mode() 要设置成t,如果设置成d,会报错failed to serialize siptrace info! Won't trace dialog!,目前暂未成功使用过d.
sip_trace_mode("t"), 如果想要跟踪完整的会话信令，并不是收到INVITE设置一次就可以了,还要在has_totag()里再设置一次, 否则只能跟踪200OK之前的信令，接通之后的BYE,ACK都不会跟踪到。
sip_trace_mode("t")设置之后还可以再设置sip_trace(),效果是一样的。

测试效果完整的记录：
HEP 以tcp的方式发送

1
2
3
4
5


listen=tcp:172.16.4.113:5461
# hep-connect地址
modparam("siptrace", "duplicate_uri", "sip:172.16.4.111:9060;transport=tcp")
# Kamailio本地监听端口, 对应了listen=tcp:172.16.4.113:5461
modparam("siptrace", "send_sock_addr", "sip:172.16.4.113:5461;transport=tcp")

其他的配置和上面的一样, HEPv3默认使用的是tcp协议, 需要在duplicate_uri和send_sock_addr中添加;transport=tcp 虽然listen监听的是tcp:5461,但是因为kamailio是客户端,所以其发出去的tcp端口是随机的,但是kamailio还是要检查你是否监听了5461端口

说明:hep-connect目前只支持HEPv3 udp方式，我测试使用自己修改的方式接收数据的。