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

Andrei Pelinescu-Onciul andrei at iptel.org
Thu May 7 22:23:54 CEST 2009


Module: sip-router
Branch: master
Commit: b477f413dd740862de642790f6b3d80acc61dae0
URL:    http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=b477f413dd740862de642790f6b3d80acc61dae0

Author: Andrei Pelinescu-Onciul <andrei at iptel.org>
Committer: Andrei Pelinescu-Onciul <andrei at iptel.org>
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 <andrei at iptel.org>
+
+
+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/sercmd/EXAMPLES].
+
+
+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_s/ctl/README].
+
+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_s/cfg_rpc/README].




More information about the sr-dev mailing list