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