sip-tester/debian/sipp.1

.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.38.2.
.TH SIPP "1" "June 2010" "Debian GNU/Linux" "User Commands"
.SH NAME
sipp \- Session Initiation Protol (SIP) performance testing tool
.SH DESCRIPTION
Usage:
.IP
sipp remote_host[:remote_port] [options]
.IP
Available options:
.TP
\fB\-v\fR
: Display version and copyright information.
.TP
\fB\-aa\fR
: Enable automatic 200 OK answer for INFO, UPDATE and
NOTIFY messages.
.TP
\fB\-base_cseq\fR
: Start value of [cseq] for each call.
.TP
\fB\-bg\fR
: Launch SIPp in background mode.
.TP
\fB\-bind_local\fR
: Bind socket to local IP address, i.e. the local IP
address is used as the source IP address.  If SIPp runs
in server mode it will only listen on the local IP
address instead of all IP addresses.
.TP
\fB\-buff_size\fR
: Set the send and receive buffer size.
.TP
\fB\-cid_str\fR
: Call ID string (default %u\-%p@%s).  %u=call_number,
%s=ip_address, %p=process_number, %%=% (in any order).
.TP
\fB\-ci\fR
: Set the local control IP address
.TP
\fB\-cp\fR
: Set the local control port number. Default is 8888.
.TP
\fB\-d\fR
: Controls the length of calls. More precisely, this
controls the duration of 'pause' instructions in the
scenario, if they do not have a 'milliseconds' section.
Default value is 0 and default unit is milliseconds.
.TP
\fB\-deadcall_wait\fR
: How long the Call\-ID and final status of calls should be
kept to improve message and error logs (default unit is
ms).
.TP
\fB\-default_behaviors\fR: Set the default behaviors that SIPp will use.
Possbile
values are:
\- all     Use all default behaviors
\- none    Use no default behaviors
\- bye     Send byes for aborted calls
\- abortunexp      Abort calls on unexpected messages
\- pingreply       Reply to ping requests
If a behavior is prefaced with a \-, then it is turned
off.  Example: all,\-bye
.TP
\fB\-f\fR
: Set the statistics report frequency on screen. Default is
1 and default unit is seconds.
.TP
\fB\-fd\fR
: Set the statistics dump log report frequency. Default is
60 and default unit is seconds.
.TP
\fB\-i\fR
: Set the local IP address for 'Contact:','Via:', and
\&'From:' headers. Default is primary host IP address.
.TP
\fB\-inf\fR
: Inject values from an external CSV file during calls into
the scenarios.
First line of this file say whether the data is to be
read in sequence (SEQUENTIAL), random (RANDOM), or user
(USER) order.
Each line corresponds to one call and has one or more
\&';' delimited data fields. Those fields can be referred
as [field0], [field1], ... in the xml scenario file.
Several CSV files can be used simultaneously (syntax:
\fB\-inf\fR f1.csv \fB\-inf\fR f2.csv ...)
.TP
\fB\-infindex\fR
: file field
Create an index of file using field.  For example \fB\-inf\fR
users.csv \fB\-infindex\fR users.csv 0 creates an index on the
first key.
.TP
\fB\-ip_field\fR
: Set which field from the injection file contains the IP
address from which the client will send its messages.
If this option is omitted and the '\-t ui' option is
present, then field 0 is assumed.
Use this option together with '\-t ui'
.TP
\fB\-l\fR
: Set the maximum number of simultaneous calls. Once this
limit is reached, traffic is decreased until the number
of open calls goes down. Default:
.IP
(3 * call_duration (s) * rate).
.TP
\fB\-lost\fR
: Set the number of packets to lose by default (scenario
specifications override this value).
.TP
\fB\-m\fR
: Stop the test and exit when 'calls' calls are processed
.TP
\fB\-mi\fR
: Set the local media IP address
.TP
\fB\-master\fR
: 3pcc extended mode: indicates the master number
.TP
\fB\-max_recv_loops\fR
: Set the maximum number of messages received read per
cycle. Increase this value for high traffic level.  The
default value is 1000.
.TP
\fB\-max_sched_loops\fR : Set the maximum number of calsl run per event loop.
Increase this value for high traffic level.  The default
value is 1000.
.TP
\fB\-max_reconnect\fR
: Set the the maximum number of reconnection.
.TP
\fB\-max_retrans\fR
: Maximum number of UDP retransmissions before call ends on
timeout.  Default is 5 for INVITE transactions and 7 for
others.
.TP
\fB\-max_invite_retrans\fR: Maximum number of UDP retransmissions for invite
transactions before call ends on timeout.
.TP
\fB\-max_non_invite_retrans\fR: Maximum number of UDP retransmissions for non\-invite
transactions before call ends on timeout.
.TP
\fB\-max_log_size\fR
: What is the limit for error and message log file sizes.
.TP
\fB\-max_socket\fR
: Set the max number of sockets to open simultaneously.
This option is significant if you use one socket per
call. Once this limit is reached, traffic is distributed
over the sockets already opened. Default value is 50000
.TP
\fB\-mb\fR
: Set the RTP echo buffer size (default: 2048).
.TP
\fB\-mp\fR
: Set the local RTP echo port number. Default is 6000.
.TP
\fB\-nd\fR
: No Default. Disable all default behavior of SIPp which
are the following:
\- On UDP retransmission timeout, abort the call by
.IP
sending a BYE or a CANCEL
.IP
\- On receive timeout with no ontimeout attribute, abort
.IP
the call by sending a BYE or a CANCEL
.IP
\- On unexpected BYE send a 200 OK and close the call
\- On unexpected CANCEL send a 200 OK and close the call
\- On unexpected PING send a 200 OK and continue the call
\- On any other unexpected message, abort the call by
.IP
sending a BYE or a CANCEL
.TP
\fB\-nr\fR
: Disable retransmission in UDP mode.
.TP
\fB\-nostdin\fR
: Disable stdin.
.TP
\fB\-p\fR
: Set the local port number.  Default is a random free port
chosen by the system.
.TP
\fB\-pause_msg_ign\fR
: Ignore the messages received during a pause defined in
the scenario
.TP
\fB\-periodic_rtd\fR
: Reset response time partition counters each logging
interval.
.TP
\fB\-r\fR
: Set the call rate (in calls per seconds).  This value can
bechanged during test by pressing '+','_','*' or '/'.
Default is 10.
pressing '+' key to increase call rate by 1 *
rate_scale,
pressing '\-' key to decrease call rate by 1 *
rate_scale,
pressing '*' key to increase call rate by 10 *
rate_scale,
pressing '/' key to decrease call rate by 10 *
rate_scale.
If the \fB\-rp\fR option is used, the call rate is calculated
with the period in ms given by the user.
.TP
\fB\-rp\fR
: Specify the rate period for the call rate.  Default is 1
second and default unit is milliseconds.  This allows
you to have n calls every m milliseconds (by using \fB\-r\fR n
\fB\-rp\fR m).
Example: \fB\-r\fR 7 \fB\-rp\fR 2000 ==> 7 calls every 2 seconds.
.IP
\fB\-r\fR 10 \fB\-rp\fR 5s => 10 calls every 5 seconds.
.TP
\fB\-rate_scale\fR
: Control the units for the '+', '\-', '*', and '/' keys.
.TP
\fB\-rate_increase\fR
: Specify the rate increase every \fB\-fd\fR units (default is
seconds).  This allows you to increase the load for each
independent logging period.
Example: \fB\-rate_increase\fR 10 \fB\-fd\fR 10s
.IP
==> increase calls by 10 every 10 seconds.
.TP
\fB\-rate_max\fR
: If \fB\-rate_increase\fR is set, then quit after the rate
reaches this value.
Example: \fB\-rate_increase\fR 10 \fB\-rate_max\fR 100
.IP
==> increase calls by 10 until 100 cps is hit.
.TP
\fB\-no_rate_quit\fR
: If \fB\-rate_increase\fR is set, do not quit after the rate
reaches \fB\-rate_max\fR.
.TP
\fB\-recv_timeout\fR
: Global receive timeout. Default unit is milliseconds. If
the expected message is not received, the call times out
and is aborted.
.TP
\fB\-send_timeout\fR
: Global send timeout. Default unit is milliseconds. If a
message is not sent (due to congestion), the call times
out and is aborted.
.HP
\fB\-reconnect_close\fR : Should calls be closed on reconnect?
.TP
\fB\-reconnect_sleep\fR : How long (in milliseconds) to sleep between the close and
reconnect?
.TP
\fB\-ringbuffer_files\fR: How many error/message files should be kept after
rotation?
.TP
\fB\-ringbuffer_size\fR : How large should error/message files be before they get
rotated?
.TP
\fB\-rsa\fR
: Set the remote sending address to host:port for sending
the messages.
.TP
\fB\-rtp_echo\fR
: Enable RTP echo. RTP/UDP packets received on port defined
by \fB\-mp\fR are echoed to their sender.
RTP/UDP packets coming on this port + 2 are also echoed
to their sender (used for sound and video echo).
.TP
\fB\-rtt_freq\fR
: freq is mandatory. Dump response times every freq calls
in the log file defined by \fB\-trace_rtt\fR. Default value is
200.
.TP
\fB\-s\fR
: Set the username part of the resquest URI. Default is
\&'service'.
.TP
\fB\-sd\fR
: Dumps a default scenario (embeded in the sipp executable)
.TP
\fB\-sf\fR
: Loads an alternate xml scenario file.  To learn more
about XML scenario syntax, use the \fB\-sd\fR option to dump
embedded scenarios. They contain all the necessary help.
.TP
\fB\-oocsf\fR
: Load out\-of\-call scenario.
.TP
\fB\-oocsn\fR
: Load out\-of\-call scenario.
.TP
\fB\-skip_rlimit\fR
: Do not perform rlimit tuning of file descriptor limits.
Default: false.
.TP
\fB\-slave\fR
: 3pcc extended mode: indicates the slave number
.TP
\fB\-slave_cfg\fR
: 3pcc extended mode: indicates the file where the master
and slave addresses are stored
.TP
\fB\-sn\fR
: Use a default scenario (embedded in the sipp executable).
If this option is omitted, the Standard SipStone UAC
scenario is loaded.
Available values in this version:
.TP
\- 'uac'
: Standard SipStone UAC (default).
.TP
\- 'uas'
: Simple UAS responder.
.TP
\- 'regexp'
: Standard SipStone UAC \- with regexp and
.IP
variables.
.TP
\- 'branchc'
: Branching and conditional branching in
.IP
scenarios \- client.
.TP
\- 'branchs'
: Branching and conditional branching in
.IP
scenarios \- server.
.IP
Default 3pcc scenarios (see \fB\-3pcc\fR option):
.IP
\- '3pcc\-C\-A' : Controller A side (must be started after
.IP
all other 3pcc scenarios)
.IP
\- '3pcc\-C\-B' : Controller B side.
\- '3pcc\-A'   : A side.
\- '3pcc\-B'   : B side.
.TP
\fB\-stat_delimiter\fR
: Set the delimiter for the statistics file
.TP
\fB\-stf\fR
: Set the file name to use to dump statistics
.TP
\fB\-t\fR
: Set the transport mode:
\- u1: UDP with one socket (default),
\- un: UDP with one socket per call,
\- ui: UDP with one socket per IP address The IP
.IP
addresses must be defined in the injection file.
.IP
\- t1: TCP with one socket,
\- tn: TCP with one socket per call,
\- l1: TLS with one socket,
\- ln: TLS with one socket per call,
\- c1: u1 + compression (only if compression plugin
.IP
loaded),
.IP
\- cn: un + compression (only if compression plugin
.TP
loaded).
This plugin is not provided with sipp.
.TP
\fB\-timeout\fR
: Global timeout. Default unit is seconds.  If this option
is set, SIPp quits after nb units (\fB\-timeout\fR 20s quits
after 20 seconds).
.TP
\fB\-timer_resol\fR
: Set the timer resolution. Default unit is milliseconds.
This option has an impact on timers precision.Small
values allow more precise scheduling but impacts CPU
usage.If the compression is on, the value is set to
50ms. The default value is 10ms.
.TP
\fB\-sendbuffer_warn\fR : Produce warnings instead of errors on SendBuffer
failures.
.TP
\fB\-trace_msg\fR
: Displays sent and received SIP messages in <scenario file
name>_<pid>_messages.log
.TP
\fB\-trace_shortmsg\fR
: Displays sent and received SIP messages as CSV in
<scenario file name>_<pid>_shortmessages.log
.TP
\fB\-trace_screen\fR
: Dump statistic screens in the
<scenario_name>_<pid>_0ms.
.TP
\fB\-trace_err\fR
: Trace all unexpected messages in <scenario file
name>_<pid>_errors.log.
.TP
\fB\-trace_stat\fR
: Dumps all statistics in <scenario_name>_<pid>.csv file.
Use the '\-h stat' option for a detailed description of
the statistics file content.
.TP
\fB\-trace_counts\fR
: Dumps individual message counts in a CSV file.
.TP
\fB\-trace_rtt\fR
: Allow tracing of all response times in <scenario file
name>_<pid>_rtt.csv.
.TP
\fB\-trace_logs\fR
: Allow tracing of <log> actions in <scenario file
name>_<pid>_logs.log.
.TP
\fB\-users\fR
: Instead of starting calls at a fixed rate, begin 'users'
calls at startup, and keep the number of calls constant.
.TP
\fB\-3pcc\fR
: Launch the tool in 3pcc mode ("Third Party call
control"). The passed ip address is depending on the
3PCC role.
\- When the first twin command is 'sendCmd' then this is
.TP
the address of the remote twin socket.
SIPp will try to
.IP
connect to this address:port to send the twin command
(This instance must be started after all other 3PCC
scenarii).
.IP
Example: 3PCC\-C\-A scenario.
.IP
\- When the first twin command is 'recvCmd' then this is
.IP
the address of the local twin socket. SIPp will open
this address:port to listen for twin command.
.IP
Example: 3PCC\-C\-B scenario.
.TP
\fB\-tdmmap\fR
: Generate and handle a table of TDM circuits.
A circuit must be available for the call to be placed.
Format: \fB\-tdmmap\fR {0\-3}{99}{5\-8}{1\-31}
.TP
\fB\-key\fR
: keyword value
Set the generic parameter named "keyword" to "value".
.PP
Signal handling:
.IP
SIPp can be controlled using posix signals. The following signals
are handled:
USR1: Similar to press 'q' keyboard key. It triggers a soft exit
.IP
of SIPp. No more new calls are placed and all ongoing calls
are finished before SIPp exits.
Example: kill \fB\-SIGUSR1\fR 732
.IP
USR2: Triggers a dump of all statistics screens in
.IP
<scenario_name>_<pid>_screens.log file. Especially useful
in background mode to know what the current status is.
Example: kill \fB\-SIGUSR2\fR 732
.PP
Exit code:
.IP
Upon exit (on fatal error or when the number of asked calls (\fB\-m\fR
option) is reached, sipp exits with one of the following exit
code:
.IP
0: All calls were successful
1: At least one call failed
.IP
97: exit on internal command. Calls may have been processed
99: Normal exit without calls processed
\fB\-1\fR: Fatal error
.PP
Example:
.IP
Run sipp with embedded server (uas) scenario:
.IP
\&./sipp \fB\-sn\fR uas
.IP
On the same host, run sipp with embedded client (uac) scenario
.IP
\&./sipp \fB\-sn\fR uac 127.0.0.1
.IP
SIPp v3.1, version unknown, built Jun 13 2010, 15:34:03.
.IP
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
.IP
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
.IP
You should have received a copy of the GNU General Public
License along with this program; if not, write to the
Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA  02111\-1307 USA
.IP
Author: see source files.