Table of Contents
sipp_path (string)
scenario_dir (string)
work_dir (string)
media_ip (string)
send_socket_name (string)
send_socket (string)
target_domain (string)
default_caller (string)
default_service (string)
valid_domains (string)
default_concurrent_calls (integer)
max_concurrent_calls (integer)
max_concurrent_tests (integer)
default_duration (integer)
default_call_rate (integer)
default_total_calls (integer)
default_max_test_duration (integer)
enable_prometheus (integer)
List of Examples
sipp_path parameterscenario_dir parameterwork_dir parametermedia_ip parametersend_socket_name parametersend_socket parametertarget_domain parameterdefault_caller parameterdefault_service parametervalid_domains parameterdefault_concurrent_calls parametermax_concurrent_calls parametermax_concurrent_tests parameterdefault_duration parameterdefault_call_rate parameterdefault_total_calls parameterdefault_max_test_duration parameterenable_prometheus parametersipp.start_test RPC examplesipp.stop_test RPC examplesipp.get_stats RPC examplesipp.running RPC examplesipp.list RPC examplesipp.pause_test RPC examplesipp.resume_test RPC examplesipp.adjust_rate RPC examplesipp.get_live_stats RPC exampleTable of Contents
sipp_path (string)
scenario_dir (string)
work_dir (string)
media_ip (string)
send_socket_name (string)
send_socket (string)
target_domain (string)
default_caller (string)
default_service (string)
valid_domains (string)
default_concurrent_calls (integer)
max_concurrent_calls (integer)
max_concurrent_tests (integer)
default_duration (integer)
default_call_rate (integer)
default_total_calls (integer)
default_max_test_duration (integer)
enable_prometheus (integer)
The SIPp module provides integration with SIPp (SIP Performance Testing Tool) for automated SIP load testing and scenario execution from within Kamailio. This module enables starting, stopping, and monitoring SIPp test sessions through RPC commands, making it suitable for CI and operational workflows.
Key features include:
Start and stop SIPp test scenarios via RPC commands
Automatic transport protocol detection (UDP/TCP/TLS)
Configurable concurrent test limits
Domain whitelist for security
Real-time test status monitoring
Support for custom SIPp scenarios
Remote control of running tests (pause/resume/adjust rate)
Prometheus metrics export for monitoring and dashboards
No additional Kamailio modules are required.
xhttp_prom (optional) - For Prometheus metrics export. If you want to export SIPp metrics to Prometheus, load xhttp_prom before loading the sipp module.
Path to the SIPp binary executable. If not set, the module will look for 'sipp' in the system PATH.
Default value is NULL (uses system PATH).
Default directory where SIPp scenario files are stored. This directory is used as the base path when relative scenario paths are provided.
No default; this parameter must be set.
Example 1.2. Set scenario_dir parameter
...
modparam("sipp", "scenario_dir", "/etc/kamailio/sipp/scenarios")
...
Working directory to use for SIPp child processes. When set, the module will chdir to this directory before executing SIPp and will place log and statistics files under this path. The directory must be writable by the Kamailio user.
Default value is NULL (uses /tmp for log/stat files).
Local media IP address for SIPp. When set, the module passes the value
as SIPp's -mi option. If not set, SIPp uses its default
media IP selection.
Default value is NULL (uses SIPp default).
Name identifier for an existing Kamailio listen socket that SIPp should
use for sending traffic (for example: udp:192.168.1.10:5060).
This parameter is mutually exclusive with send_socket.
Default value is NULL.
Example 1.5. Set send_socket_name parameter
...
modparam("sipp", "send_socket_name", "udp:192.168.1.10:5060")
...
Socket specification in the format proto:ip:port that SIPp should use
for sending traffic.
This parameter is mutually exclusive with send_socket_name.
Default value is NULL.
Example 1.6. Set send_socket parameter
...
modparam("sipp", "send_socket", "udp:192.168.1.10:5060")
...
Default target domain for SIPp tests. This domain is optional and will
be used only if the scenario references [target_domain]
and no explicit target is provided in the RPC command.
If a scenario references [target_domain] and neither a
per-test value nor a module default is set, the module falls back to
<local_ip>:<send_socket_port>.
Default value is NULL.
Example 1.7. Set target_domain parameter
...
modparam("sipp", "target_domain", "sip.example.com")
...
Default caller user/number for SIPp tests. Used only if no explicit
caller is provided via RPC. Required when scenarios use
[caller] and no caller is passed.
Default value is NULL.
Default service user/number for SIPp tests. Used only if no explicit service is provided via RPC. Required when no service is provided in RPC.
Default value is NULL.
Comma-separated list of domains that are allowed as SIPp test targets. This provides a security whitelist to prevent unauthorized test execution against arbitrary domains. If set, only domains in this list can be targeted.
Default value is NULL (all domains allowed).
Example 1.10. Set valid_domains parameter
...
modparam("sipp", "valid_domains", "test.example.com,staging.example.com,demo.example.com")
...
Default number of concurrent calls per test when the RPC command does not provide a value.
Default value is 50.
Example 1.11. Set default_concurrent_calls parameter
...
modparam("sipp", "default_concurrent_calls", 25)
...
Maximum number of concurrent calls per SIPp test session. This limits the load generated by each individual test.
Default value is 1000.
Example 1.12. Set max_concurrent_calls parameter
...
modparam("sipp", "max_concurrent_calls", 50)
...
Maximum number of SIPp test sessions that can run concurrently. This prevents resource exhaustion from too many simultaneous tests. Note: SIPp has a hard limit of 60 concurrent instances (each uses a UDP control port starting from 8888). Values above 60 will be automatically capped.
Default value is 10. Maximum value is 60.
Example 1.13. Set max_concurrent_tests parameter
...
modparam("sipp", "max_concurrent_tests", 5)
...
Default call duration in seconds (SIPp -d) used when the RPC command does not provide a duration.
Default value is 60.
Default call rate (calls per second) used when the RPC command does not
provide a rate. The rate can be adjusted at runtime using
sipp.adjust_rate.
Default value is 10.
Default maximum total calls per test. Set to 0 to allow tests to run until explicitly stopped.
Default value is 0 (unlimited).
This module does not export any functions to be used in the routing script. All functionality is exposed via RPC commands.
Start a new SIPp test session with the specified parameters.
Parameters:
scenario (string, required) - Name of SIPp scenario XML file
caller (string, optional) - Caller user/number/range/list
service (string, optional) - Service user/number/range/list
target_domain (string, optional) - Target domain for scenario variables
concurrent_calls (integer, optional) - Max concurrent calls
duration (integer, optional) - Call duration in seconds (SIPp -d)
total_calls (integer, optional) - Max total calls (0 = unlimited)
max_test_duration (integer, optional) - Max test duration in seconds (0 = unlimited)
Example 1.19. sipp.start_test RPC example
... # Using kamcmd (positional) kamcmd sipp.start_test uac_invite.xml 1000 2000 sip.example.com 10 60 0 0 # Using kamcmd (named) kamcmd sipp.start_test scenario=uac_invite.xml caller=1000 service=2000 \ target_domain=sip.example.com concurrent_calls=10 duration=60 \ total_calls=0 max_test_duration=0 ...
Stop a running SIPp test session.
Parameters:
test_id (int) - Test ID to stop
Example 1.20. sipp.stop_test RPC example
... # Using kamcmd kamcmd sipp.stop_test 1 # Using kamctl kamctl rpc sipp.stop_test 1 ...
Retrieve statistics for a specific test session.
Parameters:
test_id (int, required) - Test ID to query
Example 1.21. sipp.get_stats RPC example
... # Get stats for specific test kamcmd sipp.get_stats 1 ...
List all currently running and recently completed test sessions with their status and statistics. Completed, stopped, and failed tests are eligible for removal after 30 minutes (1800 seconds), and cleanup runs on a periodic timer (every hour). As a result, tests can remain visible for roughly 30 to 90 minutes depending on when the cleanup timer fires.
Parameters: None
List all available SIPp scenario files (.xml) from the configured scenario directory. Returns the filename and size in bytes for each scenario found.
Parameters: None
Pause a running SIPp test via remote control socket. This stops SIPp from creating new calls but keeps existing calls alive. Uses the SIPp remote control socket created for the test.
Parameters:
test_id (int, required) - Test ID to pause
Resume a paused SIPp test via remote control socket. This resumes call generation after a pause. Uses the SIPp remote control socket created for the test.
Parameters:
test_id (int, required) - Test ID to resume
Dynamically adjust the call rate of a running SIPp test. This allows increasing or decreasing the call generation rate without stopping and restarting the test. Uses the SIPp remote control socket created for the test.
Parameters:
test_id (int, required) - Test ID to adjust
change (string, required) - "increase" or "decrease"
Example 1.26. sipp.adjust_rate RPC example
... kamcmd sipp.adjust_rate 1 increase kamcmd sipp.adjust_rate 1 decrease ...
Get real-time statistics from a running SIPp test via the remote control socket. This queries SIPp directly for current call counts, active calls, and failure counts. Uses the SIPp remote control socket created for the test.
Parameters:
test_id (int, required) - Test ID to query
Returns:
test_id (int) - Test identifier
calls_active (int) - Currently active calls
calls_started (int) - Total calls started
calls_completed (int) - Calls completed successfully
calls_failed (int) - Failed calls
When the xhttp_prom module is loaded before the sipp module, SIPp test metrics are automatically exported to Prometheus. Metrics are pushed on a periodic timer (by default every 10 seconds).
All metrics include the following labels:
test_id - Unique test identifier (e.g., "1")
scenario - Scenario filename (e.g., "uac_invite.xml")
from_to - Caller and callee combined (e.g., "1000->2000")
Exported metric types:
sipp_calls_started_total (counter) - Total calls initiated
sipp_calls_completed_total (counter) - Successfully completed calls
sipp_calls_failed_total (counter) - Failed calls
sipp_calls_active (gauge) - Currently active calls
sipp_concurrent_calls_configured (gauge) - Configured concurrent call limit
Each SIPp test uses a dedicated UDP control port (8888 + test_id). Before starting a test, the module verifies the port is available. If another process is using the port, the test will fail with an error:
ERROR: control port 8889 is already in use - cannot start test ERROR: another SIPp instance or process may be using this port
Solutions:
Stop the conflicting process using that port
Wait for subsequent tests (higher test_id = higher port number)
Restart Kamailio to reset the test_id counter
When a test fails to start, detailed error messages are written to the Kamailio log. Check the log for messages from the sipp module:
grep "sipp" /var/log/kamailio.log
SIPp execution output is also captured in temporary log files:
/tmp/sipp_test_<id>_<timestamp>.log - Main SIPp log
/tmp/sipp_test_<id>_<timestamp>.log.exec.log - SIPp startup/error output
/tmp/sipp_test_<id>_<timestamp>.log.stat.csv - Statistics CSV