SIP Accounts & Wholesale Trunks

Table of Contents

1. Overview & Architecture
2. Business & Operational Significance
3. 🎯 User Roles & Key Capabilities
4. Visual Interface & Form Layout
5. Field & Configuration Reference
6. Kamailio Authentication Pipeline & Security Engine
7. Security Best Practices & Operational Hardening
8. Model Context Protocol (MCP) AI Integration
9. Troubleshooting & Verification
10. Glossary

---

1. Overview & Architecture

In Ring2All SBC, the SIP Accounts module (public.sip_accounts) represents incoming and bidirectional wholesale carrier trunks, enterprise customer SIP peers, and authenticated SIP clients terminating onto the carrier perimeter.

Each SIP Account acts as a boundary gateway profile that authenticates inbound SIP requests, enforces real-time rate limits (Calls Per Second and Concurrent Channels), maps source traffic to specific SIP Domains, binds default Outbound Routes, and manages encrypted media policies (SRTP).

 ┌────────────────────────────────────────────────────────────────────────┐
 │                      Incoming SIP Request (INVITE)                     │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
                    Source IP & Port / Digest Auth Header
                                     │
 ┌───────────────────────────────────▼────────────────────────────────────┐
 │  Kamailio Authentication Pipeline (Route AUTH)                         │
 │                                                                        │
 │  ┌───────────────────────────────┐   ┌──────────────────────────────┐  │
 │  │   IP Whitelist (Address GRP)  │   │  Digest Auth (Subscriber DB) │  │
 │  │   • Subnet CIDR / IPv4 / IPv6 │   │  • HA1 MD5 (user:domain:pwd) │  │
 │  │   • Tag: sip_account:<id>     │   │  • HA1B (user@domain:pwd)    │  │
 │  └───────────────┬───────────────┘   └──────────────┬───────────────┘  │
 │                  │                                  │                  │
 │                  └─────────────────┬────────────────┘                  │
 │                                    │ Account Matched & Authorized      │
 │  ┌─────────────────────────────────▼────────────────────────────────┐  │
 │  │  Traffic Shaping & Limit Enforcement (htable & dialog)           │  │
 │  │  • Max Concurrent Channels (atomic counter increment)            │  │
 │  │  • Calls Per Second (CPS sliding window check)                   │  │
 │  │  • Reject if exceeded (SIP 503 Channel / Rate Limit Exceeded)    │  │
 │  └─────────────────────────────────┬────────────────────────────────┘  │
 └────────────────────────────────────┼───────────────────────────────────┘
                                      │
                     Routing & Media Anchor (RTPEngine)
                                      ▼
                        Outbound Route / Ring2All PBX

When an external customer PBX or wholesale carrier sends a SIP INVITE, the SBC determines account identity using one of three authentication strategies:

1. IP-Based Authentication: The source IP address is matched against an access control list (CIDR / subnet) managed in Kamailio’s permissions table.
2. Digest Authentication: Kamailio challenges the client with a 401 Unauthorized / 407 Proxy Authentication Required challenge using pre-shared username and password credentials stored in the subscriber table.
3. Both (Dual Authentication): Requires both a recognized source IP address and valid Digest credentials, offering high security for multi-tenant wholesale trunking.

---

2. Business & Operational Significance

• Wholesale Carrier Interconnect: Enables enterprise voice providers, contact centers, and multi-tenant resellers to peer directly with Ring2All SBC without registering individual handsets.
• Granular SLA & Capacity Protection: Prevents noisy neighbor denial-of-service conditions by strictly enforcing atomic channel caps and CPS ceilings per tenant.
• Automated DID Association: Inbound phone numbers can be assigned directly to specific SIP accounts, ensuring clean tenant isolation and inbound delivery.
• Flexible Topology Traversal: Supports direct URI destination relay, native dispatching into Ring2All PBX clusters, or peering out to external Class 4 carriers.
• Secure Media Enforcement: Allows per-account SRTP policies (none, preferred, required) to guarantee media encryption compliance for enterprise clients.

---

3. 🎯 User Roles & Key Capabilities

Role	Primary Use Case	Key Capabilities
SBC Administrator	Carrier & Account Provisioning	Create, edit, and suspend SIP Accounts; configure IP whitelists, Digest credentials, concurrent channel quotas, CPS limits, and SRTP policies.
Carrier NOC Engineer	Peering Diagnostics & Tracing	Inspect live active channel counts, investigate rejected calls due to authentication failure or limit breach, and view associated DIDs.
Compliance Auditor	Security & Traffic Auditing	Verify cryptographic media requirements (SRTP enforcement), IP whitelist CIDR boundaries, and billing account associations.
AI Platform Copilot / NOC Diagnostic Agent	Trunk Telemetry & Provisioning	Execute list_sip_accounts, get_sip_account_status, create_sip_account, and delete_sip_account to audit wholesale trunks, verify IP/Digest auth modes, and enforce channel capacity limits.

---

4. Visual Interface & Form Layout

SIP Accounts List View

The list view displays all configured SIP accounts with their authentication type, allowed IPs, channel limits, CPS rate, outbound route association, and operational status.

SIP Account Configuration Form

The configuration form features a clean two-box layout under the Account tab, with an optional DIDs tab available in edit mode to inspect assigned telephone numbers.

---

5. Field & Configuration Reference

Box 1: General Information & Authentication

Field	Type	Constraints / Format	Description
Account Name *	Text	3–64 characters	Unique human-readable label identifying the customer, PBX, or carrier trunk.
Description	Text	Max 255 characters	Optional operational notes, client identifier, or service contract reference.
Authentication Type *	Dropdown	credentials, ip, both	Method used to validate inbound traffic from this account.
Username	Text	Alphanumeric (if credentials/both)	SIP username presented in Digest authorization headers.
Password	Password	Min 8 characters (if credentials/both)	SIP password used to generate HA1/HA1B MD5 authentication hashes.
Outbound Route	Dropdown	Configured Outbound Routes	The default outbound routing profile used when calls originate from this account.
Allowed IPs	Multiline Text	Valid IPv4/IPv6 or CIDR (one per line)	List of authorized IP subnets (e.g. 203.0.113.0/24, 198.51.100.5). Active when ip or both is selected.
Status *	Dropdown	active, suspended, disabled	Administrative state. Suspended accounts are immediately rejected with SIP 403 Forbidden.

Box 2: Routing & Capacity Limits

Field	Type	Constraints / Format	Description
SIP Domain	Searchable Select	Active SIP Domains	Binds this account to a multi-tenant SIP Domain namespace for Request-URI routing.
Max Concurrent Channels *	Number	Integer $\ge 0$ (0 = unlimited)	Maximum simultaneous active bidirectional calls permitted before returning SIP 503.
Max Calls Per Second (CPS) *	Number	Integer $\ge 0$ (0 = unlimited)	Burst signaling rate limit enforced via Kamailio sliding window algorithms.
Caller ID Override	Text	E.164 or numeric string	Forcefully sets the outbound Calling Line Identification (CLI) for calls passing through this account.

Advanced Routing Settings (Collapsible)

Field	Type	Constraints / Format	Description
Forward Destination	Text	SIP URI (e.g., sip:pbx.customer.com:5060)	Custom downstream SIP destination to relay inbound calls received on this account.
Tech Prefix	Text	Numeric string (e.g., 9901*)	Dialed digits prefix prepended to outbound traffic or stripped from incoming calls.
SRTP Policy	Dropdown	none, preferred, required	Media encryption requirement (none = plain RTP, preferred = offer SAVP, required = enforce SAVP).

---

6. Kamailio Authentication Pipeline & Security Engine

Database Schema & Synchronization

SIP Accounts synchronize between the PostgreSQL ss_telephony database and Kamailio memory tables:

-- Core SIP Account definition in PostgreSQL
CREATE TABLE public.sip_accounts (
    id SERIAL PRIMARY KEY,
    name VARCHAR(64) NOT NULL UNIQUE,
    description VARCHAR(255),
    auth_type VARCHAR(20) NOT NULL DEFAULT 'credentials', -- credentials, ip, both
    username VARCHAR(64),
    password_hash VARCHAR(128),
    allowed_ips TEXT, -- Comma-separated or newline CIDR list
    max_channels INT NOT NULL DEFAULT 10,
    cps INT NOT NULL DEFAULT 2,
    tech_prefix VARCHAR(32),
    caller_id_override VARCHAR(64),
    destination VARCHAR(255),
    sip_domain VARCHAR(255),
    outbound_route_id INT REFERENCES public.outbound_routes(id) ON DELETE SET NULL,
    srtp_policy VARCHAR(20) NOT NULL DEFAULT 'none',
    status VARCHAR(20) NOT NULL DEFAULT 'active',
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Kamailio Routing Script Mechanics

1. IP Authentication (permissions module):

   route[AUTH_IP] {
       # Check if source IP is within allowed subnet
       if (allow_source_address("10")) {
           $var(sip_account_id) = $sht(ip_to_account=>$si);
           return(1);
       }
       return(-1);
   }

2. Digest Authentication (auth_db module):

   route[AUTH_DIGEST] {
       if (!auth_check("$fd", "subscriber", "1")) {
           auth_challenge("$fd", "0");
           exit;
       }
       consume_credentials();
       return(1);
   }

3. Capacity & CPS Throttling (htable & dialog):

   route[CHECK_LIMITS] {
       $var(cur_calls) = $sht(account_calls=>$var(sip_account_id));
       if ($var(cur_calls) >= $var(max_channels)) {
           sl_send_reply("503", "Maximum Concurrent Channels Exceeded");
           exit;
       }
       # Atomic CPS sliding window increment
       if (!sht_rm_name_re("cps_.*")) {
           # rate limit logic
       }
   }

---

7. Security Best Practices & Operational Hardening

• Enforce Complex Digest Secrets: If using credentials or both, use generated passwords of 24+ alphanumeric characters to prevent brute-force SIP scanning.
• Combine IP Whitelisting with Credentials (both): For mission-critical trunks, require dual verification so compromised credentials cannot be used from unauthorized IPs.
• Strict CPS Limits on New Accounts: Start new accounts with conservative CPS limits (2–5 CPS) to contain automated dialing storms or compromised PBX loops.
• Mandate SRTP for Remote Cloud Connections: For trunks operating over the public Internet, set SRTP Policy to required and ensure signaling uses TLS on port 5061.

---

Model Context Protocol (MCP) AI Integration

The SIP Accounts & Wholesale Trunks module integrates with the Ring2All SBC Model Context Protocol (MCP) server, allowing AI Copilots, automated onboarding workflows, and NOC diagnostics to inspect wholesale trunk profiles, verify Digest authentication credentials, configure IP access control lists, and monitor capacity quotas.

MCP Tools Catalog

Tool Name	Type	Access	Description
list_sip_accounts	Query	sip_accounts / Read	List all Class 4 Customer SIP Accounts and Trunks registered in Ring2All SBC (username, auth method: IP/credentials, concurrent call limits, and status).
get_sip_account_status	Query	sip_accounts / Read	Get detailed configuration, authentication mode, IP whitelists, and limits of a specific SIP account.
create_sip_account	Mutation	sip_accounts / Write	Create a new Class 4 Customer SIP Account with Digest Authentication (HA1) and optional IP ACL authorization.
delete_sip_account	Mutation	sip_accounts / Delete	Delete a customer SIP account and trunk profile from the SBC.

Tool Schemas & Execution Responses

list_sip_accounts

{
  "name": "list_sip_accounts",
  "description": "List all Class 4 Customer SIP Accounts and Trunks registered in Ring2All SBC (username, auth method: IP/credentials, concurrent call limits, and status).",
  "parameters": {
    "type": "object",
    "properties": {
      "search": {
        "type": "string",
        "description": "Filter by username or name."
      },
      "status": {
        "type": "string",
        "enum": ["active", "suspended", "disabled"],
        "description": "Filter by status."
      }
    }
  }
}

Realistic Execution Response:

{
  "success": true,
  "data": {
    "total": 2,
    "accounts": [
      {
        "id": 101,
        "username": "trunk_apex_voice",
        "name": "Apex Enterprise Trunk",
        "authType": "both",
        "allowedIps": "203.0.113.10,203.0.113.11",
        "maxChannels": 100,
        "cps": 25,
        "status": "active",
        "createdAt": "2026-09-05T11:20:00Z"
      },
      {
        "id": 102,
        "username": "cust_novatel_sip",
        "name": "NovaTel Reseller SIP",
        "authType": "credentials",
        "allowedIps": null,
        "maxChannels": 50,
        "cps": 10,
        "status": "active",
        "createdAt": "2026-09-06T15:10:00Z"
      }
    ]
  }
}

get_sip_account_status

{
  "name": "get_sip_account_status",
  "description": "Get detailed configuration, authentication mode, IP whitelists, and limits of a specific SIP account.",
  "parameters": {
    "type": "object",
    "properties": {
      "username": {
        "type": "string",
        "description": "SIP account username (e.g. \"trunk_cust_1001\")."
      }
    },
    "required": ["username"]
  }
}

Realistic Execution Response:

{
  "success": true,
  "data": {
    "account": {
      "id": 101,
      "username": "trunk_apex_voice",
      "name": "Apex Enterprise Trunk",
      "authType": "both",
      "allowedIps": "203.0.113.10,203.0.113.11",
      "maxChannels": 100,
      "cps": 25,
      "outboundRouteId": 5,
      "srtpPolicy": "required",
      "status": "active",
      "assignedDidsCount": 12,
      "updatedAt": "2026-09-08T08:00:00Z"
    }
  }
}

create_sip_account

{
  "name": "create_sip_account",
  "description": "Create a new Class 4 Customer SIP Account with Digest Authentication (HA1) and optional IP ACL authorization.",
  "parameters": {
    "type": "object",
    "properties": {
      "username": { "type": "string", "description": "SIP username." },
      "password": { "type": "string", "description": "SIP secret password." },
      "name": { "type": "string", "description": "Friendly name of the customer." },
      "authType": { "type": "string", "enum": ["credentials", "ip", "both"] },
      "ips": { "type": "string", "description": "Comma-separated IP addresses or subnets." },
      "maxChannels": { "type": "number", "description": "Maximum concurrent calls." }
    },
    "required": ["username", "password", "name"]
  }
}

Realistic Execution Response:

{
  "success": true,
  "data": {
    "message": "SIP Account \"cust_quantum_voice\" created successfully.",
    "accountId": 103,
    "username": "cust_quantum_voice",
    "authType": "both",
    "status": "active"
  }
}

Bilingual Natural Language Prompt Examples

English Prompts

• “NOC Copilot, list all active customer SIP Accounts and their concurrent channel limits.”
• “Show me the configuration and IP whitelist for account ‘trunk_apex_voice’.”
• “Create a new SIP trunk account ‘cust_quantum_voice’ with authType ‘both’ and allowed IP ‘198.51.100.40’.”
• “Verify if any customer SIP accounts are currently exceeding their configured CPS quota.”

Spanish Prompts

• “Copilot NOC, lista todas las cuentas SIP de clientes activas y sus límites de canales simultáneos.”
• “Muéstrame la configuración y lista blanca de IPs de la cuenta ‘trunk_apex_voice’.”
• “Crea una nueva cuenta de troncal SIP ‘cust_quantum_voice’ con autenticación ‘both’ e IP permitida ‘198.51.100.40’.”
• “Comprueba si alguna cuenta SIP de cliente está superando actualmente su cuota de CPS configurada.”

Enterprise Safeguards & Execution Boundaries

1. Cryptographic Credential Protection (HA1 MD5): Passwords are computed into HA1 hashes (username:realm:password) before storage in Kamailio subscriber tables, preventing plaintext exposure.
2. Atomic IP Address Permissions Synchronization: Updating IP whitelist addresses triggers permissions.addressReload via Kamailio RPC without disconnecting active calls.
3. Channel Overrun & CPS Protection: Real-time channel concurrency is tracked via Kamailio dialog profiles (dlg.profile_get_size sip_account), instantly returning SIP 503 Channel Limit Exceeded when thresholds are breached.

---

8. Troubleshooting & Verification

Inspect Account Configuration via PostgreSQL

# Verify SIP Account settings and authentication mode
psql -U softswitch -d ss_telephony -c "
SELECT id, name, auth_type, username, allowed_ips, max_channels, cps, status
FROM public.sip_accounts ORDER BY id DESC;"

Check In-Memory Subscriber Credentials

# Reload Kamailio subscriber authentication table
kamcmd auth_db.reload

# Verify IP permissions address table
kamcmd permissions.addressDump

Monitor Live Active Dialogs per Account

# Check active dialogs tracked by Kamailio
kamcmd dlg.profile_get_size sip_account

View Real-Time SIP Signaling Traces

# Filter live SIP traffic for a specific SIP Account IP
sngrep host 203.0.113.10

---

9. Glossary

• AS (Authentication Service): The perimeter gateway subsystem that validates incoming SIP user agents.
• Digest Authentication: Challenge-response protocol (RFC 2617 / RFC 3261) using MD5 or SHA-256 hashes to verify caller identity without transmitting plaintext passwords.
• IP Whitelist: Firewall/ACL rules matching source IPv4 or IPv6 addresses against allowed subnets.
• CPS (Calls Per Second): The signaling transaction rate representing new call setup attempts per second.
• SRTP (Secure Real-Time Transport Protocol): RFC 3711 encryption providing confidentiality and message authentication for audio and video media streams.