Debian Codegraph @

src/modules/sipdump/README

raw
1 SIPDUMP Module
2
3 Daniel-Constantin Mierla
4
5 <[email protected]>
6
7 Edited by
8
9 Daniel-Constantin Mierla
10
11 <[email protected]>
12
13 Copyright © 2017 asipto.com
14 __________________________________________________________________
15
16 Table of Contents
17
18 1. Admin Guide
19
20 1. Overview
21 2. Dependencies
22
23 2.1. Kamailio Modules
24 2.2. External Libraries or Applications
25
26 3. Parameters
27
28 3.1. enable (int)
29 3.2. mode (int)
30 3.3. wait (int)
31 3.4. wait_mode (int)
32 3.5. rotate (int)
33 3.6. folder (str)
34 3.7. fprefix (str)
35 3.8. fage (int)
36 3.9. fagex (str)
37 3.10. event_callback (str)
38
39 4. Functions
40
41 4.1. sipdump_send(tag)
42
43 5. RPC Commands
44
45 5.1. sipdump.enable
46
47 6. Event Routes
48
49 6.1. sipdump:msg
50
51 7. Usage Remarks
52
53 List of Examples
54
55 1.1. Set enable parameter
56 1.2. Set mode parameter
57 1.3. Set wait parameter
58 1.4. Set wait_mode parameter
59 1.5. Set rotate parameter
60 1.6. Set folder parameter
61 1.7. Set fprefix parameter
62 1.8. Set fage parameter
63 1.9. Set fagex parameter
64 1.10. Set event_callback parameter
65 1.11. sipdump_send usage
66 1.12. sipdump.enable usage
67
68 Chapter 1. Admin Guide
69
70 Table of Contents
71
72 1. Overview
73 2. Dependencies
74
75 2.1. Kamailio Modules
76 2.2. External Libraries or Applications
77
78 3. Parameters
79
80 3.1. enable (int)
81 3.2. mode (int)
82 3.3. wait (int)
83 3.4. wait_mode (int)
84 3.5. rotate (int)
85 3.6. folder (str)
86 3.7. fprefix (str)
87 3.8. fage (int)
88 3.9. fagex (str)
89 3.10. event_callback (str)
90
91 4. Functions
92
93 4.1. sipdump_send(tag)
94
95 5. RPC Commands
96
97 5.1. sipdump.enable
98
99 6. Event Routes
100
101 6.1. sipdump:msg
102
103 7. Usage Remarks
104
105 1. Overview
106
107 This module writes SIP traffic and some associated details into local
108 files. It intercepts automatically all the SIP traffic received or sent
109 by Kamailio and provides a function to trigger storage from
110 configuration file.
111
112 Received traffic has the tag 'rcv' and the one to be sent has the tag
113 'snd'. The tag value is provided as parameter for the config function.
114
115 Besides the SIP packets, the module aims to save details related to
116 Kamailio runtime environment that are useful for troubleshooting, like
117 process id, child rank, a.s.o.
118
119 The module should be useful for troubleshooting during development or
120 testing of new deployments, especially when dealing with traffic over
121 TLS with forward privacy, when other tools such as wireshark cannot
122 decrypt. For production environments with a lot of SIP traffic, look at
123 siptrace and sipcapture modules for a scalable alternative to capture
124 all the SIP traffic and then search using Homer Sipcapture web toolkit.
125
126 2. Dependencies
127
128 2.1. Kamailio Modules
129 2.2. External Libraries or Applications
130
131 2.1. Kamailio Modules
132
133 The following modules must be loaded before this module:
134 * none.
135
136 2.2. External Libraries or Applications
137
138 The following libraries or applications must be installed before
139 running Kamailio with this module loaded:
140 * none
141
142 3. Parameters
143
144 3.1. enable (int)
145 3.2. mode (int)
146 3.3. wait (int)
147 3.4. wait_mode (int)
148 3.5. rotate (int)
149 3.6. folder (str)
150 3.7. fprefix (str)
151 3.8. fage (int)
152 3.9. fagex (str)
153 3.10. event_callback (str)
154
155 3.1. enable (int)
156
157 Enable sipdump activity.
158
159 Default value is 0 (0 - off; 1 - on).
160
161 Example 1.1. Set enable parameter
162 ...
163 modparam("sipdump", "enable", 1)
164 ...
165
166 3.2. mode (int)
167
168 Set the type of activity done by the module, the value can be set based
169 on flags index: 0 (value 1) - write to text files; 1 (value 2) -
170 execute event route; 2 (value 4) - write to pcap files; 3 (value 8) -
171 insert the P-KSR-SIPDump header with meta data inside the SIP message
172 written in pcap file.
173
174 To enable several activity modes, set the parameter to the sum of
175 corresponding values.
176
177 Default value is 1 (write to text files).
178
179 Example 1.2. Set mode parameter
180 ...
181 modparam("sipdump", "mode", 3)
182 ...
183
184 3.3. wait (int)
185
186 Wait time (microseconds) when no SIP traffic is received (for wait_time
187 = 0).
188
189 Default value is 100.
190
191 Example 1.3. Set wait parameter
192 ...
193 modparam("sipdump", "wait", 2000)
194 ...
195
196 3.4. wait_mode (int)
197
198 If set to 1, the module uses a pthread mutex and contion to signal when
199 SIP messages are available to the writer process. It should use less
200 CPU when idle (on no SIP traffic) than the default polling on timer,
201 but be sure that the OS supports process-shared pthread mutexes and
202 conditions (latest Linux distros have support for them).
203
204 Default value is 0.
205
206 Example 1.4. Set wait_mode parameter
207 ...
208 modparam("sipdump", "wait_mode", 1)
209 ...
210
211 3.5. rotate (int)
212
213 Time interval in seconds to rotate files.
214
215 Default value is 7200 (2 hours).
216
217 Example 1.5. Set rotate parameter
218 ...
219 modparam("sipdump", "rotate", 3600)
220 ...
221
222 3.6. folder (str)
223
224 Path to the folder where to save the files.
225
226 Default value is "/tmp".
227
228 Example 1.6. Set folder parameter
229 ...
230 modparam("sipdump", "folder", "/run/kamailio")
231 ...
232
233 3.7. fprefix (str)
234
235 File name prefix. The date is appended to this prefix in the format
236 yyyy-mm-dd--hh-mm-ss. The extension of the text file is ".data", of the
237 meta file is ".meta" and of the pcap file is ".pcap".
238
239 Default value is "kamailio-sipdump-".
240
241 Example 1.7. Set fprefix parameter
242 ...
243 modparam("sipdump", "fprefix", "ksipdump-")
244 ...
245
246 3.8. fage (int)
247
248 Age of created files (in seconds) to be removed if they become older.
249 Cleanup is done on a timer routine running every 600 seconds.
250
251 Default value is 0 (no cleanup of created files).
252
253 Example 1.8. Set fage parameter
254 ...
255 # cleanup files older than two days
256 modparam("sipdump", "fage", 172800)
257 ...
258
259 3.9. fagex (str)
260
261 Age as a time expression for the created files to be removed if they
262 become older. It overwrites the 'fage' parameter. The value can be
263 numbers followed by time units: d - days; h - hours; m - minutes; s -
264 seconds.
265
266 Default value is empty (no cleanup of created files).
267
268 Example 1.9. Set fagex parameter
269 ...
270 # cleanup files older than 2 days
271 modparam("sipdump", "fagex", "2d")
272
273 # cleanup files older than 2 days, 6 hours, 40 minutes and 30 seconds
274 modparam("sipdump", "fagex", "2d6h40m30s")
275 ...
276
277 3.10. event_callback (str)
278
279 Name of the KEMI function to be executed instead of the event route.
280
281 Default value is not set.
282
283 Example 1.10. Set event_callback parameter
284 ...
285 modparam("sipdump", "event_callback", "ksr_sipdump_event")
286 ...
287 -- event callback function implemented in Lua
288 function ksr_sipdump_event(evname)
289 KSR.info("===== sipdump module triggered event: " .. evname .. "\n");
290 return 1;
291 end
292 ...
293
294 4. Functions
295
296 4.1. sipdump_send(tag)
297
298 4.1. sipdump_send(tag)
299
300 Send the details of the current SIP message to the writer process and
301 get it stored in the file.
302
303 The parameter "tag" can be any string, it is going to be written in the
304 tag attribute inside the storage file.
305
306 This function can be used from ANY_ROUTE.
307
308 Example 1.11. sipdump_send usage
309 ...
310 sipdump_send("cfg");
311 ...
312
313 5. RPC Commands
314
315 5.1. sipdump.enable
316
317 5.1. sipdump.enable
318
319 Control the value for "enable" parameter.
320
321 If no value is provided to this command, the value of "enable"
322 parameter is returned.
323
324 This function can be used from ANY_ROUTE.
325
326 Example 1.12. sipdump.enable usage
327 ...
328 kamctl rpc sipdump.enable
329 kamctl rpc sipdump.enable 1
330 kamctl rpc sipdump.enable 0
331 ...
332
333 6. Event Routes
334
335 6.1. sipdump:msg
336
337 6.1. sipdump:msg
338
339 Executed when sipdump handles messages and mode parameter has flag 2
340 set. The variable $sipdump(...) is available inside the event route.
341
342 If drop() is used in event_route, then writing to file is no longer
343 done when mode parameter has also the flag 1 set.
344 ...
345 event_route[sipdump:msg] {
346 xinfo("[$sipdump(tag)] [[$sipdump(buf)]]\n");
347 }
348 ...
349
350 7. Usage Remarks
351
352 Note that the files with the SIP traffic and metadata are not deleted
353 by the module itself. They have to be deleted explicitely by other
354 means, such as cron.d job, or using rtimer and exec modules. Next
355 examples shows how to delete the files older than 2 days using Kamailio
356 modules.
357 ...
358 loadmodule "rtimer.so"
359 loadmodule "exec.so"
360 ...
361 modparam("rtimer", "timer", "name=tjobs;interval=300;mode=1;")
362 modparam("rtimer", "exec", "timer=tjobs;route=TCLEAN")
363 ...
364 route[TCLEAN] {
365 exec_cmd("find /tmp -type f -name kamailio-sipdump-* -mtime +2 -delete &");
366 }
367 ...
368
369 If operational mode is set to write the pcap files, note that packets
370 in the pcap file are generated always with transport UDP, no matter the
371 SIP traffic was over another transport layer like TCP, TLS, SCTP or
372 WSS. The headers of the SIP message (e.g., Via, Route) should provide
373 hints about what the SIP transport layer.