SIPp

Using SIPp

Main features

SIPp allows to generate one or many SIP calls to one remote system. The tool is started from the command line. In this example, two SIPp are started in front of each other to demonstrate SIPp capabilities.

Run sipp with embedded server (uas) scenario:

On the same host, run sipp with embedded client (uac) scenario

Integrated scenarios

Integrated scenarios? Yes, there are scenarios that are embedded in SIPp executable. While you can create your own custom SIP scenarios (see how to create your own XML scenarios), a few basic (yet useful) scenarios are available in SIPp executable.

UAC

Scenario file: uac.xml (original XML file)

| |(2) 100 (optional) | |<------------------| |(3) 180 (optional) | |<------------------| |(4) 200 | |<------------------| |(5) ACK | |------------------>| | | |(6) PAUSE | | | |(7) BYE | |------------------>| |(8) 200 | |<------------------| ]]>

UAC with media

Scenario file: uac_pcap.xml (original XML file)

| |(2) 100 (optional) | |<------------------| |(3) 180 (optional) | |<------------------| |(4) 200 | |<------------------| |(5) ACK | |------------------>| | | |(6) RTP send (8s) | |==================>| | | |(7) RFC2833 DIGIT 1| |==================>| | | |(8) BYE | |------------------>| |(9) 200 | |<------------------| ]]>

UAS

Scenario file: uas.xml (original XML file)

| |(2) 180 | |<------------------| |(3) 200 | |<------------------| |(4) ACK | |------------------>| | | |(5) PAUSE | | | |(6) BYE | |------------------>| |(7) 200 | |<------------------| ]]>

regexp

Scenario file: regexp.xml (original XML file)

This scenario, which behaves as an UAC is explained in greater details in this section.

branch

Scenario files: branchc.xml (original XML file) and branchs.xml (original XML file)

Those scenarios, which work against each other (branchc for client side and branchs for server side) are explained in greater details in this section.

200 <---------- 200 <---------- INVITE ----------> 100 <---------- 180 <---------- 403 <---------- 200 <---------- ACK ----------> [ 5000 ms] BYE ----------> 200 <----------]]>

3PCC

3PCC stands for 3rd Party Call Control. 3PCC is described in RFC 3725. While this feature was first developped to allow 3PCC like scenarios, it can also be used for every case where you would need one SIPp to talk to several remotes.

In order to keep SIPp simple (remember, it's a test tool!), one SIPp instance can only talk to one remote. Which is an issue in 3PCC call flows, like call flow I (SIPp beeing a controller):

| | | |(3) INVITE offer1 | | |------------------>| | |(4) 200 OK answer1 | | |<------------------| | |(5) ACK | | |------------------>| |(6) ACK answer1 | | |<------------------| | |(7) RTP | | |.......................................| ]]>

Scenario file: 3pcc-A.xml (original XML file)

Scenario file: 3pcc-B.xml (original XML file)

Scenario file: 3pcc-C-A.xml (original XML file)

Scenario file: 3pcc-C-B.xml (original XML file)

The 3PCC feature in SIPp allows to have two SIPp instances launched and synchronised together. If we take the example of call flow I, one SIPp instance will take care of the dialog with remote A (this instance is called 3PCC-C-A for 3PCC-Controller-A-Side) and another SIPp instance will take care of the dialog with remote B (this instance is called 3PCC-C-B for 3PCC-Controller-B-Side).

The 3PCC call flow I will, in reality, look like this (Controller has been divided in two SIPp instances):

| | | | sendCmd (offer1) | | | |----------------->| | | | recvCmd | | | |(3) INVITE offer1 | | | |------------------>| | | |(4) 200 OK answer1 | | | |<------------------| | | sendCmd | | | (answer1) | | | |<-----------------| | | recvCmd |(5) ACK | | | |------------------>| |(6) ACK answer1 | | | |<------------------| | | |(7) RTP | | | |..........................................................| ]]>

As you can see, we need to pass informations between both sides of the controller. SDP "offer1" is provided by A in message (2) and needs to be sent to B side in message (3). This mechanism is implemented in the scenarios through the <sendCmd> command. This:

]]>

Will send a "command" to the twin SIPp instance. Note that including the Call-ID is mandatory in order to correlate the commands to actual calls. In the same manner, this:

]]>

Will receive a "command" from the twin SIPp instance. Using the regular expression mechanism, the content is retrieved and stored in a call variable ($2 in this case), ready to be reinjected

;tag=[call_number] To: sut [peer_tag_param] Call-ID: [call_id] CSeq: 1 ACK Contact: sip:sipp@[local_ip]:[local_port] Max-Forwards: 70 Subject: Performance Test [$2] ]]]]> ]]>

In other words, sendCmd and recvCmd can be seen as synchronization points between two SIPp instances, with the ability to pass parameters between each other.

Another scenario that has been reported to be do-able with the 3PCC feature is the following:

A calls B. B answers. B and A converse
B calls C. C answers. C and B converse
B "REFER"s A to C and asks to replace A-B call with B-C call.
A accepts. A and C talk. B drops out of the calls.

3PCC Extended

An extension of the 3pcc mode is implemented in sipp. This feature allows n twin sipp instances to communicate each other, each one of them being connected to a remote host.

The sipp instance which initiates the call is launched in "master" mode. The others are launched in "slave" mode. Twin sipp instances have names, given in the command line (for example, s1, s2...sn for the slaves and m for the master) Correspondances between instances names and their addresses must be stored in a file (provided by -slave_cfg command line argument), in the following format:

Each twin sipp instance must access a different copy of this file.

sendCmd and recvCmd have additional attributes:

]]>

Will send a command to the "s1" peer instance, which can be either master or slave, depending on the command line argument, which must be consistent with the scenario: a slave instance cannot have a sendCmd action before having any recvCmd. Note that the message must contain a "From" field, filled with the name of the sender.

]]>

Indicates that the twin command is expected to be received from the "m" peer instance.

Note that the master must be the launched at last.

There is no integrated scenarios for the 3pcc extended mode, but you can easily adapt those from 3pcc.

Example: the following drawing illustrate the entire procedure. The arrows that are shown between SIPp master and slaves depict only the synchronization commands exchanged between the different SIPp instances. The SIP message exchange takes place as usual.

Master / slave feature

Traffic control

SIPp generates SIP traffic according to the scenario specified. You can control the number of calls (scenario) that are started per second. This can be done either:

Interactively, by pressing keys on the keyboard
- '+' key to increase call rate by 1
- '-' key to decrease call rate by 1
- '*' key to increase call rate by 10
- '/' key to decrease call rate by 10
At starting time, by specifying parameters on the command line:
- "-r" to specify the call rate in number of calls per seconds
- "-rp" to specify the "rate period" in milliseconds for the call rate (default is 1000ms/1sec). This allows you to have n calls every m milliseconds (by using -r n -rp m). Example: run SIPp at 7 calls every 2 seconds (3.5 calls per second)

You can also pause the traffic by pressing the 'p' key. SIPp will stop placing new calls and wait until all current calls go to their end. You can resume the traffic by pressing 'p' again.

To quit SIPp, press the 'q' key. SIPp will stop placing new calls and wait until all current calls go to their end. SIPp will then exit.

You can also force SIPp to quit immediatly by pressing the 'Q' key. Current calls will be terminated by sending a BYE or CANCEL message (depending if the calls have been established or not). The same behaviour is obtained by pressing 'q' twice.

TIP: you can place a defined number of calls and have SIPp exit when this is done. Use the -m option on the command line.

Remote control

SIPp can be "remote-controlled" through a UDP socket. This allows for example

To automate a series of actions, like increasing the call rate smoothly, wait for 10 seconds, increase more, wait for 1 minute and loop
Have a feedback loop so that an application under test can remote control SIPp to lower the load, pause the traffic, ...

Each SIPp instance is listening to a UDP socket. It starts to listen to port 8888 and each following SIPp instance (up to 60) will listen to base_port + 1 (8889, 8890, ...).

It is then possible to control SIPp like this:

/dev/udp/x.y.z.t/8888 -> put SIPp in pause state (p key) echo q >/dev/udp/x.y.z.t/8888 -> quit SIPp (q key)]]> All keys available through keyboard are also available in the remote control interface

You could also have a small shell script to automate a serie of action. For example, this script will increase the call rate by 10 more new calls/s every 5 seconds, wait at this call rate for one minute and exit SIPp:

/dev/udp/127.0.0.1/8889 sleep 5 echo "*" >/dev/udp/127.0.0.1/8889 sleep 5 echo "*" >/dev/udp/127.0.0.1/8889 sleep 5 echo "*" >/dev/udp/127.0.0.1/8889 sleep 60 echo "q" >/dev/udp/127.0.0.1/8889 ]]>

Running SIPp in background

SIPp can be launched in background mode (-bg command line option).

By doing so, SIPp will be detached from the current terminal and run in the background. The PID of the SIPp process is provided. If you didn't specify a number of calls to execute with the -m option, SIPp will run forever.

There is a mechanism implemented to stop SIPp smoothly. The command kill -SIGUSR1 [SIPp_PID] will instruct SIPp to stop placing any new calls and finish all ongoing calls before exiting.

When using the background mode, the main sipp instance stops and a child process will continue the job. Therefore, the log files names will contain another PID than the actual sipp instance PID.

Create your own XML scenarios

Of course embedded scenarios will not be enough. So it's time to create your own scenarios. A SIPp scenario is written in XML (a DTD that may help you write SIPp scenarios does exist and has been tested with jEdit - this is described in a later section). A scenario will always start with:

]]>

And end with:

]]>

Easy, huh? Ok, now let's see what can be put inside. You are not obliged to read the whole table now! Just go in the next section for an example.

List of commands with their attributes
Command	Attribute(s)	Description	Example
<send>	retrans	Used for UDP transport only: it specifies the T1 timer value, as described in SIP RFC 3261, section 17.1.1.2.	`<send retrans="500">`: will initiate T1 timer to 500 milliseconds (RFC3261 default).
	start_rtd	Starts one of the 5 "Response Time Duration" timer. (see statistics section).	`<send start_rtd="2">`: the timer number 2 will start when the message is sent.
	rtd	Stops one of the 5 "Response Time Duration" timer.	`<send rtd="2">`: the timer number 2 will stop when the message is sent.
	repeat_rtd	Used with a rtd attribute, it allows the corresponding "Response Time Duration" timer to be counted more than once per call (useful for loop call flows).	`<send rtd="1" repeat_rtd="true">`: the timer number 1 value will be printed but the timer won't stop.
	crlf	Displays an empty line after the arrow for the message in main SIPp screen.	`<send crlf="true">`
	lost	Emulate packet lost. The value is specified as a percentage.	`<send lost="10">`: 10% of the message sent are actually not sent :).
	next	You can put a "next" in a send to go to another part of the script when you are done with sending the message. See conditional branching section for more info.	Example to jump to label "12" after sending an ACK: ]]>
	test	You can put a "test" next to a "next" attribute to indicate that you only want to branch to the label specified with "next" if the variable specified in "test" is set (through regexp for example). See conditional branching section for more info.	Example to jump to label "6" after sending an ACK only if variable 4 is set: ]]>
	counter	Increments the counter given as parameter when the message is sent. A total of 5 counter can be used. The counter are saved in the statistic file.	`<send counter="1">`: Increments counter #1 when the message is sent.
<recv>	response	Indicates what SIP message code is expected.	`<recv response="200">`: SIPp will expect a SIP message with code "200".
	request	Indicates what SIP message request is expected.	`<recv request="ACK">`: SIPp will expect an "ACK" SIP message.
	optional	Indicates if the message to receive is optional. In case of an optional message and if the message is actually received, it is not seen as a unexpected message. When an unexpected message is received, Sipp looks if this message matches an optional message defined in the previous step of the scenario. If optional is set to "global", Sipp will look every previous steps of the scenario.	`<recv response="100" optional="true">`: The 100 SIP message can be received without being considered as "unexpected".
	crlf	Displays an empty line after the arrow for the message in main SIPp screen.	`<recv crlf="true">`
	rrs	Record Route Set. if this attribute is set to "true", then the "Record-Route:" header of the message received is stored and can be recalled using the [routes] keyword.	`<recv response="100" rrs="true">`.
	auth	Authentication. if this attribute is set to "true", then the "Proxy-Authenticate:" header of the message received is stored and is used to build the [authentication] keyword.	`<recv response="407" auth="true">`.
	start_rtd	Starts one of the 5 "Response Time Duration" timer. (see statistics section).	`<recv start_rtd="4">`: the timer number 4 will start when the message is received.
	rtd	Stops one of the 5 "Response Time Duration" timer.	`<recv rtd="4">`: the timer number 4 will stop when the message is received.
	repeat_rtd	Used with a rtd attribute, it allows the corresponding "Response Time Duration" timer to be counted more than once per call (useful for loop call flows).	`<recv rtd="1" repeat_rtd="true">`: the timer number 1 value will be printed but the timer won't stop.
	lost	Emulate packet lost. The value is specified as a percentage.	`<recv lost="10">`: 10% of the message received are thrown away.
	timeout	Specify a timeout while waiting for a message. If the message is not received, the call is aborted, unless an ontimeout label is defined.	`<recv timeout="100000">`
	ontimeout	Specify a label to jump to if the timeout popped before the message to be received.	Example to jump to label "5" when not receiving a 100 message after 100 seconds: ]]>
	action	Specify an action when receiving the message. See Actions section for possible actions.	Example of a "regular expression" action: ]]>
	next	You can put a "next" in an optional receive to go to another part of the script if you receive that message. See conditional branching section for more info.	Example to jump to label "5" when receiving a 403 message: ]]>
	test	You can put a "test" in an optional receive to go to another part of the script if you receive that message only if the variable specified by "test" is set. See conditional branching section for more info.	Example to jump to label "5" when receiving a 403 message only if variable 3 is set: ]]>
	chance	In combination with "test", probability to actually branch to another part of the scenario. Chance can have a value between 0 (never) and 1 (always). See conditional branching section for more info.	]]>90% chance to go to label "5" if variable "3" is set.
	counter	Increments the counter given as parameter when the message is received. A total of 5 counter can be used. The counter are saved in the statistic file.	`<recv counter="1">`: Increments counter #1 when the message is received.
	regexp_match	Boolean. Indicates if 'request' ('response' is not available) is given as a regular expression. If so, the recv command will match against the regular expression. This allows to catch several cases in the same receive command.	Example of a recv command that matches MESSAGE or PUBLISH or SUBSCRIBE requests: ]]>
<pause>	milliseconds	Specify the pause delay, in milliseconds. When this delay is not set, the value of the `-d` command line parameter is used.	`<pause milliseconds="5000"/>`: pause the scenario for 5 seconds.
	variable	Indicates which call variable to use to determine the length of the pause.	`<pause variable="1" />` pauses for the number of milliseconds specified by call variable 1.
	distribution	Indicates which statistical distribution to use to determine the length of the pause. Without GSL, you may use `uniform` or `fixed`. With GSL, normal, exponential, gamma, lambda, lognormal, negbin, (negative binomial), pareto, and weibull are available. Depending on the distribution you select, you must also supply distribution specific parameters.	The following examples show the various types of distributed pauses: `<pause distribution="fixed" value="1000" />` pauses for 1 second. `<pause distribution="uniform" min="2000" max="5000"/>` pauses between 2 and 5 seconds. The remaining distributions require GSL. In general The parameter names were chosen to be as consistent with Wikipedia's distribution description pages. `<pause distribution="normal" mean="60000" stdev="15000"/>` provides a normal pause with a mean of 60 seconds (i.e. 60,000 ms) and a standard deviation of 15 seconds. The mean and standard deviation are specified as integer milliseconds. The distribution will look like: `<pause distribution="lognormal" mean="12.28" stdev="1" />` creates a distribution's whose natural logarithm has a mean of 12.28 and a standard deviation of 1. The mean and standard deviation are specified as double values (in milliseconds). The distribution will look like: `<pause distribution="exponential" mean="900000"/>` creates an exponentially distributed pause with a mean of 15 minutes. The distribution will look like: `<pause distribution="weibull" lambda="3" k ="4"/>` creates a Weibull distribution with a scale of 3 and a shape of 4 (see Weibull on Wikipedia for a description of the distribution). `<pause distribution="pareto" k="1" x_m="2"/>` creates a Pareto distribution with k and x_m of 1 and 2, respectively (see Pareto on Wikipedia for a description of the distribution). `<pause distribution="gamma" k="3" theta="2"/>` creates a Gamma distribution with k and theta of 9 and 2, respectively (see Gamma on Wikipedia for a description of the distribution). `<pause distribution="negbin" p="0.1" n="2"/>` creates a Negative binomial distribution with p and n of 0.1 and 2, respectively (see Negative Binomial on Wikipedia for a description of the distribution).
	crlf	Displays an empty line after the arrow for the message in main SIPp screen.	`<pause crlf="true">`
	next	You can put a "next" in a pause to go to another part of the script when you are done with the pause. See conditional branching section for more info.	Example to jump to label "7" after pausing 4 seconds:]]>
	sanity_check	By default, statistically distributed pauses are sanity checked to ensure that their 99th percentile values are less than INT_MAX. Setting sanity_check to false disables this behavior.	`<pause distribution="lognormal" mean="10" stdev="10" sanity_check="false"/>` disables sanity checking of the lognormal distribution.
<nop>	action	The nop command doesn't do anything at SIP level. It is only there to specify an action to execute. See Actions section for possible actions.	Execute the play_pcap_audio/video action: ]]>
	start_rtd	Starts one of the 5 "Response Time Duration" timer. (see statistics section).	`<nop start_rtd="1">`: the timer number 1 starts when nop is executed.
	rtd	Stops one of the 5 "Response Time Duration" timer.	`<nop rtd="1">`: the timer number 1 will stops when nop is executed.
<sendCmd>	<![CDATA[]]>	Content to be sent to the twin 3PCC SIPp instance. The Call-ID must be included in the CDATA. In 3pcc extended mode, the From must be included to.	]]>
	dest	3pcc extended mode only: the twin sipp instance which the command will be sent to	`<sendCmd dest="s1">`: the command will be sent to the "s1" twin instance
<recvCmd>	action	Specify an action when receiving the command. See Actions section for possible actions.	Example of a "regular expression" to retrieve what has been send by a sendCmd command: ]]>
	src	3pcc extended mode only: indicate the twin sipp instance which the command is expected to be received from	`<recvCmd src = "s1">`: the command will be expected to be received from the "s1" twin instance
<label>	id	A label is used when you want to branch to specific parts in your scenarios. The "id" attribute is an integer where the maximum value is 19. See conditional branching section for more info.	Example: set label number 13:]]>
<Response Time Repartition>	value	Specify the intervals, in milliseconds, used to distribute the values of response times.	`<ResponseTimeRepartition value="10, 20, 30"/>`: response time values are distributed between 0 and 10ms, 10 and 20ms, 20 and 30ms, 30 and beyond.
<Call Length Repartition>	value	Specify the intervals, in milliseconds, used to distribute the values of the call length measures.	`<CallLengthRepartition value="10, 20, 30"/>`: call length values are distributed between 0 and 10ms, 10 and 20ms, 20 and 30ms, 30 and beyond.

There are not so many commands: send, recv, sendCmd, recvCmd, pause, ResponseTimeRepartition and CallLengthRepartition. To make things even clearer, nothing is better than an example...

Structure of client (UAC like) XML scenarios

A client scenario is a scenario that starts with a "send" command. So let's start:

[service][remote_ip][remote_port][transport][local_ip][local_port][local_ip][local_port];tag=]]>[call_number][service][remote_ip][remote_port] Call-ID: ]]>[call_id][local_ip][local_port][len][local_ip_type][local_ip][media_ip_type][media_ip][media_port] ]]>

Inside the "send" command, you have to enclose your SIP message between the "<![CDATA" and the "]]>" tags. Everything between those tags is going to be sent toward the remote system. You may have noticed that there are strange keywords in the SIP message, like [service], [remote_ip], .... Those keywords are used to indicate to SIPp that it has to do something with it.

Here is the list:

Keyword list
Keyword	Default	Description
[service]	service	Service field, as passed in the `-s service_name`
[remote_ip]	-	Remote IP address, as passed on the command line.
[remote_port]	5060	Remote IP port, as passed on the command line. You can add a computed offset [remote_port+3] to this value.
[transport]	UDP	Depending on the value of -t parameter, this will take the values "UDP" or "TCP".
[local_ip]	Primary host IP address	Will take the value of -i parameter.
[local_ip_type]	-	Depending on the address type of -i parameter (IPv4 or IPv6), local_ip_type will have value "4" for IPv4 and "6" for IPv6.
[local_port]	Chosen by the system	Will take the value of -p parameter. You can add a computed offset [local_port+3] to this value.
[len]	-	Computed length of the SIP body. To be used in "Content-Length" header. You can add a computed offset [len+3] to this value.
[call_number]	-	Index. The call_number starts from "1" and is incremented by 1 for each call.
[cseq]	-	Generates automatically the CSeq number. The initial value is 1 by default. It can be changed by using the `-base_cseq` command line option.
[call_id]	-	A call_id identifies a call and is generated by SIPp for each new call. In client mode, it is mandatory to use the value generated by SIPp in the "Call-ID" header. Otherwise, SIPp will not recognise the answer to the message sent as being part of an existing call. Note: [call_id] can be pre-pended with an arbitrary string using '///'. Example: Call-ID: ABCDEFGHIJ///[call_id] - it will still be recognized by SIPp as part of the same call.
[media_ip]	-	Depending on the value of -mi parameter, it is the local IP address for RTP echo.
[media_ip_type]	-	Depending on the address type of -mi parameter (IPv4 or IPv6), media_ip_type will have value "4" for IPv4 and "6" for IPv6. Useful to build the SDP independently of the media IP type.
[media_port]	-	Depending on the value of -mp parameter, it set the local RTP echo port number. Default is none. RTP/UDP packets received on that port are echoed to their sender. You can add a computed offset [media_port+3] to this value.
[auto_media_port]	-	Only for pcap. To make audio and video ports begin from the value of -mp parameter, and change for each call using a periodical system, modulo 10000 (which limits to 10000 concurrent RTP sessions for pcap_play)
*[last_]**	-	The '[last_]' keyword is replaced automatically by the specified header if it was present in the last message received (except if it was a retransmission). If the header was not present or if no message has been received, the '[last_]' keyword is discarded, and all bytes until the end of the line are also discarded. If the specified header was present several times in the message, all occurences are concatenated (CRLF separated) to be used in place of the '[last_*]' keyword.
[field0-n]	-	Used to inject values from an external CSV file. See "Injecting values from an external CSV during calls" section.
[$n]	-	Used to inject the value of call variable number n. See "Actions" section
[authentication]	-	Used to put the authentication header. This field can have parameters, in the following form: [authentication username=myusername password=mypassword]. If no username is provided, the value from -s command line parameter (service) is used. If no password is provided, the value from -ap command line parameter is used. See "Authentication" section
[pid]	-	Provide the process ID (pid) of the main SIPp thread.
[routes]	-	If the "rrs" attribute in a recv command is set to "true", then the "Record-Route:" header of the message received is stored and can be recalled using the [routes] keyword
[next_url]	-	If the "rrs" attribute in a recv command is set to "true", then the [next_url] contains the contents of the Contact header (i.e within the '<' and '>' of Contact)
[branch]	-	Provide a branch value which is a concatenation of magic cookie (z9hG4bK) + call number + message index in scenario. An offset (like [branch-N]) can be appended if you need to have the same branch value as a previous message.
[msg_index]	-	Provide the message number in the scenario.
[cseq]	-	Provides the CSeq value of the last request received. This value can be incremented (e.g. [cseq+1] adds 1 to the CSeq value of the last request).
[clock_tick]	-	Includes the internal SIPp clock tick value in the message.
[tdmmap]	-	Includes the tdm map values used by the call in the message (see -tdmmap option).
[fill]	-	Injects filler characters into the message. The length of the fill text is equal to the call variable stored in the `variable=N` parameter. By default the text is a sequence of X's, but can be controlled with the `text="text"` parameter.

Now that the INVITE message is sent, SIPp can wait for an answer by using the "recv" command.

optional="true" optional="true" ]]>

100 and 180 messages are optional, and 200 is mandatory. In a "recv" sequence, there must be one mandatory message.

Now, let's send the ACK:

[service][remote_ip][remote_port][transport][local_ip][local_port][local_ip][local_port];tag=]]>[call_number][service][remote_ip][remote_port]]>[peer_tag_param][call_id][local_ip][local_port] ]]>

We can also insert a pause. The scenario will wait for 5 seconds at this point.

]]>

And finish the call by sending a BYE and expecting the 200 OK:

[service][remote_ip][remote_port][transport] [local_ip][local_port][local_ip][local_port];tag=]]>[call_number][service][remote_ip][remote_port]]]>[peer_tag_param][call_id][local_ip][local_port] ]]>

And this is the end of the scenario:

]]>

Creating your own SIPp scenarios is not a big deal. If you want to see other examples, use the -sd parameter on the command line to display embedded scenarios.

Structure of server (UAS like) XML scenarios

A server scenario is a scenario that starts with a "recv" command. The syntax and the list of available commands is the same as for "client" scenarios.

But you are more likely to use [last_*] keywords in those server side scenarios. For example, a UAS example will look like:

[last_Via:][last_From:][last_To:][call_number][last_Call-ID:][last_CSeq:][local_ip][local_port][transport] Content-Length: 0 ]]]]> ]]>

The answering message, 180 Ringing in this case, is built with the content of headers received in the INVITE message.

Actions

In a "recv" or "recvCmd" command, you have the possibility to execute an action. Several actions are available:

Regular expressions (ereg)
Log something in aa log file (log)
Execute an external (system), internal (int_cmd) or pcap_play_audio/pcap_play_video command (exec)

Regular expressions

Using regular expressions in SIPp allows to

Extract content of a SIP message or a SIP header and store it for future usage (called re-injection)
Check that a part of a SIP message or of an header is matching an expected expression

Regular expressions used in SIPp are defined per Posix Extended standard (POSIX 1003.2). If you want to learn how to write regular expressions, I will recommend this regexp tutorial.

Here is the syntax of the regexp action:

regexp action syntax
Keyword	Default	Description
regexp	None	Contains the regexp to use for matching the received message or header. MANDATORY.
search_in	msg	can have 2 values: "msg" (try to match against the entire message) or "hdr" (try to match against a specific SIP header).
header	None	Header to try to match against. Only used when the search_in tag is set to hdr. MANDATORY IF search_in is equal to hdr.
case_indep	false	To look for a header ignoring case . Only used when the search_in tag is set to hdr.
occurence	1	To find the nth occurence of a header. Only used when the search_in tag is set to hdr.
start_line	false	To look only at start of line. Only used when the search_in tag is set to hdr.
check_it	false	if set to true, the call is marked as failed if the regexp doesn't match.
assign_to	None	contain the variable id (integer) or a list of variable id which will be used to store the result(s) of the matching process between the regexp and the message. Those variables can be re-used at a later time either by using '[$n]' in the scenario to inject the value of the variable in the messages or by using the content of the variables for conditional branching. The first variable in the variable list of assign_to contains the entire regular expression matching. The following variables contain the sub-expressions matching. Example: ]]>If the SIP message contains the line variable 3 contains "o=user1 53655765 2353687637", variable 4 contains "user1", variable 5 contains "53655765" and variable 8 contains "2353687637".

Note that you can have several regular expressions in one action.

The following example is used to:

First action:
- Extract the first IPv4 address of the received SIP message
- Check that we could actually extract this IP address (otherwise call will be marked as failed)
- Assign the extracted IP address to call variables 1 and 2.
Second action:
- Extract the Contact: header of the received SIP message
- Assign the extracted Contract: header to variable 6.

]]>

Log a message

The "log" action allows you to customize your traces. Messages are printed in the <scenario file name>_<pid>_logs.log file. Any keyword is expanded to reflect the value actually used.

Logs are generated only if -trace_logs option is set on the command line.

Example:

]]>

Execute a command

The "exec" action allows you to execute "internal", "external", "play_pcap_audio" or "play_pcap_video" commands.

Internal commands

Internal commands (specified using int_cmd attribute) are stop_call, stop_gracefully (similar to pressing 'q'), stop_now (similar to ctrl+C).

Example that stops the execution of the script on receiving a 603 response:

]]>

External commands

External commands (specified using command attribute) are anything that can be executed on local host with a shell.

Example that execute a system echo for every INVITE received:

]]>

PCAP (media) commands

PCAP play commands (specified using play_pcap_audio / play_pcap_video attributes) allow you to send a pre-recorded RTP stream using the pcap library.

Choose play_pcap_audio to send the pre-recorded RTP stream using the "m=audio" SIP/SDP line port as a base for the replay.

Choose play_pcap_video to send the pre-recorded RTP stream using the "m=video" SIP/SDP line port as a base.

The play_pcap_audio/video command has the following format: play_pcap_audio="[file_to_play]" with:

file_to_play: the pre-recorded pcap file to play

The action is non-blocking. SIPp will start a light-weight thread to play the file and the scenario with continue immediately. If needed, you will need to add a pause to wait for the end of the pcap play.

Example that plays a pre-recorded RTP stream:

]]>

Variable Manipulation

You may also perform simple arithmetic (add, subtract, multiply, divide) on floating point values. The "assign_to" attribute contains the first operand, and is also the destination of the resulting value. The second operand is either an immediate value or stored in a variable, represented by the "value" and "variable" attributes, respectively.

SIPp supports call variables that take on double-precision floating values. The actions that modify double variables all write to the variable referenced by the assign_to parameter. These variables can be assigned using one of three actions: assign, sample, or todouble. For assign, the double precision value is stored in the "value" parameter. The sample action assigns values based on statistical distributions, and uses the same parameters as a statistically distributed pauses. Finally, the todouble command converts the variable referenced by the "variable" attribute to a double before assigning it.

For example, to assign the value 1.0 to $1 and sample from the normal distribution into $2:

]]>

Simple arithmetic is also possible using the <add>, <subtract>, <multiply>, and <divide> actions, which add, subtract, multiply, and divide the variable referenced by assign_to by the value in value. For example, the following action modifies variable one as follows:

]]>

Rather than using fixed values, you may also retrieve the second operand from a variable, using the <variable> parameter. For example:

]]>

String Variables

You can create string variables by using the <assignstr> command, which accepts two parameters: assign_to and value. The value may contain any of the same substitutions that a message can contain. For example:

]]>

Variable Testing

Variable testing allows you to construct loops and control structures using call variables. THe test action takes four arguments: variable which is the variable that to compare against value, and assign_to which is a boolean call variable that the result of the test is stored in. Compare may be one of the following tests: equal, not_equal, greater_than, less_than, greater_than_equal, or less_than_equal.

Example that sets $2 to true if $1 is less than 10:

]]>

Injecting values from an external CSV during calls

You can use "-inf file_name" as a command line parameter to input values into the scenarios. The first line of the file should say whether the data is to be read in sequence (SEQUENTIAL), random order (RANDOM), or in a user based manner (USER). Each line corresponds to one call and has one or more ';' delimited data fields and they can be referred as [field0], [field1], ... in the xml scenario file. Example:

Will be read in sequence (first call will use first line, second call second line). At any place where the keyword "[field0]" appears in the scenario file, it will be replaced by either "Sarah", "Bob" or "Fred" depending on the call. At any place where the keyword "[field1]" appears in the scenario file, it will be replaced by either "sipphone32" or "sipphone12" or "sipphone94" depending on the call. At the end of the file, SIPp will re-start from the beginning. The file is not limited in size.

The CSV file can contain comment lines. A comment line is a line that starts with a "#".

As a picture says more than 1000 words, here is one:

Field injection

Think of the possibilities of this feature. They are huge.

It is possible to use more than one injection file, and is necessary when you want to select different types of data in different ways. For example, when running a user-based benchmark, you may have a caller.csv with "USER" as the first line and a callee.csv with "RANDOM" as the first line. To specify which CSV file is used, add the file= parameter to the keyword. For example:

;tag=[pid]SIPpTag00[call_number] To: sut user <[field0 file="callee.csv"]> ...]]>

Will select the destination user from callee.csv and the sending user from caller.csv. If no file parameter is specified, then the first input file on the command line is used by default.

Conditional branching

Conditional branching in scenarios

It is possible to execute a scenario in a non-linear way. You can jump from one part of the scenario to another for example when a message is received or if a call variable is set.

You define a label (in the xml) as <label id="n"/> Where n is a number between 1 and 19 (we can easily have more if needed). The label commands go anywhere in the main scenario between other commands. To any action command (send, receive, pause, etc.) you add a next="n" parameter, where n matches the id of a label. When it has done the command it continues the scenario from that label. This part is useful with optional receives like 403 messages, because it allows you to go to a different bit of script to reply to it and then rejoin at the BYE (or wherever or not).

Alternatively, if you add a test="m" parameter to the next, it goes to the label only if variable [$m] is set. This allows you to look for some string in a received packet and alter the flow either on that or a later part of the script. The evaluation of a test varies based on the type of call variable. For regular expressions, at least one match must have been found; for boolean variables the value must be true; and for all others a value must have been set (currently this only applies to doubles). For more complicated tests, see the <test> action.

If you add special cases at the end, don’t forget to put a label at the real end and jump to it at the end of the normal flow.

Example:

The following example corresponds to the embedded 'branchc' (client side) scenario. It has to run against the embedded 'branchs' (server side) scenario.
Conditional branching example

Randomness in conditional branching

To have SIPp behave somewhat more like a "normal" SIP client being used by a human, it is possible to use "statistical branching". Wherever you can have a conditional branch on a variable being set (test="4"), you can also branch based on a statistical decision using the attribute "chance" (e.g. chance="0.90"). Chance can have a value between 0 (never) and 1 (always). "test" and "chance" can be combined, i.e. only branching when the test succeeds and the chance is good.

With this, you can have a variable reaction in a given scenario (e.g.. answer the call or reject with busy), or run around in a loop (e.g. registrations) and break out of it after some random number of iterations.

SIP authentication

SIPp supports SIP authentication. Two authentication algorithm are supported: Digest/MD5 ("algorithm="MD5"") and Digest/AKA ("algorithm="AKAv1-MD5"", as specified by 3GPP for IMS).

To enable authentication support, SIPp must be compiled in a special way. See SIPp installation for details

Enabling authentication is simple. When receiving a 401 (Unauthorized) or a 407 (Proxy Authentication Required), you must add auth="true" in the <recv> command to take the challenge into account. Then, the authorization header can be re-injected in the next message by using [authentication] keyword.

Computing the authorization header is done through the usage of the "[authentication]" keyword. Depending on the algorithm ("MD5" or "AKAv1-MD5"), different parameters must be passed next to the authentication keyword:

Digest/MD5 (example: [authentication username=joe password=schmo])
- username: username: if no username is specified, the username is taken from the '-s' (service) command line parameter
- password: password: if no password is specified, the password is taken from the '-ap' (authentication password) command line parameter
Digest/AKA: (example: [authentication username=HappyFeet aka_OP=0xCDC202D5123E20F62B6D676AC72CB318 aka_K=0x465B5CE8B199B49FAA5F0A2EE238A6BC aka_AMF=0xB9B9])
- username: username: if no username is specified, the username is taken from the '-s' (service) command line parameter
- aka_K: Permanent secret key. If no aka_K is provided, the "password" attributed is used as aka_K.
- aka_OP: OPerator variant key
- aka_AMF: Authentication Management Field (indicates the algorithm and key in use)

In case you want to use authentication with a different username/password or aka_K for each call, you can do this:

Make a CSV like this:
And an XML like this (the [field1] will be substituted with the full auth string, which is the processed as a new keyword): From: Contact: ;transport=[transport] [field1] Expires: 300 Call-ID: [call_id] CSeq: 2 REGISTER Content-Length: 0 ]]]]> ]]>

Example:

auth="true" ;tag=[call_number] To: sut [peer_tag_param] Call-ID: [call_id] CSeq: 1 ACK Contact: sip:sipp@[local_ip]:[local_port] Max-Forwards: 70 Subject: Performance Test Content-Length: 0 ]]]]> ;tag=[call_number] To: sut Call-ID: [call_id] CSeq: 2 INVITE Contact: sip:sipp@[local_ip]:[local_port] ]]>[authentication username=foouser] ]]>

Screens

Several screens are available to monitor SIP traffic. You can change the screen view by pressing 1 to 9 keys on the keyboard.

Key '1': Scenario screen. It displays a call flow of the scenario as well as some important informations.
Key '2': Statistics screen. It displays the main statistics counters. The "Cumulative" column gather all statistics, since SIPp has been launched. The "Periodic" column gives the statistic value for the period considered (specified by -f frequency command line parameter).
Key '3': Repartition screen. It displays the distribution of response time and call length, as specified in the scenario.
Key '4': Variables screen. It displays informations on actions in scenario as well as scenario variable informations.

Transport modes

SIPp has several transport modes. The default transport mode is "UDP mono socket".

UDP mono socket

In UDP mono socket mode (-t u1 command line parameter), one IP/UDP socket is opened between SIPp and the remote. All calls are placed using this socket.

This mode is generally used for emulating a relation between 2 SIP servers.

UDP multi socket

In UDP multi socket mode (-t un command line parameter), one IP/UDP socket is opened for each new call between SIPp and the remote.

This mode is generally used for emulating user agents calling a SIP server.

UDP with one socket per IP address

In UDP with one socket per IP address mode (-t ui command line parameter), one IP/UDP socket is opened for each IP address given in the inf file.

In addition to the "-t ui" command line parameter, one must indicate which field in the inf file is to be used as local IP address for this given call. Use "-ip_field <nb>" to provide the field number.

There are two distinct cases to use this feature:

Client side: when using -t ui for a client, SIPp will originate each call with a different IP address, as provided in the inf file. In this case, when your IP addresses are in field X of the inject file, then you have to use [fieldX] instead of [local_ip] in your UAC XML scenario file.
Server side: when using -t ui for a server, SIPp will bind itself to all the IP addresses listed in the inf file instead of using 0.0.0.0. This will have the effect SIPp will answer the request on the same IP on which it received the request. In order to have proper Contact and Via fields, a keyword [server_ip] can be used and provides the IP address on which a request was received. So when using this, you have to replace the [local_ip] in your UAS XML scenario file by [server_ip].

In the following diagram, the command line for a client scenario will look like: ./sipp -sf myscenario.xml -t ui -inf database.csv -ip_field 2 192.168.1.1
By doing so, each new call will come sequentially from IP 192.168.0.1, 192.168.0.2, 192.168.0.3, 192.168.0.1, ...

One originating IP per call

This mode is generally used for emulating user agents, using on IP address per user agent and calling a SIP server.

TCP mono socket

In TCP mono socket mode (-t t1 command line parameter), one IP/TCP socket is opened between SIPp and the remote. All calls are placed using this socket.

This mode is generally used for emulating a relation between 2 SIP servers.

TCP multi socket

In TCP multi socket mode (-t tn command line parameter), one IP/TCP socket is opened for each new call between SIPp and the remote.

This mode is generally used for emulating user agents calling a SIP server.

TCP reconnections

SIPp handles TCP reconnections. In case the TCP socket is lost, SIPp will try to reconnect. The following parameters on the command line control this behaviour:

-max_reconnect: Set the maximum number of reconnection attempts.
-reconnect_close true/false: Should calls be closed on reconnect?
-reconnect_sleep int: How long to sleep (in milliseconds) between the close and reconnect?

TLS mono socket

In TLS mono socket mode (-t l1 command line parameter), one secured TLS (Transport Layer Security) socket is opened between SIPp and the remote. All calls are placed using this socket.

This mode is generally used for emulating a relation between 2 SIP servers.

When using TLS transport, SIPp will expect to have two files in the current directory: a certificate (cacert.pem) and a key (cakey.pem). If one is protected with a password, SIPp will ask for it.

SIPp supports X509's CRL (Certificate Revocation List). The CRL is read and used if -tls_crl command line specifies a CRL file to read.

TLS multi socket

In TLS multi socket mode (-t ln command line parameter), one secured TLS (Transport Layer Security) socket is opened for each new call between SIPp and the remote.

This mode is generally used for emulating user agents calling a SIP server.

IPv6 support

SIPp includes IPv6 support. To use IPv6, just specify the local IP address (-i command line parameter) to be an IPv6 IP address.

The following example launches a UAS server listening on port 5063 and a UAC client sending IPv6 traffic to that port.

The Pcap play feature may currently not work on IPv6.

Multi-socket limit

When using one of the "multi-socket" transports, the maximum number of sockets that can be opened (which corresponds to the number of simultaneous calls) will be determined by the system (see how to increase file descriptors section to modify those limits). You can also limit the number of socket used by using the -max_socket command line option. Once the maximum number of opened sockets is reached, the traffic will be distributed over the sockets already opened.

Handling media with SIPp

SIPp is originally a signalling plane traffic generator. There is a limited support of media plane (RTP).

RTP echo

The "RTP echo" feature allows SIPp to listen to one or two local IP address and port (specified using -mi and -mp command line parameters) for RTP media. Everything that is received on this address/port is echoed back to the sender.

RTP/UDP packets coming on this port + 2 are also echoed to their sender (used for sound and video echo).

PCAP Play

The PCAP play feature makes use of the PCAP library to replay pre-recorded RTP streams towards a destination. RTP streams can be recorded by tools like Wireshark (formerly known as Ethereal) or tcpdump. This allows you to:

Play any RTP stream (voice, video, voice+video, out of band DTMFs/RFC 2833, T38 fax, ...)
Use any codec as the codec is not handled by SIPp
Emulate precisely the behavior of any SIP equipment as the pcap play will try to replay the RTP stream as it was recorded (limited to the performances of the system).
Reproduce exactly what has been captured using an IP sniffer like Wireshark.

A good example is the UAC with media (uac_pcap) embedded scenario.

SIPp comes with a G711 alaw pre-recorded pcap file and out of band (RFC 2833) DTMFs in the pcap/ directory.

The PCAP play feature uses pthread_setschedparam calls from pthread library. Depending on the system settings, you might need to be root to allow this. Please check "man 3 pthread_setschedparam" man page for details

More details on the possible PCAP play actions can be found in the action reference section.

The latest info on this feature, tips and tricks can be found on SIPp wiki.

Exit codes

To ease automation of testing, upon exit (on fatal error or when the number of asked calls (-m command line option) is reached, sipp exits with one of the following exit codes:

0: All calls were successful
1: At least one call failed
97: exit on internal command. Calls may have been processed. Also exit on global timeout (see -timeout_global option)
99: Normal exit without calls processed
-1: Fatal error

Depending on the system that SIPp is running on, you can echo this exit code by using "echo ?" command.

Statistics

Response times

Response times can be gathered and reported. SIPp has 5 timers (the number is set at compile time) used to compute time between two SIPp commands (send, recv or nop). You can start a timer by using the start_rtd attribute and stop it using the rtd attribute.

You can view the value of those timers in the SIPp interface by pressing 3, 6, 7, 8 or 9. You can also save the values in a CSV file using the -trace_stat option (see below).

If the -trace_rtt option is set, the response times are also dumped in the >scenario file name<_>pid<_rtt.csv.

Each line represents a RTD measure (triggered by a message reception with a rtd="n" attribute). The dump frequency is tuned by the -rtt_freq parameter.

Available counters

The -trace_stat option dumps all statistics in the scenario_name_pid.csv file. The dump starts with one header line with all counters. All following lines are 'snapshots' of statistics counter given the statistics report frequency (-fd option). When SIPp exits, the last values of the statistics are also dumped in this file.

This file can be easily imported in any spreadsheet application, like Excel.

In counter names, (P) means 'Periodic' - since last statistic row and (C) means 'Cumulated' - since sipp was started.

Available statistics are:

StartTime: Date and time when the test has started.
LastResetTime: Date and time when periodic counters where last reseted.
CurrentTime: Date and time of the statistic row.
ElapsedTime: Elapsed time.
CallRate: Call rate (calls per seconds).
IncomingCall: Number of incoming calls.
OutgoingCall: Number of outgoing calls.
TotalCallCreated: Number of calls created.
CurrentCall: Number of calls currently ongoing.
SuccessfulCall: Number of successful calls.
FailedCall: Number of failed calls (all reasons).
FailedCannotSendMessage: Number of failed calls because Sipp cannot send the message (transport issue).
FailedMaxUDPRetrans: Number of failed calls because the maximum number of UDP retransmission attempts has been reached.
FailedUnexpectedMessage: Number of failed calls because the SIP message received is not expected in the scenario.
FailedCallRejected: Number of failed calls because of Sipp internal error. (a scenario sync command is not recognized or a scenario action failed or a scenario variable assignment failed).
FailedCmdNotSent: Number of failed calls because of inter-Sipp communication error (a scenario sync command failed to be sent).
FailedRegexpDoesntMatch: Number of failed calls because of regexp that doesn't match (there might be several regexp that don't match during the call but the counter is increased only by one).
FailedRegexpHdrNotFound: Number of failed calls because of regexp with hdr option but no matching header found.
FailedOutboundCongestion: Number of failed outgoing calls because of TCP congestion.
FailedTimeoutOnRecv: Number of failed calls because of a recv timeout statement.
FailedTimeoutOnSend: Number of failed calls because of a send timeout statement.
OutOfCallMsgs: Number of SIP messages received that cannot be associated with an existing call.
Retransmissions: Number of SIP messages being retransmitted.
AutoAnswered: Number of unexpected specific messages received for new Call-ID. The message has been automatically answered by a 200 OK Currently, implemented for 'PING' message only.

The counters defined in the scenario are also dumped in the stat file (GenericCounter columns).

In addition, two other statistics are gathered:

ResponseTime (see previous section)
CallLength: this is the time of the duration of an entire call.

Both ResponseTime and CallLength statistics can be tuned using ResponseTimeRepartition and CallLengthRepartition commands in the scenario.

The standard deviation (STDev) is also available in the log stat file for these two statistics.

Importing statistics in spreadsheet applications

Example: importation in Microsoft Excel

Here is a video (Windows Media Player 9 codec or above required) on how to import CSV statistic files in Excel and create a graph of failed calls over time.

sipp-02.wmv

Error handling

SIPp has advanced feature to handle errors and unexpected events. They are detailed in the following sections.

Unexpected messages

When a SIP message that can be correlated to an existing call (with the Call-ID: header) but is not expected in the scenario is received, SIPp will send a CANCEL message if no 200 OK message has been received or a BYE message if a 200 OK message has been received. The call will be marked as failed. If the unexpected message is a 4XX or 5XX, SIPp will send an ACK to this message, close the call and mark the call as failed.
When a SIP message that can't be correlated to an existing call (with the Call-ID: header) is received, SIPp will send a BYE message. The call will not be counted at all.
When a SIP "PING" message is received, SIPp will send an ACK message in response. This message is not counted as being an unexpected message. But it is counted in the "AutoAnswered" statistic counter.
An unexpected message that is not a SIP message will be simply dropped.

Retransmissions (UDP only)

A retransmission mechanism exists in UDP transport mode. To activate the retransmission mechanism, the "send" command must include the "retrans" attribute.

When it is activated and a SIP message is sent and no ACK or response is received in answer to this message, the message is re-sent.

The retransmission mechanism follows RFC 3261, section 17.1.1.2. Retransmissions are differentiated between INVITE and non-INVITE methods.

<send retrans="500">: will initiate the T1 timer to 500 milliseconds.

Even if retrans is specified in your scenarios, you can override this by using the -nr command line option to globally disable the retransmission mechanism.

Log files

There are several ways to trace what is going on during your SIPp runs.

You can log sent and received SIP messages in <name_of_the_scenario>_<pid>_messages.log by using the command line parameter -trace_msg. The messages are time-stamped so that you can track them back.
You also can trace it using the -trace_shortmsg parameter. This logs the most important values of a message as CSV into one line of the <scenario file name>_<pid>_shortmessages.log
You can trace all unexpected messages or events in <name_of_the_scenario>_<pid>_errors.log by using the command line parameter -trace_err.
You can save in a file the statistics screens, as displayed in the interface. This is especially useful when running SIPp in background mode.
This can be done in different ways:
- When SIPp exits to get a final status report (-trace_screen option)
- On demand by using USR2 signal (example: kill -SIGUSR2 738)
- By pressing 's' key (if -trace_screen option is set)

Online help (-h)

The online help, available through the -h option is duplicated here for your convenience