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