--- title: "Carriers & Wholesale Gateway Pools" description: "Documentation for Carriers & Groups" --- ## Table of Contents 1. [Overview & Architecture](#1-overview--architecture) 2. [Business & Operational Significance](#2-business--operational-significance) 3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities) 4. [Visual Interface & Form Layout](#4-visual-interface--form-layout) 5. [Field & Configuration Reference](#5-field--configuration-reference) 6. [Kamailio Dynamic Routing (drouting) Mechanics](#6-kamailio-dynamic-routing-drouting-mechanics) 7. [Digit Manipulation: Strip & Prefix Operations](#7-digit-manipulation-strip--prefix-operations) 8. [Security Best Practices & Operational Hardening](#8-security-best-practices--operational-hardening) 9. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration) 10. [Troubleshooting & Verification](#9-troubleshooting--verification) 11. [Glossary](#10-glossary) --- ## 1. Overview & Architecture In **Ring2All SBC**, the **Carriers & Trunks** module (`public.dr_gateways` and `public.dr_gw_lists`) manages wholesale telecommunications provider connections, SIP trunking peering partners, and PSTN termination gateways. Operating at Class 4 telecom volume, Ring2All SBC decouples physical carrier endpoints from outbound routing logic by organizing individual carrier gateways into logical **Carrier Groups (Gateway Lists)**. Outbound dialplans in Kamailio target these gateway pools, allowing real-time round-robin distribution, proportional weighting, and automated failover if an upstream telecom operator suffers route exhaustion or network failure. ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Outbound Dialplan Call Setup β”‚ β”‚ Kamailio drouting Core β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ Select Gateway List (gwlist: 10) β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β–Ό β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Carrier Gateway 1 (Primary) β”‚ β”‚ Carrier Gateway 2 (Backup) β”‚ β”‚ β€’ Provider: Bandwidth / T-1 β”‚ β”‚ β€’ Provider: Telnyx Global β”‚ β”‚ β€’ IP: 203.0.113.10:5060 β”‚ β”‚ β€’ IP: 198.51.100.25:5060 β”‚ β”‚ β€’ Strip: 0 | Prefix: 1 β”‚ β”‚ β€’ Strip: 0 | Prefix: 1 β”‚ β”‚ β€’ Auth: IP Peering (ACL) β”‚ β”‚ β€’ Auth: Digest Registration β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚ Attempt 1: INVITE sip:18005550199@203.0.113.10 β”‚ Attempt 2 (On 503/408): β”‚ β”‚ INVITE sip:18005550199@198.51.100.25 β–Ό β–Ό PSTN Telephony Network PSTN Telephony Network ``` --- ## 2. Business & Operational Significance * **Wholesale Carrier Aggregation**: Consolidates multiple tier-1 telco providers (e.g., Telnyx, Bandwidth, Inteliquent, BICS, Tata Communications) into a unified session border perimeter. * **Cost Optimization & LCR Foundation**: Provides the underlying carrier topology utilized by Least Cost Routing (LCR) algorithms to direct traffic through the most economically advantageous carrier. * **Instant Circuit Failover**: Protects mission-critical enterprise voice services with sub-second failover. If an upstream carrier responds with `503 Service Unavailable`, `408 Request Timeout`, or `500 Server Internal Error`, Kamailio immediately re-dispatches the call to the next gateway in the pool. * **Standardized Dialed Number Formatting**: Normalizes national, localized, and international telephone numbers across disparate carrier signaling standards using automated digit stripping and prefix insertion. --- ## 3. 🎯 User Roles & Key Capabilities | Role | Primary Use Case | Key Capabilities | | :--- | :--- | :--- | | **SBC Administrator** | Carrier Interconnect Provisioning | Define carrier groups; provision individual wholesale gateways; assign IP authentication or SIP digest credentials; configure failover orders. | | **Telecom Billing / LCR Analyst** | Routing Cost Management | Map carrier gateway IDs to billing rate cards; configure tech prefixes for premium or CLI-certified routes; inspect carrier ASR. | | **NOC Engineer** | Circuit Health & Diagnostic Tracing | Monitor gateway reachability; inspect SIP OPTIONS responses; enable/disable specific carrier IPs during scheduled vendor maintenance. | | **AI Platform Copilot / NOC Diagnostic Agent** | Automated Trunk Health & Routing Audit | Execute `list_carriers`, `get_carrier_status`, `create_carrier`, `delete_carrier`, and `reload_drouting_rules` to audit carrier gateway metrics, provision trunks, and trigger drouting in-memory reloads. | --- ## 4. Visual Interface & Form Layout ### Carrier Groups List View The list view provides a comprehensive inventory of all carrier groups, displaying assigned member gateway counts, load-balancing status, and operational health. ![Carriers & Carrier Groups List](/screenshots/sbc/routing/carriers/carriers-list.png) ### Carrier Group Configuration Form The group form allows operators to define gateway lists, enable load balancing, and attach multiple upstream carrier nodes with drag-and-drop prioritization. ![Carrier Group Form](/screenshots/sbc/routing/carriers/carrier-groups-form.png) ### Individual Carrier Gateway Configuration The carrier gateway form allows fine-grained configuration of signaling IP addresses, authentication credentials, and digit manipulation rules. ![Individual Carrier Gateway Form](/screenshots/sbc/routing/carriers/carrier-form.png) --- ## 5. Field & Configuration Reference ### Section 1: Carrier Group (Gateway List) Configuration | Field | Type | Options / Constraints | Description | | :--- | :--- | :--- | :--- | | **Group Name \*** | Text | Max 64 characters | Human-readable identifier for the carrier pool (e.g., `US Domestic Tier-1`, `LATAM Direct`). | | **Load Balancing \*** | Toggle | Boolean (`Yes` / `No`) | When enabled, traffic distributes across member gateways proportionally. When disabled, strict serial failover applies. | | **Member Gateways** | Dual-List / DnD | Active Gateways | Ordered list of member gateways comprising this routing pool. | ### Section 2: Individual Carrier Gateway Configuration | Field | Type | Format / Range | Description | | :--- | :--- | :--- | :--- | | **Gateway Name \*** | Text | Max 64 characters | Carrier brand or peering identifier (e.g., `Telnyx Primary ORD`, `Bandwidth US-East`). | | **SIP Address / Host \*** | Text | `sip:host[:port]` or IP | Remote carrier signaling address. Supports IPv4, IPv6, or FQDN (e.g., `sip:sip.telnyx.com:5060`). | | **Strip Digits** | Number | `0` to `10` (Default `0`) | Number of leading digits to strip from the dialed number before constructing the outbound Request-URI. | | **Prefix String** | Text | Numeric or Tech Prefix | Digits or routing prefixes prepended to the dialed number (e.g., `1`, `011`, `999#`). | | **Authentication Type** | Dropdown | `IP (ACL)`, `User/Password` | `IP` relies on trusted source IP peering. `User/Password` performs outbound SIP digest authentication. | | **Auth Username** | Text | Alphanumeric | Outbound SIP digest username provided by the wholesale carrier (if authentication type is `User/Password`). | | **Auth Password** | Password | Secure string | Cryptographic shared secret for SIP digest challenges. | | **Channel Capacity** | Number | `0` to `50,000` (0 = unmetered) | Maximum simultaneous active call channels contracted with the upstream provider. | --- ## 6. Kamailio Dynamic Routing (drouting) Mechanics When routing outbound telephone calls, Kamailio executes the `drouting` engine against database tables cached in shared memory (`shm`): 1. **Table Relationships**: - `dr_gateways`: Stores individual carrier SIP endpoints (`gwid`, `type=0`, `address`, `strip`, `pri_prefix`). - `dr_gw_lists`: Maps grouped gateways into ordered sequences (`gwlist: "1,2,3"` or balanced `"1=50,2=50"`). - `dr_rules`: Dialed number pattern matching rules that point to specific `dr_gw_lists`. 2. **In-Flight Failover Execution (`route[CARRIER_FAILOVER]`)**: ```kamailio # Initial route attempt if (!use_next_gw()) { t_reply("503", "All Gateways in Carrier Group Exhausted"); exit; } t_on_failure("GW_FAILURE"); t_relay(); # Automatic failure event handler failure_route[GW_FAILURE] { if (t_check_status("(408)|(500)|(502)|(503)|(504)")) { xlog("L_WARN", "Gateway $rd failed with code $T_reply_code. Advancing to next carrier...\n"); if (use_next_gw()) { t_on_failure("GW_FAILURE"); t_relay(); exit; } } } ``` 3. **Database Reload**: Configuration changes are committed via `kamcmd drouting.reload`, instantly rebuilding carrier routing structures without session interruption. --- ## 7. Digit Manipulation: Strip & Prefix Operations Telecom carriers frequently mandate specific dialed number formats (E.164 without plus, US 10-digit, or tech prefix prepending). Ring2All SBC normalizes numbers at the gateway level: | Dialed Number from PBX | Gateway Strip | Gateway Prefix | Delivered to Carrier | Transformation Logic | | :--- | :---: | :---: | :--- | :--- | | `+12125550199` | `1` | `""` | `12125550199` | Strip leading `+` symbol for carriers requiring raw North American E.164. | | `9011442071234567` | `1` | `""` | `011442071234567` | Strip PBX outside line access code (`9`). | | `2125550199` | `0` | `1` | `12125550199` | Prepend `1` to 10-digit local dialed numbers for LD termination. | | `14155550123` | `0` | `777#` | `777#14155550123` | Prepend vendor tech prefix (`777#`) for specialized wholesale tariff routing. | --- ## 8. Security Best Practices & Operational Hardening * **Sanitize Digest Passwords**: When storing carrier digest credentials, ensure database connections utilize TLS encryption. * **Enforce Strict Channel Limits**: Always set the `Channel Capacity` field to match the contractual port limits of the carrier account to avoid vendor billing penalties or unexpected SIP 486 rejections. * **Dedicated Media IP Binding**: When peering over private MPLS or direct cross-connects, bind RTPEngine media sockets to the carrier-facing network interface to prevent cross-routing into internal corporate LANs. --- ## Model Context Protocol (MCP) AI Integration The **Carriers & Wholesale Gateway Pools** module integrates with the Ring2All SBC Model Context Protocol (MCP) server, enabling AI Copilots and NOC automation workflows to query wholesale carrier gateway pools, inspect live routing configurations, provision gateways, and reload Kamailio dynamic routing tables. ### MCP Tools Catalog | Tool Name | Type | Access | Description | | :--- | :--- | :--- | :--- | | `list_carriers` | Query | `carriers` / Read | List all SIP Carriers and Gateways configured in Kamailio drouting and SBC Admin. | | `get_carrier_status` | Query | `carriers` / Read | Get configuration and live routing details of a specific carrier gateway. | | `create_carrier` | Mutation | `carriers` / Write | Create a new SIP Carrier trunk and gateway in Kamailio Dynamic Routing (drouting). | | `delete_carrier` | Mutation | `carriers` / Delete | Delete a carrier gateway from Kamailio and reload drouting (protected by `assertCanDeleteCarrier`). | | `reload_drouting_rules` | Operational | `carriers` / Exec | Reload Dynamic Routing and Carrier LCR rules from database into Kamailio RAM memory across all cluster nodes. | ### Tool Schemas & Execution Responses #### `list_carriers` ```json { "name": "list_carriers", "description": "List all SIP Carriers and Gateways configured in Kamailio drouting and SBC Admin.", "parameters": { "type": "object", "properties": { "search": { "type": "string", "description": "Filter by carrier name or gateway IP." } } } } ``` **Realistic Execution Response:** ```json { "success": true, "data": { "total": 2, "carriers": [ { "id": "gw_telnyx_primary", "address": "198.51.100.25:5060", "strip": 0, "prefix": "1", "type": 0, "description": "Telnyx US Direct Termination", "attrs": "carrier_id=1;max_channels=200" }, { "id": "gw_bandwidth_backup", "address": "203.0.113.10:5060", "strip": 0, "prefix": "1", "type": 0, "description": "Bandwidth PSTN Standby", "attrs": "carrier_id=2;max_channels=150" } ] } } ``` #### `get_carrier_status` ```json { "name": "get_carrier_status", "description": "Get configuration and live routing details of a specific carrier gateway.", "parameters": { "type": "object", "properties": { "carrier": { "type": "string", "description": "Gateway ID, name, or IP address of the carrier." } }, "required": ["carrier"] } } ``` **Realistic Execution Response:** ```json { "success": true, "data": { "carrier": { "id": "gw_telnyx_primary", "address": "198.51.100.25:5060", "strip": 0, "prefix": "1", "type": 0, "description": "Telnyx US Direct Termination", "attrs": "carrier_id=1;max_channels=200" }, "liveRouting": { "rawStatus": "Gateway gw_telnyx_primary state: ACTIVE (200 OK, latency: 12ms)" } } } ``` #### `create_carrier` ```json { "name": "create_carrier", "description": "Create a new SIP Carrier trunk and gateway in Kamailio Dynamic Routing (drouting).", "parameters": { "type": "object", "properties": { "name": { "type": "string", "description": "Carrier name (e.g. \"Telnyx Primary\")." }, "address": { "type": "string", "description": "Carrier SIP IP address or FQDN with port." }, "stripDigits": { "type": "number", "description": "Leading digits to strip." }, "prefix": { "type": "string", "description": "Tech prefix to prepend." }, "description": { "type": "string", "description": "Operational notes." } }, "required": ["name", "address"] } } ``` **Realistic Execution Response:** ```json { "success": true, "data": { "message": "Carrier \"Tata Global Direct\" registered successfully with gateway ID \"gw_tata_global_direct\".", "gatewayId": "gw_tata_global_direct", "address": "192.0.2.80:5060", "droutingReloaded": true } } ``` #### `reload_drouting_rules` ```json { "name": "reload_drouting_rules", "description": "Reload Dynamic Routing and Carrier LCR rules from database into Kamailio RAM memory.", "parameters": { "type": "object", "properties": {} } } ``` **Realistic Execution Response:** ```json { "success": true, "data": { "message": "Kamailio drouting routing tables reloaded into shared memory.", "status": "synchronized" } } ``` ### Bilingual Natural Language Prompt Examples #### English Prompts - *"NOC Copilot, list all wholesale carriers configured in Kamailio drouting."* - *"Check the reachability and active latency of gateway 'gw_telnyx_primary'."* - *"Create a new carrier gateway 'Tata Global Direct' pointing to '192.0.2.80:5060' with tech prefix '101#'."* - *"Reload Kamailio dynamic routing rules to apply modified carrier priorities."* #### Spanish Prompts - *"Copilot NOC, lista todos los carriers mayoristas configurados en el drouting de Kamailio."* - *"Consulta la alcanzabilidad y latencia activa de la troncal 'gw_telnyx_primary'."* - *"Registra un nuevo carrier 'Tata Global Direct' apuntando a '192.0.2.80:5060' con prefijo tΓ©cnico '101#'."* - *"Recarga las reglas de enrutamiento dinΓ‘mico en Kamailio para aplicar los cambios de prioridad."* ### Enterprise Safeguards & Execution Boundaries 1. **Referential Integrity Guard (`assertCanDeleteCarrier`):** Carrier gateways cannot be deleted if referenced in active Kamailio dispatcher sets, LCR routing rules (`drouting_rules`), or quality monitoring policies. 2. **Instant In-Memory Synchronism:** Creating or deleting carrier gateways immediately invokes `drouting.reload` via Kamailio BinRPC, preventing stale SIP routing caches. 3. **Capacity Ceiling Alignment:** Carrier gateways enforce maximum concurrent calls via `attrs` parameter flags, preventing carrier port saturation penalties. --- ## 9. Troubleshooting & Verification | Symptom / Issue | Potential Root Cause | Recommended Verification & Resolution | | :--- | :--- | :--- | | **Outbound call fails with `503 All Gateways Exhausted`** | All member gateways in the group are unreachable or timed out. | Verify remote IP reachability using `ping` and `traceroute`. Check Kamailio gateway status with `kamcmd drouting.carrierStats`. | | **Carrier rejects with `401 Unauthorized` repeatedly** | Outbound digest auth username or password mismatch. | Verify credentials in the gateway configuration form and inspect the SIP Authorization header in **Reports > SIP Traces**. | | **Carrier returns `404 Not Found` or `Invalid Number Format`** | Incorrect `strip` or `prefix` digit manipulation settings. | Inspect the delivered Request-URI in the SIP INVITE packet and adjust the strip/prefix parameters to match the carrier's specification. | --- ## 10. Glossary * **drouting (Dynamic Routing)**: High-performance routing module in Kamailio supporting prefix matching, gateway grouping, and priority-based failover. * **Gateway Pool (dr_gw_lists)**: An ordered set of SIP proxies evaluated sequentially or proportionally to route an outbound telephone call. * **E.164**: The international public telecommunication numbering plan that standardizes the format of telephone numbers globally. * **Tech Prefix**: A short dialing string (e.g., `888#`) prepended to telephone numbers to instruct wholesale carriers which routing product to invoke.