sipwise
/
kamailio
mirror of https://github.com/sipwise/kamailio.git
1
0
Fork 0
Code Issues Releases Wiki Activity
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.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '91189aba9e'
${ noResults }
kamailio/modules_k/xcap_server/doc/xcap_server_admin.xml

453 lines
11 KiB
Raw Blame History

<?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 provides an XCAP server functionaly inside Kamailio
and SER SIP servers.
</para>
<para>
Benefits brought by this integrated XCAP server:
<itemizedlist>
<listitem>
<para>
reuse of SIP router transport layer - XCAP documents can be sent
via SIP (UDP, TCP, TLS and SCTP) and via HTTP (TCP or TLS (HTTPS)).
For HTTP/S, you neet to load XHTTP module to handle HTTP/S
requests.
</para>
</listitem>
<listitem>
<para>
the Presence server has access imediatelly to the latest version
of XCAP documents. No more need to trigger refresh of XCAP
documents via MI command
</para>
</listitem>
<listitem>
<para>
can be used stand-alone, with a different Presence server. It is not
specific for Kamailio or SER. Documents can be fetched via GET
</para>
</listitem>
<listitem>
<para>
no exotic dependencies, it is written in C. It depends on
libxml2, sl module and a database module (required to store the
xcap documents).
</para>
</listitem>
<listitem>
<para>
you can do digest authentication using database, radius, ldap, etc.
Can reuse authorization mechanisms provided by SIP server.
</para>
</listitem>
<listitem>
<para>
flexibility - the XCAP server is controlled from config file of
SIP server, therefore you can blend the XCAP logic with features
provided by core or other modules.
</para>
</listitem>
</itemizedlist>
</para>
<para>
Important: be sure you have global parameter: 'tcp_accept_no_cl=yes'.
</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>sl</emphasis> - stateless reply module
</para>
</listitem>
<listitem>
<para>
<emphasis>db</emphasis> - a database engine module
</para>
</listitem>
<listitem>
<para>
<emphasis>xhttp</emphasis> - embedded HTTP server
if you want to get XCAP documents via HTTP.
</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>libxml2</emphasis> - libxml2 library for runtime and
libxml2-dev for compilation.
</para>
</listitem>
</itemizedlist>
</para>
</section>
</section>
<section>
<title>Parameters</title>
<section>
<title><varname>db_url</varname> (string)</title>
<para>
Database &url;.
</para>
<para>
<emphasis>
Default value is
<quote>mysql://openser:openserrw@localhost/openser</quote>.
</emphasis>
</para>
<example>
<title>Set the <quote>db_url</quote> parameter</title>
<programlisting format="linespecific">
...
modparam("xcap_server", "db_url", "mysql://user:passwd@host.com/dbname")
...
</programlisting>
</example>
</section>
<section>
<title><varname>xcap_table</varname> (string)</title>
<para>
The name of table where to store the xcap documents.
</para>
<para>
<emphasis>
Default value is <quote>xcap</quote>.
</emphasis>
</para>
<example>
<title>Set the <quote>xcap_table</quote> parameter</title>
<programlisting format="linespecific">
...
modparam("xcap_server", "xcap_table", "xcapdocs")
...
</programlisting>
</example>
</section>
<section>
<title><varname>xcap_root</varname> (str)</title>
<para>
XCAP root URL.
</para>
<para>
<emphasis>
Default value is '/xcap-root/'.
</emphasis>
</para>
<example>
<title>Set <varname>url_match</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("xcap_server", "xcap_root", "/xcap-root/")
...
</programlisting>
</example>
</section>
<section>
<title><varname>buf_size</varname> (int)</title>
<para>
Size of local buffer for handling XCAP documents.
</para>
<para>
<emphasis>
Default value is <quote>1024</quote>.
</emphasis>
</para>
<example>
<title>Set the <quote>buf_size</quote> parameter</title>
<programlisting format="linespecific">
...
modparam("xcap_server", "buf_size", 2048)
...
</programlisting>
</example>
</section>
<section>
<title><varname>xml_ns</varname> (str)</title>
<para>
Register extra XML namespaces to be used with XPath. You
can set the parameter many times to add more namespaces. The
format is 'prefix=href'.
</para>
<para>
<emphasis>
Default value is 'null'.
</emphasis>
</para>
<example>
<title>Set <varname>url_match</varname> parameter</title>
<programlisting format="linespecific">
...
modparam("xcap_server", "xml_ns",
"rl=urn:ietf:params:xml:ns:resource-lists")
modparam("xcap_server", "xml_ns",
"my=urn:my:prefix")
...
</programlisting>
</example>
</section>
</section>
<section>
<title>Functions</title>
<section>
<title>
<function moreinfo="none">xcaps_put(uri, path, doc)</function>
</title>
<para>
Handle XCAP PUT command.
</para>
<example>
<title><function>xcaps_put</function> usage</title>
<programlisting format="linespecific">
...
event_route[xhttp:request] {
if($hu=~"^/xcap-root/")
{
# xcap ops
switch($rm) {
case "PUT":
xcaps_put("sip:101@$Ri", "$hu", "$rb");
exit;
break;
}
}
}
...
</programlisting>
</example>
</section>
<section>
<title>
<function moreinfo="none">xcaps_get(uri, path)</function>
</title>
<para>
Handle XCAP GET command.
</para>
<example>
<title><function>xcaps_get</function> usage</title>
<programlisting format="linespecific">
...
event_route[xhttp:request] {
if($hu=~"^/xcap-root/")
{
# xcap ops
switch($rm) {
case "GETT":
xcaps_get("sip:101@$Ri", "$hu");
exit;
break;
}
}
}
...
</programlisting>
</example>
</section>
<section>
<title>
<function moreinfo="none">xcaps_del(uri, path)</function>
</title>
<para>
Handle XCAP DELETE command.
</para>
<example>
<title><function>xcaps_del</function> usage</title>
<programlisting format="linespecific">
...
event_route[xhttp:request] {
if($hu=~"^/xcap-root/")
{
# xcap ops
switch($rm) {
case "DELETE":
xcaps_del("sip:101@$Ri", "$hu");
exit;
break;
}
}
}
...
</programlisting>
</example>
</section>
</section>
<section>
<title>Exported pseudo-variables</title>
<itemizedlist>
<listitem><para>
<emphasis>$xcapuri(name=>key)</emphasis> - name can be any
to idenitfy the XCAP uri; key can be: data, uri, root, auid,
type, tree, xuid, file, node, target, domain, uri_adoc.
</para></listitem>
</itemizedlist>
<para>
Exported pseudo-variables are documented at &kamwikilink;.
</para>
<example>
<title>$xcapuri(...) PV</title>
<programlisting format="linespecific">
...
$xcapuri(u=>data) = $hu;
xdbg("SCRIPT: xcap service $xcapuri(u=>auid) for $xcapuri(u=>xuid)\n");
...
</programlisting>
</example>
</section>
<section>
<title>Simple XCAP Server Config</title>
<example>
<title>sample xcap server</title>
<programlisting format="linespecific">
...
tcp_accept_no_cl=yes
...
loadmodule "xhttp.so"
loadmodule "xcap_server.so"
...
# ----- xcap_server params -----
modparam("xcap_server", "db_url",
"mysql://openser:openserrw@localhost/openser")
...
event_route[xhttp:request] {
if (!www_authorize("xcap", "subscriber"))
{
www_challenge("xcap", "0");
exit;
}
if($hu=~"^/xcap-root/")
{
set_reply_close();
set_reply_no_connect();
# xcap ops - break down http uri to get xcap user id
$xcapuri(u=>data) = $hu;
if($xcapuri(u=>xuid)=~"^sip:.+@.+")
$var(uri) = $xcapuri(u=>xuid);
else
$var(uri) = "sip:"+ $xcapuri(u=>xuid) + "@" + $Ri;
# handle XCAP capability request
if($rm=="GET" &amp;&amp; $xcapuri(u=>auid)=="xcap-caps")
{
$var(xbody) =
"&lt;?xml version='1.0' encoding='UTF-8'?&gt;
&lt;xcap-caps xmlns='urn:ietf:params:xml:ns:xcap-caps'&gt;
&lt;auids&gt;
&lt;auid&gt;rls-services&lt;/auid&gt;
&lt;auid&gt;pidf-manipulation&lt;/auid&gt;
&lt;auid&gt;xcap-caps&lt;/auid&gt;
&lt;auid&gt;resource-lists&lt;/auid&gt;
&lt;auid&gt;pres-rules&lt;/auid&gt;
&lt;auid&gt;org.openmobilealliance.pres-rules&lt;/auid&gt;
&lt;/auids&gt;
&lt;extensions&gt;
&lt;/extensions&gt;
&lt;namespaces&gt;
&lt;namespace>urn:ietf:params:xml:ns:rls-services&lt;/namespace&gt;
&lt;namespace>urn:ietf:params:xml:ns:pidf&lt;/namespace&gt;
&lt;namespace>urn:ietf:params:xml:ns:xcap-caps&lt;/namespace&gt;
&lt;namespace>urn:ietf:params:xml:ns:resource-lists&lt;/namespace&gt;
&lt;namespace>urn:ietf:params:xml:ns:pres-rules&lt;/namespace&gt;
&lt;/namespaces&gt;
&lt;/xcap-caps&gt;";
xhttp_reply("200", "ok", "application/xcap-caps+xml",
"$var(xbody)");
exit;
}
# be sure auth user access only its documents
if ($au!=$(var(uri){uri.user})) {
xhttp_reply("403", "Forbidden", "text/html",
"operation not allowed");
exit;
}
xdbg("SCRIPT: xcap service $xcapuri(u=>auid) for $xcapuri(u=>xuid)\n");
switch($rm) {
case "PUT":
xcaps_put("$var(uri)", "$hu", "$rb");
if($xcapuri(u=>auid)=~"pres-rules")
{
pres_update_watchers("$var(uri)", "presence");
pres_refresh_watchers("$var(uri)", "presence", 1);
}
exit;
break;
case "GET":
xcaps_get("$var(uri)", "$hu");
exit;
break;
case "DELETE":
xcaps_del("$var(uri)", "$hu");
if($xcapuri(u=>auid)=~"pres-rules")
{
pres_update_watchers("$var(uri)", "presence");
pres_refresh_watchers("$var(uri)", "presence", 1);
}
exit;
break;
}
}
# other http requests
xhttp_reply("200", "OK", "text/html",
"&lt;html&gt;&lt;body>OK: $si:$sp&lt;/body&gt;&lt;/html&gt;");
exit;
}
...
</programlisting>
</example>
<para>
The URL for XCAP has to be:
</para>
<para>
http://_your_sip_server_ip_:_your_sip_server_port_/xcap-root/...
</para>
<para>
For example, if your SIP server IP is 10.1.1.10 and it is listening
on TCP port 5060 and TLS port 5061, following XCAP URLs can be used:
</para>
<para>
http://10.1.1.10:5060/xcap-root/...
</para>
<para>
https://10.1.1.10:5061/xcap-root/...
</para>
</section>
</chapter>
Reference in new issue View Git Blame Copy Permalink