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)