kamailio/modules/jsonrpc-s/doc/jsonrpc-s_admin.xml

<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
%docentities;

]>
<!-- Module User's Guide -->

<chapter>

	<title>&adminguide;</title>

	<section>
	<title>Overview</title>
	<para>
		This module provides a JSON-RPC v2 server over HTTP implementation,
		tailored for the needs of &kamailio;. It implements the &kamailio;
		RPC interface over JSON-RPC.
	</para>
	<para>
		The specification for JSON-RPC is available at:
		<ulink url="http://www.jsonrpc.org/specification">http://www.jsonrpc.org/specification</ulink>.
	</para>
	<para>
		The JSONRPC-S module uses the xHTTP module to handle HTTP/S requests.
		Read the documentation of the xHTTP module for more details.
	</para>

	<section>
	<title>Limitations</title>
	<itemizedlist>
	<listitem>
	<para>
		This module does not implement asynchronous RPC commands.
		It is unlikely that asynchronous RPC commands will be executed
		from an JSON-RPC over HTTP client.
	</para>
	</listitem>
	<listitem>
	<para>
		This module does not accept parameters embedded in a structure
		(see the RPC documentation for more info about how parameters can be
		passed to RPC).
	</para>
	</listitem>
	</itemizedlist>
	</section>
	</section>

	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>xhttp</emphasis> - xHTTP.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&kamailio; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Parameters</title>
	<section id="jsonrpc-s.p.pretty_format">
		<title><varname>pretty_format</varname> (int)</title>
		<para>
			Pretty format for JSON-RPC response document.
		</para>
		<para>
		<emphasis>
			Default value is '0'.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>pretty_format</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jsonrpc-s", "pretty_format", 1)
...
</programlisting>
		</example>
	</section>
	<section id="jsonrpc-s.p.transport">
		<title><varname>transport</varname> (int)</title>
		<para>
			Control what transports are enabled. The value can be:
		</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>0</emphasis> - all transports that can be enabled.
				For http, the xhttp module must be loaded. For FIFO, the
				fifo_name parameter must be set.
			</para></listitem>
			<listitem><para>
				<emphasis>1</emphasis> - only HTTP transport
			</para></listitem>
			<listitem><para>
				<emphasis>2</emphasis> - only FIFO transport
			</para></listitem>
		</itemizedlist>

		<para>
		<emphasis>
			Default value is '0'.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>transport</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jsonrpc-s", "transport", 1)
...
</programlisting>
		</example>
	</section>
	<section id="jsonrpc-s.p.fifo_name">
		<title><varname>fifo_name</varname> (str)</title>
		<para>
		The name of the FIFO file to be created for listening and
		reading external commands. If the given path is not absolute,
		the fifo file is created relative to run_dir (global parameter).
		</para>
		<para>
		<emphasis>
			Default value is NONE.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>fifo_name</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jsonrpc-s", "fifo_name", "/tmp/kamailio_jsonrpc_fifo")
...
</programlisting>
		</example>
	</section>

	<section id="jsonrpc-s.p.fifo_mode">
		<title><varname>fifo_mode</varname> (int)</title>
		<para>
		Permission to be used for creating the listening FIFO file. It
		follows the UNIX conventions.
		</para>
		<para>
		<emphasis>
			Default value is 0660 (rw-rw----).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>fifo_mode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jsonrpc-s", "fifo_mode", 0600)
...
</programlisting>
		</example>
	</section>

	<section id="jsonrpc-s.p.fifo_group">
		<title><varname>fifo_group</varname> (int or str)</title>
		<para>
		System Group to be used for creating the listening FIFO file.
		</para>
		<para>
		<emphasis>
			Default value is the inherited one (process group).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>fifo_group</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jsonrpc-s", "fifo_group", 0)
modparam("jsonrpc-s", "fifo_group", "root")
...
</programlisting>
		</example>
	</section>

	<section id="jsonrpc-s.p.fifo_user">
		<title><varname>fifo_user</varname> (int or str)</title>
		<para>
		System User to be used for creating the listening FIFO file.
		</para>
		<para>
		<emphasis>
			Default value is the inherited one (process user).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>fifo_user</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jsonrpc-s", "fifo_user", 0)
modparam("jsonrpc-s", "fifo_user", "root")
...
</programlisting>
		</example>
	</section>

	<section id="jsonrpc-s.p.fifo_reply_dir">
		<title><varname>fifo_reply_dir</varname> (str)</title>
		<para>
		Directory to be used for creating the reply FIFO files.
		</para>
		<para>
		<emphasis>
			Default value is <quote>/tmp/</quote>
		</emphasis>
		</para>
		<example>
		<title>Set <varname>fifo_reply_dir</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("jsonrpc-s", "fifo_reply_dir", "/home/kamailio/tmp/")
...
</programlisting>
		</example>
	</section>

	</section>

	<section>
	<title>Functions</title>
 	<section id="jsonrpc-s.f.jsonrpc_dispatch">
	    <title>
		<function moreinfo="none">jsonrpc_dispatch()</function>
	    </title>
	    <para>
		Handle the JSONRPC request and generate a response.
	    </para>
		<example>
		<title><function>jsonrpc_dispatch</function> usage</title>
		<programlisting format="linespecific">
...
#!KAMAILIO

memdbg=5
memlog=5

debug=3
log_stderror=yes

fork=yes
children=2

tcp_accept_no_cl=yes

mpath="modules/"

loadmodule "sl.so"
loadmodule "pv.so"
loadmodule "xhttp.so"
loadmodule "jsonrpc-s.so"

request_route {
	send_reply("404", "not found");
	exit;
}

event_route[xhttp:request] {
    if(src_ip!=127.0.0.1) {
        xhttp_reply("403", "Forbidden", "text/html",
            "&lt;html&gt;&lt;body&gt;Not allowed from $si&lt;/body&gt;&lt;/html&gt;");
        exit;
	}
	if ($hu =~ "^/RPC") {
		jsonrpc_dispatch();
	} else {
        xhttp_reply("200", "OK", "text/html",
            "&lt;html&gt;&lt;body&gt;Wrong URL $hu&lt;/body&gt;&lt;/html&gt;");
    }
    return;
}
...
</programlisting>
	    </example>
	</section>
 	<section id="jsonrpc-s.f.jsonrpc_exec">
	    <title>
		<function moreinfo="none">jsonrpc_exec(cmd)</function>
	    </title>
	    <para>
			Execute a JSON-RPC command given as a parameter.
		</para>
		<para>
			The parameter has to be a valid full JSON-RPC document. It can
			be a dynamic string with variables. The result of the command
			can be accessed via $jsonrpl(key) pseudo variables.
	    </para>
		<example>
		<title><function>jsonrpc_exec</function> usage</title>
		<programlisting format="linespecific">
...
jsonrpc_exec({"jsonrpc": "2.0", "method": "dispatcher.reload", "id": 1}');
...
</programlisting>
	    </example>
	</section>

	</section>

	<section>
	<title>JSONRPC Commands</title>
	<para>
	Here are some examples of RPC commands with the equivalent of running them
	with &kamcmd; and the corresponding JSON document for them. It is important
	to be aware that the name of the parameters doesn't matter, only the order
	of the values must be the one expected by &kamailio; RPC command.
	</para>
	<example>
	<title>JSONRPC Commands - Examples</title>
	<programlisting format="linespecific">
...
# kamcmd core.psx

{
 "jsonrpc": "2.0",
  "method": "core.psx",
  "id": 1
}
...
## - prototype: kamcmd dispatcher.set_state _state_ _group_ _address_
# kamcmd dispatcher.set_state ip 2 sip:127.0.0.1:5080

{
  "jsonrpc": "2.0",
  "method": "dispatcher.set_state",
  "params": ["ip", 2, "sip:127.0.0.1:5080"],
  "id": 1
}

## - or:

{
  "jsonrpc": "2.0",
  "method": "dispatcher.set_state",
  "params": {
    "state": "ip",
    "grpup": 2,
    "address": "sip:127.0.0.1:5080"
  },
  "id": 1
}
...
</programlisting>
	    </example>

	</section>

	<section>
	<title>JSONRPC Transports</title>
	<para>
	JSONRPC specifications do not enforce a specific transport to carry the
	JSON documents. Very common is JSONRPC over HTTP or HTTPS, and they are
	supported by &kamailio;. In addition, &kamailio; supports receiving JSON
	documents via a local FIFO file.
	</para>
 	<section>
	    <title>JSONRPC Over HTTP</title>
	    <para>
			It requires that XHTTP module is loaded. HTTPS can be used if
			you enable TLS for &kamailio;. The JSONRPC requests have to be
			sent to the TCP or TLS ports of &kamailio;.
		</para>
		<para>
			The 'transport' parameter has to be 0 or 1.
		</para>
		<para>
			The format of the JSON document must follow the JSONRPC
			specifications.
		</para>
	</section>
 	<section>
	    <title>JSONRPC Over FIFO</title>
	    <para>
			This module can retrive JSONRPC requests via a local FIFO file. To
			enable this feature, 'fifo_name' parameter must be set and
			'transport' parameter has to be 0 or 2.
		</para>
		<para>
			The format of the JSON document must follow the JSONRPC
			specifications plus an additional field named 'reply_name'. The
			value for this field must be the name of the FIFO file were to
			write the JSONRPC response. The reply FIFO file is created in the
			folder specified by 'fifo_reply_dir'. Next is an example showing
			a JSONRPC command to be sent via FIFO transport.
		</para>
		<example>
		<title>JSONRPC Over Fifo Command</title>
		<programlisting format="linespecific">
...
{
 "jsonrpc": "2.0",
  "method": "core.psx",
  "reply_name": "kamailio_jsonrpc_reply_fifo",
  "id": 1
}
...
</programlisting>
	    </example>
		<para>
			Next is an example of how to test it from a terminal, assuming that
			the parameter 'fifo_name' is set to '/tmp/kamailio_jsonrpc_fifo'.
		</para>
		<example>
		<title>JSONRPC Over Fifo Command From Termina</title>
		<programlisting format="linespecific">
...
mkfifo /tmp/kamailio_jsonrpc_reply_fifo
cat /tmp/kamailio_jsonrpc_reply_fifo &amp;
echo '{"jsonrpc": "2.0", "method": "core.psx", \
          "reply_name": "kamailio_jsonrpc_reply_fifo", "id": 1}' \
     > /tmp/kamailio_jsonrpc_fifo
rm /tmp/kamailio_jsonrpc_reply_fifo
</programlisting>
	    </example>

	</section>
	</section>

</chapter>