---
title: "Access Control Lists (ACL) & Trusted SIP Peers"
description: "Documentation for Access Control Lists (ACL)"
---

## Table of Contents
1. [Overview & Permissions Architecture](#1-overview--permissions-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. [Field Reference: Trusted IPs & Address Groups](#5-field-reference-trusted-ips--address-groups)
6. [Kamailio Permissions Module & Routing Logic](#6-kamailio-permissions-module--routing-logic)
7. [Address Group Numbering & Telephony Roles](#7-address-group-numbering--telephony-roles)
8. [Operational Hardening & Best Practices](#8-operational-hardening--best-practices)
9. [Verification & Diagnostics](#9-verification--diagnostics)
10. [Model Context Protocol (MCP) AI Integration](#10-model-context-protocol-mcp-ai-integration)
11. [Glossary](#11-glossary)

---

## 1. Overview & Permissions Architecture

In **Ring2All SBC**, the **Access Control List (ACL)** module delivers telecom-grade trust governance and IP authorization for SIP signaling. Directly backed by Kamailio's native **permissions** module, the ACL engine manages two fundamental database tables: **`kamailio.trusted`** (IP-based authentication for PBX core nodes and carrier gateways) and **`kamailio.address`** (group-based IP/subnet routing classifications).

```
       ┌─────────────────────────────────────────────────────────────┐
       │                 INCOMING SIP SIGNALING PACKET               │
       │                   (Source IP, Protocol, Port)               │
       └──────────────────────────────┬──────────────────────────────┘
                                      │
       ┌──────────────────────────────▼──────────────────────────────┐
       │          KAMAILIO PERMISSIONS MODULE EVALUATION             │
       └──────────────────────────────┬──────────────────────────────┘
                                      │
              ┌───────────────────────┴───────────────────────┐
              ▼                                               ▼
       ┌──────────────────────────────┐                ┌──────────────────────────────┐
       │   check_source_address(grp)  │                │     allow_trusted() CHECK    │
       │    (Table: kamailio.address) │                │    (Table: kamailio.trusted) │
       ├──────────────────────────────┤                ├──────────────────────────────┤
       │ • Group 1: Trusted SBC Node  │                │ • Core Telephony Cluster    │
       │ • Group 8: PBX Auth (Bypass) │                │ • Carrier Wholesale Gateways │
       │ • Group 9: CPS Rate Limits   │                │ • RTPEngine Media Relays     │
       └──────────────────────────────┘                └──────────────────────────────┘
                                      │
                                      ▼
       ┌─────────────────────────────────────────────────────────────┐
       │         AUTHENTICATION BYPASS & ROUTING DISPATCH            │
       │ (Trusted traffic skips SIP 401/407 digest challenges;       │
       │  Untrusted traffic strictly requires digest challenge)      │
       └─────────────────────────────────────────────────────────────┘
```

By maintaining pre-compiled in-memory hash tables of trusted peers, Kamailio evaluates incoming SIP packets in zero clock cycles, bypassing digest authentication challenges for authorized carrier trunks while strictly enforcing password authentication for remote endpoints.

---

## 2. Business & Operational Significance

* **Carrier IP-Based Authentication**: Enables seamless SIP trunking with Tier-1 wholesale telecom operators that rely on static IP peering rather than SIP registration or Digest (MD5/SHA) credentials.
* **Core PBX Cluster Interconnect**: Authorizes internal Ring2All Telephony cluster nodes and RTPEngine media proxies to dispatch calls through the SBC perimeter without authentication overhead.
* **Elimination of Auth Overhead on High CPS**: Eliminates the latency, packet round-trips, and CPU load of sending SIP `407 Proxy Authentication Required` messages on high-volume inbound wholesale DID trunks.
* **Zero-Downtime Cache Reloading**: Changes committed in the web interface automatically trigger Kamailio `permissions.addressReload` and `permissions.trustedReload` via RPC, updating routing permissions instantaneously without restarting SIP daemons.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Primary Use Case | Key Capabilities |
| :--- | :--- | :--- |
| **SBC Telephony Engineer** | Carrier Interconnect Provisioning | Register trusted carrier IP addresses, allocate address groups, specify port and transport protocols, and assign routing tags. |
| **Core PBX Administrator** | Cluster Node Authorization | Add newly provisioned Telephony nodes and media relays to the Trusted IPs table to ensure unimpeded internal signaling. |
| **NOC Systems Operator** | Peering Verification | Inspect active ACL groups, verify subnet mask lengths, and trigger on-demand permissions reloads. |
| **Security Auditor** | Trust Relationship Review | Review all authorized IP addresses to ensure no stale, unauthorized, or overly permissive subnets bypass SIP authentication. |
| **AI Peering & ACL Engineer / NOC Copilot** | Automated Trunk Whitelisting & Cache Verification | Query trusted peer records, add or remove authorized gateway IPs, and trigger atomic in-memory permissions cache reloads via MCP. |

---

## 4. Visual Interface & Layout

The ACL console provides an organized dual-section view featuring **Trusted IPs** at the top and **Address Groups** at the bottom, complete with instant creation dialogues and deletion protection for core loopback addresses.

### 4.1 ACL & Trusted Peers View
Displays authorized trusted peer IPs (e.g., Telephony nodes, RTPEngine media engines) and group-based subnet address definitions.

![Access Control List (ACL) View](/screenshots/sbc/admin/acl/acl-list.png)

---

## 5. Field Reference: Trusted IPs & Address Groups

### 5.1 Trusted IPs (`kamailio.trusted`) Parameters

| Field | Type | Constraint | Description |
| :--- | :--- | :--- | :--- |
| **IP Address** | String (IPv4/IPv6) | Required | The static IP address or CIDR subnet of the trusted telecom partner, PBX node, or carrier gateway. |
| **Protocol** | Dropdown | `any`, `udp`, `tcp`, `tls` | Transport protocol constraint. Selecting `any` authorizes signaling across all transport types. |
| **Label** | String | Optional | Descriptive identification tag (e.g., `Core PBX Telephony Node 01`, `RTPEngine Media Node 02`). |
| **Actions** | Action Icon | Trash Can | Removes the peer from the trusted table and triggers an automatic cache reload. |

### 5.2 Address Groups (`kamailio.address`) Parameters

| Field | Type | Constraint | Description |
| :--- | :--- | :--- | :--- |
| **Group** | Dropdown / Int | Numeric Group ID | The functional routing classification group (e.g., `1 — Trusted SBC`, `8 — PBX Auth`, `9 — CPS Limits`). |
| **IP Address** | String (IPv4/IPv6) | Required | IP address or network boundary associated with the group. |
| **Mask** | Number (0–32) | Default `32` | Subnet bitmask (e.g., `32` for a single host, `24` for a `/24` subnet block). |
| **Port** | Number (0–65535) | Default `0` | Port constraint. A value of `0` matches all source ports. |
| **Label / Tag** | String | Optional | Custom telemetry metadata or functional configuration string (e.g., `name:VitalPBX Casa-ip,gwgroup:1`). |

---

## 6. Kamailio Permissions Module & Routing Logic

When incoming SIP requests enter Kamailio's main request route, they are evaluated against the permissions cache:

```
# kamailio.cfg snippet
route[REQINIT] {
    # 1. Evaluate Trusted Peers (IP Auth)
    if (allow_trusted()) {
        xlog("L_INFO", "ACL: Authorized trusted peer $si:$sp [$proto]\n");
        setflag(FLAG_TRUSTED_PEER);
        route(DISPATCH_INTERNAL);
        exit;
    }

    # 2. Evaluate Address Groups
    if (check_source_address("1")) {
        xlog("L_INFO", "ACL: Source $si matched Group 1 (Trusted SBC)\n");
        setflag(FLAG_SBC_INTERCONNECT);
    }
}
```

---

## 7. Address Group Numbering & Telephony Roles

Ring2All SBC adopts a standardized group numbering taxonomy across the `kamailio.address` table:

| Group ID | Functional Purpose | Operational Behavior |
| :---: | :--- | :--- |
| **1** | **Trusted SBC Interconnect** | High-priority inter-SBC cluster signaling and management links. |
| **8** | **PBX Auth Bypass (FLT_PBX)** | Certified Core PBX nodes authorized to originate calls without challenge. |
| **9** | **CPS Rate Limit Rules** | Carrier endpoints with custom Calls-Per-Second rate exception thresholds (`tag: cps:50`). |
| **10** | **Emergency Dispatch** | Public Safety Answering Point (PSAP) and E911 high-priority trunks. |

---

## 8. Operational Hardening & Best Practices

* **Always Specify Subnet Masks Explicitly**: Use `/32` for individual server nodes rather than accepting broad defaults, preventing entire cloud hosting provider subnets from gaining trusted status.
* **Protect Loopback Addresses**: Ring2All SBC automatically blocks deletion of `127.0.0.1`, `::1`, or `localhost` from permissions tables to prevent breaking internal RPC communication.
* **Avoid Tag Clashes in Group 9**: When configuring CPS rate exceptions in Group 9, always format the tag as `cps:<number>` (e.g., `cps:50`) so the Pike rate limiting parser can extract the integer value accurately.
* **Verify Cache Reloads**: Ensure that every insertion or modification is followed by a successful `permissions.addressReload` to prevent drift between PostgreSQL and Kamailio memory.

---

## 9. Verification & Diagnostics

### 9.1 Query Active Permissions in Database
Inspect all entries in both tables:
```bash
# Query Trusted Peers
sudo -u postgres psql -d kamailio -c "SELECT id, src_ip, proto, pattern, tag FROM trusted;"

# Query Address Groups
sudo -u postgres psql -d kamailio -c "SELECT id, grp, ip_addr, mask, port, tag FROM address ORDER BY grp;"
```

### 9.2 Trigger In-Memory Cache Reload via RPC
Manually refresh Kamailio's in-memory permissions tables:
```bash
kamcmd permissions.addressReload
kamcmd permissions.trustedReload
```

### 9.3 Dump In-Memory Permissions Cache
Inspect the live routing tables in Kamailio memory:
```bash
kamcmd permissions.addressDump
kamcmd permissions.trustedDump
```

---

## 10. Model Context Protocol (MCP) AI Integration

The **Ring2All SBC MCP Server** exposes dedicated carrier peering and whitelist management tools under the `acl` category. Autonomous telephony agents and the Ring2All SBC NOC Copilot can audit trusted partner lists, provision new carrier IP endpoints, and trigger immediate Kamailio memory reloads.

### 10.1 Available MCP Tools

| Tool Name | Operation Type | Risk Level | Description |
| :--- | :--- | :--- | :--- |
| `list_trusted_ips` | Read-only | `read_only` | Lists all trusted IP subnets, PBX core nodes, and carrier whitelist entries with transport protocols and labels. |
| `add_trusted_ip` | Mutating / Operational | `critical` | Adds a new trusted IP or subnet to the Kamailio ACL permissions table, bypassing digest challenges and flood filtering. |
| `remove_trusted_ip` | Mutating / Operational | `critical` | Removes a trusted IP address from Kamailio permissions (protected against deleting loopback or management addresses). |
| `reload_acl_permissions` | Operational / Sync | `operational` | Triggers Kamailio RPC commands (`permissions.addressReload`, `permissions.trustedReload`) to synchronize memory with PostgreSQL. |

### 10.2 Tool Schemas & Parameter Definitions

#### `list_trusted_ips`
* **Description**: List all trusted IP subnets and carrier whitelist entries configured in Kamailio ACL permissions.
* **Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "search": {
      "type": "string",
      "description": "Filter by IP address or tag/description"
    }
  }
}
```

#### `add_trusted_ip`
* **Description**: Add a new trusted IP address or subnet to Kamailio ACL permissions.
* **Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "ipAddress": {
      "type": "string",
      "description": "IPv4 address or subnet (e.g., '198.51.100.50')"
    },
    "proto": {
      "type": "string",
      "enum": ["any", "udp", "tcp", "tls"],
      "description": "Transport protocol (default: any)"
    },
    "tag": {
      "type": "string",
      "description": "Descriptive label (e.g., 'Telnyx Carrier Gateway 01')"
    }
  },
  "required": ["ipAddress"]
}
```

#### `remove_trusted_ip`
* **Description**: Remove a trusted IP address from Kamailio ACL permissions.
* **Input Schema**:
```json
{
  "type": "object",
  "properties": {
    "ipAddress": {
      "type": "string",
      "description": "IP address to remove from trusted permissions"
    }
  },
  "required": ["ipAddress"]
}
```

#### `reload_acl_permissions`
* **Description**: Reload Kamailio ACL permissions and address tables from database into RAM memory.
* **Input Schema**:
```json
{
  "type": "object",
  "properties": {}
}
```

### 10.3 Sample Tool Execution Payloads

#### Example 1: Listing Trusted Carrier Gateways
**Request Payload:**
```json
{
  "tool": "list_trusted_ips",
  "parameters": {
    "search": "Telnyx"
  }
}
```

**Response Payload:**
```json
{
  "success": true,
  "data": {
    "total": 2,
    "trustedIps": [
      {
        "id": 12,
        "srcIp": "192.76.120.10",
        "proto": "any",
        "tag": "Telnyx Primary Interconnect"
      },
      {
        "id": 13,
        "srcIp": "192.76.120.11",
        "proto": "any",
        "tag": "Telnyx Secondary Interconnect"
      }
    ]
  }
}
```

#### Example 2: Authorizing a New PBX Media Relay Node
**Request Payload:**
```json
{
  "tool": "add_trusted_ip",
  "parameters": {
    "ipAddress": "198.51.100.50",
    "proto": "udp",
    "tag": "Telephony Core Node 03"
  }
}
```

**Response Payload:**
```json
{
  "success": true,
  "data": {
    "message": "Trusted IP 198.51.100.50 added successfully",
    "ipAddress": "198.51.100.50",
    "proto": "udp",
    "tag": "Telephony Core Node 03",
    "reloaded": true
  }
}
```

### 10.4 Bilingual Natural Language Copilot Prompts

#### English Prompts
* *"List all trusted carrier IP addresses configured in Kamailio ACL."*
  → Agent calls `list_trusted_ips()`.
* *"Add 198.51.100.50 as a trusted carrier gateway with tag 'Telnyx Wholesale'."*
  → Agent calls `add_trusted_ip({"ipAddress": "198.51.100.50", "proto": "udp", "tag": "Telnyx Wholesale"})`.
* *"Reload Kamailio permissions tables from the database to ensure all worker threads are synchronized."*
  → Agent calls `reload_acl_permissions()`.

#### Spanish Prompts (Español)
* *"Lista todas las direcciones IP de confianza configuradas en las ACL de Kamailio."*
  → Agente invoca `list_trusted_ips()`.
* *"Agrega la IP 198.51.100.50 como gateway de confianza con la etiqueta 'Telnyx Wholesale'."*
  → Agente invoca `add_trusted_ip({"ipAddress": "198.51.100.50", "proto": "udp", "tag": "Telnyx Wholesale"})`.
* *"Recarga las tablas de permisos de Kamailio desde la base de datos para sincronizar la memoria RAM."*
  → Agente invoca `reload_acl_permissions()`.

### 10.5 Enterprise Security & Execution Safeguards

1. **Loopback & Local Interface Protection**: The `remove_trusted_ip` tool executes strict guard validation via `assertCanRemoveTrustedIp()`. Any attempt to remove `127.0.0.1`, `::1`, or the host's primary internal IP is blocked unconditionally with an error.
2. **Automatic In-Memory Refresh**: Successful insertions and deletions automatically issue RPC reload commands (`permissions.addressReload`) within 3000ms timeouts to prevent memory-database divergence.
3. **Audit Trail Accountability**: All ACL modifications register the executing operator identity and a cryptographic change hash in the administrative audit journal.

---

## 11. Glossary

* **allow_trusted()**: Native Kamailio function that checks whether the incoming SIP message source matches an authorized entry in the `trusted` table.
* **check_source_address()**: Kamailio function that verifies whether an IP/port/protocol tuple matches a specific numeric group in the `address` table.
* **FLT_PBX**: Internal transaction flag set when an incoming request originates from an authorized Core PBX node.
* **Digest Authentication**: Challenge-response mechanism (RFC 2617 / RFC 8760) used to authenticate SIP endpoints using MD5, SHA-256, or SHA-512 hashes.
* **Model Context Protocol (MCP)**: An open standard enabling autonomous AI assistants and NOC copilots to securely discover and invoke SBC operational tools.