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
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
|
The Iptrtpproxy module
Tomas Mandys
Iptel.org
Copyright 2007 Tomas Mandys
_________________________________________________________________
Table of Contents
1. Admin Guide
1. Overview
2. Dependencies
3. Parameters
3.1. config (string)
3.2. switchboard (string)
3.3. rpc_heartbeat_timeout (int)
3.4. hostname (string)
3.5. declare_codec (string)
3.6. codec_set (string)
4. Functions
4.1. iptrtpproxy_alloc(gate_a_to_b [, existing_sess_ids])
4.2. iptrtpproxy_update(gate_a_to_b, session_ids)
4.3. iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)
4.4. iptrtpproxy_delete(session_ids)
4.5. iptrtpproxy_authorize_media()
4.6. iptrtpproxy_set_param(param, value)
4.7.
iptrtpproxy_set_param("(aggregation/switchboard)_by_sip
_ip_(a/b)", sip_ip)
4.8. iptrtpproxy_set_param("protected_session_ids",
sess_ids)
4.9. iptrtpproxy_set_param("o_name", value)
4.10. iptrtpproxy_set_param("o_addr", value)
4.11. iptrtpproxy_set_param("codec_set", value)
4.12. iptrtpproxy_set_param("remove_codec_mask", value)
5. Selects
5.1. @iptrtpproxy.session_ids
5.2. @iptrtpproxy.sdp_ip
5.3. @iptrtpproxy.o_name
5.4. @iptrtpproxy.o_addr
5.5. @iptrtpproxy.auth_rights
5.6. @iptrtpproxy.active_media_num
List of Examples
1.1. Declare switchboard
1.2. Declare codec_set
1.3. iptrtpproxy_alloc usage
1.4. iptrtpproxy_update usage
1.5. iptrtpproxy_adjust_timeout usage
1.6. iptrtpproxy_delete usage
1.7. iptrtpproxy_authorize_media usage
Chapter 1. Admin Guide
Table of Contents
1. Overview
2. Dependencies
3. Parameters
3.1. config (string)
3.2. switchboard (string)
3.3. rpc_heartbeat_timeout (int)
3.4. hostname (string)
3.5. declare_codec (string)
3.6. codec_set (string)
4. Functions
4.1. iptrtpproxy_alloc(gate_a_to_b [, existing_sess_ids])
4.2. iptrtpproxy_update(gate_a_to_b, session_ids)
4.3. iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)
4.4. iptrtpproxy_delete(session_ids)
4.5. iptrtpproxy_authorize_media()
4.6. iptrtpproxy_set_param(param, value)
4.7.
iptrtpproxy_set_param("(aggregation/switchboard)_by_sip_ip_(a
/b)", sip_ip)
4.8. iptrtpproxy_set_param("protected_session_ids", sess_ids)
4.9. iptrtpproxy_set_param("o_name", value)
4.10. iptrtpproxy_set_param("o_addr", value)
4.11. iptrtpproxy_set_param("codec_set", value)
4.12. iptrtpproxy_set_param("remove_codec_mask", value)
5. Selects
5.1. @iptrtpproxy.session_ids
5.2. @iptrtpproxy.sdp_ip
5.3. @iptrtpproxy.o_name
5.4. @iptrtpproxy.o_addr
5.5. @iptrtpproxy.auth_rights
5.6. @iptrtpproxy.active_media_num
1. Overview
This module provides similar functionality as nathelper but
communicates with netfilter kernel xt_RTPPROXY module using the
libipt_RTPPROXY userspace library. All RTP streams are manipulated
directly in kernel space, no data is copied from kernel to userspace
and back, it reduces load and delay. See
http://www.2p.cz/en/netfilter_rtp_proxy for more details.
This Kamailio module is written as a light-weight module, there is no
dialog managment as in Nathelper. The reason is that such an API
should be provided by core or a specialized dialog manager module.
Because such module is not in git, session information may be stored
in extra attributes of the avp_db module and the session id itself in
record route as cookie, see the rr module.
It should be able to support all cases as re-invites when SIP client
offers media change in SDP and when number of medias in offer/answer
are different.
Nathelper may be still used for testing if client is behind the NAT.
There is also support for media authorization. Number of codec sets
may be defined. When a message containing SDP offer/answer is being
processed then current codecs and streams may be inspected, removed or
signallized according a codec set.
Limitations:
* Only IPv4 addresses are supported.
* More media streams per session supported
2. Dependencies
The following libraries or applications must be installed before
running Kamailio with this module loaded:
* netfilter xt_RTPPROXY & libipt_RTPPROXY, see
http://www.2p.cz/en/netfilter_rtp_proxy
Note
The modules Makefile must be edited and iptdir setup to the directory
with the iptable sources (if different from ~/iptables). Alternatively
compile the module using:
make -C modules/iptrtpproxy iptdir=path_to_iptables_src
3. Parameters
3.1. config (string)
3.2. switchboard (string)
3.3. rpc_heartbeat_timeout (int)
3.4. hostname (string)
3.5. declare_codec (string)
3.6. codec_set (string)
3.1. config (string)
References iptrtpproxy.cfg, see iptrtpproxy_helper. Default value is
/etc/iptrtpproxy.cfg. If only codec authorization is to be used then
/dev/null may be used.
3.2. switchboard (string)
References xt_RTPPROXY switchboard for usage by ser module.
The format is:
"name=" value * ( ";" name "=" value )
name = "aggregation" | "sip-addr-"
The name is the switchboard name as declared in config and will be
used by script functions and references switchboard. It's mandatory
parameter. The special name * set values for all switchboards.
The sip-addr is address used by iptrtpproxy_ser_param(by_sip_ip) to
find a switchboard for particular connection. If not explicitly
configured then RTP switchboard gate address are used for this
feature.
The aggregation enables to aggregate more switchboards in cluster and
to widden bandwidth. Aggregation will take sip-addr from the first
switchboard of its.
Example 1.1. Declare switchboard
...
modparam("iptrtpproxy", "config", "/etc/iptrtpproxy.cfg");
modparam("iptrtpproxy", "switchboard", "name=my1;sip-addr-a=1.2.3.4;sip
-addr-b=5.6.7.8");
modparam("iptrtpproxy", "switchboard", "name=my2;sip-addr-a=2.3.4.5;sip
-addr-b=3.4.5.6;aggregation=my23");
modparam("iptrtpproxy", "switchboard", "name=my3;aggregation=my23");
modparam("iptrtpproxy", "switchboard", "name=*;aggregation=my123");
...
3.3. rpc_heartbeat_timeout (int)
Timeout in seconds used for rerequest remote RTP proxy via RPC command
after preceeding error. In other words if a RPC server is unresponsive
at the moment then next attempt will be forced after this timeout.
Default value is 30.
3.4. hostname (string)
The hostname used by RPC to identify machine where Ser is running to
communicate which RTP proxy via local interface. Default value is
taken from system hostname.
3.5. declare_codec (string)
There are basic implicit codecs compiled in module, more codecs may be
added by this parameter (one codec per modparam).
3.6. codec_set (string)
Declares new codec set. Codecs are declared for each media type
independently.
The format is:
"name=" value * ( ";" name "=" value )
name = "media_type" | "rights" | "codecs" | "max_streams" | ( "rtp" | "rtcp"
) "_" ( "bytes" | "packets" )
media_types = "audio" | "video" | "application" | "text" | "message" | "data"
| "control" | "?" | "*"
The name is the codec set name to be defined.
The media_type belongs to type at m= SDP line. Question mark means
"unknown media" type and asterisk "all media types".
The max_streams defines how many streams (m= lines) is allowed per
media type.
The rights defines if particular codec is allowed 0, disallowed, i.e.
will be removed if bit AND operation with remove_codec_mask is
non-zero or its presence will be signallized by
@iptrtpproxy.auth_rights (any other value).
The codecs comma separated list of codecs. Previous media_type&rights
will be applied.
The rtp/rtcp_bytes/packets limits bandwidth per media_type (0 is
unlimited). It will override bandwidth limited by
iptrtpproxy_set_param("throttle_*").
Example 1.2. Declare codec_set
...
# enable all codecs, default state when codec is declared
modparam("iptrtpproxy", "codec_set", "name=cs1;media_type=*;max_streams
=9999;rights=0;codecs=*");
# allow only 2 audio and 1 video stream
modparam("iptrtpproxy", "codec_set", "name=cs2;media_type=*;max_streams
=0;media_type=audio;max_streams=2;media_type=video;max_streams=1");
# dtto, allow only a few audio and video codecs, GSM codec is allowed b
ut signallized
modparam("iptrtpproxy", "codec_set", "name=cs3;media_type=*;max_streams
=0;rights=1;codecs=*;media_type=audio;max_streams=2;rights=0;codecs=PCMU,G729,G
728,parityfec,telephone-events;rights=2;codecs=GSM;media_type=video;max_streams
=1;rights=0;codecs=jpeg,parityfec");
# limit max. bandwidth for video
modparam("iptrtpproxy", "codec_set", "name=cs4;media_type=video;rtp_byt
es=10000;rtcp_bytes=1000");
...
4. Functions
4.1. iptrtpproxy_alloc(gate_a_to_b [, existing_sess_ids])
4.2. iptrtpproxy_update(gate_a_to_b, session_ids)
4.3. iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)
4.4. iptrtpproxy_delete(session_ids)
4.5. iptrtpproxy_authorize_media()
4.6. iptrtpproxy_set_param(param, value)
4.7.
iptrtpproxy_set_param("(aggregation/switchboard)_by_sip_ip_(a/b)",
sip_ip)
4.8. iptrtpproxy_set_param("protected_session_ids", sess_ids)
4.9. iptrtpproxy_set_param("o_name", value)
4.10. iptrtpproxy_set_param("o_addr", value)
4.11. iptrtpproxy_set_param("codec_set", value)
4.12. iptrtpproxy_set_param("remove_codec_mask", value)
4.1. iptrtpproxy_alloc(gate_a_to_b [, existing_sess_ids])
Parses SDP content and allocates for each RTP media stream one RTP
proxy session. SDP is updates to reflect allocated sessions.
Switchboard/aggregation is set using iptrtpproxy_set_param(by_sip_ip)
or iptrtpproxy_set_param("switchboard/aggregation").
Aggregation supports load balancing among more RTP proxies controlled
by RPC. The module try to allocate at machines/switchboards in
following order (priorities) not yet asked (or being heartbeated)
machines, responsive machines, switchboards having percentualy more
free slots, non responsive machines.
Proxy may hide caller identity provided at o= line using
@iptrtpproxy.o_name/addr and iptrtpproxy_set_param(o_name/addr)
functions. But the script is responsible for rewritting to original
values in a response or a callee initiated re-INVITE. Therefore
original value need to be stored in-dialog.
* if gate_a_to_b bit 0 is set then SDP regards to gate-a to gate-b
direction.
* protected_session_ids list of existing sessions enables reusing
already allocated sessions in re-INVITE without allocating new
sessions for each stream in SDP regardless a IP/port is required.
It's mostly undesirable, typically "hold-on" is done via re-INVITE
without any change. There is drawback because callee cannot change
IP:port in 200OK which is legal case in RFC3264. But because some
non-RFC3264 compliant phones dislike proactively changed IP:port
at RTP proxy it seems it's less evil.
* function returns true is a session was created, identifier is
available via select @iptrtpproxy.session_ids.
Example 1.3. iptrtpproxy_alloc usage
...
if (!iptrtpproxy_set_param("aggregation_by_sip_ip_a", "@received.ip"))
{
if (!iptrtpproxy_set_param("switchboard_by_sip_ip_a", "@receive
d.ip")) {
t_reply("500", "RTP proxy error");
drop;
}
}
eval_push("x:%@next_hop.src_ip");
if (@eval.get[-1] == @received.ip) {
if (@iptrtpproxy.aggregation_a) {
iptrtpproxy_set_param("aggregation_b", "@iptrtpproxy.ag
gregation_a");
}
else {
iptrtpproxy_set_param("switchboard_b", "@iptrtpproxy.sw
itchboard_a");
}
}
else {
if (!iptrtpproxy_set_param("aggregation_by_sip_ip_b", "@eval.ge
t[-1]")) {
if (!iptrtpproxy_set_param("switchboard_by_sip_ip_b", "
@eval.get[-1]")) {
t_reply("500", "RTP proxy error");
drop;
}
}
}
eval_remove(-1, 1);
if (!iptrtpproxy_alloc("1")) {
t_reply("500", "RTP proxy error");
drop;
}
$sess_ids = @iptrtpproxy.session_ids;
...
4.2. iptrtpproxy_update(gate_a_to_b, session_ids)
Parses SDP content and updates sessions provided by session_ids and
updates SDP. If succesfull then session_ids may be changed (in case
e.g. media stream has port zero particular session is released), the
result of @iptrtpproxy.session_ids should be stored for future
in-dialog usage.
The SDP contect is also affected by iptrtpproxy_set_param(o_name/addr)
functions. If a stream is deactivated in SDP then Sessions may be
deleted unless mentioned in protected_session_ids.
* if gate_a_to_b bit 0 is set then SDP regards to gate-a to gate-b
direction.
if gate_a_to_b bit 1 is set then SDP is updated only, no RTP
session are affected. Should be used when handling retransmission
in onreply route, retransmission replies are not eaten be tm
module!
Example 1.4. iptrtpproxy_update usage
...
# load $sess_ids from dialog
if (iptrtpproxy_update("0", $sess_ids)) {
$sess_ids = @iptrtpproxy.session_ids;
# save sess_ids in dialog
}
...
4.3. iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)
Adjust timeout for particular gate. It's useful in "200 OK" decrease
timeout to learning timeout if INVITE has set (long) ringing timeout.
* if gate_a_to_b bit 0 is set then it regards to gate-a to gate-b
direction.
Example 1.5. iptrtpproxy_adjust_timeout usage
...
# load $sess_ids from dialog
if (status=~"18[0-9]") {
iptrtpproxy_set_param("learning_timeout", "60");
}
else {
iptrtpproxy_set_param("learning_timeout", "5");
}
if (iptrtpproxy_adjust_timeout("0", $sess_ids)) {
}
...
4.4. iptrtpproxy_delete(session_ids)
Delete sessions identified by session_ids. May be used when dialog is
being destroyed (BYE) or when INVITE failed in failure route. If
protected_session_ids list is provided then this set is excluded from
sessions to be deleted.
Example 1.6. iptrtpproxy_delete usage
...
# load $sess_ids from dialog
iptrtpproxy_delete($sess_ids);
...
4.5. iptrtpproxy_authorize_media()
Authorizes SDP media according currect codec_set. If bit AND operation
between rights in codec set and remove_codec_mask is non zero then
such a codec are to be removed. The result may be obtained from
@iptrtpproxy.auth_rights which returns max. right which has been
applied when processing all codecs of enabled streams.
The function MUST NOT be called after iptrtpproxy_alloc/update! But
the function may be called several times to authorize using more codec
sets.
Example 1.7. iptrtpproxy_authorize_media usage
...
if (@iptrtpproxy.active_media_num == "0") break;
iptrtpproxy_set_param("codec_set", "cs2");
iptrtpproxy_set_param("remove_codec_mask", "1");
if (!iptrtpproxy_authorize_media()) {
t_reply("415", "Cannot authorize media");
drop;
}
iptrtpproxy_set_param("codec_set", "cs3");
if (!iptrtpproxy_authorize_media()) {
t_reply("415", "Cannot authorize media");
drop;
}
if (@iptrtpproxy.active_media_num == "0") {
t_reply("488", "Not acceptable here");
drop;
}
if (@iptrtpproxy.auth_rights == "2") {
append_hf_value("Contact: <sip:1.2.3.4>");
t_reply("301", "Redirect to transcoder");
drop;
}
...
4.6. iptrtpproxy_set_param(param, value)
Set particular parameter needed mainly by
iptrtpproxy_alloc/update/adjust_timeout. The paramter value is
availble via @iptrtpproxy.<param>.
* Supported parameters: expiration_timeout, ttl, learning_timeout,
always_learn, aggregation_a, aggregation_b, switchboard_a,
switchboard_b, throttle_mark, throttle_rtp_max_bytes,
throttle_rtp_max_packets, throttle_rtcp_max_bytes,
throttle_rtcp_max_packets.
4.7. iptrtpproxy_set_param("(aggregation/switchboard)_by_sip_ip_(a/b)",
sip_ip)
Find corresponding aggregation or switchboard and set
@iptrtpproxy.aggregation_a/b or @iptrtpproxy.switchboard_a/b.
Switchboards/aggregations are compared against sip-addr, it allow
separate SIP and RTP traffic and RTP aggregation.
* sip_ip IP to be compared, typically @received.ip or
@next_hop.src_ip.
* function returns true if switchboard/aggregation was found
4.8. iptrtpproxy_set_param("protected_session_ids", sess_ids)
Used for reusing sessions in iptrtpproxy_alloc, iptrtpproxy_update and
iptrtpproxy_delete.
4.9. iptrtpproxy_set_param("o_name", value)
Username to be rewritten at o= line by iptrtpproxy_alloc/update to
hide caller identity. If value is blank then username is left
unchanged.
4.10. iptrtpproxy_set_param("o_addr", value)
Address to be rewritten at o= line by iptrtpproxy_alloc/update to hide
caller identity. If value is blank then address is left unchanged.
4.11. iptrtpproxy_set_param("codec_set", value)
Codec set for iptrtpproxy_authorize_media. Current codec set may be
obtained by @iptrtpproxy.codec_set.
4.12. iptrtpproxy_set_param("remove_codec_mask", value)
Mask used in iptrtpproxy_authorize_media. Current mask may be obtained
by @iptrtpproxy.remove_codec_mask.
5. Selects
5.1. @iptrtpproxy.session_ids
5.2. @iptrtpproxy.sdp_ip
5.3. @iptrtpproxy.o_name
5.4. @iptrtpproxy.o_addr
5.5. @iptrtpproxy.auth_rights
5.6. @iptrtpproxy.active_media_num
5.1. @iptrtpproxy.session_ids
Returns sessions allocated/updated in iptrtpproxy_alloc/update.
The format is:
switchboard_name [ ":" [ session_id "/" created ] * ( "," session_id "/" create
d ) ] ]
session_id = * ( [0-9] ) ; empty when no session allocated
created = timestamp
5.2. @iptrtpproxy.sdp_ip
Return first rewritten IP provided at SDP c= line.
5.3. @iptrtpproxy.o_name
Return username from original o= line.
5.4. @iptrtpproxy.o_addr
Return address from original o= line.
5.5. @iptrtpproxy.auth_rights
Result of iptrtpproxy_authorize_media.
5.6. @iptrtpproxy.active_media_num
Returns number of active media streams in SDP.
iptrtpproxy_authorize_media may disable some streams, i.e. returned
value may change after authorization.
|
