---
title: "Outbound Routes & LCR"
description: "Documentation for Outbound Routes & LCR"
---

## 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) Engine & LCR Algorithms](#6-kamailio-dynamic-routing-drouting-engine--lcr-algorithms)
7. [Security Best Practices & Operational Hardening](#7-security-best-practices--operational-hardening)
8. [Troubleshooting & Verification](#8-troubleshooting--verification)
9. [Glossary](#9-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:
1. **Pattern Matching**: The SBC tests the dialed digits against configured regular expressions or numerical prefixes.
2. **Digit Transformation**: Applies string manipulations (stripping tech prefixes, prepending international dialing codes).
3. **Gateway Dispatch**: Kamailio routes the call to the highest-priority carrier gateway.
4. **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](/screenshots/sbc/routing/outbound-routes/outbound-routes-list.png)

### 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](/screenshots/sbc/routing/outbound-routes/outbound-routes-form.png)

---

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

```sql
-- 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

```c
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
```bash
# 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
```bash
# Test how Kamailio matches a dialed number (+17865550199)
kamcmd drouting.dr_test_routing 1 "+17865550199"
```

### Trace Live Carrier Failover Events
```bash
# 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.