SIPp

https://sipp.readthedocs.io/en/latest
Admin
SIPp is an open-source test tool for the SIP protocol, designed for performance testing, simulating...
Tokens:16,772
Snippets:239
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Launch SIPp with IPv6 support

Source: https://sipp.readthedocs.io/en/latest/transport.html

Example commands to start a UAS server and a UAC client using IPv6 addresses.

```bash
./sipp -sn uas -i [fe80::204:75ff:fe4d:19d9] -p 5063
./sipp -sn uac -i [fe80::204:75ff:fe4d:19d9] [fe80::204:75ff:fe4d:19d9]:5063
```

--------------------------------

### SIP authentication flow example

Source: https://sipp.readthedocs.io/en/latest/scenarios/sipauth.html

Handle a 407 challenge and re-send an INVITE with authentication credentials.

```xml
<recv response="407" auth="true">
</recv>

<send>
  <![CDATA[

    ACK sip:[service]@[remote_ip]:[remote_port] SIP/2.0
    Via: SIP/2.0/[transport] [local_ip]:[local_port]
    From: sipp <sip:sipp@[local_ip]:[local_port]>;tag=[call_number]
    To: sut <sip:[service]@[remote_ip]:[remote_port]>[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

  ]]>
</send>

<send retrans="500">
  <![CDATA[

    INVITE sip:[service]@[remote_ip]:[remote_port] SIP/2.0
    Via: SIP/2.0/[transport] [local_ip]:[local_port]
    From: sipp <sip:sipp@[local_ip]:[local_port]>;tag=[call_number]
    To: sut <sip:[service]@[remote_ip]:[remote_port]>
    Call-ID: [call_id]
    CSeq: 2 INVITE
    Contact: sip:sipp@[local_ip]:[local_port]
    [authentication username=foouser]
    Max-Forwards: 70
    Subject: Performance Test
    Content-Type: application/sdp
    Content-Length: [len]

    v=0
    o=user1 53655765 2353687637 IN IP[local_ip_type] [local_ip]
    s=-
    t=0 0
    c=IN IP[media_ip_type] [media_ip]
    m=audio [media_port] RTP/AVP 0
    a=rtpmap:0 PCMU/8000

  ]]>
</send>
```

--------------------------------

### Run SIPp scenarios

Source: https://sipp.readthedocs.io/en/latest/sipp.html

Commands to start the embedded server (uas) and client (uac) scenarios.

```bash
# ./sipp -sn uas
```

```bash
# ./sipp -sn uac 127.0.0.1
```

--------------------------------

### Equivalent Standard File for Multi-line PRINTF

Source: https://sipp.readthedocs.io/en/latest/scenarios/inject_from_csv.html

The logical expansion of the multi-line PRINTF template example.

```text
USERS
user000;password000;Foo
user001;password001;Bar
user002;password002;Foo
user003;password003;Bar
```

--------------------------------

### Example Injection File Content

Source: https://sipp.readthedocs.io/en/latest/scenarios/inject_from_csv.html

A sample CSV-formatted injection file containing user names and passwords.

```text
USERS
alice,pass_A
bob,pass_B
carol,pass_C
```

--------------------------------

### Compile SIPp with multiple features enabled

Source: https://sipp.readthedocs.io/en/latest/installation.html

Example of combining multiple build flags to enable GSL, PCAP, SSL, and SCTP simultaneously.

```bash
tar -xvzf sipp-xxx.tar.gz
cd sipp
cmake . -DUSE_GSL=1 -DUSE_PCAP=1 -DUSE_SSL=1 -DUSE_SCTP=1
make
```

--------------------------------

### Standard PRINTF Injection File

Source: https://sipp.readthedocs.io/en/latest/scenarios/inject_from_csv.html

Example of a repetitive injection file structure that can be optimized using PRINTF.

```text
USERS
user000;password000
user001;password001
...
user999;password999
```

--------------------------------

### Multi-line PRINTF Template

Source: https://sipp.readthedocs.io/en/latest/scenarios/inject_from_csv.html

Example of cycling through multiple template lines using PRINTF.

```text
USERS,PRINTF=4
user%03d;password%03d;Foo
user%03d;password%03d;Bar
```

--------------------------------

### Send basic control commands to SIPp

Source: https://sipp.readthedocs.io/en/latest/controlling.html

Examples of sending single-character commands to a SIPp instance via a UDP socket.

```bash
echo p >/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)
```

--------------------------------

### Execute SIPp with UDP one socket per IP address

Source: https://sipp.readthedocs.io/en/latest/transport.html

Example command line for running a client scenario using the -t ui transport mode with an injection file.

```bash
./sipp -sf myscenario.xml -t ui -inf database.csv -ip_field 2 192.168.1.1
```

--------------------------------

### RTP Stream Execution Examples

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Various configurations for the rtp_stream action to control audio playback, looping, and stream state.

```xml
<exec rtp_stream=”file.wav” />
```

```xml
<exec rtp_stream=”[filename],[loopcount],[payloadtype],[payloadparam]” />
```

```xml
<exec rtp_stream=”pause” />
```

```xml
<exec rtp_stream=”resume” />
```

--------------------------------

### Compile SIPp without optional features

Source: https://sipp.readthedocs.io/en/latest/installation.html

Standard build process for a basic SIPp installation without TLS, SCTP, or PCAP support.

```bash
tar -xvzf sipp-xxx.tar
cd sipp
cmake .
make
```

--------------------------------

### Set SIPp call rate via remote command

Source: https://sipp.readthedocs.io/en/latest/controlling.html

Example of using the 'c' prefix to send specific configuration commands like setting the call rate.

```bash
echo "cset rate 100" >/dev/udp/127.0.0.1/8888
```

--------------------------------

### CSV Injection File Format

Source: https://sipp.readthedocs.io/en/latest/scenarios/inject_from_csv.html

Example of a standard CSV injection file using the SEQUENTIAL strategy with comments.

```text
SEQUENTIAL
#This line will be ignored
Sarah;sipphone32
Bob;sipphone12
#This line too
Fred;sipphone94
```

--------------------------------

### Configure Distributed Pauses

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Examples of various pause distributions available in SIPp scenarios, including fixed, uniform, and GSL-based statistical distributions.

```xml
<pause distribution=”fixed” value=”1000” />
```

```xml
<pause distribution=”uniform” min=”2000” max=”5000”/>
```

```xml
<pause distribution=”normal” mean=”60000” stdev=”15000”/>
```

```xml
<pause distribution=”lognormal” mean=”12.28” stdev=”1” />
```

```xml
<pause distribution=”exponential” mean=”900000”/>
```

```xml
<pause distribution=”weibull” lambda=”3” k =”4”/>
```

```xml
<pause distribution=”pareto” k=”1” x_m=”2”/>
```

```xml
<pause distribution=”gamma” k=”3” theta=”2”/>
```

```xml
<pause distribution=”negbin” p=”0.1” n=”2”/>
```

--------------------------------

### Automate SIPp actions with a shell script

Source: https://sipp.readthedocs.io/en/latest/controlling.html

A shell script example that automates increasing the call rate and eventually quitting the SIPp instance.

```bash
#!/bin/sh
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 5
echo "*" >/dev/udp/127.0.0.1/8889
sleep 60
echo "q" >/dev/udp/127.0.0.1/8889
```

--------------------------------

### Regular Expression Assignment Example

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Demonstrates using the ereg action to extract sub-expressions from a SIP message line into specific variables.

```xml
<ereg regexp="o=([[:alnum:]]*) ([[:alnum:]]*) ([[:alnum:]]*)"
      search_in="msg"
      check_it=i"true"
      assign_to="3,4,5,8"/>
```

```text
o=user1 53655765 2353687637 IN IP4 127.0.0.1
```

--------------------------------

### Multi-file CSV Injection

Source: https://sipp.readthedocs.io/en/latest/scenarios/inject_from_csv.html

Example of referencing specific CSV files within a SIP message using the file parameter.

```text
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"]>
...
```

--------------------------------

### Compile SIPp with PCAP play support

Source: https://sipp.readthedocs.io/en/latest/installation.html

Builds SIPp with libpcap and libnet support for media playback.

```bash
tar -xvzf sipp-xxx.tar.gz
cd sipp
cmake . -DUSE_PCAP=1
make
```

--------------------------------

### Assign and Sample Variables in SIPp

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Demonstrates assigning values, sampling from distributions, and converting string variables to double-precision.

```xml
<nop>
  <action>
    <assign assign_to="1" value="1" />
    <sample assign_to="2" distribution="normal" mean="0" stdev="1"/>
    <!-- Stores the first field in the injection file into string variable $3.
         You may also use regular expressions to store string variables. -->
    <assignstr assign_to="3" value="[field0]" />
    <!-- Converts the string value in $3 to a double-precision value stored in $4. -->
    <todouble assign_to="4" variable="3" />
  </action>
</nop>
```

--------------------------------

### Configure send command transaction attributes

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Use start_txn to track branch IDs for response matching and ack_txn to associate ACKs with specific INVITE transactions.

```xml
<send start_txn="invite">
```

```xml
<send ack_txn="invite">
```

--------------------------------

### Compile SIPp with TLS support

Source: https://sipp.readthedocs.io/en/latest/installation.html

Builds SIPp with OpenSSL or WolfSSL support enabled.

```bash
tar -xvzf sipp-xxx.tar.gz
cd sipp
cmake . -DUSE_SSL=1
make
```

--------------------------------

### Define an initialization stanza

Source: https://sipp.readthedocs.io/en/latest/scenarios/init_stanza.html

Use this structure to set default values for variables like $THINKTIME if they have not been provided via command line arguments.

```xml
<init>
  <!-- By Default THINKTIME is true. -->
  <nop>
    <action>
      <strcmp assign_to="empty" variable="THINKTIME" value="" />
      <test assign_to="empty" compare="equal" variable="empty" value="0" />
    </action>
  </nop>
  <nop condexec="empty">
    <action>
      <assignstr assign_to="THINKTIME" value="1" />
    </action>
  </nop>
</init>
```

--------------------------------

### Compile SIPp with SCTP support

Source: https://sipp.readthedocs.io/en/latest/installation.html

Builds SIPp with lksctp-tools support.

```bash
tar -xvzf sipp-xxx.tar.gz
cd sipp
cmake . -DUSE_SCTP=1
make
```

--------------------------------

### Configure recv command optional and header attributes

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Handle optional messages, ignore SDP, store Record-Route headers, or enable authentication processing.

```xml
<recv response="100" optional="true">
```

```xml
<recv request="INVITE" ignoresdp="true">
```

```xml
<recv response="100" rrs="true">
```

```xml
<recv response="407" auth="true">
```

--------------------------------

### Compile SIPp with statistically distributed pauses

Source: https://sipp.readthedocs.io/en/latest/installation.html

Builds SIPp with GSL support for distributed pauses.

```bash
tar -xvzf sipp-xxx.tar.gz
cd sipp
cmake . -DUSE_GSL=1
make
```

--------------------------------

### Run SIPp with specific call rate

Source: https://sipp.readthedocs.io/en/latest/controlling.html

Execute SIPp to initiate 7 calls every 2 seconds, resulting in a rate of 3.5 calls per second.

```bash
./sipp -sn uac -r 7 -rp 2000 127.0.0.1
```

--------------------------------

### Jump Action

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Navigates to a specific scenario index or a stored variable address.

```xml
<nop>
  <action>
    <jump value="5" />
  </action>
</nop>
```

```xml
<nop>
  <action>
    <jump variable="_unexp.retaddr" />
  </action>
</nop>
```

--------------------------------

### Execute external command

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Executes shell commands on the local host during scenario execution.

```xml
<recv request="INVITE">
  <action>
    <exec command="echo [last_From] is the from header received >> from_list.log"/>
  </action>
</recv>
```

--------------------------------

### Scenario XML Structure

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

The mandatory opening and closing tags for a SIPp scenario file.

```xml
<?xml version="1.0" encoding="ISO-8859-1" ?>
<scenario name="Basic Sipstone UAC">
```

```xml
</scenario>
```

--------------------------------

### Log a message in SIPp

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Logs a message to the scenario log file when the -trace_logs command line option is enabled. Keywords are expanded to their current values.

```xml
<recv request="INVITE" crlf="true" rrs="true">
  <action>
    <ereg regexp=".*" search_in="hdr" header="Some-New-Header:" assign_to="1" />
    <log message="From is [last_From]. Custom header is [$1]"/>
  </action>
</recv>
```

--------------------------------

### Configure recv command timeout handling and actions

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Define labels for timeout jumps or execute actions like regular expression matching upon receiving a message.

```xml
<recv response="100" timeout="100000" ontimeout="5">
</recv>
```

```xml
<recv response="200">
<action>
  <ereg regexp="([0-9]{1,3}\.){3}[0-9]{1,3}:[0-9]*"
    search_in="msg"
    check_it="true"
    assign_to="1,2"/>
  </action>
</recv>
```

--------------------------------

### Execute Actions with Nop

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Uses the nop command to trigger specific actions like playing PCAP audio.

```xml
<nop>
  <action>
    <exec play_pcap_audio="pcap/g711a.pcap"/>
  </action>
</nop>
```

--------------------------------

### Configure recv command message expectations

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Define expected SIP responses or requests using response or request attributes.

```xml
<recv response="200">
```

```xml
<recv request="ACK">
```

--------------------------------

### Receive Command from Twin SIPp Instance

Source: https://sipp.readthedocs.io/en/latest/int_scenarios.html

Used to capture incoming commands from a twin instance. Regular expressions are typically used to extract content into call variables.

```xml
<recvCmd>
  <action>
     <ereg regexp="Content-Type:.*"
           search_in="msg"
           assign_to="2"/>
  </action>
</recvCmd>
```

--------------------------------

### Arithmetic Operations with Variables in SIPp

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Demonstrates using the variable parameter to perform arithmetic between two variables.

```xml
<nop>
  <action>
    <!-- Multiplies $1 by itself -->
    <multiply assign_to="1" variable="1" />
    <!-- Divides $1 by $2, Note that $2 must not be zero -->
    <multiply assign_to="1" variable="2" />
  </action>
</nop>
```

--------------------------------

### Configure pause command

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Control scenario execution delays using fixed millisecond values or dynamic variables.

```xml
<pause milliseconds="5000"/>
```

```xml
<pause variable="1" />
```

--------------------------------

### CSV configuration for dynamic authentication

Source: https://sipp.readthedocs.io/en/latest/scenarios/sipauth.html

Define unique authentication credentials per call using a CSV file.

```text
SEQUENTIAL
User0001;[authentication username=joe password=schmo]
User0002;[authentication username=john password=smith]
User0003;[authentication username=betty password=boop]
```

--------------------------------

### Configure recv command regex matching and transaction response

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Match multiple request types using regex or link responses to specific transactions.

```xml
<recv request="MESSAGE|PUBLISH|SUBSCRIBE" crlf="true" regexp_match="true">
</recv>
```

```xml
<recv response="200" response_txn="invite" />
```

--------------------------------

### Define UAC Scenario INVITE

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Initiate a client scenario with an INVITE request using CDATA to encapsulate the SIP message.

```xml
<scenario name="Basic Sipstone UAC">
  <send>
    <![CDATA[

      INVITE sip:[service]@[remote_ip]:[remote_port] SIP/2.0
      Via: SIP/2.0/[transport] [local_ip]:[local_port]
      From: sipp <sip:sipp@[local_ip]:[local_port]>;tag=[call_number]
      To: sut <sip:[service]@[remote_ip]:[remote_port]>
      Call-ID: [call_id]
      Cseq: 1 INVITE
      Contact: sip:sipp@[local_ip]:[local_port]
      Max-Forwards: 70
      Subject: Performance Test
      Content-Type: application/sdp
      Content-Length: [len]

      v=0
      o=user1 53655765 2353687637 IN IP[local_ip_type] [local_ip]
      s=-
      t=0 0
      c=IN IP[media_ip_type] [media_ip]
      m=audio [media_port] RTP/AVP 0
      a=rtpmap:0 PCMU/8000


    ]]>
  </send>
```

--------------------------------

### Configure Response Time Repartition

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Defines intervals for distributing response time measurements.

```xml
<ResponseTimeRepartition value="10, 20, 30"/>
```

--------------------------------

### Define User and Reference Variables

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Use these tags to define user-scoped variables or suppress warnings about unused variables.

```xml
<User variables="foo,bar"/>
```

```xml
<Reference variables="dummy"/>
```

--------------------------------

### Define Scenario Labels

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Sets a label ID for branching within a scenario.

```xml
<label id="13"/>
```

--------------------------------

### Declare Global and User Variables

Source: https://sipp.readthedocs.io/en/latest/scenarios/variables.html

Use these tags to define variables that persist across calls or users.

```xml
<Global variables="foo,bar" />
<User variables="baz,quux" />
```

--------------------------------

### Configure recv command timeout and packet loss

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Simulate packet loss or define timeouts for message reception.

```xml
<recv lost="10">
```

```xml
<recv timeout="100000">
```

--------------------------------

### Close Scenario Tag

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Finalize the XML scenario structure.

```xml
</scenario>
```

--------------------------------

### Log a warning message

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Logs a message specifically to SIPp’s error log.

```xml
<warning message="From is [last_From]. Custom header is [$1]"/>
```

--------------------------------

### XML scenario with dynamic authentication field

Source: https://sipp.readthedocs.io/en/latest/scenarios/sipauth.html

Inject the authentication string from a CSV field into a SIP message.

```xml
<send retrans="500">
  <![CDATA[

    REGISTER sip:[remote_ip] SIP/2.0
    Via: SIP/2.0/[transport] [local_ip]:[local_port]
    To: <sip:[field0]@sip.com:[remote_port]>
    From: <sip:[field0]@[remote_ip]:[remote_port]>
    Contact: <sip:[field0]@[local_ip]:[local_port]>;transport=[transport]
    [field1]
    Expires: 300
    Call-ID: [call_id]
    CSeq: 2 REGISTER
    Content-Length: 0

  ]]>
</send>
```

--------------------------------

### Configure 3PCC Extended Slave Mapping

Source: https://sipp.readthedocs.io/en/latest/3PCC_extended.html

Defines the mapping between instance names and their respective addresses in a configuration file.

```text
s1;127.0.0.1:8080
s2;127.0.0.1:7080
m;127.0.0.1:6080
```

--------------------------------

### Regexp Scenario Flow

Source: https://sipp.readthedocs.io/en/latest/int_scenarios.html

Visual representation of the UAC regexp scenario message sequence.

```text
SIPp regexp         Remote
    |(1) INVITE         |
    |------------------>|
    |(2) 100 (optional) |
    |<------------------|
    |(3) 180 (optional) |
    |<------------------|
    |(4) 200            |
    |<------------------|
    |(5) ACK            |
    |------------------>|
    |                   |
    |(6) PAUSE          |
    |                   |
    |(7) BYE            |
    |------------------>|
    |(8) 200            |
    |<------------------|
```

--------------------------------

### Insert Scenario Pause

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Introduce a delay in the scenario execution.

```xml
<pause milliseconds="5000"/>
```

--------------------------------

### Testing Variables

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Use <test> to perform conditional comparisons and store the boolean result in a variable.

```xml
<nop>
  <action>
    <test assign_to="2" variable="1" compare="less_than" value="10" />
  </action>
</nop>
```

--------------------------------

### Execute internal command

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Triggers internal SIPp commands like stop_now to control scenario execution flow.

```xml
<recv response="603" optional="true">
  <action>
    <exec int_cmd="stop_now"/>
  </action>
</recv>
```

--------------------------------

### Configure Call Length Repartition

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Defines intervals for distributing call length measurements.

```xml
<CallLengthRepartition value="10, 20, 30"/>
```

--------------------------------

### Performing Lookups

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Use <lookup> to retrieve a line number from an indexed injection file based on a provided key.

```xml
<recv request="REGISTER">
  <action>
    <ereg regexp="Digest .*username=\"([^\"]*)\"" search_in="hdr" header="Authorization:" assign_to="junk,username" />
    <lookup assign_to="line" file="users.csv" key="[$username]" />
  </action>
</recv>
```

--------------------------------

### Branch Scenario Flow

Source: https://sipp.readthedocs.io/en/latest/int_scenarios.html

Message sequence for branchc and branchs scenarios working in tandem.

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

--------------------------------

### Arithmetic Operations with Fixed Values in SIPp

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Shows basic arithmetic operations using fixed values to modify a variable.

```xml
<nop>
  <action>
    <assign assign_to="1" value="0" /> <!-- $1 == 0 -->
    <add assign_to="1" value="2" /> <!-- $1 == 2 -->
    <subtract assign_to="1" value="3" /> <!-- $1 == -1 -->
    <multiply assign_to="1" value="4" /> <!-- $1 == -4 -->
    <divide assign_to="1" value="5" /> <!-- $1 == -0.8 -->
  </action>
</nop>
```

--------------------------------

### ereg (Regular Expression Action)

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

The ereg action allows matching patterns against SIP messages, headers, or variables. It supports validation (check_it) and extraction of matched content into variables (assign_to).

```APIDOC
## ereg Action

### Description
Performs a POSIX Extended regular expression match against a specified part of a SIP message or variable. Results can be stored in variables for re-injection or conditional logic.

### Parameters
- **regexp** (string) - Required - The POSIX Extended regular expression to match.
- **search_in** (string) - Optional - Where to search: "msg", "hdr", "body", or "var". Defaults to "msg".
- **header** (string) - Required if search_in is "hdr" - The SIP header to search within.
- **variable** (string) - Required if search_in is "var" - The SIPp variable to search within.
- **case_indep** (boolean) - Optional - Ignore case when searching headers. Defaults to false.
- **occurrence** (integer) - Optional - The nth occurrence of a header to match. Defaults to 1.
- **start_line** (boolean) - Optional - Match only at the start of the line. Defaults to false.
- **check_it** (boolean) - Optional - Mark call as failed if no match. Defaults to false.
- **check_it_inverse** (boolean) - Optional - Mark call as failed if match occurs. Defaults to false.
- **assign_to** (string) - Optional - Comma-separated list of variable IDs to store the full match and sub-expression matches.

### Example
```xml
<ereg regexp="([0-9]{1,3}\.){3}[0-9]{1,3}:[0-9]*"
      search_in="msg"
      check_it="true"
      assign_to="1,2" />
```
```

--------------------------------

### Command-Specific Attributes

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Attributes specific to individual commands like send.

```xml
<send retrans="500">
```

```xml
<send lost="10">
```

--------------------------------

### Send Command to Twin SIPp Instance

Source: https://sipp.readthedocs.io/en/latest/int_scenarios.html

Used to transmit information, such as SDP offers, to a synchronized SIPp instance. Including the Call-ID is mandatory for call correlation.

```xml
<sendCmd>
  <![CDATA[
    Call-ID: [call_id]
    [$1]

   ]]>
</sendCmd>
```

--------------------------------

### Send Commands in 3PCC Mode

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Sends commands to a twin 3PCC SIPp instance, optionally specifying the destination instance.

```xml
<sendCmd>
  <![CDATA[
    Call-ID: [call_id]
    [$1]

  ]]>
</sendCmd>
```

```xml
<sendCmd dest="s1">
```

--------------------------------

### Verify Authentication Credentials

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Extracts the username from the Authorization header and validates it against credentials stored in an injection file.

```xml
<recv request="REGISTER">
  <action>
    <ereg regexp="Digest .*username=\"([^\"]*)\"" search_in="hdr" header="Authorization:" assign_to="junk,username" />
    <lookup assign_to="line" file="users.conf" key="[$username]" />
    <verifyauth assign_to="authvalid" username="[field0 line=\"[$line]\"]" password="[field3 line=\"[$line]\"]" />
  </action>
</recv>

<nop hide="true" test="authvalid" next="goodauth" />
<nop hide="true" next="badauth" />
```

--------------------------------

### Insert into Injection File

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Adds a new line to an in-memory injection file using the insert action.

```xml
<nop display="Insert User">
  <action>
    <insert file="usersdb.conf" value="[$user];[$calltype]" />
  </action>
</nop>
```

--------------------------------

### Optimized PRINTF Injection Template

Source: https://sipp.readthedocs.io/en/latest/scenarios/inject_from_csv.html

Using the PRINTF parameter to generate structured data dynamically in memory.

```text
USERS,PRINTF=999
user%03d;password%03d
```

--------------------------------

### Receive SIP Responses

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Handle incoming SIP responses, marking them as optional or mandatory.

```xml
<recv response="100"> optional="true"
</recv>

<recv response="180"> optional="true"
</recv>

<recv response="200">
</recv>
```

--------------------------------

### Retrieve Current Time with gettimeofday

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Captures the current epoch time in seconds and microseconds into specified variables.

```xml
<nop>
  <action>
    <gettimeofday assign_to="seconds,microseconds" />
  </action>
</nop>
```

--------------------------------

### Receive Commands in 3PCC Mode

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Receives commands from a twin 3PCC instance and optionally performs actions like regex extraction.

```xml
<recvCmd>
  <action>
    <ereg regexp="Content-Type:.*"
          search_in="msg"
          assign_to="2"/>
  </action>
</recvCmd>
```

```xml
<recvCmd src = "s1">
```

--------------------------------

### Send 401 Challenge

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Sends a 401 Authorization Required response to initiate the authentication process.

```xml
<recv request="REGISTER" />
<send>
  <![CDATA[

    SIP/2.0 401 Authorization Required
    [last_Via:]
    [last_From:]
    [last_To:];tag=[pid]SIPpTag01[call_number]
    [last_Call-ID:]
    [last_CSeq:]
    Contact: <sip:[local_ip]:[local_port];transport=[transport]>
    WWW-Authenticate: Digest realm="test.example.com", nonce="47ebe028cda119c35d4877b383027d28da013815"
    Content-Length: [len]

  ]]>
</send>
```

--------------------------------

### Reference Single-Use Variables

Source: https://sipp.readthedocs.io/en/latest/scenarios/variables.html

Use the Reference tag to prevent SIPp from flagging variables that are only used once, such as dummy variables in regex captures.

```xml
<recv request="INVITE">
  <action>
    <ereg regexp="<sip:([^;@]*)" search_in="hdr" header="To:" assign_to="dummy,uri" />
  </action>
</recv>
<Reference variables="dummy" />
```

--------------------------------

### CSV Line Selection Override

Source: https://sipp.readthedocs.io/en/latest/scenarios/inject_from_csv.html

Syntax for overriding the default line selection strategy using the line argument.

```text
[field0 line=1]
```

--------------------------------

### Assigning String Variables

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Use <assignstr> to store values, including substitutions, into a variable.

```xml
<nop>
  <action>
    <!-- Assign the value in field0 of the CSV file to a $1. -->
    <assignstr assign_to="1" value="[field0]" />
  </action>
</nop>
```

--------------------------------

### play_pcap_audio / play_pcap_video

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Sends a pre-recorded RTP stream using the pcap library based on SIP/SDP line ports.

```APIDOC
## <exec play_pcap_audio="[file]" /> / <exec play_pcap_video="[file]" />

### Description
Plays a pre-recorded pcap file as an RTP stream. play_pcap_audio uses the m=audio line port, while play_pcap_video uses the m=video line port.

### Parameters
- **file_to_play** (string) - Required - The path to the pre-recorded pcap file.

### Usage Example
<nop>
  <action>
    <exec play_pcap_audio="pcap/g711a.pcap"/>
  </action>
</nop>
```

--------------------------------

### Common Command Attributes

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Attributes applicable to all message commands like send, recv, and nop for flow control and statistics.

```xml
<send start_rtd="invite">
```

```xml
<send rtd="2">
```

```xml
<send rtd="1"repeat_rtd="true">
```

```xml
<send crlf="true">
```

```xml
<send next="12">
  <![CDATA[

    ACK sip:[service]@[remote_ip]:[remote_port] SIP/2.0
    Via: ...
    From: ...
    To: ...
    Call-ID: ...
    Cseq: ...
    Contact: ...
    Max-Forwards: ...
    Subject: ...
    Content-Length: 0

  ]]>
</send>
```

```xml
<recv response="100"
      optional="true">
</recv>
<recv response="180" optional="true">
</recv>
<recv response="403" optional="true" next="5">
</recv>
<recv response="200">
</recv>
```

```xml
<send next="6" test="4">
  <![CDATA[

    ACK sip:[service]@[remote_ip]:[remote_port] SIP/2.0
    Via: ...
    From: ...
    To: ...
    Call-ID: ...
    Cseq: ...
    Contact: ...
    Max-Forwards: ...
    Subject: ...
    Content-Length: 0

  ]]>
</send>
```

```xml
<recv response="403" optional="true" next="5" test="3" chance="0.90">
</recv>
```

```xml
<nop condexec="executethis">
```

```xml
<nop condexec="skipthis"condexec_inverse="true">
```

```xml
<send counter="MsgA">
```

--------------------------------

### Terminate Call with BYE

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Send a BYE request and expect a 200 OK response to close the call.

```xml
<send retrans="500">
  <![CDATA[

    BYE sip:[service]@[remote_ip]:[remote_port] SIP/2.0
    Via: SIP/2.0/[transport] [local_ip]:[local_port]
    From: sipp  <sip:sipp@[local_ip]:[local_port]>;tag=[call_number]
    To: sut  <sip:[service]@[remote_ip]:[remote_port]>[peer_tag_param]
    Call-ID: [call_id]
    Cseq: 2 BYE
    Contact: sip:sipp@[local_ip]:[local_port]
    Max-Forwards: 70
    Subject: Performance Test
    Content-Length: 0

  ]]>
</send>

<recv response="200" />
```

--------------------------------

### Define Global Variables

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Specifies names for globally scoped variables.

```xml
<Global variables="foo,bar"/>
```

--------------------------------

### Comparing String Variables

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Use <strcmp> to perform lexicographical comparison between a variable and a value.

```xml
<nop>
  <action>
    <!-- Compare the value of $strvar to "Hello" and assign it to $result.. -->
    <strcmp assign_to="result" variable="strvar" value="Hello" />
  </action>
</nop>
```

--------------------------------

### Reinject Captured Content into SIP Message

Source: https://sipp.readthedocs.io/en/latest/int_scenarios.html

Demonstrates how to use a previously captured variable (e.g., $2) within a standard SIP message header or body.

```xml
<send>
  <![CDATA[

    ACK sip:[service]@[remote_ip]:[remote_port] SIP/2.0
    Via: SIP/2.0/[transport] [local_ip]:[local_port]
    From: sipp <sip:sipp@[local_ip]:[local_port]>;tag=[call_number]
    To: sut <sip:[service]@[remote_ip]:[remote_port]>[peer_tag_param]
    Call-ID: [call_id]
    CSeq: 1 ACK
    Contact: sip:sipp@[local_ip]:[local_port]
    Max-Forwards: 70
    Subject: Performance Test
    [$2]

  ]]>
</send>
```

--------------------------------

### Encode Variables with urlencode

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Replaces the content of a specified variable with its URL-encoded equivalent.

```xml
<nop>
  <action>
    <urlencode variable="variable_to_be_encoded" />
  </action>
</nop>
```

--------------------------------

### Send ACK Request

Source: https://sipp.readthedocs.io/en/latest/scenarios/ownscenarios.html

Send an ACK message following the initial INVITE exchange.

```xml
<send>
  <![CDATA[

    ACK sip:[service]@[remote_ip]:[remote_port] SIP/2.0
    Via: SIP/2.0/[transport] [local_ip]:[local_port]
    From: sipp <sip:sipp@[local_ip]:[local_port]>;tag=[call_number]
    To: sut <sip:[service]@[remote_ip]:[remote_port]>[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

  ]]>
</send>
```

--------------------------------

### Replace in Injection File

Source: https://sipp.readthedocs.io/en/latest/scenarios/actions.html

Updates an existing line in an in-memory injection file, typically preceded by a lookup to identify the target line index.

```xml
<nop display="Update User">
  <action>
    <lookup assign_to="index" file="usersdb.conf" key="[$user]" />
    <!-- Note: This assumes that the lookup always succeeds. -->
    <replace file="usersdb.conf" line="[$index]" value="[$user];[$calltype]" />
  </action>
</nop>
```

--------------------------------

### Receive 3PCC Extended Command

Source: https://sipp.readthedocs.io/en/latest/3PCC_extended.html

Defines an expectation to receive a command from a specific peer instance.

```xml
<recvCmd src="m">
  <action>
     <ereg regexp="Content-Type:.*"
           search_in="msg"
           assign_to="2"/>
  </action>
</recvCmd>
```

--------------------------------

### Send 3PCC Extended Command

Source: https://sipp.readthedocs.io/en/latest/3PCC_extended.html

Sends a command to a peer instance, requiring a 'From' field identifying the sender.

```xml
<sendCmd dest="s1">
  <![CDATA[
    Call-ID: [call_id]
    From: m
    [$1]

  ]]>
</sendCmd>
```
Tokens:
Raw