<?xml version="1.0" encoding="UTF-8"?>
<!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 "../../../../doc/docbook/entities.xml">


<book id="ctl" xmlns:xi="http://www.w3.org/2001/XInclude">
	<title>The Ctl Module</title>
		<affiliation><orgname>iptelorg GmbH</orgname></affiliation>
		<holder>iptelorg GmbH</holder>

	<title>Admin Guide</title>
	<section id="ctl.overview">
		This module implements the binrpc transport interface for &kamailio; RPCs.
		It supports various transports over which it speaks binrpc:
		Unix datagram sockets, Unix stream sockets, UDP and TCP.
		It also supports a backward compatible FIFO interface (using the old
		&kamailio; FIFO protocol).
		By default (if no parameters are changed in the config file) it uses
		a Unix stream socket under /run/&kamailiobinary;:
		/run/&kamailiobinary;/&ctlsocket;. This socket is also the
		default for &sercmd;.
		In general it's used in conjunction with &sercmd;. &sercmd; is a Unix
		tool for invoking &kamailio; RPC functions. It can be used both in
		interactive mode (supports tab-completion and history) or command
		line mode.
		<title><function>&sercmd; example</function> usage</title>
		<programlisting format="linespecific">

$ &sercmd; ps
11262	attendant
11268	udp receiver child=0 sock=
11269	udp receiver child=1 sock=
11270	udp receiver child=0 sock=
11271	udp receiver child=1 sock=
11272	slow timer
11273	timer
11274	ctl handler
11275	tcp receiver child=0
11276	tcp receiver child=1
11277	tcp main process

	See <ulink url='http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=utils/sercmd/EXAMPLES' >utils/&sercmd;/EXAMPLES</ulink>
	for more examples.
	<section id="ctl.binrpc">
		binrpc is a &kamailio; proprietary binary protocol for invoking rpcs.
		It was designed such that it would minimize the packet sizes and it
		would be very fast to parse (as opposed to XML-rpc).
		The binrpc encoding format is fully documented inside
		<ulink url='http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=modules/ctl/binrpc.h' >

    <xi:include href="ctl_params.xml"/>
    <xi:include href="ctl_rpc.xml"/>