1SIPSAK(1) User Manuals SIPSAK(1)
2
6 sipsak - a utility for various tests on sip servers and user agents
7
9 sipsak [-dFGhiILnNMRSTUVvwz] [-a PASSWORD ] [-b NUMBER ] [-c SIPURI ]
10 [-C SIPURI ] [-D NUMBER ] [-e NUMBER ] [-E STRING ] [-f FILE ] [-g
11 STRING ] [-H HOSTNAME ] [-j STRING ] [-J STRING ] [-l PORT ] [-m NUMBER
12 ] [-o NUMBER ] [-p HOSTNAME ] [-P NUMBER ] [-q REGEXP ] [-r PORT ] [-t
13 NUMBER ] [-u STRING ] [-W NUMBER ] [-x NUMBER ] -s SIPURI
14
17 sipsak is a SIP stress and diagnostics utility. It sends SIP requests
18 to the server within the sip-uri and examines received responses. It
19 runs in one of the following modes:
20 - default mode
22 A SIP message is sent to destination in sip-uri and reply status
23 is displayed. The request is either taken from filename or gen‐
24 erated as a new OPTIONS message.
25 - traceroute mode (-T)
27 This mode is useful for learning request's path. It operates
28 similarly to IP-layer utility traceroute(8).
29 - message mode (-M)
31 Sends a short message (similar to SMS from the mobile phones) to
32 a given target. With the option -B the content of the MESSAGE
33 can be set. Useful might be the options -c and -O in this mode.
34 - usrloc mode (-U)
36 Stress mode for SIP registrar. sipsak keeps registering to a
37 SIP server at high pace. Additionally the registrar can be
38 stressed with the -I or the -M option. If -I and -M are omitted
39 sipsak can be used to register any given contact (with the -C
40 option) for an account at a registrar and to query the current
41 bindings for an account at a registrar.
42 - randtrash mode (-R)
44 Parser torture mode. sipsak keeps sending randomly corrupted
45 messages to torture a SIP server's parser.
46 - flood mode (-F)
48 Stress mode for SIP servers. sipsak keeps sending requests to a
49 SIP server at high pace.
50 If c-ares (http://daniel.haxx.se/projects/c-ares/) support is compiled
53 into the sipsak binary, then first a SRV lookup for _sip._tcp.hostname
54 is made. If that fails a SRV lookup for _sip._udp.hostname is made. And
55 if this lookup fails a normal A lookup is made. If a port was given in
56 the target URI the SRV lookup is omitted. Failover, load distribution
57 and other transports are not supported yet.
58
61 -a, --password PASSWORD
62 With the given PASSWORD an authentication will be tried on
63 received '401 Unauthorized'. Authorization will be tried on
64 time. If this option is omitted an authorization with an empty
65 password ("") will be tried. If the password is equal to - the
66 password will be read from the standard input (e.g. the key‐
67 board). This prevents other users on the same host from seeing
68 the password in the process list. NOTE: the password still can
69 be read from the memory if other users have access to it.
70 -A, --timing
73 prints only the timing values of the test run if verbosity is
74 zero because no -v was given. If one or more -v were given this
75 option will be ignored.
76 -b, --appendix-begin NUMBER
79 The starting number which is appended to the user name in the
80 usrloc mode. This NUMBER is increased until it reaches the
81 value given by the -e parameter. If omitted the starting number
82 will be one.
83 -B, --message-body STRING
86 The given STRING will be used as the body for outgoing MESSAGE
87 requests.
88 -c, --from SIPURI
91 The given SIPURI will be used in the From header if sipsak runs
92 in the message mode (initiated with the -M option). This is
93 helpful to present the receiver of a MESSAGE a meaningful and
94 usable address to where maybe even responses can be sent.
95 -C, --contact SIPURI
98 This is the content of the Contact header in the usrloc mode.
99 This allows to insert forwards like for mail. For example you
100 can insert the uri of your first SIP account at a second
101 account, thus all calls to the second account will be forwarded
102 to the first account. As the argument to this option will not
103 be enclosed in brackets you can give also multiple contacts in
104 the raw format as comma separated list. The special words empty
105 or none will result in no contact header in the REGISTER request
106 and thus the server should answer with the current bindings for
107 the account at the registrar. The special words * or star will
108 result in Contact header containing just a star, e.g. to remove
109 all bindings by using expires value 0 together with this Con‐
110 tact.
111 -d, --ignore-redirects
114 If this option is set all redirects will be ignored. By default
115 without this option received redirects will be respected. This
116 option is automatically activated in the randtrash mode and in
117 the flood mode.
118 -D, --timeout-factor NUMBER
121 The SIP_T1 timer is getting multiplied with the given NUMBER.
122 After receiving a provisional response for an INVITE request, or
123 when a reliable transport like TCP or TLS is used sipsak waits
124 for the resulting amount of time for a final response until it
125 gives up.
126 -e, --appendix-end NUMBER
129 The ending number which is appended to the user name in the usr‐
130 loc mode. This number is increased until it reaches this ending
131 number. In the flood mode this is the maximum number of mes‐
132 sages which will be sent. If omitted the default value is 2^31
133 (2147483647) in the flood mode.
134 -E, --transport STRING
137 The value of STRING will be used as IP transport for sending and
138 receiving requests and responses. This option overwrites any
139 result from the URI evaluation and SRV lookup. Currently only
140 'udp' and 'tcp' are accepted as value for STRING.
141 -f, --filename FILE
144 The content of FILE will be read in in binary mode and will be
145 used as replacement for the alternatively created sip message.
146 This can used in the default mode to make other requests than
147 OPTIONS requests (e.g. INVITE). By default missing carriage
148 returns in front of line feeds will be inserted (use -L to de-
149 activate this function). If the filename is equal to - the file
150 is read from standard input, e.g. from the keyboard or a pipe.
151 Please note that the manipulation functions (e.g. inserting Via
152 header) are only tested with RFC conform requests. Additionally
153 special strings within the file can be replaced with some local
154 or given values (see -g and -G for details).
155 -F, --flood-mode
158 This option activates the flood mode. In this mode OPTIONS
159 requests with increasing CSeq numbers are sent to the server.
160 Replies are ignored -- source port 9 (discard) of localhost is
161 advertised in topmost Via.
162 -h, --help
165 Prints out a simple usage help message. If the long option
166 --help is available it will print out a help message with the
167 available long options.
168 -g, --replace-string STRING
171 Activates the replacement of $replace$ within the request (usu‐
172 ally read in from a file) with the STRING. Alternatively you
173 can also specify a list of attributes and values. This list has
174 to start and end with a non alpha-numeric character. The same
175 character has to be used also as separator between the attribute
176 and the value and between new further attribute value pairs. The
177 string "$attribute$" will be replaced with the value string in
178 the message.
179 -G, --replace
182 Activates the automatic replacement of the following variables
183 in the request (usually read in from a file): $dsthost$ will be
184 replaced with the host or domainname which is given by the -s
185 parameter. $srchost$ will be replaced by the hostname of the
186 local machine. $port$ will be replaced by the local listening
187 port of sipsak. $user$ will be replaced by the username which
188 is given by the -s parameter.
189 -H, --hostname HOSTNAME
192 Overwrites the automatic detection of the hostname with the
193 given parameter. Warning: use this with caution (preferable
194 only if the automatic detection fails).
195 -i, --no-via
198 Deactivates the insertion of the Via line of the localhost.
199 Warning: this probably disables the receiving of the responses
200 from the server.
201 -I, --invite-mode
204 Activates the Invites cycles within the usrloc mode. It should
205 be combined with -U. In this combination sipsak first registers
206 a user, and then simulates an invitation to this user. First an
207 Invite is sent, this is replied with 200 OK and finally an ACK
208 is sent. This option can also be used without -U , but you
209 should be sure to NOT invite real UAs with this option. In the
210 case of a missing -U the -l PORT is required because only if you
211 made a -U run with a fixed local port before, a run with -I and
212 the same fixed local port can be successful. Warning: sipsak is
213 no real UA and invitations to real UAs can result in unexpected
214 behaviour.
215 -j, --headers STRING
218 The string will be added as one or more additional headers to
219 the request. The string "\n" (note: two characters) will be
220 replaced with CRLF and thus result in two separate headers. That
221 way more then one header can be added.
222 -J, --autohash STRING
225 The string will be used as the H(A1) input to the digest authen‐
226 tication response calculation. Thus no password from the -a
227 option is required if this option is provided. The given string
228 is expected to be a hex string with the length of the used hash
229 function.
230 -k, --local-ip STRING
233 The local ip address to be used
234 -l, --local-port PORT
237 The receiving UDP socket will use the local network port. Use‐
238 ful if a file is given by -f which contains a correct Via line.
239 Check the -S option for details how sipsak sends and receives
240 messages.
241 -L, --no-crlf
244 De-activates the insertion of carriage returns (\r) before all
245 line feeds (\n) (which is not already proceeded by carriage
246 return) if the input is coming from a file ( -f ). Without this
247 option also an empty line will be appended to the request if
248 required.
249 -m, --max-forwards NUMBER
252 This sets the value of the Max-Forward header field. If omitted
253 no Max-Forward field will be inserted. If omitted in the tracer‐
254 oute mode number will be 255.
255 -M, --message-mode
258 This activates the Messages cycles within the usrloc mode (known
259 from sipsak versions pre 0.8.0 within the normal usrloc test).
260 This option should be combined with -U so that a successful reg‐
261 istration will be tested with a test message to the user and
262 replied with 200 OK. But this option can also be used without
263 the -U option. Warning: using without -U can cause unexpected
264 behavior.
265 -n, --numeric
268 Instead of the full qualified domain name in the Via line the IP
269 of the local host will be used. This option is now on by
270 default.
271 -N, --nagios-code
274 Use Nagios compliant return codes instead of the normal sipsak
275 ones. This means sipsak will return 0 if everything was ok and 2
276 in case of any error (local or remote).
277 -o, --sleep NUMBER
280 sipsak will sleep for NUMBER ms before it starts the next cycle
281 in the usrloc mode. This will slow down the whole test process
282 to be more realistic. Each cycle will be still completed as fast
283 as possible, but the whole test will be slowed down.
284 -O, --disposition STRING
287 The given STRING will be used as the content for the Content-
288 Disposition header. Without this option there will be no Con‐
289 tent-Disposition header in the request.
290 -p, --outbound-proxy HOSTNAME[:PORT]
293 the address of the hostname is the target where the request will
294 be sent to (outgoing proxy). Use this if the destination host is
295 different from the host part of the request uri. The hostname is
296 resolved via DNS SRV if supported (see description for SRV
297 resolving) and no port is given.
298 -P, --processes NUMBER
301 Start NUMBER of processes in parallel to do the send and reply
302 checking. Only makes sense if a higher number for -e is given in
303 the usrloc, message or invite mode.
304 -q, --search REGEXP
307 match replies against REGEXP and return false if no match
308 occurred. Useful for example to detect server name in Server
309 header field.
310 -r, --remote-port PORT
313 Instead of the default sip port 5060 the PORT will be used.
314 Alternatively the remote port can be given within the sip uri of
315 the -s parameter.
316 -R, --random-mode
319 This activates the randtrash mode. In this mode OPTIONS requests
320 will be sent to server with increasing numbers of randomly
321 crashed characters within this request. The position within the
322 request and the replacing character are randomly chosen. Any
323 other response than Bad request (4xx) will stop this mode. Also
324 three unresponded sends will stop this mode. With the -t parame‐
325 ter the maximum of trashed characters can be given.
326 -s, --sip-uri SIPURI
329 This mandatory option sets the destination of the request. It
330 depends on the mode if only the server name or also a user name
331 is mandatory. Example for a full SIPURI : sip:test@foo.bar:123
332 See the note in the description part about SRV lookups for
333 details how the hostname of this URI is converted into an IP and
334 port.
335 -S, --symmetric
338 With this option sipsak will use only one port for sending and
339 receiving messages. With this option the local port for sending
340 will be the value from the -l option. In the default mode sipsak
341 sends from a random port and listens on the given port from the
342 -l option. Note: With this option sipsak will not be able to
343 receive replies from servers with asymmetric signaling (and bro‐
344 ken rport implementation) like the Cisco proxy. If you run sip‐
345 sak as root and with raw socket support (check the output from
346 the -V option) then this option is not required because in this
347 case sipsak already uses only one port for sending and receiving
348 messages.
349 -t, --trash-chars NUMBER
352 This parameter specifies the maximum of trashed characters in
353 the randtrash mode. If omitted NUMBER will be set to the length
354 of the request.
355 -T, --traceroute-mode
358 This activates the traceroute mode. This mode works like the
359 well known traceroute(8) command expect that not the number of
360 network hops is counted rather the number of servers on the way
361 to the destination user. Also the round trip time of each
362 request is printed out, but due to a limitation within the sip
363 protocol the identity (IP or name) can only be determined and
364 printed out if the response from the server contains a warning
365 header field. In this mode on each outgoing request the value of
366 the Max-Forwards header field is increased, starting with one.
367 The maximum of the Max-Forwards header will be 255 if no other
368 value is given by the -m parameter. Any other response than 483
369 or 1xx is treated as a final response and will terminate this
370 mode.
371 -u, --auth-username STRING
374 Use the given STRING as username value for the authentication
375 (different account and authentication username).
376 -U, --usrloc-mode
379 This activates the usrloc mode. Without the -I or the -M option,
380 this only registers users at a registrar. With one of the above
381 options the previous registered user will also be probed, wether
382 with a simulated call flow (invite, 200, ack) or with an instant
383 message (message, 200). One password for all users accounts
384 within the usrloc test can be given with the -a option. A user
385 name is mandatory for this mode in the -s parameter. The number
386 starting from the -b parameter to the -e parameter is appended
387 the user name. If the -b and the -e parameter are omitted, only
388 one run with the given username, but without append number to
389 the usernames is done.
390 -v, --verbose
393 This parameter increases the output verbosity. No -v means
394 nearly no output except in traceroute and error messages. The
395 maximum of three v's prints out the content of all packets
396 received and sent.
397 -V, --version
400 Prints out the name and version number of sipsak and the options
401 which were compiled into the binary.
402 -w, --extract-ip
405 Activates the extraction of the IP or hostname from the Warning
406 header field.
407 -W, --nagios-warn NUMBER
410 Return Nagios warn exit code (1) if the number of retransmis‐
411 sions before success was above the given number.
412 -x, --expires NUMBER
415 Sets the value of the Expires header to the given number.
416 -z, --remove-bindings
419 Activates the randomly removing of old bindings in the usrloc
420 mode. How many percent of the bindings will be removed, is
421 determined by the USRLOC_REMOVE_PERCENT define within the code
422 (set it before compilation). Multiple removing of bindings is
423 possible, and cannot be prevented.
424 -Z, --timer-t1
427 Sets the amount of milliseconds for the SIP timer T1. It deter‐
428 mines the length of the gaps between two retransmissions of a
429 request on a unreliable transport. Default value is 500 if not
430 changed via the configure option --enable-timeout.
431
434 The return value 0 means that a 200 was received. 1 means something
435 else than 1xx or 2xx was received. 2 will be returned on local errors
436 like non resolvable names or wrong options combination. 3 will be
437 returned on remote errors like socket errors (e.g. icmp error), redi‐
438 rects without a contact header or simply no answer (timeout).
439 If the -N option was given the return code will be 2 in case of any
441 (local or remote) error. 1 in case there have been retransmissions from
442 sipsak to the server. And 0 if there was no error at all.
443
445 Use sipsak responsibly. Running it in any of the stress modes puts sub‐
446 stantial burden on network and server under test.
447
450 sipsak -vv -s sip:nobody@foo.bar
451 displays received replies.
452 sipsak -T -s sip:nobody@foo.bar
454 traces SIP path to nobody.
455 sipsak -U -C sip:me@home -x 3600 -a password -s sip:myself@company
457 inserts forwarding from work to home for one hour.
458 sipsak -f bye.sip -g '!FTAG!345.af23!TTAG!1208.12!' -s sip:myproxy
460 reads the file bye.sip, replaces $FTAG$ with 345.af23 and $TTAG$
461 with 1208.12 and finally send this message to myproxy
462
465 Many servers may decide NOT to include SIP "Warning" header fields.
466 Unfortunately, this makes displaying IP addresses of SIP servers in
467 traceroute mode impossible.
468 IPv6 is not supported.
470 Missing support for the Record-Route and Route header.
472
475 sipsak is only tested against the SIP Express Router (ser) though their
476 could be various bugs. Please feel free to mail them to the author.
477
481 Nils Ohlmeier <nils at sipsak dot org>
482
484 traceroute(8)
485Linux JULY 2002 - SEPTEMBER 2005 SIPSAK(1)