/
README
414 lines (325 loc) · 14 KB
/
README
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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
SipTrace Module
__________________________________________________________
Table of Contents
1. Admin Guide
1.1. Overview
1.2. Dependencies
1.2.1. OpenSIPS Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. trace_on (integer)
1.3.2. trace_local_ip (str)
1.3.3. trace_id (str)
1.4. Exported Functions
1.4.1. sip_trace(trace_id, [type, [trace_attrs]])
1.5. Exported MI Functions
1.5.1. sip_trace
1.6. Database setup
1.7. Known issues
2. Contributors
2.1. By Commit Statistics
2.2. By Commit Activity
3. Documentation
3.1. Contributors
List of Tables
2.1. Top contributors by DevScore^(1), authored commits^(2) and
lines added/removed^(3)
2.2. Most recently active contributors^(1) to this module
List of Examples
1.1. Set trace_on parameter
1.2. Set trace_local_ip parameter
1.3. Set trace_id parameter
1.4. sip_trace() usage
Chapter 1. Admin Guide
1.1. Overview
Offer a possibility to store incoming/outgoing SIP messages in
database. Since version 2.2, proto_hep module needs to be
loaded in order to duplicate with hep. All hep parameters moved
inside proto_hep.
The 2.2 version of OpenSIPS came with a major improvement in
siptrace module. Now all you have to do is call sip_trace()
function with the proper parameters and it will do the job for
you. Now you can trace messages, transactions and dialogs with
the same function. Also, you can trace to multiple databases,
multiple hep destinations and sip destinations using only one
parameter. All you need now is defining trace_id parameters in
modparam section and switch between them in siptrace function.
Also you cand turn tracing on and off using trace_on either
globally(for all trace_ids) or for a certain trace_id.
IMPORTANT: In 2.2 version support for stateless trace has been
removed.
The tracing tracing can be turned on/off using fifo command.
opensipsctl fifo sip_trace on opensipsctl fifo sip_trace
[some_trace_id] on
opensipsctl fifo sip_trace off opensipsctl fifo sip_trace
[some_trace_id] off
1.2. Dependencies
1.2.1. OpenSIPS Modules
The following modules must be loaded before this module:
* database module - mysql, postrgress, dbtext, unixodbc...
only if you are using a database type trace id
* dialog - only if you want to trace dialogs.
* tm - only if you want to trace dialogs/transactions.
* proto_hep - only if you want to replicate messages over
hep.
1.2.2. External Libraries or Applications
The following libraries or applications must be installed
before running OpenSIPS with this module loaded:
* None.
1.3. Exported Parameters
1.3.1. trace_on (integer)
Parameter to enable/disable trace (on(1)/off(0))
Default value is "1"(enabled).
Example 1.1. Set trace_on parameter
...
modparam("siptrace", "trace_on", 1)
...
1.3.2. trace_local_ip (str)
The address to be used in the fields that specify the source
address (protocol, ip and port) for locally generated messages.
If not set, the module sets it to the address of the socket
that will be used to send the message. Protocol and/or port are
optional and if omitted will take the default values: udp and
5060.
Default value is "NULL".
Example 1.2. Set trace_local_ip parameter
...
#Resulting address: udp:10.1.1.1:5064
modparam("siptrace", "trace_local_ip", "10.1.1.1:5064")
...
...
#Resulting address: tcp:10.1.1.1:5060
modparam("siptrace, "trace_local_ip", "tcp:10.1.1.1")
...
...
#Resulting address: tcp:10.1.1.1:5064
modparam("siptrace", "trace_local_ip", "tcp:10.1.1.1:5064")
...
...
#Resulting address: udp:10.1.1.1:5060
modparam("siptrace", "trace_local_ip", "10.1.1.1")
...
1.3.3. trace_id (str)
Specify a destination for the trace. This can be a hep uri, sip
uri or a database url and a table. All parameters inside
trace_id must be separated by ;. The parameters are given in
key-value format, the possible keys being uri for HEP and SIP
IDs and uri and table for databases. The format is
[id_name]key1=value1;key2=value2;. HEP uris must be specified
as hep:host:port.
One can declare multiple types of tracing under the same trace
id, being identified by their name. So if you define two
database url, one hep uri and one sip uri with the same name,
when calling sip_trace() with this name tracing shall be done
to all the destinations.
All the old parameter such as db_url, table and duplicate_uri
will form the trace id with the name "default".
No default value. If not set the module will be useless. For
HEP ids, if transport parameter is not set default will be TCP
for version 3 and UDP for 1 and 2. Also if version not set,
version 3 will be used by default.
Example 1.3. Set trace_id parameter
...
/*DB trace id*/
modparam("siptrace", "trace_id",
"[tid]
uri=mysql://xxxx:xxxx@10.10.10.10/opensips;
table=new_sip_trace;")
/*hep trace id*/
modparam("siptrace", "trace_id",
"[tid]uri=hep:10.10.10.10:6161;")
/*sip trace id*/
modparam("siptrace", "trace_id",
"[tid]uri=sip:10.10.10.11:5060;")
/* notice that they all have the same name
* meaning that calling sip_trace("tid",...)
* will do sql, sip and hep tracing */
/* hep version 3 with tcp - ALSO DEFAULT ONE */
modparam("siptrace", "trace_id",
"[tid]uri=hep:10.10.10.12:5061;transport=tcp;version=3;")
/* hep version 3 with udp (version not set-default will be 3)*/
modparam("siptrace", "trace_id",
"[tid]uri=hep:10.10.10.12:5061;transport=udp;")
/* hep version 1 */
modparam("siptrace", "trace_id",
"[tid]uri=hep:10.10.10.12:5061;version=1;")
...
1.4. Exported Functions
1.4.1. sip_trace(trace_id, [type, [trace_attrs]])
Store or replocate current processed SIP message,transaction or
dialogin database. It is stored in the form prior applying
chages made to it. The traced_user_avp parameter is now an
argument to sip_trace() function. Since version 2.2,
sip_trace() also catches internally generated replies in
stateless mode(sl_send_reply(...)).
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
ONREPLY_ROUTE, BRANCH_ROUTE.
Meaning of the parameters is as follows:
* trace_id (string, pvar) the name of the trace_id specifying
where to do the tracing.
* type (string) what do you want to trace: dialog,
transaction or only the message. If not specified, will try
the topmost trace that can be done: if dialog module loaded
will trace dialogs, else if tm module loaded will trace
transaction and if none of these loaded will trace
messages.
Types can be the following:
+ 'm'/'M' trace messages. Is the only one you should use
in stateless mode.
+ 't'/'T' trace transactions. If tm module not loaded,
it will be in stateless transaction aware mode meaning
that will catch selected requests both in and out and
internally generated replies.
+ 'd'/'D' trace dialog
* trace_attrs (string,pvar) this parameter replaces the
traced_user_avp from the old version. To avoid duplicating
an entry only for this parameter, whatever you put
here(string/pvar) shall be stored in the trace_attrs column
in the sip_trace table.
Example 1.4. sip_trace() usage
...
/* see declaration of tid in trace_id section */
$var(trace_id) = "tid";
$var(user) = "osip_user@opensips.org";
...
/* Example 1: how to trace a dialog */
if (has_totag()) {
match_dialog();
} else {
if (is_method("INVITE") {
sip_trace("$var(trace_id)", "d", "$var(user)");
}
}
...
/* Example 2: how to trace initial INVITE and BYE */
if (has_totag()) {
if (is_method("BYE")) {
sip_trace("$var(trace_id)", "m", "$var(user)");
}
} else {
if (is_method("INVITE")) {
sip_trace("$var(trace_id)", "m", "$var(user)");
}
}
...
/* Example 3: trace initial INVITE transaction */
if (!has_totag()) {
if (is_method("INVITE")) {
sip_trace("$var(trace_id)", "t", "$var(user)");
}
}
...
/* Example 4: stateless transaction aware mode!*/
/* tm module must not be loaded */
if (is_method("REGISTER")) {
sip_trace("$var(trace_id)", "t", "$var(user)");
if (!www_authorize("", "subscriber")) {
/* siptrace will also catch the 401 generated by
www_challenge() */
www_challenge("", "1");
}
}
1.5. Exported MI Functions
1.5.1. sip_trace
Name: sip_trace
Parameters:
* trace_id/trace_mode : if it is a trace_id name it dumps
info about that trace id if the second parameter is not set
to on/off or it turns tracing on/off for a certain trace id
if it is set, else if it's on/off it turns on/off tracing
for all the trace ids. If you turn global trace on but some
of the trace ids had trace to off, then they shall not do
tracing. In order to do that you have to set the trace_on
parameter for each trace_id. Possible values are:
+ on
+ off
+ trace_id name
The parameter is optional - if missing, the command will
return the status of the SIP message tracing (as string
“on” or “off”) marked with global and the status for each
trace id without changing anything.
* trace_mode : this parameter has the same meaning as the
trace_mode in the first parameter, but this time it
enables/disables tracing for a certain trace id given in
the first parameter.
MI FIFO Command Format:
:sip_trace:_reply_fifo_file_
trace_id/trace_mode
trace_mode
_empty_line_
1.6. Database setup
Before running OpenSIPS with siptrace, you have to setup the
database tables where the module will store the data. For that,
if the table were not created by the installation script or you
choose to install everything by yourself you can use the
siptrace-create.sql SQL script in the database directories in
the opensips/scripts folder as template. You can also find the
complete database documentation on the project webpage,
http://www.opensips.org/html/docs/db/db-schema-devel.html.
1.7. Known issues
ACKs related to a transaction that are leaving OpenSIPS are not
traced since they are handled statelessly using forward_request
function. Fixing it would mean to register a fwdcb callback
that would be called for all the messages but would be used
only by ACKs, which would be highly ineffective.
Chapter 2. Contributors
2.1. By Commit Statistics
Table 2.1. Top contributors by DevScore^(1), authored
commits^(2) and lines added/removed^(3)
Name DevScore Commits Lines ++ Lines --
1. Bogdan-Andrei Iancu (@bogdan-iancu) 76 60 650 542
2. Ionut Ionita (@ionutrazvanionita) 65 24 1856 1420
3. Daniel-Constantin Mierla (@miconda) 48 26 2215 191
4. Vlad Paiu (@vladpaiu) 21 8 335 528
5. Razvan Crainea (@razvancrainea) 19 16 124 85
6. Liviu Chircu (@liviuchircu) 14 12 61 46
7. Henning Westerholt (@henningw) 11 6 146 155
8. Andrei Datcu (@andrei-datcu) 11 5 284 135
9. Alexandr Dubovikov (@adubovikov) 6 1 500 4
10. Dusan Klinec 4 2 8 4
All remaining contributors: Andreas Heise, Sergio Gutierrez,
Vlad Patrascu (@rvlad-patrascu), Dan Pascu (@danpascu),
Konstantin Bokarius, Iouri Kharon, Edson Gellert Schubert,
Elena-Ramona Modroiu, Stephane Alnet.
(1) DevScore = author_commits + author_lines_added /
(project_lines_added / project_commits) + author_lines_deleted
/ (project_lines_deleted / project_commits)
(2) including any documentation-related commits, excluding
merge commits. Regarding imported patches/code, we do our best
to count the work on behalf of the proper owner, as per the
"fix_authors" and "mod_renames" arrays in
opensips/doc/build-contrib.sh. If you identify any
patches/commits which do not get properly attributed to you,
please submit a pull request which extends "fix_authors" and/or
"mod_renames".
(3) ignoring whitespace edits, renamed files and auto-generated
files
2.2. By Commit Activity
Table 2.2. Most recently active contributors^(1) to this module
Name Commit Activity
1. Liviu Chircu (@liviuchircu) Jan 2013 - Oct 2018
2. Bogdan-Andrei Iancu (@bogdan-iancu) Jul 2006 - Jun 2018
3. Razvan Crainea (@razvancrainea) Jun 2011 - Sep 2017
4. Vlad Patrascu (@rvlad-patrascu) Aug 2017 - Aug 2017
5. Ionut Ionita (@ionutrazvanionita) Nov 2014 - Feb 2017
6. Stephane Alnet Nov 2016 - Nov 2016
7. Dusan Klinec Dec 2015 - Dec 2015
8. Andrei Datcu (@andrei-datcu) Jun 2014 - Jul 2014
9. Vlad Paiu (@vladpaiu) Jun 2011 - Nov 2013
10. Alexandr Dubovikov (@adubovikov) Nov 2011 - Nov 2011
All remaining contributors: Sergio Gutierrez, Dan Pascu
(@danpascu), Daniel-Constantin Mierla (@miconda), Iouri Kharon,
Konstantin Bokarius, Edson Gellert Schubert, Henning Westerholt
(@henningw), Andreas Heise, Elena-Ramona Modroiu.
(1) including any documentation-related commits, excluding
merge commits
Chapter 3. Documentation
3.1. Contributors
Last edited by: Liviu Chircu (@liviuchircu), Bogdan-Andrei
Iancu (@bogdan-iancu), Ionut Ionita (@ionutrazvanionita),
Andrei Datcu (@andrei-datcu), Razvan Crainea (@razvancrainea),
Alexandr Dubovikov (@adubovikov), Daniel-Constantin Mierla
(@miconda), Konstantin Bokarius, Edson Gellert Schubert,
Henning Westerholt (@henningw), Elena-Ramona Modroiu.
doc copyrights:
Copyright © 2006 Voice Sistem SRL