[SR-Dev] git:master: sercmd: doc added (README)

Module: sip-router Branch: master Commit: b477f413dd740862de642790f6b3d80acc61dae0 URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=b477f41… Author: Andrei Pelinescu-Onciul &lt;andrei(a)iptel.org&gt; Committer: Andrei Pelinescu-Onciul &lt;andrei(a)iptel.org&gt; Date: Thu May 7 22:23:12 2009 +0200 sercmd: doc added (README) --- utils/sercmd/EXAMPLES | 2 +- utils/sercmd/README | 217 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 218 insertions(+), 1 deletions(-) diff --git a/utils/sercmd/EXAMPLES b/utils/sercmd/EXAMPLES index b46542d..079dc6a 100644 --- a/utils/sercmd/EXAMPLES +++ b/utils/sercmd/EXAMPLES @@ -4,7 +4,7 @@ sercmd usage examples help: - sercmd unixd:/tmp/unix_dgram -h + sercmd -h use an udp ser control socket: ser config: diff --git a/utils/sercmd/README b/utils/sercmd/README new file mode 100644 index 0000000..1c9c823 --- /dev/null +++ b/utils/sercmd/README @@ -0,0 +1,217 @@ +# $Id$ +# +# History: +# -------- +# 2009-05-07 created by Andrei Pelinescu-Onciul &lt;andrei(a)iptel.org&gt; + + +Overview +======== + +sercmd is a unix tool for interfacing with sip-router using ser exported RPCs. +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 +(modules_s/ctl/README). + +sercmd can work in command line mode (the RPC or command name is just another +command line parameter) or in interactive mode. The interactive mode supports +history and tab-completion (if sercmd was compiled with libreadline support). + +On ser side the ctl module must be loaded. + + +Usage +===== + + sercmd [options][-s address] [ cmd ] + +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 + +If no address is specified (no -s), sercmd will use by default +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 +============= + +There are 3 types of commands: "raw" ser RPC, sercmd aliases and sercmd + builtins. + +The "raw" RPC commands work directly with ser with no change on the input or + the output. +All the RPCs can be seen using sercmd ls. + +The aliases are just other easier to remember names for some ser RPCs, which +some time include nicer formatting of the rpc result. +One can see all the defined aliases using: sercmd help|grep alias: . +Example: + ps is an alias for core.ps with the output formatted in a more readable way. + sercmd ps is equivalent to sercmd -f"%v\t%v\n" core.ps. + Without the formatting, the output of sercmd core.ps looks like: + +11262 +attendant +11268 +udp receiver child=0 sock=127.0.0.1:5060 +... + Using sercmd ps (or sercmd -f"%v\t%v\n" core.ps) the output looks like: + +11262 attendant +11268 udp receiver child=0 sock=127.0.0.1:5060 +... + +The built-in commands can combine several different rpcs. +One can see all the built-in commands using: sercmd help|grep builtin: . + + +Getting help on a command +========================= + +To get the help message associated with a command use +sercmd help <command_name>. +Example: +$ sercmd help ps +ps is an alias for core.ps with reply formatting: "%v\t%v\n" +$ sercmd help core.ps +Returns the description of running SER processes. + + +Listing all the commands +======================== + +To see all the available commands (ser RPCs, aliases and bultins) use + sercmd help. +To see only the "raw" RPCs, user sercmd ls. +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): + +$ sercmd ps +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 + +$ sercmd help # list all the supported commands +dst_blacklist.add +ctl.who +... + +$ sercmd help core.uptime # help for the core.uptime rpc +Returns uptime of SER server. + +$ sercmd cfg.cfg_set_int_now debug 5 # turn debug level to 5 (needs cfg) + +$ sercmd # enters interactive mode + +Using a tcp socket +(assumes modparam("ctl", "binrpc", "tcp:localhost:2048") in ser.cfg) + +$ sercmd -s tcp:localhost:2048 core.version +Server: Sip EXpress router (2.1.0-dev23-make (i386/linux)) + +$ sercmd -s tcp:localhost:2048 SRV _sip._udp.iptel.org + 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 + +sercmd -s tcp:127.0.0.1:2048 # enters interactive mode over tcp + +For more examples see utils/sercmd/EXAMPLES + [http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=utils/se…]. + + +Interactive Mode +================ + +To enter the interactive mode start sercmd without specifying a command name + on the command line. +If sercmd was compiled with libreadline support (automatically if +libreadline dev files are installed), the interactive mode will have tab +completion and history support. + +Example: + +$ sercmd +sercmd 0.1 +Copyright 2006 iptelorg GmbH +This is free software with ABSOLUTELY NO WARRANTY. +For details type `warranty'. +sercmd> core.s<tab> +core.sctp_info core.sctp_options core.shmmem +sercmd> help core.shmmem +Returns shared memory info. +sercmd> core.shmmem +{ + total: 33554432 + free: 33147816 + used: 190644 + real_used: 406616 + max_used: 406616 + fragments: 2 +} +sercmd> quit + + +Related Stuff +============= + + +ctl module: required, implements binrpc on ser side, without it sercmd +doesn't work. +See modules_s/ctl/README + [http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=modules_…]. + +cfg_rpc module: allows setting or reading configuration parameters on-the-fly. +For example one could change the tcp connection lifetime to 180s using: +$ sercmd cfg.set_now_int tcp.connection_lifetime 180 +See modules_s/cfg_rpc/README + [http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=modules_…].