Section: User Manuals (1)
Updated: JULY 2002 - SEPTEMBER 2005
sipsak - a utility for various tests on sip servers and user agents
sipsak [-dFGhiILnNMRSTUVvwz] [-a
is a SIP stress and diagnostics utility.
It sends SIP requests to the server within the
and examines received responses.
It runs in one of the following modes:
- - default mode
A SIP message is sent to destination in
and reply status is displayed.
The request is either taken from
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
- - message mode (-M)
Sends a short message (similar to SMS from the mobile phones) to a given target. With the option
the content of the MESSAGE can be set. Usefull might be the options
in this mode.
- - usrloc mode (-U)
Stress mode for SIP registrar.
keeps registering to a SIP server at high pace. Additionaly the registrar
can be stressed with the
can be used to register any given contact (with the
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.
keeps sending randomly corrupted messages to torture a SIP server's
- - flood mode (-F)
Stress mode for SIP servers.
keeps sending requests to a SIP server at high pace.
If libruli (http://www.nongnu.org/ruli/) support is compiled into the
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.
- -a, --password PASSWORD
With the given
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.
the password still can be read from the memory if other users have access to
- -A, --timing
prints only the timing values of the test run if verbosity is zero because no
was given. If one or more
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.
is increased until it reaches the value given by the
parameter. If omitted the starting number will be one.
- -B, --message-body STRING
will be used as the body for outgoing MESSAGE requests.
- -c, --from SIPURI
will be used in the From header if
runs in the message mode (initiated with the
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
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
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
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
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
- -f, --filename FILE
The content of
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
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
- -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
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
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):
will be replaced by with the host or domainname which is given
will be replaced by the hostname of the local machine.
will be replaced by the local listening port of
will be replaced by the username which is given by the
- -H, --hostname HOSTNAME
Overwrites the automatic detection of the hostname with the given parameter.
use this with caution (preferable only if the automatic detection fails).
- -i, --no-via
Deactivates the insertion of the Via line of the localhost.
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
In this combination
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
, but you should be sure to NOT invite real UAs with this option. In the case
of a missing
is required because only if you made a
run with a fixed local port before, a run with
and the same fixed local port can be successful.
is no real UA and invitations to real UAs can result in unexpected
- -j, --headers 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
Useful if a file is given by
which contains a correct Via line. Check the
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 (
). Without this option also an empty line will be appended to the request
- -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
will be 255.
- -M, --message-mode
This activates the Messages cycles within the usrloc mode (known from
versions pre 0.8.0 within the normal usrloc test). This option should be
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
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
will return 0 if everything was ok and 2 in case of any error (local or remote).
- -o, --sleep NUMBER
will sleep for
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
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
of processes in parallel to do the send and reply checking. Makes only sence
if a higher number for
is given in the usrloc, message or invite mode.
- -q, --search REGEXP
match replies against
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
will be used. Alternatively the remote port can be given within the sip uri of
- -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
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
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
will use only one port for sending and receiving messages. With this option
the local port for sending will be the value from the
option. In the default mode
sends from a random port and listens on the given port from the
With this option
will not be able to receive replies from servers with asymmetric signaling
(and broken rport implementation) like the Cisco proxy. If you run
as root and with raw socket support (check the output from the
option) then this option is not required because in this case
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
will be set to the length of the request.
- -T, --traceroute-mode
This activates the traceroute mode. This mode works like the well known
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
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
as username value for the authentication (different account and
- -U, --usrloc-mode
This activates the usrloc mode. Without the
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
option. An user name is mandatory for this mode in the
parameter. The number starting from the
parameter to the
parameter is appended the user name. If the
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
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
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.
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).
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
to the server. And 0 if there was no error at all.
responsibly. Running it in any of the stress modes puts
substantial burden on network and server under test.
- sipsak -vv -s sip:firstname.lastname@example.org
displays received replies.
- sipsak -T -s sip:email@example.com
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.
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>