API Reference
April 28, 2026 · View on GitHub
Complete listing of all MCP tools, resources, and prompts provided by the OpenSIPS MCP Server.
Tools
MI Commands
mi_execute
Execute an arbitrary OpenSIPS MI command.
| Parameter | Type | Required | Description |
|---|---|---|---|
command | string | Yes | MI command name (e.g. ul_dump, lb_list) |
params | dict | No | Parameters for the MI command |
Permission: mi.execute
mi_list_commands
List all MI commands available on the connected OpenSIPS instance.
Permission: mi.list
get_statistics
Retrieve OpenSIPS runtime statistics.
| Parameter | Type | Required | Description |
|---|---|---|---|
group | string | No | Statistics group (core, shmem, net, tm, sl, usrloc, or all). Default: all |
name | string | No | Specific statistic name within the group |
Permission: stats.read
health_check
Run a comprehensive health check against the OpenSIPS instance. Checks MI connectivity, basic statistics, and uptime.
Permission: health.read
User Location
ul_show_contacts
Show registered contacts for an Address of Record.
| Parameter | Type | Required | Description |
|---|---|---|---|
table | string | No | Usrloc table name. Default: location |
aor | string | Yes | Address of Record to look up |
Permission: mi.read
ul_dump
Dump all registered users from the user location table.
| Parameter | Type | Required | Description |
|---|---|---|---|
table | string | No | Usrloc table name. Default: location |
brief | bool | No | Return abbreviated output |
Permission: mi.read
ul_add_contact
Add a contact binding to the user location table.
| Parameter | Type | Required | Description |
|---|---|---|---|
table | string | No | Usrloc table name. Default: location |
aor | string | Yes | Address of Record |
contact | string | Yes | Contact URI |
expires | int | No | Expiration time in seconds |
q | float | No | Contact priority (0.0-1.0) |
Permission: mi.write
ul_remove_contact
Remove a contact binding from the user location table.
| Parameter | Type | Required | Description |
|---|---|---|---|
table | string | No | Usrloc table name. Default: location |
aor | string | Yes | Address of Record |
contact | string | Yes | Contact URI to remove |
Permission: mi.write
Dialog Management
dlg_list
List active dialogs with optional filtering.
| Parameter | Type | Required | Description |
|---|---|---|---|
callid | string | No | Filter by Call-ID |
from_tag | string | No | Filter by From-tag |
Permission: mi.read
dlg_end
Terminate an active dialog.
| Parameter | Type | Required | Description |
|---|---|---|---|
callid | string | Yes | Call-ID of the dialog |
from_tag | string | Yes | From-tag of the dialog |
to_tag | string | Yes | To-tag of the dialog |
Permission: mi.write
dlg_get_profiles
Get the size of dialog profiles.
| Parameter | Type | Required | Description |
|---|---|---|---|
profile | string | Yes | Dialog profile name |
value | string | No | Specific profile value to count |
Permission: mi.read
dlg_push_var
Set a variable on an active dialog.
| Parameter | Type | Required | Description |
|---|---|---|---|
callid | string | Yes | Call-ID of the dialog |
from_tag | string | Yes | From-tag |
to_tag | string | Yes | To-tag |
var_name | string | Yes | Variable name |
var_value | string | Yes | Variable value |
Permission: mi.write
Subscriber Management
subscriber_list
List subscribers with pagination.
| Parameter | Type | Required | Description |
|---|---|---|---|
domain | string | No | Filter by SIP domain |
limit | int | No | Max records to return. Default: 100 |
offset | int | No | Pagination offset. Default: 0 |
Permission: db.read
subscriber_get
Get a subscriber by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | int | Yes | Subscriber database ID |
Permission: db.read
subscriber_create
Create a new subscriber.
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | Yes | SIP username |
domain | string | Yes | SIP domain |
password | string | Yes | Password (HA1 hash is computed) |
Permission: db.write
subscriber_update
Update subscriber fields.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | int | Yes | Subscriber database ID |
password | string | No | New password |
email_address | string | No | New email address |
rpid | string | No | New Remote-Party-ID |
Permission: db.write
subscriber_delete
Delete a subscriber.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | int | Yes | Subscriber database ID |
Permission: db.write
Dispatcher (Load Balancing)
dispatcher_list_db
List dispatcher destinations from the database.
| Parameter | Type | Required | Description |
|---|---|---|---|
setid | int | No | Filter by dispatcher set ID |
limit | int | No | Max records to return |
offset | int | No | Pagination offset |
Permission: db.read
dispatcher_add
Add a new dispatcher destination.
| Parameter | Type | Required | Description |
|---|---|---|---|
setid | int | Yes | Dispatcher set ID |
destination | string | Yes | SIP URI of the destination |
flags | int | No | Flags. Default: 0 |
priority | int | No | Priority. Default: 0 |
attrs | string | No | Attributes string |
description | string | No | Human-readable description |
weight | int | No | Weight for load distribution |
socket | string | No | Outbound socket |
Permission: db.write
dispatcher_update
Update an existing dispatcher destination.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | int | Yes | Dispatcher record ID |
setid | int | No | New set ID |
destination | string | No | New destination URI |
flags | int | No | New flags |
priority | int | No | New priority |
attrs | string | No | New attributes |
description | string | No | New description |
weight | int | No | New weight |
Permission: db.write
dispatcher_remove
Remove a dispatcher destination.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | int | Yes | Dispatcher record ID |
Permission: db.write
Dynamic Routing
drouting_list_rules
List dynamic routing rules.
| Parameter | Type | Required | Description |
|---|---|---|---|
groupid | string | No | Filter by group ID |
prefix | string | No | Filter by prefix |
limit | int | No | Max records |
offset | int | No | Pagination offset |
Permission: db.read
drouting_add_rule
Add a dynamic routing rule.
| Parameter | Type | Required | Description |
|---|---|---|---|
groupid | string | Yes | Group ID |
prefix | string | Yes | Digit prefix to match |
gwlist | string | Yes | Gateway list (comma-separated IDs) |
priority | int | No | Rule priority |
routeid | string | No | Route ID |
timerec | string | No | Time recurrence |
attrs | string | No | Attributes |
description | string | No | Description |
sort_alg | string | No | Sort algorithm (N, W, etc.) |
Permission: db.write
drouting_list_gateways
List dynamic routing gateways.
| Parameter | Type | Required | Description |
|---|---|---|---|
type | int | No | Filter by gateway type |
limit | int | No | Max records |
offset | int | No | Pagination offset |
Permission: db.read
drouting_add_gateway
Add a dynamic routing gateway.
| Parameter | Type | Required | Description |
|---|---|---|---|
address | string | Yes | Gateway SIP address |
type | int | No | Gateway type |
strip | int | No | Digits to strip |
pri_prefix | string | No | Prefix to prepend |
attrs | string | No | Attributes |
probe_mode | int | No | OPTIONS probe mode |
description | string | No | Description |
Permission: db.write
drouting_list_carriers
List dynamic routing carriers.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | int | No | Max records |
offset | int | No | Pagination offset |
Permission: db.read
drouting_add_carrier
Add a dynamic routing carrier.
| Parameter | Type | Required | Description |
|---|---|---|---|
carrierid | string | Yes | Carrier identifier |
gwlist | string | Yes | Gateway list |
flags | int | No | Flags |
sort_alg | string | No | Sort algorithm |
attrs | string | No | Attributes |
description | string | No | Description |
Permission: db.write
Load Balancer
lb_list
List load balancer destinations and their resource status.
Permission: mi.read
lb_reload
Reload the load balancer table from the database.
Permission: mi.execute
lb_set_status
Enable or disable a load balancer destination.
| Parameter | Type | Required | Description |
|---|---|---|---|
group | int | Yes | Destination group ID |
uri | string | Yes | Destination SIP URI |
status | int | Yes | 0 = active, 1 = disabled |
Permission: mi.execute
lb_resize
Resize a load balancer resource.
| Parameter | Type | Required | Description |
|---|---|---|---|
group | int | Yes | Destination group ID |
uri | string | Yes | Destination SIP URI |
resource | string | Yes | Resource name |
value | int | Yes | New resource value |
Permission: mi.execute
Call Center
cc_list_queue
List the call center queue (waiting calls).
Permission: mi.read
cc_list_agents
List all call center agents and their status.
Permission: mi.read
cc_agent_login
Login or logout a call center agent.
| Parameter | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | Agent identifier |
state | int | Yes | 1 = login, 0 = logout |
Permission: mi.execute
cc_reload_tool
Reload call center configuration from the database.
Permission: mi.execute
cc_status
Get call center statistics (queue size, agent counts, etc.).
Permission: mi.read
Permissions
address_list
List address permission entries.
| Parameter | Type | Required | Description |
|---|---|---|---|
grp | int | No | Filter by permission group |
limit | int | No | Max records |
offset | int | No | Pagination offset |
Permission: db.read
address_add
Add an address permission entry.
| Parameter | Type | Required | Description |
|---|---|---|---|
grp | int | Yes | Permission group |
ip | string | Yes | IP address |
mask | int | No | Network mask (CIDR). Default: 32 |
port | int | No | Port (0 = any). Default: 0 |
proto | string | No | Protocol (udp, tcp, tls, any). Default: any |
pattern | string | No | Matching pattern |
context_info | string | No | Context info string |
Permission: db.write
address_remove
Remove an address permission entry.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | int | Yes | Address record ID |
Permission: db.write
Security
pike_list_blocked
List IP addresses currently blocked by the Pike anti-flood module.
Permission: mi.read
pike_unblock_ip
Remove an IP address from the Pike block list.
| Parameter | Type | Required | Description |
|---|---|---|---|
ip | string | Yes | IP address to unblock |
Permission: mi.execute
security_generate_ha1
Generate HA1 and HA1B digest authentication hashes.
| Parameter | Type | Required | Description |
|---|---|---|---|
username | string | Yes | SIP username |
domain | string | Yes | SIP domain |
password | string | Yes | Password |
Permission: db.read
security_audit_config
Perform a basic security audit on an OpenSIPS configuration snippet.
| Parameter | Type | Required | Description |
|---|---|---|---|
config | string | Yes | OpenSIPS configuration text |
Permission: config.read
RTPEngine
rtpengine_show
Show RTPEngine node status and statistics.
Permission: mi.read
rtpengine_enable
Enable or disable an RTPEngine instance.
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | Yes | RTPEngine socket URL |
enable | int | Yes | 1 = enable, 0 = disable |
Permission: mi.execute
rtpengine_reload
Reload RTPEngine configuration.
Permission: mi.execute
Rate Limiting
ratelimit_status
Show the status of all rate limit pipes.
Permission: mi.read
ratelimit_reset
Reset a rate limit pipe counter.
| Parameter | Type | Required | Description |
|---|---|---|---|
pipe | string | Yes | Pipe name to reset |
Permission: mi.execute
Cluster
cluster_status
Show cluster node status.
Permission: mi.read
cluster_topology
Show cluster topology (nodes and links).
Permission: mi.read
cluster_send_command
Send a command to cluster nodes.
| Parameter | Type | Required | Description |
|---|---|---|---|
cluster_id | int | Yes | Cluster ID |
command | string | Yes | Command to broadcast |
node | int | No | Target node (omit for broadcast) |
Permission: mi.execute
Tracing
trace_control
Enable or disable SIP tracing.
| Parameter | Type | Required | Description |
|---|---|---|---|
action | string | Yes | on or off |
trace_id | string | No | Specific trace ID |
Permission: mi.execute
trace_start_live
Start a live SIP trace session.
| Parameter | Type | Required | Description |
|---|---|---|---|
filter | string | No | SIP message filter expression |
Permission: mi.execute
Registrar
registrar_stats
Retrieve registrar statistics (registrations, lookups, etc.).
Permission: stats.read
Accounting
acc_query_cdrs
Query Call Detail Records from the accounting table.
| Parameter | Type | Required | Description |
|---|---|---|---|
from_date | string | No | Start date (ISO 8601) |
to_date | string | No | End date (ISO 8601) |
caller | string | No | Filter by caller |
callee | string | No | Filter by callee |
limit | int | No | Max records. Default: 100 |
Permission: db.read
acc_query_missed
Query missed call records.
| Parameter | Type | Required | Description |
|---|---|---|---|
from_date | string | No | Start date (ISO 8601) |
to_date | string | No | End date (ISO 8601) |
caller | string | No | Filter by caller |
callee | string | No | Filter by callee |
limit | int | No | Max records. Default: 100 |
Permission: db.read
Diagnostics
get_process_list
List all OpenSIPS worker processes.
Permission: mi.read
get_memory_stats
Get shared and private memory statistics.
Permission: mi.read
get_uptime
Get the server uptime.
Permission: mi.read
get_tcp_connections
List active TCP connections.
Permission: mi.read
opensips_version
Get the OpenSIPS version string.
Permission: mi.read
Configuration Engine
cfg_generate
Generate an OpenSIPS configuration from a predefined scenario template.
| Parameter | Type | Required | Description |
|---|---|---|---|
scenario | string | Yes | Scenario name (e.g. load_balancer, webrtc_gateway) |
params | dict | No | Template parameters |
Permission: config.generate
cfg_validate
Validate an OpenSIPS configuration by running opensips -C -f.
| Parameter | Type | Required | Description |
|---|---|---|---|
config | string | Yes | Configuration text to validate |
Permission: config.read
cfg_parse
Parse an OpenSIPS configuration and extract its structure (modules, routes, globals).
| Parameter | Type | Required | Description |
|---|---|---|---|
config | string | Yes | Configuration text to parse |
Permission: config.read
cfg_list_scenarios
List all available configuration scenarios with descriptions.
Permission: config.read
cfg_get_scenario_params
Get required and optional parameters for a scenario.
| Parameter | Type | Required | Description |
|---|---|---|---|
scenario | string | Yes | Scenario name |
Permission: config.read
cfg_diff
Compute a unified diff between two OpenSIPS configurations.
| Parameter | Type | Required | Description |
|---|---|---|---|
config_a | string | Yes | First configuration text |
config_b | string | Yes | Second configuration text |
Permission: config.read
cfg_explain_route
Explain an OpenSIPS route block by identifying its components.
| Parameter | Type | Required | Description |
|---|---|---|---|
route_code | string | Yes | Route block source code |
Permission: config.read
cfg_add_module
Add a module to an existing OpenSIPS configuration.
| Parameter | Type | Required | Description |
|---|---|---|---|
config | string | Yes | Existing configuration text |
module | string | Yes | Module name to add |
params | dict | No | Module parameters |
Permission: config.generate
cfg_optimize
Analyze an OpenSIPS configuration and suggest optimizations.
| Parameter | Type | Required | Description |
|---|---|---|---|
config | string | Yes | Configuration text to analyze |
Permission: config.read
cfg_generate_iterative
Generate an OpenSIPS config and iteratively validate it.
| Parameter | Type | Required | Description |
|---|---|---|---|
scenario | string | Yes | Scenario name |
params | dict | No | Template parameters |
max_iterations | int | No | Max validation attempts |
Permission: config.generate
Resources
| URI | Description |
|---|---|
opensips://system/version | OpenSIPS version string from the MI version command |
opensips://system/uptime | Server uptime from the MI uptime command |
opensips://system/processes | Running OpenSIPS processes from MI ps |
opensips://system/memory | Shared and private memory usage |
opensips://stats/all | All runtime statistics |
opensips://modules/list | List of known OpenSIPS modules with brief descriptions |
opensips://modules/{name} | Detailed documentation for a specific module |
opensips://docs/mi/{command} | Documentation for a specific MI command |
opensips://templates/list | Available configuration scenario templates |
opensips://templates/{scenario} | Raw Jinja2 template source for a scenario |
opensips://scenarios/list | Deployment scenario catalog with Docker info |
opensips://scenarios/{name} | Detailed scenario description and configuration |
opensips://db/subscribers | Snapshot of the subscriber table |
opensips://db/dispatchers | Snapshot of the dispatcher table |
Prompts
Configuration
build_config
Interactive configuration builder that guides through scenario selection and parameter input.
| Argument | Type | Required | Description |
|---|---|---|---|
scenario | string | No | Pre-selected scenario |
requirements | string | No | Free-text requirements |
optimize_performance
Performance tuning advisor that analyzes current stats and config.
| Argument | Type | Required | Description |
|---|---|---|---|
current_config | string | No | Current configuration to analyze |
workload | string | No | Expected workload description |
design_architecture
SIP architecture designer for multi-node deployments.
| Argument | Type | Required | Description |
|---|---|---|---|
requirements | string | Yes | Architecture requirements |
scale | string | No | Expected call volume |
Troubleshooting
troubleshoot_calls
Call failure troubleshooting workflow.
| Argument | Type | Required | Description |
|---|---|---|---|
symptom | string | Yes | Description of the call failure |
caller | string | No | Caller URI |
callee | string | No | Callee URI |
troubleshoot_registration
Registration failure troubleshooting workflow.
| Argument | Type | Required | Description |
|---|---|---|---|
symptom | string | Yes | Description of the registration failure |
user | string | No | Affected user |
explain_error
SIP or OpenSIPS error code/message explainer.
| Argument | Type | Required | Description |
|---|---|---|---|
error | string | Yes | Error message or SIP response code |
Security
security_audit
Security configuration audit that reviews the running config for common issues.
| Argument | Type | Required | Description |
|---|---|---|---|
config | string | No | Configuration to audit |
focus | string | No | Area to focus on (auth, tls, acl, etc.) |
Education
teach_concept
SIP/VoIP concept educator.
| Argument | Type | Required | Description |
|---|---|---|---|
topic | string | Yes | Concept to explain (e.g. "SIP registration", "dialog state") |
explain_sip_ladder
SIP ladder diagram analyzer that explains message flows.
| Argument | Type | Required | Description |
|---|---|---|---|
sip_trace | string | Yes | SIP trace or ladder diagram text |
explain_route
OpenSIPS route block explainer.
| Argument | Type | Required | Description |
|---|---|---|---|
route_code | string | Yes | OpenSIPS route block code |
debug_sip_message
SIP message parser and debugger.
| Argument | Type | Required | Description |
|---|---|---|---|
sip_message | string | Yes | Raw SIP message text |
SIP Operations
plan_capacity
SIP capacity planning advisor.
| Argument | Type | Required | Description |
|---|---|---|---|
call_volume | string | Yes | Expected call volume (CPS, concurrent calls) |
features | string | No | Required features (recording, transcoding, etc.) |
write_module
OpenSIPS C module development guide and scaffolding.
| Argument | Type | Required | Description |
|---|---|---|---|
module_name | string | Yes | Name of the module to develop |
description | string | No | Module purpose and functionality |
Migration
migrate_version
Version migration assistant.
| Argument | Type | Required | Description |
|---|---|---|---|
from_version | string | Yes | Current OpenSIPS version |
to_version | string | Yes | Target OpenSIPS version |
compare_modules
Module comparison guide between OpenSIPS versions.
| Argument | Type | Required | Description |
|---|---|---|---|
module | string | Yes | Module name to compare |
version_a | string | Yes | First version |
version_b | string | Yes | Second version |
Operational tools (Top-10 coverage expansion)
These tools fill the workflow gaps an audit identified in April 2026: Homer integration, graceful reload orchestration, cluster drain, CDR audit, NAT-flow diagnosis, RTPEngine control, bulk subscriber ops, synthetic SIP traffic, performance sampling, and cfg backup/rollback.
Homer (advanced)
Complements the beginner-friendly homer_search_calls /
homer_get_call_flow / homer_stats tools in ecosystem_tools. All
require OPENSIPS_MCP_HOMER_URL pointing at a Homer 7 / homer-app
deployment.
homer_search_calls_v7
Homer 7 native search with ms-precision timestamps and source-IP filter.
| Parameter | Type | Required | Description |
|---|---|---|---|
from_ts, to_ts | int | Yes | Unix timestamps in milliseconds |
from_user, to_user | string | No | Substring match on SIP From/To user |
callid | string | No | Exact SIP Call-ID |
source_ip | string | No | Source IP filter |
limit | int | No | Default 50, cap 500 |
homer_get_call_transaction
Fetch every captured SIP message for a Call-ID (timestamp-windowed).
homer_correlate_callid
Find sibling Call-IDs when OpenSIPS rewrites Call-ID mid-dialog (B2BUA, topology_hiding).
homer_health
Status probe against /api/v3/status. Returns {ok: false} when
Homer is not configured — never raises.
Reload orchestration
reload_data_tables
Fire every data-table reload (ds_reload, dr_reload, lb_reload,
dp_reload, tls_reload, ...) in dependency order. Missing commands
are reported as skipped, not failures.
| Parameter | Type | Required | Description |
|---|---|---|---|
targets | list[str] | No | Whitelist of module names to reload |
stop_on_error | bool | No | Abort on first failure. Default False |
delay_ms_between | int | No | Per-call spacing. Default 100ms |
reload_single
Reload one module and (optionally) snapshot its stats after.
reload_dry_run
Preview which reloads would run, based on which enumeration.
Cluster orchestration
cluster_drain_node
Disable a node in the clusterer and poll dialog count until it hits zero (or timeout). Does NOT stop the OpenSIPS process — combine with your init-script.
| Parameter | Type | Required | Description |
|---|---|---|---|
cluster_id, node_id | int | Yes | Target node |
timeout_sec | int | No | 5..600, default 60 |
poll_interval_sec | int | No | 1..60, default 5 |
cluster_promote_node
Flip status back to active after maintenance.
cluster_sync_check
Report node list, capabilities, sharing tags, and topology in one call.
Derives a simple healthy: true/false.
CDR audit
cdr_audit
Scan the acc table for gaps, duplicate Call-IDs, and duration
anomalies (negative, excessive, connected-with-zero-duration).
| Parameter | Type | Required | Description |
|---|---|---|---|
date_from, date_to | ISO string | Yes | Window, capped at 31 days |
max_gap_sec | int | No | Suspicious-silence threshold. Default 300 |
long_call_threshold_sec | int | No | Stuck-dialog threshold. Default 14400 |
cdr_summary
Volume + answered/failed breakdown grouped by hour or day.
cdr_count_by_code
SIP-response-code histogram for a window.
NAT diagnosis
diagnose_nat_flow
One-call triage for "why is this call one-way audio?". Correlates dialog state, RTPEngine state, and nathelper/tm/dialog stats, plus returns heuristic hints.
RTPEngine (new)
rtpengine_terminate_call
MI teardown — forcibly free a media session when signalling leaves
one stranded.
rtpengine_instance_health
Fold rtpengine_show + rtpengine: stats into one call.
Subscriber bulk ops
subscriber_bulk_import
Import a CSV of (username, domain, password [, email_address, rpid]).
Cap: 5000 rows. Modes: skip / overwrite / error. dry_run=True
by default — always review the plan before committing.
subscriber_bulk_export
CSV dump of subscribers. include_ha1=True is opt-in: credential
material does not leave the DB by accident.
Performance
perf_process_breakdown
Group OpenSIPS child processes by role (UDP, TCP, timer, HTTPD, ...).
perf_memory_report
mem + shmem: / pkmem: stats. Watch shmem in production.
perf_sample_window
Sample selected get_statistics groups at a fixed cadence (1..10 min,
2..60 samples) and return the raw series.
perf_hotspots
One-shot "where is the pain?" view: memory + core rates + process count in a single call.
Synthetic SIP traffic
sip_options_ping
Pure-Python UDP OPTIONS probe. Refuses public-IP targets unless
allow_public=True.
| Parameter | Type | Required | Description |
|---|---|---|---|
target | string | Yes | host[:port], port defaults to 5060 |
count | int | No | 1..20, default 3 |
timeout_sec | float | No | 0.2..10, default 2.0 |
from_uri | string | No | Synthetic From URI so traffic analysis can filter it |
allow_public | bool | No | Must be True for non-private addresses |
sip_generate_sipp_scenario
Generate a SIPp XML scenario (options / register /
invite_uas_ringing) and the exact run command. Does not execute
SIPp — the MCP process is the wrong place to originate load.
Config backup / rollback
cfg_backup
Copy <config> to <config>.bak-YYYYMMDD-HHMMSS within an allowlisted
dir (/tmp, /var/tmp, $HOME, or the OPENSIPS_MCP_OUT_DIR_ROOT
override).
cfg_list_backups
Enumerate .bak-* siblings of a config, sorted newest first.
cfg_rollback
Restore a backup. Before overwriting, the current target file is
itself snapshotted as <target>.pre-rollback-<ts> so the rollback is
reversible one more step. validate_after=True runs the restored
file through opensips -C; a validation failure is reported but does
NOT undo the restore.
Observability stack generator
The observability tools synthesise a complete monitoring deployment (Grafana dashboards + Prometheus scrape config + Grafana provisioning
- a docker-compose for the monitoring side-car stack) tailored to the exact OpenSIPS scenario being deployed. Panel categories are picked from the loaded modules so the dashboard set never drifts from what the cfg actually exposes.
observability_list_panel_categories
Return every panel category (overview, dialog/calls, dispatcher, rtpengine, tls, security, ims, b2b, ...). No parameters.
observability_categories_for_modules
Given a list of loadmodule names, return which panel categories
would fire. Useful for previewing a dashboard set before generating.
| Parameter | Type | Required | Description |
|---|---|---|---|
modules | list[str] | Yes | Module names (with or without .so) |
observability_generate_dashboards
Generate Grafana dashboards for a scenario.
| Parameter | Type | Required | Description |
|---|---|---|---|
scenario | string | Yes | Scenario name (must exist in cfg engine) |
params | dict | No | Same params you'd pass to cfg_generate |
instance_label | string | No | Default instance filter for templating |
observability_generate_dashboards_from_cfg
Same idea but takes an arbitrary rendered cfg instead of a scenario
name. Useful when you've already produced a custom cfg via
cfg_generate_iterative or hand-edited.
observability_generate_prometheus_scrape
Emit a Prometheus scrape_configs YAML stanza for one or more
OpenSIPS instances exposing /metrics.
| Parameter | Type | Required | Description |
|---|---|---|---|
targets | list[str] | Yes | host:port of each OpenSIPS metrics endpoint |
job_name | string | No | scrape_configs.job_name. Default opensips. |
scrape_interval | string | No | Prometheus duration. Default 15s. |
observability_generate_grafana_provisioning
Emit Grafana provisioning files: a Prometheus datasource definition
- a dashboard provider that auto-loads dashboards from a directory.
Drop both into Grafana's
/etc/grafana/provisioning/.
observability_generate_monitoring_compose
Emit a docker-compose YAML for a side-car Prometheus + Grafana stack
that points at the OpenSIPS instances you specify. Pair with the
observability_generate_grafana_provisioning output.
observability_inject_prometheus
Add loadmodule "prometheus.so" + loadmodule "httpd.so" to a
rendered cfg if they aren't already present. Idempotent. Returns the
modified cfg + a list of warnings (e.g. existing httpd port collision).
observability_generate_bundle
The headline tool. One call → deployment-ready bundle:
- Rendered OpenSIPS cfg with prometheus module injected
- Per-category Grafana dashboard JSON files
- Prometheus scrape YAML
- Grafana datasource + dashboard-provider provisioning files
- docker-compose for the side-car monitoring stack
- README explaining how to deploy
| Parameter | Type | Required | Description |
|---|---|---|---|
scenario | string | Yes | Scenario name |
params | dict | No | Scenario render params |
targets | list[str] | No | Prometheus scrape targets. Default ["localhost:8888"] |
observability_generate_bundle_from_cfg
Same as observability_generate_bundle but starts from an existing
cfg string instead of a scenario name.
observability_save_bundle
Persist a bundle returned by observability_generate_bundle* to disk
under an allowlisted directory (/tmp, /var/tmp, $HOME, or
OPENSIPS_MCP_OUT_DIR_ROOT). Rejects path traversal in the bundle's
own filenames.
| Parameter | Type | Required | Description |
|---|---|---|---|
bundle | dict | Yes | The bundle dict returned by a generator |
out_dir | string | Yes | Target directory (must be in safe allowlist) |