xenial (1) sipsak.1.gz

Provided by: sipsak_0.9.6-2.3_amd64 bug

NAME

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

SYNOPSIS

       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
       HOSTNAME  ]  [-P  NUMBER ] [-q REGEXP ] [-r PORT ] [-t NUMBER ] [-u STRING ] [-W NUMBER ] [-x NUMBER ] -s
       SIPURI

DESCRIPTION

       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 generated 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 (http://www.nongnu.org/ruli/) 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 distribution and other  transports  are
       not supported yet.

OPTIONS

       -a, --password PASSWORD
              With  the  given  PASSWORD  an  authentication  will  be  tryed  on  received  '401 Unauthorized'.
              Authorization will be tryed on time. If this option is omitted  an  authorization  with  an  empty
              password  ("")  will  be  tryed.  If the password is equal to - the password will be read from the
              standard input (e.g. the keyboard). This prevents other users on the same  host  from  seeing  the
              password  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 requests.

       -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  account,  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 usrloc mode.  This number is increased
              until it reaches this ending number.  In the flood mode this is the  maximum  number  of  messages
              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 returns in front of line feeds will be
              inserted (use -L to de-activate 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 requests 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 (usualy 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 character 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 registeres 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: sipsak is no real
              UA and invitations to real UAs can result in unexpected 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 replaced 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.  Useful if a file is given by -f which
              contains a correct Via line. Check the -S  option  for  details  how  sipsak  sends  and  receives
              messages.

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

       -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 traceroute 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
              registration 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
              behaivor.

       -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 default.

       -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 Content-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 resolving) 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 occured. Useful for  example  to  detect
              server name in Server header field.

       -r, --remote-port PORT
              Instead  of  the default sip port 5060 the PORT will be used. Alternatively 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 parameter 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 : sip:test@foo.bar:123
              See the note in the description part about SRV lookups for details how the hostname of this URI is
              converted into an IP and port.

       -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  broken
              rport  implementation) like the Cisco proxy. If you run sipsak 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 messages.

       -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 request  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 mode.

       -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 received 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 retransmissions 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 determined by the USRLOC_REMOVE_PERCENT define within the code (set
              it before compilation).  Multiple removing of bindings is possible, and cannot be prevented.

RETURN VALUES

       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
       returned 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.

CAUTION

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

EXAMPLES

       sipsak -vv -s sip:nobody@foo.bar
              displays received replies.

       sipsak -T -s sip:nobody@foo.bar
              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

LIMITATIONS / NOT IMPLEMENTED

       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.

BUGS

       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.

AUTHOR

       Nils Ohlmeier <nils at sipsak dot org>

SEE ALSO

       traceroute(8)