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 ] [-l PORT ] [-m NUMBER ] [-o NUMBER ] [-p HOST‐
12 NAME ] [-P NUMBER ] [-q REGEXP ] [-r PORT ] [-t NUMBER ] [-u STRING ]
13 [-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. Usefull 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. Additionaly 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/) support is compiled into the
53 sipsak binary, then first a SRV lookup for _sip._udp.hostname is made.
54 And if this lookup fails a normal A lookup is made. If a port was given
55 in the target URI the SRV lookup is omitted. Failover, load distribu‐
56 tion and other transports are not supported yet.
57
60 -a, --password PASSWORD
61 With the given PASSWORD an authentication will be tryed on
62 received '401 Unauthorized'. Authorization will be tryed on
63 time. If this option is omitted an authorization with an empty
64 password ("") will be tryed. If the password is equal to - the
65 password will be read from the standard input (e.g. the key‐
66 board). This prevents other users on the same host from seeing
67 the password the password in the process list. NOTE: the pass‐
68 word still can be read from the memory if other users have
69 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, --apendix-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 helpfull to present the receiver of a MESSAGE a meaningfull and
94 usable address to where maybe even responses can be send.
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 seperated 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.
108 -d, --ignore-redirects
111 If this option is set all redirects will be ignored. By default
112 without this option received redirects will be respected. This
113 option is automaticly activated in the randtrash mode and in the
114 flood mode.
115 -D, --timeout-factor NUMBER
118 The SIP_T1 timer is getting multiplied with the given NUMBER.
119 After receiving a provisional response for an INVITE request, or
120 when a reliable transport like TCP or TLS is used sipsak waits
121 for the resulting amount of time for a final response until it
122 gives up.
123 -e, --appendix-end NUMBER
126 The ending number which is appended to the user name in the usr‐
127 loc mode. This number is increased until it reaches this ending
128 number. In the flood mode this is the maximum number of mes‐
129 sages which will be send. If omitted the default value is 2^31
130 (2147483647) in the flood mode.
131 -E, --transport STRING
134 The value of STRING will be used as IP transport for sending and
135 receiving requests and responses. This option overwrites any
136 result from the URI evaluation and SRV lookup. Currently only
137 'udp' and 'tcp' are accepted as value for STRING.
138 -f, --filename FILE
141 The content of FILE will be read in in binary mode and will be
142 used as replacement for the alternatively created sip message.
143 This can used in the default mode to make other requests than
144 OPTIONS requests (e.g. INVITE). By default missing carriage
145 returns in front of line feeds will be inserted (use -L to de-
146 activate this function). If the filename is equal to - the file
147 is read from standard input, e.g. from the keyboard or a pipe.
148 Please note that the manipulation functions (e.g. inserting Via
149 header) are only tested with RFC conform requests. Additionaly
150 special strings within the file can be replaced with some local
151 or given values (see -g and -G for details).
152 -F, --flood-mode
155 This options activates the flood mode. In this mode OPTIONS
156 requests with increasing CSeq numbers are sent to the server.
157 Replies are ignored -- source port 9 (discard) of localhost is
158 advertised in topmost Via.
159 -h, --help
162 Prints out a simple usage help message. If the long option
163 --help is available it will print out a help message with the
164 available long options.
165 -g, --replace-string STRING
168 Activates the replacement of $replace$ within the request (usu‐
169 aly read in from a file) with the STRING. Alternatively you can
170 also specify a list of attribute and values. This list has to
171 start and end with a non alpha-numeric character. The same char‐
172 acter has to be used also as seperator between the attribute and
173 the value and between new further attribute value pairs. The
174 string "$attribute$" will be replaced with the value string in
175 the message.
176 -G, --replace
179 Activates the automatic replacement of the following variables
180 in the request (usualy read in from a file): $dsthost$ will be
181 replaced by with the host or domainname which is given by the -s
182 parameter. $srchost$ will be replaced by the hostname of the
183 local machine. $port$ will be replaced by the local listening
184 port of sipsak. $user$ will be replaced by the username which
185 is given by the -s parameter.
186 -H, --hostname HOSTNAME
189 Overwrites the automatic detection of the hostname with the
190 given parameter. Warning: use this with caution (preferable
191 only if the automatic detection fails).
192 -i, --no-via
195 Deactivates the insertion of the Via line of the localhost.
196 Warning: this probably disables the receiving of the responses
197 from the server.
198 -I, --invite-mode
201 Activates the Invites cycles within the usrloc mode. It should
202 be combined with -U. In this combination sipsak first regis‐
203 teres a user, and then simulates an invitation to this user.
204 First an Invite is sent, this is replied with 200 OK and finaly
205 an ACK is sent. This option can also be used without -U , but
206 you should be sure to NOT invite real UAs with this option. In
207 the case of a missing -U the -l PORT is required because only if
208 you made a -U run with a fixed local port before, a run with -I
209 and the same fixed local port can be successful. Warning: sip‐
210 sak is no real UA and invitations to real UAs can result in
211 unexpected behaivior.
212 -j, --headers STRING
215 The string will be added as one or more additional headers to
216 the request. The string "\n" (note: two characters) will be
217 replaced with CRLF and thus result in two seperate headers.
218 That way more then one header can be added.
219 -l, --local-port PORT
222 The receiving UDP socket will use the local network port. Use‐
223 ful if a file is given by -f which contains a correct Via line.
224 Check the -S option for details how sipsak sends and receives
225 messages.
226 -L, --no-crlf
229 De-activates the insertion of carriage returns (\r) before all
230 line feeds (\n) (which is not allready proceeded by carraige
231 return) if the input is comming from a file ( -f ). Without this
232 option also an empty line will be appended to the request if
233 required.
234 -m, --max-forwards NUMBER
237 This sets the value of the Max-Forward header field. If omitted
238 no Max-Forward field will be inserted. If omitted in the tracer‐
239 oute mode number will be 255.
240 -M, --message-mode
243 This activates the Messages cycles within the usrloc mode (known
244 from sipsak versions pre 0.8.0 within the normal usrloc test).
245 This option should be combined with -U so that a succesful reg‐
246 istration will be tested with a test message to the user and
247 replied with 200 OK. But this option can also be used without
248 the -U option. Warning: using without -U can cause unexpected
249 behaivor.
250 -n, --numeric
253 Instead of the full qualified domain name in the Via line the IP
254 of the local host will be used. This option is now on by
255 default.
256 -N, --nagios-code
259 Use Nagios comliant return codes instead of the normal sipsak
260 ones. This means sipsak will return 0 if everything was ok and 2
261 in case of any error (local or remote).
262 -o, --sleep NUMBER
265 sipsak will sleep for NUMBER ms before it starts the next cycle
266 in the usrloc mode. This will slow down the whole test process
267 to be more realistic. Each cycle will be still completed as fast
268 as possible, but the whole test will be slowed down.
269 -O, --disposition STRING
272 The given STRING will be used as the content for the Content-
273 Disposition header. Without this option there will be no Con‐
274 tent-Disposition header in the request.
275 -p, --outbound-proxy HOSTNAME[:PORT]
278 the address of the hostname is the target where the request will
279 be sent to (outgoing proxy). Use this if the destination host is
280 different then the host part of the request uri. The hostname is
281 resolved via DNS SRV if supported (see description for SRV
282 resolving) and no port is given.
283 -P, --processes NUMBER
286 Start NUMBER of processes in parallel to do the send and reply
287 checking. Makes only sence if a higher number for -e is given in
288 the usrloc, message or invite mode.
289 -q, --search REGEXP
292 match replies against REGEXP and return false if no match
293 occured. Useful for example to detect server name in Server
294 header field.
295 -r, --remote-port PORT
298 Instead of the default sip port 5060 the PORT will be used.
299 Alternatively the remote port can be given within the sip uri of
300 the -s parameter.
301 -R, --random-mode
304 This activates the randtrash mode. In this mode OPTIONS requests
305 will be send to server with increasing numbers of randomly
306 crashed characters within this request. The position within the
307 request and the replacing character are randomly chosen. Any
308 other response than Bad request (4xx) will stop this mode. Also
309 three unresponded sends will stop this mode. With the -t parame‐
310 ter the maximum of trashed characters can be given.
311 -s, --sip-uri SIPURI
314 This mandatory option sets the destination of the request. It
315 depends on the mode if only the server name or also an user name
316 is mandatory. Example for a full SIPURI : sip:test@foo.bar:123
317 See the note in the description part about SRV lookups for
318 details how the hostname of this URI is converted into an IP and
319 port.
320 -S, --symmetric
323 With this option sipsak will use only one port for sending and
324 receiving messages. With this option the local port for sending
325 will be the value from the -l option. In the default mode sipsak
326 sends from a random port and listens on the given port from the
327 -l option. Note: With this option sipsak will not be able to
328 receive replies from servers with asymmetric signaling (and bro‐
329 ken rport implementation) like the Cisco proxy. If you run sip‐
330 sak as root and with raw socket support (check the output from
331 the -V option) then this option is not required because in this
332 case sipsak already uses only one port for sending and receiving
333 messages.
334 -t, --trash-chars NUMBER
337 This parameter specifies the maximum of trashed characters in
338 the randtrash mode. If omitted NUMBER will be set to the length
339 of the request.
340 -T, --traceroute-mode
343 This activates the traceroute mode. This mode works like the
344 well known traceroute(8) command expect that not the number of
345 network hops are counted rather the number of server on the way
346 to the destination user. Also the round trip time of each
347 request is printed out, but due to a limitation within the sip
348 protocol the identity (IP or name) can only determined and
349 printed out if the response from the server contains a warning
350 header field. In this mode on each outgoing request the value of
351 the Max-Forwards header field is increased, starting with one.
352 The maximum of the Max-Forwards header will 255 if no other
353 value is given by the -m parameter. Any other response than 483
354 or 1xx are treated as a final response and will terminate this
355 mode.
356 -u, --auth-username STRING
359 Use the given STRING as username value for the authentication
360 (different account and authentication username).
361 -U, --usrloc-mode
364 This activates the usrloc mode. Without the -I or the -M option,
365 this only registers users at a registrar. With one of the above
366 options the previous registered user will also be probed ether
367 with a simulated call flow (invite, 200, ack) or with an instant
368 message (message, 200). One password for all users accounts
369 within the usrloc test can be given with the -a option. An user
370 name is mandatory for this mode in the -s parameter. The number
371 starting from the -b parameter to the -e parameter is appended
372 the user name. If the -b and the -e parameter are omitted, only
373 one runs with the given username, but without append number to
374 the usernames is done.
375 -v, --verbose
378 This parameter increases the output verbosity. No -v means
379 nearly no output except in traceroute and error messages. The
380 maximum of three v's prints out the content of all packets
381 received and sent.
382 -V, --version
385 Prints out the name and version number of sipsak and the options
386 which were compiled into the binary.
387 -w, --extract-ip
390 Activates the extraction of the IP or hostname from the Warning
391 header field.
392 -W, --nagios-warn NUMBER
395 Return Nagios warn exit code (1) if the number of retransmis‐
396 sions before success was above the given number.
397 -x, --expires NUMBER
400 Sets the value of the Expires header to the given number.
401 -z, --remove-bindings
404 Activates the randomly removing of old bindings in the usrloc
405 mode. How many per cent of the bindings will be removed, is
406 determined by the USRLOC_REMOVE_PERCENT define within the code
407 (set it before compilation). Multiple removing of bindings is
408 possible, and cannot be prevented.
409
412 The return value 0 means that a 200 was received. 1 means something
413 else then 1xx or 2xx was received. 2 will be returned on local errors
414 like non resolvable names or wrong options combination. 3 will be
415 returned on remote errors like socket errors (e.g. icmp error), redi‐
416 rects without a contact header or simply no answer (timeout).
417 If the -N option was given the return code will be 2 in case of any
419 (local or remote) error. 1 in case there have been retransmissions from
420 sipsak to the server. And 0 if there was no error at all.
421
423 Use sipsak responsibly. Running it in any of the stress modes puts sub‐
424 stantial burden on network and server under test.
425
428 sipsak -vv -s sip:nobody@foo.bar
429 displays received replies.
430 sipsak -T -s sip:nobody@foo.bar
432 traces SIP path to nobody.
433 sipsak -U -C sip:me@home -x 3600 -a password -s sip:myself@company
435 inserts forwarding from work to home for one hour.
436 sipsak -f bye.sip -g '!FTAG!345.af23!TTAG!1208.12!' -s sip:myproxy
438 reads the file bye.sip, replaces $FTAG$ with 345.af23 and $TTAG$
439 with 1208.12 and finally send this message to myproxy
440
443 Many servers may decide NOT to include SIP "Warning" header fields.
444 Unfortunately, this makes displaying IP addresses of SIP servers in
445 traceroute mode impossible.
446 IPv6 is not supported.
448 Missing support for the Record-Route and Route header.
450
453 sipsak is only tested against the SIP Express Router (ser) though their
454 could be various bugs. Please feel free to mail them to the author.
455
459 Nils Ohlmeier <nils at sipsak dot org>
460
462 traceroute(8)
463Linux JULY 2002 - SEPTEMBER 2005 SIPSAK(1)