# &adminguide;

## Dependencies

### &kamailio; modules

The following modules must be loaded before this module:

- SL - Stateless request handling

## Parameters

### `route` (string)

Name of the route called for XMLRPC messages.

This route will be called only for HTTP messages whose method is either GET or POST. The message visible inside the route will be a HTTP request converted to SIP (the uri will be fixed and a fake via will be added).

The route should perform additional security checks to ensure the client is authorized to execute management/RPC functions and then it should call the `dispatch_rpc()`.

Default: the main route is used.

#### Set `route` parameter

    modparam("xmlrpc", "route", "route_for_xmlrpcs")

### `autoconversion` (string)

Enable or disable automatic parameter type conversion globally, for all the methods parameters. If on, a type mismatch in a method parameter will not cause a fault if it is possible to automatically convert it to the type expected by the method.

Default: off.

It is recommended to leave this parameter to its default off value and fix instead the client application (which should use the proper types) or to modify the target rpc to accept any type (see the rpc scan '.' modifier).

#### Set the `autoconversion` parameter

    modparam("xmlrpc", "autoconversion", 1)

### `escape_cr` (integer)

Enable CR ('\r') escaping in replies. If enabled each '\r' in the xmlrpc reply will be replaced with "&#xD;", according to the xml spec.

It should be turned off only if you suspect interoperability problems with older clients.

Default: on.

#### Set the `escape_cr` parameter

    modparam("xmlrpc", "escape_cr", 1)

### `double_lf_to_crlf` (integer)

When enabled double LFs ('\n\n') in the input xmlrpc strings will be replaced with CR LF ('\r\n'). This makes LF LF behave like an escape character for CR LF and is needed for compatibility with &kamailio; tools and to work around buggy xmlrpc clients that don't escape the CR in CR LF ('\r' should be escaped to "&#xD;" otherwise according to the xml spec "\r\n" will be transformed to '\n'), but need to send CR LF in the strings (e.g. they use `tm.t_uac_wait`).

Note: when this option is turned on, there is no way to send a double LF ('\n\n'), it will always be transformed in CR LF ('\r\n').

Default: off.

#### Set the `double_lf_to_crlf` parameter

    modparam("xmlrpc", "double_lf_to_crlf", 1)

### `mode` (integer)

When set to 1, the xmlrpc module does not register to core the callback functions for non-SIP messages. Useful when another module registers a callback for HTTP request, letting the admin decide when to call the XMLRPC route (or functions).

Default: 0.

#### Set the `mode` parameter

    modparam("xmlrpc", "mode", 1)

### `url_skip` (str)

Regular expression to match the HTTP URL. If there is a match, then the xmlrpc route is not executed.

Default value is null (don't skip).

#### Set `url_skip` parameter

    ...
    modparam("xmlrpc", "url_skip", "^/sip")
    ...

### `url_match` (str)

Regular expression to match the HTTP URL. If there is no match, then xmlrpc route is not executed. This check is done after url_skip, so if both url_skip and url_match would match then the xmlrpc route is not executed (url_skip has higher priority).

Default value is null (match everything).

#### Set `url_match` parameter

    ...
    modparam("xmlrpc", "url_match", "^/RPC2")
    ...

### `event_callback` (string)

The name of the function in the kemi configuration file (embedded scripting language such as Lua, Python, ...) to be executed instead of route blocks defined by route parameter for xmlrpc request.

This route will be called only for HTTP messages whose method is either GET or POST. The message visible inside the route will be a HTTP request converted to SIP (the uri will be fixed and a fake via will be added).

The route should perform additional security checks to ensure the client is authorized to execute management/RPC functions and then it should call the `dispatch_rpc()`.

#### Set `event_callback` parameter

    ...
    modparam("xmlrpc", "event_callback", "ksr_xmlrpc_event")
    ...
    -- event callback function implemented in Lua
    function ksr_xmlrpc_event(evname)
    	KSR.info("===== xmlrpc triggered event: " .. evname .. "\n");
    	local rpc_method = KSR.pv.get("$rm") or ""
    	if ((rpc_method == "POST" or rpc_method == "GET")) then
    		if (KSR.xmlrpc.dispatch_rpc() < 0) then
    			KSR.err("error while executing xmlrpc event")
    		end
    	end
    	return 1;
    end
    ...

## Functions

### `dispatch_rpc()`

This function processes an XMLRPC request, found in the body of the request.

It should be used only in a route specified using the `"route"` module parameter or if the request method is GET or POST (using it for other request methods will not have adverse side-effects, but it will probably not work).

dispatch_rpc() extracts the XML-RPC document from the body of the request to determine the name of the RPC method to be called and then it searches through the list of all the RPC functions to find a function with matching name. If such a function is found then dispatch_rpc() will pass control to the function to handle the request.

#### `dispatch_rpc` usage

    #...
    modparam("xmlrpc", "route", "XMLRPC");
    #...
    route[XMLRPC]{
    	if search("^User-Agent:.*xmlrpclib"))
    		set_reply_close();
    	set_reply_no_connect(); # optional
    	dispatch_rpc();
    }

### `xmlrpc_reply(code, reason)`

This function can be called from the config script to directly generate an XML-RPC reply.

#### `xmlrpc_reply` usage

    #...
    modparam("xmlrpc", "route", "XMLRPC");
    #...
    route[XMLRPC]{
    	# allow XMLRPC requests only on TLS and only if the client
    	# certificate is valid
    	if (proto!=TLS){
    		xmlrpc_reply("400", "xmlrpc allowed only over TLS");
    		return;
    	}
    	if (@tls.peer.verified!=""){
    		xmlrpc_reply("400", "Unauthorized");
    		return;
    	}
    	if search("^User-Agent:.*xmlrpclib"))
    		set_reply_close();
    	set_reply_no_connect(); # optional
    	dispatch_rpc();
    }