xHTTP_RPC Module

Ovidiu Sas

   <osas@voipembedded.com>

Edited by

Ovidiu Sas

   <osas@voipembedded.com>

Alex Balashov

   <abalashov@evaristesys.com>

   Copyright © 2011 VoIPEmbedded Inc.
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Limitations
        3. Dependencies

              3.1. Kamailio Modules
              3.2. External Libraries or Applications

        4. Parameters

              4.1. xhttp_rpc_root (str)
              4.2. xhttp_rpc_buf_size (str)

        5. Functions

              5.1. dispatch_xhttp_rpc()

        6. Usage

   List of Examples

   1.1. Set xhttp_rpc_root parameter
   1.2. Set xhttp_rpc_buf_size parameter
   1.3. dispatch_xhttp_rpc usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Limitations
   3. Dependencies

        3.1. Kamailio Modules
        3.2. External Libraries or Applications

   4. Parameters

        4.1. xhttp_rpc_root (str)
        4.2. xhttp_rpc_buf_size (str)

   5. Functions

        5.1. dispatch_xhttp_rpc()

   6. Usage

1. Overview

   This module provides an HTTP transport layer implementation for the RPC
   management interface in a human-readable format.

   The xHTTP_RPC module uses the xHTTP module to handle HTTP requests.
   Read the documentation of the xHTTP module for more details.

2. Limitations

     * This module does not implement asynchronous RPC commands. It is
       unlikely that asynchronous RPC commands will be executed from an
       RPC web interface.
     * This module does not accept parameters embedded in a structure (see
       RPC documentation for more info about how parameters can be passed
       to RPC).
     * At startup, all RPC commands are sorted and grouped based on their
       format. The expected format is [group].[subcommand]. The initial
       xhttp_rpc webpage displays all the retrieved groups. All RPC
       commands are available as sub-menus of each [group]. If an RPC
       command is not in the expected format, it will be dropped from the
       initial xhttp_rpc home page menu.

3. Dependencies

   3.1. Kamailio Modules
   3.2. External Libraries or Applications

3.1. Kamailio Modules

   The following modules must be loaded before this module:
     * xhttp - xHTTP.

3.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * None

4. Parameters

   4.1. xhttp_rpc_root (str)
   4.2. xhttp_rpc_buf_size (str)

4.1. xhttp_rpc_root (str)

   Specifies the root path for RPC http requests. The link to the RPC web
   interface must be constructed using the following pattern:
   http://[server_IP]:[tcp_port]/[xhttp_rpc_root]

   Default value is "rpc".

   Example 1.1. Set xhttp_rpc_root parameter
...
modparam("xhttp_rpc", "xhttp_rpc_root", "http_rpc")
...

4.2. xhttp_rpc_buf_size (str)

   Specifies the maximum length of the buffer (in bytes) used to write the
   RPC 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_rpc_buf_size parameter
...
modparam("xhttp_rpc", "xhttp_rpc_buf_size", 1024)
...

5. Functions

   5.1. dispatch_xhttp_rpc()

5.1.  dispatch_xhttp_rpc()

   Handle the HTTP request and generate a response.

   Example 1.3. dispatch_xhttp_rpc usage
...
tcp_accept_no_cl=yes
...
loadmodule "sl.so"
loadmodule "xhttp.so"
loadmodule "xhttp_rpc.so"
...
modparam("xhttp_rpc", "xhttp_rpc_root", "http_rpc")
...
event_route[xhttp:request] {
        $var(xhttp_rpc_root) = $(hu{s.substr,0,9});
        if ($var(xhttp_rpc_root) == "/http_rpc")
                dispatch_xhttp_rpc();
        else
                xhttp_reply("200", "OK", "text/html",
                        "<html><body>Wrong URL $hu</body></html>");
}
...

6. Usage

   The module is not intended to be used in a "scripted" mode with command
   line tools. It only provides a simple web interface with all the
   available RPC commands. Point a web browser to
   http://serverip:port/http_rpc and browse through the available rpc
   commands.

   If you don't configure a dedicated port for HTTP, then you have to use
   same port as for SIP TCP. If you load and configure TLS module, then
   you can browse using HTTPS to the SIP TLS port.