diff --git a/docs/3PCC_extended.rst b/docs/3PCC_extended.rst index 8408bc58..d3fc89e8 100644 --- a/docs/3PCC_extended.rst +++ b/docs/3PCC_extended.rst @@ -10,29 +10,24 @@ mode. The others are launched in "slave" mode. Slave 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: +``-slave_cfg`` command line argument), in the following format:: -:: - - - s1;127.0.0.1:8080 - s2;127.0.0.1:7080 - m;127.0.0.1:6080 + s1;127.0.0.1:8080 + s2;127.0.0.1:7080 + m;127.0.0.1:6080 Each SIPp instance must access a different copy of this file. -sendCmd and recvCmd have additional attributes: - -:: +sendCmd and recvCmd have additional attributes:: + + ]]> @@ -66,4 +61,4 @@ 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. -.. image:: master_slave.png \ No newline at end of file +.. image:: master_slave.png diff --git a/docs/3pcc-C-A.xml b/docs/3pcc-C-A.xml index f366eaa8..799b40cf 100644 --- a/docs/3pcc-C-A.xml +++ b/docs/3pcc-C-A.xml @@ -58,9 +58,9 @@ - + @@ -71,16 +71,16 @@ ]]> - + - + - + - + - + @@ -68,13 +68,13 @@ - + - - + + - + diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css index 55ae8a3e..2640f1f9 100644 --- a/docs/_static/theme_overrides.css +++ b/docs/_static/theme_overrides.css @@ -46,7 +46,7 @@ span.menuselection { color: blue; - font-family: monospace, "Courier New", Courier + font-family: monospace, "Courier New", Courier } code.kbd, code.kbd span { diff --git a/docs/controlling.rst b/docs/controlling.rst index 65812d21..9c83d6da 100644 --- a/docs/controlling.rst +++ b/docs/controlling.rst @@ -9,19 +9,19 @@ and also a simple command mode. The hot keys are: ===== ====== Key Action ===== ====== -\+ Increase the call rate by 1 * rate_scale -\* Increase the call rate by 10 * rate_scale -\- Decrease the call rate by 1 * rate_scale -/ Decrease the call rate by 10 * rate_scale -c Enter command mode -q Quit SIPp (after all calls complete, enter a second time to quit immediately) -Q Quit SIPp immediately s Dump screens to the log file (if -trace_screen is passed) -p Pause traffic -1 Display the scenario screen -2 Display the statistics screen -3 Display the repartition screen -4 Display the variable screen -5 Display the TDM screen +\+ Increase the call rate by 1 * rate_scale +\* Increase the call rate by 10 * rate_scale +\- Decrease the call rate by 1 * rate_scale +/ Decrease the call rate by 10 * rate_scale +c Enter command mode +q Quit SIPp (after all calls complete, enter a second time to quit immediately) +Q Quit SIPp immediately s Dump screens to the log file (if -trace_screen is passed) +p Pause traffic +1 Display the scenario screen +2 Display the statistics screen +3 Display the repartition screen +4 Display the variable screen +5 Display the TDM screen 6-9 Display the second through fifth repartition screen. ===== ====== @@ -35,14 +35,14 @@ commands are available: List of Interactive Commands ```````````````````````````` -- ``dump tasks`` Prints a list of active tasks (most tasks are calls) to the error log. dump tasks -- ``set rate X`` Sets the call rate. set rate 10 -- ``set rate-scale X`` Sets the rate scale, which adjusts the speed of '+', '-', '*', and '/'. set rate-scale 10 -- ``set users X`` Sets the number of users (only valid when -users is specified). set rate 10 -- ``set limit X`` Sets the open call limit (equivalent to -l option) set limit 100 -- ``set hide `` Should the hide XML attribute be respected? set hide false -- ``set index `` Display message indexes in the scenario screen. set index true -- ``set display `` Changes the scenario that is displayed to either the main or the out-of-call scenario. set display main set display ooc +- ``dump tasks`` Prints a list of active tasks (most tasks are calls) to the error log. dump tasks +- ``set rate X`` Sets the call rate. set rate 10 +- ``set rate-scale X`` Sets the rate scale, which adjusts the speed of '+', '-', '*', and '/'. set rate-scale 10 +- ``set users X`` Sets the number of users (only valid when -users is specified). set rate 10 +- ``set limit X`` Sets the open call limit (equivalent to -l option) set limit 100 +- ``set hide `` Should the hide XML attribute be respected? set hide false +- ``set index `` Display message indexes in the scenario screen. set index true +- ``set display `` Changes the scenario that is displayed to either the main or the out-of-call scenario. set display main set display ooc - ``trace `` Turns log on or off at run time. Valid values for log are "error", "logs", "messages", and "shortmessages". trace error on @@ -75,7 +75,7 @@ the command line: + "-r" to specify the call rate in number of calls per seconds + "-rp" to specify the " r ate p eriod" 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). + milliseconds (by using -r n -rp m). .. note:: Example: run SIPp at 7 calls every 2 seconds (3.5 calls per second) @@ -154,4 +154,4 @@ minute and exit SIPp: To send a command to SIPp, preface it with 'c'. For example: ``echo -"cset rate 100" >/dev/udp/127.0.0.1/8888 sets the call rate to 100.`` \ No newline at end of file +"cset rate 100" >/dev/udp/127.0.0.1/8888 sets the call rate to 100.`` diff --git a/docs/foreword.rst b/docs/foreword.rst index 07afa8b1..a3bc047d 100644 --- a/docs/foreword.rst +++ b/docs/foreword.rst @@ -25,5 +25,3 @@ Want to see it? Here is a screenshot .. figure:: sipp-01.jpg - - \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index d5893fb4..34fdd499 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,7 +23,6 @@ Welcome to SIPp reference documentation! error perftest tools - diff --git a/docs/installation.rst b/docs/installation.rst index 0e51e770..14f0b877 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -58,7 +58,8 @@ Installing SIPp + On Linux, SIPp is provided in the form of source code. You will need to compile SIPp to actually use it. -+ Pre-requisites to compile SIPp are : + ++ Pre-requisites to compile SIPp are: + C++ Compiler + curses or ncurses library @@ -69,68 +70,48 @@ Installing SIPp + You have four options to compile SIPp: - + Without TLS (Transport Layer Security), SCTP or PCAP support : - - This is the recommended setup if you don't need to handle SCTP, TLS or - PCAP. - -:: - - # tar -xvzf sipp-xxx.tar - # cd sipp - # ./configure - # make - - - -+ With TLS support, - you must have installed `OpenSSL library`_ (>=0.9.8) (which may come - with your system). Building SIPp consists only in adding the "--with-openssl" - option to the configure command: - -:: - - # tar -xvzf sipp-xxx.tar.gz - # cd sipp - # ./configure --with-openssl - # make - - - -+ With PCAP play support : - -:: - - # tar -xvzf sipp-xxx.tar.gz - # cd sipp - # ./configure --with-pcap - # make - + + Without TLS (Transport Layer Security), SCTP or PCAP support -- + this is the recommended setup if you don't need to handle SCTP, TLS or + PCAP:: + tar -xvzf sipp-xxx.tar + cd sipp + ./configure + make -+ With SCTP support : + + With TLS support, you must have installed `OpenSSL library`_ + (>=0.9.8) (which may come with your system). Building SIPp + consists only of adding the ``--with-openssl`` option to the + configure command:: -:: + tar -xvzf sipp-xxx.tar.gz + cd sipp + ./configure --with-openssl + make - # tar -xvzf sipp-xxx.tar.gz - # cd sipp - # ./configure --with-sctp - # make - + + With PCAP play support:: + tar -xvzf sipp-xxx.tar.gz + cd sipp + ./configure --with-pcap + make -+ You can also combine these various options, e.g.: : + + With SCTP support:: -:: + tar -xvzf sipp-xxx.tar.gz + cd sipp + ./configure --with-sctp + make - # tar -xvzf sipp-xxx.tar.gz - # cd sipp - # ./configure --with-sctp --with-pcap --with-openssl - # make - + + You can also combine these various options, e.g.:: + tar -xvzf sipp-xxx.tar.gz + cd sipp + ./configure --with-sctp --with-pcap --with-openssl + make -.. warning:: +.. warning:: SIPp compiles under CYGWIN on Windows, provided that you installed IPv6 extension for `CYGWIN `_, as well as libncurses and (optionally OpenSSL and WinPcap). SCTP is not @@ -148,4 +129,4 @@ Installing SIPp .. _WinPcap developer package: http://www.winpcap.org/devel.htm .. _hewlett-packard: http://www.hp.com/ .. _SIPp's master tree: https://github.com/SIPp/sipp/tree/master -.. _OpenSSL library: http://www.openssl.org/ \ No newline at end of file +.. _OpenSSL library: http://www.openssl.org/ diff --git a/docs/int_scenarios.rst b/docs/int_scenarios.rst index 68c2378e..304e153b 100644 --- a/docs/int_scenarios.rst +++ b/docs/int_scenarios.rst @@ -136,18 +136,18 @@ this section. :: - REGISTER ----------> - 200 <---------- - 200 <---------- - INVITE ----------> - 100 <---------- - 180 <---------- - 403 <---------- - 200 <---------- - ACK ----------> - [ 5000 ms] - BYE ----------> - 200 <---------- + REGISTER ----------> + 200 <---------- + 200 <---------- + INVITE ----------> + 100 <---------- + 180 <---------- + 403 <---------- + 200 <---------- + ACK ----------> + [ 5000 ms] + BYE ----------> + 200 <---------- @@ -174,32 +174,30 @@ or -oocsn command line options. 3PCC ```` -3PCC stands for 3rd Party Call Control. 3PCC is described in +3PCC stands for 3rd Party Call Control. 3PCC is described in :rfc:`3725`. While this feature was first developed 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 being a controller): - -:: - - A Controller B - |(1) INVITE no SDP | | - |<------------------| | - |(2) 200 offer1 | | - |------------------>| | - | |(3) INVITE offer1 | - | |------------------>| - | |(4) 200 OK answer1 | - | |<------------------| - | |(5) ACK | - | |------------------>| - |(6) ACK answer1 | | - |<------------------| | - |(7) RTP | | - |.......................................| +flows, like call flow I (SIPp being a controller):: + + A Controller B + |(1) INVITE no SDP | | + |<------------------| | + |(2) 200 offer1 | | + |------------------>| | + | |(3) INVITE offer1 | + | |------------------>| + | |(4) 200 OK answer1 | + | |<------------------| + | |(5) ACK | + | |------------------>| + |(6) ACK answer1 | | + |<------------------| | + |(7) RTP | | + |.......................................| Scenario file: :download:`3pcc-A.xml <3pcc-A.xml>` @@ -218,55 +216,48 @@ 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): - -:: - - - A Controller A Controller B B - |(1) INVITE no SDP | | | - |<------------------| | | - |(2) 200 offer1 | | | - |------------------>| | | - | sendCmd (offer1) | | - | |----------------->| | - | | recvCmd | - | | |(3) INVITE offer1 | - | | |------------------>| - | | |(4) 200 OK answer1 | - | | |<------------------| - | | sendCmd | - | | (answer1) | | - | |<-----------------| | - | recvCmd |(5) ACK | - | | |------------------>| - |(6) ACK answer1 | | | - |<------------------| | | - |(7) RTP | | | - |..........................................................| +been divided in two SIPp instances):: + + A Controller A Controller B B + |(1) INVITE no SDP | | | + |<------------------| | | + |(2) 200 offer1 | | | + |------------------>| | | + | 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 information 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 command. This: - -:: +scenarios through the 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: - -:: +calls. In the same manner, this:: + - ;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] - - ]]> - + ACK sip:[service]@[remote_ip]:[remote_port] SIP/2.0 + Via: SIP/2.0/[transport] [local_ip]:[local_port] + From: sipp ;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 @@ -313,5 +302,3 @@ feature is the following: + 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. - - diff --git a/docs/regexp.xml b/docs/regexp.xml index 32b29719..45d585cd 100644 --- a/docs/regexp.xml +++ b/docs/regexp.xml @@ -82,18 +82,18 @@ - - diff --git a/docs/scenarios/actions.rst b/docs/scenarios/actions.rst index 4b0641e6..cf9ba15f 100644 --- a/docs/scenarios/actions.rst +++ b/docs/scenarios/actions.rst @@ -44,32 +44,32 @@ regexp action syntax ```````````````````` ================ ======= =========== -Keyword Default Description +Keyword Default Description ================ ======= =========== regexp None Contains the regexp to use for - matching the received message or header. MANDATORY. + matching the received message or header. MANDATORY. search_in msg can have four values: "msg" (try to match against the entire message), "hdr" (try to match against a specific SIP header), "body" (try to match against the SIP message body), or "var" (try to match against a - SIPp string variable). + SIPp string variable). 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. + is equal to hdr. variable None Variable to try to match against. Only used when the search_in tag is set to var. MANDATORY IF search_in is - equal to var. + equal to var. case_indep false To look for a header ignoring case . - Only used when the search_in tag is set to hdr. + Only used when the search_in tag is set to hdr. occurrence 1 To find the nth occurrence of a header. Only used when the search_in tag is set - to hdr. + to hdr. start_line false To look only at start of line. Only used when - the search_in tag is set to hdr. + 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. Can not be - combined with check_it_inverse. + combined with check_it_inverse. check_it_inverse false Inverse of check_it. iff set to true, the call is marked as failed if the regexp - does match. Can not be combined with check_it. + does match. Can not be combined with check_it. 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 @@ -78,7 +78,7 @@ assign_to None contain 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. + variables contain the sub-expressions matching. ================ ======= =========== Example for assign_to @@ -86,9 +86,9 @@ Example for assign_to :: + search_in="msg" + check_it=i"true" + assign_to="3,4,5,8"/> If the SIP message contains the line @@ -116,11 +116,8 @@ The following example is used to: + Extract the Contact: header of the received SIP message + Assign the extracted Contract: header to variable 6. - - :: - @@ -140,22 +137,18 @@ is expanded to reflect the value actually used. .. warning:: Logs are generated only if -trace_logs option is set on the command line. -Example: +Example:: -:: - - - - - - - + + + + + + You can use the alternative "warning" action to log a message to -SIPp's error log. For example: - -:: +SIPp's error log. For example:: @@ -176,15 +169,13 @@ 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: +response:: -:: - - - - - - + + + + + @@ -194,15 +185,13 @@ 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: +Example that execute a system echo for every INVITE received:: -:: - - - - - - + + + + + @@ -252,9 +241,7 @@ play_pcap_audio="[file_to_play]" with: pcap_play_video command, and vice versa; you cannot play both audio and video streams at once. -Example that plays a pre-recorded RTP stream: - -:: +Example that plays a pre-recorded RTP stream:: @@ -284,10 +271,8 @@ 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: - -:: +For example, to assign the value 1.0 to ``$1`` and sample from the +normal distribution into ``$2``:: @@ -305,9 +290,7 @@ distribution into $2: Simple arithmetic is also possible using the , , , and 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: - -:: +For example, the following action modifies variable one as follows:: @@ -317,21 +300,20 @@ 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 parameter. For example: - -:: +operand from a variable, using the parameter. For example:: - - - - - - + + + + + + @@ -341,32 +323,28 @@ String Variables You can create string variables by using the 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: - -:: +example:: - - - - - + + + + + A string variable and a value can be compared using the action. The result is a double value, that is less than, equal to, or greater than zero if the variable is lexographically less than, equal to, or greater than the value. The parameters are assign_to, variable, -and value. For example: - -:: +and value. For example:: - - - - - + + + + + @@ -380,9 +358,7 @@ 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: - -:: +Example that sets ``$2`` to true if ``$1`` is less than 10:: @@ -422,29 +398,25 @@ in-memory version of an injection file (there is presently no way to update the disk-based version). The insert action takes two parameters: file and value, and the replace action takes an additional line value. For example, to inserting a new line can be accomplished -as follows: - -:: +as follows:: - - - + + + Replacing a line is similar, but a line number must be specified. You will probably want to use the lookup action to obtain the line number -for use with replace as follows: - -:: +for use with replace as follows:: - - - - - + + + + + @@ -460,9 +432,7 @@ special label named "_unexp.main" in the scenario, SIPp will jump to that label whenever an unexpected message is received and store the previous address in the variable named "_unexp.retaddr". -Example that jumps to index 5: - -:: +Example that jumps to index 5:: @@ -472,9 +442,7 @@ Example that jumps to index 5: Example that jumps to the index contained in the variable named -_unexp.retaddr: - -:: +_unexp.retaddr:: @@ -488,9 +456,7 @@ gettimeofday ++++++++++++ The gettimeofday action allows you to get the current time in seconds -and microseconds since the epoch. For example: - -:: +and microseconds since the epoch. For example:: @@ -515,17 +481,16 @@ connects to the value specified in the [next_url] keyword. :: - - - - - - - - + + + + + + + -:: warning.. +.. warning:: If you are using setdest with IPv6, you must not use square brackets around the address. These have a special meaning to SIPp, and it will try to interpret your IPv6 address as a variable. @@ -541,43 +506,40 @@ message against a provided username and password. The result of the check is stored in a boolean variable. This allows you to simulate a server which requires authorization. Currently only simple MD5 digest authentication is supported. Before using the verifyauth action, you -must send a challenge. For example: +must send a challenge. For example:: -:: + + + - - WWW-Authenticate: Digest realm="test.example.com", nonce="47ebe028cda119c35d4877b383027d28da013815" - Content-Length: [len] - - ]]> - + SIP/2.0 401 Authorization Required + [last_Via:] + [last_From:] + [last_To:];tag=[pid]SIPpTag01[call_number] + [last_Call-ID:] + [last_CSeq:] + Contact: + WWW-Authenticate: Digest realm="test.example.com", nonce="47ebe028cda119c35d4877b383027d28da013815" + Content-Length: [len] + + ]]> + After receiving the second request, you can extract the username provided and compare it against a list of user names and passwords provided as an injection file, and take the appropriate action based -on the result: - -:: +on the result:: - - - - - - - - - - -.. _PCAP library: http://www.tcpdump.org/pcap3_man.html \ No newline at end of file + + + + + + + + + + +.. _PCAP library: http://www.tcpdump.org/pcap3_man.html diff --git a/docs/scenarios/init_stanza.rst b/docs/scenarios/init_stanza.rst index 034986d4..38327d79 100644 --- a/docs/scenarios/init_stanza.rst +++ b/docs/scenarios/init_stanza.rst @@ -12,18 +12,17 @@ line parameter). :: - - - - - - - - - - - - - + + + + + + + + + + + + diff --git a/docs/scenarios/inject_from_csv.rst b/docs/scenarios/inject_from_csv.rst index 104251d7..d0fee124 100644 --- a/docs/scenarios/inject_from_csv.rst +++ b/docs/scenarios/inject_from_csv.rst @@ -6,9 +6,7 @@ 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: - -:: +referred as [field0], [field1], ... in the xml scenario file. Example:: SEQUENTIAL #This line will be ignored @@ -28,9 +26,7 @@ the end of the file, SIPp will re-start from the beginning. The file is not limited in size. You can override the default line selection strategy with the optional -line argument. For example: - -:: +line argument. For example:: [field0 line=1] @@ -53,11 +49,8 @@ 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: +file= parameter to the keyword. For example:: -:: - - INVITE sip:[field0 file="callee.csv"] SIP/2.0 From: sipp user <[field0 file="caller.csv"]>;tag=[pid]SIPpTag00[call_number] To: sut user <[field0 file="callee.csv"]> @@ -73,30 +66,24 @@ PRINTF Injection files ++++++++++++++++++++++ An extension of the standard injection file is a "PRINTF" injection -file. Often, an input file will has a repetitive nature such as: +file. Often, an input file will has a repetitive nature such as:: -:: + USERS + user000;password000 + user001;password001 + ... + user999;password999 - - USERS - user000;password000 - user001;password001 - ... - user999;password999 - SIPp must maintain this structure in memory, which can reduce performance for very large injection files. To eliminate this problem, SIPp can automatically generate such a structured file based on one or -more template lines. For example: +more template lines. For example:: -:: + USERS,PRINTF=999 + user%03d;password%03d - - USERS,PRINTF=999 - user%03d;password%03d - Has the same logical meaning as the original example, yet SIPp only @@ -104,28 +91,21 @@ needs to store one entry in memory. Each time a line is used; SIPp will replace %d with the requested line number (starting from zero). Standard printf format decimal specifiers can be used. When more than one template line is available, SIPp cycles through them. This -example: +example:: -:: + USERS,PRINTF=4 + user%03d;password%03d;Foo + user%03d;password%03d;Bar - - USERS,PRINTF=4 - user%03d;password%03d;Foo - user%03d;password%03d;Bar - -Is equivalent to the following injection file: +Is equivalent to the following injection file:: -:: - - - USERS - user000;password000;Foo - user001;password001;Bar - user002;password002;Foo - user003;password003;Bar - + USERS + user000;password000;Foo + user001;password001;Bar + user002;password002;Foo + user003;password003;Bar The following parameters are used to control the behavior of printf @@ -153,16 +133,12 @@ The -infindex option allows you to generate an index of an injection file. The arguments to -infindex are the injection file to index and the field number that should be indexed. For example if you have an injection file that contains user names and passwords (as the -following): - -:: +following):: - - USERS - alice,pass_A - bob,pass_B - carol,pass_C - + USERS + alice,pass_A + bob,pass_B + carol,pass_C You may want to extract the password for a given user in the file. To @@ -173,5 +149,3 @@ logical entries {"alice" => 0, "bob" => 1, "carol" => 2}. To extract a particular password, you can use the lookup action to store the line number into a variable (say $line) and then use the keyword[field1 line="[$line]"]. - - diff --git a/docs/scenarios/keywords.rst b/docs/scenarios/keywords.rst index 7701c6c8..1b27486e 100644 --- a/docs/scenarios/keywords.rst +++ b/docs/scenarios/keywords.rst @@ -4,59 +4,59 @@ Keyword list ``[service]`` ============= -:Default: (service) -:Description: Service field, as passed in the -s service_name +:Default: (service) +:Description: Service field, as passed in the -s service_name ``[remote_ip]`` =============== -:Description: Remote IP address, as passed on the command line. +:Description: Remote IP address, as passed on the command line. -``[remote_port]`` +``[remote_port]`` ================= :Default: 5060 -:Description: Remote IP port, as passed on the command line. - You can add a computed offset [remote_port+3] to this value. +:Description: Remote IP port, as passed on the command line. + You can add a computed offset [remote_port+3] to this value. ``[transport]`` =============== :Default: UDP -:Description: Depending on the value of -t parameter, this will take the values "UDP" or "TCP". +:Description: Depending on the value of -t parameter, this will take the values "UDP" or "TCP". -``[local_ip]`` +``[local_ip]`` ============== -:Description: (Primary host IP address) Will take the value of -i parameter. +:Description: (Primary host IP address) Will take the value of -i parameter. ``[local_ip_type]`` =================== -:Description: Depending on the address type of -i parameter (IPv4 or IPv6), +:Description: 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]`` +``[local_port]`` ================ -:Default: Chosen by the system -:Description: Will take the value of -p parameter. - You can add a computed offset [local_port+3] to this value. +:Default: Chosen by the system +:Description: Will take the value of -p parameter. + You can add a computed offset [local_port+3] to this value. -``[len]`` +``[len]`` ========== -:Description: Computed length of the SIP body. To be used in "Content-Length" header. +:Description: 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]`` ================= -:Description: Index. The call_number starts from "1" and is incremented by 1 for each call. +:Description: Index. The call_number starts from "1" and is incremented by 1 for each call. ``[cseq]`` ========== -:Description: Generates automatically the CSeq number. The initial value is 1 by default. - It can be changed by using the -base_cseq command line option. +:Description: 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]`` +``[call_id]`` ============= -:Description: 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 +:Description: 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. + '///'. Example: Call-ID: ABCDEFGHIJ///[call_id] - it will still be recognized by SIPp as part of the same call. ``[media_ip]`` =============== @@ -64,29 +64,29 @@ Keyword list ``[media_ip_type]`` =================== -:Description: Depending on the address type of -mi parameter (IPv4 or IPv6), media_ip_type +:Description: 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]`` ================ -:Description: 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. +:Description: 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]`` ===================== :Description: 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) + 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_*]`` ============ -:Description: 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 +:Description: 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. + concatenated (CRLF separated) to be used in place of the '[last_*]' keyword. ``[field0-n file= line=]`` ============================================ @@ -94,7 +94,7 @@ Keyword list values from an external CSV file. See "Injecting values from an external CSV during calls" section. The optional file and line parameters allow you to select which of the injection files specified - on the command line to use and which line number from that file. + on the command line to use and which line number from that file. ``[file name=]`` ========================== @@ -102,21 +102,21 @@ Keyword list message. Whitespace, including carriage returns and newlines at the end of the line in the file are not processed as with other keywords; thus your file must be formatted exactly as you would like the bytes - to appear in the message. + to appear in the message. ``[timestamp]`` =============== -:Description: The current time using the same format as error log messages. +:Description: The current time using the same format as error log messages. -``[last_message]`` +``[last_message]`` ================== -:Description: The last received message. +:Description: The last received message. ``[$n]`` ======== -:Description: Used to inject the value of call variable number n. See `Actions_` section +:Description: Used to inject the value of call variable number n. See `Actions_` section -``[authentication]`` +``[authentication]`` ==================== :Description: Used to put the authentication header. This field can have parameters, in the @@ -124,11 +124,11 @@ Keyword list password=mypassword]. If no username is provided, the value from the -au (authentication username) or -s (service) command line parameter is used. If no password is provided, the value from -ap command line - parameter is used. See "Authentication" section + parameter is used. See "Authentication" section ``[pid]`` ========= -:Description: Provide the process ID (pid) of the main SIPp thread. +:Description: Provide the process ID (pid) of the main SIPp thread. ``[routes]`` ============= @@ -139,24 +139,24 @@ Keyword list ============== :Description: 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) + Contact header (i.e within the '<' and '>' of Contact) ``[branch]`` ============ :Description: 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. + same branch value as a previous message. -``[msg_index]`` +``[msg_index]`` =============== -:Description: Provide the message number in the scenario. +:Description: Provide the message number in the scenario. ``[cseq]`` =========== :Description: 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). + [cseq+1] adds 1 to the CSeq value of the last request). ``[clock_tick]`` ================ @@ -169,19 +169,19 @@ Keyword list ``[tdmmap]`` ============ :Description: Includes the tdm map values used by the call in the message - (see -tdmmap option). + (see -tdmmap option). ``[fill]`` ============ :Description: 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. + of X's, but can be controlled with the text="text" parameter. ``[users]`` ============= :Description: If the -users command line option is specified, then this keyword - contains the number of users that are currently instantiated. + contains the number of users that are currently instantiated. ``[userid]`` ============= diff --git a/docs/scenarios/ownscenarios.rst b/docs/scenarios/ownscenarios.rst index 49a06df6..ab17346d 100644 --- a/docs/scenarios/ownscenarios.rst +++ b/docs/scenarios/ownscenarios.rst @@ -41,38 +41,38 @@ List of attributes common to all commands - Description - Example * - ``start_rtd`` - - Starts one of the " Response Time Duration" timer. (see statistics section). + - Starts one of the " Response Time Duration" timer. (see statistics section). - :: - + - - the timer named "invite" will start when the message is sent. + + the timer named "invite" will start when the message is sent. * - ``rtd`` - Stops one of the 5 " Response Time Duration" - :: - + - - the timer number 2 will stop when the message is sent. + + 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). + than once per call (useful for loop call flows). - :: - - - the timer number 1 value will be printed but the timer won't stop. + + + 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. + message in main SIPp screen. - :: - + * - ``next`` - - You can put a "next" + - You can put a "next" in any command element to go to another part of the script when you are done with sending the message. For optional receives, the next is only taken if that message was received. See conditional branching @@ -84,7 +84,7 @@ List of attributes common to all commands @@ -118,7 +118,7 @@ List of attributes common to all commands - 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. + conditional branching section for more info. - Example to jump to label "6" after sending an ACK only if variable 4 is set: @@ -127,7 +127,7 @@ List of attributes common to all commands @@ -153,12 +153,12 @@ List of attributes common to all commands - 90% chance to go to label "5" if variable "3" is set. + 90% chance to go to label "5" if variable "3" is set. * - ``condexec`` - Executes an element only if the variable in the condexec attribute is set. This attribute allows you to write complex XML scenarios with - fewer next attributes and labels. + fewer next attributes and labels. - :: @@ -167,16 +167,16 @@ List of attributes common to all commands * - ``condexec_inverse`` - If condexec is set, condexec_inverse inverts the condition in condexec. This allows you to execute an element only when - a variable is **not** set. + a variable is **not** set. - :: - + - * - counter + * - counter - Increments the counter given as parameter when the message is sent. The counters are saved in the - statistic file. + statistic file. - :: @@ -193,64 +193,64 @@ List of commands with their attributes :stub-columns: 0 :widths: 1 1 5 5 - * - Command - - Attribute(s) - - Description - - Example + * - Command + - Attribute(s) + - Description + - Example * - **** - - retrans + - retrans - Used for UDP transport only: it specifies the T1 timer value, as described in SIP - RFC 3261, section 17.1.1.2. + RFC 3261, section 17.1.1.2. - :: - - - + + + will initiate T1 timer to 500 milliseconds (RFC3261 default). - * - - - ``lost`` - - Emulate packet lost. The value is specified as a percentage. + * - + - ``lost`` + - Emulate packet lost. The value is specified as a percentage. - :: - - - - 10% of the message sent are actually not sent :). - * - + + + + 10% of the message sent are actually not sent :). + * - - ``start_txn`` - - Records the branch ID of this sent message so that responses - can be properly matched (without this element the transaction + - Records the branch ID of this sent message so that responses + can be properly matched (without this element the transaction matching is done based on the CSeq method, which is imprecise). - - :: - - - + - :: + + + Stores the branch ID of this message in the transaction named "invite". - * - - - ``ack_txn`` + * - + - ``ack_txn`` - Indicates that the ACK being sent corresponds to the transaction started by a start_txn attribute. Every INVITE with a start_txn tag must have a matching ACK with an ack_txn attribute. - :: - - - - References the branch ID of the transaction named "invite". + + + + References the branch ID of the transaction named "invite". * - **** - - response - - Indicates what SIP message code is expected. + - response + - Indicates what SIP message code is expected. - :: - - - - SIPp will expect a SIP message with code "200". - * - - - ``request`` + + + + SIPp will expect a SIP message with code "200". + * - + - ``request`` - Indicates what SIP message request is expected. - :: - - - - SIPp will expect an "ACK" SIP message. - * - + + + + 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 @@ -258,47 +258,47 @@ List of commands with their attributes 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. + the scenario. - :: - + - - The 100 SIP message can be received without being considered as "unexpected". - * - - - ``rrs`` + + The 100 SIP message can be received without being considered as "unexpected". + * - + - ``rrs`` - R ecord R oute S et. 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. + recalled using the ``[routes]`` keyword. - :: - + . * - - - ``auth`` + - ``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. + used to build the [authentication] keyword. - :: - - . - * - - - ``lost`` + + . + * - + - ``lost`` - Emulate packet lost. The value is specified as a - percentage. + percentage. - :: - - - - 10% of the message received are thrown away. - * - - - ``timeout`` + + + + 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. + label is defined. - :: - - - * - - - ``ontimeout`` + + + * - + - ``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: @@ -308,10 +308,10 @@ List of commands with their attributes - * - - - ``action`` + * - + - ``action`` - Specify an action when receiving the message. See Actions - section for possible actions. + section for possible actions. - Example of a "regular expression" action: :: @@ -325,12 +325,12 @@ List of commands with their attributes - * - - - ``regexp_match`` + * - + - ``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. + several cases in the same receive command. - Example of a recv command that matches MESSAGE or PUBLISH or SUBSCRIBE requests: :: @@ -338,47 +338,47 @@ List of commands with their attributes - * - - - ``response_txn`` + * - + - ``response_txn`` - Indicates that this is a response to a transaction that was previously started. To match, the branch ID of the first via - header must match the stored transaction ID. + header must match the stored transaction ID. - :: - + - - Matches only responses to the message sent with start_txn="invite" - attribute. - * - ```` - - milliseconds + + Matches only responses to the message sent with start_txn="invite" + attribute. + * - ```` + - milliseconds - Specify the pause delay, in milliseconds. When this delay is not set, the value of - the -d command line parameter is used. + the -d command line parameter is used. - :: - + - - pause the scenario for 5 seconds. - * - - - ``variable`` - - Indicates which call variable to use to determine the length of the pause. + + pause the scenario for 5 seconds. + * - + - ``variable`` + - Indicates which call variable to use to determine the length of the pause. - :: - - - + + + pauses for the number of milliseconds specified by - call variable 1. - * - - - ``distribution`` + 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. + supply distribution specific parameters. - The following examples show the various types of distributed pauses: - + + pauses for 1 second. - + + pauses between 2 and 5 seconds. @@ -390,7 +390,7 @@ List of commands with their attributes 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: - + .. figure:: dist_normal.gif + creates a @@ -423,21 +423,21 @@ List of commands with their attributes `Negative Binomial on Wikipedia`_ for a description of the distribution). - * - - - ``sanity_check`` + * - + - ``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. - - :: - + INT_MAX. Setting sanity_check to false disables this behavior. + - :: + - - disables sanity checking of the lognormal distribution. + + disables sanity checking of the lognormal distribution. * - **** - 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. + actions. - Execute the play_pcap_audio/video action: :: @@ -459,26 +459,26 @@ List of commands with their attributes - * - - - ``dest`` + * - + - ``dest`` - 3pcc extended mode only: the twin sipp instance which the command - will be sent to + will be sent to - :: - + - - the command will be sent to the "s1" twin instance - * - **** - - ``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 + + the command will be sent to the "s1" twin instance + * - **** + - ``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: - + :: @@ -489,62 +489,62 @@ List of commands with their attributes - * - - - ``src`` + * - + - ``src`` - 3pcc extended mode only: indicate the twin sipp instance which the - command is expected to be received from - - :: - - - + command is expected to be received from + - :: + + + the command will be expected to be received from the "s1" twin instance - * - **