Troubleshooting Examples

The OpenSIPS MCP Server provides tools and prompts that help diagnose and resolve common SIP issues.

Using Troubleshooting Prompts

Call Failures

Start a guided troubleshooting session:

{
  "prompt": "troubleshoot_calls",
  "arguments": {
    "symptom": "Outbound calls to PSTN numbers fail with 503 Service Unavailable",
    "caller": "sip:1001@example.com",
    "callee": "sip:+14155551234@example.com"
  }
}

The prompt will guide you through a systematic diagnosis:

1. Check OpenSIPS health and MI connectivity.
2. Verify the caller is registered.
3. Check dynamic routing rules for the dialed prefix.
4. Verify gateway availability.
5. Examine SIP transaction logs.
6. Suggest fixes based on findings.

Registration Failures

{
  "prompt": "troubleshoot_registration",
  "arguments": {
    "symptom": "User 1001 cannot register - getting 401 Unauthorized after providing credentials",
    "user": "1001@example.com"
  }
}

Error Code Explanation

{
  "prompt": "explain_error",
  "arguments": {
    "error": "488 Not Acceptable Here"
  }
}

Step-by-Step Manual Troubleshooting

Scenario: Calls Failing with 503

Step 1: Health check

{"tool": "health_check", "arguments": {}}

Verify mi_reachable is true and status is healthy.

Step 2: Check active dialogs

{"tool": "dlg_list", "arguments": {}}

If there are no active dialogs, calls are not being established at all.

Step 3: Check dispatcher/gateway status

{"tool": "dispatcher_list_db", "arguments": {"setid": 1}}

Look for destinations with state != 0 (disabled or probing-failed).

Step 4: Check load balancer status (if using lb module)

{"tool": "lb_list", "arguments": {}}

Look for destinations marked as unavailable.

Step 5: Check dynamic routing rules

{"tool": "drouting_list_rules", "arguments": {"prefix": "1"}}

Verify that a matching rule exists for the dialed prefix.

Step 6: Check DR gateways

{"tool": "drouting_list_gateways", "arguments": {}}

Verify the gateways referenced in the rule exist and are active (state = 0).

Step 7: Check statistics for errors

{"tool": "get_statistics", "arguments": {"group": "tm"}}

Look at transaction manager stats for high failure rates.

Scenario: Registration Not Working

Step 1: Check if user exists in the database

{"tool": "subscriber_list", "arguments": {"domain": "example.com"}}

Step 2: Check user location

{"tool": "ul_show_contacts", "arguments": {"aor": "1001@example.com"}}

If no contacts are returned, the registration is not being saved.

Step 3: Check registrar stats

{"tool": "registrar_stats", "arguments": {}}

Look for rejected registrations or authentication failures.

Step 4: Verify HA1 hash

{"tool": "security_generate_ha1", "arguments": {"username": "1001", "domain": "example.com", "password": "user-password"}}

Compare the generated HA1 with the one stored in the subscriber table. A mismatch means the password or domain is wrong.

Scenario: High Memory Usage

Step 1: Check memory stats

{"tool": "get_memory_stats", "arguments": {}}

Compare used_size against total_size. If usage is above 80%, investigate further.

Step 2: Check process list

{"tool": "get_process_list", "arguments": {}}

Look for processes consuming disproportionate memory.

Step 3: Check active dialogs

{"tool": "dlg_list", "arguments": {}}

A large number of active dialogs (thousands) can consume significant memory. Look for stale dialogs that should have been cleaned up.

Step 4: Check user location table

{"tool": "ul_dump", "arguments": {"brief": true}}

An unusually large number of registrations could indicate a flood attack.

Scenario: Pike Blocking Legitimate Traffic

Step 1: List blocked IPs

{"tool": "pike_list_blocked", "arguments": {}}

Step 2: Identify legitimate IPs

Check if known carrier or internal IPs appear in the blocked list.

Step 3: Unblock the IP

{"tool": "pike_unblock_ip", "arguments": {"ip": "10.0.0.50"}}

Step 4: Add the IP to the address permission whitelist

{"tool": "address_add", "arguments": {"grp": 1, "ip": "10.0.0.50", "mask": 32, "context_info": "internal-pbx"}}

Scenario: Checking Call Quality Issues

Step 1: Check RTPEngine status

{"tool": "rtpengine_show", "arguments": {}}

Verify all RTPEngine instances are active.

Step 2: Check TCP connections

{"tool": "get_tcp_connections", "arguments": {}}

A large number of connections in TIME_WAIT or CLOSE_WAIT may indicate resource exhaustion.

Step 3: Check overall statistics

{"tool": "get_statistics", "arguments": {"group": "all"}}

Look for anomalies in request/reply ratios, retransmission counts, or error rates.

Security Audit

Audit an OpenSIPS Configuration

{"tool": "security_audit_config", "arguments": {"config": "# paste your opensips.cfg here"}}

The audit checks for common security issues such as:

• Missing authentication on public interfaces
• Weak TLS settings
• Missing anti-flood protection
• Open relay configurations
• Hardcoded credentials

Full Security Audit Prompt

{
  "prompt": "security_audit",
  "arguments": {
    "focus": "authentication"
  }
}

This runs a comprehensive security review focused on the specified area.