keepalive: early start of OPTIONS checking
[sip-router] / src / modules / rtpengine / doc / rtpengine_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
7 %docentities;
8
9 ]>
10
11 <!-- Module User's Guide -->
12
13 <chapter>
14
15         <title>&adminguide;</title>
16
17         <section>
18         <title>Overview</title>
19         <para>
20                 This is a module that enables media streams to be proxied
21                 via an &rtp; proxy. The only &rtp; proxy currently known to work
22                 with this module is the Sipwise rtpengine
23                 <ulink url="https://github.com/sipwise/rtpengine"></ulink>.
24                 The rtpengine module is a modified version of the original
25                 rtpproxy module using a new control protocol. The module is
26                 designed to be a drop-in replacement for the old module from
27                 a configuration file point of view, however due to the
28                 incompatible control protocol, it only works with &rtp; proxies
29                 which specifically support it.
30         </para>
31         </section>
32
33         <section>
34         <title>Usage With Multiple RTPEngine Instances</title>
35         <para>
36                 The rtpengine module can support multiple RTPEngine instances for
37                 balancing/distribution and control/selection purposes.
38         </para>
39         <para>
40                 The module allows definition of several sets of RTPEngines.
41                 Load-balancing will be performed over a set and the admin has the
42                 ability to choose what set should be used. The set is selected via
43                 its id - the id being defined with the set. Refer to the
44                 <quote>rtpengine_sock</quote> module parameter definition for syntax
45                 description.
46         </para>
47         <para>
48                 The balancing inside a set is done automatically by the module based on
49                 the weight of each RTPEngine from the set.
50         </para>
51         <para>
52                 The selection of the set is done from script prior using
53                 rtpengine_delete(), rtpengine_offer() or rtpengine_answer()
54                 functions - see the set_rtpengine_set() function.
55         </para>
56         <para>
57                 Another way to select the set is to define setid_avp
58                 module parameter and assign setid to the defined avp
59                 before calling rtpengine_offer() or rtpengine_manage()
60                 function.  If forwarding of the requests fails and
61                 there is another branch to try, remember to unset the
62                 avp after calling rtpengine_delete() function.
63         </para>
64         <para>
65                 For backward compatibility reasons, a set with no id take by default
66                 the id 0. Also if no set is explicitly set before
67                 rtpengine_delete(), rtpengine_offer() or rtpengine_answer()
68                 the 0 id set will be used.
69         </para>
70         <para>
71                 IMPORTANT: if you use multiple sets, take care and use the same set for
72                 both rtpengine_offer()/rtpengine_answer() and rtpengine_delete()!!
73                 If the set was selected using setid_avp, the avp needs to be
74                 set only once before rtpengine_offer() or rtpengine_manage() call.
75         </para>
76         <para>
77                 From the current implementation point of view, the sets of rtpengine nodes
78                 are in shared memory(shm), so all processes can see a common list of nodes.
79                 There is no locking when setting the nodes enabled/disabled (to keep the
80                 memory access as fast as possible). Thus, problems related to node state
81                 might appear for concurrent processes that might set the nodes
82                 enabled/disabled(e.g. by fifo command). This robustness problems are overcome as follows.
83         </para>
84
85         <para>
86                 If the current process sees the selected node as disabled, the node is
87                 <emphasis>force tested</emphasis> before the current process actually
88                 takes the disabled decision. If the test succeeds, the process will set
89                 the node as enabled (but other concurrent process might still see it as disabled).
90 .
91         </para>
92
93         <para>
94                 If the current process sees the selected node as enabled, it does no additional checks
95                 and sends the command which will fail in case the machine is actually broken.
96                 The process will set the node as disabled (but other concurrent process might still see it as enabled).
97         </para>
98
99         <para>
100                 The 'kamctl fifo' commands (including rtpengine ones) are executed by an exclusive
101                 process which operate on the same shared memory node list.
102         </para>
103
104         <para>
105                 All the nodes are pinged in the beginning by all the processes,
106                 even if the node list is shared memory.
107         </para>
108         </section>
109
110         <section>
111         <title>Dependencies</title>
112         <section>
113                 <title>&kamailio; Modules</title>
114                 <para>
115                 The following modules must be loaded before this module:
116                         <itemizedlist>
117                         <listitem>
118                         <para>
119                                 <emphasis>tm module</emphasis> - (optional) if you want to
120                                 have rtpengine_manage() fully functional
121                         </para>
122                         </listitem>
123                         </itemizedlist>
124                 </para>
125         </section>
126         <section>
127                 <title>External Libraries or Applications</title>
128                 <para>
129                 The following libraries or applications must be installed before
130                 running &kamailio; with this module loaded:
131                         <itemizedlist>
132                         <listitem>
133                         <para>
134                                 <emphasis>None</emphasis>.
135                         </para>
136                         </listitem>
137                         </itemizedlist>
138                 </para>
139         </section>
140         </section>
141
142         <section>
143         <title>Parameters</title>
144         <section id="rtpengine.p.rtpengine_sock">
145                 <title><varname>rtpengine_sock</varname> (string)</title>
146                 <para>
147                 Definition of socket(s) used to connect to (a set) &rtp; proxy. It may
148                 specify a UNIX socket or an IPv4/IPv6 UDP socket.
149                 </para>
150                 <para>
151                 <emphasis>
152                         Default value is <quote>NONE</quote> (disabled).
153                 </emphasis>
154                 </para>
155                 <example>
156                 <title>Set <varname>rtpengine_sock</varname> parameter</title>
157                 <programlisting format="linespecific">
158 ...
159 # single rtproxy
160 modparam("rtpengine", "rtpengine_sock", "udp:localhost:12221")
161 # multiple rtproxies for LB with weights (missing weight defaults to 1)
162 modparam("rtpengine", "rtpengine_sock",
163         "udp:localhost:12221=2 udp:localhost:12222=1")
164 # multiple sets of multiple rtproxies
165 modparam("rtpengine", "rtpengine_sock",
166         "1 == udp:localhost:12221 udp:localhost:12222")
167 modparam("rtpengine", "rtpengine_sock",
168         "2 == udp:localhost:12225")
169 ...
170 </programlisting>
171                 </example>
172         </section>
173         <section id="rtpengine.p.rtpengine_disable_tout">
174                 <title><varname>rtpengine_disable_tout</varname> (integer)</title>
175                 <para>
176                 Once an &rtp; proxy was found unreachable and marked as disabled, the rtpengine
177                 module will not attempt to establish communication to that &rtp; proxy for
178                 rtpengine_disable_tout seconds.
179                 </para>
180                 <para>
181                 <emphasis>
182                         Default value is <quote>60</quote>.
183                 </emphasis>
184                 </para>
185                 <para>
186                         Can be set at runtime, e.g.:
187                         <programlisting>
188                         $ &sercmd; cfg.set_now_int rtpengine rtpengine_disable_tout 20
189                         </programlisting>
190                 </para>
191                 <example>
192                 <title>Set <varname>rtpengine_disable_tout</varname> parameter</title>
193                 <programlisting format="linespecific">
194 ...
195 modparam("rtpengine", "rtpengine_disable_tout", 20)
196 ...
197 </programlisting>
198                 </example>
199         </section>
200         <section id="rtpengine.p.aggressive_redetection">
201                 <title><varname>aggressive_redetection</varname> (integer)</title>
202                 <para>
203                 This parameter determines what happens when all potential rtpengines are found
204                 to be unreachable. If enabled, the sip server will send pings to all rtpengines,
205                 else no rtpengine will be queried until its rtpengine_disable_tout timeout passes.
206                 </para>
207                 <para>
208                 <emphasis>
209                         Default value is <quote>1</quote>.
210                 </emphasis>
211                 </para>
212                 <para>
213                         Can be set at runtime, e.g.:
214                         <programlisting>
215                         $ &sercmd; cfg.set_now_int rtpengine aggressive_redetection 0
216                         </programlisting>
217                 </para>
218                 <example>
219                 <title>Set <varname>aggressive_redetection</varname> parameter</title>
220                 <programlisting format="linespecific">
221 ...
222 modparam("rtpengine", "aggressive_redetection", 0)
223 ...
224 </programlisting>
225                 </example>
226         </section>
227         <section id="rtpengine.p.rtpengine_tout_ms">
228                 <title><varname>rtpengine_tout_ms</varname> (integer)</title>
229                 <para>
230                 Timeout value expressed in milliseconds in waiting for reply from &rtp; proxy.
231                 </para>
232                 <para>
233                 <emphasis>
234                         Default value is <quote>1000</quote>.
235                 </emphasis>
236                 </para>
237                 <para>
238                         Can be set at runtime, e.g.:
239                         <programlisting>
240                         $ &sercmd; cfg.set_now_int rtpengine rtpengine_tout_ms 1000
241                         </programlisting>
242                 </para>
243                 <example>
244                 <title>Set <varname>rtpengine_tout_ms</varname> parameter</title>
245                 <programlisting format="linespecific">
246 ...
247 modparam("rtpengine", "rtpengine_tout_ms", 2000)
248 ...
249 </programlisting>
250                 </example>
251         </section>
252         <section id="rtpengine.p.rtpengine_allow_op">
253                 <title><varname>rtpengine_allow_op</varname> (integer)</title>
254                 <para>
255                 Enable this to allow finishing the current sessions while denying new sessions for the
256                 <emphasis>manually deactivated nodes </emphasis> via kamctl command i.e. "disabled(permanent)" nodes.
257                 Probably the manually deactivated machine is still running(did not crash).
258                 </para>
259                 <para>
260                 This is <emphasis>useful</emphasis> when deactivating a node for maintenance and reject new sessions but allow current ones to finish.
261                 </para>
262                 <para>
263                 The behaviour is the same for a rtpengine deleted table node.
264                 When the node is deleted from the table and the table reloaded (see nh_reload_rtpp) the node actually is disabled(permanent) and hidden for display.
265                 Next time the same node will be added in the table, and the content reloaded, it will be updated and re-displayed.
266                 </para>
267                 <para>
268                 <emphasis>
269                 Default value is <quote>0</quote> to keep the current behaviour.
270                 </emphasis>
271                 </para>
272                 <example>
273                 <title>Set <varname>rtpengine_allow_op</varname> parameter</title>
274                 <programlisting format="linespecific">
275 ...
276 modparam("rtpengine", "rtpengine_allow_op", 1)
277 ...
278 </programlisting>
279                 </example>
280         </section>
281         <section id="rtpengine.p.queried_nodes_limit">
282                 <title><varname>queried_nodes_limit</varname> (integer)</title>
283                 <para>
284                 The total number of nodes inside a set (sets are configurable via rtpengine_sock function) to be queried
285                 before giving up establishing a session. This brings more flexibility in case checking all rtpengines
286                 would take too long. Max limit is 30.
287                 </para>
288                 <para>
289                 <emphasis>
290                         By default all nodes in a set are tried before giving up communicating with the rtpengines.
291                 </emphasis>
292                 </para>
293                 <para>
294                         Can be set at runtime, e.g.:
295                         <programlisting>
296                         $ &sercmd; cfg.set_now_int rtpengine queried_nodes_limit 5
297                         </programlisting>
298                 </para>
299                 <example>
300                 <title>Set <varname>queried_nodes_limit</varname> parameter</title>
301                 <programlisting format="linespecific">
302 ...
303 modparam("rtpengine", "queried_nodes_limit", 5)
304 ...
305 </programlisting>
306                 </example>
307         </section>
308         <section id="rtpengine.p.rtpengine_retr">
309                 <title><varname>rtpengine_retr</varname> (integer)</title>
310                 <para>
311                 How many times the module should retry to send and receive after
312                 timeout was generated.
313                 </para>
314                 <para>
315                 <emphasis>
316                         Default value is <quote>5</quote>.
317                 </emphasis>
318                 </para>
319                 <para>
320                         Can be set at runtime, e.g.:
321                         <programlisting>
322                         $ &sercmd; cfg.set_now_int rtpengine rtpengine_retr 5
323                         </programlisting>
324                 </para>
325                 <example>
326                 <title>Set <varname>rtpengine_retr</varname> parameter</title>
327                 <programlisting format="linespecific">
328 ...
329 modparam("rtpengine", "rtpengine_retr", 2)
330 ...
331 </programlisting>
332                 </example>
333         </section>
334         <section id="rtpengine.p.extra_id_pv">
335                 <title><varname>extra_id_pv</varname> (string)</title>
336                 <para>
337                         The parameter sets the PV definition to use when the <quote>via-branch</quote>
338                         parameter is used on rtpengine_delete(), rtpengine_offer(),
339                         rtpengine_answer() or rtpengine_manage() command.
340                 </para><para>
341                         Default is empty, the <quote>via-branch</quote> parameter may not be used then.
342                 </para>
343                 <example>
344                 <title>Set <varname>extra_id_pv</varname> parameter</title>
345                 <programlisting format="linespecific">
346 ...
347 modparam("rtpengine", "extra_id_pv", "$avp(extra_id)")
348 ...
349 </programlisting>
350                 </example>
351         </section>
352
353         <section id="rtpengine.p.setid_avp">
354                 <title><varname>setid_avp</varname> (string)</title>
355                 <para>
356                         The parameter defines an AVP that, if set,
357                         determines which &rtp; proxy set
358                         rtpengine_offer(), rtpengine_answer(),
359                         rtpengine_delete(), and rtpengine_manage()
360                         functions use.
361                 </para>
362                 <para>
363                         There is no default value.
364                 </para>
365                 <example>
366                 <title>Set <varname>setid_avp</varname> parameter</title>
367 <programlisting format="linespecific">
368 ...
369 modparam("rtpengine", "setid_avp", "$avp(setid)")
370 ...
371 </programlisting>
372                 </example>
373         </section>
374
375         <section id="rtpengine.p.force_send_interface">
376                 <title><varname>force_send_interface</varname> (string)</title>
377                 <para>
378                         Forces all control messages between the &sip; proxy and
379                         the &rtp; proxy to be sent from the specified local
380                         interface. Both IPv4 and IPv6 addresses are supported. If
381                         not specified, the default interface selected by the
382                         operating system will be used.
383                         Note: when rtpengine_sock is a IPv6 link-local address,
384                         one _must_ set this parameter in order to successfully connect to RTP engine.
385                         This is necessarily because OS needs additional scope_id hint to communicate
386                         over IPv6 link locals. The scope_id is resolved based on the given IPv6.
387                 </para>
388                 <para>
389                         There is no default value.
390                 </para>
391                 <example>
392                 <title>Set <varname>force_send_interface</varname> parameter</title>
393 <programlisting format="linespecific">
394 ...
395 modparam("rtpengine", "force_send_interface", "10.3.7.123")
396 modparam("rtpengine", "force_send_interface", "2001:8d8:1ff:10c0:9a90:96ff:fea8:fd99")
397 ...
398 </programlisting>
399                 </example>
400         </section>
401
402         <section id="rtpengine.p.read_sdp_pv">
403                 <title><varname>read_sdp_pv</varname> (string)</title>
404                 <para>
405                         If this parameter is set to a valid AVP or script var specifier, rtpengine
406                         will take the input SDP from this pv instead of the message body.
407                 </para>
408                 <para>
409                         There is no default value.
410                 </para>
411                 <example>
412                 <title>Set <varname>read_sdp_pv</varname> parameter</title>
413 <programlisting format="linespecific">
414 ...
415 modparam("rtpengine", "read_sdp_pv", "$var(sdp)")
416 ...
417 route {
418         ...
419         $var(sdp) = $rb + "a=foo:bar\r\n";
420         rtpengine_manage();
421 }
422 </programlisting>
423                 </example>
424         </section>
425
426         <section id="rtpengine.p.write_sdp_pv">
427                 <title><varname>write_sdp_pv</varname> (string)</title>
428                 <para>
429                         If this parameter is set to a valid AVP or script var specifier, the
430             SDP returned by rtpengine in the offer/answer operations
431             is returned in the specified variable instead of the
432             message body.
433                 </para>
434                 <para>
435                         There is no default value.
436                 </para>
437                 <example>
438                 <title>Set <varname>write_sdp_pv</varname> parameter</title>
439 <programlisting format="linespecific">
440 ...
441 modparam("rtpengine", "write_sdp_pv", "$avp(sdp)")
442 ...
443 route {
444         ...
445         rtpengine_manage();
446         set_body("$avp(sdp)a=baz123\r\n", "application/sdp");
447 }
448 </programlisting>
449                 </example>
450         </section>
451
452         <section id="rtpengine.p.rtp_inst_pvar">
453                 <title><varname>rtp_inst_pvar</varname> (string)</title>
454                 <para>
455                         A pseudo variable to store the chosen RTP Engine IP address.
456                         If this parameter is set, the IP address and port of the instance chosen will be stored in the given variable.
457                 </para>
458                 <para>
459                         By default, this parameter is not set.
460                 </para>
461                 <example>
462                 <title>Set <varname>rtp_inst_pvar</varname> parameter</title>
463 <programlisting format="linespecific">
464 ...
465 modparam("rtpengine", "rtp_inst_pvar", "$avp(RTP_INSTANCE)")
466 ...
467 </programlisting>
468                 </example>
469         </section>
470
471         <section id="rtpengine.p.hash_table_size">
472                 <title><varname>hash_table_size</varname> (integer)</title>
473                 <para>
474                         Size of the hash table. Default value is 256.
475                 </para>
476                 <para>
477                         NOTE: If configured size is <emphasis>less than</emphasis> 1, the size will be defaulted to 1.
478                 </para>
479                 <example>
480                 <title>Set <varname>hash_table_size</varname> parameter</title>
481 <programlisting format="linespecific">
482 ...
483 modparam("rtpengine", "hash_table_size", 123)
484 ...
485 </programlisting>
486                 </example>
487         </section>
488
489         <section id="rtpengine.p.hash_table_tout">
490                 <title><varname>hash_table_tout</varname> (integer)</title>
491                 <para>
492                         Number of seconds after an rtpengine hash table entry is marked for deletion.
493                         By default, this parameter is set to 3600 (seconds).
494                 </para>
495                 <para>
496                         To maintain information about a selected rtp machine node, for a given call, entries are added in a hashtable of (callid, node) pairs.
497                         When command comes, lookup callid. If found, return chosen node. If not found, choose a new node, insert it in the hastable and return the chosen node.
498                 </para>
499                 <para>
500                         NOTE: In the current implementation, the actual deletion happens <emphasis>on the fly</emphasis>,
501                         while insert/remove/lookup the hastable, <emphasis>only</emphasis> for the entries in the insert/remove/lookup path.
502                 </para>
503                 <para>
504                         NOTE: When configuring this parameter, one should consider maximum call time VS share memory for unfinished calls.
505                 </para>
506                 <example>
507                 <title>Set <varname>hash_table_tout</varname> parameter</title>
508 <programlisting format="linespecific">
509 ...
510 modparam("rtpengine", "hash_table_tout", 300)
511 ...
512 </programlisting>
513                 </example>
514         </section>
515
516
517
518
519         <section id="rtpengine.p.db_url">
520                 <title><varname>db_url</varname> (string)</title>
521                 <para>
522                         The rtpengine datablase url. If present and valid, it activates database mode.
523                         Node information is read from database, not from config.
524                 </para>
525                 <para>
526                         By default, the datablase url is NULL (not set).
527                 </para>
528                 <example>
529                 <title>Set <varname>db_url</varname> parameter</title>
530 <programlisting format="linespecific">
531 ...
532 modparam("rtpengine", "db_url", "mysql://pass@localhost/db")
533 ...
534 </programlisting>
535                 </example>
536         </section>
537
538
539         <section id="rtpengine.p.table_name">
540                 <title><varname>table_name</varname> (string)</title>
541                 <para>
542                         The rtpengine table name. If database mode is activated (i.e. valid db_url),
543                         set the name of rtpengine table, on startup.
544                 </para>
545                 <para>
546                         By default, the rtpengine table name is "rtpengine".
547                 </para>
548                 <para>
549                         NOTE: One needs to add the version of the rtpengine table in the version table.
550                         The current version is version 1.
551                 </para>
552                 <example>
553                 <title>Set <varname>table_name</varname> parameter</title>
554 <programlisting format="linespecific">
555 ...
556 modparam("rtpengine", "table_name", "rtpengine_table_name")
557 ...
558 </programlisting>
559                 </example>
560
561                 <example>
562                 <title>Setup <varname>rtpengine</varname> table</title>
563 <programlisting format="linespecific">
564 mysql> describe rtpengine;
565 +----------+------------------+------+-----+---------------------+-------+
566 | Field    | Type             | Null | Key | Default             | Extra |
567 +----------+------------------+------+-----+---------------------+-------+
568 | setid    | int(10) unsigned | NO   | PRI | 0                   |       |
569 | url      | varchar(64)      | NO   | PRI | NULL                |       |
570 | weight   | int(10) unsigned | NO   |     | 1                   |       |
571 | disabled | int(1)           | NO   |     | 0                   |       |
572 | stamp    | datetime         | NO   |     | 1900-01-01 00:00:01 |       |
573 +----------+------------------+------+-----+---------------------+-------+
574
575 mysql> select * from rtpengine;
576 +-------+----------------------------+--------+----------+---------------------+
577 | setid | url                        | weight | disabled | stamp               |
578 +-------+----------------------------+--------+----------+---------------------+
579 |     0 | udp:rtpengine1.domain:8800 |      1 |        0 | 2016-03-10 10:30:54 |
580 |     0 | udp:rtpengine2.domain:8800 |      1 |        1 | 2016-03-10 10:30:54 |
581 +-------+----------------------------+--------+----------+---------------------+
582
583 mysql> select * from version;
584 +---------------------------+---------------+
585 | table_name                | table_version |
586 +---------------------------+---------------+
587 | rtpengine                 |             1 |
588 +---------------------------+---------------+
589 </programlisting>
590                 </example>
591         </section>
592
593
594         <section id="rtpengine.p.setid_col">
595                 <title><varname>setid_col</varname> (string)</title>
596                 <para>
597                         Column name in the rtpengine table. If database mode is activated (i.e. valid db_url),
598                         set the setid of rtp nodes according to this column, on startup.
599                         The MySQL value for this column should be INT UNSIGNED.
600                 </para>
601                 <para>
602                         By default, the column name is "setid".
603                 </para>
604                 <example>
605                 <title>Set <varname>setid_col</varname> parameter</title>
606 <programlisting format="linespecific">
607 ...
608 modparam("rtpengine", "setid_col", "setid_column_name")
609 ...
610 </programlisting>
611                 </example>
612         </section>
613
614
615         <section id="rtpengine.p.url_col">
616                 <title><varname>url_col</varname> (string)</title>
617                 <para>
618                         Column name in the rtpengine table. If database mode is activated (i.e. valid db_url),
619                         set the url of rtp nodes according to this column, on startup.
620                         The MySQL value for this column should be VARCHAR.
621                 </para>
622                 <para>
623                         By default, the column name is "url".
624                 </para>
625                 <example>
626                 <title>Set <varname>url_col</varname> parameter</title>
627 <programlisting format="linespecific">
628 ...
629 modparam("rtpengine", "url_col", "url_column_name")
630 ...
631 </programlisting>
632                 </example>
633         </section>
634
635
636         <section id="rtpengine.p.weight_col">
637                 <title><varname>weight_col</varname> (string)</title>
638                 <para>
639                         Column name in the rtpengine table. If database mode is activated (i.e. valid db_url),
640                         set the weight of rtp nodes according to this column, on startup. The column value has
641                         priority over the URL weight.
642                         The MySQL value for this column should be INT UNSIGNED.
643                 </para>
644                 <para>
645                         By default, the column name is "weight".
646                 </para>
647                 <example>
648                 <title>Set <varname>weight_col</varname> parameter</title>
649 <programlisting format="linespecific">
650 ...
651 modparam("rtpengine", "weight_col", "weight_column_name")
652 ...
653 </programlisting>
654                 </example>
655         </section>
656
657
658         <section id="rtpengine.p.disabled_col">
659                 <title><varname>disabled_col</varname> (string)</title>
660                 <para>
661                         Column name in the rtpengine table. If database mode is activated (i.e. valid db_url),
662                         set the state of rtp nodes according to this column, on startup.
663                         The MySQL value for this column should be INT.
664                 </para>
665                 <para>
666                         By default, the column name is "disabled".
667                 </para>
668                 <example>
669                 <title>Set <varname>disabled_col</varname> parameter</title>
670 <programlisting format="linespecific">
671 ...
672 modparam("rtpengine", "disabled_col", "disabled_column_name")
673 ...
674 </programlisting>
675                 </example>
676         </section>
677
678
679         <section id="rtpengine.p.setid_default">
680                 <title><varname>setid_default</varname> (integer)</title>
681                 <para>
682                         The default set of nodes to be used.
683                 </para>
684                 <para>
685                         By default, the setid is 0.
686                 </para>
687                 <para>
688                         NOTE that if setid_avp is configured, this value will be ignored and
689                         the active set will be chosen according to the setid_avp.
690                 </para>
691                 <example>
692                 <title>Set <varname>setid_default</varname> parameter</title>
693 <programlisting format="linespecific">
694 ...
695 modparam("rtpengine", "setid_default", 11)
696 ...
697 </programlisting>
698                 </example>
699         </section>
700
701
702         <section id="rtpengine.p.media_duration">
703                 <title><varname>media_duration</varname> (string)</title>
704                 <para>
705                         The name of a pseudovariable to be filled in with the length of the
706                         media being played back after a call to <quote>play_media</quote>,
707                         expressed in milliseconds. It's set to -1 if the length of the media
708                         could not be determined.
709                 </para>
710                 <para>
711                         By default, this parameter is not set.
712                 </para>
713                 <example>
714                 <title>Set <varname>media_duration</varname> parameter</title>
715 <programlisting format="linespecific">
716 ...
717 modparam("rtpengine", "media_duration", "$avp(MEDIA_DURATION)")
718 ...
719 </programlisting>
720                 </example>
721         </section>
722
723
724         <section id="rtpengine.p.mos_min_pv">
725                 <title><varname>mos_min_pv</varname> (string)</title>
726                 <para>
727                         The name of a pseudovariable to hold the minimum encountered MOS value for the call.
728                         The value typically has a range of 1.0 through 5.0.
729                 </para>
730                 <para>
731                         There is no default value.
732                 </para>
733                 <para>
734                         This value is filled in after invoking<quote>rtpengine_delete</quote>,
735                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
736                         command resulted in a deletion of the call (or call branch).
737                 </para>
738                 <example>
739                 <title>Set <varname>mos_min_pv</varname> parameter</title>
740 <programlisting format="linespecific">
741 ...
742 modparam("rtpengine", "mos_min_pv", "$avp(mos_min)")
743 ...
744 </programlisting>
745                 </example>
746         </section>
747
748         <section id="rtpengine.p.mos_min_at_pv">
749                 <title><varname>mos_min_at_pv</varname> (string)</title>
750                 <para>
751                         The name of a pseudovariable to hold the timestamp of when the minimum MOS value
752                         was encountered during the call, such as <quote>0:30</quote> for 30 seconds
753                         after the start of the call.
754                 </para>
755                 <para>
756                         There is no default value.
757                 </para>
758                 <para>
759                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
760                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
761                         command resulted in a deletion of the call (or call branch).
762                 </para>
763                 <example>
764                 <title>Set <varname>mos_min_at_pv</varname> parameter</title>
765 <programlisting format="linespecific">
766 ...
767 modparam("rtpengine", "mos_min_at_pv", "$avp(mos_min_at)")
768 ...
769 </programlisting>
770                 </example>
771         </section>
772
773         <section id="rtpengine.p.mos_min_packetloss_pv">
774                 <title><varname>mos_min_packetloss_pv</varname> (string)</title>
775                 <para>
776                         The name of a pseudovariable to hold the amount of packetloss in percent
777                         at the time the minimum MOS value was encountered;
778                 </para>
779                 <para>
780                         There is no default value.
781                 </para>
782                 <para>
783                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
784                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
785                         command resulted in a deletion of the call (or call branch).
786                 </para>
787                 <example>
788                 <title>Set <varname>mos_min_packetloss_pv</varname> parameter</title>
789 <programlisting format="linespecific">
790 ...
791 modparam("rtpengine", "mos_min_packetloss_pv", "$avp(mos_min_packetloss)")
792 ...
793 </programlisting>
794                 </example>
795         </section>
796
797         <section id="rtpengine.p.mos_min_jitter_pv">
798                 <title><varname>mos_min_jitter_pv</varname> (string)</title>
799                 <para>
800                         The name of a pseudovariable to hold the amount of jitter in milliseconds
801                         at the time the minimum MOS value was encountered;
802                 </para>
803                 <para>
804                         There is no default value.
805                 </para>
806                 <para>
807                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
808                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
809                         command resulted in a deletion of the call (or call branch).
810                 </para>
811                 <example>
812                 <title>Set <varname>mos_min_jitter_pv</varname> parameter</title>
813 <programlisting format="linespecific">
814 ...
815 modparam("rtpengine", "mos_min_jitter_pv", "$avp(mos_min_jitter)")
816 ...
817 </programlisting>
818                 </example>
819         </section>
820
821         <section id="rtpengine.p.mos_min_roundtrip_pv">
822                 <title><varname>mos_min_roundtrip_pv</varname> (string)</title>
823                 <para>
824                         The name of a pseudovariable to hold the packet round-trip time in milliseconds
825                         at the time the minimum MOS value was encountered;
826                 </para>
827                 <para>
828                         There is no default value.
829                 </para>
830                 <para>
831                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
832                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
833                         command resulted in a deletion of the call (or call branch).
834                 </para>
835                 <example>
836                 <title>Set <varname>mos_min_roundtrip_pv</varname> parameter</title>
837 <programlisting format="linespecific">
838 ...
839 modparam("rtpengine", "mos_min_roundtrip_pv", "$avp(mos_min_roundtrip)")
840 ...
841 </programlisting>
842                 </example>
843         </section>
844
845
846         <section id="rtpengine.p.mos_max_pv">
847                 <title><varname>mos_max_pv</varname> (string)</title>
848                 <para>
849                         The name of a pseudovariable to hold the maximum encountered MOS value for the call.
850                         The value typically has a range of 1.0 through 5.0.
851                 </para>
852                 <para>
853                         There is no default value.
854                 </para>
855                 <para>
856                         This value is filled in after invoking<quote>rtpengine_delete</quote>,
857                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
858                         command resulted in a deletion of the call (or call branch).
859                 </para>
860                 <example>
861                 <title>Set <varname>mos_max_pv</varname> parameter</title>
862 <programlisting format="linespecific">
863 ...
864 modparam("rtpengine", "mos_max_pv", "$avp(mos_max)")
865 ...
866 </programlisting>
867                 </example>
868         </section>
869
870         <section id="rtpengine.p.mos_max_at_pv">
871                 <title><varname>mos_max_at_pv</varname> (string)</title>
872                 <para>
873                         The name of a pseudovariable to hold the timestamp of when the maximum MOS value
874                         was encountered during the call, such as <quote>0:30</quote> for 30 seconds
875                         after the start of the call.
876                 </para>
877                 <para>
878                         There is no default value.
879                 </para>
880                 <para>
881                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
882                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
883                         command resulted in a deletion of the call (or call branch).
884                 </para>
885                 <example>
886                 <title>Set <varname>mos_max_at_pv</varname> parameter</title>
887 <programlisting format="linespecific">
888 ...
889 modparam("rtpengine", "mos_max_at_pv", "$avp(mos_max_at)")
890 ...
891 </programlisting>
892                 </example>
893         </section>
894
895         <section id="rtpengine.p.mos_max_packetloss_pv">
896                 <title><varname>mos_max_packetloss_pv</varname> (string)</title>
897                 <para>
898                         The name of a pseudovariable to hold the amount of packetloss in percent
899                         at the time the maximum MOS value was encountered;
900                 </para>
901                 <para>
902                         There is no default value.
903                 </para>
904                 <para>
905                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
906                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
907                         command resulted in a deletion of the call (or call branch).
908                 </para>
909                 <example>
910                 <title>Set <varname>mos_max_packetloss_pv</varname> parameter</title>
911 <programlisting format="linespecific">
912 ...
913 modparam("rtpengine", "mos_max_packetloss_pv", "$avp(mos_max_packetloss)")
914 ...
915 </programlisting>
916                 </example>
917         </section>
918
919         <section id="rtpengine.p.mos_max_jitter_pv">
920                 <title><varname>mos_max_jitter_pv</varname> (string)</title>
921                 <para>
922                         The name of a pseudovariable to hold the amount of jitter in milliseconds
923                         at the time the maximum MOS value was encountered;
924                 </para>
925                 <para>
926                         There is no default value.
927                 </para>
928                 <para>
929                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
930                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
931                         command resulted in a deletion of the call (or call branch).
932                 </para>
933                 <example>
934                 <title>Set <varname>mos_max_jitter_pv</varname> parameter</title>
935 <programlisting format="linespecific">
936 ...
937 modparam("rtpengine", "mos_max_jitter_pv", "$avp(mos_max_jitter)")
938 ...
939 </programlisting>
940                 </example>
941         </section>
942
943         <section id="rtpengine.p.mos_max_roundtrip_pv">
944                 <title><varname>mos_max_roundtrip_pv</varname> (string)</title>
945                 <para>
946                         The name of a pseudovariable to hold the packet round-trip time in milliseconds
947                         at the time the maximum MOS value was encountered;
948                 </para>
949                 <para>
950                         There is no default value.
951                 </para>
952                 <para>
953                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
954                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
955                         command resulted in a deletion of the call (or call branch).
956                 </para>
957                 <example>
958                 <title>Set <varname>mos_max_roundtrip_pv</varname> parameter</title>
959 <programlisting format="linespecific">
960 ...
961 modparam("rtpengine", "mos_max_roundtrip_pv", "$avp(mos_max_roundtrip)")
962 ...
963 </programlisting>
964                 </example>
965         </section>
966
967         <section id="rtpengine.p.mos_average_pv">
968                 <title><varname>mos_average_pv</varname> (string)</title>
969                 <para>
970                         The name of a pseudovariable to hold the average (median) MOS value for the call.
971                         The value typically has a range of 1.0 through 5.0.
972                 </para>
973                 <para>
974                         There is no default value.
975                 </para>
976                 <para>
977                         This value is filled in after invoking<quote>rtpengine_delete</quote>,
978                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
979                         command resulted in a deletion of the call (or call branch).
980                 </para>
981                 <example>
982                 <title>Set <varname>mos_average_pv</varname> parameter</title>
983 <programlisting format="linespecific">
984 ...
985 modparam("rtpengine", "mos_average_pv", "$avp(mos_average)")
986 ...
987 </programlisting>
988                 </example>
989         </section>
990
991         <section id="rtpengine.p.mos_average_packetloss_pv">
992                 <title><varname>mos_average_packetloss_pv</varname> (string)</title>
993                 <para>
994                         The name of a pseudovariable to hold the average (median) amount of packetloss
995                         in percent
996                         present throughout the call.
997                 </para>
998                 <para>
999                         There is no default value.
1000                 </para>
1001                 <para>
1002                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1003                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1004                         command resulted in a deletion of the call (or call branch).
1005                 </para>
1006                 <example>
1007                 <title>Set <varname>mos_average_packetloss_pv</varname> parameter</title>
1008 <programlisting format="linespecific">
1009 ...
1010 modparam("rtpengine", "mos_average_packetloss_pv", "$avp(mos_average_packetloss)")
1011 ...
1012 </programlisting>
1013                 </example>
1014         </section>
1015
1016         <section id="rtpengine.p.mos_average_jitter_pv">
1017                 <title><varname>mos_average_jitter_pv</varname> (string)</title>
1018                 <para>
1019                         The name of a pseudovariable to hold the average (median) amount of jitter
1020                         in milliseconds
1021                         present throughout the call.
1022                 </para>
1023                 <para>
1024                         There is no default value.
1025                 </para>
1026                 <para>
1027                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1028                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1029                         command resulted in a deletion of the call (or call branch).
1030                 </para>
1031                 <example>
1032                 <title>Set <varname>mos_average_jitter_pv</varname> parameter</title>
1033 <programlisting format="linespecific">
1034 ...
1035 modparam("rtpengine", "mos_average_jitter_pv", "$avp(mos_average_jitter)")
1036 ...
1037 </programlisting>
1038                 </example>
1039         </section>
1040
1041         <section id="rtpengine.p.mos_average_roundtrip_pv">
1042                 <title><varname>mos_average_roundtrip_pv</varname> (string)</title>
1043                 <para>
1044                         The name of a pseudovariable to hold the average (median) packet round-trip
1045                         time in milliseconds
1046                         present throughout the call.
1047                 </para>
1048                 <para>
1049                         There is no default value.
1050                 </para>
1051                 <para>
1052                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1053                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1054                         command resulted in a deletion of the call (or call branch).
1055                 </para>
1056                 <example>
1057                 <title>Set <varname>mos_average_roundtrip_pv</varname> parameter</title>
1058 <programlisting format="linespecific">
1059 ...
1060 modparam("rtpengine", "mos_average_roundtrip_pv", "$avp(mos_average_roundtrip)")
1061 ...
1062 </programlisting>
1063                 </example>
1064         </section>
1065
1066         <section id="rtpengine.p.mos_average_samples_pv">
1067                 <title><varname>mos_average_samples_pv</varname> (string)</title>
1068                 <para>
1069                         The name of a pseudovariable to hold the number of samples used to determine
1070                         the other <quote>average</quote> MOS data points.
1071                 </para>
1072                 <para>
1073                         There is no default value.
1074                 </para>
1075                 <para>
1076                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1077                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1078                         command resulted in a deletion of the call (or call branch).
1079                 </para>
1080                 <example>
1081                 <title>Set <varname>mos_average_samples_pv</varname> parameter</title>
1082 <programlisting format="linespecific">
1083 ...
1084 modparam("rtpengine", "mos_average_samples_pv", "$avp(mos_average_samples)")
1085 ...
1086 </programlisting>
1087                 </example>
1088         </section>
1089
1090
1091         <section id="rtpengine.p.mos_A_label_pv">
1092                 <title><varname>mos_A_label_pv</varname> (string)</title>
1093                 <para>
1094                         The name of a pseudovariable to hold a custom label used in rtpengine signalling.
1095                         If set, all the statistics pseudovariables with the <quote>_A</quote> suffix will
1096                         be filled in
1097                         with statistics only from the call legs that match the label given in this
1098                         variable.
1099                 </para>
1100                 <para>
1101                         There is no default value.
1102                 </para>
1103                 <example>
1104                 <title>Set <varname>mos_A_label_pv</varname> parameter</title>
1105 <programlisting format="linespecific">
1106 ...
1107 modparam("rtpengine", "mos_A_label_pv", "$avp(mos_A_label)")
1108 ...
1109 </programlisting>
1110                 </example>
1111         </section>
1112
1113
1114         <section id="rtpengine.p.mos_min_A_pv">
1115                 <title><varname>mos_min_A_pv</varname> (string)</title>
1116                 <para>
1117                         The name of a pseudovariable to hold the minimum encountered MOS value for the call.
1118                         The value typically has a range of 1.0 through 5.0.
1119                 </para>
1120                 <para>
1121                         There is no default value.
1122                 </para>
1123                 <para>
1124                         This value is filled in after invoking<quote>rtpengine_delete</quote>,
1125                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1126                         command resulted in a deletion of the call (or call branch).
1127                 </para>
1128                 <para>
1129                         Only call legs matching the rtpengine label given in the <quote>mos_A_label_pv</quote>
1130                         will be used in calculating this statistics value.
1131                 </para>
1132                 <example>
1133                 <title>Set <varname>mos_min_A_pv</varname> parameter</title>
1134 <programlisting format="linespecific">
1135 ...
1136 modparam("rtpengine", "mos_min_A_pv", "$avp(mos_min_A)")
1137 ...
1138 </programlisting>
1139                 </example>
1140         </section>
1141
1142         <section id="rtpengine.p.mos_min_at_A_pv">
1143                 <title><varname>mos_min_at_A_pv</varname> (string)</title>
1144                 <para>
1145                         The name of a pseudovariable to hold the timestamp of when the minimum MOS value
1146                         was encountered during the call, such as <quote>0:30</quote> for 30 seconds
1147                         after the start of the call.
1148                 </para>
1149                 <para>
1150                         There is no default value.
1151                 </para>
1152                 <para>
1153                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1154                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1155                         command resulted in a deletion of the call (or call branch).
1156                 </para>
1157                 <para>
1158                         Only call legs matching the rtpengine label given in the <quote>mos_A_label_pv</quote>
1159                         will be used in calculating this statistics value.
1160                 </para>
1161                 <example>
1162                 <title>Set <varname>mos_min_at_A_pv</varname> parameter</title>
1163 <programlisting format="linespecific">
1164 ...
1165 modparam("rtpengine", "mos_min_at_A_pv", "$avp(mos_min_at_A)")
1166 ...
1167 </programlisting>
1168                 </example>
1169         </section>
1170
1171         <section id="rtpengine.p.mos_min_packetloss_A_pv">
1172                 <title><varname>mos_min_packetloss_A_pv</varname> (string)</title>
1173                 <para>
1174                         The name of a pseudovariable to hold the amount of packetloss in percent
1175                         at the time the minimum MOS value was encountered;
1176                 </para>
1177                 <para>
1178                         There is no default value.
1179                 </para>
1180                 <para>
1181                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1182                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1183                         command resulted in a deletion of the call (or call branch).
1184                 </para>
1185                 <para>
1186                         Only call legs matching the rtpengine label given in the <quote>mos_A_label_pv</quote>
1187                         will be used in calculating this statistics value.
1188                 </para>
1189                 <example>
1190                 <title>Set <varname>mos_min_packetloss_A_pv</varname> parameter</title>
1191 <programlisting format="linespecific">
1192 ...
1193 modparam("rtpengine", "mos_min_packetloss_A_pv", "$avp(mos_min_packetloss_A)")
1194 ...
1195 </programlisting>
1196                 </example>
1197         </section>
1198
1199         <section id="rtpengine.p.mos_min_jitter_A_pv">
1200                 <title><varname>mos_min_jitter_A_pv</varname> (string)</title>
1201                 <para>
1202                         The name of a pseudovariable to hold the amount of jitter in milliseconds
1203                         at the time the minimum MOS value was encountered;
1204                 </para>
1205                 <para>
1206                         There is no default value.
1207                 </para>
1208                 <para>
1209                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1210                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1211                         command resulted in a deletion of the call (or call branch).
1212                 </para>
1213                 <para>
1214                         Only call legs matching the rtpengine label given in the <quote>mos_A_label_pv</quote>
1215                         will be used in calculating this statistics value.
1216                 </para>
1217                 <example>
1218                 <title>Set <varname>mos_min_jitter_A_pv</varname> parameter</title>
1219 <programlisting format="linespecific">
1220 ...
1221 modparam("rtpengine", "mos_min_jitter_A_pv", "$avp(mos_min_jitter_A)")
1222 ...
1223 </programlisting>
1224                 </example>
1225         </section>
1226
1227         <section id="rtpengine.p.mos_min_roundtrip_A_pv">
1228                 <title><varname>mos_min_roundtrip_A_pv</varname> (string)</title>
1229                 <para>
1230                         The name of a pseudovariable to hold the packet round-trip time in milliseconds
1231                         at the time the minimum MOS value was encountered;
1232                 </para>
1233                 <para>
1234                         There is no default value.
1235                 </para>
1236                 <para>
1237                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1238                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1239                         command resulted in a deletion of the call (or call branch).
1240                 </para>
1241                 <para>
1242                         Only call legs matching the rtpengine label given in the <quote>mos_A_label_pv</quote>
1243                         will be used in calculating this statistics value.
1244                 </para>
1245                 <example>
1246                 <title>Set <varname>mos_min_roundtrip_A_pv</varname> parameter</title>
1247 <programlisting format="linespecific">
1248 ...
1249 modparam("rtpengine", "mos_min_roundtrip_A_pv", "$avp(mos_min_roundtrip_A)")
1250 ...
1251 </programlisting>
1252                 </example>
1253         </section>
1254
1255
1256         <section id="rtpengine.p.mos_max_A_pv">
1257                 <title><varname>mos_max_A_pv</varname> (string)</title>
1258                 <para>
1259                         The name of a pseudovariable to hold the maximum encountered MOS value for the call.
1260                         The value typically has a range of 1.0 through 5.0.
1261                 </para>
1262                 <para>
1263                         There is no default value.
1264                 </para>
1265                 <para>
1266                         This value is filled in after invoking<quote>rtpengine_delete</quote>,
1267                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1268                         command resulted in a deletion of the call (or call branch).
1269                 </para>
1270                 <para>
1271                         Only call legs matching the rtpengine label given in the <quote>mos_A_label_pv</quote>
1272                         will be used in calculating this statistics value.
1273                 </para>
1274                 <example>
1275                 <title>Set <varname>mos_max_A_pv</varname> parameter</title>
1276 <programlisting format="linespecific">
1277 ...
1278 modparam("rtpengine", "mos_max_A_pv", "$avp(mos_max_A)")
1279 ...
1280 </programlisting>
1281                 </example>
1282         </section>
1283
1284         <section id="rtpengine.p.mos_max_at_A_pv">
1285                 <title><varname>mos_max_at_A_pv</varname> (string)</title>
1286                 <para>
1287                         The name of a pseudovariable to hold the timestamp of when the maximum MOS value
1288                         was encountered during the call, such as <quote>0:30</quote> for 30 seconds
1289                         after the start of the call.
1290                 </para>
1291                 <para>
1292                         There is no default value.
1293                 </para>
1294                 <para>
1295                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1296                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1297                         command resulted in a deletion of the call (or call branch).
1298                 </para>
1299                 <para>
1300                         Only call legs matching the rtpengine label given in the <quote>mos_A_label_pv</quote>
1301                         will be used in calculating this statistics value.
1302                 </para>
1303                 <example>
1304                 <title>Set <varname>mos_max_at_A_pv</varname> parameter</title>
1305 <programlisting format="linespecific">
1306 ...
1307 modparam("rtpengine", "mos_max_at_A_pv", "$avp(mos_max_at_A)")
1308 ...
1309 </programlisting>
1310                 </example>
1311         </section>
1312
1313         <section id="rtpengine.p.mos_max_packetloss_A_pv">
1314                 <title><varname>mos_max_packetloss_A_pv</varname> (string)</title>
1315                 <para>
1316                         The name of a pseudovariable to hold the amount of packetloss in percent
1317                         at the time the maximum MOS value was encountered;
1318                 </para>
1319                 <para>
1320                         There is no default value.
1321                 </para>
1322                 <para>
1323                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1324                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1325                         command resulted in a deletion of the call (or call branch).
1326                 </para>
1327                 <para>
1328                         Only call legs matching the rtpengine label given in the <quote>mos_A_label_pv</quote>
1329                         will be used in calculating this statistics value.
1330                 </para>
1331                 <example>
1332                 <title>Set <varname>mos_max_packetloss_A_pv</varname> parameter</title>
1333 <programlisting format="linespecific">
1334 ...
1335 modparam("rtpengine", "mos_max_packetloss_A_pv", "$avp(mos_max_packetloss_A)")
1336 ...
1337 </programlisting>
1338                 </example>
1339         </section>
1340
1341         <section id="rtpengine.p.mos_max_jitter_A_pv">
1342                 <title><varname>mos_max_jitter_A_pv</varname> (string)</title>
1343                 <para>
1344                         The name of a pseudovariable to hold the amount of jitter in milliseconds
1345                         at the time the maximum MOS value was encountered;
1346                 </para>
1347                 <para>
1348                         There is no default value.
1349                 </para>
1350                 <para>
1351                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1352                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1353                         command resulted in a deletion of the call (or call branch).
1354                 </para>
1355                 <para>
1356                         Only call legs matching the rtpengine label given in the <quote>mos_A_label_pv</quote>
1357                         will be used in calculating this statistics value.
1358                 </para>
1359                 <example>
1360                 <title>Set <varname>mos_max_jitter_A_pv</varname> parameter</title>
1361 <programlisting format="linespecific">
1362 ...
1363 modparam("rtpengine", "mos_max_jitter_A_pv", "$avp(mos_max_jitter_A)")
1364 ...
1365 </programlisting>
1366                 </example>
1367         </section>
1368
1369         <section id="rtpengine.p.mos_max_roundtrip_A_pv">
1370                 <title><varname>mos_max_roundtrip_A_pv</varname> (string)</title>
1371                 <para>
1372                         The name of a pseudovariable to hold the packet round-trip time in milliseconds
1373                         at the time the maximum MOS value was encountered;
1374                 </para>
1375                 <para>
1376                         There is no default value.
1377                 </para>
1378                 <para>
1379                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1380                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1381                         command resulted in a deletion of the call (or call branch).
1382                 </para>
1383                 <para>
1384                         Only call legs matching the rtpengine label given in the <quote>mos_A_label_pv</quote>
1385                         will be used in calculating this statistics value.
1386                 </para>
1387                 <example>
1388                 <title>Set <varname>mos_max_roundtrip_A_pv</varname> parameter</title>
1389 <programlisting format="linespecific">
1390 ...
1391 modparam("rtpengine", "mos_max_roundtrip_A_pv", "$avp(mos_max_roundtrip_A)")
1392 ...
1393 </programlisting>
1394                 </example>
1395         </section>
1396
1397         <section id="rtpengine.p.mos_average_A_pv">
1398                 <title><varname>mos_average_A_pv</varname> (string)</title>
1399                 <para>
1400                         The name of a pseudovariable to hold the average (median) MOS value for the call.
1401                         The value typically has a range of 1.0 through 5.0.
1402                 </para>
1403                 <para>
1404                         There is no default value.
1405                 </para>
1406                 <para>
1407                         This value is filled in after invoking<quote>rtpengine_delete</quote>,
1408                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1409                         command resulted in a deletion of the call (or call branch).
1410                 </para>
1411                 <para>
1412                         Only call legs matching the rtpengine label given in the <quote>mos_A_label_pv</quote>
1413                         will be used in calculating this statistics value.
1414                 </para>
1415                 <example>
1416                 <title>Set <varname>mos_average_A_pv</varname> parameter</title>
1417 <programlisting format="linespecific">
1418 ...
1419 modparam("rtpengine", "mos_average_A_pv", "$avp(mos_average_A)")
1420 ...
1421 </programlisting>
1422                 </example>
1423         </section>
1424
1425         <section id="rtpengine.p.mos_average_packetloss_A_pv">
1426                 <title><varname>mos_average_packetloss_A_pv</varname> (string)</title>
1427                 <para>
1428                         The name of a pseudovariable to hold the average (median) amount of packetloss
1429                         in percent
1430                         present throughout the call.
1431                 </para>
1432                 <para>
1433                         There is no default value.
1434                 </para>
1435                 <para>
1436                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1437                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1438                         command resulted in a deletion of the call (or call branch).
1439                 </para>
1440                 <para>
1441                         Only call legs matching the rtpengine label given in the <quote>mos_A_label_pv</quote>
1442                         will be used in calculating this statistics value.
1443                 </para>
1444                 <example>
1445                 <title>Set <varname>mos_average_packetloss_A_pv</varname> parameter</title>
1446 <programlisting format="linespecific">
1447 ...
1448 modparam("rtpengine", "mos_average_packetloss_A_pv", "$avp(mos_average_packetloss_A)")
1449 ...
1450 </programlisting>
1451                 </example>
1452         </section>
1453
1454         <section id="rtpengine.p.mos_average_jitter_A_pv">
1455                 <title><varname>mos_average_jitter_A_pv</varname> (string)</title>
1456                 <para>
1457                         The name of a pseudovariable to hold the average (median) amount of jitter
1458                         in milliseconds
1459                         present throughout the call.
1460                 </para>
1461                 <para>
1462                         There is no default value.
1463                 </para>
1464                 <para>
1465                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1466                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1467                         command resulted in a deletion of the call (or call branch).
1468                 </para>
1469                 <para>
1470                         Only call legs matching the rtpengine label given in the <quote>mos_A_label_pv</quote>
1471                         will be used in calculating this statistics value.
1472                 </para>
1473                 <example>
1474                 <title>Set <varname>mos_average_jitter_A_pv</varname> parameter</title>
1475 <programlisting format="linespecific">
1476 ...
1477 modparam("rtpengine", "mos_average_jitter_A_pv", "$avp(mos_average_jitter_A)")
1478 ...
1479 </programlisting>
1480                 </example>
1481         </section>
1482
1483         <section id="rtpengine.p.mos_average_roundtrip_A_pv">
1484                 <title><varname>mos_average_roundtrip_A_pv</varname> (string)</title>
1485                 <para>
1486                         The name of a pseudovariable to hold the average (median) packet round-trip
1487                         time in milliseconds
1488                         present throughout the call.
1489                 </para>
1490                 <para>
1491                         There is no default value.
1492                 </para>
1493                 <para>
1494                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1495                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1496                         command resulted in a deletion of the call (or call branch).
1497                 </para>
1498                 <para>
1499                         Only call legs matching the rtpengine label given in the <quote>mos_A_label_pv</quote>
1500                         will be used in calculating this statistics value.
1501                 </para>
1502                 <example>
1503                 <title>Set <varname>mos_average_roundtrip_A_pv</varname> parameter</title>
1504 <programlisting format="linespecific">
1505 ...
1506 modparam("rtpengine", "mos_average_roundtrip_A_pv", "$avp(mos_average_roundtrip_A)")
1507 ...
1508 </programlisting>
1509                 </example>
1510         </section>
1511
1512         <section id="rtpengine.p.mos_average_samples_A_pv">
1513                 <title><varname>mos_average_samples_A_pv</varname> (string)</title>
1514                 <para>
1515                         The name of a pseudovariable to hold the number of samples used to determine
1516                         the other <quote>average</quote> MOS data points.
1517                 </para>
1518                 <para>
1519                         There is no default value.
1520                 </para>
1521                 <para>
1522                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1523                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1524                         command resulted in a deletion of the call (or call branch).
1525                 </para>
1526                 <para>
1527                         Only call legs matching the rtpengine label given in the <quote>mos_A_label_pv</quote>
1528                         will be used in calculating this statistics value.
1529                 </para>
1530                 <example>
1531                 <title>Set <varname>mos_average_samples_A_pv</varname> parameter</title>
1532 <programlisting format="linespecific">
1533 ...
1534 modparam("rtpengine", "mos_average_samples_A_pv", "$avp(mos_average_samples_A)")
1535 ...
1536 </programlisting>
1537                 </example>
1538         </section>
1539
1540
1541         <section id="rtpengine.p.mos_B_label_pv">
1542                 <title><varname>mos_B_label_pv</varname> (string)</title>
1543                 <para>
1544                         The name of a pseudovariable to hold a custom label used in rtpengine signalling.
1545                         If set, all the statistics pseudovariables with the <quote>_B</quote> suffix will
1546                         be filled in
1547                         with statistics only from the call legs that match the label given in this
1548                         variable.
1549                 </para>
1550                 <para>
1551                         There is no default value.
1552                 </para>
1553                 <example>
1554                 <title>Set <varname>mos_B_label_pv</varname> parameter</title>
1555 <programlisting format="linespecific">
1556 ...
1557 modparam("rtpengine", "mos_B_label_pv", "$avp(mos_B_label)")
1558 ...
1559 </programlisting>
1560                 </example>
1561         </section>
1562
1563
1564         <section id="rtpengine.p.mos_min_B_pv">
1565                 <title><varname>mos_min_B_pv</varname> (string)</title>
1566                 <para>
1567                         The name of a pseudovariable to hold the minimum encountered MOS value for the call.
1568                         The value typically has a range of 1.0 through 5.0.
1569                 </para>
1570                 <para>
1571                         There is no default value.
1572                 </para>
1573                 <para>
1574                         This value is filled in after invoking<quote>rtpengine_delete</quote>,
1575                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1576                         command resulted in a deletion of the call (or call branch).
1577                 </para>
1578                 <para>
1579                         Only call legs matching the rtpengine label given in the <quote>mos_B_label_pv</quote>
1580                         will be used in calculating this statistics value.
1581                 </para>
1582                 <example>
1583                 <title>Set <varname>mos_min_B_pv</varname> parameter</title>
1584 <programlisting format="linespecific">
1585 ...
1586 modparam("rtpengine", "mos_min_B_pv", "$avp(mos_min_B)")
1587 ...
1588 </programlisting>
1589                 </example>
1590         </section>
1591
1592         <section id="rtpengine.p.mos_min_at_B_pv">
1593                 <title><varname>mos_min_at_B_pv</varname> (string)</title>
1594                 <para>
1595                         The name of a pseudovariable to hold the timestamp of when the minimum MOS value
1596                         was encountered during the call, such as <quote>0:30</quote> for 30 seconds
1597                         after the start of the call.
1598                 </para>
1599                 <para>
1600                         There is no default value.
1601                 </para>
1602                 <para>
1603                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1604                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1605                         command resulted in a deletion of the call (or call branch).
1606                 </para>
1607                 <para>
1608                         Only call legs matching the rtpengine label given in the <quote>mos_B_label_pv</quote>
1609                         will be used in calculating this statistics value.
1610                 </para>
1611                 <example>
1612                 <title>Set <varname>mos_min_at_B_pv</varname> parameter</title>
1613 <programlisting format="linespecific">
1614 ...
1615 modparam("rtpengine", "mos_min_at_B_pv", "$avp(mos_min_at_B)")
1616 ...
1617 </programlisting>
1618                 </example>
1619         </section>
1620
1621         <section id="rtpengine.p.mos_min_packetloss_B_pv">
1622                 <title><varname>mos_min_packetloss_B_pv</varname> (string)</title>
1623                 <para>
1624                         The name of a pseudovariable to hold the amount of packetloss in percent
1625                         at the time the minimum MOS value was encountered;
1626                 </para>
1627                 <para>
1628                         There is no default value.
1629                 </para>
1630                 <para>
1631                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1632                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1633                         command resulted in a deletion of the call (or call branch).
1634                 </para>
1635                 <para>
1636                         Only call legs matching the rtpengine label given in the <quote>mos_B_label_pv</quote>
1637                         will be used in calculating this statistics value.
1638                 </para>
1639                 <example>
1640                 <title>Set <varname>mos_min_packetloss_B_pv</varname> parameter</title>
1641 <programlisting format="linespecific">
1642 ...
1643 modparam("rtpengine", "mos_min_packetloss_B_pv", "$avp(mos_min_packetloss_B)")
1644 ...
1645 </programlisting>
1646                 </example>
1647         </section>
1648
1649         <section id="rtpengine.p.mos_min_jitter_B_pv">
1650                 <title><varname>mos_min_jitter_B_pv</varname> (string)</title>
1651                 <para>
1652                         The name of a pseudovariable to hold the amount of jitter in milliseconds
1653                         at the time the minimum MOS value was encountered;
1654                 </para>
1655                 <para>
1656                         There is no default value.
1657                 </para>
1658                 <para>
1659                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1660                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1661                         command resulted in a deletion of the call (or call branch).
1662                 </para>
1663                 <para>
1664                         Only call legs matching the rtpengine label given in the <quote>mos_B_label_pv</quote>
1665                         will be used in calculating this statistics value.
1666                 </para>
1667                 <example>
1668                 <title>Set <varname>mos_min_jitter_B_pv</varname> parameter</title>
1669 <programlisting format="linespecific">
1670 ...
1671 modparam("rtpengine", "mos_min_jitter_B_pv", "$avp(mos_min_jitter_B)")
1672 ...
1673 </programlisting>
1674                 </example>
1675         </section>
1676
1677         <section id="rtpengine.p.mos_min_roundtrip_B_pv">
1678                 <title><varname>mos_min_roundtrip_B_pv</varname> (string)</title>
1679                 <para>
1680                         The name of a pseudovariable to hold the packet round-trip time in milliseconds
1681                         at the time the minimum MOS value was encountered;
1682                 </para>
1683                 <para>
1684                         There is no default value.
1685                 </para>
1686                 <para>
1687                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1688                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1689                         command resulted in a deletion of the call (or call branch).
1690                 </para>
1691                 <para>
1692                         Only call legs matching the rtpengine label given in the <quote>mos_B_label_pv</quote>
1693                         will be used in calculating this statistics value.
1694                 </para>
1695                 <example>
1696                 <title>Set <varname>mos_min_roundtrip_B_pv</varname> parameter</title>
1697 <programlisting format="linespecific">
1698 ...
1699 modparam("rtpengine", "mos_min_roundtrip_B_pv", "$avp(mos_min_roundtrip_B)")
1700 ...
1701 </programlisting>
1702                 </example>
1703         </section>
1704
1705
1706         <section id="rtpengine.p.mos_max_B_pv">
1707                 <title><varname>mos_max_B_pv</varname> (string)</title>
1708                 <para>
1709                         The name of a pseudovariable to hold the maximum encountered MOS value for the call.
1710                         The value typically has a range of 1.0 through 5.0.
1711                 </para>
1712                 <para>
1713                         There is no default value.
1714                 </para>
1715                 <para>
1716                         This value is filled in after invoking<quote>rtpengine_delete</quote>,
1717                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1718                         command resulted in a deletion of the call (or call branch).
1719                 </para>
1720                 <para>
1721                         Only call legs matching the rtpengine label given in the <quote>mos_B_label_pv</quote>
1722                         will be used in calculating this statistics value.
1723                 </para>
1724                 <example>
1725                 <title>Set <varname>mos_max_B_pv</varname> parameter</title>
1726 <programlisting format="linespecific">
1727 ...
1728 modparam("rtpengine", "mos_max_B_pv", "$avp(mos_max_B)")
1729 ...
1730 </programlisting>
1731                 </example>
1732         </section>
1733
1734         <section id="rtpengine.p.mos_max_at_B_pv">
1735                 <title><varname>mos_max_at_B_pv</varname> (string)</title>
1736                 <para>
1737                         The name of a pseudovariable to hold the timestamp of when the maximum MOS value
1738                         was encountered during the call, such as <quote>0:30</quote> for 30 seconds
1739                         after the start of the call.
1740                 </para>
1741                 <para>
1742                         There is no default value.
1743                 </para>
1744                 <para>
1745                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1746                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1747                         command resulted in a deletion of the call (or call branch).
1748                 </para>
1749                 <para>
1750                         Only call legs matching the rtpengine label given in the <quote>mos_B_label_pv</quote>
1751                         will be used in calculating this statistics value.
1752                 </para>
1753                 <example>
1754                 <title>Set <varname>mos_max_at_B_pv</varname> parameter</title>
1755 <programlisting format="linespecific">
1756 ...
1757 modparam("rtpengine", "mos_max_at_B_pv", "$avp(mos_max_at_B)")
1758 ...
1759 </programlisting>
1760                 </example>
1761         </section>
1762
1763         <section id="rtpengine.p.mos_max_packetloss_B_pv">
1764                 <title><varname>mos_max_packetloss_B_pv</varname> (string)</title>
1765                 <para>
1766                         The name of a pseudovariable to hold the amount of packetloss in percent
1767                         at the time the maximum MOS value was encountered;
1768                 </para>
1769                 <para>
1770                         There is no default value.
1771                 </para>
1772                 <para>
1773                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1774                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1775                         command resulted in a deletion of the call (or call branch).
1776                 </para>
1777                 <para>
1778                         Only call legs matching the rtpengine label given in the <quote>mos_B_label_pv</quote>
1779                         will be used in calculating this statistics value.
1780                 </para>
1781                 <example>
1782                 <title>Set <varname>mos_max_packetloss_B_pv</varname> parameter</title>
1783 <programlisting format="linespecific">
1784 ...
1785 modparam("rtpengine", "mos_max_packetloss_B_pv", "$avp(mos_max_packetloss_B)")
1786 ...
1787 </programlisting>
1788                 </example>
1789         </section>
1790
1791         <section id="rtpengine.p.mos_max_jitter_B_pv">
1792                 <title><varname>mos_max_jitter_B_pv</varname> (string)</title>
1793                 <para>
1794                         The name of a pseudovariable to hold the amount of jitter in milliseconds
1795                         at the time the maximum MOS value was encountered;
1796                 </para>
1797                 <para>
1798                         There is no default value.
1799                 </para>
1800                 <para>
1801                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1802                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1803                         command resulted in a deletion of the call (or call branch).
1804                 </para>
1805                 <para>
1806                         Only call legs matching the rtpengine label given in the <quote>mos_B_label_pv</quote>
1807                         will be used in calculating this statistics value.
1808                 </para>
1809                 <example>
1810                 <title>Set <varname>mos_max_jitter_B_pv</varname> parameter</title>
1811 <programlisting format="linespecific">
1812 ...
1813 modparam("rtpengine", "mos_max_jitter_B_pv", "$avp(mos_max_jitter_B)")
1814 ...
1815 </programlisting>
1816                 </example>
1817         </section>
1818
1819         <section id="rtpengine.p.mos_max_roundtrip_B_pv">
1820                 <title><varname>mos_max_roundtrip_B_pv</varname> (string)</title>
1821                 <para>
1822                         The name of a pseudovariable to hold the packet round-trip time in milliseconds
1823                         at the time the maximum MOS value was encountered;
1824                 </para>
1825                 <para>
1826                         There is no default value.
1827                 </para>
1828                 <para>
1829                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1830                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1831                         command resulted in a deletion of the call (or call branch).
1832                 </para>
1833                 <para>
1834                         Only call legs matching the rtpengine label given in the <quote>mos_B_label_pv</quote>
1835                         will be used in calculating this statistics value.
1836                 </para>
1837                 <example>
1838                 <title>Set <varname>mos_max_roundtrip_B_pv</varname> parameter</title>
1839 <programlisting format="linespecific">
1840 ...
1841 modparam("rtpengine", "mos_max_roundtrip_B_pv", "$avp(mos_max_roundtrip_B)")
1842 ...
1843 </programlisting>
1844                 </example>
1845         </section>
1846
1847         <section id="rtpengine.p.mos_average_B_pv">
1848                 <title><varname>mos_average_B_pv</varname> (string)</title>
1849                 <para>
1850                         The name of a pseudovariable to hold the average (median) MOS value for the call.
1851                         The value typically has a range of 1.0 through 5.0.
1852                 </para>
1853                 <para>
1854                         There is no default value.
1855                 </para>
1856                 <para>
1857                         This value is filled in after invoking<quote>rtpengine_delete</quote>,
1858                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1859                         command resulted in a deletion of the call (or call branch).
1860                 </para>
1861                 <para>
1862                         Only call legs matching the rtpengine label given in the <quote>mos_B_label_pv</quote>
1863                         will be used in calculating this statistics value.
1864                 </para>
1865                 <example>
1866                 <title>Set <varname>mos_average_B_pv</varname> parameter</title>
1867 <programlisting format="linespecific">
1868 ...
1869 modparam("rtpengine", "mos_average_B_pv", "$avp(mos_average_B)")
1870 ...
1871 </programlisting>
1872                 </example>
1873         </section>
1874
1875         <section id="rtpengine.p.mos_average_packetloss_B_pv">
1876                 <title><varname>mos_average_packetloss_B_pv</varname> (string)</title>
1877                 <para>
1878                         The name of a pseudovariable to hold the average (median) amount of packetloss
1879                         in percent
1880                         present throughout the call.
1881                 </para>
1882                 <para>
1883                         There is no default value.
1884                 </para>
1885                 <para>
1886                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1887                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1888                         command resulted in a deletion of the call (or call branch).
1889                 </para>
1890                 <para>
1891                         Only call legs matching the rtpengine label given in the <quote>mos_B_label_pv</quote>
1892                         will be used in calculating this statistics value.
1893                 </para>
1894                 <example>
1895                 <title>Set <varname>mos_average_packetloss_B_pv</varname> parameter</title>
1896 <programlisting format="linespecific">
1897 ...
1898 modparam("rtpengine", "mos_average_packetloss_B_pv", "$avp(mos_average_packetloss_B)")
1899 ...
1900 </programlisting>
1901                 </example>
1902         </section>
1903
1904         <section id="rtpengine.p.mos_average_jitter_B_pv">
1905                 <title><varname>mos_average_jitter_B_pv</varname> (string)</title>
1906                 <para>
1907                         The name of a pseudovariable to hold the average (median) amount of jitter
1908                         in milliseconds
1909                         present throughout the call.
1910                 </para>
1911                 <para>
1912                         There is no default value.
1913                 </para>
1914                 <para>
1915                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1916                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1917                         command resulted in a deletion of the call (or call branch).
1918                 </para>
1919                 <para>
1920                         Only call legs matching the rtpengine label given in the <quote>mos_B_label_pv</quote>
1921                         will be used in calculating this statistics value.
1922                 </para>
1923                 <example>
1924                 <title>Set <varname>mos_average_jitter_B_pv</varname> parameter</title>
1925 <programlisting format="linespecific">
1926 ...
1927 modparam("rtpengine", "mos_average_jitter_B_pv", "$avp(mos_average_jitter_B)")
1928 ...
1929 </programlisting>
1930                 </example>
1931         </section>
1932
1933         <section id="rtpengine.p.mos_average_roundtrip_B_pv">
1934                 <title><varname>mos_average_roundtrip_B_pv</varname> (string)</title>
1935                 <para>
1936                         The name of a pseudovariable to hold the average (median) packet round-trip
1937                         time in milliseconds
1938                         present throughout the call.
1939                 </para>
1940                 <para>
1941                         There is no default value.
1942                 </para>
1943                 <para>
1944                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1945                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1946                         command resulted in a deletion of the call (or call branch).
1947                 </para>
1948                 <para>
1949                         Only call legs matching the rtpengine label given in the <quote>mos_B_label_pv</quote>
1950                         will be used in calculating this statistics value.
1951                 </para>
1952                 <example>
1953                 <title>Set <varname>mos_average_roundtrip_B_pv</varname> parameter</title>
1954 <programlisting format="linespecific">
1955 ...
1956 modparam("rtpengine", "mos_average_roundtrip_B_pv", "$avp(mos_average_roundtrip_B)")
1957 ...
1958 </programlisting>
1959                 </example>
1960         </section>
1961
1962         <section id="rtpengine.p.mos_average_samples_B_pv">
1963                 <title><varname>mos_average_samples_B_pv</varname> (string)</title>
1964                 <para>
1965                         The name of a pseudovariable to hold the number of samples used to determine
1966                         the other <quote>average</quote> MOS data points.
1967                 </para>
1968                 <para>
1969                         There is no default value.
1970                 </para>
1971                 <para>
1972                         This value is filled in after invoking <quote>rtpengine_delete</quote>,
1973                         <quote>rtpengine_query</quote>, or <quote>rtpengine_manage</quote> if the
1974                         command resulted in a deletion of the call (or call branch).
1975                 </para>
1976                 <para>
1977                         Only call legs matching the rtpengine label given in the <quote>mos_B_label_pv</quote>
1978                         will be used in calculating this statistics value.
1979                 </para>
1980                 <example>
1981                 <title>Set <varname>mos_average_samples_B_pv</varname> parameter</title>
1982 <programlisting format="linespecific">
1983 ...
1984 modparam("rtpengine", "mos_average_samples_B_pv", "$avp(mos_average_samples_B)")
1985 ...
1986 </programlisting>
1987                 </example>
1988         </section>
1989
1990         <section id="rtpengine.p.control_cmd_tos">
1991                 <title><varname>control_cmd_tos</varname> (integer)</title>
1992                 <para>
1993                         The parameter is used to set the value of <quote>type of service (tos)</quote> for the control commands (such as rtpengine_offer(), rtpengine_answer() etc).
1994                 </para>
1995                 <para>
1996                         There is no default value. By default this feature is not used.
1997                 </para>
1998                 <para>
1999                         The values not falling into the range <quote>0-255</quote> will be simply ignored.
2000                 </para>
2001                 <example>
2002                 <title>Set <varname>control_cmd_tos</varname> parameter</title>
2003 <programlisting format="linespecific">
2004 ...
2005 modparam("rtpengine", "control_cmd_tos", 144)
2006 ...
2007 </programlisting>
2008                 </example>
2009         </section>
2010
2011         <section id="rtpengine.p.hash_algo">
2012                 <title><varname>hash_algo</varname> (integer)</title>
2013                 <para>
2014                         Hashing algorithm to be used in node selection algorithm. Now there are 2 possibilities: legacy
2015                         alogrithm - 0(very basic hash over callid) or SHA1 - 1(apply sha1 over the callid and calculate hash).
2016                 </para>
2017                 <para>
2018                         Default value is 0, legacy algorithm.
2019                 </para>
2020                 <para>
2021                         The values not falling into the range <quote>0-1</quote> .
2022                 </para>
2023                 <example>
2024                 <title>Set <varname>control_cmd_tos</varname> parameter</title>
2025 <programlisting format="linespecific">
2026 ...
2027 ### use SHA1 instead of legacy algorithm
2028 modparam("rtpengine", "hash_algo", 1)
2029 ...
2030 </programlisting>
2031                 </example>
2032         </section>
2033
2034
2035
2036         </section>
2037
2038
2039         <section>
2040         <title>Functions</title>
2041         <section id="rtpengine.f.set_rtpengine_set">
2042                 <title>
2043                 <function moreinfo="none">set_rtpengine_set(setid[, setid])</function>
2044                 </title>
2045                 <para>
2046                 Sets the ID of the &rtp; proxy set to be used for the next
2047                 rtpengine_delete(), rtpengine_offer(), rtpengine_answer()
2048                 or rtpengine_manage() command. The parameter can be an integer or
2049                 a config variable holding an integer.
2050                 </para>
2051                 <para>
2052                 A second set ID can be specified to daisy-chain two &rtp; proxies.
2053                 The two set IDs must be distinct from each other and there must not
2054                 be any overlap in the proxies present in both sets. In this use case,
2055                 the request (offer, answer, etc) is first sent to an &rtp; proxy from
2056                 the first set, which rewrites the &sdp; body and sends it back to the
2057                 module. The rewritten &sdp; body is then used to make another request
2058                 to an &rtp; proxy from the second set, which rewrites the &sdp; body
2059                 another time and sends it back to the module to be placed back into the
2060                 &sip; message. This is useful if you have a set of &rtp; proxies that
2061                 the caller must use, and another distinct set of &rtp; proxies that the
2062                 callee must use. This is supported by all rtpengine commands except
2063                 rtpengine_manage().
2064                 </para>
2065                 <para>
2066                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
2067                 BRANCH_ROUTE.
2068                 </para>
2069                 <example>
2070                 <title><function>set_rtpengine_set</function> usage</title>
2071                 <programlisting format="linespecific">
2072 ...
2073 set_rtpengine_set("2");
2074 rtpengine_offer();
2075 ...
2076 </programlisting>
2077                 </example>
2078         </section>
2079         <section id="rtpengine.f.rtpengine_offer">
2080                 <title>
2081                 <function moreinfo="none">rtpengine_offer([flags])</function>
2082                 </title>
2083                 <para>
2084                 Rewrites &sdp; body to ensure that media is passed through
2085                 an &rtp; proxy. To be invoked
2086                 on INVITE for the cases the &sdp; bodies are in INVITE and 200 OK and on 200 OK
2087                 when &sdp; bodies are in 200 OK and ACK.
2088                 </para>
2089                 <para>
2090                 The function will return true on success and false (-1) on various failures,
2091                 like using rtp_engine_offer() on a SIP MESSAGE request or communication with
2092                 rtpengine fails.
2093                 </para>
2094                 <para>Meaning of the parameters is as follows:</para>
2095                 <itemizedlist>
2096                 <listitem>
2097                         <para>
2098                         <emphasis>flags</emphasis> - flags to turn on some features.
2099                         </para>
2100                         <para>The <quote>flags</quote> string is a list of space-separated items. Each item
2101                         is either an individual token, or a token in <quote>key=value</quote> format. The
2102                         possible tokens are described below.</para>
2103                         <itemizedlist>
2104                                 <listitem><para>
2105                                 <emphasis>via-branch=...</emphasis> - Include the <quote>branch</quote>
2106                                 value of one of the <quote>Via</quote> headers in the request to the
2107                                 &rtp; proxy. Possible values are:
2108                                 <quote>1</quote> - use the first <quote>Via</quote> header;
2109                                 <quote>2</quote> - use the second <quote>Via</quote> header;
2110                                 <quote>auto</quote> - use the first <quote>Via</quote> header if this is
2111                                 a request, or the second one if this is a reply;
2112                                 <quote>extra</quote> - don't take the value from a header, but instead use
2113                                 the value of the <quote>extra_id_pv</quote> variable;
2114                                 <quote>next</quote> - use the branch ID generated by &kamailio; for the
2115                                 next outgoing branch;
2116                                 <quote>auto-next</quote> - use <quote>next</quote> in requests and
2117                                 <quote>1</quote> in replies;
2118                                 <quote>auto-extra</quote> - use <quote>extra</quote> in requests and
2119                                 <quote>1</quote> in replies.
2120                                 This can be used to create one media session per branch
2121                                 on the &rtp; proxy. When sending a subsequent <quote>delete</quote> command to
2122                                 the &rtp; proxy, you can then stop just the session for a specific branch when
2123                                 passing the flag '1' or '2' in the <quote>rtpengine_delete</quote>, or stop
2124                                 all sessions for a call when not passing one of those two flags there. This is
2125                                 especially useful if you have serially forked call scenarios where the &rtp; proxy
2126                                 gets an <quote>offer</quote> command for a new branch, and then a
2127                                 <quote>delete</quote> command for the previous branch, which would otherwise
2128                                 delete the full call, breaking the subsequent <quote>answer</quote> for the
2129                                 new branch. <emphasis>This flag is only supported by the Sipwise rtpengine
2130                                 &rtp; proxy at the moment!</emphasis>
2131                                 </para></listitem>
2132                                 <listitem><para>
2133                                 <emphasis>asymmetric</emphasis> - flags that UA from which message is
2134                                 received doesn't support symmetric &rtp;. Disables learning of endpoint addresses
2135                                 in the Sipwise rtpengine proxy.
2136                                 </para></listitem>
2137                                 <listitem><para>
2138                                 <emphasis>no-redis-update</emphasis> - this flag can be used by Kamailio in order
2139                                 to tell rtpengine not to persist the call into Redis upon receiving offer/answer()
2140                                 control commands. If flag is not set, default action is rtpengine persists call
2141                                 to redis.
2142                                 </para></listitem>
2143                                 <listitem><para>
2144                                 <emphasis>force-answer</emphasis> - force <quote>answer</quote>, that is,
2145                                 only rewrite &sdp; when corresponding session already exists
2146                                 in the &rtp; proxy. By default is on when the session is to be
2147                                 completed.
2148                                 </para></listitem>
2149                                 <listitem><para>
2150                                 <emphasis>direction=...</emphasis> - this option specifies a logical network
2151                                 interface and should be given exactly twice. It enables &rtp; bridging between
2152                                 different addresses or networks of the same family (e.g. IPv4 to IPv4). The
2153                                 first instance of the option
2154                                 specifies the interface that the originator of this message should be using,
2155                                 while the second instance specifies the interface that the target should be
2156                                 using. For example, if the &sip; message was sent by an endpoint on a private
2157                                 network and will be sent to an endpoint on the public internet, you would use
2158                                 <quote>direction=priv direction=pub</quote> if those two logical network
2159                                 interfaces were called <quote>priv</quote> and <quote>pub</quote> in your
2160                                 &rtp; proxy's configuration respectively. The direction must only be specified
2161                                 in for initial &sdp; offer; answers or subsequent offers can omit this option.
2162                                 </para></listitem>
2163                                 <listitem><para>
2164                                 <emphasis>internal, external</emphasis> - shorthand for
2165                                 <quote>direction=internal</quote> and <quote>direction=external</quote>
2166                                 respectively. Useful for brevity or as legacy option if the &rtp; proxy only
2167                                 supports two network interfaces instead of multiple, arbitrarily named ones.
2168                                 </para></listitem>
2169                                 <listitem><para>
2170                                 <emphasis>address-family=...</emphasis> - instructs the &rtp; proxy that the
2171                                 recipient of this &sdp; body expects to see addresses of a particular family.
2172                                 Possible values are <quote>IP4</quote> and <quote>IP6</quote>. For example,
2173                                 if the &sdp; body contains IPv4 addresses but the recipient only speaks IPv6,
2174                                 you would use <quote>address-family=IP6</quote> to bridge between the two
2175                                 address families.
2176                                 </para><para>
2177                                 Sipwise rtpengine remembers the address family preference of each party after
2178                                 it has seen an &sdp; body from them. This means that normally it is only
2179                                 necessary to explicitly specify the address family in the <quote>offer</quote>,
2180                                 but not in the <quote>answer</quote>.
2181                                 </para><para>
2182                                 Note: Please note, that this will only work properly with non-dual-stack user-agents or with
2183                                 dual-stack clients according to RFC6157 (which suggest ICE for Dual-Stack implementations).
2184                                 This short-cut will not work properly with RFC4091 (ANAT) compatible clients, which suggests
2185                                 having different m-lines with different IP-protocols grouped together.
2186                                 </para></listitem>
2187                                 <listitem><para>
2188                                 <emphasis>force</emphasis> - instructs the &rtp; proxy to ignore marks
2189                                 inserted by another &rtp; proxy in transit to indicate that the
2190                                 session is already goes through another proxy. Allows creating
2191                                 a chain of proxies. Not supported and ignored by Sipwise rtpengine.
2192                                 </para></listitem>
2193                                 <listitem><para>
2194                                 <emphasis>trust-address</emphasis> - flags that IP address in &sdp; should
2195                                 be trusted. Starting with rtpengine 3.8, this is the default behaviour.
2196                                 In older versions, without this flag the &rtp; proxy ignores the address in
2197                                 the &sdp; and uses source address of the &sip; message as media
2198                                 address which is passed to the &rtp; proxy.
2199                                 </para></listitem>
2200                                 <listitem><para>
2201                                 <emphasis>SIP-source-address</emphasis> - the opposite of
2202                                 <emphasis>trust-address</emphasis>. Restores the old default behaviour
2203                                 of ignoring endpoint addresses in the &sdp; body.
2204                                 </para></listitem>
2205                                 <listitem><para>
2206                                 <emphasis>replace-origin</emphasis> - flags that IP from the origin
2207                                 description (o=) should be also changed.
2208                                 </para></listitem>
2209                                 <listitem><para>
2210                                 <emphasis>replace-session-connection</emphasis> - flags to change the session-level
2211                                 &sdp; connection (c=) IP if media description also includes
2212                                 connection information.
2213                                 </para></listitem>
2214                                 <listitem><para>
2215                                 <emphasis>symmetric</emphasis> - flags that for the UA from which
2216                                 message is received, support symmetric &rtp; must be forced. Does nothing with
2217                                 the Sipwise rtpengine proxy as it is the default.
2218                                 </para></listitem>
2219                                 <listitem><para>
2220                                 <emphasis>repacketize=NN</emphasis> - requests the &rtp; proxy to perform
2221                                 re-packetization of &rtp; traffic coming from the UA which
2222                                 has sent the current message to increase or decrease payload
2223                                 size per each &rtp; packet forwarded if possible.  The NN is the
2224                                 target payload size in ms, for the most codecs its value should
2225                                 be in 10ms increments, however for some codecs the increment
2226                                 could differ (e.g. 30ms for GSM or 20ms for G.723).  The
2227                                 &rtp; proxy would select the closest value supported by the codec.
2228                                 This feature could be used for significantly reducing bandwith
2229                                 overhead for low bitrate codecs, for example with G.729 going
2230                                 from 10ms to 100ms saves two thirds of the network bandwith.
2231                                 Not supported by Sipwise rtpengine.
2232                                 </para></listitem>
2233                                 <listitem><para>
2234                                 <emphasis>ICE=...</emphasis> - controls the &rtp; proxy's behaviour
2235                                 regarding ICE attributes within the &sdp; body. Possible values
2236                                 are: <quote>force</quote> -
2237                                 discard any ICE attributes already present in the &sdp; body
2238                                 and then generate and insert new ICE data, leaving itself
2239                                 as the <emphasis>only</emphasis> ICE candidates;
2240                                 <quote>force-relay</quote> -
2241                                 discard any <quote>relay</quote> type ICE attributes already present
2242                                 in the &sdp; body and then generate and insert itself
2243                                 as the <emphasis>only</emphasis> ICE <quote>relay</quote> candidates;
2244                                 <quote>remove</quote> instructs the &rtp; proxy to discard
2245                                 any ICE attributes and not insert any new ones into the &sdp;.
2246                                 The default (if no <quote>ICE=...</quote> is given at all),
2247                                 new ICE data will only be generated
2248                                 if no ICE was present in the &sdp; originally; otherwise
2249                                 the &rtp; proxy will only insert itself as
2250                                 <emphasis>additional</emphasis> ICE candidate. Other
2251                                 &sdp; substitutions (c=, m=, etc) are unaffected by this flag.
2252                                 </para></listitem>
2253                                 <listitem><para>
2254                                 <emphasis>RTP, SRTP, DTLS, AVP, AVPF</emphasis> - These flags control the &rtp;
2255                                 transport protocol that should be used towards the recipient of
2256                                 the &sdp;. If none of them are specified, the protocol given in
2257                                 the &sdp; is left untouched. Otherwise, the <quote>SRTP</quote> flag indicates that
2258                                 SRTP should be used, while <quote>RTP</quote> indicates that SRTP should not be used.
2259                                 <quote>AVPF</quote> indicates that the advanced RTCP profile with feedback messages
2260                                 should be used, and <quote>AVP</quote> indicates that the regular RTCP profile
2261                                 should be used. See also the next set of flags below.
2262                                 </para></listitem>
2263                                 <listitem><para>
2264                                 <emphasis>RTP/AVP, RTP/SAVP, UDP/TLS/RTP/SAVP, RTP/AVPF, RTP/SAVPF, UDP/TLS/RTP/SAVPF</emphasis> - these
2265                                 serve as an alternative, more explicit way to select between the different &rtp; protocols
2266                                 and profiles supported by the &rtp; proxy. For example, giving the flag
2267                                 <quote>RTP/SAVPF</quote> has the same effect as giving the two flags
2268                                 <quote>SRTP AVPF</quote>.
2269                                 </para></listitem>
2270                                 <listitem><para>
2271                                 <emphasis>to-tag</emphasis> - force inclusion of the <quote>To</quote> tag.
2272                                 Normally, the <quote>To</quote> tag is always included when present, except
2273                                 for <quote>delete</quote> messages. Including the <quote>To</quote> tag in
2274                                 a <quote>delete</quote> messages allows you to be more selective about which
2275                                 dialogues within a call are being torn down.
2276                                 </para></listitem>
2277                                 <listitem><para>
2278                                 <emphasis>to-tag=...</emphasis> - use the specified string as <quote>To</quote>
2279                                 tag instead of the actual <quote>To</quote> tag from the &sip; message, and
2280                                 force inclusion of the tag in the message as per above.
2281                                 </para></listitem>
2282                                 <listitem><para>
2283                                 <emphasis>from-tag=...</emphasis> - use the specified string as
2284                                 <quote>From</quote> tag instead of the actual <quote>From</quote>
2285                                 tag from the &sip; message.
2286                                 </para></listitem>
2287                                 <listitem><para>
2288                                 <emphasis>call-id=...</emphasis> - use the specified string as
2289                                 <quote>Call-ID</quote> instead of the actual <quote>Call-ID</quote>
2290                                 from the &sip; message.
2291                                 </para></listitem>
2292                                 <listitem><para>
2293                                 <emphasis>rtcp-mux-demux</emphasis> - if rtcp-mux (RFC 5761) was
2294                                 offered, make the &rtp; proxy accept the offer, but not offer it to the
2295                                 recipient of this message.
2296                                 </para></listitem>
2297                                 <listitem><para>
2298                                 <emphasis>rtcp-mux-reject</emphasis> - if rtcp-mux was offered, make the
2299                                 &rtp; proxy reject the offer, but still offer it to the recipient. Can be
2300                                 combined with <quote>rtcp-mux-offer</quote> to always offer it.
2301                                 </para></listitem>
2302                                 <listitem><para>
2303                                 <emphasis>rtcp-mux-offer</emphasis> - make the &rtp; proxy offer rtcp-mux
2304                                 to the recipient of this message, regardless of whether it was offered
2305                                 originally or not.
2306                                 </para></listitem>
2307                                 <listitem><para>
2308                                 <emphasis>rtcp-mux-accept</emphasis> - if rtcp-mux was offered, make the
2309                                 &rtp; proxy accept the offer and also offer it to the recipient of this
2310                                 message. Can be combined with <quote>rtcp-mux-offer</quote> to always offer it.
2311                                 </para></listitem>
2312                                 <listitem><para>
2313                                 <emphasis>media-address=...</emphasis> - force a particular media address to
2314                                 be used in the &sdp; body. Address family is detected automatically.
2315                                 </para></listitem>
2316                                 <listitem><para>
2317                                 <emphasis>TOS=...</emphasis> - change the IP TOS value for all outgoing &rtp;
2318                                 packets within the entire call in both directions. Only honoured in an
2319                                 <quote>offer</quote>, ignored for an <quote>answer</quote>. Valid values are
2320                                 0 through 255, given in decimal. If this option is not specified, the TOS
2321                                 value will revert to the default TOS (normally 184). A value of -1 may be used
2322                                 to leave the currently used TOS unchanged.
2323                                 </para></listitem>
2324                                 <listitem><para>
2325                                 <emphasis>delete-delay=...</emphasis> - override the default delay (in seconds)
2326                                 before a call is actually deleted from memory. Can be set to zero to effectuate
2327                                 immediate deletion. This option only makes sense for <emphasis>delete</emphasis>
2328                                 operations.
2329                                 </para></listitem>
2330                                 <listitem><para>
2331                                 <emphasis>strict-source</emphasis> - instructs the &rtp; proxy to check the
2332                                 source addresses of all incoming &rtp; packets and drop the packets if the
2333                                 address doesn't match.
2334                                 </para></listitem>
2335                                 <listitem><para>
2336                                 <emphasis>media-handover</emphasis> - the antithesis of
2337                                 <emphasis>strict-source</emphasis>. Instructs the &rtp; proxy not only to accept
2338                                 mismatching &rtp; source addresses (as it normally would), but also to accept
2339                                 them as the new endpoint address of the opposite media flow. Not recommended
2340                                 as it allows media streams to be hijacked by an attacker.
2341                                 </para></listitem>
2342                                 <listitem><para>
2343                                 <emphasis>DTLS=...</emphasis> - influence the behaviour of DTLS-SRTP. Possible
2344                                 values are <quote>no</quote> or <quote>off</quote> to suppress offering or
2345                                 accepting DTLS-SRTP, and <quote>passive</quote> to prefer participating in
2346                                 DTLS-SRTP in a passive role.
2347                                 </para></listitem>
2348                                 <listitem><para>
2349                                 <emphasis>SDES-off</emphasis> - don't offer SDES when it normally would. In an SRTP
2350                                 context, this leaves DTLS-SRTP as the only other option.
2351                                 </para></listitem>
2352                                 <listitem><para>
2353                                 <emphasis>SDES-unencrypted_srtp, SDES-unencrypted_srtcp,
2354                                 SDES-unauthenticated_srtp</emphasis> - these directly reflect the SDES session
2355                                 parameters from RFC 4568 and will make the &rtp; proxy offer these parameters
2356                                 when offering SDES.
2357                                 </para></listitem>
2358                                 <listitem><para>
2359                                 <emphasis>SDES-encrypted_srtp, SDES-encrypted_srtcp,
2360                                 SDES-authenticated_srtp</emphasis> - the opposites of the flags above. Useful
2361                                 if accepting these parameters is not desired and they should be rejected instead.
2362                                 </para></listitem>
2363                                 <listitem><para>
2364                                 <emphasis>unidirectional</emphasis> - allows kernelization of one-way streams
2365                                 in the Sipwise rtpengine proxy. This is especially useful when the first call leg is handled
2366                                 by some rtpengine machine while the second call leg is handled by other rtpengine machine.
2367                                 </para></listitem>
2368                                 <listitem><para>
2369                                 <emphasis>record-call=on</emphasis> - instructs RTPEngine to record the session. Use
2370                                 it in rtpengine_offer() to start recording immediately and save the call metadata,
2371                                 as alternative to start_recording().
2372                                 </para></listitem>
2373                                 <listitem><para>
2374                                 <emphasis>metadata</emphasis> - a generic metadata string. The metadata will be  used when
2375                                 recording calls to provide custom additional information. More details about this are found
2376                                 in the rtpengine README.
2377                                 </para></listitem>
2378                                 <listitem><para>
2379                                 <emphasis>codec-transcode=...</emphasis> - allows codecs to be added to the list of offered codecs even
2380                                 if they were not present in the original list of codecs. In this case, the transcoding engine
2381                                 will be engaged. Only codecs that are supported for both decoding and encoding can be added in
2382                                 this manner. More details about this are found in the rtpengine README.
2383                                 </para></listitem>
2384
2385                                 <listitem><para>
2386                                 <emphasis>codec-strip=...</emphasis> - strips given codec from sdp
2387                                 </para></listitem>
2388
2389                                 <listitem><para>
2390                                 <emphasis>codec-offer=...</emphasis> - offer given codec from sdp.More details about this are found in the rtpengine README.
2391                                 </para></listitem>
2392
2393                                 <listitem><para>
2394                                 <emphasis>codec-mask=...</emphasis> - Similar to strip except that codecs listed here will still be accepted
2395                                 and used for transcoding on the offering side.Useful only in combination with codec-transcode. <emphasis>all</emphasis> keyword
2396                                 can be used to mask all offered codecs
2397                                 </para></listitem>
2398                                 <listitem><para>
2399                                 <emphasis>T.38=decode</emphasis> - If the offered &sdp; contains a media section
2400                                 advertising T.38 over UDPTL, translate it to a regular audio media section
2401                                 over RTP. By default, PCMU and PCMA will be used as audio codecs, but that can
2402                                 be overriden using the codec options described above. Other transport protocols
2403                                 (e.g. SRTP) can also be selected in the same way. If the offered &sdp; does not
2404                                 contain a T.38 section, then this flag has no effect.
2405                                 </para></listitem>
2406                                 <listitem><para>
2407                                 <emphasis>T.38=force</emphasis> - Any audio media section (over RTP) in the
2408                                 offered &sdp; will be translated into a T.38 section over UDPTL.
2409                                 </para></listitem>
2410                                 <listitem><para>
2411                                 <emphasis>T.38=stop</emphasis> - Stops a previously established T.38 to audio
2412                                 gateway and reverts the session back to media passthrough. This is useful when
2413                                 handling a rejected T.38 offer.
2414                                 </para></listitem>
2415                         </itemizedlist>
2416                         <para>
2417                          Check also the documentation of RTPEngine, these flags are documented there as well:
2418                         <ulink url="https://github.com/sipwise/rtpengine">https://github.com/sipwise/rtpengine</ulink>.
2419                         </para>
2420                 </listitem>
2421                 </itemizedlist>
2422                 <para>
2423                 This function can be used from ANY_ROUTE.
2424                 </para>
2425                 <example>
2426                 <title><function>rtpengine_offer</function> usage</title>
2427                 <programlisting format="linespecific">
2428 route {
2429 ...
2430     if (is_method("INVITE")) {
2431         if (has_body("application/sdp")) {
2432             if (rtpengine_offer())
2433                 t_on_reply("1");
2434         } else {
2435             t_on_reply("2");
2436         }
2437     }
2438     if (is_method("ACK") &amp;&amp; has_body("application/sdp"))
2439         rtpengine_answer();
2440 ...
2441 }
2442
2443 onreply_route[1]
2444 {
2445 ...
2446     if (has_body("application/sdp"))
2447         rtpengine_answer();
2448 ...
2449 }
2450
2451 onreply_route[2]
2452 {
2453 ...
2454     if (has_body("application/sdp"))
2455         rtpengine_offer();
2456 ...
2457 }
2458 ...
2459 if (has_body("application/sdp")) {
2460                 if (rtpengine_offer("codec-mask=all codec-transcode=PCMU codec-transcode=PCMA"))
2461                                 t_on_reply("1");
2462 }
2463
2464 ...
2465 </programlisting>
2466                 </example>
2467         </section>
2468         <section id="rtpengine.f.rtpengine_answer">
2469                 <title>
2470                 <function moreinfo="none">rtpengine_answer([flags])</function>
2471                 </title>
2472                 <para>
2473                 Rewrites &sdp; body to ensure that media is passed through
2474                 an &rtp; proxy. To be invoked
2475                 on 200 OK for the cases the &sdp; bodies are in INVITE and 200 OK and on ACK
2476                 when &sdp; bodies are in 200 OK and ACK.
2477                 </para>
2478                 <para>
2479                 See rtpengine_offer() function description above for the meaning of the
2480                 parameters.
2481                 </para>
2482                 <para>
2483                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
2484                 FAILURE_ROUTE, BRANCH_ROUTE.
2485                 </para>
2486                 <example>
2487                  <title><function>rtpengine_answer</function> usage</title>
2488                 <para>
2489                 See rtpengine_offer() function example above for example.
2490                 </para>
2491                 </example>
2492         </section>
2493         <section id="rtpengine.f.rtpengine_info">
2494                 <title>
2495                 <function moreinfo="none">rtpengine_info([flags])</function>
2496                 </title>
2497                 <para>
2498                 Send an updated offer to rtpengine. This is meant to be used when processing
2499                 Tricke ICE &sdp; Fragments that are carried in &sip; INFO messages
2500                 and are proxied to endpoints that do not support ICE. With a matching
2501                 content type, the &sdp; fragment is used to update rtpengine's list of ICE
2502                 candidates. No new &sdp; is returned and so the &sip; INFO message should
2503                 be consumed after calling this function.
2504                 </para>
2505                 <para>
2506                 While this function supports the same flags as <quote>rtpengine_offer</quote>
2507                 et al, it is not normally necessary to provide any.
2508                 </para>
2509                 <para>
2510                 This function can be used from ANY_ROUTE.
2511                 </para>
2512                 <example>
2513                 <title><function>rtpengine_info</function> usage</title>
2514                 <programlisting format="linespecific">
2515 ...
2516 rtpengine_info();
2517 ...
2518 </programlisting>
2519                 </example>
2520         </section>
2521         <section id="rtpengine.f.rtpengine_delete">
2522                 <title>
2523                 <function moreinfo="none">rtpengine_delete([flags])</function>
2524                 </title>
2525                 <para>
2526                 Tears down the RTPProxy session for the current call.
2527                 This populates the statistics pseudovariables (such <quote>mos_min_pv</quote> etc).
2528                 </para>
2529                 <para>
2530                 See rtpengine_offer() function description above for the meaning of the
2531                 parameters. Note that not all flags make sense for a <quote>delete</quote>.
2532                 </para>
2533                 <para>
2534                 This function can be used from ANY_ROUTE.
2535                 </para>
2536                 <example>
2537                 <title><function>rtpengine_delete</function> usage</title>
2538                 <programlisting format="linespecific">
2539 ...
2540 rtpengine_delete();
2541 ...
2542 </programlisting>
2543                 </example>
2544         </section>
2545         <section id="rtpengine.f.rtpengine_query">
2546                 <title>
2547                 <function moreinfo="none">rtpengine_query([flags])</function>
2548                 </title>
2549                 <para>
2550                 Queries the &rtp; proxy about the current status and statistics of a running
2551                 call. This populates the statistics pseudovariables (such <quote>mos_min_pv</quote> etc).
2552                 </para>
2553                 <para>
2554                 See rtpengine_offer() function description above for the meaning of the
2555                 parameters. Note that not all flags make sense for a <quote>query</quote>.
2556                 </para>
2557                 <para>
2558                 This function can be used from ANY_ROUTE.
2559                 </para>
2560                 <example>
2561                 <title><function>rtpengine_query</function> usage</title>
2562                 <programlisting format="linespecific">
2563 ...
2564 rtpengine_query();
2565 ...
2566 </programlisting>
2567                 </example>
2568         </section>
2569
2570     <section id="rtpengine.f.rtpengine_manage">
2571         <title>
2572         <function moreinfo="none">rtpengine_manage([flags])</function>
2573         </title>
2574                 <para>
2575                 Manage the RTPEngine session - it combines the functionality of
2576                 rtpengine_offer(), rtpengine_answer() and rtpengine_delete(), detecting
2577                 internally based on message type and method which one to execute.
2578                 </para>
2579                 <para>
2580                 It can take the same parameters as <function>rtpengine_offer().</function>
2581                 The flags parameter to rtpengine_manage() can be a configuration variable
2582                 containing the flags as a string.
2583                 </para>
2584                 <para>
2585                 Functionality:
2586                 </para>
2587                 <itemizedlist>
2588                 <listitem>
2589                         <para>
2590                         If INVITE with &sdp;, then do <function>rtpengine_offer()</function>
2591                         </para>
2592                 </listitem>
2593                 <listitem>
2594                         <para>
2595                         If INVITE with &sdp;, when the tm module is loaded, mark transaction with
2596                         internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
2597                         <function>rtpengine_answer()</function>
2598                         </para>
2599                 </listitem>
2600                 <listitem>
2601                         <para>
2602                         If ACK with &sdp;, then do <function>rtpengine_answer()</function>
2603                         </para>
2604                 </listitem>
2605                 <listitem>
2606                         <para>
2607                         If BYE or CANCEL, or called within a FAILURE_ROUTE[], then call
2608                         <function>rtpengine_delete()</function>. Be careful with calling
2609                         this function after resuming a suspended transaction (e.g., after
2610                         t_continue()), because the context of executed route is FAILURE
2611                         ROUTE (in other words, rtpengine_manage() in the route block of
2612                         t_continue() does the same as in failure_route; use a branch route
2613                         to engage rtpengine for a forwarded branch after resuming the
2614                         transaction).
2615                         </para>
2616                 </listitem>
2617                 <listitem>
2618                         <para>
2619                         It does nothing if used inside event_route[tm:branch-failure:...]
2620                         </para>
2621                 </listitem>
2622                 <listitem>
2623                         <para>
2624                         If reply to INVITE with code >= 300 do <function>rtpengine_delete()</function>
2625                         </para>
2626                 </listitem>
2627                 <listitem>
2628                         <para>
2629                         If reply with &sdp; to INVITE having code 1xx and 2xx, then