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.
396 lines
11 KiB
396 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 provides a web provisioning interface
|
|
for &kamailio;. It is using the &kamailio;'s internal
|
|
database API to provide a simple way of manipulating
|
|
records inside &kamailio;'s tables.
|
|
</para>
|
|
<para>
|
|
The module offers:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
ability to connect to multiple/different databases
|
|
through &kamailio;'s db API;
|
|
(all &kamailio;'s databases are supported);
|
|
</para></listitem>
|
|
<listitem><para>
|
|
ability to perform data input validation through &kamailio; API;
|
|
</para></listitem>
|
|
<listitem><para>
|
|
ability to reconfigure the interface layout on the fly by
|
|
reloading the config from the xml framework via the rpc
|
|
command interface.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Note: when provisioning tables using <emphasis>db_text</emphasis>,
|
|
any change made to a <emphasis>db_text</emphasis> table will not
|
|
be reflected on the actual text file. In order to force a write
|
|
out to the disk of the cached tables, the db_text rpc command
|
|
<emphasis>db_text.dump</emphasis> must be used.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Usage</title>
|
|
<para>
|
|
The layout of the provisionning interface is controlled via an external
|
|
xml file (see the framework parameter).
|
|
An example of a framework xml file is provided inside the &kamailio;'s
|
|
examples directory.
|
|
A simple framework file can be generated by the kamdbctl command:
|
|
<programlisting format="linespecific">
|
|
kamdbctl pframework create
|
|
</programlisting>
|
|
The generated framework will be saved inside &kamailio;'s
|
|
config directory as <emphasis>pi_framework_sample</emphasis>.
|
|
The list of configurable tables will be based on the
|
|
<emphasis>STANDARD_MODULES</emphasis> and
|
|
<emphasis>EXTRA_MODULES</emphasis> vars from
|
|
<emphasis>kamctlrc</emphasis> file.
|
|
The sample framework file will provide the ability to inspect tables.
|
|
In order to add/modify/remove records to/from tables,
|
|
new commands must be added by the admin.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Framework </title>
|
|
<para>
|
|
The xml framework file is organized in three distinctive blocks:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
database connection definition block
|
|
</para></listitem>
|
|
<listitem><para>
|
|
table definition block
|
|
</para></listitem>
|
|
<listitem><para>
|
|
command definition block
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<section>
|
|
<title>Database connection definition block</title>
|
|
<para>
|
|
Each connection to a particular database must be defined here
|
|
with a unique database connection id.
|
|
The connection parameters are defined following the db_url param pattern
|
|
for all &kamailio; modules that are using a database.
|
|
</para>
|
|
<para>
|
|
Supported databases:
|
|
<itemizedlist>
|
|
<listitem><para>berkeley</para></listitem>
|
|
<listitem><para>cassandra</para></listitem>
|
|
<listitem><para>cluster</para></listitem>
|
|
<listitem><para>flatstore</para></listitem>
|
|
<listitem><para>mysql</para></listitem>
|
|
<listitem><para>oracle</para></listitem>
|
|
<listitem><para>postgres</para></listitem>
|
|
<listitem><para>sqlite</para></listitem>
|
|
<listitem><para>text</para></listitem>
|
|
<listitem><para>unixodbc</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Table definition block</title>
|
|
<para>
|
|
Each table managed through the &kamailio; provisioning interface
|
|
must be defined here with a unique table id.
|
|
For each table, the database connection id must be specified.
|
|
Each table must list all columns that will be managed by the
|
|
&kamailio; provisioning interface.
|
|
Each column must have a unique field name and a type.
|
|
Each column may have a validation tag for validating input data.
|
|
</para>
|
|
<para>
|
|
Supported column types:
|
|
<itemizedlist>
|
|
<listitem><para>DB1_INT</para></listitem>
|
|
<listitem><para>DB1_BIGINT</para></listitem>
|
|
<listitem><para>DB1_DOUBLE</para></listitem>
|
|
<listitem><para>DB1_STRING</para></listitem>
|
|
<listitem><para>DB1_STR</para></listitem>
|
|
<listitem><para>DB1_DATETIME</para>
|
|
<itemizedlist>
|
|
<listitem><para>Note: input field must be provided in
|
|
'YEAR-MM-DD HH:MM:SS' format.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem><para>DB1_BLOB</para></listitem>
|
|
<listitem><para>DB1_BITMAP</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Supported validation methods:
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
IPV4 - represents an IPv4 address
|
|
</para></listitem>
|
|
<listitem><para>
|
|
URI - represents a SIP URI
|
|
</para></listitem>
|
|
<listitem><para>
|
|
URI_IPV4HOST - represents a SIP URI with an IPV4 as a host
|
|
</para></listitem>
|
|
<listitem><para>
|
|
P_HOST_PORT - represents [proto:]host[:port]
|
|
</para></listitem>
|
|
<listitem><para>
|
|
P_IPV4_PORT - represents [proto:]IPv4[:port]
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Command definition block</title>
|
|
<para>
|
|
Multiple provisioning commands can be grouped together.
|
|
Each group can have multiple commands.
|
|
Each command definition in a group must have the table id
|
|
of the table that is operating on along with the command
|
|
type to be performed.
|
|
</para>
|
|
<para>
|
|
The command type can have up to three type of column parameters:
|
|
<itemizedlist>
|
|
<listitem><para>clause columns</para></listitem>
|
|
<listitem><para>query columns</para></listitem>
|
|
<listitem><para>order by columns</para></listitem>
|
|
</itemizedlist>
|
|
Each column parameter must define the name(s) of the column(s)
|
|
(must match a field name in the description table identified
|
|
by the table id).
|
|
A column can accept a list of imposed values.
|
|
Each imposed value will have an id that will be displayed
|
|
on the web interface and the actual value that will be
|
|
used for db operations.
|
|
Clause columns must define operators.
|
|
Here's the list of supported operators:
|
|
'<', '>', '=', '<=', '>=', '!='.
|
|
</para>
|
|
<para>
|
|
Supported database command types:
|
|
<itemizedlist>
|
|
<listitem><para>DB1_QUERY - performs an SQL query
|
|
and supports three type of columns:</para>
|
|
<itemizedlist>
|
|
<listitem><para>clause: 0 or more columns</para></listitem>
|
|
<listitem><para>query: 1 column</para></listitem>
|
|
<listitem><para>order: 0 or 1 column</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem><para>DB1_INSERT - performs an SQL insert
|
|
and supports one type of column:</para>
|
|
<itemizedlist>
|
|
<listitem><para>query: 1 or more columns</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem><para>DB1_DELETE - performs an SQL delete
|
|
and supports one type of column:</para>
|
|
<itemizedlist>
|
|
<listitem><para>clause: 1 or more columns</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem><para>DB1_UPDATE - performs an SQL update
|
|
and supports two type of columns:</para>
|
|
<itemizedlist>
|
|
<listitem><para>clause: 0 or more columns</para></listitem>
|
|
<listitem><para>query: 1 or more columns</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem><para>DB1_REPLACE - performs an SQL replace
|
|
and supports one type of column:</para>
|
|
<itemizedlist>
|
|
<listitem><para>query: 1 or more columns</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
Please note that some databases have a restricted
|
|
set of database command types.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>To-do</title>
|
|
<para>
|
|
Features to be added in the future:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>
|
|
full subscriber provisionning with automatic ha1/ha1b fields.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Dependencies</title>
|
|
<section>
|
|
<title>&kamailio; Modules</title>
|
|
<para>
|
|
The following modules must be loaded before this module:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>xhttp</emphasis> - xHTTP.
|
|
</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>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<section>
|
|
<title>Parameters</title>
|
|
<section>
|
|
<title><varname>xhttp_pi_root</varname> (str)</title>
|
|
<para>
|
|
It specifies the root path for provisionning http requests.
|
|
The link to the provisioning web interface must be constructed
|
|
using the following patern:
|
|
http://[server_IP]:[tcp_port]/[xhttp_pi_root]
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is "pi".
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>xhttp_pi_root</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("xhttp_pi", "xhttp_pi_root", "pi")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>xhttp_pi_buf_size</varname> (int)</title>
|
|
<para>
|
|
It specifies the maximum length of the buffer (in bytes) used
|
|
to write in the HTML reply information in order to
|
|
build the HTML response.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is 0 (auto set to 1/3 of the size of the configured pkg mem).
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>xhttp_pi_buf_size</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("xhttp", "xhttp_pi_buf_size", 1024)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>framework</varname> (string)</title>
|
|
<para>
|
|
It specifies the full path for xml framework descriptor.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
There's no default value. This parameter is mandatory.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>framework</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("xhttp", "framework", "/usr/local/etc/kamailio/pi_framework.xml")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Functions</title>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">dispatch_xhttp_pi()</function>
|
|
</title>
|
|
<para>
|
|
Handle the HTTP request and generate a response.
|
|
</para>
|
|
<example>
|
|
<title><function>dispatch_xhttp_pi</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
tcp_accept_no_cl=yes
|
|
...
|
|
loadmodule "sl.so"
|
|
loadmodule "xhttp.so"
|
|
loadmodule "xhttp_pi.so"
|
|
...
|
|
modparam("xhttp", "framework", "/usr/local/etc/kamailio/pi_framework.xml")
|
|
...
|
|
event_route[xhttp:request] {
|
|
$var(xhttp_root) = $(hu{s.substr,0,3});
|
|
if ($var(xhttp_root) == "/pi")
|
|
dispatch_xhttp_pi();
|
|
else
|
|
xhttp_reply("200", "OK", "text/html",
|
|
"<html><body>Wrong URL $hu</body></html>");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Exported RPC Functions</title>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">xhttp_pi.reload</function>
|
|
</title>
|
|
<para>Reloads the xml framework.</para>
|
|
<para>Name: <emphasis>xhttp_pi.reload</emphasis></para>
|
|
<para>Parameters: <emphasis>none</emphasis></para>
|
|
<para>RPC Command Format:</para>
|
|
<programlisting format="linespecific">
|
|
kamctl xhttp_pi.reload
|
|
</programlisting>
|
|
</section>
|
|
</section>
|
|
|
|
</chapter>
|
|
|