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.
362 lines
11 KiB
362 lines
11 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 module implements various utility functions that are not SIP
|
|
related.
|
|
</para>
|
|
<para>
|
|
Function http_query allows &kamailio; to issue an HTTP GET
|
|
request and get access to parts of the reply.
|
|
</para>
|
|
<para>
|
|
The forward functionality allows &kamailio; to configure forwarding
|
|
at runtime with FIFO commands. The forwarding is executed in the pre
|
|
script call back and therefore handled before the routing script is
|
|
executed on the current message. The callback is not installed on
|
|
default, thus this functionality has no runtime overhead when its
|
|
deactivated.
|
|
</para>
|
|
<para>
|
|
Function xcap_auth_status can be used to check from presence
|
|
server database, if watcher is authorized to subscribe event
|
|
<quote>presence</quote> of presentity.
|
|
</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>a database module if
|
|
xcap_auth_status function is enabled</emphasis>.
|
|
</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>libcurl</emphasis>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Parameters</title>
|
|
<section id="utils.p.http_query_timeout">
|
|
<title><varname>http_query_timeout</varname> (int)</title>
|
|
<para>
|
|
Defines in seconds how long &kamailio; waits for response
|
|
from HTTP server.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is zero, i.e.,
|
|
that the http_query_timeout function is disabled.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>http_query_timeout</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("utils", "http_query_timeout", 2)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="utils.p.forward_active">
|
|
<title><varname>forward_active</varname> (int)</title>
|
|
<para>
|
|
Defines if the forwarding callback should be installed.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0</quote> - disabled.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>forward_active</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("utils", "forward_active", 1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="utils.p.pres_db_url">
|
|
<title><varname>pres_db_url</varname> (string)</title>
|
|
<para>
|
|
Defines presence server database URL. If not
|
|
given, the xcap_auth_status function is disabled.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
There is no default value.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>pres_db_url</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("utils", "pres_db_url", "mysql://foo:secret@localhost/pres")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="utils.p.xcap_table">
|
|
<title><varname>xcap_table</varname> (string)</title>
|
|
<para>
|
|
Defines the name of the xcap table in the presence server database.
|
|
See the xcap_server module documentation for more information.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>xcap</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>xcap_table</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("utils", "xcap_table", "pres_xcap")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Functions</title>
|
|
<section id="utils.f.http_query">
|
|
<title>
|
|
<function moreinfo="none">http_query(url, [post-data], result)</function>
|
|
</title>
|
|
<para>
|
|
Sends HTTP GET or POST request according to URL given in
|
|
<quote>url</quote> parameter, which is a string that may
|
|
contain pseudo variables.
|
|
</para>
|
|
<para>
|
|
If you want to make a POST-Request, you have to define
|
|
the <quote>post</quote>-data, that should be submitted
|
|
in that request as the second parameter.
|
|
</para>
|
|
<para>
|
|
If HTTP server returns a class 2xx or 3xx reply,
|
|
the first line of the reply's body (if any) is
|
|
stored in <quote>result</quote> parameter,
|
|
which must be a writable pseudo variable.
|
|
</para>
|
|
<para>
|
|
Function returns reply code of HTTP reply or -1
|
|
if something went wrong.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE,
|
|
ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>http_query()</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
# GET-Request
|
|
http_query("http://tutpro.com/index.php?r_uri=$(ru{s.escape.param})&f_uri=$(fu{s.escape.param})",
|
|
"$var(result)")
|
|
switch ($retcode) {
|
|
...
|
|
}
|
|
...
|
|
</programlisting>
|
|
<programlisting format="linespecific">
|
|
...
|
|
# POST-Request
|
|
http_query("http://tutpro.com/index.php", "r_uri=$(ru{s.escape.param})&f_uri=$(fu{s.escape.param})",
|
|
"$var(result)")
|
|
switch ($retcode) {
|
|
...
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="utils.f.xcap_auth_status">
|
|
<title>
|
|
<function moreinfo="none">xcap_auth_status(watcher_uri, presentity_uri)</function>
|
|
</title>
|
|
<para>
|
|
Function checks in the presence server database if
|
|
a watcher is authorized to subscribe to event
|
|
<quote>presence</quote> of presentity. Sphere
|
|
checking is not included.
|
|
</para>
|
|
<para>
|
|
Both watcher_uri and presentity_uri are
|
|
pseudo variables. The function returns
|
|
ACTIVE_STATUS, if a subscription is
|
|
allowed and PENDING_STATUS, TERMINATED_STATUS,
|
|
or WAITING_STATUS otherwise. See
|
|
presence/subscribe.h for the corresponding integer
|
|
codes. In case of error, function returns -1.
|
|
</para>
|
|
<para>
|
|
Function can be used from REQUEST_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>xcap_auth_status()</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (method=="MESSAGE") {
|
|
xcap_auth_status("$fu", $ru");
|
|
if ($retcode == 1) {
|
|
t_relay();
|
|
} else {
|
|
send_reply("403", "Forbidden");
|
|
}
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title><acronym>MI</acronym> Commands</title>
|
|
|
|
<section id="utils.m.forward_list">
|
|
<title><function moreinfo="none">forward_list</function></title>
|
|
<para>
|
|
List active forward rules.
|
|
</para>
|
|
<para>
|
|
No parameters.
|
|
</para>
|
|
<example>
|
|
<title><function>forward_list</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
&ctltool; fifo forward_list
|
|
id switch filter proxy
|
|
0 off REGISTER:INVITE:SUBSCRIBE host-a.domain-a:5060
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="utils.m.forward_switch">
|
|
<title><function moreinfo="none">forward_switch</function></title>
|
|
<para>
|
|
This command can be used to activate or deactivate forwarding rules.
|
|
The syntax of this configuration string is described in 1.6. (switch_setting_list).
|
|
</para>
|
|
<example>
|
|
<title><function>forward_switch</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
&ctltool; fifo forward_switch 0=on
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="utils.m.forward_filter">
|
|
<title><function moreinfo="none">forward_filter</function></title>
|
|
<para>
|
|
Can be used to specify the filter for a certain id. Messages will only be
|
|
forwarded if one of the filters matches the message.
|
|
</para>
|
|
<para>
|
|
There are special filters and regular filters.
|
|
Special filters are:
|
|
<itemizedlist>
|
|
<listitem>REQUEST (matches on every request)</listitem>
|
|
<listitem>REPLY (matches on every reply)</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Regular filters are arbitrary strings not containing the
|
|
delimiter ':'. They are matched against the request method
|
|
names of the sip messages. The syntax of this configuration
|
|
string is described in 1.6. (filter_setting_list).
|
|
</para>
|
|
<example>
|
|
<title><function>forward_filter</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
&ctltool; fifo forward_filter 0=REGISTER:INVITE
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section id="utils.m.forward_proxy">
|
|
<title><function moreinfo="none">forward_proxy</function></title>
|
|
<para>
|
|
This command can be used to configure forwarding rules. Specifies
|
|
the destination for a certain id. Messages will be forwarded to
|
|
this destination if the preconditions hold (matching id, filter, and
|
|
switch). The syntax of this configuration string is described in 1.6.
|
|
(proxy_setting_list).
|
|
</para>
|
|
<example>
|
|
<title><function>forward_proxy</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
&ctltool; fifo forward_proxy 0=host-c.domain-c:5060
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Configuration syntax</title>
|
|
<para>This grammar specify the usable configuration syntax</para>
|
|
<itemizedlist>
|
|
<listitem>switch_setting_list ::= switch_setting { "," switch_setting }</listitem>
|
|
<listitem>filter_setting_list ::= switch_setting { "," switch_setting }</listitem>
|
|
<listitem>proxy_setting_list ::= proxy_setting { "," proxy_setting }</listitem>
|
|
<listitem>switch_setting ::= id "=" switch</listitem>
|
|
<listitem>filter_setting ::= id "=" filter_list</listitem>
|
|
<listitem>proxy_setting ::= id "=" proxy</listitem>
|
|
<listitem>switch ::= ( "off" | "on" )</listitem>
|
|
<listitem>filter_list ::= filter { ":" filter }</listitem>
|
|
<listitem>proxy ::= host ":" port</listitem>
|
|
<listitem>filter ::= ( special_filter | regular_filter )</listitem>
|
|
<listitem>special_filter ::= ( "REQUEST" | "REPLY" )</listitem>
|
|
<listitem>regular_filter ::= ? [^:]* ?</listitem>
|
|
<listitem>host ::= char { char }</listitem>
|
|
<listitem>char ::= ? A-Za-z0-9.-_ ?</listitem>
|
|
<listitem>id ::= number</listitem>
|
|
<listitem>port ::= number</listitem>
|
|
<listitem>number ::= digit {digit}</listitem>
|
|
<listitem>digit ::= ? 0-9 ?</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</chapter>
|