Carriers & Wholesale Gateway Pools

Overview & Architecture
Business & Operational Significance
🎯 User Roles & Key Capabilities
Visual Interface & Form Layout
Field & Configuration Reference
Kamailio Dynamic Routing (drouting) Mechanics
Digit Manipulation: Strip & Prefix Operations
Security Best Practices & Operational Hardening
Model Context Protocol (MCP) AI Integration
Troubleshooting & Verification
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

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

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

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):

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.

In-Flight Failover Execution (route[CARRIER_FAILOVER]):

# 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;
        }
    }
}

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`

{
  "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:

{
  "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`

{
  "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:

{
  "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`

{
  "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:

{
  "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`

{
  "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:

{
  "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

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.
Instant In-Memory Synchronism: Creating or deleting carrier gateways immediately invokes drouting.reload via Kamailio BinRPC, preventing stale SIP routing caches.
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.

Carriers & Wholesale Gateway Pools

Table of Contents

1. Overview & Architecture

2. Business & Operational Significance

3. 🎯 User Roles & Key Capabilities

4. Visual Interface & Form Layout

Carrier Groups List View

Carrier Group Configuration Form

Individual Carrier Gateway Configuration

5. Field & Configuration Reference

Section 1: Carrier Group (Gateway List) Configuration

Section 2: Individual Carrier Gateway Configuration

6. Kamailio Dynamic Routing (drouting) Mechanics

7. Digit Manipulation: Strip & Prefix Operations

8. Security Best Practices & Operational Hardening

Model Context Protocol (MCP) AI Integration

MCP Tools Catalog

Tool Schemas & Execution Responses

list_carriers

get_carrier_status

create_carrier

reload_drouting_rules

Bilingual Natural Language Prompt Examples

English Prompts

Spanish Prompts

Enterprise Safeguards & Execution Boundaries

9. Troubleshooting & Verification

10. Glossary

`list_carriers`

`get_carrier_status`

`create_carrier`

`reload_drouting_rules`