39
Copyright © 2003-2008 Sippy Software, Inc.
41
Copyright © 2005 Voice Sistem SRL
43
Copyright © 2009-2012 TuTPro Inc.
45
Copyright © 2010 VoIPEmbedded Inc.
47
Copyright © 2013 Sipwise GmbH
48
__________________________________________________________________
55
2. Multiple RTPProxy usage
59
3.2. External Libraries or Applications
63
4.1. rtpproxy_sock (string)
64
4.2. rtpproxy_disable_tout (integer)
65
4.3. rtpproxy_tout (integer)
66
4.4. rtpproxy_retr (integer)
67
4.5. extra_id_pv (string)
71
5.1. set_rtp_proxy_set(setid)
72
5.2. rtpproxy_offer([flags [, ip_address]])
73
5.3. rtpproxy_answer([flags [, ip_address]])
74
5.4. rtpproxy_destroy([flags])
75
5.5. unforce_rtp_proxy()
76
5.6. rtpproxy_manage([flags [, ip_address]])
77
5.7. start_recording()
79
6. Exported Pseudo Variables
88
2. Frequently Asked Questions
92
1.1. Set rtpproxy_sock parameter
93
1.2. Set rtpproxy_disable_tout parameter
94
1.3. Set rtpproxy_tout parameter
95
1.4. Set rtpproxy_retr parameter
96
1.5. Set extra_id_pv parameter
97
1.6. set_rtp_proxy_set usage
98
1.7. rtpproxy_offer usage
99
1.8. rtpproxy_answer usage
100
1.9. rtpproxy_destroy usage
101
1.10. rtpproxy_manage usage
102
1.11. start_recording usage
104
1.13. nh_enable_rtpp usage
105
1.14. nh_show_rtpp usage
107
Chapter 1. Admin Guide
112
2. Multiple RTPProxy usage
115
3.1. Kamailio Modules
116
3.2. External Libraries or Applications
120
4.1. rtpproxy_sock (string)
121
4.2. rtpproxy_disable_tout (integer)
122
4.3. rtpproxy_tout (integer)
123
4.4. rtpproxy_retr (integer)
124
4.5. extra_id_pv (string)
128
5.1. set_rtp_proxy_set(setid)
129
5.2. rtpproxy_offer([flags [, ip_address]])
130
5.3. rtpproxy_answer([flags [, ip_address]])
131
5.4. rtpproxy_destroy([flags])
132
5.5. unforce_rtp_proxy()
133
5.6. rtpproxy_manage([flags [, ip_address]])
134
5.7. start_recording()
136
6. Exported Pseudo Variables
147
This is a module that enables media streams to be proxied via an RTP
148
proxy. The only RTP proxy currently known to work with this module is
149
the Sipwise ngcp-rtpproxy-ng https://github.com/sipwise/mediaproxy-ng.
150
The rtpproxy-ng module is a modified version of the original rtpproxy
151
module using a new control protocol. The module is designed to be a
152
drop-in replacement for the old module from a configuration file point
153
of view, however due to the incompatible control protocol, it only
154
works with RTP proxies which specifically support it.
156
2. Multiple RTPProxy usage
158
The rtpproxy-ng module can support multiple RTP proxies for
159
balancing/distribution and control/selection purposes.
161
The module allows definition of several sets of rtpproxies.
162
Load-balancing will be performed over a set and the admin has the
163
ability to choose what set should be used. The set is selected via its
164
id - the id being defined with the set. Refer to the “rtpproxy_sock”
165
module parameter definition for syntax description.
167
The balancing inside a set is done automatically by the module based on
168
the weight of each rtpproxy from the set.
170
The selection of the set is done from script prior using
171
unforce_rtp_proxy(), rtpproxy_offer() or rtpproxy_answer() functions -
172
see the set_rtp_proxy_set() function.
174
For backward compatibility reasons, a set with no id take by default
175
the id 0. Also if no set is explicitly set before unforce_rtp_proxy(),
176
rtpproxy_offer() or rtpproxy_answer() the 0 id set will be used.
178
IMPORTANT: if you use multiple sets, take care and use the same set for
179
both rtpproxy_offer()/rtpproxy_answer() and unforce_rtpproxy()!!
183
3.1. Kamailio Modules
184
3.2. External Libraries or Applications
186
3.1. Kamailio Modules
188
The following modules must be loaded before this module:
189
* tm module - (optional) if you want to have rtpproxy_manage() fully
192
3.2. External Libraries or Applications
194
The following libraries or applications must be installed before
195
running Kamailio with this module loaded:
200
4.1. rtpproxy_sock (string)
201
4.2. rtpproxy_disable_tout (integer)
202
4.3. rtpproxy_tout (integer)
203
4.4. rtpproxy_retr (integer)
204
4.5. extra_id_pv (string)
206
4.1. rtpproxy_sock (string)
208
Definition of socket(s) used to connect to (a set) RTPProxy. It may
209
specify a UNIX socket or an IPv4/IPv6 UDP socket.
211
Default value is “NONE” (disabled).
213
Example 1.1. Set rtpproxy_sock parameter
216
modparam("rtpproxy-ng", "rtpproxy_sock", "udp:localhost:12221")
217
# multiple rtproxies for LB
218
modparam("rtpproxy-ng", "rtpproxy_sock",
219
"udp:localhost:12221 udp:localhost:12222")
220
# multiple sets of multiple rtproxies
221
modparam("rtpproxy-ng", "rtpproxy_sock",
222
"1 == udp:localhost:12221 udp:localhost:12222")
223
modparam("rtpproxy-ng", "rtpproxy_sock",
224
"2 == udp:localhost:12225")
227
4.2. rtpproxy_disable_tout (integer)
229
Once an RTP proxy was found unreachable and marked as disabled, the
230
rtpproxy-ng module will not attempt to establish communication to that
231
RTP proxy for rtpproxy_disable_tout seconds.
233
Default value is “60”.
235
Example 1.2. Set rtpproxy_disable_tout parameter
237
modparam("rtpproxy-ng", "rtpproxy_disable_tout", 20)
240
4.3. rtpproxy_tout (integer)
242
Timeout value in waiting for reply from RTP proxy.
244
Default value is “1”.
246
Example 1.3. Set rtpproxy_tout parameter
248
modparam("rtpproxy-ng", "rtpproxy_tout", 2)
251
4.4. rtpproxy_retr (integer)
253
How many times the module should retry to send and receive after
254
timeout was generated.
256
Default value is “5”.
258
Example 1.4. Set rtpproxy_retr parameter
260
modparam("rtpproxy-ng", "rtpproxy_retr", 2)
263
4.5. extra_id_pv (string)
265
The parameter sets the PV defination to use when the “b” parameter is
266
used on unforce_rtp_proxy(), rtpproxy_offer(), rtpproxy_answer() or
267
rtpproxy_manage() command.
269
Default is empty, the “b” parameter may not be used then.
271
Example 1.5. Set extra_id_pv parameter
273
modparam("rtpproxy-ng", "extra_id_pv", "$avp(extra_id)")
278
5.1. set_rtp_proxy_set(setid)
279
5.2. rtpproxy_offer([flags [, ip_address]])
280
5.3. rtpproxy_answer([flags [, ip_address]])
281
5.4. rtpproxy_destroy([flags])
282
5.5. unforce_rtp_proxy()
283
5.6. rtpproxy_manage([flags [, ip_address]])
284
5.7. start_recording()
286
5.1. set_rtp_proxy_set(setid)
288
Sets the Id of the rtpproxy set to be used for the next
289
unforce_rtp_proxy(), rtpproxy_offer(), rtpproxy_answer() or
290
rtpproxy_manage() command. The parameter can be an integer or a config
291
variable holding an integer.
293
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
296
Example 1.6. set_rtp_proxy_set usage
298
set_rtp_proxy_set("2");
302
5.2. rtpproxy_offer([flags [, ip_address]])
304
Rewrites SDP body to ensure that media is passed through an RTP proxy.
305
To be invoked on INVITE for the cases the SDPs are in INVITE and 200 OK
306
and on 200 OK when SDPs are in 200 OK and ACK.
308
Meaning of the parameters is as follows:
309
* flags - flags to turn on some features.
310
+ 1 - append first Via branch to Call-ID when sending command to
311
rtpproxy. This can be used to create one media session per
312
branch on the rtpproxy. When sending a subsequent “delete”
313
command to the rtpproxy, you can then stop just the session
314
for a specific branch when passing the flag '1' or '2' in the
315
“unforce_rtpproxy”, or stop all sessions for a call when not
316
passing one of those two flags there. This is especially
317
useful if you have serially forked call scenarios where
318
rtpproxy gets an “offer” command for a new branch, and then a
319
“delete” command for the previous branch, which would
320
otherwise delete the full call, breaking the subsequent
321
“answer” for the new branch. This flag is only supported by
322
the ngcp-mediaproxy-ng rtpproxy at the moment!
323
+ 2 - append second Via branch to Call-ID when sending command
324
to rtpproxy. See flag '1' for its meaning.
325
+ 3 - behave like flag 1 is set for a request and like flag 2 is
327
+ a - flags that UA from which message is received doesn't
328
support symmetric RTP. (automatically sets the 'r' flag)
329
+ b - append branch specific variable to Call-ID when sending
330
command to rtpproxy. This creates one rtpproxy session per
331
unique variable. Works similar to the 1, 2 and 3 parameter,
332
but is usefull when forking to multiple destinations on
333
different address families or network segments, requiring
334
different rtpproxy parameters. The variable value is taken
335
from the “extra_id_pv”. When used, it must be used in every
336
call to rtpproxy_manage(), rtpproxy_offer(), rtpproxy_answer()
337
and rtpproxy_destroy() with the same contents of the PV. The b
338
parameter may not be used in conjunction with the 1, 2 or 3
339
parameter to use the Via branch in the Call-ID.
340
+ l - force “lookup”, that is, only rewrite SDP when
341
corresponding session already exists in the RTP proxy. By
342
default is on when the session is to be completed.
343
+ i, e - these flags specify the direction of the SIP message.
344
These flags only make sense when rtpproxy is running in bridge
345
mode. 'i' means internal network (LAN), 'e' means external
346
network (WAN). 'i' corresponds to rtpproxy's first interface,
347
'e' corresponds to rtpproxy's second interface. You always
348
have to specify two flags to define the incoming network and
349
the outgoing network. For example, 'ie' should be used for SIP
350
message received from the local interface and sent out on the
351
external interface, and 'ei' vice versa. Other options are
352
'ii' and 'ee'. So, for example if a SIP requests is processed
353
with 'ie' flags, the corresponding response must be processed
355
For ngcp-mediaproxy-ng, these flags are used to select between
356
IPv4 and IPv6 addresses, corresponding to 'i' and 'e'
357
respectively. For example, if the request is coming from an
358
IPv4 host and is going to an IPv6 host, the flags should be
360
Note: As rtpproxy in bridge mode s per default asymmetric, you
361
have to specify the 'w' flag for clients behind NAT! See also
363
+ x - this flag an alternative to the 'ie' or 'ei'-flags in
364
order to do automatic bridging between IPv4 on the "internal
365
network" and IPv6 on the "external network". Instead of
366
explicitly instructing the RTP proxy to select a particular
367
address family, the distinction is done by the given IP in the
368
SDP body by the RTP proxy itself. Not supported by
370
Note: Please note, that this will only work properly with
371
non-dual-stack user-agents or with dual-stack clients
372
according to RFC6157 (which suggest ICE for Dual-Stack
373
implementations). This short-cut will not work properly with
374
RFC4091 (ANAT) compatible clients, which suggests having
375
different m-lines with different IP-protocols grouped
377
+ f - instructs rtpproxy to ignore marks inserted by another
378
rtpproxy in transit to indicate that the session is already
379
goes through another proxy. Allows creating a chain of
381
+ r - flags that IP address in SDP should be trusted. Without
382
this flag, rtpproxy ignores address in the SDP and uses source
383
address of the SIP message as media address which is passed to
385
+ o - flags that IP from the origin description (o=) should be
387
+ c - flags to change the session-level SDP connection (c=) IP
388
if media-description also includes connection information.
389
+ w - flags that for the UA from which message is received,
390
support symmetric RTP must be forced.
391
+ zNN - requests the RTPproxy to perform re-packetization of RTP
392
traffic coming from the UA which has sent the current message
393
to increase or decrease payload size per each RTP packet
394
forwarded if possible. The NN is the target payload size in
395
ms, for the most codecs its value should be in 10ms
396
increments, however for some codecs the increment could differ
397
(e.g. 30ms for GSM or 20ms for G.723). The RTPproxy would
398
select the closest value supported by the codec. This feature
399
could be used for significantly reducing bandwith overhead for
400
low bitrate codecs, for example with G.729 going from 10ms to
401
100ms saves two thirds of the network bandwith.
402
+ + - instructs the RTP proxy to discard any ICE attributes
403
already present in the SDP body and then generate and insert
404
new ICE data, leaving itself as the only ICE candidates.
405
Without this flag, new ICE data will only be generated if no
406
ICE was present in the SDP originally; otherwise the RTP proxy
407
will only insert itself as an additional ICE candidate. Other
408
SDP substitutions (c=, m=, etc) are unaffected by this flag.
409
+ - - instructs the RTP proxy to discard any ICE attributes and
410
not insert any new ones into the SDP. Mutually exclusive with
412
+ s, S, p, P - These flags control the RTP transport protocol
413
that should be used towards the recipient of the SDP. If none
414
of them are specified, the protocol given in the SDP is left
415
untouched. Otherwise, the "S" flag indicates that SRTP should
416
be used, while "s" indicates that SRTP should not be used. "P"
417
indicates that the advanced RTCP profile with feedback
418
messages should be used, and "p" indicates that the regular
419
RTCP profile should be used. As such, the combinations "sp",
420
"sP", "Sp" and "SP" select between RTP/AVP, RTP/AVPF, RTP/SAVP
421
and RTP/SAVPF, respectively.
422
* ip_address - new SDP IP address.
424
This function can be used from ANY_ROUTE.
426
Example 1.7. rtpproxy_offer usage
429
if (is_method("INVITE")) {
430
if (has_body("application/sdp")) {
431
if (rtpproxy_offer())
437
if (is_method("ACK") && has_body("application/sdp"))
445
if (has_body("application/sdp"))
453
if (has_body("application/sdp"))
458
5.3. rtpproxy_answer([flags [, ip_address]])
460
Rewrites SDP body to ensure that media is passed through an RTP proxy.
461
To be invoked on 200 OK for the cases the SDPs are in INVITE and 200 OK
462
and on ACK when SDPs are in 200 OK and ACK.
464
See rtpproxy_answer() function description above for the meaning of the
467
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
468
FAILURE_ROUTE, BRANCH_ROUTE.
470
Example 1.8. rtpproxy_answer usage
472
See rtpproxy_offer() function example above for example.
474
5.4. rtpproxy_destroy([flags])
476
Tears down the RTPProxy session for the current call.
478
This function can be used from ANY_ROUTE.
480
Meaning of the parameters is as follows:
481
* flags - flags to turn on some features.
482
+ 1 - append first Via branch to Call-ID when sending command to
483
rtpproxy. This can be used to create one media session per
484
branch on the rtpproxy. When sending a subsequent “delete”
485
command to the rtpproxy, you can then stop just the session
486
for a specific branch when passing the flag '1' or '2' in the
487
“unforce_rtpproxy”, or stop all sessions for a call when not
488
passing one of those two flags there. This is especially
489
useful if you have serially forked call scenarios where
490
rtpproxy gets an “update” command for a new branch, and then a
491
“delete” command for the previous branch, which would
492
otherwise delete the full call, breaking the subsequent
493
“lookup” for the new branch. This flag is only supported by
494
the ngcp-mediaproxy-ng rtpproxy at the moment!
495
+ 2 - append second Via branch to Call-ID when sending command
496
to rtpproxy. See flag '1' for its meaning.
497
+ b - append branch specific variable to Call-ID when sending
498
command to rtpproxy. See rtpproxy_offer() for details.
501
t - do not include To tag to “delete” command to rtpproxy thus
502
causing full call to be deleted. Useful for deleting unused
503
rtpproxy call when 200 OK is received on a branch, where
504
rtpproxy is not needed.
506
Example 1.9. rtpproxy_destroy usage
511
5.5. unforce_rtp_proxy()
513
Same as rtpproxy_destroy().
515
5.6. rtpproxy_manage([flags [, ip_address]])
517
Manage the RTPProxy session - it combines the functionality of
518
rtpproxy_offer(), rtpproxy_answer() and unforce_rtpproxy(), detecting
519
internally based on message type and method which one to execute.
521
It can take the same parameters as rtpproxy_offer(). The flags
522
parameter to rtpproxy_manage() can be a configuration variable
523
containing the flags as a string.
526
* If INVITE with SDP, then do rtpproxy_offer()
527
* If INVITE with SDP, when the tm module is loaded, mark transaction
528
with internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
530
* If ACK with SDP, then do rtpproxy_answer()
531
* If BYE or CANCEL, or called within a FAILURE_ROUTE[], then do
533
* If reply to INVITE with code >= 300 do unforce_rtpproxy()
534
* If reply with SDP to INVITE having code 1xx and 2xx, then do
535
rtpproxy_answer() if the request had SDP or tm is not loaded,
536
otherwise do rtpproxy_offer()
538
This function can be used from ANY_ROUTE.
540
Example 1.10. rtpproxy_manage usage
545
5.7. start_recording()
547
This function will send a signal to the RTP Proxy to record the RTP
548
stream on the RTP Proxy. This function is not supported by
549
ngcp-mediaproxy-ng at the moment!
551
This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
553
Example 1.11. start_recording usage
558
6. Exported Pseudo Variables
564
Returns the RTP Statistics from the RTP Proxy. The RTP Statistics from
565
the RTP Proxy are provided as a string and it does contain several
566
packet counters. The statistics must be retrieved before the session is
567
deleted (before unforce_rtpproxy()).
569
Example 1.12. $rtpstat Usage
571
append_hf("X-RTP-Statistics: $rtpstat\r\n");
581
Enables a rtp proxy if parameter value is greater than 0. Disables it
582
if a zero value is given.
584
The first parameter is the rtp proxy url (exactly as defined in the
587
The second parameter value must be a number in decimal.
589
NOTE: if a rtpproxy is defined multiple times (in the same or diferente
590
sete), all of its instances will be enables/disabled.
592
Example 1.13. nh_enable_rtpp usage
594
$ kamctl fifo nh_enable_rtpp udp:192.168.2.133:8081 0
599
Displays all the rtp proxies and their information: set and status
600
(disabled or not, weight and recheck_ticks).
604
Example 1.14. nh_show_rtpp usage
606
$ kamctl fifo nh_show_rtpp
609
Chapter 2. Frequently Asked Questions
611
2.1. What happend with “rtpproxy_disable” parameter?
612
2.2. Where can I find more about Kamailio?
613
2.3. Where can I post a question about this module?
614
2.4. How can I report a bug?
618
What happend with “rtpproxy_disable” parameter?
620
It was removed as it became obsolete - now “rtpproxy_sock” can take
621
empty value to disable the rtpproxy functionality.
625
Where can I find more about Kamailio?
627
Take a look at http://www.kamailio.org/.
631
Where can I post a question about this module?
633
First at all check if your question was already answered on one of our
635
* User Mailing List -
636
http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
637
* Developer Mailing List -
638
http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
640
E-mails regarding any stable Kamailio release should be sent to
641
<sr-users@lists.sip-router.org> and e-mails regarding development
642
versions should be sent to <sr-dev@lists.sip-router.org>.
644
If you want to keep the mail private, send it to
645
<sr-users@lists.sip-router.org>.
649
How can I report a bug?
651
Please follow the guidelines provided at:
652
http://sip-router.org/tracker.
added
removed
modules/rtpproxy-ng/README
