The XMLRPC Module

This module implements the XML-RPC transport and encoding interface for Kamailio RPCs.

The XML-RPC protocol encodes the name of the method to be called along with its parameter in an XML document which is then conveyed using HTTP (Hyper Text Transfer Protocol) to the server. The server will extract the name of the function to be called along with its parameters from the XML document, execute the function, and encode any data returned by the function into another XML document which is then returned to the client in the body of a 200 OK reply to the HTTP request.

XML-RPC is similar to more popular SOAP (Simple Object Access Protocol), which is an XML-based messaging framework used in Web Services developed within the World Wide Web Consortium. Both protocols are using HTTP as the transport protocol for XML documents, but XML-RPC is much simpler and easier to implement than SOAP.

Here is an example of single XML-RPC function call to determine current time:

POST /RPC2 HTTP/1.0
User-Agent: Radio UserLand/7.1b7 (WinNT)
Host: time.xmlrpc.com
Content-Type: text/xml
Content-length: 131

<?xml version="1.0"?>
<methodCall>
<methodName>currentTime.getCurrentTime</methodName>
<params>
</params>
</methodCall>

And the response returned by the server:

HTTP/1.1 200 OK
Connection: close
Content-Length: 183
Content-Type: text/xml
Date: Wed, 03 Oct 2001 15:53:38 GMT
Server: UserLand Frontier/7.0.1-WinNT

<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value><dateTime.iso8601>20011003T08:53:38</dateTime.iso8601>
</value>
</param>
</params>
</methodResponse>

XML-RPC specification spells HTTP as the official transport protocol for XML-RPC documents. Kamailio does not directly support HTTP, it is a SIP server so SIP is the only protocol supported by Kamailio. Because we would like to reuse all transport protocols available in Kamailio, such as TCP and TLS, it would be natural to use modified version of XML-RPC which would run on top of SIP instead of HTTP. XML-RPC documents would be then encoded in the bodies of SIP requests and replies would be sent by the server in the bodies of SIP replies. This way we could reuse all transport protocols (including UDP) and message parsers available in Kamailio.

Although this approach seems to be the logical choice, there is one big drawback. No existing XML-RPC implementations support SIP as the transport protocol, and there are many existing implementations available for vast majority of existing languages. See the XML-RPC implementation page for more details. Extending existing implementations with SIP support would not be easy.

Because extending available XML-RPC implementation would be too expensive, we could also do it the other way around, keep existing XML-RPC implementations and extend Kamailio to support HTTP. Extending Kamailio with HTTP support is easier than it might seem at a first glance, due to the similarity between SIP requests and HTTP requests.

Kamailio already supports TCP, so existing HTTP implementations can send HTTP requests to it. HTTP requests are missing certain mandatory SIP header fields, such as Via, From, and CSeq. The contents of the header fields is mainly used for transaction matching. A SIP server could perform two basic operations when processing an HTTP request:

Nothing special is needed on the SIP server terminating the request, except that it has to know where it should send the reply. Parsing of HTTP header field bodies would fail because we do not have parsers for them in Kamailio, but that does not matter anyway because all the information is encoded in the body of the request. HTTP requests contain no Via header fields. Via header fields are used by SIP implementations to determine the destination (IP, transport protocol, and port number) for replies. When processing HTTP requests the SIP server needs to create a fake Via header field based on the source IP address and port number of the TCP connection. The SIP server will use this information when sending a reply back.

Forwarding of HTTP requests by SIP proxies is a little bit more complicated and there are several limitations. First of all, we can only use stateless forwarding, no transactional forwarding, because HTTP requests do not contain all the header fields needed for transaction matching. Any attempt to call t_relay on an HTTP requests would fail. HTTP requests always use TCP and thus we could use stateless forwarding on the SIP server, provided that the request will be also forwarded over TCP. Stateless forwarding does not require the mandatory header fields (which are missing here) and it would work. In addition to that, the SIP server would also append fake Via header field to the request and change the contents of the Request-URI. The Request-URI of HTTP requests sent by XML-RPC implementations typically contain something like "/RPC2" and the first SIP server processing the request should rewrite the value with a valid SIP URI.

Figure RPC Example shows a scenario which involves two SIP servers, one performs HTTP request "normalization" and forwarding, and the other terminates the request, executes corresponding function, and generates a reply.

Example RPC Scenario

Step 1. An HTTP user agent sends an ordinary HTTP request to a SIP server. The user agent can either establish a connection directly to port 5060 or the SIP server can be configured to listen on port 80. The request contains standard HTTP headers and an XML-RPC document in the body:

POST / HTTP/1.0.
Host: localhost:5060
User-Agent: xmlrpclib.py/1.0.1 (by www.pythonware.com)
Content-Type: text/xml
Content-Length: 111

<?xml version='1.0'?>
<methodCall>
<methodName>usrloc.statistics</methodName>
<params>
</params>
</methodCall>

This particular request calls method "statistics" from from usrloc module of Kamailio. The method has no parameters.

The outbound SIP server receives the HTTP request and performs a set of actions called "SIP-normalization". This includes creation of fake Via header field based on the source IP and port of the TCP connection, looking up of the target SIP server that should terminate and process the request, and rewriting of the Request-URI with the SIP URI of the target SIP server. Modified HTTP request will be then forwarded statelessly to the target SIP server.

POST sip:proxy01.sip-server.net HTTP/1.0
Via: SIP/2.0/TCP 127.0.0.1:3571
Host: localhost:5060
User-Agent: xmlrpclib.py/1.0.1 (by www.pythonware.com)
Content-Type: text/xml
Content-Length: 111

<?xml version='1.0'?>
<methodCall>
<methodName>usrloc.statistics</methodName>
<params>
</params>
</methodCall>

Step 2. "normalized" HTTP request is statelessly forwarded to the target SIP server over TCP.

Step 3. The target SIP server receives the HTTP request and executes function called dispatch_rpc from xmlrpc Kamailio module. This function will parse the XML-RPC document in the body of the request and lookup the function to be called among all RPC functions exported by the Kamailio core and modules. Function dispatch_rpc will be called from the configuration file just like any other function:

if (method == "POST" || method == "GET") {
    dispatch_rpc();
    break;
};

This particular configuration snippet executes the function whenever Kamailio receives GET or POST requests. These two method names indicate HTTP.

Step 4. The function dispatch_rpc scans through the list of all exported RPC functions searching for the statistics function of the usrloc module. The Kamailio RPC Module API describes in detail how modules export RPC functions.

Step 5. As the RPC function from usrloc module is running and gathering statistics, it calls functions of RPC interface to prepare the result for the caller.

Step 6. Once the RPC function finishes, xmlrpc module will build the XML-RPC document from the data received from usrloc module and generate a reply which will be sent to the caller.

Steps 7. and 8. HTTP reply is sent back to the caller and the remote procedure call finishes.

HTTP/1.0 200 OK
Via: SIP/2.0/TCP 127.0.0.1:3571
Server: Sip EXpress router (0.10.99-janakj_experimental (i386/linux))
Content-Length: 651
Warning: 392 127.0.0.1:5060 "Noisy feedback tells:  pid=9975 req_src_ip=127.0.0
1 req_src_port=3571 in_uri=/ out_uri=sip:proxy01.sip-server.net via_cnt==1"

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
<params>
<param><value><array><data>
<value><struct>
<member><name>domain</name>
<value><string>aliases</string></value></member>
<member><name>users</name>
<value><i4>0</i4></value></member>
<member><name>expired</name>
<value><i4>0</i4></value></member>
</struct></value>
<value><struct>
<member><name>domain</name>
<value><string>location</string></value></member>
<member><name>users</name>
<value><i4>0</i4></value></member>
<member><name>expired</name>
<value><i4>0</i4></value></member>
</struct></value>
</data></array></value></param>
</params>
</methodResponse>

if (method == "POST" || method == "GET") {
    dispatch_rpc(); # Process the request
    break;
};

The purpose of the functions of this module is to convert XML-RPC document carried in the body of HTTP requests into data returned by the RPC interface and back. The module also contains functions necessary to "normalize" HTTP requests. The module uses xmlrpc-c library to perform XML-RPC related functions.

The module always returns 200 OK HTTP reply, it will never return any other HTTP reply. Failures are expressed in XML-RPC documents in the body of the reply. There is basic method introspection support in the module. Currently the module can list all functions exported by the server and for each function it can return the documentation string describing the function.

POST / HTTP/1.0
Host: localhost:5060
User-Agent: xmlrpclib.py/1.0.1 (by www.pythonware.com)
Content-Type: text/xml
Content-Length: 112

<?xml version='1.0'?>
<methodCall>
<methodName>system.listMethods</methodName>
<params>
</params>
</methodCall>

HTTP/1.0 200 OK
Via: SIP/2.0/TCP 127.0.0.1:2464
Server: Sip EXpress router (0.10.99-janakj_experimental (i386/linux))
Content-Length: 301

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>

<fault>
<value><struct>
<member><name>faultCode</name>
<value><i4>501</i4></value></member>
<member><name>faultString</name>
<value><string>Method Not Implemented</string></value></member>
</struct></value>
</fault>

</methodResponse>

HTTP/1.0 200 OK
Via: SIP/2.0/TCP 127.0.0.1:4626
Server: Sip EXpress router (0.10.99-janakj_experimental (i386/linux))
Content-Length: 150

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
<params>
<param><value><boolean>1</boolean></value></param>
</params>
</methodResponse>

HTTP/1.0 200 OK
Via: SIP/2.0/TCP 127.0.0.1:3793
Server: Sip EXpress router (0.10.99-janakj_experimental (i386/linux))
Content-Length: 216

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
<params>
<param><value><string>Server: Sip EXpress router (0.10.99-janakj_experimental (i386/linux))</string></value></param>
</params>
</methodResponse>

HTTP/1.0 200 OK
Via: SIP/2.0/TCP 127.0.0.1:2932
Server: Sip EXpress router (0.10.99-janakj_experimental (i386/linux))
Content-Length: 276

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
<params>
<param><value><array><data>
<value><string>./ser</string></value>
<value><string>-f</string></value>
<value><string>ser.cfg</string></value>
</data></array></value></param>
</params>
</methodResponse>

<struct>
  <member>
    <name>param1</name>
    <value>
      <i4>42</i4>
    </value>
  </member>
  <member>
    <name>param2</name>
    <value>
      <double>-12.214</i4>
    </value>
  </member>
</struct>

route[XMLRPC]{
	# close connection only for xmlrpclib user agents
	if search("^User-Agent:.*xmlrpclib"))
		set_reply_close();
	set_reply_no_connect(); # optional
	dispatch_rpc();
}