File: sipsak.1

package info (click to toggle)
sipsak 0.9.6+git20170713-1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 396 kB
  • ctags: 466
  • sloc: ansic: 5,910; makefile: 78
file content (588 lines) | stat: -rw-r--r-- 18,774 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
.\" Process this file with
.\" groff -man -Tascii sipsak.1
.\"
.TH SIPSAK 1 "JULY 2002 - SEPTEMBER 2005" Linux "User Manuals"
.SH NAME
sipsak \- a utility for various tests on sip servers and user agents
.SH SYNOPSIS
.B sipsak [-dFGhiILnNMRSTUVvwz] [-a
.I PASSWORD
.B ] [-b
.I NUMBER 
.B ] [-c
.I SIPURI
.B ] [-C
.I SIPURI
.B ] [-D
.I NUMBER
.B ] [-e 
.I NUMBER 
.B ] [-E
.I STRING
.B ] [-f 
.I FILE 
.B ] [-g
.I STRING
.B ] [-H
.I HOSTNAME
.B ] [-j
.I STRING
.B ] [-J
.I STRING
.B ] [-l 
.I PORT
.B ] [-m 
.I NUMBER
.B ] [-o 
.I NUMBER
.B ] [-p
.I HOSTNAME
.B ] [-P
.I NUMBER
.B ] [-q
.I REGEXP
.B ] [-r 
.I PORT
.B ] [-t 
.I NUMBER 
.B ] [-u
.I STRING
.B ] [-W
.I NUMBER
.B ] [-x 
.I NUMBER
.B ] -s 
.I SIPURI

.SH DESCRIPTION
.B sipsak
is a SIP stress and diagnostics utility. 
It sends SIP requests to the server within the 
.BR sip-uri 
and examines received responses.
It runs in one of the following modes:
.IP "- default mode"
A SIP message is sent to destination in 
.BR sip-uri
and reply status is displayed. 
The request is either taken from
.BR filename
or generated as a new OPTIONS message.  
.IP "- traceroute mode (-T)"
This mode is useful for learning request's path. It
operates similarly to IP-layer utility
.BR traceroute (8).
.IP "- message mode (-M)"
Sends a short message (similar to SMS from the mobile phones) to a given target. With the option
.BR -B
the content of the MESSAGE can be set. Useful might be the options
.BR -c
and
.BR -O
in this mode.
.IP "- usrloc mode (-U)"
Stress mode for SIP registrar. 
.B sipsak
keeps registering to a SIP server at high pace. Additionally the registrar
can be stressed with the 
.BR -I
or the
.BR -M
option.
If
.BR -I
and
.BR -M
are omitted
.B sipsak
can be used to register any given contact (with the
.BR -C
option) for an account at a registrar and to query the current bindings for
an account at a registrar.
.IP "- randtrash mode (-R)"
Parser torture mode. 
.B sipsak 
keeps sending randomly corrupted messages to torture a SIP server's
parser.
.IP "- flood mode (-F)"
Stress mode for SIP servers.
.B sipsak 
keeps sending requests to a SIP server at high pace.

.PP
If libruli (http://www.nongnu.org/ruli/) or c-ares 
(http://daniel.haxx.se/projects/c-ares/) support is compiled into the
.B sipsak
binary, then first a SRV lookup for _sip._tcp.hostname is made. If that
fails 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.

.SH OPTIONS
.IP "-a, --password PASSWORD"
With the given 
.I PASSWORD
an authentication will be tried on received '401 Unauthorized'. Authorization
will be tried on time. If this option is omitted an authorization with an
empty password ("") will be tried. If the password is equal to 
.I -
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
in the process list.
.B NOTE:
the password still can be read from the memory if other users have access to
it.

.IP "-A, --timing"
prints only the timing values of the test run if verbosity is zero because no 
.BR -v 
was given. If one or more 
.BR -v 
were given this option will be ignored.

.IP "-b, --apendix-begin NUMBER"
The starting number which is appended to the user name in the usrloc mode.
This 
.I NUMBER
is increased until it reaches the value given by the
.BR -e
parameter. If omitted the starting number will be one.

.IP "-B, --message-body STRING"
The given 
.I STRING
will be used as the body for outgoing MESSAGE requests.

.IP "-c, --from SIPURI"
The given
.I SIPURI
will be used in the From header if
.B sipsak
runs in the message mode (initiated with the
.BR -M
option). This is helpful to present the receiver of a MESSAGE a meaningful
and usable address to where maybe even responses can be sent.

.IP "-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 separated list.
The special words 
.B empty
or
.B 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.
The special words 
.B *
or
.B star
will result in Contact header containing just a star, e.g. to remove all
bindings by using expires value 0 together with this Contact.

.IP "-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 automatically 
activated in the randtrash mode and in the flood mode.

.IP "-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
.B sipsak
waits for the resulting amount of time for a final response until it gives up.

.IP "-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
.I number.
In the flood mode this is the maximum number of messages which will be sent. 
If omitted the default value is 2^31 (2147483647) in the flood mode.

.IP "-E, --transport STRING"
The value of
.I 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
.I STRING.

.IP "-f, --filename FILE"
The content of 
.I 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
.BR -L
to de-activate this function). If the filename is equal to 
.I -
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. Additionally special strings
within the file can be replaced with some local or given values (see 
.BR -g
and
.BR -G
for details).

.IP "-F, --flood-mode"
This option 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.

.IP "-h, --help"
Prints out a simple usage help message. If the long option
.BR --help
is available it will print out a help message with the available long options.

.IP "-g, --replace-string STRING"
Activates the replacement of $replace$ within the request (usually read 
in from a file) with the
.I STRING.
Alternatively you can also specify a list of attributes and values.
This list has to start and end with a non alpha-numeric character. The
same character has to be used also as separator 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.

.IP "-G, --replace"
Activates the automatic replacement of the following variables in the
request (usually read in from a file):
.B $dsthost$ 
will be replaced with the host or domainname which is given
by the
.B -s
parameter.
.B $srchost$
will be replaced by the hostname of the local machine.
.B $port$
will be replaced by the local listening port of 
.B sipsak.
.B $user$
will be replaced by the username which is given by the
.B -s
parameter.

.IP "-H, --hostname HOSTNAME"
Overwrites the automatic detection of the hostname with the given parameter.
.B Warning: 
use this with caution (preferable only if the automatic detection fails).

.IP "-i, --no-via"
Deactivates the insertion of the Via line of the localhost. 
.B Warning: 
this probably disables the receiving of the responses from the server.

.IP "-I, --invite-mode"
Activates the Invites cycles within the usrloc mode. It should be combined
with
.BR -U.
In this combination 
.B sipsak 
first registers a user, and then simulates an 
invitation to this user. First an Invite is sent, this is replied with 200 OK
and finally an ACK is sent. This option can also be used without
.BR -U
, but you should be sure to NOT invite real UAs with this option. In the case
of a missing 
.BR -U
the
.BR "-l PORT"
is required because only if you made a 
.BR -U 
run with a fixed local port before, a run with
.BR -I
and the same fixed local port can be successful.
.B Warning: sipsak 
is no real UA and invitations to real UAs can result in unexpected 
behaviour.

.IP "-j, --headers STRING"
The
.BR 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 separate headers. That way more then one header can be added.

.IP "-J, --autohash STRING"
The
.BR string
will be used as the H(A1) input to the digest authentication response
calculation. Thus no password from the 
.BR -a
option is required if this option is provided. The given
.BR string
is expected to be a hex string with the length of the used hash function.

.IP "-k, --local-ip STRING"
The local ip address to be used

.IP "-l, --local-port PORT"
The receiving UDP socket will use the local network 
.I port.
Useful if a file is given by 
.BR -f
which contains a correct Via line. Check the 
.BR -S
option for details how sipsak sends and receives messages.

.IP "-L, --no-crlf"
De-activates the insertion of carriage returns (\\r) before all line feeds
(\\n) (which is not already proceeded by carraige return) if the input
is coming from a file (
.BR -f
). Without this option also an empty line will be appended to the request
if required.

.IP "-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 
.BR number
will be 255.

.IP "-M, --message-mode"
This activates the Messages cycles within the usrloc mode (known from 
.B sipsak
versions pre 0.8.0 within the normal usrloc test). This option should be
combined with
.BR -U
so that a successful 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
.BR -U
option.
.B Warning:
using without 
.BR -U
can cause unexpected behaivor.

.IP "-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.

.IP "-N, --nagios-code"
Use Nagios comliant return codes instead of the normal sipsak ones. This means
.B sipsak 
will return 0 if everything was ok and 2 in case of any error (local or remote).

.IP "-o, --sleep NUMBER"
.B sipsak 
will sleep for 
.BR 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.

.IP "-O, --disposition STRING"
The given
.BR 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.

.IP "-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 from 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.

.IP "-P, --processes NUMBER"
Start
.BR NUMBER
of processes in parallel to do the send and reply checking. Only makes sense
if a higher number for 
.BR -e
is given in the usrloc, message or invite mode.

.IP "-q, --search REGEXP"
match replies against 
.BR REGEXP
and return false if no match
occurred. Useful for example to detect server name in Server header field.

.IP "-r, --remote-port PORT"
Instead of the default sip port 5060 the 
.BR PORT
will be used. Alternatively the remote port can be given within the sip uri of
the 
.BR -s
parameter.

.IP "-R, --random-mode"
This activates the randtrash mode. In this mode OPTIONS requests will be sent
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 
.BR -t
parameter the maximum of trashed characters can be given.

.IP "-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 a user name is mandatory. Example for a
full 
.BR SIPURI
: 
.I 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.

.IP "-S, --symmetric"
With this option
.B 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
.BR -l
option. In the default mode
.B sipsak
sends from a random port and listens on the given port from the
.BR -l
option.
.B Note:
With this option
.B sipsak
will not be able to receive replies from servers with asymmetric signaling
(and broken rport implementation) like the Cisco proxy. If you run
.B sipsak
as root and with raw socket support (check the output from the
.BR -V
option) then this option is not required because in this case
.B sipsak
already uses only one port for sending and receiving messages.

.IP "-t, --trash-chars NUMBER"
This parameter specifies the maximum of trashed characters in the randtrash 
mode. If omitted 
.BR NUMBER
will be set to the length of the request.

.IP "-T, --traceroute-mode"
This activates the traceroute mode. This mode works like the well known
.BR traceroute(8) 
command expect that not the number of network hops is counted rather
the number of servers 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 be 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 be 255
if no other value is given by the 
.BR -m
parameter. Any other response than 483 or 1xx is treated as a final response
and will terminate this mode.

.IP "-u, --auth-username STRING"
Use the given
.BR STRING
as username value for the authentication (different account and 
authentication username).

.IP "-U, --usrloc-mode"
This activates the usrloc mode. Without the 
.BR -I
or the
.BR -M
option, this only registers users at a registrar. With one of the above
options the previous registered user will also be probed, wether 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 
.BR -a
option. A user name is mandatory for this mode in the 
.BR -s
parameter. The number starting from the 
.BR -b
parameter to the 
.BR -e
parameter is appended the user name. If the 
.BR -b
and the
.BR -e
parameter are omitted, only one run with the given username, but without 
append number to the usernames is done.

.IP "-v, --verbose"
This parameter increases the output verbosity. No
.BR -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.

.IP "-V, --version"
Prints out the name and version number of 
.B sipsak
and the options which were compiled into the binary.

.IP "-w, --extract-ip"
Activates the extraction of the IP or hostname from the Warning header field.

.IP "-W, --nagios-warn NUMBER"
Return Nagios warn exit code (1) if the number of retransmissions before
success was above the given number.

.IP "-x, --expires NUMBER"
Sets the value of the Expires header to the given number.

.IP "-z, --remove-bindings"
Activates the randomly removing of old bindings in the usrloc mode. How many 
percent 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.

.IP "-Z, --timer-t1"
Sets the amount of milliseconds for the SIP timer T1. It determines the
length of the gaps between two retransmissions of a request on a unreliable
transport. Default value is 500 if not changed via the configure option
--enable-timeout.

.SH RETURN VALUES
The return value 0 means that a 200 was received. 1 means something else 
than 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 
.BR -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
.B sipsak
to the server. And 0 if there was no error at all.
.SH CAUTION
Use
.B sipsak
responsibly. Running it in any of the stress modes puts
substantial burden on network and server under test.

.SH EXAMPLES
.IP "sipsak -vv -s sip:nobody@foo.bar" 
displays received replies.
.IP "sipsak -T -s sip:nobody@foo.bar" 
traces SIP path to nobody.
.IP "sipsak -U -C sip:me@home -x 3600 -a password -s sip:myself@company"
inserts forwarding from work to home for one hour.
.IP "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

.SH 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.

.SH 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.


.SH AUTHOR
Nils Ohlmeier <nils at sipsak dot org>
.SH "SEE ALSO"
.BR traceroute (8)