Outbound Routes & LCR

Overview & Architecture
Business & Operational Significance
🎯 User Roles & Key Capabilities
Visual Interface & Form Layout
Field & Configuration Reference
Kamailio Dynamic Routing (drouting) Engine & LCR Algorithms
Security Best Practices & Operational Hardening
Troubleshooting & Verification
Glossary

1. Overview & Architecture

In Ring2All SBC, the Outbound Routes module (public.outbound_routes, public.outbound_route_prefixes, and public.outbound_route_prefix_carriers) governs how calls originating from enterprise tenants, customer SIP Accounts, or Ring2All PBX clusters exit the perimeter toward wholesale PSTN carriers.

Built directly on Kamailio’s high-performance drouting (Dynamic Routing) engine, the module implements Least Cost Routing (LCR), dial pattern normalization (strip/prepend), and deterministic multi-tier carrier gateway failover.

                    ┌──────────────────────────────────────────┐
                    │      Inbound Outbound Call Request       │
                    │         INVITE sip:917865551234          │
                    └─────────────────────┬────────────────────┘
                                          │
                                          ▼
                    ┌──────────────────────────────────────────┐
                    │    Route Matching & Prefix Translation   │
                    │   • Pattern: ^91[2-9]..[2-9]......$      │
                    │   • Strip: 1 digit (remove '9')          │
                    │   • Prepend: '+' (format to E.164)       │
                    │   • Output Dialed: +17865551234          │
                    └─────────────────────┬────────────────────┘
                                          │
                                          ▼
                    ┌──────────────────────────────────────────┐
                    │     Kamailio drouting Gateway Selection  │
                    │          do_routing("$var(dr_group)")    │
                    └─────────────────────┬────────────────────┘
                                          │
                       Gateway Pool Ordered by Priority & Weight
                                          │
         ┌────────────────────────────────┼────────────────────────────────┐
         │ Priority 1 (Weight 70)         │ Priority 1 (Weight 30)         │ Priority 2 (Failover)
         ▼                                ▼                                ▼
┌──────────────────────┐        ┌──────────────────────┐        ┌──────────────────────┐
│  Primary Carrier A   │        │  Primary Carrier B   │        │  Backup Carrier C    │
│  • Low Tariffs       │        │  • Low Tariffs       │        │  • Premium Routing   │
│  • Normal Operation  │        │  • Normal Operation  │        │  • Used if 503 / 500 │
└──────────────────────┘        └──────────────────────┘        └──────────────────────┘

When an outbound call initiates:

Pattern Matching: The SBC tests the dialed digits against configured regular expressions or numerical prefixes.
Digit Transformation: Applies string manipulations (stripping tech prefixes, prepending international dialing codes).
Gateway Dispatch: Kamailio routes the call to the highest-priority carrier gateway.
Autonomous Failover: If the primary carrier returns a SIP error code (503 Service Unavailable, 500 Server Internal Error, or transaction timeout 408), Kamailio invokes use_next_gw() to immediately re-attempt the call over secondary carriers without call drops.

2. Business & Operational Significance

Least Cost Routing (LCR) Optimization: Dynamically selects the most cost-effective wholesale carrier for each destination country, area code, or rate center.
Carrier Redundancy & High Availability: Eliminates carrier-induced outages through zero-downtime, sub-second failover across alternative gateway providers.
Flexible Dialplan Manipulation: Normalizes diverse customer dialing habits (e.g. 7-digit local dialing, 10-digit national, or 11-digit prefixes) into standardized E.164 formats required by wholesale carriers.
Proportional Traffic Balancing: Distributes call volume among multiple wholesale providers using granular percentage-based weights to fulfill carrier volume commitments.

3. 🎯 User Roles & Key Capabilities

Role	Primary Use Case	Key Capabilities
SBC Administrator	Carrier Route Architecture	Create, reorder, and configure outbound routing policies; define dial patterns and digit translations; assign carrier gateway pools.
Carrier NOC Engineer	Telephony Troubleshooting	Monitor gateway selection logs, test regex pattern matching, and verify carrier failover sequences during peering maintenance.
Telecom Billing Analyst	Wholesale Margin Optimization	Adjust carrier priority order based on monthly rate sheet updates, LCR matrices, and minimum usage commitments.

4. Visual Interface & Form Layout

Outbound Routes List View

The list view displays all configured outbound routes, their operational status, assigned description, and quick management actions.

Outbound Routes List

Outbound Route Configuration Form

The route editor features a top-level Route Configuration card followed by two dedicated drag-and-drop tabs: Dial Patterns and Gateways & Failover.

Outbound Route Configuration Form

5. Field & Configuration Reference

Route Configuration Card

Field	Type	Constraints / Format	Description
Route Name *	Text	3–64 characters	Unique descriptive identifier (e.g., North America Standard, International LCR).
Description	Text	Max 255 characters	Free-form operational notes, carrier group scope, or client association.
Status *	Toggle	Active / Disabled	Administrative toggle. Inactive routes are ignored during dialplan matching.

Tab 1: Dial Patterns

This tab defines the destination patterns that trigger this outbound route. Multiple patterns can be evaluated in order using drag-and-drop priority.

Control / Column	Type	Constraints / Format	Description
Move (Grip)	Drag Handle	Drag-and-drop reordering	Reorders pattern evaluation sequence from top to bottom.
Pattern *	Text	Prefix or Regular Expression	Dialed digit filter (e.g., `^1[2-9]..[2-9]......$`, `^011[0-9]+$`, `+44*`).
Strip Digits	Number	Integer $\ge 0$	Number of leading characters to remove from the dialed string before forwarding.
Prepend Digits	Text	Numeric or `+` string	Characters to attach to the front of the dialed number after stripping (e.g., `+1`, `011`).
Enabled	Toggle	True / False	Toggles pattern activation without deleting the rule.
Add Pattern	Button	Action	Appends a new pattern row to the route definition.

Tab 2: Gateways & Failover

This tab defines the ordered sequence of carrier gateways used to terminate calls matching this route.

Control / Column	Type	Constraints / Format	Description
Move (Grip)	Drag Handle	Drag-and-drop reordering	Determines gateway dispatch precedence. Top gateways are attempted first.
Gateway *	Dropdown	Configured Carrier Gateways	Wholesale carrier endpoint selected from the Carriers catalog.
Weight	Number	0–100	Proportional load balancing weight among gateways sharing identical priority levels.
Enabled	Toggle	True / False	Enables or disables the carrier gateway in this route without deleting it.
Add Gateway	Button	Action	Adds an additional carrier gateway to the failover pool.

6. Kamailio Dynamic Routing (drouting) Engine & LCR Algorithms

Database Schema

Outbound Routes compile directly into Kamailio’s drouting data model:

-- Main route definition
CREATE TABLE public.outbound_routes (
    id SERIAL PRIMARY KEY,
    name VARCHAR(64) NOT NULL UNIQUE,
    description VARCHAR(255),
    status VARCHAR(20) NOT NULL DEFAULT 'active',
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Prefix and regex pattern rules (dr_rules)
CREATE TABLE public.outbound_route_prefixes (
    id SERIAL PRIMARY KEY,
    route_id INT NOT NULL REFERENCES public.outbound_routes(id) ON DELETE CASCADE,
    prefix VARCHAR(64) NOT NULL,
    strip_digits INT NOT NULL DEFAULT 0,
    prepend VARCHAR(32) DEFAULT '',
    priority INT NOT NULL DEFAULT 10,
    description VARCHAR(128)
);

-- Gateway and failover assignments (dr_gw_lists)
CREATE TABLE public.outbound_route_prefix_carriers (
    id SERIAL PRIMARY KEY,
    prefix_id INT NOT NULL REFERENCES public.outbound_route_prefixes(id) ON DELETE CASCADE,
    carrier_id INT NOT NULL REFERENCES public.carriers(id) ON DELETE CASCADE,
    priority INT NOT NULL DEFAULT 10,
    weight INT NOT NULL DEFAULT 0
);

Kamailio Routing Script Mechanics

route[OUTBOUND_LCR_ROUTING] {
    # 1. Execute dynamic routing lookup
    # Group '1' represents default outbound carrier routes
    if (!do_routing("1", "W")) {
        sl_send_reply("503", "No Outbound Route Available");
        exit;
    }

    # 2. Arm failure route for gateway failover
    t_on_failure("FAILOVER_GATEWAY");

    # 3. Relay call to selected gateway
    route(RELAY_TO_CARRIER);
}

failure_route[FAILOVER_GATEWAY] {
    # Failover on carrier signaling failure or timeout
    if (t_check_status("503|500|408|480")) {
        xlog("L_WARN", "Carrier $rd failed with code $T_reply_code, attempting next gateway\n");
        if (use_next_gw()) {
            t_on_failure("FAILOVER_GATEWAY");
            route(RELAY_TO_CARRIER);
            exit;
        }
    }
    # No further backup gateways available
    t_reply("503", "All Carrier Gateways Unavailable");
}

7. Security Best Practices & Operational Hardening

Prevent Toll Fraud & Looping: Include explicit digit length constraints in regular expressions (e.g. ^1[2-9]..[2-9]......$ rather than open-ended wildcards ^1.*$) to block international premium rate exploits.
Sanitize Prepend Values: Ensure prepend strings contain only valid telephony digits (0–9) or standard ITU prefixes (+) to prevent invalid SIP headers.
Carrier Failure Rate Limiting: Ensure failover triggers do not retry on client-caused errors (such as 404 Not Found, 486 Busy Here, or 487 Request Terminated) to prevent multiplying invalid traffic onto backup carriers.
Isolate Emergency Routing: Never route 911 / 112 emergency services through general LCR routes. Emergency services must utilize dedicated, non-failover local emergency trunks.

8. Troubleshooting & Verification

Inspect In-Memory Routing Rules via Kamailio CLI

# Reload dynamic routing tables from database
kamcmd drouting.reload

# Dump all active dynamic routing rules
kamcmd drouting.dump_rules

# Dump configured carrier gateways and availability status
kamcmd drouting.dump_gateways

Verify Route Matching for a Target Number

# Test how Kamailio matches a dialed number (+17865550199)
kamcmd drouting.dr_test_routing 1 "+17865550199"

Trace Live Carrier Failover Events

# Watch real-time Kamailio system logs for failover events
tail -f /var/log/syslog | grep -E "drouting|FAILOVER_GATEWAY"

9. Glossary

drouting (Dynamic Routing): Kamailio module providing high-speed database-driven routing with prefix matching, gateway blacklisting, and carrier failover.
LCR (Least Cost Routing): Telephony routing strategy that analyzes available carrier rate sheets to route calls via the least expensive path.
Strip / Prepend: Telephony dialplan transformation functions that remove leading characters or add prefixes to normalize dialed numbers.
use_next_gw(): Kamailio API function that switches the active SIP destination to the next available gateway in the failover list upon transaction failure.

Outbound Routes & LCR

Table of Contents

1. Overview & Architecture

2. Business & Operational Significance

3. 🎯 User Roles & Key Capabilities

4. Visual Interface & Form Layout

Outbound Routes List View

Outbound Route Configuration Form

5. Field & Configuration Reference

Route Configuration Card

Tab 1: Dial Patterns

Tab 2: Gateways & Failover

6. Kamailio Dynamic Routing (drouting) Engine & LCR Algorithms

Database Schema

Kamailio Routing Script Mechanics

7. Security Best Practices & Operational Hardening

8. Troubleshooting & Verification

Inspect In-Memory Routing Rules via Kamailio CLI

Verify Route Matching for a Target Number

Trace Live Carrier Failover Events

9. Glossary