kamailio/modules/xhttp_pi

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