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.
327 lines
8.8 KiB
327 lines
8.8 KiB
xHTTP_PI Module
|
|
|
|
Ovidiu Sas
|
|
|
|
<osas@voipembedded.com>
|
|
|
|
Edited by
|
|
|
|
Ovidiu Sas
|
|
|
|
<osas@voipembedded.com>
|
|
|
|
Copyright © 2012-2013 VoIP Embedded Inc.
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
2. Usage
|
|
3. Framework
|
|
|
|
3.1. Database connection definition block
|
|
3.2. Table definition block
|
|
3.3. Command definition block
|
|
|
|
4. To-do
|
|
5. Dependencies
|
|
|
|
5.1. Kamailio Modules
|
|
5.2. External Libraries or Applications
|
|
|
|
6. Parameters
|
|
|
|
6.1. xhttp_pi_root (str)
|
|
6.2. xhttp_pi_buf_size (int)
|
|
6.3. framework (string)
|
|
|
|
7. Functions
|
|
|
|
7.1. dispatch_xhttp_pi()
|
|
|
|
8. Exported RPC Functions
|
|
|
|
8.1. xhttp_pi.reload
|
|
|
|
List of Examples
|
|
|
|
1.1. Set xhttp_pi_root parameter
|
|
1.2. Set xhttp_pi_buf_size parameter
|
|
1.3. Set framework parameter
|
|
1.4. dispatch_xhttp_pi usage
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. Usage
|
|
3. Framework
|
|
|
|
3.1. Database connection definition block
|
|
3.2. Table definition block
|
|
3.3. Command definition block
|
|
|
|
4. To-do
|
|
5. Dependencies
|
|
|
|
5.1. Kamailio Modules
|
|
5.2. External Libraries or Applications
|
|
|
|
6. Parameters
|
|
|
|
6.1. xhttp_pi_root (str)
|
|
6.2. xhttp_pi_buf_size (int)
|
|
6.3. framework (string)
|
|
|
|
7. Functions
|
|
|
|
7.1. dispatch_xhttp_pi()
|
|
|
|
8. Exported RPC Functions
|
|
|
|
8.1. xhttp_pi.reload
|
|
|
|
1. Overview
|
|
|
|
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.
|
|
|
|
The module offers:
|
|
* ability to connect to multiple/different databases through
|
|
Kamailio's db API; (all Kamailio's databases are supported);
|
|
* ability to perform data input validation through Kamailio API;
|
|
* ability to reconfigure the interface layout on the fly by reloading
|
|
the config from the xml framework via the rpc command interface.
|
|
|
|
Note: when provisioning tables using db_text, any change made to a
|
|
db_text 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 db_text.dump must be used.
|
|
|
|
2. Usage
|
|
|
|
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:
|
|
kamdbctl pframework create
|
|
|
|
The generated framework will be saved inside Kamailio's config
|
|
directory as pi_framework_sample. The list of configurable tables will
|
|
be based on the STANDARD_MODULES and EXTRA_MODULES vars from kamctlrc
|
|
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.
|
|
|
|
3. Framework
|
|
|
|
3.1. Database connection definition block
|
|
3.2. Table definition block
|
|
3.3. Command definition block
|
|
|
|
The xml framework file is organized in three distinctive blocks:
|
|
* database connection definition block
|
|
* table definition block
|
|
* command definition block
|
|
|
|
3.1. Database connection definition block
|
|
|
|
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.
|
|
|
|
Supported databases:
|
|
* berkeley
|
|
* cassandra
|
|
* cluster
|
|
* flatstore
|
|
* mysql
|
|
* oracle
|
|
* postgres
|
|
* sqlite
|
|
* text
|
|
* unixodbc
|
|
|
|
3.2. Table definition block
|
|
|
|
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.
|
|
|
|
Supported column types:
|
|
* DB1_INT
|
|
* DB1_BIGINT
|
|
* DB1_DOUBLE
|
|
* DB1_STRING
|
|
* DB1_STR
|
|
* DB1_DATETIME
|
|
+ Note: input field must be provided in 'YEAR-MM-DD HH:MM:SS'
|
|
format.
|
|
* DB1_BLOB
|
|
* DB1_BITMAP
|
|
|
|
Supported validation methods:
|
|
* IPV4 - represents an IPv4 address
|
|
* URI - represents a SIP URI
|
|
* URI_IPV4HOST - represents a SIP URI with an IPV4 as a host
|
|
* P_HOST_PORT - represents [proto:]host[:port]
|
|
* P_IPV4_PORT - represents [proto:]IPv4[:port]
|
|
|
|
3.3. Command definition block
|
|
|
|
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.
|
|
|
|
The command type can have up to three type of column parameters:
|
|
* clause columns
|
|
* query columns
|
|
* order by columns
|
|
|
|
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: '<', '>',
|
|
'=', '<=', '>=', '!='.
|
|
|
|
Supported database command types:
|
|
* DB1_QUERY - performs an SQL query and supports three type of
|
|
columns:
|
|
+ clause: 0 or more columns
|
|
+ query: 1 column
|
|
+ order: 0 or 1 column
|
|
* DB1_INSERT - performs an SQL insert and supports one type of
|
|
column:
|
|
+ query: 1 or more columns
|
|
* DB1_DELETE - performs an SQL delete and supports one type of
|
|
column:
|
|
+ clause: 1 or more columns
|
|
* DB1_UPDATE - performs an SQL update and supports two type of
|
|
columns:
|
|
+ clause: 0 or more columns
|
|
+ query: 1 or more columns
|
|
* DB1_REPLACE - performs an SQL replace and supports one type of
|
|
column:
|
|
+ query: 1 or more columns
|
|
|
|
Please note that some databases have a restricted set of database
|
|
command types.
|
|
|
|
4. To-do
|
|
|
|
Features to be added in the future:
|
|
* full subscriber provisionning with automatic ha1/ha1b fields.
|
|
|
|
5. Dependencies
|
|
|
|
5.1. Kamailio Modules
|
|
5.2. External Libraries or Applications
|
|
|
|
5.1. Kamailio Modules
|
|
|
|
The following modules must be loaded before this module:
|
|
* xhttp - xHTTP.
|
|
|
|
5.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* libxml2
|
|
|
|
6. Parameters
|
|
|
|
6.1. xhttp_pi_root (str)
|
|
6.2. xhttp_pi_buf_size (int)
|
|
6.3. framework (string)
|
|
|
|
6.1. xhttp_pi_root (str)
|
|
|
|
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]
|
|
|
|
Default value is "pi".
|
|
|
|
Example 1.1. Set xhttp_pi_root parameter
|
|
...
|
|
modparam("xhttp_pi", "xhttp_pi_root", "pi")
|
|
...
|
|
|
|
6.2. xhttp_pi_buf_size (int)
|
|
|
|
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.
|
|
|
|
Default value is 0 (auto set to 1/3 of the size of the configured pkg
|
|
mem).
|
|
|
|
Example 1.2. Set xhttp_pi_buf_size parameter
|
|
...
|
|
modparam("xhttp", "xhttp_pi_buf_size", 1024)
|
|
...
|
|
|
|
6.3. framework (string)
|
|
|
|
It specifies the full path for xml framework descriptor.
|
|
|
|
There's no default value. This parameter is mandatory.
|
|
|
|
Example 1.3. Set framework parameter
|
|
...
|
|
modparam("xhttp", "framework", "/usr/local/etc/kamailio/pi_framework.xml")
|
|
...
|
|
|
|
7. Functions
|
|
|
|
7.1. dispatch_xhttp_pi()
|
|
|
|
7.1. dispatch_xhttp_pi()
|
|
|
|
Handle the HTTP request and generate a response.
|
|
|
|
Example 1.4. dispatch_xhttp_pi usage
|
|
...
|
|
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>");
|
|
}
|
|
...
|
|
|
|
8. Exported RPC Functions
|
|
|
|
8.1. xhttp_pi.reload
|
|
|
|
8.1. xhttp_pi.reload
|
|
|
|
Reloads the xml framework.
|
|
|
|
Name: xhttp_pi.reload
|
|
|
|
Parameters: none
|
|
|
|
RPC Command Format:
|
|
kamctl xhttp_pi.reload
|