00b26f28609f81a47b31ea1e4a1bc0c911e95f36
[sip-router] / modules / rtpengine / README
1 rtpengine Module
2
3 Maxim Sobolev
4
5    Sippy Software, Inc.
6
7 Juha Heinanen
8
9    TuTPro, Inc.
10
11 Edited by
12
13 Maxim Sobolev
14
15 Edited by
16
17 Bogdan-Andrei Iancu
18
19 Edited by
20
21 Juha Heinanen
22
23 Edited by
24
25 Sas Ovidiu
26
27 Edited by
28
29 Carsten Bock
30
31    ng-voice GmbH
32
33 Edited by
34
35 Richard Fuchs
36
37    Sipwise GmbH
38
39    Copyright © 2003-2008 Sippy Software, Inc.
40
41    Copyright © 2005 Voice Sistem SRL
42
43    Copyright © 2009-2014 TuTPro Inc.
44
45    Copyright © 2010 VoIPEmbedded Inc.
46
47    Copyright © 2013-2015 Sipwise GmbH
48      __________________________________________________________________
49
50    Table of Contents
51
52    1. Admin Guide
53
54         1. Overview
55         2. Multiple RTP proxy usage
56         3. Dependencies
57
58               3.1. Kamailio Modules
59               3.2. External Libraries or Applications
60
61         4. Parameters
62
63               4.1. rtpengine_sock (string)
64               4.2. rtpengine_disable_tout (integer)
65               4.3. rtpengine_tout_ms (integer)
66               4.4. queried_nodes_limit (integer)
67               4.5. rtpengine_retr (integer)
68               4.6. extra_id_pv (string)
69               4.7. setid_avp (string)
70               4.8. force_send_interface (string)
71               4.9. write_sdp_pv (string)
72               4.10. rtp_inst_pvar (string)
73
74         5. Functions
75
76               5.1. set_rtpengine_set(setid[, setid])
77               5.2. rtpengine_offer([flags])
78               5.3. rtpengine_answer([flags])
79               5.4. rtpengine_delete([flags])
80               5.5. rtpengine_manage([flags])
81               5.6. start_recording()
82
83         6. Exported Pseudo Variables
84
85               6.1. $rtpstat
86
87         7. MI Commands
88
89               7.1. nh_enable_rtpp proxy_url/all 0/1
90               7.2. nh_show_rtpp proxy_url/all
91               7.3. nh_ping_rtpp proxy_url/all
92
93    2. Frequently Asked Questions
94
95    List of Examples
96
97    1.1. Set rtpengine_sock parameter
98    1.2. Set rtpengine_disable_tout parameter
99    1.3. Set rtpengine_tout_ms parameter
100    1.4. Set queried_nodes_limit parameter
101    1.5. Set rtpengine_retr parameter
102    1.6. Set extra_id_pv parameter
103    1.7. Set setid_avp parameter
104    1.8. Set force_send_interface parameter
105    1.9. Set write_sdp_pv parameter
106    1.10. Set rtp_inst_pvar parameter
107    1.11. set_rtpengine_set usage
108    1.12. rtpengine_offer usage
109    1.13. rtpengine_answer usage
110    1.14. rtpengine_delete usage
111    1.15. rtpengine_manage usage
112    1.16. start_recording usage
113    1.17. $rtpstat Usage
114    1.18. nh_enable_rtpp usage
115    1.19. nh_show_rtpp usage
116    1.20. nh_ping_rtpp usage
117
118 Chapter 1. Admin Guide
119
120    Table of Contents
121
122    1. Overview
123    2. Multiple RTP proxy usage
124    3. Dependencies
125
126         3.1. Kamailio Modules
127         3.2. External Libraries or Applications
128
129    4. Parameters
130
131         4.1. rtpengine_sock (string)
132         4.2. rtpengine_disable_tout (integer)
133         4.3. rtpengine_tout_ms (integer)
134         4.4. queried_nodes_limit (integer)
135         4.5. rtpengine_retr (integer)
136         4.6. extra_id_pv (string)
137         4.7. setid_avp (string)
138         4.8. force_send_interface (string)
139         4.9. write_sdp_pv (string)
140         4.10. rtp_inst_pvar (string)
141
142    5. Functions
143
144         5.1. set_rtpengine_set(setid[, setid])
145         5.2. rtpengine_offer([flags])
146         5.3. rtpengine_answer([flags])
147         5.4. rtpengine_delete([flags])
148         5.5. rtpengine_manage([flags])
149         5.6. start_recording()
150
151    6. Exported Pseudo Variables
152
153         6.1. $rtpstat
154
155    7. MI Commands
156
157         7.1. nh_enable_rtpp proxy_url/all 0/1
158         7.2. nh_show_rtpp proxy_url/all
159         7.3. nh_ping_rtpp proxy_url/all
160
161 1. Overview
162
163    This is a module that enables media streams to be proxied via an RTP
164    proxy. The only RTP proxy currently known to work with this module is
165    the Sipwise rtpengine https://github.com/sipwise/rtpengine. The
166    rtpengine module is a modified version of the original rtpproxy module
167    using a new control protocol. The module is designed to be a drop-in
168    replacement for the old module from a configuration file point of view,
169    however due to the incompatible control protocol, it only works with
170    RTP proxies which specifically support it.
171
172 2. Multiple RTP proxy usage
173
174    The rtpengine module can support multiple RTP proxies for
175    balancing/distribution and control/selection purposes.
176
177    The module allows definition of several sets of rtpproxies.
178    Load-balancing will be performed over a set and the admin has the
179    ability to choose what set should be used. The set is selected via its
180    id - the id being defined with the set. Refer to the "rtpengine_sock"
181    module parameter definition for syntax description.
182
183    The balancing inside a set is done automatically by the module based on
184    the weight of each RTP proxy from the set.
185
186    The selection of the set is done from script prior using
187    rtpengine_delete(), rtpengine_offer() or rtpengine_answer() functions -
188    see the set_rtpengine_set() function.
189
190    Another way to select the set is to define setid_avp module parameter
191    and assign setid to the defined avp before calling rtpengine_offer() or
192    rtpengine_manage() function. If forwarding of the requests fails and
193    there is another branch to try, remember to unset the avp after calling
194    rtpengine_delete() function.
195
196    For backward compatibility reasons, a set with no id take by default
197    the id 0. Also if no set is explicitly set before rtpengine_delete(),
198    rtpengine_offer() or rtpengine_answer() the 0 id set will be used.
199
200    IMPORTANT: if you use multiple sets, take care and use the same set for
201    both rtpengine_offer()/rtpengine_answer() and rtpengine_delete()!! If
202    the set was selected using setid_avp, the avp needs to be set only once
203    before rtpengine_offer() or rtpengine_manage() call.
204
205 3. Dependencies
206
207    3.1. Kamailio Modules
208    3.2. External Libraries or Applications
209
210 3.1. Kamailio Modules
211
212    The following modules must be loaded before this module:
213      * tm module - (optional) if you want to have rtpengine_manage() fully
214        functional
215
216 3.2. External Libraries or Applications
217
218    The following libraries or applications must be installed before
219    running Kamailio with this module loaded:
220      * None.
221
222 4. Parameters
223
224    4.1. rtpengine_sock (string)
225    4.2. rtpengine_disable_tout (integer)
226    4.3. rtpengine_tout_ms (integer)
227    4.4. queried_nodes_limit (integer)
228    4.5. rtpengine_retr (integer)
229    4.6. extra_id_pv (string)
230    4.7. setid_avp (string)
231    4.8. force_send_interface (string)
232    4.9. write_sdp_pv (string)
233    4.10. rtp_inst_pvar (string)
234
235 4.1. rtpengine_sock (string)
236
237    Definition of socket(s) used to connect to (a set) RTP proxy. It may
238    specify a UNIX socket or an IPv4/IPv6 UDP socket.
239
240    Default value is "NONE" (disabled).
241
242    Example 1.1. Set rtpengine_sock parameter
243 ...
244 # single rtproxy
245 modparam("rtpengine", "rtpengine_sock", "udp:localhost:12221")
246 # multiple rtproxies for LB with weights (missing weight defaults to 1)
247 modparam("rtpengine", "rtpengine_sock",
248         "udp:localhost:12221=2 udp:localhost:12222=1")
249 # multiple sets of multiple rtproxies
250 modparam("rtpengine", "rtpengine_sock",
251         "1 == udp:localhost:12221 udp:localhost:12222")
252 modparam("rtpengine", "rtpengine_sock",
253         "2 == udp:localhost:12225")
254 ...
255
256 4.2. rtpengine_disable_tout (integer)
257
258    Once an RTP proxy was found unreachable and marked as disabled, the
259    rtpengine module will not attempt to establish communication to that
260    RTP proxy for rtpengine_disable_tout seconds.
261
262    Default value is "60".
263
264    Example 1.2. Set rtpengine_disable_tout parameter
265 ...
266 modparam("rtpengine", "rtpengine_disable_tout", 20)
267 ...
268
269 4.3. rtpengine_tout_ms (integer)
270
271    Timeout value expressed in milliseconds in waiting for reply from RTP
272    proxy.
273
274    Default value is "1000".
275
276    Example 1.3. Set rtpengine_tout_ms parameter
277 ...
278 modparam("rtpengine", "rtpengine_tout_ms", 2000)
279 ...
280
281 4.4. queried_nodes_limit (integer)
282
283    The total number of nodes inside a set (sets are configurable via
284    rtpengine_sock function) to be queried before giving up establishing a
285    session. This brings more flexibility in case checking all rtpengines
286    would take too long. Max limit is 50.
287
288    By default all nodes in a set are tried before giving up communicating
289    with the rtpengines.
290
291    Example 1.4. Set queried_nodes_limit parameter
292 ...
293 modparam("rtpengine", "queried_nodes_limit", 5)
294 ...
295
296 4.5. rtpengine_retr (integer)
297
298    How many times the module should retry to send and receive after
299    timeout was generated.
300
301    Default value is "5".
302
303    Example 1.5. Set rtpengine_retr parameter
304 ...
305 modparam("rtpengine", "rtpengine_retr", 2)
306 ...
307
308 4.6. extra_id_pv (string)
309
310    The parameter sets the PV defination to use when the "b" parameter is
311    used on rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or
312    rtpengine_manage() command.
313
314    Default is empty, the "b" parameter may not be used then.
315
316    Example 1.6. Set extra_id_pv parameter
317 ...
318 modparam("rtpengine", "extra_id_pv", "$avp(extra_id)")
319 ...
320
321 4.7. setid_avp (string)
322
323    The parameter defines an AVP that, if set, determines which RTP proxy
324    set rtpengine_offer(), rtpengine_answer(), rtpengine_delete(), and
325    rtpengine_manage() functions use.
326
327    There is no default value.
328
329    Example 1.7. Set setid_avp parameter
330 ...
331 modparam("rtpengine", "setid_avp", "$avp(setid)")
332 ...
333
334 4.8. force_send_interface (string)
335
336    Forces all control messages between the SIP proxy and the RTP proxy to
337    be sent from the specified local interface. Both IPv4 and IPv6
338    addresses are supported. If not specified, the default interface
339    selected by the operating system will be used. Note: when
340    rtpengine_sock is a IPv6 link-local address, one _must_ set this
341    parameter in order to successfully connect to RTP engine. This is
342    necessarely because OS needs additional scope_id hint to communicate
343    over IPv6 link locals. The scope_id is resolved based on the given
344    IPv6.
345
346    There is no default value.
347
348    Example 1.8. Set force_send_interface parameter
349 ...
350 modparam("rtpengine", "force_send_interface", "10.3.7.123")
351 modparam("rtpengine", "force_send_interface", "2001:8d8:1ff:10c0:9a90:96ff:fea8:
352 fd99")
353 ...
354
355 4.9. write_sdp_pv (string)
356
357    If this parameter is set to a valid AVP or script var specifier, the
358    SDP returned by rtpengine in the offer/answer operations is returned in
359    the specified variable instead of the message body.
360
361    There is no default value.
362
363    Example 1.9. Set write_sdp_pv parameter
364 ...
365 modparam("rtpengine", "write_sdp_pv", "$avp(sdp)")
366   ...  or
367 modparam("rtpengine", "write_sdp_pv", "$pv(sdp)")
368 ...
369
370 4.10. rtp_inst_pvar (string)
371
372    A pseudo variable to store the chosen RTP Engine IP address. If this
373    parameter is set, the IP address and port of the instance chosen will
374    be stored in the given variable.
375
376    By default, this parameter is not set.
377
378    Example 1.10. Set rtp_inst_pvar parameter
379 ...
380 modparam("rtpproxy", "rtp_inst_pvar", "$avp(RTP_INSTANCE)")
381 ...
382
383 5. Functions
384
385    5.1. set_rtpengine_set(setid[, setid])
386    5.2. rtpengine_offer([flags])
387    5.3. rtpengine_answer([flags])
388    5.4. rtpengine_delete([flags])
389    5.5. rtpengine_manage([flags])
390    5.6. start_recording()
391
392 5.1. set_rtpengine_set(setid[, setid])
393
394    Sets the ID of the RTP proxy set to be used for the next
395    rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or
396    rtpengine_manage() command. The parameter can be an integer or a config
397    variable holding an integer.
398
399    A second set ID can be specified to daisy-chain two RTP proxies. The
400    two set IDs must be distinct from each other and there must not be any
401    overlap in the proxies present in both sets. In this use case, the
402    request (offer, answer, etc) is first sent to an RTP proxy from the
403    first set, which rewrites the SDP body and sends it back to the module.
404    The rewritten SDP body is then used to make another request to an RTP
405    proxy from the second set, which rewrites the SDP body another time and
406    sends it back to the module to be placed back into the SIP message.
407    This is useful if you have a set of RTP proxies that the caller must
408    use, and another distinct set of RTP proxies that the callee must use.
409    This is supported by all rtpengine commands except rtpengine_manage().
410
411    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
412    BRANCH_ROUTE.
413
414    Example 1.11. set_rtpengine_set usage
415 ...
416 set_rtpengine_set("2");
417 rtpengine_offer();
418 ...
419
420 5.2. rtpengine_offer([flags])
421
422    Rewrites SDP body to ensure that media is passed through an RTP proxy.
423    To be invoked on INVITE for the cases the SDP bodies are in INVITE and
424    200 OK and on 200 OK when SDP bodies are in 200 OK and ACK.
425
426    Meaning of the parameters is as follows:
427      * flags - flags to turn on some features.
428        The "flags" string is a list of space-separated items. Each item is
429        either an individual token, or a token in "key=value" format. The
430        possible tokens are described below.
431           + via-branch=... - Include the "branch" value of one of the
432             "Via" headers in the request to the RTP proxy. Possible values
433             are: "1" - use the first "Via" header; "2" - use the second
434             "Via" header; "auto" - use the first "Via" header if this is a
435             request, or the second one if this is a reply; "extra" - don't
436             take the value from a header, but instead use the value of the
437             "extra_id_pv" variable. This can be used to create one media
438             session per branch on the RTP proxy. When sending a subsequent
439             "delete" command to the RTP proxy, you can then stop just the
440             session for a specific branch when passing the flag '1' or '2'
441             in the "rtpengine_delete", or stop all sessions for a call
442             when not passing one of those two flags there. This is
443             especially useful if you have serially forked call scenarios
444             where the RTP proxy gets an "offer" command for a new branch,
445             and then a "delete" command for the previous branch, which
446             would otherwise delete the full call, breaking the subsequent
447             "answer" for the new branch. This flag is only supported by
448             the Sipwise rtpengine RTP proxy at the moment!
449           + asymmetric - flags that UA from which message is received
450             doesn't support symmetric RTP. Disables learning of endpoint
451             addresses in the Sipwise rtpengine proxy.
452           + force-answer - force "answer", that is, only rewrite SDP when
453             corresponding session already exists in the RTP proxy. By
454             default is on when the session is to be completed.
455           + direction=... - this option specifies a logical network
456             interface and should be given exactly twice. It enables RTP
457             bridging between different addresses or networks of the same
458             family (e.g. IPv4 to IPv4). The first instance of the option
459             specifies the interface that the originator of this message
460             should be using, while the second instance specifies the
461             interface that the target should be using. For example, if the
462             SIP message was sent by an endpoint on a private network and
463             will be sent to an endpoint on the public internet, you would
464             use "direction=priv direction=pub" if those two logical
465             network interfaces were called "priv" and "pub" in your RTP
466             proxy's configuration respectively. The direction must only be
467             specified in for initial SDP offer; answers or subsequent
468             offers can omit this option.
469           + internal, external - shorthand for "direction=internal" and
470             "direction=external" respectively. Useful for brevity or as
471             legacy option if the RTP proxy only supports two network
472             interfaces instead of multiple, arbitrarily named ones.
473           + auto-bridge - this flag an alternative to the "internal" and
474             "external" flags in order to do automatic bridging between
475             IPv4 on the "internal network" and IPv6 on the "external
476             network". Instead of explicitly instructing the RTP proxy to
477             select a particular address family, the distinction is done by
478             the given IP in the SDP body by the RTP proxy itself. Not
479             supported by Sipwise rtpengine.
480           + address-family=... - instructs the RTP proxy that the
481             recipient of this SDP body expects to see addresses of a
482             particular family. Possible values are "IP4" and "IP6". For
483             example, if the SDP body contains IPv4 addresses but the
484             recipient only speaks IPv6, you would use "address-family=IP6"
485             to bridge between the two address families.
486             Sipwise rtpengine remembers the address family preference of
487             each party after it has seen an SDP body from them. This means
488             that normally it is only necessary to explicitly specify the
489             address family in the "offer", but not in the "answer".
490             Note: Please note, that this will only work properly with
491             non-dual-stack user-agents or with dual-stack clients
492             according to RFC6157 (which suggest ICE for Dual-Stack
493             implementations). This short-cut will not work properly with
494             RFC4091 (ANAT) compatible clients, which suggests having
495             different m-lines with different IP-protocols grouped
496             together.
497           + force - instructs the RTP proxy to ignore marks inserted by
498             another RTP proxy in transit to indicate that the session is
499             already goes through another proxy. Allows creating a chain of
500             proxies. Not supported and ignored by Sipwise rtpengine.
501           + trust-address - flags that IP address in SDP should be
502             trusted. Starting with rtpengine 3.8, this is the default
503             behaviour. In older versions, without this flag the RTP proxy
504             ignores the address in the SDP and uses source address of the
505             SIP message as media address which is passed to the RTP proxy.
506           + SIP-source-address - the opposite of trust-address. Restores
507             the old default behaviour of ignoring endpoint addresses in
508             the SDP body.
509           + replace-origin - flags that IP from the origin description
510             (o=) should be also changed.
511           + replace-session-connection - flags to change the session-level
512             SDP connection (c=) IP if media description also includes
513             connection information.
514           + symmetric - flags that for the UA from which message is
515             received, support symmetric RTP must be forced. Does nothing
516             with the Sipwise rtpengine proxy as it is the default.
517           + repacketize=NN - requests the RTP proxy to perform
518             re-packetization of RTP traffic coming from the UA which has
519             sent the current message to increase or decrease payload size
520             per each RTP packet forwarded if possible. The NN is the
521             target payload size in ms, for the most codecs its value
522             should be in 10ms increments, however for some codecs the
523             increment could differ (e.g. 30ms for GSM or 20ms for G.723).
524             The RTP proxy would select the closest value supported by the
525             codec. This feature could be used for significantly reducing
526             bandwith overhead for low bitrate codecs, for example with
527             G.729 going from 10ms to 100ms saves two thirds of the network
528             bandwith. Not supported by Sipwise rtpengine.
529           + ICE=... - controls the RTP proxy's behaviour regarding ICE
530             attributes within the SDP body. Possible values are: "force" -
531             discard any ICE attributes already present in the SDP body and
532             then generate and insert new ICE data, leaving itself as the
533             only ICE candidates; "force-relay" - discard any "relay" type
534             ICE attributes already present in the SDP body and then
535             generate and insert itself as the only ICE "relay" candidates;
536             "remove" instructs the RTP proxy to discard any ICE attributes
537             and not insert any new ones into the SDP. The default (if no
538             "ICE=..." is given at all), new ICE data will only be
539             generated if no ICE was present in the SDP originally;
540             otherwise the RTP proxy will only insert itself as additional
541             ICE candidate. Other SDP substitutions (c=, m=, etc) are
542             unaffected by this flag.
543           + RTP, SRTP, AVP, AVPF - These flags control the RTP transport
544             protocol that should be used towards the recipient of the SDP.
545             If none of them are specified, the protocol given in the SDP
546             is left untouched. Otherwise, the "SRTP" flag indicates that
547             SRTP should be used, while "RTP" indicates that SRTP should
548             not be used. "AVPF" indicates that the advanced RTCP profile
549             with feedback messages should be used, and "AVP" indicates
550             that the regular RTCP profile should be used. See also the
551             next set of flags below.
552           + RTP/AVP, RTP/SAVP, RTP/AVPF, RTP/SAVPF - these serve as an
553             alternative, more explicit way to select between the different
554             RTP protocols and profiles supported by the RTP proxy. For
555             example, giving the flag "RTP/SAVPF" has the same effect as
556             giving the two flags "SRTP AVPF".
557           + to-tag - force inclusion of the "To" tag. Normally, the "To"
558             tag is always included when present, except for "delete"
559             messages. Including the "To" tag in a "delete" messages allows
560             you to be more selective about which dialogues within a call
561             are being torn down.
562           + rtcp-mux-demux - if rtcp-mux (RFC 5761) was offered, make the
563             RTP proxy accept the offer, but not offer it to the recipient
564             of this message.
565           + rtcp-mux-reject - if rtcp-mux was offered, make the RTP proxy
566             reject the offer, but still offer it to the recipient. Can be
567             combined with "rtcp-mux-offer" to always offer it.
568           + rtcp-mux-offer - make the RTP proxy offer rtcp-mux to the
569             recipient of this message, regardless of whether it was
570             offered originally or not.
571           + rtcp-mux-accept - if rtcp-mux was offered, make the RTP proxy
572             accept the offer and also offer it to the recipient of this
573             message. Can be combined with "rtcp-mux-offer" to always offer
574             it.
575           + media-address=... - force a particular media address to be
576             used in the SDP body. Address family is detected
577             automatically.
578           + TOS=... - change the IP TOS value for all outgoing RTP packets
579             within the entire call in both directions. Only honoured in an
580             "offer", ignored for an "answer". Valid values are 0 through
581             255, given in decimal. If this option is not specified, the
582             TOS value will revert to the default TOS (normally 184). A
583             value of -1 may be used to leave the currently used TOS
584             unchanged.
585           + delete-delay=... - override the default delay (in seconds)
586             before a call is actually deleted from memory. Can be set to
587             zero to effectuate immediate deletion. This option only makes
588             sense for delete operations.
589           + strict-source - instructs the RTP proxy to check the source
590             addresses of all incoming RTP packets and drop the packets if
591             the address doesn't match.
592           + media-handover - the antithesis of strict-source. Instructs
593             the RTP proxy not only to accept mismatching RTP source
594             addresses (as it normally would), but also to accept them as
595             the new endpoint address of the opposite media flow. Not
596             recommended as it allows media streams to be hijacked by an
597             attacker.
598           + DTLS=... - influence the behaviour of DTLS-SRTP. Possible
599             values are "no" or "off" to suppress offering or accepting
600             DTLS-SRTP, and "passive" to prefer participating in DTLS-SRTP
601             in a passive role.
602           + SDES-off - don't offer SDES when it normally would. In an SRTP
603             context, this leaves DTLS-SRTP as the only other option.
604           + SDES-unencrypted_srtp, SDES-unencrypted_srtcp,
605             SDES-unauthenticated_srtp - these directly reflect the SDES
606             session parameters from RFC 4568 and will make the RTP proxy
607             offer these parameters when offering SDES.
608           + SDES-encrypted_srtp, SDES-encrypted_srtcp,
609             SDES-authenticated_srtp - the opposites of the flags above.
610             Useful if accepting these parameters is not desired and they
611             should be rejected instead.
612
613    This function can be used from ANY_ROUTE.
614
615    Example 1.12. rtpengine_offer usage
616 route {
617 ...
618     if (is_method("INVITE")) {
619         if (has_body("application/sdp")) {
620             if (rtpengine_offer())
621                 t_on_reply("1");
622         } else {
623             t_on_reply("2");
624         }
625     }
626     if (is_method("ACK") && has_body("application/sdp"))
627         rtpengine_answer();
628 ...
629 }
630
631 onreply_route[1]
632 {
633 ...
634     if (has_body("application/sdp"))
635         rtpengine_answer();
636 ...
637 }
638
639 onreply_route[2]
640 {
641 ...
642     if (has_body("application/sdp"))
643         rtpengine_offer();
644 ...
645 }
646
647 5.3. rtpengine_answer([flags])
648
649    Rewrites SDP body to ensure that media is passed through an RTP proxy.
650    To be invoked on 200 OK for the cases the SDP bodies are in INVITE and
651    200 OK and on ACK when SDP bodies are in 200 OK and ACK.
652
653    See rtpengine_offer() function description above for the meaning of the
654    parameters.
655
656    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
657    FAILURE_ROUTE, BRANCH_ROUTE.
658
659    Example 1.13. rtpengine_answer usage
660
661    See rtpengine_offer() function example above for example.
662
663 5.4. rtpengine_delete([flags])
664
665    Tears down the RTPProxy session for the current call.
666
667    See rtpengine_offer() function description above for the meaning of the
668    parameters. Note that not all flags make sense for a "delete".
669
670    This function can be used from ANY_ROUTE.
671
672    Example 1.14. rtpengine_delete usage
673 ...
674 rtpengine_delete();
675 ...
676
677 5.5. rtpengine_manage([flags])
678
679    Manage the RTPProxy session - it combines the functionality of
680    rtpengine_offer(), rtpengine_answer() and rtpengine_delete(), detecting
681    internally based on message type and method which one to execute.
682
683    It can take the same parameters as rtpengine_offer(). The flags
684    parameter to rtpengine_manage() can be a configuration variable
685    containing the flags as a string.
686
687    Functionality:
688      * If INVITE with SDP, then do rtpengine_offer()
689      * If INVITE with SDP, when the tm module is loaded, mark transaction
690        with internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
691        rtpengine_answer()
692      * If ACK with SDP, then do rtpengine_answer()
693      * If BYE or CANCEL, or called within a FAILURE_ROUTE[], then do
694        rtpengine_delete()
695      * If reply to INVITE with code >= 300 do rtpengine_delete()
696      * If reply with SDP to INVITE having code 1xx and 2xx, then do
697        rtpengine_answer() if the request had SDP or tm is not loaded,
698        otherwise do rtpengine_offer()
699
700    This function can be used from ANY_ROUTE.
701
702    Example 1.15. rtpengine_manage usage
703 ...
704 rtpengine_manage();
705 ...
706
707 5.6. start_recording()
708
709    This function will send a signal to the RTP proxy to record the RTP
710    stream on the RTP proxy. This function is not supported by Sipwise
711    rtpengine at the moment!
712
713    This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
714
715    Example 1.16. start_recording usage
716 ...
717 start_recording();
718 ...
719
720 6. Exported Pseudo Variables
721
722    6.1. $rtpstat
723
724 6.1. $rtpstat
725
726    Returns the RTP statistics from the RTP proxy. The RTP statistics from
727    the RTP proxy are provided as a string and it does contain several
728    packet counters. The statistics must be retrieved before the session is
729    deleted (before rtpengine_delete()).
730
731    Example 1.17. $rtpstat Usage
732 ...
733     append_hf("X-RTP-Statistics: $rtpstat\r\n");
734 ...
735
736 7. MI Commands
737
738    7.1. nh_enable_rtpp proxy_url/all 0/1
739    7.2. nh_show_rtpp proxy_url/all
740    7.3. nh_ping_rtpp proxy_url/all
741
742 7.1. nh_enable_rtpp proxy_url/all 0/1
743
744    Enables a RTP proxy if the second parameter value is greater than 0.
745    Disables it if a zero value is given. The first parameter is either a
746    specific RTP proxy url (exactly as defined in the config file) or the
747    keyword all. The second parameter value must be a number in decimal.
748
749    When try to enable the RTP proxy, an application ping command is sent
750    to it. If it fails, the proxy is not enabled. Displays success or fail
751    when try to enable/disable.
752
753    NOTE: If a RTP proxy is defined multiple times (in the same or diferent
754    sets), all of its instances will be enabled/disabled.
755
756    NOTE: If a RTP proxy is in the disabled permanent state and one tries
757    to enable it, even if the ping fails, it is moved to a disabled
758    temporary state and a recheck_ticks are given to it. While the
759    recheck_ticks are grater than 0, the proxy is considered disabled
760    temporary, and it is not taken into consideration for sending data.
761    When the recheck_ticks are 0, the proxy is retested when trying to send
762    data(not automatically retested), and data can be send to it on
763    success.
764
765    NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
766    escape the :: from the IPv6 address. See the example below.
767
768    Example 1.18. nh_enable_rtpp usage
769 ...
770 $ kamctl fifo nh_enable_rtpp udp:192.168.2.133:8081 0
771 $ kamctl fifo nh_enable_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999 1
772 $ kamctl fifo nh_enable_rtpp all 1
773 ...
774
775 7.2. nh_show_rtpp proxy_url/all
776
777    Displays all the RTP proxies and their information: set and status
778    (disabled or not, weight and recheck_ticks). If a RTP proxy has been
779    disabled by nh_enable_rtpp mi command a "(permanent)" quote will appear
780    when printing the disabled status. This is to differentiate from a
781    temporary disable due to the proxy being not found responsive by
782    kamailio. In addition, when disabled permanent, recheck_ticks have no
783    meaning and "N\A" is printed instead of the value.
784
785    It takes either a specific RTP proxy url (exactly as defined in the
786    config file) or the keyword all as a parameter.
787
788    NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
789    escape the :: from the IPv6 address. See the example below.
790
791    Example 1.19. nh_show_rtpp usage
792 ...
793 $ kamctl fifo nh_show_rtpp udp:192.168.2.133:8081
794 $ kamctl fifo nh_show_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999
795 $ kamctl fifo nh_show_rtpp all
796 ...
797
798 7.3. nh_ping_rtpp proxy_url/all
799
800    Sends an application ping command to the RTP proxy. If the proxy does
801    not respond, it will be disabled, but not permanent. If the proxy
802    responds, no action is taken. Displays the ping result, i.e. success or
803    fail when try to ping.
804
805    It takes either a specific RTP proxy url (exactly as defined in the
806    config file) or the keyword all as a parameter.
807
808    NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
809    escape the :: from the IPv6 address. See the example below.
810
811    Example 1.20. nh_ping_rtpp usage
812 ...
813 $ kamctl fifo nh_ping_rtpp udp:192.168.2.133:8081
814 $ kamctl fifo nh_ping_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999
815 $ kamctl fifo nh_ping_rtpp all
816 ...
817
818 Chapter 2. Frequently Asked Questions
819
820    2.1. How do I migrate from "rtpproxy" or "rtpproxy-ng" to "rtpengine"?
821    2.2. Where can I find more about Kamailio?
822    2.3. Where can I post a question about this module?
823    2.4. How can I report a bug?
824
825    2.1.
826
827    How do I migrate from "rtpproxy" or "rtpproxy-ng" to "rtpengine"?
828
829    For the most part, only the names of the functions have changed, with
830    "rtpproxy" in each name replaced with "rtpengine". For example,
831    "rtpproxy_manage()" has become "rtpengine_manage()". A few name
832    duplications have also been resolved, for example there is now a single
833    "rtpengine_delete()" instead of "unforce_rtp_proxy()" and the identical
834    "rtpproxy_destroy()".
835
836    The largest difference to the old module is how flags are passed to
837    "rtpengine_offer()", "rtpengine_answer()", "rtpengine_manage()" and
838    "rtpengine_delete()". Instead of having a string of single-letter
839    flags, they now take a string of space-separated items, with each item
840    being either a single token (word) or a "key=value" pair.
841
842    For example, if you had a call "rtpproxy_offer("FRWOC+PS");", this
843    would then become:
844 rtpengine_offer("force trust-address symmetric replace-origin replace-session-co
845 nnection ICE=force RTP/SAVPF");
846
847    Finally, if you were using the second paramater (explicit media
848    address) to any of these functions, this has been replaced by the
849    "media-address=..." option within the first string of flags.
850
851    2.2.
852
853    Where can I find more about Kamailio?
854
855    Take a look at http://www.kamailio.org/.
856
857    2.3.
858
859    Where can I post a question about this module?
860
861    First at all check if your question was already answered on one of our
862    mailing lists:
863      * User Mailing List -
864        http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
865      * Developer Mailing List -
866        http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
867
868    E-mails regarding any stable Kamailio release should be sent to
869    <sr-users@lists.sip-router.org> and e-mails regarding development
870    versions should be sent to <sr-dev@lists.sip-router.org>.
871
872    If you want to keep the mail private, send it to
873    <sr-users@lists.sip-router.org>.
874
875    2.4.
876
877    How can I report a bug?
878
879    Please follow the guidelines provided at:
880    http://sip-router.org/tracker.