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