---
title: "RPC Console"
description: "Documentation for RPC Console"
---

## Table of Contents
1. [Overview & Management Architecture](#1-overview--management-architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Layout](#4-visual-interface--layout)
5. [Essential Command Catalog & Reference](#5-essential-command-catalog--reference)
6. [Quick Command Shortcuts & Interactive Workflow](#6-quick-command-shortcuts--interactive-workflow)
7. [Security Safeguards & Audit Logging](#7-security-safeguards--audit-logging)
8. [Troubleshooting & Verification](#8-troubleshooting--verification)
9. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration)
10. [Glossary](#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.

![RPC Console Terminal Interface](/screenshots/sbc/settings/tools/rpc-console/rpc-console.png)

---

## 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:
```bash
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`)
```bash
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
```json
{
  "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
```json
{
  "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
```json
{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": ["core", "dispatcher", "dialog", "htable", "stats"],
      "description": "Optional category filter."
    }
  }
}
```

##### Output Payload Example
```json
{
  "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.