RPC Console

Table of Contents

1. Overview & Management Architecture
2. Business & Operational Significance
3. 🎯 User Roles & Key Capabilities
4. Visual Interface & Layout
5. Essential Command Catalog & Reference
6. Quick Command Shortcuts & Interactive Workflow
7. Security Safeguards & Audit Logging
8. Troubleshooting & Verification
9. Model Context Protocol (MCP) AI Integration
10. Glossary

---

1. Overview & Management Architecture

In Ring2All SBC, the RPC Console provides an interactive, terminal-like web interface for executing live management commands against the Kamailio core engine via its high-performance JSON-RPC interface (jsonrpcs module). Emulating the behavior of the native command-line utility kamcmd, the RPC Console allows engineers to query runtime memory statistics, inspect active dialog tables, trigger module reloads, and unblock blacklisted IPs directly from the browser.

       ┌─────────────────────────────────────────────────────────────┐
       │                Ring2All SBC Web Interface                   │
       │                   Interactive RPC Console                   │
       └──────────────────────────────┬──────────────────────────────┘
                                      │
                         JSON-RPC 2.0 Request Payload
                      {"method": "core.uptime", "id": 1}
                                      │
                                      ▼
       ┌─────────────────────────────────────────────────────────────┐
       │             Ring2All SBC API / Backend Daemon               │
       └──────────────────────────────┬──────────────────────────────┘
                                      │
                     UNIX Domain Socket (/run/kamailio/kamailio_rpc.sock)
                                      │
                                      ▼
       ┌─────────────────────────────────────────────────────────────┐
       │                 Kamailio JSON-RPC Server                    │
       │                     (jsonrpcs.so)                           │
       └─────────────────────────────┴──────────────────────────────┘

By communicating through a secured local UNIX domain socket rather than exposing network ports, the console achieves microsecond response times while preserving perimeter isolation.

---

2. Business & Operational Significance

• Rapid Incident Triage Without SSH: Empowers Network Operations Center (NOC) engineers to diagnose trunk degradation, SIP timeouts, and worker process states without requiring Linux root credentials.
• Instant Hot Reloading: Triggers live reloads of dispatchers (dispatcher.reload), memory trees (mtree.reload), TLS profiles (tls.reload), and dialplans in real time with zero packet loss.
• Real-Time Capacity & Memory Telemetry: Provides deep diagnostic visibility into shared memory (shm) pools, private process memory (pkg), and active dialog tables during peak load events.
• Immediate Security Remediation: Enables security personnel to instantly unblock false-positive IP bans or flush suspicious sessions with single-click commands.

---

3. 🎯 User Roles & Key Capabilities

Role	Primary Use Case	Key Capabilities
NOC Tier 2/3 Incident Responder	Live Signaling Triage	Query dispatcher gateway states, inspect in-flight dialogs, and verify SIP transaction throughput.
Senior SBC Telecom Engineer	Live Module Management	Execute hot reloads of routing tables, inspect shared memory fragmentation, and tune worker threads.
Security Operations Analyst	IP Ban Management	Dump active anti-flood tables (htable.dump ipban), investigate threat keys, and release blocked client IPs.
Capacity Planning Analyst	Performance Benchmarking	Extract statistical counters (stats.get_statistics all) to evaluate call completion rates and CPS trends.
AI NOC Diagnostics Agent / Operations Copilot	Low-Level Core Telemetry & Triage	Execute authorized Kamailio JSON-RPC commands, inspect shared memory fragmentation, and unban client IPs via MCP.

---

4. Visual Interface & Layout

The RPC Console provides a command execution input bar with command history support, quick-action badge shortcuts for standard queries, and a syntax-highlighted terminal window displaying formatted JSON responses.

---

5. Essential Command Catalog & Reference

5.1 Core Engine Commands

Command	Arguments	Purpose & Output
core.uptime	None	Returns the daemon uptime in seconds, startup timestamp, and current system time.
core.version	None	Returns the exact Kamailio version, compiler flags, and compiled module features.
core.shmmem	None	Displays shared memory pool metrics: total available, used, real used, and fragmentation count.
core.ps	None	Lists all active POSIX worker child processes, their process IDs (PIDs), and assigned tasks.

5.2 Dispatcher & Trunking Commands

Command	Arguments	Purpose & Output
dispatcher.list	None	Dumps all registered carrier gateways, distribution sets, operational states (Active/Probing/Inactive), and latencies.
dispatcher.reload	None	Reloads the dispatcher routing table from PostgreSQL without dropping active calls.
dispatcher.set_state	<state> <group> <address>	Manually sets a carrier gateway state (e.g., dispatcher.set_state 0 1 sip:192.168.10.50:5060 to force offline).

5.3 Dialogs & Active Calls

Command	Arguments	Purpose & Output
dlg.list	None	Dumps all active in-flight SIP dialogs, Call-IDs, duration timers, and caller/callee contact URIs.
dlg.profile_get_size	<profile_name>	Returns the total count of active calls currently tracked under a specific concurrency profile.
dlg.terminate_dlg	<call_id> <from_tag>	Forcefully terminates an active call by injecting BYE packets to both call legs.

5.4 Hash Tables & Security

Command	Arguments	Purpose & Output
htable.dump	<table_name>	Dumps all keys, values, and remaining TTLs for a specific hash table (e.g., htable.dump ipban).
htable.delete	<table_name> <key>	Immediately purges a specific key from memory (e.g., htable.delete ipban 192.168.11.199).
htable.sets	<table_name> <key> <val>	Sets a string value for a key in a hash table.

5.5 Statistics & Performance

Command	Arguments	Purpose & Output
stats.get_statistics	all / <group>	Returns real-time metrics for transactions (tm:), core counters (core:), and memory usage.

---

6. Quick Command Shortcuts & Interactive Workflow

The console header features pre-configured quick badges that execute standard diagnostic routines with a single click:

• Uptime (core.uptime): Instant verification that the Kamailio core daemon is running and responsive.
• Shm Memory (core.shmmem): Immediate health check of shared memory utilization to detect potential memory leaks.
• Dispatchers (dispatcher.list): Quick assessment of carrier trunk reachability and SIP options keepalive responses.
• IP Bans (htable.dump ipban): Fast inspection of currently blacklisted IP addresses.

---

7. Security Safeguards & Audit Logging

Because JSON-RPC commands operate directly upon runtime memory, Ring2All SBC enforces multi-layered governance:

1. Role-Based Access Control (RBAC): The RPC Console is strictly restricted to users holding the sbc.admin or system.superadmin permissions.
2. Dangerous Command Interception: Destructive commands (such as core.kill or manual memory freeing) are intercepted and restricted by backend authorization filters.
3. Audit Trail Logging: Every command executed via the console is logged in the Audit Logs module with the operator’s user identity, client IP address, timestamp, and command payload.

---

8. Troubleshooting & Verification

Validating JSON-RPC Socket Accessibility from OS

If the Web UI reports that the RPC server is unreachable, verify the UNIX socket on the SBC host:

ls -la /run/kamailio/kamailio_rpc.sock

Ensure the socket is owned by the kamailio:kamailio user with read/write permissions (0660).

Testing Execution via Native CLI (kamcmd)

kamcmd core.uptime

---

9. Model Context Protocol (MCP) AI Integration

The RPC Console module integrates with the Model Context Protocol (MCP) to allow diagnostic agents to execute authorized management commands, inspect core memory statistics, query suggested commands, and troubleshoot engine state.

Available MCP Tools

Tool Name	Operation Type	Risk Level	Description
execute_rpc_command	Core Command Execution	operational	Execute an authorized JSON-RPC management command directly against the Kamailio core engine.
get_rpc_suggestions	Catalog Query	read	Retrieve recommended RPC commands and catalog descriptions categorized by operational domain.

Tool Schemas & Payloads

1. execute_rpc_command

Input Schema

{
  "type": "object",
  "properties": {
    "command": {
      "type": "string",
      "description": "The RPC method name (e.g. 'core.uptime', 'dispatcher.list', 'core.shmmem')."
    },
    "params": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Optional array of string arguments for the RPC method."
    }
  },
  "required": ["command"]
}

Output Payload Example

{
  "success": true,
  "data": {
    "command": "core.uptime",
    "result": {
      "uptime": 864200,
      "uptime_formatted": "10 days, 0 hours, 3 minutes",
      "started": "2026-08-29T11:24:00Z"
    }
  }
}

2. get_rpc_suggestions

Input Schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["core", "dispatcher", "dialog", "htable", "stats"],
      "description": "Optional category filter."
    }
  }
}

Output Payload Example

{
  "success": true,
  "data": {
    "suggestions": [
      { "command": "core.uptime", "description": "Check Kamailio daemon uptime and startup time" },
      { "command": "core.shmmem", "description": "Check shared memory usage and fragmentation" },
      { "command": "dispatcher.list", "description": "List all carrier gateways and latency health" }
    ]
  }
}

Natural Language AI Prompts

English Examples

• “Run ‘core.uptime’ in the RPC Console to check how long Kamailio has been running.”
• “Inspect shared memory pool usage and fragmentation using ‘core.shmmem’.”
• “List all carrier trunks and their keepalive status using ‘dispatcher.list’.”

Spanish Examples (Español)

• “Ejecuta ‘core.uptime’ en la consola RPC para verificar cuánto tiempo lleva corriendo Kamailio.”
• “Inspecciona el uso de memoria compartida y fragmentación usando ‘core.shmmem’.”
• “Lista todas las troncales carrier y su estado de keepalive usando ‘dispatcher.list’.”

Enterprise Safeguards & Access Governance

1. Destructive Command Interception: Commands that attempt to kill the engine or wipe runtime structures are strictly blocked by whitelist validation.
2. UNIX Socket Boundary: Communications travel exclusively across a local /run/kamailio/kamailio_rpc.sock domain socket with strict OS filesystem permissions.
3. Role Enforcement: RPC execution requires the sbc_system_admin or noc_network_engineer role; unauthorized roles cannot trigger runtime commands.

---

10. Glossary

• JSON-RPC: A lightweight remote procedure call (RPC) protocol encoded in JSON format.
• UNIX Domain Socket: An inter-process communication endpoint for bidirectional data exchange between processes executing on the same host operating system.
• AVP (Attribute-Value Pair): A variable attached to a SIP transaction or user in Kamailio routing logic.
• kamcmd: The official command-line administration utility for Kamailio, communicating with the core engine via RPC sockets.