SIPSAK(1)

NAME
sipsak - a utility for various tests on sip server

SYNOPSIS
sipsak [-dFhinRTUVvwz] [-a password ] [-b number ] [-c number ] [-e number ] [-f filename ] [-l port ] [-m number ] [-r port ] [-t number ] [-x number ] -s sip-uri

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

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

- usrloc mode (-U)
    stress mode for SIP registrar. sipsak keeps registering and sending requests to a SIP server at high pace.

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

OPTIONS

-a password
    With the given password an authentication will be tryed on received '401 Unauthorized'. Authorization will be tryed on time. If no this option is omitted an authorization with the username as password will be tryed.

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

-c number
    This is the maximum CSeq number in the flood mode. If omitted the maximum will be 2^31 (2147483647).

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

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

-f filename
    The content of filename will be read in in binary mode and will be used as replacement for the alternatively created sip header. This can used in the default mode to make other requests than OPTIONS requests (e.g. INVITE). But be warned that the manipulation functions (e.g. inserting Via header) are only tested with RFC conform requests.

-F  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  Prints out a simple usage help message.

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

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

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

-n  In stead of the full qualified domain name in the Via line the IP of the local host will be used.

-r port
    In stead 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  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
    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 sip:uri : sip:test@foo.bar:123

-t 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  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  This activates the usrloc mode. First a REGISTER request for the given user name is sent to server. Authentication is not expected and not supported. After successful registration an IM request is sent to the before registered user. After successful receiving the before sent IM the expected 200 is sent back. If the 200 is received successful the number at the end of the user name is increased and the next usrloc cycle starts. 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  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  Prints out only the name and version number of sipsak.

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

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

-z  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 can not be prevented.

RETURN VALUES
The return value 0 means that no error occurred and received the expected answer (a 200 in most cases). 1 will be returned on unexpected answers. 2 will be returned on local errors like non resolvable names, socket errors or wrong options combination. 3 will be returned on remote errors like icmp error messages or redirects without a contact header.

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.

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. sipsak is case sensitive (not RFC conform). So all the header fields are only found if they are written like in the RFC. The short notation is not supported. IPv6 is not supported. DNS/SRV is not supported. Currently, sipsak has only been ported to Linux.

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 <ohlmeier at fokus dot fhg dot de>

SEE ALSO
traceroute(8)