utils/kamcmd/README
b477f413
 # $Id$
 #
 # History:
 # --------
 #  2009-05-07  created by Andrei Pelinescu-Onciul <andrei@iptel.org>
 
 
 Overview
 ========
 
9b745fbb
 kamcmd is a unix tool for interfacing with Kamailio using exported RPCs.
b477f413
 It uses binrpc (a proprietary protocol, designed for minimal packet size and
 fast parsing) over a variety of transports (unix stream sockets, unix datagram
  sockets, udp or tcp).
 For more details on binrpc see the ctl module documentation
9b745fbb
 (modules/ctl/README).
b477f413
 
9b745fbb
 kamcmd can work in command line mode (the RPC or command name is just another
b477f413
 command line parameter) or in interactive mode. The interactive mode supports
9b745fbb
 history and tab-completion (if kamcmd was compiled with libreadline support).
b477f413
 
9b745fbb
 On Kamailio side the ctl module must be loaded.
b477f413
 
 Usage
 =====
 
9b745fbb
 	kamcmd [options][-s address] [ cmd ]
b477f413
 
 Options:
     -s address  unix socket name or host name to send the commands on
     -R name     force reply socket name, for the unix datagram socket mode
     -D dir      create the reply socket in the directory <dir> if no reply
                 socket is forced (-R) and an unix datagram socket is selected
                 as the transport
     -f format   print the result using format. Format is a string containing
                 %v at the places where values read from the reply should be
                 substituted. To print '%v', escape it using '%': %%v.
     -v          Verbose 
     -V          Version number
     -h          Help message
 address:
     [proto:]name[:port]   where proto is one of tcp, udp, unixs, unix or unixd
                           e.g.:  tcp:localhost:2048 , unixs:/tmp/ser_ctl
                           If the protocol is not specified, unixs will be
                           used if name is a filesystem path and udp if not.
                           "unixs" or "unix" stand for unix stream sockets
                           and "unixd" for unix datagram sockets.
 cmd:
     method  [arg1 [arg2...]]
 arg:
      string or number; to force a number to be interpreted as string 
      prefix it by "s:", e.g. s:1
 
9b745fbb
 If no address is specified (no -s), kamcmd will use  by default
b477f413
 unixs:/tmp/ser_ctl. This is also the default for the ctl module (if no
  "binrpc" module parameters are present in the config).
 
 
 Command Types
 =============
 
9b745fbb
 There are 3 types of commands: "raw" RPC, kamcmd aliases and kamcmd
b477f413
  builtins.
 
 The "raw" RPC commands work directly with ser with no change on the input or
  the output.
9b745fbb
 To list available RPC commands, use "kamcmd help".
b477f413
 
9b745fbb
 The aliases are just easier to remember names for some RPCs, which
 some time include nicer formatting of the RPC result.
 One can see all the defined aliases using: kamcmd help|grep alias: .
b477f413
 Example:
  ps is an alias for core.ps with the output formatted in a more readable way.
9b745fbb
  kamcmd ps is equivalent to kamcmd -f"%v\t%v\n" core.ps.
  Without the formatting, the output of kamcmd core.ps looks like:
b477f413
 
 11262
 attendant
 11268
 udp receiver child=0 sock=127.0.0.1:5060
 ...
9b745fbb
  Using kamcmd ps (or  kamcmd -f"%v\t%v\n" core.ps) the output looks like:
b477f413
 
 11262	attendant
 11268	udp receiver child=0 sock=127.0.0.1:5060
 ...
 
 The built-in commands can combine several different rpcs.
9b745fbb
 One can see all the built-in commands using: kamcmd help|grep builtin: .
b477f413
 
 Getting help on a command
 =========================
 
 To get the help message associated with a command use 
9b745fbb
 kamcmd help <command_name>.
b477f413
 Example:
9b745fbb
 $ kamcmd help ps
b477f413
 ps is an alias for core.ps with reply formatting: "%v\t%v\n"
9b745fbb
 $ kamcmd help core.ps
 Returns the description of running Kamailio processes.
b477f413
 
 
 Listing all the commands
 ========================
 
 To see all the available commands (ser RPCs, aliases and bultins) use
9b745fbb
  kamcmd help.
 To see only the "raw" RPCs, user kamcmd ls.
b477f413
 Note: since each module can define its own RPCs, the available RPCs depend
  on the loaded modules.
 
 
 Examples
 ========
 
 Using the default socket (requires only loadmodule "ctl" in ser.cfg):
 
9b745fbb
 $ kamcmd ps
b477f413
 11262	attendant
 11268	udp receiver child=0 sock=127.0.0.1:5060
 11269	udp receiver child=1 sock=127.0.0.1:5060
 11270	udp receiver child=0 sock=192.168.1.101:5060
 11271	udp receiver child=1 sock=192.168.1.101:5060
 11272	slow timer
 11273	timer
 11274	ctl handler
 11275	tcp receiver child=0
 11276	tcp receiver child=1
 11277	tcp main process
 
9b745fbb
 $ kamcmd help  # list all the supported commands
b477f413
 dst_blacklist.add
 ctl.who
 ...
 
9b745fbb
 $ kamcmd help core.uptime # help for the core.uptime rpc
 Returns uptime of the Kamailio server.
b477f413
 
9b745fbb
 $ kamcmd cfg.cfg_set_int_now debug 5 # turn debug level to 5 (needs cfg)
b477f413
 
9b745fbb
 $ kamcmd # enters interactive mode
b477f413
 
 Using a tcp socket
9b745fbb
 (assumes modparam("ctl", "binrpc", "tcp:localhost:2048") in kamailio.cfg)
b477f413
 
9b745fbb
 $ kamcmd -s tcp:localhost:2048 core.version
 Server: Kamailio (3.3.2 (i386/linux))
b477f413
 
9b745fbb
 $ kamcmd -s tcp:localhost:2048 SRV _sip._udp.iptel.org
b477f413
     name: _sip._udp.iptel.org
     type: SRV
     size (bytes): 104
     reference counter: 2
     expires in (s): 67693
     last used (s): 0
     error flags: 0
     rr name: sip.iptel.org
     rr port: 5060
     rr priority: 0
     rr weight: 0
     rr expires in (s): 67693
     rr error flags: 0
 
9b745fbb
 kamcmd -s tcp:127.0.0.1:2048  # enters interactive mode over tcp
b477f413
 
9b745fbb
 For more examples see utils/kamcmd/EXAMPLES
  [http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=utils/kamcmd/EXAMPLES].
b477f413
 
 
 Interactive Mode
 ================
 
9b745fbb
 To enter the interactive mode start kamcmd without specifying a command name
b477f413
  on the command line.
9b745fbb
 If kamcmd was compiled with libreadline support (automatically if
b477f413
 libreadline dev files are installed), the interactive mode will have tab
 completion and history support.
 
 Example:
 
9b745fbb
 $ kamcmd
 kamcmd 0.2
b477f413
 Copyright 2006 iptelorg GmbH
 This is free software with ABSOLUTELY NO WARRANTY.
 For details type `warranty'.
9b745fbb
 kamcmd> core.s<tab>
b477f413
 core.sctp_info     core.sctp_options  core.shmmem
9b745fbb
 kamcmd> help core.shmmem 
b477f413
 Returns shared memory info.
9b745fbb
 kamcmd> core.shmmem
b477f413
 {
 	total: 33554432
 	free: 33147816
 	used: 190644
 	real_used: 406616
 	max_used: 406616
 	fragments: 2
 }
9b745fbb
 kamcmd> quit
b477f413
 
 
 Related Stuff
 =============
 
9b745fbb
 * ctl module: required, implements binrpc on Kamailio side, without it kamcmd doesn't work.
b477f413
 
9b745fbb
 See modules/ctl/README
b477f413
  [http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=modules_s/ctl/README].
 
9b745fbb
 * cfg_rpc module: allows setting or reading configuration parameters on-the-fly.
 	For example one could change the tcp connection lifetime to 180s using:
 	$ kamcmd cfg.set_now_int tcp.connection_lifetime 180
 	See modules/cfg_rpc/README
  	[http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=modules_s/cfg_rpc/README].