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