Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SIPSAK(1)			 User Manuals			     SIPSAK(1)

       sipsak -	a utility for various tests on sip servers and user agents

       sipsak  [-dFGhiILnNMRSTUVvwz]  [-a PASSWORD ] [-b NUMBER	] [-c SIPURI ]
       [-C SIPURI ] [-D	NUMBER ] [-e NUMBER ] [-E STRING  ]  [-f  FILE	]  [-g
       STRING  ] [-H HOSTNAME ]	[-l PORT ] [-m NUMBER ]	[-o NUMBER ] [-p HOST-
       NAME ] [-P NUMBER ] [-q REGEXP ]	[-r PORT ] [-t NUMBER ]	[-u  STRING  ]
       [-W NUMBER ] [-x	NUMBER ] -s SIPURI

       sipsak  is a SIP	stress and diagnostics utility.	 It sends SIP requests
       to the server within the	sip-uri	and examines received  responses.   It
       runs in one of the following modes:

       - default mode
	      A	SIP message is sent to destination in sip-uri and reply	status
	      is displayed.  The request is either taken from filename or gen-
	      erated as	a new OPTIONS message.

       - traceroute mode (-T)
	      This  mode  is  useful  for learning request's path. It operates
	      similarly	to IP-layer utility traceroute(8).

       - message mode (-M)
	      Sends a short message (similar to	SMS from the mobile phones) to
	      a	 given	target.	 With the option -B the	content	of the MESSAGE
	      can be set. Usefull might	be the options -c and -O in this mode.

       - usrloc	mode (-U)
	      Stress mode for SIP registrar.  sipsak keeps  registering	 to  a
	      SIP  server  at  high  pace.  Additionaly	 the  registrar	can be
	      stressed with the	-I or the -M option.  If -I and	-M are omitted
	      sipsak  can  be  used to register	any given contact (with	the -C
	      option) for an account at	a registrar and	to query  the  current
	      bindings for an account at a registrar.

       - randtrash mode	(-R)
	      Parser  torture  mode.   sipsak keeps sending randomly corrupted
	      messages to torture a SIP	server's parser.

       - flood mode (-F)
	      Stress mode for SIP servers.  sipsak keeps sending requests to a
	      SIP server at high pace.

       If  libruli  ( support is compiled into the
       sipsak binary, then first a SRV lookup for _sip._udp.hostname is	 made.
       And if this lookup fails	a normal A lookup is made. If a	port was given
       in the target URI the SRV lookup	is omitted. Failover,  load  distribu-
       tion and	other transports are not supported yet.

       -a, --password PASSWORD
	      With  the	 given PASSWORD	an authentication will be tryed	on re-
	      ceived '401 Unauthorized'. Authorization will be tryed on	 time.
	      If  this	option is omitted an authorization with	an empty pass-
	      word ("")	will be	tryed. If the password is equal	to - the pass-
	      word  will  be read from the standard input (e.g.	the keyboard).
	      This prevents other users	on the same host from seeing the pass-
	      word the password	in the process list.  NOTE: the	password still
	      can be read from the memory if other users have access to	it.

       -A, --timing
	      prints only the timing values of the test	run  if	 verbosity  is
	      zero  because no -v was given. If	one or more -v were given this
	      option will be ignored.

       -b, --apendix-begin NUMBER
	      The starting number which	is appended to the user	 name  in  the
	      usrloc  mode.   This  NUMBER  is	increased until	it reaches the
	      value given by the -e parameter. If omitted the starting	number
	      will be one.

       -B, --message-body STRING
	      The  given  STRING will be used as the body for outgoing MESSAGE

       -c, --from SIPURI
	      The given	SIPURI will be used in the From	header if sipsak  runs
	      in  the  message	mode  (initiated  with the -M option). This is
	      helpfull to present the receiver of a MESSAGE a meaningfull  and
	      usable address to	where maybe even responses can be send.

       -C, --contact SIPURI
	      This  is	the  content of	the Contact header in the usrloc mode.
	      This allows to insert forwards like for mail.  For  example  you
	      can  insert  the	uri  of	your first SIP account at a second ac-
	      count, thus all calls to the second account will be forwarded to
	      the  first  account.  As the argument to this option will	not be
	      enclosed in brackets you can give	also multiple contacts in  the
	      raw  format as comma seperated list.  The	special	words empty or
	      none will	result in no contact header in	the  REGISTER  request
	      and  thus	the server should answer with the current bindings for
	      the account at the registrar.

       -d, --ignore-redirects
	      If this option is	set all	redirects will be ignored. By  default
	      without  this  option received redirects will be respected. This
	      option is	automaticly activated in the randtrash mode and	in the
	      flood mode.

       -D, --timeout-factor NUMBER
	      The  SIP_T1  timer  is getting multiplied	with the given NUMBER.
	      After receiving a	provisional response for an INVITE request, or
	      when  a  reliable	transport like TCP or TLS is used sipsak waits
	      for the resulting	amount of time for a final response  until  it
	      gives up.

       -e, --appendix-end NUMBER
	      The ending number	which is appended to the user name in the usr-
	      loc mode.	 This number is	increased until	it reaches this	ending
	      number.	In  the	 flood mode this is the	maximum	number of mes-
	      sages which will be send.	 If omitted the	default	value is  2^31
	      (2147483647) in the flood	mode.

       -E, --transport STRING
	      The value	of STRING will be used as IP transport for sending and
	      receiving	requests and responses.	 This  option  overwrites  any
	      result  from  the	URI evaluation and SRV lookup.	Currently only
	      'udp' and	'tcp' are accepted as value for	STRING.

       -f, --filename FILE
	      The content of FILE will be read in in binary mode and  will  be
	      used  as	replacement for	the alternatively created sip message.
	      This can used in the default mode	to make	 other	requests  than
	      OPTIONS  requests	(e.g. INVITE). By default missing carriage re-
	      turns in front of	line feeds will	be inserted (use -L to	de-ac-
	      tivate this function). If	the filename is	equal to - the file is
	      read from	standard input,	e.g. from  the	keyboard  or  a	 pipe.
	      Please  note that	the manipulation functions (e.g. inserting Via
	      header) are only tested with RFC conform	requests.  Additionaly
	      special  strings within the file can be replaced with some local
	      or given values (see -g and -G for details).

       -F, --flood-mode
	      This options activates the flood mode. In	this mode OPTIONS  re-
	      quests  with  increasing	CSeq  numbers  are sent	to the server.
	      Replies are ignored -- source port 9 (discard) of	 localhost  is
	      advertised in topmost Via.

       -h, --help
	      Prints  out  a  simple  usage  help  message. If the long	option
	      --help is	available it will print	out a help  message  with  the
	      available	long options.

       -g, --replace-string STRING
	      Activates	 the replacement of $replace$ within the request (usu-
	      aly read in from a file) with the	STRING.	 Alternatively you can
	      also  specify  a list of attribute and values.  This list	has to
	      start and	end with a non alpha-numeric character.	The same char-
	      acter has	to be used also	as seperator between the attribute and
	      the value	and between new	further	 attribute  value  pairs.  The
	      string  "$attribute$"  will be replaced with the value string in
	      the message.

       -G, --replace
	      Activates	the automatic replacement of the  following  variables
	      in  the  request (usualy read in from a file): $dsthost$ will be
	      replaced by with the host	or domainname which is given by	the -s
	      parameter.   $srchost$  will  be replaced	by the hostname	of the
	      local machine.  $port$ will be replaced by the  local  listening
	      port  of	sipsak.	 $user$	will be	replaced by the	username which
	      is given by the -s parameter.

       -H, --hostname HOSTNAME
	      Overwrites the automatic detection  of  the  hostname  with  the
	      given  parameter.	  Warning:  use	 this with caution (preferable
	      only if the automatic detection fails).

       -i, --no-via
	      Deactivates the insertion	of the	Via  line  of  the  localhost.
	      Warning:	this  probably disables	the receiving of the responses
	      from the server.

       -I, --invite-mode
	      Activates	the Invites cycles within the usrloc mode.  It	should
	      be  combined  with  -U.  In this combination sipsak first	regis-
	      teres a user, and	then simulates an  invitation  to  this	 user.
	      First  an	Invite is sent,	this is	replied	with 200 OK and	finaly
	      an ACK is	sent. This option can also be used without  -U	,  but
	      you  should  be sure to NOT invite real UAs with this option. In
	      the case of a missing -U the -l PORT is required because only if
	      you  made	a -U run with a	fixed local port before, a run with -I
	      and the same fixed local port can	be successful.	Warning:  sip-
	      sak  is no real UA and invitations to real UAs can result	in un-
	      expected behaivior.

       -j, --headers STRING
	      The string will be added as one or more  additional  headers  to
	      the  request. The	string "\n" (note: two characters) will	be re-
	      placed with CRLF and thus	result in two  seperate	headers.  That
	      way more then one	header can be added.

       -l, --local-port	PORT
	      The  receiving UDP socket	will use the local network port.  Use-
	      ful if a file is given by	-f which contains a correct Via	 line.
	      Check  the  -S  option for details how sipsak sends and receives

       -L, --no-crlf
	      De-activates the insertion of carriage returns (\r)  before  all
	      line feeds (\n) (which is	not allready proceeded by carraige re-
	      turn) if the input is comming from a file	( -f ).	 Without  this
	      option also an empty line	will be	appended to the	request	if re-

       -m, --max-forwards NUMBER
	      This sets	the value of the Max-Forward header field. If  omitted
	      no Max-Forward field will	be inserted. If	omitted	in the tracer-
	      oute mode	number will be 255.

       -M, --message-mode
	      This activates the Messages cycles within	the usrloc mode	(known
	      from  sipsak  versions pre 0.8.0 within the normal usrloc	test).
	      This option should be combined with -U so	that a succesful  reg-
	      istration	 will  be  tested  with	a test message to the user and
	      replied with 200 OK. But this option can also  be	 used  without
	      the  -U  option.	Warning: using without -U can cause unexpected

       -n, --numeric
	      Instead of the full qualified domain name	in the Via line	the IP
	      of  the  local  host  will be used. This option is now on	by de-

       -N, --nagios-code
	      Use Nagios comliant return codes instead of  the	normal	sipsak
	      ones. This means sipsak will return 0 if everything was ok and 2
	      in case of any error (local or remote).

       -o, --sleep NUMBER
	      sipsak will sleep	for NUMBER ms before it	starts the next	 cycle
	      in  the  usrloc mode. This will slow down	the whole test process
	      to be more realistic. Each cycle will be still completed as fast
	      as possible, but the whole test will be slowed down.

       -O, --disposition STRING
	      The  given  STRING  will be used as the content for the Content-
	      Disposition header. Without this option there will  be  no  Con-
	      tent-Disposition header in the request.

       -p, --outbound-proxy HOSTNAME[:PORT]
	      the address of the hostname is the target	where the request will
	      be sent to (outgoing proxy). Use this if the destination host is
	      different	then the host part of the request uri. The hostname is
	      resolved via DNS SRV if supported	(see description for  SRV  re-
	      solving) and no port is given.

       -P, --processes NUMBER
	      Start  NUMBER  of	processes in parallel to do the	send and reply
	      checking.	Makes only sence if a higher number for	-e is given in
	      the usrloc, message or invite mode.

       -q, --search REGEXP
	      match  replies  against  REGEXP and return false if no match oc-
	      cured. Useful for	example	to detect server name in Server	header

       -r, --remote-port PORT
	      Instead  of the default sip port 5060 the	PORT will be used. Al-
	      ternatively the remote port can be given within the sip  uri  of
	      the -s parameter.

       -R, --random-mode
	      This activates the randtrash mode. In this mode OPTIONS requests
	      will be send to  server  with  increasing	 numbers  of  randomly
	      crashed  characters within this request. The position within the
	      request and the replacing	character  are	randomly  chosen.  Any
	      other  response than Bad request (4xx) will stop this mode. Also
	      three unresponded	sends will stop	this mode. With	the -t parame-
	      ter the maximum of trashed characters can	be given.

       -s, --sip-uri SIPURI
	      This  mandatory  option  sets the	destination of the request. It
	      depends on the mode if only the server name or also an user name
	      is  mandatory.  Example for a full SIPURI	:
	      See the note in the description part about SRV lookups  for  de-
	      tails  how  the hostname of this URI is converted	into an	IP and

       -S, --symmetric
	      With this	option sipsak will use only one	port for  sending  and
	      receiving	 messages. With	this option the	local port for sending
	      will be the value	from the -l option. In the default mode	sipsak
	      sends  from a random port	and listens on the given port from the
	      -l option.  Note:	With this option sipsak	will not  be  able  to
	      receive replies from servers with	asymmetric signaling (and bro-
	      ken rport	implementation)	like the Cisco proxy. If you run  sip-
	      sak  as  root and	with raw socket	support	(check the output from
	      the -V option) then this option is not required because in  this
	      case sipsak already uses only one	port for sending and receiving

       -t, --trash-chars NUMBER
	      This parameter specifies the maximum of  trashed	characters  in
	      the  randtrash mode. If omitted NUMBER will be set to the	length
	      of the request.

       -T, --traceroute-mode
	      This activates the traceroute mode. This	mode  works  like  the
	      well  known  traceroute(8) command expect	that not the number of
	      network hops are counted rather the number of server on the  way
	      to  the  destination  user. Also the round trip time of each re-
	      quest is printed out, but	due to a  limitation  within  the  sip
	      protocol	the  identity  (IP  or	name)  can only	determined and
	      printed out if the response from the server contains  a  warning
	      header field. In this mode on each outgoing request the value of
	      the Max-Forwards header field is increased, starting  with  one.
	      The  maximum  of	the  Max-Forwards  header will 255 if no other
	      value is given by	the -m parameter. Any other response than  483
	      or  1xx  are treated as a	final response and will	terminate this

       -u, --auth-username STRING
	      Use the given STRING as username value  for  the	authentication
	      (different account and authentication username).

       -U, --usrloc-mode
	      This activates the usrloc	mode. Without the -I or	the -M option,
	      this only	registers users	at a registrar.	With one of the	 above
	      options  the  previous registered	user will also be probed ether
	      with a simulated call flow (invite, 200, ack) or with an instant
	      message  (message,  200).	 One  password	for all	users accounts
	      within the usrloc	test can be given with the -a option. An  user
	      name  is mandatory for this mode in the -s parameter. The	number
	      starting from the	-b parameter to	the -e parameter  is  appended
	      the  user	name. If the -b	and the	-e parameter are omitted, only
	      one runs with the	given username,	but without append  number  to
	      the usernames is done.

       -v, --verbose
	      This  parameter  increases  the  output  verbosity.  No -v means
	      nearly no	output except in traceroute and	 error	messages.  The
	      maximum  of  three v's prints out	the content of all packets re-
	      ceived and sent.

       -V, --version
	      Prints out the name and version number of	sipsak and the options
	      which were compiled into the binary.

       -w, --extract-ip
	      Activates	 the extraction	of the IP or hostname from the Warning
	      header field.

       -W, --nagios-warn NUMBER
	      Return Nagios warn exit code (1) if the  number  of  retransmis-
	      sions before success was above the given number.

       -x, --expires NUMBER
	      Sets the value of	the Expires header to the given	number.

       -z, --remove-bindings
	      Activates	 the  randomly	removing of old	bindings in the	usrloc
	      mode. How	many per cent of the bindings will be removed, is  de-
	      termined	by  the	 USRLOC_REMOVE_PERCENT	define within the code
	      (set it before compilation).  Multiple removing of  bindings  is
	      possible,	and cannot be prevented.

       The  return  value  0  means that a 200 was received. 1 means something
       else then 1xx or	2xx was	received.  2 will be returned on local	errors
       like  non  resolvable names or wrong options combination. 3 will	be re-
       turned on remote	errors like socket errors (e.g.	icmp error), redirects
       without a contact header	or simply no answer (timeout).

       If  the	-N  option  was	given the return code will be 2	in case	of any
       (local or remote) error.	1 in case there	have been retransmissions from
       sipsak to the server. And 0 if there was	no error at all.

       Use sipsak responsibly. Running it in any of the	stress modes puts sub-
       stantial	burden on network and server under test.

       sipsak -vv -s
	      displays received	replies.

       sipsak -T -s
	      traces SIP path to nobody.

       sipsak -U -C sip:me@home	-x 3600	-a password -s sip:myself@company
	      inserts forwarding from work to home for one hour.

       sipsak -f bye.sip -g '!FTAG!345.af23!TTAG!1208.12!' -s sip:myproxy
	      reads the	file bye.sip, replaces $FTAG$ with 345.af23 and	$TTAG$
	      with 1208.12 and finally send this message to myproxy

       Many  servers  may  decide  NOT to include SIP "Warning"	header fields.
       Unfortunately, this makes displaying IP addresses  of  SIP  servers  in
       traceroute mode impossible.

       IPv6 is not supported.

       Missing support for the Record-Route and	Route header.

       sipsak is only tested against the SIP Express Router (ser) though their
       could be	various	bugs. Please feel free to mail them to the author.

       Nils Ohlmeier <nils at sipsak dot org>


Linux			  JULY 2002 - SEPTEMBER	2005		     SIPSAK(1)


Want to link to this manual page? Use this URL:

home | help