mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1310 lines
48 KiB
1310 lines
48 KiB
<?xml version="1.0" encoding='ISO-8859-1'?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
|
|
|
|
<!-- Include general documentation entities -->
|
|
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
|
|
%docentities;
|
|
|
|
]>
|
|
|
|
<!-- Module User's Guide -->
|
|
|
|
<chapter>
|
|
|
|
<title>&adminguide;</title>
|
|
|
|
<section>
|
|
<title>Overview</title>
|
|
<para>
|
|
This is a module that enables media streams to be proxied
|
|
via an &rtp; proxy. The only &rtp; proxy currently known to work
|
|
with this module is the Sipwise rtpengine
|
|
<ulink url="https://github.com/sipwise/rtpengine"></ulink>.
|
|
The rtpengine module is a modified version of the original
|
|
rtpproxy module using a new control protocol. The module is
|
|
designed to be a drop-in replacement for the old module from
|
|
a configuration file point of view, however due to the
|
|
incompatible control protocol, it only works with &rtp; proxies
|
|
which specifically support it.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Multiple &rtp; proxy usage</title>
|
|
<para>
|
|
The rtpengine module can support multiple &rtp; proxies for
|
|
balancing/distribution and control/selection purposes.
|
|
</para>
|
|
<para>
|
|
The module allows definition of several sets of rtpproxies.
|
|
Load-balancing will be performed over a set and the admin has the
|
|
ability to choose what set should be used. The set is selected via
|
|
its id - the id being defined with the set. Refer to the
|
|
<quote>rtpengine_sock</quote> module parameter definition for syntax
|
|
description.
|
|
</para>
|
|
<para>
|
|
The balancing inside a set is done automatically by the module based on
|
|
the weight of each &rtp; proxy from the set.
|
|
</para>
|
|
<para>
|
|
The selection of the set is done from script prior using
|
|
rtpengine_delete(), rtpengine_offer() or rtpengine_answer()
|
|
functions - see the set_rtpengine_set() function.
|
|
</para>
|
|
<para>
|
|
Another way to select the set is to define setid_avp
|
|
module parameter and assign setid to the defined avp
|
|
before calling rtpengine_offer() or rtpengine_manage()
|
|
function. If forwarding of the requests fails and
|
|
there is another branch to try, remember to unset the
|
|
avp after calling rtpengine_delete() function.
|
|
</para>
|
|
<para>
|
|
For backward compatibility reasons, a set with no id take by default
|
|
the id 0. Also if no set is explicitly set before
|
|
rtpengine_delete(), rtpengine_offer() or rtpengine_answer()
|
|
the 0 id set will be used.
|
|
</para>
|
|
<para>
|
|
IMPORTANT: if you use multiple sets, take care and use the same set for
|
|
both rtpengine_offer()/rtpengine_answer() and rtpengine_delete()!!
|
|
If the set was selected using setid_avp, the avp needs to be
|
|
set only once before rtpengine_offer() or rtpengine_manage() call.
|
|
</para>
|
|
<para>
|
|
From the current implementation point of view, the sets of rtpproxy nodes
|
|
are shared memory(shm), so all processes can see a common list of nodes.
|
|
There is no locking when setting the nodes enabled/disabled (to keep the
|
|
memory access as fast as possible). Thus, problems related to node state
|
|
might appear for concurent processes that might set the nodes
|
|
enabled/disabled(e.g. by fifo command). This robustness problems are overcomed as follows.
|
|
</para>
|
|
|
|
<para>
|
|
If the current process sees the selected node as disabled, the node is
|
|
<emphasis>force tested</emphasis> before the current process actually
|
|
takes the disabled decision. If the test succeeds, the process will set
|
|
the node as enabled (but other concurrent process might still see it as disabled).
|
|
.
|
|
</para>
|
|
|
|
<para>
|
|
If the current process sees the selected node as enabled, it does no additional checks
|
|
and sends the command which will fail in case the machine is actually broken.
|
|
The process will set the node as disabled (but other concurrent process might still see it as enabled).
|
|
</para>
|
|
|
|
<para>
|
|
The 'kamctl fifo' commands (including rtpengin ones) are executed by an exclusive
|
|
process which operate on the same shared memory node list.
|
|
</para>
|
|
|
|
<para>
|
|
All the nodes are pinged in the beginning by all the processes,
|
|
even if the node list is shared memory.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Dependencies</title>
|
|
<section>
|
|
<title>&kamailio; Modules</title>
|
|
<para>
|
|
The following modules must be loaded before this module:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>tm module</emphasis> - (optional) if you want to
|
|
have rtpengine_manage() fully functional
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>External Libraries or Applications</title>
|
|
<para>
|
|
The following libraries or applications must be installed before
|
|
running &kamailio; with this module loaded:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>None</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Parameters</title>
|
|
<section id="rtpengine.p.rtpengine_sock">
|
|
<title><varname>rtpengine_sock</varname> (string)</title>
|
|
<para>
|
|
Definition of socket(s) used to connect to (a set) &rtp; proxy. It may
|
|
specify a UNIX socket or an IPv4/IPv6 UDP socket.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>NONE</quote> (disabled).
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>rtpengine_sock</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
# single rtproxy
|
|
modparam("rtpengine", "rtpengine_sock", "udp:localhost:12221")
|
|
# multiple rtproxies for LB with weights (missing weight defaults to 1)
|
|
modparam("rtpengine", "rtpengine_sock",
|
|
"udp:localhost:12221=2 udp:localhost:12222=1")
|
|
# multiple sets of multiple rtproxies
|
|
modparam("rtpengine", "rtpengine_sock",
|
|
"1 == udp:localhost:12221 udp:localhost:12222")
|
|
modparam("rtpengine", "rtpengine_sock",
|
|
"2 == udp:localhost:12225")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="rtpengine.p.rtpengine_disable_tout">
|
|
<title><varname>rtpengine_disable_tout</varname> (integer)</title>
|
|
<para>
|
|
Once an &rtp; proxy was found unreachable and marked as disabled, the rtpengine
|
|
module will not attempt to establish communication to that &rtp; proxy for
|
|
rtpengine_disable_tout seconds.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>60</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>rtpengine_disable_tout</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "rtpengine_disable_tout", 20)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="rtpengine.p.rtpengine_tout_ms">
|
|
<title><varname>rtpengine_tout_ms</varname> (integer)</title>
|
|
<para>
|
|
Timeout value expressed in milliseconds in waiting for reply from &rtp; proxy.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>1000</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>rtpengine_tout_ms</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "rtpengine_tout_ms", 2000)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="rtpengine.p.rtpengine_allow_op">
|
|
<title><varname>rtpengine_allow_op</varname> (integer)</title>
|
|
<para>
|
|
Enable this to allow finishing the current sessions while denying new sessions for the
|
|
<emphasis>manually deactivated nodes </emphasis> via kamctl command i.e. "disabled(permanent)" nodes.
|
|
Probably the manually deactivated machine is still running(did not crash).
|
|
</para>
|
|
<para>
|
|
This is <emphasis>useful</emphasis> when deactivating a node for maintanance and reject new sessions but allow current ones to finish.
|
|
</para>
|
|
<para>
|
|
The behaviour is the same for a rtpengine deleted table node.
|
|
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.
|
|
Next time the same node will be added in the table, and the content reloaded, it will be updated and re-displayed.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote> to keep the current behaviour.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>rtpengine_allow_op</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "rtpengine_allow_op", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="rtpengine.p.queried_nodes_limit">
|
|
<title><varname>queried_nodes_limit</varname> (integer)</title>
|
|
<para>
|
|
The total number of nodes inside a set (sets are configurable via rtpengine_sock function) to be queried
|
|
before giving up establishing a session. This brings more flexibility in case checking all rtpengines
|
|
would take too long. Max limit is 50.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
By default all nodes in a set are tried before giving up communicating with the rtpengines.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>queried_nodes_limit</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "queried_nodes_limit", 5)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="rtpengine.p.rtpengine_retr">
|
|
<title><varname>rtpengine_retr</varname> (integer)</title>
|
|
<para>
|
|
How many times the module should retry to send and receive after
|
|
timeout was generated.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>5</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>rtpengine_retr</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "rtpengine_retr", 2)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="rtpengine.p.extra_id_pv">
|
|
<title><varname>extra_id_pv</varname> (string)</title>
|
|
<para>
|
|
The parameter sets the PV defination to use when the <quote>b</quote>
|
|
parameter is used on rtpengine_delete(), rtpengine_offer(),
|
|
rtpengine_answer() or rtpengine_manage() command.
|
|
</para><para>
|
|
Default is empty, the <quote>b</quote> parameter may not be used then.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>extra_id_pv</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "extra_id_pv", "$avp(extra_id)")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="rtpengine.p.setid_avp">
|
|
<title><varname>setid_avp</varname> (string)</title>
|
|
<para>
|
|
The parameter defines an AVP that, if set,
|
|
determines which &rtp; proxy set
|
|
rtpengine_offer(), rtpengine_answer(),
|
|
rtpengine_delete(), and rtpengine_manage()
|
|
functions use.
|
|
</para>
|
|
<para>
|
|
There is no default value.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>setid_avp</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "setid_avp", "$avp(setid)")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="rtpengine.p.force_send_interface">
|
|
<title><varname>force_send_interface</varname> (string)</title>
|
|
<para>
|
|
Forces all control messages between the &sip; proxy and
|
|
the &rtp; proxy to be sent from the specified local
|
|
interface. Both IPv4 and IPv6 addresses are supported. If
|
|
not specified, the default interface selected by the
|
|
operating system will be used.
|
|
Note: when rtpengine_sock is a IPv6 link-local address,
|
|
one _must_ set this parameter in order to successfully connect to RTP engine.
|
|
This is necessarely because OS needs additional scope_id hint to communicate
|
|
over IPv6 link locals. The scope_id is resolved based on the given IPv6.
|
|
</para>
|
|
<para>
|
|
There is no default value.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>force_send_interface</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "force_send_interface", "10.3.7.123")
|
|
modparam("rtpengine", "force_send_interface", "2001:8d8:1ff:10c0:9a90:96ff:fea8:fd99")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="rtpengine.p.read_sdp_pv">
|
|
<title><varname>read_sdp_pv</varname> (string)</title>
|
|
<para>
|
|
If this parameter is set to a valid AVP or script var specifier, rtpengine
|
|
will take the input SDP from this pv instead of the message body.
|
|
</para>
|
|
<para>
|
|
There is no default value.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>read_sdp_pv</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "read_sdp_pv", "$var(sdp)")
|
|
...
|
|
route {
|
|
...
|
|
$var(sdp) = $rb + "a=foo:bar\r\n";
|
|
rtpengine_manage();
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="rtpengine.p.write_sdp_pv">
|
|
<title><varname>write_sdp_pv</varname> (string)</title>
|
|
<para>
|
|
If this parameter is set to a valid AVP or script var specifier, the
|
|
SDP returned by rtpengine in the offer/answer operations
|
|
is returned in the specified variable instead of the
|
|
message body.
|
|
</para>
|
|
<para>
|
|
There is no default value.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>write_sdp_pv</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "write_sdp_pv", "$avp(sdp)")
|
|
...
|
|
route {
|
|
...
|
|
rtpengine_manage();
|
|
set_body("$avp(sdp)a=baz123\r\n", "application/sdp");
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="rtpengine.p.rtp_inst_pvar">
|
|
<title><varname>rtp_inst_pvar</varname> (string)</title>
|
|
<para>
|
|
A pseudo variable to store the chosen RTP Engine IP address.
|
|
If this parameter is set, the IP address and port of the instance chosen will be stored in the given variable.
|
|
</para>
|
|
<para>
|
|
By default, this parameter is not set.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>rtp_inst_pvar</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "rtp_inst_pvar", "$avp(RTP_INSTANCE)")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="rtpengine.p.hash_table_size">
|
|
<title><varname>hash_table_size</varname> (integer)</title>
|
|
<para>
|
|
Size of the hash table. Default value is 256.
|
|
</para>
|
|
<para>
|
|
NOTE: If configured size is <emphasis>less than</emphasis> 1, the size will be defaulted to 1.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>hash_table_size</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "hash_table_size", "123")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="rtpengine.p.hash_table_tout">
|
|
<title><varname>hash_table_tout</varname> (integer)</title>
|
|
<para>
|
|
Number of seconds after an rtpengine hash table entry is marked for deletion.
|
|
By default, this parameter is set to 3600 (seconds).
|
|
</para>
|
|
<para>
|
|
To maintain information about a selected rtp machine node, for a given call, entries are added in a hashtable of (callid, node) pairs.
|
|
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.
|
|
</para>
|
|
<para>
|
|
NOTE: In the current implementation, the actual deletion happens <emphasis>on the fly</emphasis>,
|
|
while insert/remove/lookup the hastable, <emphasis>only</emphasis> for the entries in the insert/remove/lookup path.
|
|
</para>
|
|
<para>
|
|
NOTE: When configuring this parameter, one should consider maximum call time VS share memory for unfinished calls.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>hash_table_tout</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "hash_table_tout", "300")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section id="rtpengine.p.db_url">
|
|
<title><varname>db_url</varname> (string)</title>
|
|
<para>
|
|
The rtpengine datablase url. If present and valid, it activates database mode.
|
|
Node information is read from database, not from config.
|
|
</para>
|
|
<para>
|
|
By default, the datablase url is NULL (not set).
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_url</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "db_url", "mysql://pass@localhost/db")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
<section id="rtpengine.p.table_name">
|
|
<title><varname>table_name</varname> (string)</title>
|
|
<para>
|
|
The rtpengine table name. If database mode is activated (i.e. valid db_url),
|
|
set the name of rtpengine table, on startup.
|
|
</para>
|
|
<para>
|
|
By default, the rtpengine table name is "rtpengine".
|
|
</para>
|
|
<para>
|
|
NOTE: One needs to add the version of the rtpengine table in the version table.
|
|
The current version is version 1.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>table_name</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "table_name", "rtpengine_table_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Setup <varname>rtpengine</varname> table</title>
|
|
<programlisting format="linespecific">
|
|
mysql> describe rtpengine;
|
|
+----------+------------------+------+-----+---------+-------+
|
|
| Field | Type | Null | Key | Default | Extra |
|
|
+----------+------------------+------+-----+---------+-------+
|
|
| setid | int(10) unsigned | NO | | NULL | |
|
|
| url | varchar(256) | NO | | NULL | |
|
|
| weight | int(10) unsigned | NO | | NULL | |
|
|
| disabled | int(11) | NO | | NULL | |
|
|
+----------+------------------+------+-----+---------+-------+
|
|
|
|
mysql> select * from rtpengine;
|
|
+-------+---------------------------+--------+----------+
|
|
| setid | url | weight | disabled |
|
|
+-------+---------------------------+--------+----------+
|
|
| 0 | udp:rtpproxy1.domain:8800 | 100 | 0 |
|
|
| 0 | udp:rtpproxy2.domain:8800 | 200 | 1 |
|
|
+-------+---------------------------+--------+----------+
|
|
|
|
mysql> select * from version;
|
|
+---------------------------+---------------+
|
|
| table_name | table_version |
|
|
+---------------------------+---------------+
|
|
| rtpengine | 1 |
|
|
+---------------------------+---------------+
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
<section id="rtpengine.p.setid_col">
|
|
<title><varname>setid_col</varname> (string)</title>
|
|
<para>
|
|
Column name in the rtpengine table. If database mode is activated (i.e. valid db_url),
|
|
set the setid of rtp nodes according to this column, on startup.
|
|
The MySQL value for this column should be INT UNSIGNED.
|
|
</para>
|
|
<para>
|
|
By default, the column name is "setid".
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>setid_col</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "setid_col", "setid_column_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
<section id="rtpengine.p.url_col">
|
|
<title><varname>url_col</varname> (string)</title>
|
|
<para>
|
|
Column name in the rtpengine table. If database mode is activated (i.e. valid db_url),
|
|
set the url of rtp nodes according to this column, on startup.
|
|
The MySQL value for this column should be VARCHAR.
|
|
</para>
|
|
<para>
|
|
By default, the column name is "url".
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>url_col</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "url_col", "url_column_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
<section id="rtpengine.p.weight_col">
|
|
<title><varname>weight_col</varname> (string)</title>
|
|
<para>
|
|
Column name in the rtpengine table. If database mode is activated (i.e. valid db_url),
|
|
set the weight of rtp nodes according to this column, on startup. The column value has
|
|
priority over the URL weight.
|
|
The MySQL value for this column should be INT UNSIGNED.
|
|
</para>
|
|
<para>
|
|
By default, the column name is "weight".
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>weight_col</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "weight_col", "weight_column_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
<section id="rtpengine.p.disabled_col">
|
|
<title><varname>disabled_col</varname> (string)</title>
|
|
<para>
|
|
Column name in the rtpengine table. If database mode is activated (i.e. valid db_url),
|
|
set the state of rtp nodes according to this column, on startup.
|
|
The MySQL value for this column should be INT.
|
|
</para>
|
|
<para>
|
|
By default, the column name is "disabled".
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>disabled_col</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "disabled_col", "disabled_column_name")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
<section id="rtpengine.p.setid_default">
|
|
<title><varname>setid_default</varname> (string)</title>
|
|
<para>
|
|
The default set of nodes to be used.
|
|
</para>
|
|
<para>
|
|
By default, the setid is 0.
|
|
</para>
|
|
<para>
|
|
NOTE that if setid_avp is configured, this value will be ignored and
|
|
the active set will be chosen according to the setid_avp.
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>setid_default</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("rtpengine", "setid_default", 11)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
<section>
|
|
<title>Functions</title>
|
|
<section id="rtpengine.f.set_rtpengine_set">
|
|
<title>
|
|
<function moreinfo="none">set_rtpengine_set(setid[, setid])</function>
|
|
</title>
|
|
<para>
|
|
Sets the ID of the &rtp; proxy set to be used for the next
|
|
rtpengine_delete(), rtpengine_offer(), rtpengine_answer()
|
|
or rtpengine_manage() command. The parameter can be an integer or
|
|
a config variable holding an integer.
|
|
</para>
|
|
<para>
|
|
A second set ID can be specified to daisy-chain two &rtp; proxies.
|
|
The two set IDs must be distinct from each other and there must not
|
|
be any overlap in the proxies present in both sets. In this use case,
|
|
the request (offer, answer, etc) is first sent to an &rtp; proxy from
|
|
the first set, which rewrites the &sdp; body and sends it back to the
|
|
module. The rewritten &sdp; body is then used to make another request
|
|
to an &rtp; proxy from the second set, which rewrites the &sdp; body
|
|
another time and sends it back to the module to be placed back into the
|
|
&sip; message. This is useful if you have a set of &rtp; proxies that
|
|
the caller must use, and another distinct set of &rtp; proxies that the
|
|
callee must use. This is supported by all rtpengine commands except
|
|
rtpengine_manage().
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
|
|
BRANCH_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>set_rtpengine_set</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
set_rtpengine_set("2");
|
|
rtpengine_offer();
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="rtpengine.f.rtpengine_offer">
|
|
<title>
|
|
<function moreinfo="none">rtpengine_offer([flags])</function>
|
|
</title>
|
|
<para>
|
|
Rewrites &sdp; body to ensure that media is passed through
|
|
an &rtp; proxy. To be invoked
|
|
on INVITE for the cases the &sdp; bodies are in INVITE and 200 OK and on 200 OK
|
|
when &sdp; bodies are in 200 OK and ACK.
|
|
</para>
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>flags</emphasis> - flags to turn on some features.
|
|
</para>
|
|
<para>The <quote>flags</quote> string is a list of space-separated items. Each item
|
|
is either an individual token, or a token in <quote>key=value</quote> format. The
|
|
possible tokens are described below.</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
<emphasis>via-branch=...</emphasis> - Include the <quote>branch</quote>
|
|
value of one of the <quote>Via</quote> headers in the request to the
|
|
&rtp; proxy. Possible values are:
|
|
<quote>1</quote> - use the first <quote>Via</quote> header;
|
|
<quote>2</quote> - use the second <quote>Via</quote> header;
|
|
<quote>auto</quote> - use the first <quote>Via</quote> header if this is
|
|
a request, or the second one if this is a reply;
|
|
<quote>extra</quote> - don't take the value from a header, but instead use
|
|
the value of the <quote>extra_id_pv</quote> variable.
|
|
This can be used to create one media session per branch
|
|
on the &rtp; proxy. When sending a subsequent <quote>delete</quote> command to
|
|
the &rtp; proxy, you can then stop just the session for a specific branch when
|
|
passing the flag '1' or '2' in the <quote>rtpengine_delete</quote>, or stop
|
|
all sessions for a call when not passing one of those two flags there. This is
|
|
especially useful if you have serially forked call scenarios where the &rtp; proxy
|
|
gets an <quote>offer</quote> command for a new branch, and then a
|
|
<quote>delete</quote> command for the previous branch, which would otherwise
|
|
delete the full call, breaking the subsequent <quote>answer</quote> for the
|
|
new branch. <emphasis>This flag is only supported by the Sipwise rtpengine
|
|
&rtp; proxy at the moment!</emphasis>
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>asymmetric</emphasis> - flags that UA from which message is
|
|
received doesn't support symmetric &rtp;. Disables learning of endpoint addresses
|
|
in the Sipwise rtpengine proxy.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>force-answer</emphasis> - force <quote>answer</quote>, that is,
|
|
only rewrite &sdp; when corresponding session already exists
|
|
in the &rtp; proxy. By default is on when the session is to be
|
|
completed.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>direction=...</emphasis> - this option specifies a logical network
|
|
interface and should be given exactly twice. It enables &rtp; bridging between
|
|
different addresses or networks of the same family (e.g. IPv4 to IPv4). The
|
|
first instance of the option
|
|
specifies the interface that the originator of this message should be using,
|
|
while the second instance specifies the interface that the target should be
|
|
using. For example, if the &sip; message was sent by an endpoint on a private
|
|
network and will be sent to an endpoint on the public internet, you would use
|
|
<quote>direction=priv direction=pub</quote> if those two logical network
|
|
interfaces were called <quote>priv</quote> and <quote>pub</quote> in your
|
|
&rtp; proxy's configuration respectively. The direction must only be specified
|
|
in for initial &sdp; offer; answers or subsequent offers can omit this option.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>internal, external</emphasis> - shorthand for
|
|
<quote>direction=internal</quote> and <quote>direction=external</quote>
|
|
respectively. Useful for brevity or as legacy option if the &rtp; proxy only
|
|
supports two network interfaces instead of multiple, arbitrarily named ones.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>auto-bridge</emphasis> - this flag an alternative to the
|
|
<quote>internal</quote> and <quote>external</quote> flags
|
|
in order to do automatic bridging between IPv4 on the
|
|
"internal network" and IPv6 on the "external network". Instead of
|
|
explicitly instructing the &rtp; proxy to select a particular address
|
|
family, the distinction is done by the given IP in the &sdp; body by
|
|
the &rtp; proxy itself. Not supported by Sipwise rtpengine.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>address-family=...</emphasis> - instructs the &rtp; proxy that the
|
|
recipient of this &sdp; body expects to see addresses of a particular family.
|
|
Possible values are <quote>IP4</quote> and <quote>IP6</quote>. For example,
|
|
if the &sdp; body contains IPv4 addresses but the recipient only speaks IPv6,
|
|
you would use <quote>address-family=IP6</quote> to bridge between the two
|
|
address families.
|
|
</para><para>
|
|
Sipwise rtpengine remembers the address family preference of each party after
|
|
it has seen an &sdp; body from them. This means that normally it is only
|
|
necessary to explicitly specify the address family in the <quote>offer</quote>,
|
|
but not in the <quote>answer</quote>.
|
|
</para><para>
|
|
Note: Please note, that this will only work properly with non-dual-stack user-agents or with
|
|
dual-stack clients according to RFC6157 (which suggest ICE for Dual-Stack implementations).
|
|
This short-cut will not work properly with RFC4091 (ANAT) compatible clients, which suggests
|
|
having different m-lines with different IP-protocols grouped together.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>force</emphasis> - instructs the &rtp; proxy to ignore marks
|
|
inserted by another &rtp; proxy in transit to indicate that the
|
|
session is already goes through another proxy. Allows creating
|
|
a chain of proxies. Not supported and ignored by Sipwise rtpengine.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>trust-address</emphasis> - flags that IP address in &sdp; should
|
|
be trusted. Starting with rtpengine 3.8, this is the default behaviour.
|
|
In older versions, without this flag the &rtp; proxy ignores the address in
|
|
the &sdp; and uses source address of the &sip; message as media
|
|
address which is passed to the &rtp; proxy.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>SIP-source-address</emphasis> - the opposite of
|
|
<emphasis>trust-address</emphasis>. Restores the old default behaviour
|
|
of ignoring endpoint addresses in the &sdp; body.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>replace-origin</emphasis> - flags that IP from the origin
|
|
description (o=) should be also changed.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>replace-session-connection</emphasis> - flags to change the session-level
|
|
&sdp; connection (c=) IP if media description also includes
|
|
connection information.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>symmetric</emphasis> - flags that for the UA from which
|
|
message is received, support symmetric &rtp; must be forced. Does nothing with
|
|
the Sipwise rtpengine proxy as it is the default.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>repacketize=NN</emphasis> - requests the &rtp; proxy to perform
|
|
re-packetization of &rtp; traffic coming from the UA which
|
|
has sent the current message to increase or decrease payload
|
|
size per each &rtp; packet forwarded if possible. The NN is the
|
|
target payload size in ms, for the most codecs its value should
|
|
be in 10ms increments, however for some codecs the increment
|
|
could differ (e.g. 30ms for GSM or 20ms for G.723). The
|
|
&rtp; proxy would select the closest value supported by the codec.
|
|
This feature could be used for significantly reducing bandwith
|
|
overhead for low bitrate codecs, for example with G.729 going
|
|
from 10ms to 100ms saves two thirds of the network bandwith.
|
|
Not supported by Sipwise rtpengine.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>ICE=...</emphasis> - controls the &rtp; proxy's behaviour
|
|
regarding ICE attributes within the &sdp; body. Possible values
|
|
are: <quote>force</quote> -
|
|
discard any ICE attributes already present in the &sdp; body
|
|
and then generate and insert new ICE data, leaving itself
|
|
as the <emphasis>only</emphasis> ICE candidates;
|
|
<quote>force-relay</quote> -
|
|
discard any <quote>relay</quote> type ICE attributes already present
|
|
in the &sdp; body and then generate and insert itself
|
|
as the <emphasis>only</emphasis> ICE <quote>relay</quote> candidates;
|
|
<quote>remove</quote> instructs the &rtp; proxy to discard
|
|
any ICE attributes and not insert any new ones into the &sdp;.
|
|
The default (if no <quote>ICE=...</quote> is given at all),
|
|
new ICE data will only be generated
|
|
if no ICE was present in the &sdp; originally; otherwise
|
|
the &rtp; proxy will only insert itself as
|
|
<emphasis>additional</emphasis> ICE candidate. Other
|
|
&sdp; substitutions (c=, m=, etc) are unaffected by this flag.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>RTP, SRTP, AVP, AVPF</emphasis> - These flags control the &rtp;
|
|
transport protocol that should be used towards the recipient of
|
|
the &sdp;. If none of them are specified, the protocol given in
|
|
the &sdp; is left untouched. Otherwise, the <quote>SRTP</quote> flag indicates that
|
|
SRTP should be used, while <quote>RTP</quote> indicates that SRTP should not be used.
|
|
<quote>AVPF</quote> indicates that the advanced RTCP profile with feedback messages
|
|
should be used, and <quote>AVP</quote> indicates that the regular RTCP profile
|
|
should be used. See also the next set of flags below.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>RTP/AVP, RTP/SAVP, RTP/AVPF, RTP/SAVPF</emphasis> - these serve as
|
|
an alternative, more explicit way to select between the different &rtp; protocols
|
|
and profiles supported by the &rtp; proxy. For example, giving the flag
|
|
<quote>RTP/SAVPF</quote> has the same effect as giving the two flags
|
|
<quote>SRTP AVPF</quote>.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>to-tag</emphasis> - force inclusion of the <quote>To</quote> tag.
|
|
Normally, the <quote>To</quote> tag is always included when present, except
|
|
for <quote>delete</quote> messages. Including the <quote>To</quote> tag in
|
|
a <quote>delete</quote> messages allows you to be more selective about which
|
|
dialogues within a call are being torn down.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>rtcp-mux-demux</emphasis> - if rtcp-mux (RFC 5761) was
|
|
offered, make the &rtp; proxy accept the offer, but not offer it to the
|
|
recipient of this message.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>rtcp-mux-reject</emphasis> - if rtcp-mux was offered, make the
|
|
&rtp; proxy reject the offer, but still offer it to the recipient. Can be
|
|
combined with <quote>rtcp-mux-offer</quote> to always offer it.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>rtcp-mux-offer</emphasis> - make the &rtp; proxy offer rtcp-mux
|
|
to the recipient of this message, regardless of whether it was offered
|
|
originally or not.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>rtcp-mux-accept</emphasis> - if rtcp-mux was offered, make the
|
|
&rtp; proxy accept the offer and also offer it to the recipient of this
|
|
message. Can be combined with <quote>rtcp-mux-offer</quote> to always offer it.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>media-address=...</emphasis> - force a particular media address to
|
|
be used in the &sdp; body. Address family is detected automatically.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>TOS=...</emphasis> - change the IP TOS value for all outgoing &rtp;
|
|
packets within the entire call in both directions. Only honoured in an
|
|
<quote>offer</quote>, ignored for an <quote>answer</quote>. Valid values are
|
|
0 through 255, given in decimal. If this option is not specified, the TOS
|
|
value will revert to the default TOS (normally 184). A value of -1 may be used
|
|
to leave the currently used TOS unchanged.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>delete-delay=...</emphasis> - override the default delay (in seconds)
|
|
before a call is actually deleted from memory. Can be set to zero to effectuate
|
|
immediate deletion. This option only makes sense for <emphasis>delete</emphasis>
|
|
operations.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>strict-source</emphasis> - instructs the &rtp; proxy to check the
|
|
source addresses of all incoming &rtp; packets and drop the packets if the
|
|
address doesn't match.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>media-handover</emphasis> - the antithesis of
|
|
<emphasis>strict-source</emphasis>. Instructs the &rtp; proxy not only to accept
|
|
mismatching &rtp; source addresses (as it normally would), but also to accept
|
|
them as the new endpoint address of the opposite media flow. Not recommended
|
|
as it allows media streams to be hijacked by an attacker.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>DTLS=...</emphasis> - influence the behaviour of DTLS-SRTP. Possible
|
|
values are <quote>no</quote> or <quote>off</quote> to suppress offering or
|
|
accepting DTLS-SRTP, and <quote>passive</quote> to prefer participating in
|
|
DTLS-SRTP in a passive role.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>SDES-off</emphasis> - don't offer SDES when it normally would. In an SRTP
|
|
context, this leaves DTLS-SRTP as the only other option.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>SDES-unencrypted_srtp, SDES-unencrypted_srtcp,
|
|
SDES-unauthenticated_srtp</emphasis> - these directly reflect the SDES session
|
|
parameters from RFC 4568 and will make the &rtp; proxy offer these parameters
|
|
when offering SDES.
|
|
</para></listitem>
|
|
<listitem><para>
|
|
<emphasis>SDES-encrypted_srtp, SDES-encrypted_srtcp,
|
|
SDES-authenticated_srtp</emphasis> - the opposites of the flags above. Useful
|
|
if accepting these parameters is not desired and they should be rejected instead.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>rtpengine_offer</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
route {
|
|
...
|
|
if (is_method("INVITE")) {
|
|
if (has_body("application/sdp")) {
|
|
if (rtpengine_offer())
|
|
t_on_reply("1");
|
|
} else {
|
|
t_on_reply("2");
|
|
}
|
|
}
|
|
if (is_method("ACK") && has_body("application/sdp"))
|
|
rtpengine_answer();
|
|
...
|
|
}
|
|
|
|
onreply_route[1]
|
|
{
|
|
...
|
|
if (has_body("application/sdp"))
|
|
rtpengine_answer();
|
|
...
|
|
}
|
|
|
|
onreply_route[2]
|
|
{
|
|
...
|
|
if (has_body("application/sdp"))
|
|
rtpengine_offer();
|
|
...
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="rtpengine.f.rtpengine_answer">
|
|
<title>
|
|
<function moreinfo="none">rtpengine_answer([flags])</function>
|
|
</title>
|
|
<para>
|
|
Rewrites &sdp; body to ensure that media is passed through
|
|
an &rtp; proxy. To be invoked
|
|
on 200 OK for the cases the &sdp; bodies are in INVITE and 200 OK and on ACK
|
|
when &sdp; bodies are in 200 OK and ACK.
|
|
</para>
|
|
<para>
|
|
See rtpengine_offer() function description above for the meaning of the
|
|
parameters.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
|
|
FAILURE_ROUTE, BRANCH_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>rtpengine_answer</function> usage</title>
|
|
<para>
|
|
See rtpengine_offer() function example above for example.
|
|
</para>
|
|
</example>
|
|
</section>
|
|
<section id="rtpengine.f.rtpengine_delete">
|
|
<title>
|
|
<function moreinfo="none">rtpengine_delete([flags])</function>
|
|
</title>
|
|
<para>
|
|
Tears down the RTPProxy session for the current call.
|
|
</para>
|
|
<para>
|
|
See rtpengine_offer() function description above for the meaning of the
|
|
parameters. Note that not all flags make sense for a <quote>delete</quote>.
|
|
</para>
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>rtpengine_delete</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
rtpengine_delete();
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="rtpengine.f.rtpengine_manage">
|
|
<title>
|
|
<function moreinfo="none">rtpengine_manage([flags])</function>
|
|
</title>
|
|
<para>
|
|
Manage the RTPProxy session - it combines the functionality of
|
|
rtpengine_offer(), rtpengine_answer() and rtpengine_delete(), detecting
|
|
internally based on message type and method which one to execute.
|
|
</para>
|
|
<para>
|
|
It can take the same parameters as <function>rtpengine_offer().</function>
|
|
The flags parameter to rtpengine_manage() can be a configuration variable
|
|
containing the flags as a string.
|
|
</para>
|
|
<para>
|
|
Functionality:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
If INVITE with &sdp;, then do <function>rtpengine_offer()</function>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If INVITE with &sdp;, when the tm module is loaded, mark transaction with
|
|
internal flag FL_SDP_BODY to know that the 1xx and 2xx are for
|
|
<function>rtpengine_answer()</function>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If ACK with &sdp;, then do <function>rtpengine_answer()</function>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If BYE or CANCEL, or called within a FAILURE_ROUTE[], then call
|
|
<function>rtpengine_delete()</function>. Be careful with calling
|
|
this function after resuming a suspended transaction (e.g., after
|
|
t_continue()), because the context of executed route is FAILURE
|
|
ROUTE (in other words, rtpengine_manage() in the route block of
|
|
t_continue() does the same as in failure_route).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If reply to INVITE with code >= 300 do <function>rtpengine_delete()</function>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If reply with &sdp; to INVITE having code 1xx and 2xx, then
|
|
do <function>rtpengine_answer()</function> if the request had &sdp; or tm is not loaded,
|
|
otherwise do <function>rtpengine_offer()</function>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
This function can be used from ANY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>rtpengine_manage</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
rtpengine_manage();
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="rtpengine.f.start_recording">
|
|
<title>
|
|
<function moreinfo="none">start_recording()</function>
|
|
</title>
|
|
<para>
|
|
This function will send a signal to the &rtp; proxy to record
|
|
the &rtp; stream on the &rtp; proxy.
|
|
<emphasis>This function is not supported by Sipwise rtpengine at the moment!</emphasis>
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE and ONREPLY_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>start_recording</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
start_recording();
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Exported Pseudo Variables</title>
|
|
<section>
|
|
<title><function moreinfo="none">$rtpstat</function></title>
|
|
<para>
|
|
Returns the &rtp; statistics from the &rtp; proxy. The &rtp; statistics from the &rtp; proxy
|
|
are provided as a string and it does contain several packet counters. The statistics
|
|
must be retrieved before the session is deleted (before <function>rtpengine_delete()</function>).
|
|
</para>
|
|
|
|
<example>
|
|
<title>$rtpstat Usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
append_hf("X-RTP-Statistics: $rtpstat\r\n");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title><acronym>MI</acronym> Commands</title>
|
|
<section id="rtpengine.m.nh_enable_rtpp">
|
|
<title><function moreinfo="none">nh_enable_rtpp proxy_url/all 0/1</function></title>
|
|
<para>
|
|
Enables a &rtp; proxy if the second parameter value is greater than 0. Disables it if a zero value is given.
|
|
The first parameter is either a specific &rtp; proxy url (exactly as defined in
|
|
the config file) or the keyword <emphasis>all</emphasis>.
|
|
The second parameter value must be a number in decimal.
|
|
</para>
|
|
<para>
|
|
When try to enable the &rtp; proxy, an application ping command is sent to it.
|
|
If it fails, the proxy is not enabled.
|
|
Displays <emphasis>success</emphasis> or <emphasis>fail</emphasis> when try to enable/disable.
|
|
</para>
|
|
<para>
|
|
NOTE: If a &rtp; proxy is defined multiple times (in the same or diferent sets), all of its instances will be enabled/disabled.
|
|
</para>
|
|
<para>
|
|
NOTE: If a &rtp; proxy is in the disabled permanent state and one tries to enable it, even if the ping fails,
|
|
it is moved to a disabled temporary state and a recheck_ticks are given to it.
|
|
While the recheck_ticks are grater than 0, the proxy is considered disabled temporary, and it is not taken into consideration for sending data.
|
|
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.
|
|
</para>
|
|
<para>
|
|
NOTE: When specify the IPv6 &rtp; proxy url one must prefix it with <emphasis>::</emphasis>
|
|
to escape the :: from the IPv6 address. See the example below.
|
|
</para>
|
|
<example>
|
|
<title>
|
|
<function moreinfo="none">nh_enable_rtpp</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
$ &ctltool; fifo nh_enable_rtpp udp:192.168.2.133:8081 0
|
|
$ &ctltool; fifo nh_enable_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999 1
|
|
$ &ctltool; fifo nh_enable_rtpp all 1
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="rtpengine.m.nh_show_rtpp">
|
|
<title><function moreinfo="none">nh_show_rtpp proxy_url/all</function></title>
|
|
<para>
|
|
Displays all the &rtp; proxies and their information: set and
|
|
status (disabled or not, weight and recheck_ticks). If a &rtp; proxy has been disabled by
|
|
nh_enable_rtpp mi command a "(permanent)" quote will appear when printing the disabled status.
|
|
This is to differentiate from a temporary disable due to the proxy being not found responsive
|
|
by kamailio. In addition, when disabled permanent, recheck_ticks have no meaning and "N\A"
|
|
is printed instead of the value.
|
|
</para>
|
|
<para>
|
|
It takes either a specific &rtp; proxy url (exactly as defined in
|
|
the config file) or the keyword <emphasis>all</emphasis> as a parameter.
|
|
</para>
|
|
<para>
|
|
NOTE: When specify the IPv6 &rtp; proxy url one must prefix it with <emphasis>::</emphasis>
|
|
to escape the :: from the IPv6 address. See the example below.
|
|
</para>
|
|
<example>
|
|
<title>
|
|
<function moreinfo="none">nh_show_rtpp</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
$ &ctltool; fifo nh_show_rtpp udp:192.168.2.133:8081
|
|
$ &ctltool; fifo nh_show_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999
|
|
$ &ctltool; fifo nh_show_rtpp all
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="rtpengine.m.nh_ping_rtpp">
|
|
<title><function moreinfo="none">nh_ping_rtpp proxy_url/all</function></title>
|
|
<para>
|
|
Sends an application ping command to the &rtp; proxy. If the proxy does not respond,
|
|
it will be disabled, but not permanent. If the proxy responds, no action is taken.
|
|
Displays the ping result, i.e.
|
|
<emphasis>success</emphasis> or <emphasis>fail</emphasis> when try to ping.
|
|
</para>
|
|
<para>
|
|
It takes either a specific &rtp; proxy url (exactly as defined in
|
|
the config file) or the keyword <emphasis>all</emphasis> as a parameter.
|
|
</para>
|
|
<para>
|
|
NOTE: When specify the IPv6 &rtp; proxy url one must prefix it with <emphasis>::</emphasis>
|
|
to escape the :: from the IPv6 address. See the example below.
|
|
</para>
|
|
<example>
|
|
<title>
|
|
<function moreinfo="none">nh_ping_rtpp</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
$ &ctltool; fifo nh_ping_rtpp udp:192.168.2.133:8081
|
|
$ &ctltool; fifo nh_ping_rtpp ::udp6:fe80::9a90:96ff:fea8:fd99:9999
|
|
$ &ctltool; fifo nh_ping_rtpp all
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
<section id="rtpengine.m.nh_reload_rtpp">
|
|
<title><function moreinfo="none">nh_reload_rtpp</function></title>
|
|
<para>
|
|
Reloads the database node table content <emphasis>if configured</emphasis>.
|
|
Returns specific message related to success, failure and no db_url configured.
|
|
</para>
|
|
<para>
|
|
NOTE: The current behaviour updates the nodes state or creates new ones or
|
|
hides old ones, based on the database content. If allow_op modparam is enabled,
|
|
the sessions are still allowed to finish for the hidden old nodes.
|
|
</para>
|
|
<example>
|
|
<title>
|
|
<function moreinfo="none">nh_reload_rtpp</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
$ &ctltool; fifo nh_reload_rtpp
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
|
|
<section id="rtpengine.m.nh_show_hash_total">
|
|
<title><function moreinfo="none">nh_show_hash_total</function></title>
|
|
<para>
|
|
Print the total number of hash entries in the hash table at a given moment.
|
|
</para>
|
|
<example>
|
|
<title>
|
|
<function moreinfo="none">nh_show_hash_total</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
$ &ctltool; fifo nh_show_hash_total
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</chapter>
|
|
|