Provided by: sipsak_0.9.6-2.1build1_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)