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.
344 lines
12 KiB
344 lines
12 KiB
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
|
[ <!ENTITY % local.common.attrib
|
|
"xmlns:xi CDATA #FIXED 'http://www.w3.org/2001/XInclude'">
|
|
<!-- Include general documentation entities -->
|
|
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
|
|
%docentities;
|
|
]
|
|
>
|
|
|
|
|
|
<section id="iptrtpproxy.funcs" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<title>Functions</title>
|
|
|
|
<section id="iptrtpproxy_alloc">
|
|
<title>
|
|
<function>iptrtpproxy_alloc(gate_a_to_b [, existing_sess_ids])</function>
|
|
</title>
|
|
<para>
|
|
Parses SDP content and allocates for each RTP media stream one RTP proxy session.
|
|
SDP is updates to reflect allocated sessions. Switchboard/aggregation is set using
|
|
<function>iptrtpproxy_set_param(by_sip_ip)</function> or <function>iptrtpproxy_set_param("switchboard/aggregation")</function>.
|
|
</para>
|
|
<para>
|
|
Aggregation supports load balancing among more RTP proxies controlled by RPC.
|
|
The module try to allocate at machines/switchboards in following order (priorities)
|
|
not yet asked (or being heartbeated) machines, responsive machines, switchboards
|
|
having percentualy more free slots, non responsive machines.
|
|
</para>
|
|
<para>
|
|
Proxy may hide caller identity provided at <emphasis>o=</emphasis> line using
|
|
<function>@iptrtpproxy.o_name/addr</function> and <function>iptrtpproxy_set_param(o_name/addr)</function>
|
|
functions. But the script is responsible for rewritting to original values in
|
|
a response or a callee initiated re-INVITE. Therefore original value need to be stored
|
|
in-dialog.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
if <emphasis>gate_a_to_b</emphasis> bit 0 is set
|
|
then SDP regards to gate-a to gate-b direction.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>protected_session_ids</emphasis> list of existing sessions
|
|
enables reusing already allocated sessions in re-INVITE without
|
|
allocating new sessions for each stream in SDP regardless a IP/port
|
|
is required. It's mostly undesirable, typically "hold-on" is
|
|
done via re-INVITE without any change. There is drawback because
|
|
callee cannot change IP:port in 200OK which is legal case in RFC3264.
|
|
But because some non-RFC3264 compliant phones dislike proactively
|
|
changed IP:port at RTP proxy it seems it's less evil.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
function returns true is a session was created, identifier is available
|
|
via select <function>@iptrtpproxy.session_ids</function>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<example>
|
|
<title><function>iptrtpproxy_alloc</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
if (!iptrtpproxy_set_param("aggregation_by_sip_ip_a", "@received.ip")) {
|
|
if (!iptrtpproxy_set_param("switchboard_by_sip_ip_a", "@received.ip")) {
|
|
t_reply("500", "RTP proxy error");
|
|
drop;
|
|
}
|
|
}
|
|
eval_push("x:%@next_hop.src_ip");
|
|
if (@eval.get[-1] == @received.ip) {
|
|
if (@iptrtpproxy.aggregation_a) {
|
|
iptrtpproxy_set_param("aggregation_b", "@iptrtpproxy.aggregation_a");
|
|
}
|
|
else {
|
|
iptrtpproxy_set_param("switchboard_b", "@iptrtpproxy.switchboard_a");
|
|
}
|
|
}
|
|
else {
|
|
if (!iptrtpproxy_set_param("aggregation_by_sip_ip_b", "@eval.get[-1]")) {
|
|
if (!iptrtpproxy_set_param("switchboard_by_sip_ip_b", "@eval.get[-1]")) {
|
|
t_reply("500", "RTP proxy error");
|
|
drop;
|
|
}
|
|
}
|
|
}
|
|
eval_remove(-1, 1);
|
|
|
|
if (!iptrtpproxy_alloc("1")) {
|
|
t_reply("500", "RTP proxy error");
|
|
drop;
|
|
}
|
|
$sess_ids = @iptrtpproxy.session_ids;
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="iptrtpproxy_update">
|
|
<title>
|
|
<function>iptrtpproxy_update(gate_a_to_b, session_ids)</function>
|
|
</title>
|
|
<para>
|
|
Parses SDP content and updates sessions provided by <emphasis>session_ids</emphasis> and
|
|
updates SDP. If succesfull then session_ids may be changed (in case e.g. media
|
|
stream has port zero particular session is released), the
|
|
result of <function>@iptrtpproxy.session_ids</function> should be stored for future in-dialog usage.
|
|
</para>
|
|
<para>
|
|
The SDP contect is also affected by <function>iptrtpproxy_set_param(o_name/addr)</function>
|
|
functions. If a stream is deactivated in SDP then Sessions may be deleted unless
|
|
mentioned in <emphasis>protected_session_ids</emphasis>.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
if <emphasis>gate_a_to_b</emphasis> bit 0 is set
|
|
then SDP regards to gate-a to gate-b direction.
|
|
</para>
|
|
<para>
|
|
if <emphasis>gate_a_to_b</emphasis> bit 1 is set
|
|
then SDP is updated only, no RTP session are affected.
|
|
Should be used when handling retransmission in onreply route,
|
|
retransmission replies are not eaten be tm module!
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<example>
|
|
<title><function>iptrtpproxy_update</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
# load $sess_ids from dialog
|
|
if (iptrtpproxy_update("0", $sess_ids)) {
|
|
$sess_ids = @iptrtpproxy.session_ids;
|
|
# save sess_ids in dialog
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="iptrtpproxy_adjust_timeout">
|
|
<title>
|
|
<function>iptrtpproxy_adjust_timeout(gate_a_to_b, session_ids)</function>
|
|
</title>
|
|
<para>
|
|
Adjust timeout for particular gate. It's useful in "200 OK"
|
|
decrease timeout to learning timeout if INVITE has set (long) <emphasis>ringing timeout</emphasis>.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
if <emphasis>gate_a_to_b</emphasis> bit 0 is set
|
|
then it regards to gate-a to gate-b direction.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<example>
|
|
<title><function>iptrtpproxy_adjust_timeout</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
# load $sess_ids from dialog
|
|
if (status=~"18[0-9]") {
|
|
iptrtpproxy_set_param("learning_timeout", "60");
|
|
}
|
|
else {
|
|
iptrtpproxy_set_param("learning_timeout", "5");
|
|
}
|
|
if (iptrtpproxy_adjust_timeout("0", $sess_ids)) {
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="iptrtpproxy_delete">
|
|
<title>
|
|
<function>iptrtpproxy_delete(session_ids)</function>
|
|
</title>
|
|
<para>
|
|
Delete sessions identified by <emphasis>session_ids</emphasis>. May be used when dialog is being
|
|
destroyed (BYE) or when INVITE failed in failure route. If <emphasis>protected_session_ids</emphasis>
|
|
list is provided then this set is excluded from sessions to be deleted.
|
|
</para>
|
|
<example>
|
|
<title><function>iptrtpproxy_delete</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
# load $sess_ids from dialog
|
|
iptrtpproxy_delete($sess_ids);
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="iptrtpproxy_authorize_media">
|
|
<title>
|
|
<function>iptrtpproxy_authorize_media()</function>
|
|
</title>
|
|
<para>
|
|
Authorizes SDP media according currect <emphasis>codec_set</emphasis>. If bit AND operation
|
|
between rights in codec set and <function>remove_codec_mask</function> is non zero then
|
|
such a codec are to be removed. The result may be obtained from
|
|
<function>@iptrtpproxy.auth_rights</function> which returns max. right which has been applied when
|
|
processing all codecs of enabled streams.
|
|
</para>
|
|
<para>
|
|
The function MUST NOT be called after <function>iptrtpproxy_alloc/update</function>!
|
|
But the function may be called several times to authorize using more codec sets.
|
|
</para>
|
|
<example>
|
|
<title><function>iptrtpproxy_authorize_media</function> usage</title>
|
|
<programlisting>
|
|
...
|
|
if (@iptrtpproxy.active_media_num == "0") break;
|
|
iptrtpproxy_set_param("codec_set", "cs2");
|
|
iptrtpproxy_set_param("remove_codec_mask", "1");
|
|
if (!iptrtpproxy_authorize_media()) {
|
|
t_reply("415", "Cannot authorize media");
|
|
drop;
|
|
}
|
|
iptrtpproxy_set_param("codec_set", "cs3");
|
|
if (!iptrtpproxy_authorize_media()) {
|
|
t_reply("415", "Cannot authorize media");
|
|
drop;
|
|
}
|
|
if (@iptrtpproxy.active_media_num == "0") {
|
|
t_reply("488", "Not acceptable here");
|
|
drop;
|
|
}
|
|
if (@iptrtpproxy.auth_rights == "2") {
|
|
append_hf_value("Contact: <sip:1.2.3.4>");
|
|
t_reply("301", "Redirect to transcoder");
|
|
drop;
|
|
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
<section id="iptrtpproxy_set_param">
|
|
<title>
|
|
<function>iptrtpproxy_set_param(param, value)</function>
|
|
</title>
|
|
<para>
|
|
Set particular parameter needed mainly by <function>iptrtpproxy_alloc/update/adjust_timeout</function>.
|
|
The paramter value is availble via <function>@iptrtpproxy.<param></function>.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Supported parameters: <emphasis>expiration_timeout</emphasis>, <emphasis>ttl</emphasis>, <emphasis>learning_timeout</emphasis>,
|
|
<emphasis>always_learn</emphasis>,
|
|
<emphasis>aggregation_a</emphasis>, <emphasis>aggregation_b</emphasis>,
|
|
<emphasis>switchboard_a</emphasis>, <emphasis>switchboard_b</emphasis>,
|
|
<emphasis>throttle_mark</emphasis>,
|
|
<emphasis>throttle_rtp_max_bytes</emphasis>, <emphasis>throttle_rtp_max_packets</emphasis>,
|
|
<emphasis>throttle_rtcp_max_bytes</emphasis>, <emphasis>throttle_rtcp_max_packets</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section id="iptrtpproxy_set_param(by_sip_ip)">
|
|
<title>
|
|
<function>iptrtpproxy_set_param("(aggregation/switchboard)_by_sip_ip_(a/b)", sip_ip)</function>
|
|
</title>
|
|
<para>
|
|
Find corresponding aggregation or switchboard and set
|
|
<function>@iptrtpproxy.aggregation_a/b</function> or <function>@iptrtpproxy.switchboard_a/b</function>.
|
|
Switchboards/aggregations are compared against <emphasis>sip-addr</emphasis>,
|
|
it allow separate SIP and RTP traffic and RTP aggregation.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>sip_ip</emphasis> IP to be compared, typically <function>@received.ip</function>
|
|
or <function>@next_hop.src_ip</function>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
function returns true if switchboard/aggregation was found
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section id="iptrtpproxy_set_param(protected_session_ids)">
|
|
<title>
|
|
<function>iptrtpproxy_set_param("protected_session_ids", sess_ids)</function>
|
|
</title>
|
|
<para>
|
|
Used for reusing sessions in <function>iptrtpproxy_alloc</function>, <function>iptrtpproxy_update</function>
|
|
and <function>iptrtpproxy_delete</function>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="iptrtpproxy_set_param(o_name)">
|
|
<title>
|
|
<function>iptrtpproxy_set_param("o_name", value)</function>
|
|
</title>
|
|
<para>
|
|
Username to be rewritten at <emphasis>o=</emphasis> line by <function>iptrtpproxy_alloc/update</function>
|
|
to hide caller identity. If value is blank then username is left unchanged.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="iptrtpproxy_set_param(o_addr)">
|
|
<title>
|
|
<function>iptrtpproxy_set_param("o_addr", value)</function>
|
|
</title>
|
|
<para>
|
|
Address to be rewritten at <emphasis>o=</emphasis> line by <function>iptrtpproxy_alloc/update</function>
|
|
to hide caller identity. If value is blank then address is left unchanged.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="iptrtpproxy_set_param(codec_set)">
|
|
<title>
|
|
<function>iptrtpproxy_set_param("codec_set", value)</function>
|
|
</title>
|
|
<para>
|
|
Codec set for <function>iptrtpproxy_authorize_media</function>. Current codec set
|
|
may be obtained by <function>@iptrtpproxy.codec_set</function>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="iptrtpproxy_set_param(remove_codec_mask)">
|
|
<title>
|
|
<function>iptrtpproxy_set_param("remove_codec_mask", value)</function>
|
|
</title>
|
|
<para>
|
|
Mask used in <function>iptrtpproxy_authorize_media</function>. Current mask
|
|
may be obtained by <function>@iptrtpproxy.remove_codec_mask</function>.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|