rtpengine Add result code for rtpengine_offer (et al) to README and regenerate README
[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>
706                 The function will return true on success and false (-1) on various failures,
707                 like using rtp_engine_offer() on a SIP MESSAGE request or communication with
708                 rtpengine fails.
709                 </para>
710                 <para>Meaning of the parameters is as follows:</para>
711                 <itemizedlist>
712                 <listitem>
713                         <para>
714                         <emphasis>flags</emphasis> - flags to turn on some features.
715                         </para>
716                         <para>The <quote>flags</quote> string is a list of space-separated items. Each item
717                         is either an individual token, or a token in <quote>key=value</quote> format. The
718                         possible tokens are described below.</para>
719                         <itemizedlist>
720                                 <listitem><para>
721                                 <emphasis>via-branch=...</emphasis> - Include the <quote>branch</quote>
722                                 value of one of the <quote>Via</quote> headers in the request to the
723                                 &rtp; proxy. Possible values are:
724                                 <quote>1</quote> - use the first <quote>Via</quote> header;
725                                 <quote>2</quote> - use the second <quote>Via</quote> header;
726                                 <quote>auto</quote> - use the first <quote>Via</quote> header if this is
727                                 a request, or the second one if this is a reply;
728                                 <quote>extra</quote> - don't take the value from a header, but instead use
729                                 the value of the <quote>extra_id_pv</quote> variable.
730                                 This can be used to create one media session per branch
731                                 on the &rtp; proxy. When sending a subsequent <quote>delete</quote> command to
732                                 the &rtp; proxy, you can then stop just the session for a specific branch when
733                                 passing the flag '1' or '2' in the <quote>rtpengine_delete</quote>, or stop
734                                 all sessions for a call when not passing one of those two flags there. This is
735                                 especially useful if you have serially forked call scenarios where the &rtp; proxy
736                                 gets an <quote>offer</quote> command for a new branch, and then a
737                                 <quote>delete</quote> command for the previous branch, which would otherwise
738                                 delete the full call, breaking the subsequent <quote>answer</quote> for the
739                                 new branch. <emphasis>This flag is only supported by the Sipwise rtpengine
740                                 &rtp; proxy at the moment!</emphasis>
741                                 </para></listitem>
742                                 <listitem><para>
743                                 <emphasis>asymmetric</emphasis> - flags that UA from which message is
744                                 received doesn't support symmetric &rtp;. Disables learning of endpoint addresses
745                                 in the Sipwise rtpengine proxy.
746                                 </para></listitem>
747                                 <listitem><para>
748                                 <emphasis>force-answer</emphasis> - force <quote>answer</quote>, that is,
749                                 only rewrite &sdp; when corresponding session already exists
750                                 in the &rtp; proxy. By default is on when the session is to be
751                                 completed.
752                                 </para></listitem>
753                                 <listitem><para>
754                                 <emphasis>direction=...</emphasis> - this option specifies a logical network
755                                 interface and should be given exactly twice. It enables &rtp; bridging between
756                                 different addresses or networks of the same family (e.g. IPv4 to IPv4). The
757                                 first instance of the option
758                                 specifies the interface that the originator of this message should be using,
759                                 while the second instance specifies the interface that the target should be
760                                 using. For example, if the &sip; message was sent by an endpoint on a private
761                                 network and will be sent to an endpoint on the public internet, you would use
762                                 <quote>direction=priv direction=pub</quote> if those two logical network
763                                 interfaces were called <quote>priv</quote> and <quote>pub</quote> in your
764                                 &rtp; proxy's configuration respectively. The direction must only be specified
765                                 in for initial &sdp; offer; answers or subsequent offers can omit this option.
766                                 </para></listitem>
767                                 <listitem><para>
768                                 <emphasis>internal, external</emphasis> - shorthand for
769                                 <quote>direction=internal</quote> and <quote>direction=external</quote>
770                                 respectively. Useful for brevity or as legacy option if the &rtp; proxy only
771                                 supports two network interfaces instead of multiple, arbitrarily named ones.
772                                 </para></listitem>
773                                 <listitem><para>
774                                 <emphasis>auto-bridge</emphasis> - this flag an alternative to the
775                                 <quote>internal</quote> and <quote>external</quote> flags
776                                 in order to do automatic bridging between IPv4 on the
777                                 "internal network" and IPv6 on the "external network". Instead of
778                                 explicitly instructing the &rtp; proxy to select a particular address
779                                 family, the distinction is done by the given IP in the &sdp; body by
780                                 the &rtp; proxy itself. Not supported by Sipwise rtpengine.
781                                 </para></listitem>
782                                 <listitem><para>
783                                 <emphasis>address-family=...</emphasis> - instructs the &rtp; proxy that the
784                                 recipient of this &sdp; body expects to see addresses of a particular family.
785                                 Possible values are <quote>IP4</quote> and <quote>IP6</quote>. For example,
786                                 if the &sdp; body contains IPv4 addresses but the recipient only speaks IPv6,
787                                 you would use <quote>address-family=IP6</quote> to bridge between the two
788                                 address families.
789                                 </para><para>
790                                 Sipwise rtpengine remembers the address family preference of each party after
791                                 it has seen an &sdp; body from them. This means that normally it is only
792                                 necessary to explicitly specify the address family in the <quote>offer</quote>,
793                                 but not in the <quote>answer</quote>.
794                                 </para><para>
795                                 Note: Please note, that this will only work properly with non-dual-stack user-agents or with
796                                 dual-stack clients according to RFC6157 (which suggest ICE for Dual-Stack implementations).
797                                 This short-cut will not work properly with RFC4091 (ANAT) compatible clients, which suggests
798                                 having different m-lines with different IP-protocols grouped together.
799                                 </para></listitem>
800                                 <listitem><para>
801                                 <emphasis>force</emphasis> - instructs the &rtp; proxy to ignore marks
802                                 inserted by another &rtp; proxy in transit to indicate that the
803                                 session is already goes through another proxy. Allows creating
804                                 a chain of proxies. Not supported and ignored by Sipwise rtpengine.
805                                 </para></listitem>
806                                 <listitem><para>
807                                 <emphasis>trust-address</emphasis> - flags that IP address in &sdp; should
808                                 be trusted. Starting with rtpengine 3.8, this is the default behaviour.
809                                 In older versions, without this flag the &rtp; proxy ignores the address in
810                                 the &sdp; and uses source address of the &sip; message as media
811                                 address which is passed to the &rtp; proxy.
812                                 </para></listitem>
813                                 <listitem><para>
814                                 <emphasis>SIP-source-address</emphasis> - the opposite of
815                                 <emphasis>trust-address</emphasis>. Restores the old default behaviour
816                                 of ignoring endpoint addresses in the &sdp; body.
817                                 </para></listitem>
818                                 <listitem><para>
819                                 <emphasis>replace-origin</emphasis> - flags that IP from the origin
820                                 description (o=) should be also changed.
821                                 </para></listitem>
822                                 <listitem><para>
823                                 <emphasis>replace-session-connection</emphasis> - flags to change the session-level
824                                 &sdp; connection (c=) IP if media description also includes
825                                 connection information.
826                                 </para></listitem>
827                                 <listitem><para>
828                                 <emphasis>symmetric</emphasis> - flags that for the UA from which
829                                 message is received, support symmetric &rtp; must be forced. Does nothing with
830                                 the Sipwise rtpengine proxy as it is the default.
831                                 </para></listitem>
832                                 <listitem><para>
833                                 <emphasis>repacketize=NN</emphasis> - requests the &rtp; proxy to perform
834                                 re-packetization of &rtp; traffic coming from the UA which
835                                 has sent the current message to increase or decrease payload
836                                 size per each &rtp; packet forwarded if possible.  The NN is the
837                                 target payload size in ms, for the most codecs its value should
838                                 be in 10ms increments, however for some codecs the increment
839                                 could differ (e.g. 30ms for GSM or 20ms for G.723).  The
840                                 &rtp; proxy would select the closest value supported by the codec.
841                                 This feature could be used for significantly reducing bandwith
842                                 overhead for low bitrate codecs, for example with G.729 going
843                                 from 10ms to 100ms saves two thirds of the network bandwith.
844                                 Not supported by Sipwise rtpengine.
845                                 </para></listitem>
846                                 <listitem><para>
847                                 <emphasis>ICE=...</emphasis> - controls the &rtp; proxy's behaviour
848                                 regarding ICE attributes within the &sdp; body. Possible values
849                                 are: <quote>force</quote> -
850                                 discard any ICE attributes already present in the &sdp; body
851                                 and then generate and insert new ICE data, leaving itself
852                                 as the <emphasis>only</emphasis> ICE candidates;
853                                 <quote>force-relay</quote> -
854                                 discard any <quote>relay</quote> type ICE attributes already present
855                                 in the &sdp; body and then generate and insert itself
856                                 as the <emphasis>only</emphasis> ICE <quote>relay</quote> candidates;
857                                 <quote>remove</quote> instructs the &rtp; proxy to discard
858                                 any ICE attributes and not insert any new ones into the &sdp;.
859                                 The default (if no <quote>ICE=...</quote> is given at all),
860                                 new ICE data will only be generated
861                                 if no ICE was present in the &sdp; originally; otherwise
862                                 the &rtp; proxy will only insert itself as
863                                 <emphasis>additional</emphasis> ICE candidate. Other
864                                 &sdp; substitutions (c=, m=, etc) are unaffected by this flag.
865                                 </para></listitem>
866                                 <listitem><para>
867                                 <emphasis>RTP, SRTP, AVP, AVPF</emphasis> - These flags control the &rtp;
868                                 transport protocol that should be used towards the recipient of
869                                 the &sdp;. If none of them are specified, the protocol given in
870                                 the &sdp; is left untouched. Otherwise, the <quote>SRTP</quote> flag indicates that
871                                 SRTP should be used, while <quote>RTP</quote> indicates that SRTP should not be used.
872                                 <quote>AVPF</quote> indicates that the advanced RTCP profile with feedback messages
873                                 should be used, and <quote>AVP</quote> indicates that the regular RTCP profile
874                                 should be used. See also the next set of flags below.
875                                 </para></listitem>
876                                 <listitem><para>
877                                 <emphasis>RTP/AVP, RTP/SAVP, RTP/AVPF, RTP/SAVPF</emphasis> - these serve as
878                                 an alternative, more explicit way to select between the different &rtp; protocols
879                                 and profiles supported by the &rtp; proxy. For example, giving the flag
880                                 <quote>RTP/SAVPF</quote> has the same effect as giving the two flags
881                                 <quote>SRTP AVPF</quote>.
882                                 </para></listitem>
883                                 <listitem><para>
884                                 <emphasis>to-tag</emphasis> - force inclusion of the <quote>To</quote> tag.
885                                 Normally, the <quote>To</quote> tag is always included when present, except
886                                 for <quote>delete</quote> messages. Including the <quote>To</quote> tag in
887                                 a <quote>delete</quote> messages allows you to be more selective about which
888                                 dialogues within a call are being torn down.
889                                 </para></listitem>
890                                 <listitem><para>
891                                 <emphasis>rtcp-mux-demux</emphasis> - if rtcp-mux (RFC 5761) was
892                                 offered, make the &rtp; proxy accept the offer, but not offer it to the
893                                 recipient of this message.
894                                 </para></listitem>
895                                 <listitem><para>
896                                 <emphasis>rtcp-mux-reject</emphasis> - if rtcp-mux was offered, make the
897                                 &rtp; proxy reject the offer, but still offer it to the recipient. Can be
898                                 combined with <quote>rtcp-mux-offer</quote> to always offer it.
899                                 </para></listitem>
900                                 <listitem><para>
901                                 <emphasis>rtcp-mux-offer</emphasis> - make the &rtp; proxy offer rtcp-mux
902                                 to the recipient of this message, regardless of whether it was offered
903                                 originally or not.
904                                 </para></listitem>
905                                 <listitem><para>
906                                 <emphasis>rtcp-mux-accept</emphasis> - if rtcp-mux was offered, make the
907                                 &rtp; proxy accept the offer and also offer it to the recipient of this
908                                 message. Can be combined with <quote>rtcp-mux-offer</quote> to always offer it.
909                                 </para></listitem>
910                                 <listitem><para>
911                                 <emphasis>media-address=...</emphasis> - force a particular media address to
912                                 be used in the &sdp; body. Address family is detected automatically.
913                                 </para></listitem>
914                                 <listitem><para>
915                                 <emphasis>TOS=...</emphasis> - change the IP TOS value for all outgoing &rtp;
916                                 packets within the entire call in both directions. Only honoured in an
917                                 <quote>offer</quote>, ignored for an <quote>answer</quote>. Valid values are
918                                 0 through 255, given in decimal. If this option is not specified, the TOS
919                                 value will revert to the default TOS (normally 184). A value of -1 may be used
920                                 to leave the currently used TOS unchanged.
921                                 </para></listitem>
922                                 <listitem><para>
923                                 <emphasis>delete-delay=...</emphasis> - override the default delay (in seconds)
924                                 before a call is actually deleted from memory. Can be set to zero to effectuate
925                                 immediate deletion. This option only makes sense for <emphasis>delete</emphasis>
926                                 operations.
927                                 </para></listitem>
928                                 <listitem><para>
929                                 <emphasis>strict-source</emphasis> - instructs the &rtp; proxy to check the
930                                 source addresses of all incoming &rtp; packets and drop the packets if the
931                                 address doesn't match.
932                                 </para></listitem>
933                                 <listitem><para>
934                                 <emphasis>media-handover</emphasis> - the antithesis of
935                                 <emphasis>strict-source</emphasis>. Instructs the &rtp; proxy not only to accept
936                                 mismatching &rtp; source addresses (as it normally would), but also to accept
937                                 them as the new endpoint address of the opposite media flow. Not recommended
938                                 as it allows media streams to be hijacked by an attacker.
939                                 </para></listitem>
940                                 <listitem><para>
941                                 <emphasis>DTLS=...</emphasis> - influence the behaviour of DTLS-SRTP. Possible
942                                 values are <quote>no</quote> or <quote>off</quote> to suppress offering or
943                                 accepting DTLS-SRTP, and <quote>passive</quote> to prefer participating in
944                                 DTLS-SRTP in a passive role.
945                                 </para></listitem>
946                                 <listitem><para>
947                                 <emphasis>SDES-off</emphasis> - don't offer SDES when it normally would. In an SRTP
948                                 context, this leaves DTLS-SRTP as the only other option.
949                                 </para></listitem>
950                                 <listitem><para>
951                                 <emphasis>SDES-unencrypted_srtp, SDES-unencrypted_srtcp,
952                                 SDES-unauthenticated_srtp</emphasis> - these directly reflect the SDES session
953                                 parameters from RFC 4568 and will make the &rtp; proxy offer these parameters
954                                 when offering SDES.
955                                 </para></listitem>
956                                 <listitem><para>
957                                 <emphasis>SDES-encrypted_srtp, SDES-encrypted_srtcp,
958                                 SDES-authenticated_srtp</emphasis> - the opposites of the flags above. Useful
959                                 if accepting these parameters is not desired and they should be rejected instead.
960                                 </para></listitem>
961                         </itemizedlist>
962                 </listitem>
963                 </itemizedlist>
964                 <para>
965                 This function can be used from ANY_ROUTE.
966                 </para>
967                 <example>
968                 <title><function>rtpengine_offer</function> usage</title>
969                 <programlisting format="linespecific">
970 route {
971 ...
972     if (is_method("INVITE")) {
973         if (has_body("application/sdp")) {
974             if (rtpengine_offer())
975                 t_on_reply("1");
976         } else {
977             t_on_reply("2");
978         }
979     }
980     if (is_method("ACK") &amp;&amp; has_body("application/sdp"))
981         rtpengine_answer();
982 ...
983 }
984
985 onreply_route[1]
986 {
987 ...
988     if (has_body("application/sdp"))
989         rtpengine_answer();
990 ...
991 }
992
993 onreply_route[2]
994 {
995 ...
996     if (has_body("application/sdp"))
997         rtpengine_offer();
998 ...
999 }
1000 </programlisting>
1001                 </example>
1002         </section>
1003         <section id="rtpengine.f.rtpengine_answer">
1004                 <title>
1005                 <function moreinfo="none">rtpengine_answer([flags])</function>
1006                 </title>
1007                 <para>
1008                 Rewrites &sdp; body to ensure that media is passed through
1009                 an &rtp; proxy. To be invoked
1010                 on 200 OK for the cases the &sdp; bodies are in INVITE and 200 OK and on ACK
1011                 when &sdp; bodies are in 200 OK and ACK.
1012                 </para>
1013                 <para>
1014                 See rtpengine_offer() function description above for the meaning of the
1015                 parameters.
1016                 </para>
1017                 <para>
1018                 This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
1019                 FAILURE_ROUTE, BRANCH_ROUTE.
1020                 </para>
1021                 <example>
1022                  <title><function>rtpengine_answer</function> usage</title>
1023                 <para>
1024                 See rtpengine_offer() function example above for example.
1025                 </para>
1026                 </example>
1027         </section>
1028         <section id="rtpengine.f.rtpengine_delete">
1029                 <title>
1030                 <function moreinfo="none">rtpengine_delete([flags])</function>
1031                 </title>
1032                 <para>
1033                 Tears down the RTPProxy session for the current call.
1034                 </para>
1035                 <para>
1036                 See rtpengine_offer() function description above for the meaning of the
1037                 parameters. Note that not all flags make sense for a <quote>delete</quote>.
1038                 </para>
1039                 <para>
1040                 This function can be used from ANY_ROUTE.
1041                 </para>
1042                 <example>
1043                 <title><function>rtpengine_delete</function> usage</title>
1044                 <programlisting format="linespecific">
1045 ...
1046 rtpengine_delete();
1047 ...
1048 </programlisting>
1049                 </example>
1050         </section>
1051
1052     <section id="rtpengine.f.rtpengine_manage">
1053         <title>
1054         <function moreinfo="none">rtpengine_manage([flags])</function>
1055         </title>
1056                 <para>
1057                 Manage the RTPProxy session - it combines the functionality of
1058                 rtpengine_offer(), rtpengine_answer() and rtpengine_delete(), detecting
1059                 internally based on message type and method which one to execute.
1060                 </para>
1061                 <para>
1062                 It can take the same parameters as <function>rtpengine_offer().</function>
1063                 The flags parameter to rtpengine_manage() can be a configuration variable
1064                 containing the flags as a string.
1065                 </para>
1066                 <para>
1067                 Functionality:
1068                 </para>
1069                 <itemizedlist>
1070                 <listitem>
1071                         <para>
1072                         If INVITE with &sdp;, then do <function>rtpengine_offer()</function>
1073                         </para>
1074                 </listitem>
1075                 <listitem>
1076                         <para>
1077                         If INVITE with &sdp;, when the tm module is loaded, mark transaction with
1078                         internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
1079                         <function>rtpengine_answer()</function>
1080                         </para>
1081                 </listitem>
1082                 <listitem>
1083                         <para>
1084                         If ACK with &sdp;, then do <function>rtpengine_answer()</function>
1085                         </para>
1086                 </listitem>
1087                 <listitem>
1088                         <para>
1089                         If BYE or CANCEL, or called within a FAILURE_ROUTE[], then do <function>rtpengine_delete()</function>
1090                         </para>
1091                 </listitem>
1092                 <listitem>
1093                         <para>
1094                         If reply to INVITE with code >= 300 do <function>rtpengine_delete()</function>
1095                         </para>
1096                 </listitem>
1097                 <listitem>
1098                         <para>
1099                         If reply with &sdp; to INVITE having code 1xx and 2xx, then
1100                         do <function>rtpengine_answer()</function> if the request had &sdp; or tm is not loaded,
1101                         otherwise do <function>rtpengine_offer()</function>
1102                         </para>
1103                 </listitem>
1104         </itemizedlist>
1105
1106                 <para>
1107                 This function can be used from ANY_ROUTE.
1108                 </para>
1109                 <example>
1110                  <title><function>rtpengine_manage</function> usage</title>
1111                 <programlisting format="linespecific">
1112 ...
1113 rtpengine_manage();
1114 ...
1115 </programlisting>
1116                 </example>
1117         </section>
1118
1119         <section id="rtpengine.f.start_recording">
1120                 <title>
1121                 <function moreinfo="none">start_recording()</function>
1122                 </title>
1123                 <para>
1124                 This function will send a signal to the &rtp; proxy to record
1125                 the &rtp; stream on the &rtp; proxy.
1126                 <emphasis>This function is not supported by Sipwise rtpengine at the moment!</emphasis>
1127                 </para>
1128                 <para>
1129                 This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
1130                 </para>
1131                 <example>
1132                 <title><function>start_recording</function> usage</title>
1133                 <programlisting format="linespecific">
1134 ...
1135 start_recording();
1136 ...
1137                 </programlisting>
1138                 </example>
1139         </section>
1140
1141
1142         </section>
1143
1144         <section>
1145                 <title>Exported Pseudo Variables</title>
1146                 <section>
1147                         <title><function moreinfo="none">$rtpstat</function></title>
1148                         <para>
1149                         Returns the &rtp; statistics from the &rtp; proxy. The &rtp; statistics from the &rtp; proxy
1150                         are provided as a string and it does contain several packet counters. The statistics
1151                         must be retrieved before the session is deleted (before <function>rtpengine_delete()</function>).
1152                         </para>
1153
1154                 <example>
1155                 <title>$rtpstat Usage</title>
1156                 <programlisting format="linespecific">
1157 ...
1158     append_hf("X-RTP-Statistics: $rtpstat\r\n");
1159 ...
1160                 </programlisting>
1161                 </example>
1162                 </section>
1163
1164         </section>
1165
1166         <section>
1167                 <title><acronym>MI</acronym> Commands</title>
1168                 <section id="rtpengine.m.nh_enable_rtpp">
1169                         <title><function moreinfo="none">nh_enable_rtpp proxy_url/all 0/1</function></title>
1170                         <para>
1171                         Enables a &rtp; proxy if the second parameter value is greater than 0. Disables it if a zero value is given.
1172                         The first parameter is either a specific &rtp; proxy url (exactly as defined in
1173                         the config file) or the keyword <emphasis>all</emphasis>.
1174                         The second parameter value must be a number in decimal.
1175                         </para>
1176                         <para>
1177             When try to enable the &rtp; proxy, an application ping command is sent to it.
1178             If it fails, the proxy is not enabled.
1179             Displays <emphasis>success</emphasis> or <emphasis>fail</emphasis> when try to enable/disable.
1180                         </para>
1181                         <para>
1182                         NOTE: If a &rtp; proxy is defined multiple times (in the same or diferent sets), all of its instances will be enabled/disabled.
1183                         </para>
1184                         <para>
1185                         NOTE: If a &rtp; proxy is in the disabled permanent state and one tries to enable it, even if the ping fails,
1186             it is moved to a disabled temporary state and a recheck_ticks are given to it.
1187             While the recheck_ticks are grater than 0, the proxy is considered disabled temporary, and it is not taken into consideration for sending data.
1188             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.
1189                         </para>
1190                         <para>
1191                         NOTE: When specify the IPv6 &rtp; proxy url one must prefix it with <emphasis>::</emphasis>
1192             to escape the :: from the IPv6 address. See the example below.
1193                         </para>
1194                         <example>
1195                         <title>
1196                         <function moreinfo="none">nh_enable_rtpp</function> usage</title>
1197                         <programlisting format="linespecific">
1198 ...
1199 $ &ctltool; fifo nh_enable_rtpp udp:192.168.2.133:8081 0
1200 $ &ctltool; fifo nh_enable_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999 1
1201 $ &ctltool; fifo nh_enable_rtpp all 1
1202 ...
1203                         </programlisting>
1204                         </example>
1205                 </section>
1206
1207             <section id="rtpengine.m.nh_show_rtpp">
1208                         <title><function moreinfo="none">nh_show_rtpp proxy_url/all</function></title>
1209                         <para>
1210                         Displays all the &rtp; proxies and their information: set and
1211                         status (disabled or not, weight and recheck_ticks). If a &rtp; proxy has been disabled by
1212             nh_enable_rtpp mi command a "(permanent)" quote will appear when printing the disabled status.
1213             This is to differentiate from a temporary disable due to the proxy being not found responsive
1214             by kamailio. In addition, when disabled permanent, recheck_ticks have no meaning and "N\A"
1215             is printed instead of the value.
1216                         </para>
1217                         <para>
1218             It takes either a specific &rtp; proxy url (exactly as defined in
1219                         the config file) or the keyword <emphasis>all</emphasis> as a parameter.
1220                         </para>
1221                         <para>
1222                         NOTE: When specify the IPv6 &rtp; proxy url one must prefix it with <emphasis>::</emphasis>
1223             to escape the :: from the IPv6 address. See the example below.
1224                         </para>
1225                         <example>
1226                         <title>
1227                                 <function moreinfo="none">nh_show_rtpp</function> usage</title>
1228                         <programlisting format="linespecific">
1229 ...
1230 $ &ctltool; fifo nh_show_rtpp udp:192.168.2.133:8081
1231 $ &ctltool; fifo nh_show_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999
1232 $ &ctltool; fifo nh_show_rtpp all
1233 ...
1234                         </programlisting>
1235                         </example>
1236                 </section>
1237
1238             <section id="rtpengine.m.nh_ping_rtpp">
1239                         <title><function moreinfo="none">nh_ping_rtpp proxy_url/all</function></title>
1240                         <para>
1241             Sends an application ping command to the &rtp; proxy. If the proxy does not respond,
1242             it will be disabled, but not permanent. If the proxy responds, no action is taken.
1243             Displays the ping result, i.e.
1244             <emphasis>success</emphasis> or <emphasis>fail</emphasis> when try to ping.
1245                         </para>
1246                         <para>
1247             It takes either a specific &rtp; proxy url (exactly as defined in
1248                         the config file) or the keyword <emphasis>all</emphasis> as a parameter.
1249                         </para>
1250                         <para>
1251                         NOTE: When specify the IPv6 &rtp; proxy url one must prefix it with <emphasis>::</emphasis>
1252             to escape the :: from the IPv6 address. See the example below.
1253                         </para>
1254                         <example>
1255                         <title>
1256                                 <function moreinfo="none">nh_ping_rtpp</function> usage</title>
1257                         <programlisting format="linespecific">
1258 ...
1259 $ &ctltool; fifo nh_ping_rtpp udp:192.168.2.133:8081
1260 $ &ctltool; fifo nh_ping_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999
1261 $ &ctltool; fifo nh_ping_rtpp all
1262 ...
1263                         </programlisting>
1264                         </example>
1265                 </section>
1266
1267
1268             <section id="rtpengine.m.nh_reload_rtpp">
1269                         <title><function moreinfo="none">nh_reload_rtpp</function></title>
1270                         <para>
1271                                 Reloads the database node table content <emphasis>if configured</emphasis>.
1272                                 Returns specific message related to success, failure and no db_url configured.
1273                         </para>
1274                         <para>
1275                                 NOTE: The current behaviour updates the nodes state or creates new ones or
1276                                 hides old ones, based on the database content. If allow_op modparam is enabled,
1277                                 the sessions are still allowed to finish for the hidden old nodes.
1278                         </para>
1279                         <example>
1280                         <title>
1281                                 <function moreinfo="none">nh_reload_rtpp</function> usage</title>
1282                         <programlisting format="linespecific">
1283 ...
1284 $ &ctltool; fifo nh_reload_rtpp
1285 ...
1286                         </programlisting>
1287                         </example>
1288                 </section>
1289
1290
1291             <section id="rtpengine.m.nh_show_hash_total">
1292                         <title><function moreinfo="none">nh_show_hash_total</function></title>
1293                         <para>
1294                                 Print the total number of hash entries in the hash table at a given moment.
1295                         </para>
1296                         <example>
1297                         <title>
1298                                 <function moreinfo="none">nh_show_hash_total</function> usage</title>
1299                         <programlisting format="linespecific">
1300 ...
1301 $ &ctltool; fifo nh_show_hash_total
1302 ...
1303                         </programlisting>
1304                         </example>
1305                 </section>
1306
1307         </section>
1308
1309 </chapter>
1310