New Management Interface: RPC, XML-RPC

SERi's management interface has been rewritten. Former SER releases had a managment interface hardcoded in the core with support for FIFO and UDP. The new release introduces a management RPC (Remote Procedure Call) API provided by the SER core, but where independent transport protocol implementations are found in a module (i.e. how you call the management functions, ex. XMLRPC).

Both the core and all modules may register own management functions that will automatically be accessible via the RPC interface.

The preferred RPC protocol is XML-RPC, which packages the name of the function to be called along with its call parameter in an XML document.  This document is then transported to the SER RPC server using HTTP (Hyper Text Transfer Protocol). 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. This document is then returned to the caller in the body of a 200 OK reply to the HTTP request. There are many XML-RPC libraries available, so it is quite easy to create your own client that can control various things in SER.

The XML-RPC specification mandates HTTP as the official transport protocol for XML-RPC documents. SER does not directly support HTTP, it is a SIP server, so SIP is the only protocol supported by SER. Because we would like to reuse all transport protocols available in SER, such as TCP and TLS, it is natural to use modified version of XML-RPC which would run on top of SIP instead of HTTP. XML-RPC documents are 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 reuse all transport protocols (including UDP) and message parsers available in SER. Practically, this means that a client can send an XML-RPC request to the SER XML-RPC server in (standard) HTTP or using (non-standard) SIP over UDP,TCP, or TLS and the same logic will process the request.

If you want to know more in detail how this is accomplished, read on. If not, skip to the script example below.

 SER 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 CSeqi. The contents of the header fields is mainly used for transactioni matching. A SIP server could perform two basic operations when processing an HTTP request:

• Terminate the request, execute the function and send a reply back.
• Forward the request to another SIP server.

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 SER, 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.

Following simple script snippet is responsible for RPC processing:

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

You may want to use one main XML-RPC server and then forward HTTP requests to other SER servers.  This is a little bit more complicated and there are several limitations. First of all, we can only use statelessi 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 will 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-URIii. 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.

The procedures may be easily called using the seri_xxx tools. ser_ctl is the successor of the well known serctli.

Example:

 ser_ctl list_methods  ser_ctl stat  ser_rpc core.uptime