rtpengine Add result code for rtpengine_offer (et al) to README and regenerate README
[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. rtpengine_allow_op (integer)
67               4.5. queried_nodes_limit (integer)
68               4.6. rtpengine_retr (integer)
69               4.7. extra_id_pv (string)
70               4.8. setid_avp (string)
71               4.9. force_send_interface (string)
72               4.10. read_sdp_pv (string)
73               4.11. write_sdp_pv (string)
74               4.12. rtp_inst_pvar (string)
75               4.13. hash_table_size (integer)
76               4.14. hash_table_tout (integer)
77               4.15. db_url (string)
78               4.16. table_name (string)
79               4.17. setid_col (string)
80               4.18. url_col (string)
81               4.19. weight_col (string)
82               4.20. disabled_col (string)
83               4.21. setid_default (string)
84
85         5. Functions
86
87               5.1. set_rtpengine_set(setid[, setid])
88               5.2. rtpengine_offer([flags])
89               5.3. rtpengine_answer([flags])
90               5.4. rtpengine_delete([flags])
91               5.5. rtpengine_manage([flags])
92               5.6. start_recording()
93
94         6. Exported Pseudo Variables
95
96               6.1. $rtpstat
97
98         7. MI Commands
99
100               7.1. nh_enable_rtpp proxy_url/all 0/1
101               7.2. nh_show_rtpp proxy_url/all
102               7.3. nh_ping_rtpp proxy_url/all
103               7.4. nh_reload_rtpp
104               7.5. nh_show_hash_total
105
106    2. Frequently Asked Questions
107
108    List of Examples
109
110    1.1. Set rtpengine_sock parameter
111    1.2. Set rtpengine_disable_tout parameter
112    1.3. Set rtpengine_tout_ms parameter
113    1.4. Set rtpengine_allow_op parameter
114    1.5. Set queried_nodes_limit parameter
115    1.6. Set rtpengine_retr parameter
116    1.7. Set extra_id_pv parameter
117    1.8. Set setid_avp parameter
118    1.9. Set force_send_interface parameter
119    1.10. Set read_sdp_pv parameter
120    1.11. Set write_sdp_pv parameter
121    1.12. Set rtp_inst_pvar parameter
122    1.13. Set hash_table_size parameter
123    1.14. Set hash_table_tout parameter
124    1.15. Set db_url parameter
125    1.16. Set table_name parameter
126    1.17. Setup rtpengine table
127    1.18. Set setid_col parameter
128    1.19. Set url_col parameter
129    1.20. Set weight_col parameter
130    1.21. Set disabled_col parameter
131    1.22. Set setid_default parameter
132    1.23. set_rtpengine_set usage
133    1.24. rtpengine_offer usage
134    1.25. rtpengine_answer usage
135    1.26. rtpengine_delete usage
136    1.27. rtpengine_manage usage
137    1.28. start_recording usage
138    1.29. $rtpstat Usage
139    1.30. nh_enable_rtpp usage
140    1.31. nh_show_rtpp usage
141    1.32. nh_ping_rtpp usage
142    1.33. nh_reload_rtpp usage
143    1.34. nh_show_hash_total usage
144
145 Chapter 1. Admin Guide
146
147    Table of Contents
148
149    1. Overview
150    2. Multiple RTP proxy usage
151    3. Dependencies
152
153         3.1. Kamailio Modules
154         3.2. External Libraries or Applications
155
156    4. Parameters
157
158         4.1. rtpengine_sock (string)
159         4.2. rtpengine_disable_tout (integer)
160         4.3. rtpengine_tout_ms (integer)
161         4.4. rtpengine_allow_op (integer)
162         4.5. queried_nodes_limit (integer)
163         4.6. rtpengine_retr (integer)
164         4.7. extra_id_pv (string)
165         4.8. setid_avp (string)
166         4.9. force_send_interface (string)
167         4.10. read_sdp_pv (string)
168         4.11. write_sdp_pv (string)
169         4.12. rtp_inst_pvar (string)
170         4.13. hash_table_size (integer)
171         4.14. hash_table_tout (integer)
172         4.15. db_url (string)
173         4.16. table_name (string)
174         4.17. setid_col (string)
175         4.18. url_col (string)
176         4.19. weight_col (string)
177         4.20. disabled_col (string)
178         4.21. setid_default (string)
179
180    5. Functions
181
182         5.1. set_rtpengine_set(setid[, setid])
183         5.2. rtpengine_offer([flags])
184         5.3. rtpengine_answer([flags])
185         5.4. rtpengine_delete([flags])
186         5.5. rtpengine_manage([flags])
187         5.6. start_recording()
188
189    6. Exported Pseudo Variables
190
191         6.1. $rtpstat
192
193    7. MI Commands
194
195         7.1. nh_enable_rtpp proxy_url/all 0/1
196         7.2. nh_show_rtpp proxy_url/all
197         7.3. nh_ping_rtpp proxy_url/all
198         7.4. nh_reload_rtpp
199         7.5. nh_show_hash_total
200
201 1. Overview
202
203    This is a module that enables media streams to be proxied via an RTP
204    proxy. The only RTP proxy currently known to work with this module is
205    the Sipwise rtpengine https://github.com/sipwise/rtpengine. The
206    rtpengine module is a modified version of the original rtpproxy module
207    using a new control protocol. The module is designed to be a drop-in
208    replacement for the old module from a configuration file point of view,
209    however due to the incompatible control protocol, it only works with
210    RTP proxies which specifically support it.
211
212 2. Multiple RTP proxy usage
213
214    The rtpengine module can support multiple RTP proxies for
215    balancing/distribution and control/selection purposes.
216
217    The module allows definition of several sets of rtpproxies.
218    Load-balancing will be performed over a set and the admin has the
219    ability to choose what set should be used. The set is selected via its
220    id - the id being defined with the set. Refer to the "rtpengine_sock"
221    module parameter definition for syntax description.
222
223    The balancing inside a set is done automatically by the module based on
224    the weight of each RTP proxy from the set.
225
226    The selection of the set is done from script prior using
227    rtpengine_delete(), rtpengine_offer() or rtpengine_answer() functions -
228    see the set_rtpengine_set() function.
229
230    Another way to select the set is to define setid_avp module parameter
231    and assign setid to the defined avp before calling rtpengine_offer() or
232    rtpengine_manage() function. If forwarding of the requests fails and
233    there is another branch to try, remember to unset the avp after calling
234    rtpengine_delete() function.
235
236    For backward compatibility reasons, a set with no id take by default
237    the id 0. Also if no set is explicitly set before rtpengine_delete(),
238    rtpengine_offer() or rtpengine_answer() the 0 id set will be used.
239
240    IMPORTANT: if you use multiple sets, take care and use the same set for
241    both rtpengine_offer()/rtpengine_answer() and rtpengine_delete()!! If
242    the set was selected using setid_avp, the avp needs to be set only once
243    before rtpengine_offer() or rtpengine_manage() call.
244
245    From the current implementation point of view, the sets of rtpproxy
246    nodes are shared memory(shm), so all processes can see a common list of
247    nodes. There is no locking when setting the nodes enabled/disabled (to
248    keep the memory access as fast as possible). Thus, problems related to
249    node state might appear for concurent processes that might set the
250    nodes enabled/disabled(e.g. by fifo command). This robustness problems
251    are overcomed as follows.
252
253    If the current process sees the selected node as disabled, the node is
254    force tested before the current process actually takes the disabled
255    decision. If the test succeeds, the process will set the node as
256    enabled (but other concurrent process might still see it as disabled).
257    .
258
259    If the current process sees the selected node as enabled, it does no
260    additional checks and sends the command which will fail in case the
261    machine is actually broken. The process will set the node as disabled
262    (but other concurrent process might still see it as enabled).
263
264    The 'kamctl fifo' commands (including rtpengin ones) are executed by an
265    exclusive process which operate on the same shared memory node list.
266
267    All the nodes are pinged in the beginning by all the processes, even if
268    the node list is shared memory.
269
270 3. Dependencies
271
272    3.1. Kamailio Modules
273    3.2. External Libraries or Applications
274
275 3.1. Kamailio Modules
276
277    The following modules must be loaded before this module:
278      * tm module - (optional) if you want to have rtpengine_manage() fully
279        functional
280
281 3.2. External Libraries or Applications
282
283    The following libraries or applications must be installed before
284    running Kamailio with this module loaded:
285      * None.
286
287 4. Parameters
288
289    4.1. rtpengine_sock (string)
290    4.2. rtpengine_disable_tout (integer)
291    4.3. rtpengine_tout_ms (integer)
292    4.4. rtpengine_allow_op (integer)
293    4.5. queried_nodes_limit (integer)
294    4.6. rtpengine_retr (integer)
295    4.7. extra_id_pv (string)
296    4.8. setid_avp (string)
297    4.9. force_send_interface (string)
298    4.10. read_sdp_pv (string)
299    4.11. write_sdp_pv (string)
300    4.12. rtp_inst_pvar (string)
301    4.13. hash_table_size (integer)
302    4.14. hash_table_tout (integer)
303    4.15. db_url (string)
304    4.16. table_name (string)
305    4.17. setid_col (string)
306    4.18. url_col (string)
307    4.19. weight_col (string)
308    4.20. disabled_col (string)
309    4.21. setid_default (string)
310
311 4.1. rtpengine_sock (string)
312
313    Definition of socket(s) used to connect to (a set) RTP proxy. It may
314    specify a UNIX socket or an IPv4/IPv6 UDP socket.
315
316    Default value is "NONE" (disabled).
317
318    Example 1.1. Set rtpengine_sock parameter
319 ...
320 # single rtproxy
321 modparam("rtpengine", "rtpengine_sock", "udp:localhost:12221")
322 # multiple rtproxies for LB with weights (missing weight defaults to 1)
323 modparam("rtpengine", "rtpengine_sock",
324         "udp:localhost:12221=2 udp:localhost:12222=1")
325 # multiple sets of multiple rtproxies
326 modparam("rtpengine", "rtpengine_sock",
327         "1 == udp:localhost:12221 udp:localhost:12222")
328 modparam("rtpengine", "rtpengine_sock",
329         "2 == udp:localhost:12225")
330 ...
331
332 4.2. rtpengine_disable_tout (integer)
333
334    Once an RTP proxy was found unreachable and marked as disabled, the
335    rtpengine module will not attempt to establish communication to that
336    RTP proxy for rtpengine_disable_tout seconds.
337
338    Default value is "60".
339
340    Example 1.2. Set rtpengine_disable_tout parameter
341 ...
342 modparam("rtpengine", "rtpengine_disable_tout", 20)
343 ...
344
345 4.3. rtpengine_tout_ms (integer)
346
347    Timeout value expressed in milliseconds in waiting for reply from RTP
348    proxy.
349
350    Default value is "1000".
351
352    Example 1.3. Set rtpengine_tout_ms parameter
353 ...
354 modparam("rtpengine", "rtpengine_tout_ms", 2000)
355 ...
356
357 4.4. rtpengine_allow_op (integer)
358
359    Enable this to allow finishing the current sessions while denying new
360    sessions for the manually deactivated nodes via kamctl command i.e.
361    "disabled(permanent)" nodes. Probably the manually deactivated machine
362    is still running(did not crash).
363
364    This is useful when deactivating a node for maintanance and reject new
365    sessions but allow current ones to finish.
366
367    The behaviour is the same for a rtpengine deleted table node. When the
368    node is deleted from the table and the table reloaded (see
369    nh_reload_rtpp) the node actually is disabled(permanent) and hidden for
370    display. Next time the same node will be added in the table, and the
371    content reloaded, it will be updated and re-displayed.
372
373    Default value is "0" to keep the current behaviour.
374
375    Example 1.4. Set rtpengine_allow_op parameter
376 ...
377 modparam("rtpengine", "rtpengine_allow_op", 1)
378 ...
379
380 4.5. queried_nodes_limit (integer)
381
382    The total number of nodes inside a set (sets are configurable via
383    rtpengine_sock function) to be queried before giving up establishing a
384    session. This brings more flexibility in case checking all rtpengines
385    would take too long. Max limit is 50.
386
387    By default all nodes in a set are tried before giving up communicating
388    with the rtpengines.
389
390    Example 1.5. Set queried_nodes_limit parameter
391 ...
392 modparam("rtpengine", "queried_nodes_limit", 5)
393 ...
394
395 4.6. rtpengine_retr (integer)
396
397    How many times the module should retry to send and receive after
398    timeout was generated.
399
400    Default value is "5".
401
402    Example 1.6. Set rtpengine_retr parameter
403 ...
404 modparam("rtpengine", "rtpengine_retr", 2)
405 ...
406
407 4.7. extra_id_pv (string)
408
409    The parameter sets the PV defination to use when the "b" parameter is
410    used on rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or
411    rtpengine_manage() command.
412
413    Default is empty, the "b" parameter may not be used then.
414
415    Example 1.7. Set extra_id_pv parameter
416 ...
417 modparam("rtpengine", "extra_id_pv", "$avp(extra_id)")
418 ...
419
420 4.8. setid_avp (string)
421
422    The parameter defines an AVP that, if set, determines which RTP proxy
423    set rtpengine_offer(), rtpengine_answer(), rtpengine_delete(), and
424    rtpengine_manage() functions use.
425
426    There is no default value.
427
428    Example 1.8. Set setid_avp parameter
429 ...
430 modparam("rtpengine", "setid_avp", "$avp(setid)")
431 ...
432
433 4.9. force_send_interface (string)
434
435    Forces all control messages between the SIP proxy and the RTP proxy to
436    be sent from the specified local interface. Both IPv4 and IPv6
437    addresses are supported. If not specified, the default interface
438    selected by the operating system will be used. Note: when
439    rtpengine_sock is a IPv6 link-local address, one _must_ set this
440    parameter in order to successfully connect to RTP engine. This is
441    necessarely because OS needs additional scope_id hint to communicate
442    over IPv6 link locals. The scope_id is resolved based on the given
443    IPv6.
444
445    There is no default value.
446
447    Example 1.9. Set force_send_interface parameter
448 ...
449 modparam("rtpengine", "force_send_interface", "10.3.7.123")
450 modparam("rtpengine", "force_send_interface", "2001:8d8:1ff:10c0:9a90:96ff:fea8:
451 fd99")
452 ...
453
454 4.10. read_sdp_pv (string)
455
456    If this parameter is set to a valid AVP or script var specifier,
457    rtpengine will take the input SDP from this pv instead of the message
458    body.
459
460    There is no default value.
461
462    Example 1.10. Set read_sdp_pv parameter
463 ...
464 modparam("rtpengine", "read_sdp_pv", "$var(sdp)")
465 ...
466 route {
467         ...
468         $var(sdp) = $rb + "a=foo:bar\r\n";
469         rtpengine_manage();
470 }
471
472 4.11. write_sdp_pv (string)
473
474    If this parameter is set to a valid AVP or script var specifier, the
475    SDP returned by rtpengine in the offer/answer operations is returned in
476    the specified variable instead of the message body.
477
478    There is no default value.
479
480    Example 1.11. Set write_sdp_pv parameter
481 ...
482 modparam("rtpengine", "write_sdp_pv", "$avp(sdp)")
483 ...
484 route {
485         ...
486         rtpengine_manage();
487         set_body("$avp(sdp)a=baz123\r\n", "application/sdp");
488 }
489
490 4.12. rtp_inst_pvar (string)
491
492    A pseudo variable to store the chosen RTP Engine IP address. If this
493    parameter is set, the IP address and port of the instance chosen will
494    be stored in the given variable.
495
496    By default, this parameter is not set.
497
498    Example 1.12. Set rtp_inst_pvar parameter
499 ...
500 modparam("rtpengine", "rtp_inst_pvar", "$avp(RTP_INSTANCE)")
501 ...
502
503 4.13. hash_table_size (integer)
504
505    Size of the hash table. Default value is 256.
506
507    NOTE: If configured size is less than 1, the size will be defaulted to
508    1.
509
510    Example 1.13. Set hash_table_size parameter
511 ...
512 modparam("rtpengine", "hash_table_size", "123")
513 ...
514
515 4.14. hash_table_tout (integer)
516
517    Number of seconds after an rtpengine hash table entry is marked for
518    deletion. By default, this parameter is set to 3600 (seconds).
519
520    To maintain information about a selected rtp machine node, for a given
521    call, entries are added in a hashtable of (callid, node) pairs. When
522    command comes, lookup callid. If found, return chosen node. If not
523    found, choose a new node, insert it in the hastable and return the
524    chosen node.
525
526    NOTE: In the current implementation, the actual deletion happens on the
527    fly, while insert/remove/lookup the hastable, only for the entries in
528    the insert/remove/lookup path.
529
530    NOTE: When configuring this parameter, one should consider maximum call
531    time VS share memory for unfinished calls.
532
533    Example 1.14. Set hash_table_tout parameter
534 ...
535 modparam("rtpengine", "hash_table_tout", "300")
536 ...
537
538 4.15. db_url (string)
539
540    The rtpengine datablase url. If present and valid, it activates
541    database mode. Node information is read from database, not from config.
542
543    By default, the datablase url is NULL (not set).
544
545    Example 1.15. Set db_url parameter
546 ...
547 modparam("rtpengine", "db_url", "mysql://pass@localhost/db")
548 ...
549
550 4.16. table_name (string)
551
552    The rtpengine table name. If database mode is activated (i.e. valid
553    db_url), set the name of rtpengine table, on startup.
554
555    By default, the rtpengine table name is "rtpengine".
556
557    NOTE: One needs to add the version of the rtpengine table in the
558    version table. The current version is version 1.
559
560    Example 1.16. Set table_name parameter
561 ...
562 modparam("rtpengine", "table_name", "rtpengine_table_name")
563 ...
564
565    Example 1.17. Setup rtpengine table
566 mysql> describe rtpengine;
567 +----------+------------------+------+-----+---------------------+-------+
568 | Field    | Type             | Null | Key | Default             | Extra |
569 +----------+------------------+------+-----+---------------------+-------+
570 | setid    | int(10) unsigned | NO   | PRI | 0                   |       |
571 | url      | varchar(64)      | NO   | PRI | NULL                |       |
572 | weight   | int(10) unsigned | NO   |     | 1                   |       |
573 | disabled | int(1)           | NO   |     | 0                   |       |
574 | stamp    | datetime         | NO   |     | 1900-01-01 00:00:01 |       |
575 +----------+------------------+------+-----+---------------------+-------+
576
577 mysql> select * from rtpengine;
578 +-------+---------------------------+--------+----------+---------------------+
579 | setid | url                       | weight | disabled | stamp               |
580 +-------+---------------------------+--------+----------+---------------------+
581 |     0 | udp:rtpproxy1.domain:8800 |      1 |        0 | 2016-03-10 10:30:54 |
582 |     0 | udp:rtpproxy2.domain:8800 |      1 |        1 | 2016-03-10 10:30:54 |
583 +-------+---------------------------+--------+----------+---------------------+
584
585 mysql> select * from version;
586 +---------------------------+---------------+
587 | table_name                | table_version |
588 +---------------------------+---------------+
589 | rtpengine                 |             1 |
590 +---------------------------+---------------+
591
592 4.17. setid_col (string)
593
594    Column name in the rtpengine table. If database mode is activated (i.e.
595    valid db_url), set the setid of rtp nodes according to this column, on
596    startup. The MySQL value for this column should be INT UNSIGNED.
597
598    By default, the column name is "setid".
599
600    Example 1.18. Set setid_col parameter
601 ...
602 modparam("rtpengine", "setid_col", "setid_column_name")
603 ...
604
605 4.18. url_col (string)
606
607    Column name in the rtpengine table. If database mode is activated (i.e.
608    valid db_url), set the url of rtp nodes according to this column, on
609    startup. The MySQL value for this column should be VARCHAR.
610
611    By default, the column name is "url".
612
613    Example 1.19. Set url_col parameter
614 ...
615 modparam("rtpengine", "url_col", "url_column_name")
616 ...
617
618 4.19. weight_col (string)
619
620    Column name in the rtpengine table. If database mode is activated (i.e.
621    valid db_url), set the weight of rtp nodes according to this column, on
622    startup. The column value has priority over the URL weight. The MySQL
623    value for this column should be INT UNSIGNED.
624
625    By default, the column name is "weight".
626
627    Example 1.20. Set weight_col parameter
628 ...
629 modparam("rtpengine", "weight_col", "weight_column_name")
630 ...
631
632 4.20. disabled_col (string)
633
634    Column name in the rtpengine table. If database mode is activated (i.e.
635    valid db_url), set the state of rtp nodes according to this column, on
636    startup. The MySQL value for this column should be INT.
637
638    By default, the column name is "disabled".
639
640    Example 1.21. Set disabled_col parameter
641 ...
642 modparam("rtpengine", "disabled_col", "disabled_column_name")
643 ...
644
645 4.21. setid_default (string)
646
647    The default set of nodes to be used.
648
649    By default, the setid is 0.
650
651    NOTE that if setid_avp is configured, this value will be ignored and
652    the active set will be chosen according to the setid_avp.
653
654    Example 1.22. Set setid_default parameter
655 ...
656 modparam("rtpengine", "setid_default", 11)
657 ...
658
659 5. Functions
660
661    5.1. set_rtpengine_set(setid[, setid])
662    5.2. rtpengine_offer([flags])
663    5.3. rtpengine_answer([flags])
664    5.4. rtpengine_delete([flags])
665    5.5. rtpengine_manage([flags])
666    5.6. start_recording()
667
668 5.1. set_rtpengine_set(setid[, setid])
669
670    Sets the ID of the RTP proxy set to be used for the next
671    rtpengine_delete(), rtpengine_offer(), rtpengine_answer() or
672    rtpengine_manage() command. The parameter can be an integer or a config
673    variable holding an integer.
674
675    A second set ID can be specified to daisy-chain two RTP proxies. The
676    two set IDs must be distinct from each other and there must not be any
677    overlap in the proxies present in both sets. In this use case, the
678    request (offer, answer, etc) is first sent to an RTP proxy from the
679    first set, which rewrites the SDP body and sends it back to the module.
680    The rewritten SDP body is then used to make another request to an RTP
681    proxy from the second set, which rewrites the SDP body another time and
682    sends it back to the module to be placed back into the SIP message.
683    This is useful if you have a set of RTP proxies that the caller must
684    use, and another distinct set of RTP proxies that the callee must use.
685    This is supported by all rtpengine commands except rtpengine_manage().
686
687    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
688    BRANCH_ROUTE.
689
690    Example 1.23. set_rtpengine_set usage
691 ...
692 set_rtpengine_set("2");
693 rtpengine_offer();
694 ...
695
696 5.2. rtpengine_offer([flags])
697
698    Rewrites SDP body to ensure that media is passed through an RTP proxy.
699    To be invoked on INVITE for the cases the SDP bodies are in INVITE and
700    200 OK and on 200 OK when SDP bodies are in 200 OK and ACK.
701
702    The function will return true on success and false (-1) on various
703    failures, like using rtp_engine_offer() on a SIP MESSAGE request or
704    communication with rtpengine fails.
705
706    Meaning of the parameters is as follows:
707      * flags - flags to turn on some features.
708        The "flags" string is a list of space-separated items. Each item is
709        either an individual token, or a token in "key=value" format. The
710        possible tokens are described below.
711           + via-branch=... - Include the "branch" value of one of the
712             "Via" headers in the request to the RTP proxy. Possible values
713             are: "1" - use the first "Via" header; "2" - use the second
714             "Via" header; "auto" - use the first "Via" header if this is a
715             request, or the second one if this is a reply; "extra" - don't
716             take the value from a header, but instead use the value of the
717             "extra_id_pv" variable. This can be used to create one media
718             session per branch on the RTP proxy. When sending a subsequent
719             "delete" command to the RTP proxy, you can then stop just the
720             session for a specific branch when passing the flag '1' or '2'
721             in the "rtpengine_delete", or stop all sessions for a call
722             when not passing one of those two flags there. This is
723             especially useful if you have serially forked call scenarios
724             where the RTP proxy gets an "offer" command for a new branch,
725             and then a "delete" command for the previous branch, which
726             would otherwise delete the full call, breaking the subsequent
727             "answer" for the new branch. This flag is only supported by
728             the Sipwise rtpengine RTP proxy at the moment!
729           + asymmetric - flags that UA from which message is received
730             doesn't support symmetric RTP. Disables learning of endpoint
731             addresses in the Sipwise rtpengine proxy.
732           + force-answer - force "answer", that is, only rewrite SDP when
733             corresponding session already exists in the RTP proxy. By
734             default is on when the session is to be completed.
735           + direction=... - this option specifies a logical network
736             interface and should be given exactly twice. It enables RTP
737             bridging between different addresses or networks of the same
738             family (e.g. IPv4 to IPv4). The first instance of the option
739             specifies the interface that the originator of this message
740             should be using, while the second instance specifies the
741             interface that the target should be using. For example, if the
742             SIP message was sent by an endpoint on a private network and
743             will be sent to an endpoint on the public internet, you would
744             use "direction=priv direction=pub" if those two logical
745             network interfaces were called "priv" and "pub" in your RTP
746             proxy's configuration respectively. The direction must only be
747             specified in for initial SDP offer; answers or subsequent
748             offers can omit this option.
749           + internal, external - shorthand for "direction=internal" and
750             "direction=external" respectively. Useful for brevity or as
751             legacy option if the RTP proxy only supports two network
752             interfaces instead of multiple, arbitrarily named ones.
753           + auto-bridge - this flag an alternative to the "internal" and
754             "external" flags in order to do automatic bridging between
755             IPv4 on the "internal network" and IPv6 on the "external
756             network". Instead of explicitly instructing the RTP proxy to
757             select a particular address family, the distinction is done by
758             the given IP in the SDP body by the RTP proxy itself. Not
759             supported by Sipwise rtpengine.
760           + address-family=... - instructs the RTP proxy that the
761             recipient of this SDP body expects to see addresses of a
762             particular family. Possible values are "IP4" and "IP6". For
763             example, if the SDP body contains IPv4 addresses but the
764             recipient only speaks IPv6, you would use "address-family=IP6"
765             to bridge between the two address families.
766             Sipwise rtpengine remembers the address family preference of
767             each party after it has seen an SDP body from them. This means
768             that normally it is only necessary to explicitly specify the
769             address family in the "offer", but not in the "answer".
770             Note: Please note, that this will only work properly with
771             non-dual-stack user-agents or with dual-stack clients
772             according to RFC6157 (which suggest ICE for Dual-Stack
773             implementations). This short-cut will not work properly with
774             RFC4091 (ANAT) compatible clients, which suggests having
775             different m-lines with different IP-protocols grouped
776             together.
777           + force - instructs the RTP proxy to ignore marks inserted by
778             another RTP proxy in transit to indicate that the session is
779             already goes through another proxy. Allows creating a chain of
780             proxies. Not supported and ignored by Sipwise rtpengine.
781           + trust-address - flags that IP address in SDP should be
782             trusted. Starting with rtpengine 3.8, this is the default
783             behaviour. In older versions, without this flag the RTP proxy
784             ignores the address in the SDP and uses source address of the
785             SIP message as media address which is passed to the RTP proxy.
786           + SIP-source-address - the opposite of trust-address. Restores
787             the old default behaviour of ignoring endpoint addresses in
788             the SDP body.
789           + replace-origin - flags that IP from the origin description
790             (o=) should be also changed.
791           + replace-session-connection - flags to change the session-level
792             SDP connection (c=) IP if media description also includes
793             connection information.
794           + symmetric - flags that for the UA from which message is
795             received, support symmetric RTP must be forced. Does nothing
796             with the Sipwise rtpengine proxy as it is the default.
797           + repacketize=NN - requests the RTP proxy to perform
798             re-packetization of RTP traffic coming from the UA which has
799             sent the current message to increase or decrease payload size
800             per each RTP packet forwarded if possible. The NN is the
801             target payload size in ms, for the most codecs its value
802             should be in 10ms increments, however for some codecs the
803             increment could differ (e.g. 30ms for GSM or 20ms for G.723).
804             The RTP proxy would select the closest value supported by the
805             codec. This feature could be used for significantly reducing
806             bandwith overhead for low bitrate codecs, for example with
807             G.729 going from 10ms to 100ms saves two thirds of the network
808             bandwith. Not supported by Sipwise rtpengine.
809           + ICE=... - controls the RTP proxy's behaviour regarding ICE
810             attributes within the SDP body. Possible values are: "force" -
811             discard any ICE attributes already present in the SDP body and
812             then generate and insert new ICE data, leaving itself as the
813             only ICE candidates; "force-relay" - discard any "relay" type
814             ICE attributes already present in the SDP body and then
815             generate and insert itself as the only ICE "relay" candidates;
816             "remove" instructs the RTP proxy to discard any ICE attributes
817             and not insert any new ones into the SDP. The default (if no
818             "ICE=..." is given at all), new ICE data will only be
819             generated if no ICE was present in the SDP originally;
820             otherwise the RTP proxy will only insert itself as additional
821             ICE candidate. Other SDP substitutions (c=, m=, etc) are
822             unaffected by this flag.
823           + RTP, SRTP, AVP, AVPF - These flags control the RTP transport
824             protocol that should be used towards the recipient of the SDP.
825             If none of them are specified, the protocol given in the SDP
826             is left untouched. Otherwise, the "SRTP" flag indicates that
827             SRTP should be used, while "RTP" indicates that SRTP should
828             not be used. "AVPF" indicates that the advanced RTCP profile
829             with feedback messages should be used, and "AVP" indicates
830             that the regular RTCP profile should be used. See also the
831             next set of flags below.
832           + RTP/AVP, RTP/SAVP, RTP/AVPF, RTP/SAVPF - these serve as an
833             alternative, more explicit way to select between the different
834             RTP protocols and profiles supported by the RTP proxy. For
835             example, giving the flag "RTP/SAVPF" has the same effect as
836             giving the two flags "SRTP AVPF".
837           + to-tag - force inclusion of the "To" tag. Normally, the "To"
838             tag is always included when present, except for "delete"
839             messages. Including the "To" tag in a "delete" messages allows
840             you to be more selective about which dialogues within a call
841             are being torn down.
842           + rtcp-mux-demux - if rtcp-mux (RFC 5761) was offered, make the
843             RTP proxy accept the offer, but not offer it to the recipient
844             of this message.
845           + rtcp-mux-reject - if rtcp-mux was offered, make the RTP proxy
846             reject the offer, but still offer it to the recipient. Can be
847             combined with "rtcp-mux-offer" to always offer it.
848           + rtcp-mux-offer - make the RTP proxy offer rtcp-mux to the
849             recipient of this message, regardless of whether it was
850             offered originally or not.
851           + rtcp-mux-accept - if rtcp-mux was offered, make the RTP proxy
852             accept the offer and also offer it to the recipient of this
853             message. Can be combined with "rtcp-mux-offer" to always offer
854             it.
855           + media-address=... - force a particular media address to be
856             used in the SDP body. Address family is detected
857             automatically.
858           + TOS=... - change the IP TOS value for all outgoing RTP packets
859             within the entire call in both directions. Only honoured in an
860             "offer", ignored for an "answer". Valid values are 0 through
861             255, given in decimal. If this option is not specified, the
862             TOS value will revert to the default TOS (normally 184). A
863             value of -1 may be used to leave the currently used TOS
864             unchanged.
865           + delete-delay=... - override the default delay (in seconds)
866             before a call is actually deleted from memory. Can be set to
867             zero to effectuate immediate deletion. This option only makes
868             sense for delete operations.
869           + strict-source - instructs the RTP proxy to check the source
870             addresses of all incoming RTP packets and drop the packets if
871             the address doesn't match.
872           + media-handover - the antithesis of strict-source. Instructs
873             the RTP proxy not only to accept mismatching RTP source
874             addresses (as it normally would), but also to accept them as
875             the new endpoint address of the opposite media flow. Not
876             recommended as it allows media streams to be hijacked by an
877             attacker.
878           + DTLS=... - influence the behaviour of DTLS-SRTP. Possible
879             values are "no" or "off" to suppress offering or accepting
880             DTLS-SRTP, and "passive" to prefer participating in DTLS-SRTP
881             in a passive role.
882           + SDES-off - don't offer SDES when it normally would. In an SRTP
883             context, this leaves DTLS-SRTP as the only other option.
884           + SDES-unencrypted_srtp, SDES-unencrypted_srtcp,
885             SDES-unauthenticated_srtp - these directly reflect the SDES
886             session parameters from RFC 4568 and will make the RTP proxy
887             offer these parameters when offering SDES.
888           + SDES-encrypted_srtp, SDES-encrypted_srtcp,
889             SDES-authenticated_srtp - the opposites of the flags above.
890             Useful if accepting these parameters is not desired and they
891             should be rejected instead.
892
893    This function can be used from ANY_ROUTE.
894
895    Example 1.24. rtpengine_offer usage
896 route {
897 ...
898     if (is_method("INVITE")) {
899         if (has_body("application/sdp")) {
900             if (rtpengine_offer())
901                 t_on_reply("1");
902         } else {
903             t_on_reply("2");
904         }
905     }
906     if (is_method("ACK") && has_body("application/sdp"))
907         rtpengine_answer();
908 ...
909 }
910
911 onreply_route[1]
912 {
913 ...
914     if (has_body("application/sdp"))
915         rtpengine_answer();
916 ...
917 }
918
919 onreply_route[2]
920 {
921 ...
922     if (has_body("application/sdp"))
923         rtpengine_offer();
924 ...
925 }
926
927 5.3. rtpengine_answer([flags])
928
929    Rewrites SDP body to ensure that media is passed through an RTP proxy.
930    To be invoked on 200 OK for the cases the SDP bodies are in INVITE and
931    200 OK and on ACK when SDP bodies are in 200 OK and ACK.
932
933    See rtpengine_offer() function description above for the meaning of the
934    parameters.
935
936    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
937    FAILURE_ROUTE, BRANCH_ROUTE.
938
939    Example 1.25. rtpengine_answer usage
940
941    See rtpengine_offer() function example above for example.
942
943 5.4. rtpengine_delete([flags])
944
945    Tears down the RTPProxy session for the current call.
946
947    See rtpengine_offer() function description above for the meaning of the
948    parameters. Note that not all flags make sense for a "delete".
949
950    This function can be used from ANY_ROUTE.
951
952    Example 1.26. rtpengine_delete usage
953 ...
954 rtpengine_delete();
955 ...
956
957 5.5. rtpengine_manage([flags])
958
959    Manage the RTPProxy session - it combines the functionality of
960    rtpengine_offer(), rtpengine_answer() and rtpengine_delete(), detecting
961    internally based on message type and method which one to execute.
962
963    It can take the same parameters as rtpengine_offer(). The flags
964    parameter to rtpengine_manage() can be a configuration variable
965    containing the flags as a string.
966
967    Functionality:
968      * If INVITE with SDP, then do rtpengine_offer()
969      * If INVITE with SDP, when the tm module is loaded, mark transaction
970        with internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
971        rtpengine_answer()
972      * If ACK with SDP, then do rtpengine_answer()
973      * If BYE or CANCEL, or called within a FAILURE_ROUTE[], then do
974        rtpengine_delete()
975      * If reply to INVITE with code >= 300 do rtpengine_delete()
976      * If reply with SDP to INVITE having code 1xx and 2xx, then do
977        rtpengine_answer() if the request had SDP or tm is not loaded,
978        otherwise do rtpengine_offer()
979
980    This function can be used from ANY_ROUTE.
981
982    Example 1.27. rtpengine_manage usage
983 ...
984 rtpengine_manage();
985 ...
986
987 5.6. start_recording()
988
989    This function will send a signal to the RTP proxy to record the RTP
990    stream on the RTP proxy. This function is not supported by Sipwise
991    rtpengine at the moment!
992
993    This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
994
995    Example 1.28. start_recording usage
996 ...
997 start_recording();
998 ...
999
1000 6. Exported Pseudo Variables
1001
1002    6.1. $rtpstat
1003
1004 6.1. $rtpstat
1005
1006    Returns the RTP statistics from the RTP proxy. The RTP statistics from
1007    the RTP proxy are provided as a string and it does contain several
1008    packet counters. The statistics must be retrieved before the session is
1009    deleted (before rtpengine_delete()).
1010
1011    Example 1.29. $rtpstat Usage
1012 ...
1013     append_hf("X-RTP-Statistics: $rtpstat\r\n");
1014 ...
1015
1016 7. MI Commands
1017
1018    7.1. nh_enable_rtpp proxy_url/all 0/1
1019    7.2. nh_show_rtpp proxy_url/all
1020    7.3. nh_ping_rtpp proxy_url/all
1021    7.4. nh_reload_rtpp
1022    7.5. nh_show_hash_total
1023
1024 7.1. nh_enable_rtpp proxy_url/all 0/1
1025
1026    Enables a RTP proxy if the second parameter value is greater than 0.
1027    Disables it if a zero value is given. The first parameter is either a
1028    specific RTP proxy url (exactly as defined in the config file) or the
1029    keyword all. The second parameter value must be a number in decimal.
1030
1031    When try to enable the RTP proxy, an application ping command is sent
1032    to it. If it fails, the proxy is not enabled. Displays success or fail
1033    when try to enable/disable.
1034
1035    NOTE: If a RTP proxy is defined multiple times (in the same or diferent
1036    sets), all of its instances will be enabled/disabled.
1037
1038    NOTE: If a RTP proxy is in the disabled permanent state and one tries
1039    to enable it, even if the ping fails, it is moved to a disabled
1040    temporary state and a recheck_ticks are given to it. While the
1041    recheck_ticks are grater than 0, the proxy is considered disabled
1042    temporary, and it is not taken into consideration for sending data.
1043    When the recheck_ticks are 0, the proxy is retested when trying to send
1044    data(not automatically retested), and data can be send to it on
1045    success.
1046
1047    NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
1048    escape the :: from the IPv6 address. See the example below.
1049
1050    Example 1.30. nh_enable_rtpp usage
1051 ...
1052 $ kamctl fifo nh_enable_rtpp udp:192.168.2.133:8081 0
1053 $ kamctl fifo nh_enable_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999 1
1054 $ kamctl fifo nh_enable_rtpp all 1
1055 ...
1056
1057 7.2. nh_show_rtpp proxy_url/all
1058
1059    Displays all the RTP proxies and their information: set and status
1060    (disabled or not, weight and recheck_ticks). If a RTP proxy has been
1061    disabled by nh_enable_rtpp mi command a "(permanent)" quote will appear
1062    when printing the disabled status. This is to differentiate from a
1063    temporary disable due to the proxy being not found responsive by
1064    kamailio. In addition, when disabled permanent, recheck_ticks have no
1065    meaning and "N\A" is printed instead of the value.
1066
1067    It takes either a specific RTP proxy url (exactly as defined in the
1068    config file) or the keyword all as a parameter.
1069
1070    NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
1071    escape the :: from the IPv6 address. See the example below.
1072
1073    Example 1.31. nh_show_rtpp usage
1074 ...
1075 $ kamctl fifo nh_show_rtpp udp:192.168.2.133:8081
1076 $ kamctl fifo nh_show_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999
1077 $ kamctl fifo nh_show_rtpp all
1078 ...
1079
1080 7.3. nh_ping_rtpp proxy_url/all
1081
1082    Sends an application ping command to the RTP proxy. If the proxy does
1083    not respond, it will be disabled, but not permanent. If the proxy
1084    responds, no action is taken. Displays the ping result, i.e. success or
1085    fail when try to ping.
1086
1087    It takes either a specific RTP proxy url (exactly as defined in the
1088    config file) or the keyword all as a parameter.
1089
1090    NOTE: When specify the IPv6 RTP proxy url one must prefix it with :: to
1091    escape the :: from the IPv6 address. See the example below.
1092
1093    Example 1.32. nh_ping_rtpp usage
1094 ...
1095 $ kamctl fifo nh_ping_rtpp udp:192.168.2.133:8081
1096 $ kamctl fifo nh_ping_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999
1097 $ kamctl fifo nh_ping_rtpp all
1098 ...
1099
1100 7.4. nh_reload_rtpp
1101
1102    Reloads the database node table content if configured. Returns specific
1103    message related to success, failure and no db_url configured.
1104
1105    NOTE: The current behaviour updates the nodes state or creates new ones
1106    or hides old ones, based on the database content. If allow_op modparam
1107    is enabled, the sessions are still allowed to finish for the hidden old
1108    nodes.
1109
1110    Example 1.33. nh_reload_rtpp usage
1111 ...
1112 $ kamctl fifo nh_reload_rtpp
1113 ...
1114
1115 7.5. nh_show_hash_total
1116
1117    Print the total number of hash entries in the hash table at a given
1118    moment.
1119
1120    Example 1.34. nh_show_hash_total usage
1121 ...
1122 $ kamctl fifo nh_show_hash_total
1123 ...
1124
1125 Chapter 2. Frequently Asked Questions
1126
1127    2.1. How do I migrate from "rtpproxy" or "rtpproxy-ng" to "rtpengine"?
1128    2.2. Where can I find more about Kamailio?
1129    2.3. Where can I post a question about this module?
1130    2.4. How can I report a bug?
1131
1132    2.1.
1133
1134    How do I migrate from "rtpproxy" or "rtpproxy-ng" to "rtpengine"?
1135
1136    For the most part, only the names of the functions have changed, with
1137    "rtpproxy" in each name replaced with "rtpengine". For example,
1138    "rtpproxy_manage()" has become "rtpengine_manage()". A few name
1139    duplications have also been resolved, for example there is now a single
1140    "rtpengine_delete()" instead of "unforce_rtp_proxy()" and the identical
1141    "rtpproxy_destroy()".
1142
1143    The largest difference to the old module is how flags are passed to
1144    "rtpengine_offer()", "rtpengine_answer()", "rtpengine_manage()" and
1145    "rtpengine_delete()". Instead of having a string of single-letter
1146    flags, they now take a string of space-separated items, with each item
1147    being either a single token (word) or a "key=value" pair.
1148
1149    For example, if you had a call "rtpproxy_offer("FRWOC+PS");", this
1150    would then become:
1151 rtpengine_offer("force trust-address symmetric replace-origin replace-session-co
1152 nnection ICE=force RTP/SAVPF");
1153
1154    Finally, if you were using the second paramater (explicit media
1155    address) to any of these functions, this has been replaced by the
1156    "media-address=..." option within the first string of flags.
1157
1158    2.2.
1159
1160    Where can I find more about Kamailio?
1161
1162    Take a look at http://www.kamailio.org/.
1163
1164    2.3.
1165
1166    Where can I post a question about this module?
1167
1168    First at all check if your question was already answered on one of our
1169    mailing lists:
1170      * User Mailing List -
1171        http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
1172      * Developer Mailing List -
1173        http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
1174
1175    E-mails regarding any stable Kamailio release should be sent to
1176    <sr-users@lists.sip-router.org> and e-mails regarding development
1177    versions should be sent to <sr-dev@lists.sip-router.org>.
1178
1179    If you want to keep the mail private, send it to
1180    <sr-users@lists.sip-router.org>.
1181
1182    2.4.
1183
1184    How can I report a bug?
1185
1186    Please follow the guidelines provided at:
1187    http://sip-router.org/tracker.