DEV Community: Moisi Trungu

Asterisk Queue Strategy Guide — Which Ring Strategy to Use

Moisi Trungu — Tue, 07 Jul 2026 03:30:03 +0000

Asterisk Queue Strategy Guide — Which Ring Strategy to Use

Master ring strategies to optimize call routing, reduce agent idle time, and improve contact center performance in ViciDial and Asterisk environments

Introduction

Ring strategy determines how Asterisk distributes calls across available agents in a queue. Choose the wrong strategy and you'll watch call times spike, agents go idle despite having calls waiting, and customers hear excessive hold times. Choose correctly and you maximize agent utilization while maintaining quality.

This guide walks you through every ring strategy Asterisk supports, explains when to use each one, and shows you exactly how to configure and monitor them in production ViciDial environments. You'll learn which strategies work best for predictive dialing, inbound call centers, and hybrid operations—and how to troubleshoot when ring strategy causes problems.

Prerequisites

Before implementing ring strategies in your Asterisk/ViciDial environment, confirm you have:

Asterisk 11.0+ (14.x or 16.x recommended for ViciDial)
ViciDial 2.12+ installed and fully operational
Direct SSH/CLI access to your Asterisk server
MySQL root or vicidial user access to the asterisk database
Understanding of basic queue concepts: agents, queue members, extension status
Current queue configuration in /etc/asterisk/extensions-vicidial.conf
Ability to reload Asterisk (asterisk -rx "core reload") without disrupting production
Log monitoring capability via /var/log/asterisk/messages

If you're unfamiliar with ViciDial queue setup, run asterisk -rx "queue show" to verify your existing configuration is loading.

Understanding Asterisk Ring Strategies

Ring strategy is set in the queue.conf file and controls member selection when a call arrives in queue. Asterisk evaluates the strategy, picks the next agent, and sends the call to that extension.

Ring Strategy Types

Asterisk supports six core strategies:

linear — Cycles through members in order (first-in-queue order)
round-robin — Distributes calls evenly, tracking position
round-robin queue member — Tracks per-queue position (most common in ViciDial)
random — Selects random available agent
fewest-calls — Routes to agent with fewest calls handled
longest-idle — Routes to agent idle longest (agent reuse prevention)

ViciDial defaults to round-robin queue member for good reason: it balances load without requiring call counts and prevents agent burnout from rapid consecutive calls.

Why Ring Strategy Matters in ViciDial

In predictive dialers, agents answer calls immediately—ring strategy doesn't impact speed much. But in inbound queues and blended operations, ring strategy determines:

Agent utilization — Proper strategy keeps agents working, not waiting
Call distribution fairness — Prevents some agents from taking all calls
Customer experience — Bad strategy causes calls to queue while agents are idle
Compliance logging — ViciDial tracks agent activity; wrong strategy creates false idle time

Linear Ring Strategy

Linear sends each new call to the next agent in the queue member list, cycling from top to bottom. Once it reaches the last member, it restarts at the top.

When to Use Linear

Small teams (3-5 agents) where agent positions are fixed
Skill-based routing where agents are listed by specialization order
Legacy systems where you need predictable agent assignment
Testing and development environments

When NOT to Use Linear

Medium-to-large teams (you'll create uneven distribution)
Dynamic agent populations (agents logging in/out constantly)
Predictive dialer environments (agents not present in time for calls)

Linear Configuration

[general]
persistmembers = yes

[inbound_queue]
type = queue
strategy = linear
members = SIP/2001,SIP/2002,SIP/2003
timeout = 15
retry = 5
maxlen = 0
announce-frequency = 60
announce-holdtime = yes

Testing Linear in ViciDial

Verify the queue is loaded and check member order:

asterisk -rx "queue show inbound_queue"

Expected output:

Queue: inbound_queue
  Members: 
    SIP/2001 (dynamic) (In Call)
    SIP/2002 (dynamic) (Not in use) (Penalty: 0)
    SIP/2003 (dynamic) (Not in use) (Penalty: 0)
  Strategy: linear
  Calls in queue: 2

The next call goes to SIP/2002 (first available after SIP/2001).

Linear in ViciDial Database

Check queue configuration in the vicidial database:

SELECT * FROM vicidial_queues WHERE queue_name = 'inbound_queue'\G

If you don't see a queue_strategy field, your ViciDial version stores strategy only in extensions-vicidial.conf.

Round-Robin Ring Strategy

Round-robin selects agents in order, but remembers position between calls. Call 1 goes to agent 2, call 2 goes to agent 3, call 3 goes to agent 1—cycling continuously.

When to Use Round-Robin

Medium teams (5-15 agents) with similar skill levels
When you want to prevent agent burnout from repeated calls
Blended inbound/outbound operations
Phone system testing and demos

When NOT to Use Round-Robin

Predictive dialers (round-robin doesn't align with agent readiness)
Large centers (performance degrades with 50+ members)
Skill-based routing
ViciDial inbound queues (round-robin queue member is superior)

Round-Robin Configuration

[general]
persistmembers = yes
autofill = yes
autofillweight = 0

[sales_queue]
type = queue
strategy = round-robin
members = SIP/3001,SIP/3002,SIP/3003,SIP/3004
timeout = 20
retry = 5
maxlen = 0
announce-frequency = 60
announce-holdtime = yes
joinempty = yes
leavewhenempty = yes

Round-Robin in ViciDial

Create a test queue and monitor call distribution:

# Reload config
asterisk -rx "core reload"

# Check position tracking
asterisk -rx "queue show sales_queue"

# Make test calls and observe position change

After 4 calls, you'll see position reset to the beginning.

Round-Robin Queue Member Strategy (RRQM)

This is ViciDial's default and recommended strategy. It's identical to round-robin but resets position per queue, not globally. This is critical when agents belong to multiple queues.

Why RRQM for ViciDial

In a production contact center:

Agents log into multiple queue types (inbound, tech support, sales)
Round-robin global position breaks queue separation
RRQM ensures fair distribution within each queue independently

When to Use Round-Robin Queue Member

ViciDial inbound queues (always use this)
Multi-queue environments
Blended operations with queue specialization
Any production ViciDial system with 3+ agents

RRQM Configuration

[general]
persistmembers = yes
autofill = yes
autofillweight = 0

[inbound_sales]
type = queue
strategy = rrmemory
members = SIP/4001,SIP/4002,SIP/4003,SIP/4004,SIP/4005
timeout = 25
retry = 5
maxlen = 0
announce-frequency = 60
announce-holdtime = yes
joinempty = yes
leavewhenempty = yes
weight = 100

[inbound_support]
type = queue
strategy = rrmemory
members = SIP/4001,SIP/4002,SIP/4006,SIP/4007
timeout = 30
retry = 5
maxlen = 0
announce-frequency = 60
announce-holdtime = yes
joinempty = yes
leavewhenempty = yes
weight = 80

Here, SIP/4001 and SIP/4002 are in both queues. RRQM maintains separate position tracking for each queue.

Verifying RRQM in Production

Check the active strategy:

asterisk -rx "queue show inbound_sales" | grep Strategy

Output:

Strategy: round robin with memory

Check agent distribution over 1 hour:

SELECT 
  user_extension,
  COUNT(*) as call_count,
  AVG(call_duration) as avg_duration
FROM vicidial_closer_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR)
  AND queue_name = 'inbound_sales'
GROUP BY user_extension
ORDER BY call_count DESC;

Equal call counts across agents confirms RRQM is working.

Random Ring Strategy

Random selects any available agent at random. No position tracking, no fairness guarantee per-call.

When to Use Random

Very small queues (2-3 agents) as a quick test
Kiosk/callback systems where agent identity doesn't matter
Load testing Asterisk queue logic
Emergency overflow scenarios

When NOT to Use Random

Production ViciDial centers (ever)
Any queue with more than 3 agents
Compliance-heavy environments (call distribution is unpredictable)
Agent scheduling (fairness reports become unreliable)

Random Configuration

[testing_queue]
type = queue
strategy = random
members = SIP/5001,SIP/5002,SIP/5003
timeout = 15
retry = 5
maxlen = 0

Why Not to Use Random in ViciDial

Run a call distribution test:

# Generate 100 test calls to random queue
for i in {1..100}; do
  asterisk -rx "queue add member SIP/test$i to testing_queue"
done

Check distribution:

SELECT user_extension, COUNT(*) FROM vicidial_closer_log 
WHERE queue_name = 'testing_queue' 
GROUP BY user_extension;

Result: Expect uneven distribution. One agent may get 40+ calls while another gets 10.

Fewest-Calls Ring Strategy

Routes calls to the agent who has handled the fewest calls (all-time or in a configurable interval).

When to Use Fewest-Calls

Fair load balancing across long shifts
Ensuring low-performing agents aren't left idle
Blended inbound/outbound where outbound dialing skews call counts
Predictive dialers with manual agent selection

When NOT to Use Fewest-Calls

High-volume predictive dialing (adds database overhead)
ViciDial standard inbound (RRQM is lighter and sufficient)
Real-time performance is critical (call selection latency)
Agents with variable skill levels (you want experienced agents taking more calls)

Fewest-Calls Configuration

[blended_queue]
type = queue
strategy = fewest-calls
members = SIP/6001,SIP/6002,SIP/6003,SIP/6004,SIP/6005
timeout = 20
retry = 5
maxlen = 0
announce-frequency = 60
announce-holdtime = yes
joinempty = yes
leavewhenempty = yes

With fewest-calls, if call counts are:

SIP/6001: 45 calls
SIP/6002: 47 calls
SIP/6003: 42 calls (fewest)
SIP/6004: 49 calls
SIP/6005: 46 calls

The next call routes to SIP/6003.

Monitoring Fewest-Calls Distribution

Check call counts in real time:

asterisk -rx "queue show blended_queue"

Log calls per agent per hour to verify algorithm:

SELECT 
  user_extension,
  DATE_FORMAT(call_date, '%Y-%m-%d %H:00:00') as hour,
  COUNT(*) as calls
FROM vicidial_closer_log
WHERE queue_name = 'blended_queue'
  AND call_date >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
GROUP BY user_extension, hour
ORDER BY hour DESC, calls DESC;

Longest-Idle Ring Strategy

Routes calls to the agent idle the longest. Critical for preventing agent burnout and managing call pacing.

When to Use Longest-Idle

Predictive dialers (prevents rapid-fire call pacing)
Agent health and retention focus
Compliance environments where call pacing matters
Blended operations where you're mixing outbound prep time with inbound

When NOT to Use Longest-Idle

Pure inbound call centers (unnecessary overhead)
ViciDial with auto-dialing (dialer already manages pacing)
Very small teams (performance difference is negligible)

Longest-Idle Configuration

[predictive_queue]
type = queue
strategy = longest-idle
members = SIP/7001,SIP/7002,SIP/7003,SIP/7004,SIP/7005,SIP/7006
timeout = 30
retry = 5
maxlen = 0
announce-frequency = 120
announce-holdtime = yes
joinempty = yes
leavewhenempty = yes
wrapuptime = 30

The wrapuptime = 30 parameter tells Asterisk an agent needs 30 seconds between calls. Longest-idle respects this.

Verifying Idle Time in ViciDial

Check agent idle tracking:

SELECT 
  user_extension,
  user_name,
  status,
  last_call_time
FROM vicidial_users
WHERE active = 'Y'
ORDER BY last_call_time DESC;

Monitor idle period in real time:

watch -n 2 'asterisk -rx "queue show predictive_queue" | grep -A 50 "Members:"'

Penalty-Based Member Configuration

All strategies can incorporate member penalties. A penalty increases an agent's effective call count or idle time, effectively deprioritizing them.

Why Use Penalties

Tier agents by skill (high-skill agents get lower penalties)
Manage part-time vs. full-time distribution
Temporarily reduce load on specific agents
Handle agent unavailability gracefully

Penalty Syntax

[skilled_queue]
type = queue
strategy = rrmemory
members = SIP/8001,SIP/8002(penalty=5),SIP/8003(penalty=10),SIP/8004
timeout = 25
retry = 5
maxlen = 0

SIP/8001 (penalty=0, default): Highest priority
SIP/8002 (penalty=5): Medium priority
SIP/8003 (penalty=10): Lowest priority (used only if others unavailable)
SIP/8004 (penalty=0): Equal priority to 8001

Dynamic Penalty in ViciDial

Adjust penalties without reloading config:

asterisk -rx "queue remove member SIP/8003 from skilled_queue"
asterisk -rx "queue add member SIP/8003(penalty=15) to skilled_queue"

Verify:

asterisk -rx "queue show skilled_queue" | grep -A 30 "Members:"

Configuring Queue Strategy in ViciDial

Via extensions-vicidial.conf

The authoritative configuration location for production ViciDial:

[vicidial_queues]
exten => 300,1,Answer()
exten => 300,n,Queue(inbound_queue,t)
exten => 300,n,Hangup()

[general]
persistmembers = yes
autofill = yes

[inbound_queue]
type = queue
strategy = rrmemory
members = SIP/2001,SIP/2002,SIP/2003,SIP/2004
timeout = 25
retry = 5
maxlen = 0
announce-frequency = 60
announce-holdtime = yes
joinempty = yes
leavewhenempty = no

Applying Configuration Changes

Reload without dropping calls:

asterisk -rx "core reload"

Verify queue loaded correctly:

asterisk -rx "queue show inbound_queue"

ViciDial Web Admin Configuration

Navigate to /vicidial/admin.php → System Settings → Queues (if available in your version).

Most modern ViciDial installations manage queues via extensions-vicidial.conf, but older versions (2.10 and earlier) may have GUI queue management. Always verify the loaded config:

grep -n "strategy" /etc/asterisk/extensions-vicidial.conf | head -20

Performance Considerations

CPU and Memory Impact

Different strategies have different overhead:

Strategy	CPU Cost	Memory Cost	Best For
linear	Very Low	Minimal	Small teams
rrmemory	Low	Minimal	Production ViciDial
random	Very Low	Minimal	Testing
fewest-calls	Medium	Medium	Large centers
longest-idle	Medium	Medium	Predictive dialers

Scaling Considerations

For large contact centers:

Up to 20 agents: RRQM or linear work fine
20-50 agents: Use RRQM with penalties for skill tiers
50+ agents: Consider fewest-calls or longest-idle; monitor CPU
100+ agents: Use load balancing across multiple Asterisk boxes

Monitoring Queue Performance

Create a monitoring script to track strategy effectiveness:

#!/bin/bash
# /usr/local/bin/monitor_queues.sh

LOGFILE="/var/log/queue_monitor.log"

while true; do
  TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')

  echo "=== $TIMESTAMP ===" >> $LOGFILE
  asterisk -rx "queue show" >> $LOGFILE 2>&1

  echo "" >> $LOGFILE
  sleep 300  # Check every 5 minutes
done

Run in background:

nohup /usr/local/bin/monitor_queues.sh > /dev/null 2>&1 &

Ring Strategy Selection Matrix

Use this matrix to pick the right strategy for your scenario:

SCENARIO                          RECOMMENDED STRATEGY    BACKUP
────────────────────────────────────────────────────────────────────
Small inbound (< 5 agents)        linear                  rrmemory
Medium inbound (5-20 agents)      rrmemory                rrmemory
Large inbound (20+ agents)        rrmemory + penalties    fewest-calls
Predictive dialer                 longest-idle            rrmemory
Blended (inbound + outbound)      rrmemory or fewest      longest-idle
Skill-based routing               linear + penalties      rrmemory
Multi-queue agents                rrmemory (mandatory)    N/A
Testing/Demo                      random or linear        N/A
High compliance requirements      longest-idle            rrmemory

Troubleshooting Ring Strategy Issues

Symptom: Uneven Call Distribution

Cause: Wrong strategy or penalty misconfiguration

Diagnosis:

# Check queue strategy
asterisk -rx "queue show yourqueue" | grep Strategy

# Check member penalties
asterisk -rx "queue show yourqueue" | grep -A 50 "Members:"

Solution:

If using linear and distribution is uneven, switch to rrmemory:

[yourqueue]
strategy = rrmemory

Reload and verify:

asterisk -rx "core reload"
asterisk -rx "queue show yourqueue"

Symptom: Agents Sitting Idle While Calls Queue

Cause: Strategy doesn't match agent availability state, or agent status is stuck

Diagnosis:

# Check actual extension status
asterisk -rx "core show hints | grep SIP/2001"

# Check if agent is truly available
asterisk -rx "sip show peers | grep 2001"

# Check queue log for routing decisions
tail -50 /var/log/asterisk/queue_log

Solution:

Verify agent is actually available in Asterisk state machine:

asterisk -rx "device state list | grep SIP/2001"

If stuck NOT_INUSE when agent is on call, restart agent phone or kickout stale session:

asterisk -rx "sip notify check-sync SIP/2001"

Symptom: Strategy Changed But Old Behavior Persists

Cause: Config reload didn't take effect, or persistmembers saved old config

Diagnosis:

# Verify which config is loaded
asterisk -rx "module show like queue"

# Check persistent members file
ls -la /var/spool/asterisk/outgoing/
cat /var/spool/asterisk/outgoing/queue_members.conf 2>/dev/null

Solution:

Clear persistent member cache:

asterisk -rx "queue reset stats"

If that doesn't work, rebuild completely:

# Backup current config
cp /etc/asterisk/extensions-vicidial.conf /etc/asterisk/extensions-vicidial.conf.backup

# Remove persistent files
rm -f /var/spool/asterisk/outgoing/queue_members.conf

# Full restart Asterisk (careful in production)
systemctl restart asterisk

# Verify new strategy
asterisk -rx "queue show yourqueue" | grep Strategy

Symptom: High CPU Usage After Strategy Change

Cause: fewest-calls or longest-idle causing database queries per call

Diagnosis:

# Check CPU
top -b -n 1 | grep asterisk

# Check Asterisk process details
ps aux | grep asterisk | grep -v grep

# Monitor Asterisk queue processing
asterisk -rx "core show profile" | grep Queue

Solution:

If CPU spike correlates with fewest-calls strategy, downgrade to rrmemory:

# Change from
strategy = fewest-calls

# To
strategy = rrmemory

Reload and monitor:

asterisk -rx "core reload"
watch -n 1 'top -b -n 1 | grep asterisk'

Symptom: Random Strategy Causing Call Distribution Complaints

Cause: Random legitimately causes uneven distribution; agents perceive unfairness

Diagnosis:

Run hourly distribution report:

SELECT 
  user_extension,
  COUNT(*) as total_calls,
  ROUND(COUNT(*) * 100.0 / (SELECT COUNT(*) FROM vicidial_closer_log WHERE queue_name = 'yourqueue' AND call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR)), 2) as percent
FROM vicidial_closer_log
WHERE queue_name = 'yourqueue'
  AND call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR)
GROUP BY user_extension
ORDER BY total_calls DESC;

Solution:

Switch to rrmemory:

strategy = rrmemory

Re-run report after 1 hour—distribution will be nearly identical across agents.

Advanced: Custom Queue Logic via AGI

For edge cases where built-in strategies don't fit, use Asterisk Gateway Interface (AGI) to implement custom routing:

<?php
// /var/lib/asterisk/agi-bin/custom_route.php

$agi = new AGI();
$queue = $agi->request['agi_arg_1'];

// Fetch agents ordered by custom logic
$mysqli = new mysqli('localhost', 'root', 'password', 'asterisk');

$result = $mysqli->query("
  SELECT user_extension 
  FROM vicidial_users
  WHERE active = 'Y'
    AND user_group = '$queue'
  ORDER BY calls_today ASC
  LIMIT 1
");

$row = $result->fetch_assoc();
$target = $row['user_extension'];

// Route call to chosen agent
$agi->exec('Dial', "SIP/$target");
?>

Call from extensions-vicidial.conf:

exten => 300,1,AGI(custom_route.php,inbound_queue)
exten => 300,n,Queue(inbound_queue,t)

This is overkill for 99% of installations but useful for complex skill-based routing.

Summary

Ring strategy is the invisible backbone of queue performance. Choose wisely:

For production ViciDial: Use rrmemory (round-robin queue member) as your default. It's battle-tested, fair, and lightweight.
For predictive dialers: Use longest-idle to prevent agent burnout and control call pacing.
For skill-based routing: Start with linear or rrmemory plus penalties to prioritize experienced agents.
For large centers (50+ agents): Monitor fewest-calls as an alternative, but verify CPU impact first.
Never use random in production—it's called "random" for a reason.

Always verify configuration loaded correctly with asterisk -rx "queue show yourqueue", monitor distribution with database queries, and adjust penalties if specific agents need deprioritization.

The right ring strategy keeps your agents happy, your customers served quickly, and your contact center running efficiently. Get this right, and you'll never think about it again.

ViciDial Disposition Statuses — Complete Reference & Custom Setup

Moisi Trungu — Mon, 06 Jul 2026 10:14:03 +0000

ViciDial Disposition Statuses — Complete Reference & Custom Setup

Master ViciDial disposition codes, implement custom statuses, configure agent workflows, and troubleshoot disposition-related issues in production call center environments.

Prerequisites

Before configuring disposition statuses in ViciDial, ensure you have:

ViciDial 2.14+ installed and running (this guide applies to 2.14–2.15+)
Root or administrative database access to the asterisk MySQL database
SSH access to your ViciDial server for command-line operations
Agent login credentials for testing agent-facing UI changes
PhpMyAdmin or MySQL CLI for direct database queries
Backup of your asterisk database before making changes
Understanding of call disposition workflows in your organization
Access to ViciDial admin panel (/vicidial/admin.php)

Verify your setup with:

mysql -u root -p asterisk -e "SELECT VERSION();"
asterisk -rx "core show version"
ps aux | grep vicidial

What Are ViciDial Disposition Statuses?

Disposition statuses represent the outcome of a call recorded in your call center. When an agent ends a call, they select a disposition code that categorizes what happened: "Sold," "No Answer," "Callback," "Wrong Number," etc.

ViciDial stores these dispositions in the database and uses them for:

Call analytics and reporting (conversion rates, abandonment tracking)
Compliance and call tagging (for recording regulations, quality assurance)
Callback queuing (disposition rules can auto-schedule future calls)
Lead status tracking (updating CRM integration feeds)
Agent performance metrics (which agents achieve higher sales rates)
Dial plan routing (different dispositions trigger different behaviors)

Every call logged in vicidial_log must have a valid disposition from the vicidial_statuses table.

The ViciDial Statuses Table Structure

The core disposition data lives in the vicidial_statuses table. Understanding its schema is essential for custom configuration.

Default Table Schema

DESCRIBE vicidial_statuses;

Output:

| Field            | Type         | Null | Key | Default |
|------------------|--------------|------|-----|---------|
| status           | varchar(6)   | NO   | PRI | NULL    |
| status_name      | varchar(20)  | NO   |     | NULL    |
| status_details   | varchar(255) | YES  |     | NULL    |
| scheduled_status | char(1)      | NO   |     | N       |
| customer_viewable| char(1)      | NO   |     | N       |
| agent_viewable   | char(1)      | NO   |     | Y       |
| lead_status_id   | int(11)      | YES  |     | NULL    |
| callback_type    | varchar(20)  | YES  |     | NULL    |
| scheduled_callback| char(1)      | NO   |     | N       |

Column Definitions

Column	Purpose	Example
`status`	6-char code, primary key	`SALE`, `CALLB`
`status_name`	Display name (20 chars max)	`Sale`, `Callback`
`status_details`	Long description for clarity	`Successful sale completed`
`scheduled_status`	'Y' if status schedules callbacks	`Y`
`customer_viewable`	'Y' if visible on customer portal	`N`
`agent_viewable`	'Y' if agent can select it	`Y`
`lead_status_id`	Maps to external CRM/lead table	`1`, `2`, etc.
`callback_type`	Type of callback: `SAME_AGENT`, `ANY_AGENT`, `VOICEMAIL`	`SAME_AGENT`
`scheduled_callback`	'Y' if auto-schedules for future	`Y`

Default ViciDial Disposition Statuses

ViciDial ships with these standard dispositions:

SELECT status, status_name, scheduled_status, agent_viewable 
FROM vicidial_statuses 
ORDER BY status;

Common defaults:

| SALE     | Sale              | N | Y |
| CALLB    | Callback          | Y | Y |
| XFER     | Transfer          | N | Y |
| AFAX     | Answering Machine | N | Y |
| IGVM     | IVR/Voicemail     | N | Y |
| XFAX     | Transfer Fax      | N | Y |
| DROP     | Dropped Call      | N | N |
| RING     | No Answer/Ring    | N | Y |
| BUSY     | Busy Signal       | N | Y |
| INTL     | International     | N | Y |
| INVALID  | Invalid Number    | N | Y |
| NOTINT   | Not Interested    | N | Y |
| ABANDON  | Agent Abandoned   | N | N |
| VLCM     | Voicemail/IVR     | N | Y |
| REVIEW   | Review            | N | Y |
| DLEADS   | DNC/Bad Lead      | N | Y |
| DNCS     | Do Not Call List  | N | Y |
| PAID     | Paid              | N | Y |

Not all defaults are visible to agents—some (like DROP, ABANDON) are system-assigned.

Adding Custom Disposition Statuses

Most call centers need custom statuses beyond ViciDial's defaults. Common examples:

WARM – Warm lead for follow-up
SURVEY – Customer completed survey
DISPUTE – Payment dispute or refund
DCNTCT – Do Not Contact (different from DNC list)
RESCHL – Rescheduled appointment
PARTIAL – Partial sale or trial signup

Method 1: Via ViciDial Web Admin Panel

Login to /vicidial/admin.php
Navigate: System > Statuses
Click Add New Status
Fill in:
- Status Code: WARM (6 chars max, uppercase)
- Status Name: Warm Lead (20 chars max)
- Status Details: Prospect interested, needs follow-up (optional)
- Scheduled Status: Toggle if this triggers callbacks
- Agent Viewable: Yes (so agents can select it)
- Customer Viewable: No (for internal use only)
Click Save

Method 2: Direct Database Insert (Recommended for Scripting/Bulk)

INSERT INTO vicidial_statuses 
(status, status_name, status_details, scheduled_status, customer_viewable, agent_viewable, callback_type, scheduled_callback)
VALUES
('WARM', 'Warm Lead', 'Prospect interested, needs follow-up', 'N', 'N', 'Y', NULL, 'N'),
('SURVEY', 'Survey Completed', 'Customer completed survey', 'N', 'N', 'Y', NULL, 'N'),
('DISPUTE', 'Dispute', 'Customer reports payment issue', 'Y', 'N', 'Y', 'SAME_AGENT', 'Y'),
('DCNTCT', 'Do Not Contact', 'Customer requests no contact', 'N', 'N', 'Y', NULL, 'N'),
('RESCHL', 'Rescheduled', 'Appointment rescheduled', 'Y', 'N', 'Y', 'SAME_AGENT', 'Y'),
('PARTIAL', 'Trial Signup', 'Customer signed up for trial', 'Y', 'N', 'Y', 'ANY_AGENT', 'Y');

Always test in a development environment first.

Verify insertion:

SELECT status, status_name, scheduled_status, agent_viewable 
FROM vicidial_statuses 
WHERE status IN ('WARM', 'SURVEY', 'DISPUTE', 'DCNTCT', 'RESCHL', 'PARTIAL');

Method 3: Via Script (Bash + MySQL)

Create /tmp/add_dispositions.sql:

USE asterisk;

INSERT INTO vicidial_statuses (status, status_name, status_details, scheduled_status, agent_viewable, callback_type, scheduled_callback)
VALUES ('WARM', 'Warm Lead', 'Interested prospect', 'N', 'Y', NULL, 'N');

INSERT INTO vicidial_statuses (status, status_name, status_details, scheduled_status, agent_viewable, callback_type, scheduled_callback)
VALUES ('SURVEY', 'Survey', 'Completed survey', 'N', 'Y', NULL, 'N');

-- Add more as needed...

Execute:

mysql -u root -p < /tmp/add_dispositions.sql

Or without interactive password prompt:

mysql -u root -p"YOUR_PASSWORD" < /tmp/add_dispositions.sql

Mapping Dispositions to Lead Statuses

ViciDial can integrate dispositions with external lead management systems via lead_status_id. This field links a disposition to a status in your CRM or lead database.

Understanding lead_status_id

The lead_status_id column in vicidial_statuses maps to the vicidial_list.lead_status field. When an agent selects a disposition, that lead's status updates accordingly.

Query available lead statuses:

SELECT DISTINCT lead_status FROM vicidial_list LIMIT 20;

Common lead_status values:

NEW – New lead
CALL – Ready for call
CALLBACK – Scheduled callback
SALE – Sale completed
DNCS – Do not call

Mapping Example

Link your custom "WARM" disposition to lead status CALLBACK:

UPDATE vicidial_statuses 
SET lead_status_id = 
  (SELECT COALESCE(MAX(CAST(lead_status AS UNSIGNED)), 0) + 1 FROM vicidial_list)
WHERE status = 'WARM';

-- Or explicitly:
UPDATE vicidial_statuses 
SET lead_status = 'CALLBACK' 
WHERE status = 'WARM';

Configuring Scheduled Callbacks

When an agent selects a "Callback" or custom disposition marked for scheduling, ViciDial can automatically insert that lead back into the queue for a future date/time.

Enable Scheduling on a Disposition

UPDATE vicidial_statuses 
SET scheduled_status = 'Y', 
    callback_type = 'SAME_AGENT', 
    scheduled_callback = 'Y' 
WHERE status = 'DISPUTE';

Callback Types

Type	Behavior
`SAME_AGENT`	Callback scheduled only for original agent
`ANY_AGENT`	Any available agent can take callback
`VOICEMAIL`	Auto-dial with voicemail

How Callbacks Work in Production

Agent dials lead, conversation occurs
Agent selects "DISPUTE" disposition
ViciDial UI prompts agent for callback date/time
Record inserted into vicidial_callbacks table
Vicidial dialer process checks table periodically
At scheduled time, call re-queued to appropriate agent/queue

Verify callback records:

SELECT lead_id, phone_number, callback_datetime, callback_type 
FROM vicidial_callbacks 
WHERE callback_datetime > NOW() 
LIMIT 10;

Agent-Facing Disposition UI Customization

How agents interact with dispositions is configured in /agc/vicidial.php (the agent client).

Controlling Disposition Visibility

In vicidial_statuses, toggle agent access:

-- Hide a disposition from agents (system-assigned only)
UPDATE vicidial_statuses 
SET agent_viewable = 'N' 
WHERE status = 'ABANDON';

-- Show a disposition to agents
UPDATE vicidial_statuses 
SET agent_viewable = 'Y' 
WHERE status = 'WARM';

Grouping Dispositions (Using Status Details)

While ViciDial doesn't have built-in grouping, you can use status_details to organize codes in documentation:

UPDATE vicidial_statuses 
SET status_details = 'SALES_GROUP: Prospect converted to customer' 
WHERE status = 'SALE';

UPDATE vicidial_statuses 
SET status_details = 'SALES_GROUP: Prospect interested but not ready' 
WHERE status = 'WARM';

UPDATE vicidial_statuses 
SET status_details = 'REJECTION_GROUP: Lead not interested in product' 
WHERE status = 'NOTINT';

Agents see this in tooltips/hover text in some UI versions.

Custom Disposition Dropdown Order

ViciDial sorts dispositions alphabetically by status_name. To customize order, some deployments use numeric prefixes:

UPDATE vicidial_statuses 
SET status_name = '01 - Sale' 
WHERE status = 'SALE';

UPDATE vicidial_statuses 
SET status_name = '02 - Callback' 
WHERE status = 'CALLB';

UPDATE vicidial_statuses 
SET status_name = '99 - Abandoned' 
WHERE status = 'ABANDON';

Note: This affects sorting but requires agents to ignore numeric prefix when reading.

Disposition Rules & Automation

ViciDial can automatically trigger actions based on disposition selection. Configuration happens in vicidial_disposition_rules table.

View Existing Rules

SELECT rule_id, disposition, pause_after_call, seconds_pause, pause_type 
FROM vicidial_disposition_rules;

Common Automation: Force Pause After Sale

Require agents to pause (e.g., for documentation) after recording a sale:

INSERT INTO vicidial_disposition_rules 
(disposition, pause_after_call, seconds_pause, pause_type)
VALUES
('SALE', 'Y', 60, 'AFTER_SALE_PAUSE');

This forces a 60-second pause on agents after they log a sale disposition.

Automatic DNC List Addition

Some dispositions automatically add numbers to DNC (Do Not Call) list:

This is typically handled in the dialer code, but can be logged by disposition:

-- Log which dispositions hit DNC
SELECT COUNT(*), disposition 
FROM vicidial_log 
WHERE disposition IN ('DNCS', 'DLEADS') 
GROUP BY disposition;

Reporting & Analytics by Disposition

Most call centers track KPIs by disposition. Common queries:

Disposition Summary Today

SELECT disposition, COUNT(*) as calls, 
       ROUND(COUNT(*) * 100.0 / (SELECT COUNT(*) FROM vicidial_log WHERE call_date >= CURDATE()), 2) as pct
FROM vicidial_log 
WHERE call_date >= CURDATE()
GROUP BY disposition 
ORDER BY calls DESC;

Sales Conversion Rate by Agent

SELECT user, 
       SUM(CASE WHEN disposition = 'SALE' THEN 1 ELSE 0 END) as sales,
       COUNT(*) as total_calls,
       ROUND(SUM(CASE WHEN disposition = 'SALE' THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 2) as conversion_pct
FROM vicidial_log 
WHERE call_date >= DATE_SUB(CURDATE(), INTERVAL 7 DAY)
GROUP BY user 
ORDER BY sales DESC;

Callbacks Scheduled vs. Completed

SELECT disposition, 
       COUNT(*) as dispositions_selected,
       SUM(CASE WHEN disposition IN ('CALLB', 'DISPUTE', 'RESCHL') THEN 1 ELSE 0 END) as callbacks_scheduled
FROM vicidial_log 
WHERE call_date >= DATE_SUB(CURDATE(), INTERVAL 30 DAY)
GROUP BY disposition;

Time to Disposition (Handle Time)

SELECT disposition, 
       COUNT(*) as calls,
       ROUND(AVG(LENGTH_OF_CALL), 2) as avg_seconds,
       MAX(LENGTH_OF_CALL) as longest_call
FROM vicidial_log 
WHERE call_date >= CURDATE()
GROUP BY disposition 
ORDER BY avg_seconds DESC;

ViciDial Configuration Files (Advanced)

For full customization, some settings live in config files, though most disposition logic is database-driven.

Relevant Config Paths

Asterisk extensions (call routing by disposition):

/etc/asterisk/extensions-vicidial.conf

SIP configuration:

/etc/asterisk/sip-vicidial.conf

ViciDial web config:

/var/www/html/vicidial/vicidial_settings.php

Example: Disable Disposition Selection for Certain Agents

While not in config files, you can restrict agent groups by modifying the agent record:

-- Agent 'john' can ONLY select SALE or CALLB
-- This requires custom UI mod, but data structure allows it
UPDATE vicidial_users 
SET agent_group = 'SALES_ONLY' 
WHERE user = 'john';

Then query agents during call to enforce:

SELECT allowed_statuses FROM vicidial_user_groups 
WHERE group_name = 'SALES_ONLY';

This requires custom code in /agc/vicidial.php to implement.

Troubleshooting Disposition Issues

Issue 1: Agent Sees "Invalid Disposition" Error

Symptom: Agent logs call but gets error when selecting disposition.

Cause: Selected disposition code doesn't exist in vicidial_statuses or is not viewable.

Solution:

# Check if disposition is in database
mysql -u root -p asterisk -e \
  "SELECT status, agent_viewable FROM vicidial_statuses WHERE status = 'WARM';"

# If missing, add it:
mysql -u root -p asterisk -e \
  "INSERT INTO vicidial_statuses (status, status_name, agent_viewable) VALUES ('WARM', 'Warm Lead', 'Y');"

# If hidden, make it visible:
mysql -u root -p asterisk -e \
  "UPDATE vicidial_statuses SET agent_viewable = 'Y' WHERE status = 'WARM';"

Then reload ViciDial dialer:

/usr/share/astguiclient/ADMIN_reload_vicidial_agent.pl

Issue 2: Callbacks Not Triggering

Symptom: Agent selects callback disposition but lead doesn't re-queue.

Cause: scheduled_callback not set to 'Y' or callback type not configured.

Solution:

-- Verify callback disposition config
SELECT status, scheduled_status, scheduled_callback, callback_type 
FROM vicidial_statuses 
WHERE status = 'CALLB';

-- Should show: CALLB | Y | Y | SAME_AGENT or ANY_AGENT

-- If not, update:
UPDATE vicidial_statuses 
SET scheduled_status = 'Y', scheduled_callback = 'Y', callback_type = 'SAME_AGENT' 
WHERE status = 'CALLB';

-- Verify callback queue
SELECT * FROM vicidial_callbacks WHERE callback_datetime > NOW() LIMIT 5;

Check ViciDial dialer logs:

tail -f /var/log/asterisk/messages | grep -i callback

Issue 3: Custom Disposition Not Appearing in Dropdown

Symptom: New custom disposition added but agents don't see it in UI.

Cause:

Disposition not viewable to agents
Agent screen needs cache cleared
Database not synchronized to all dialer nodes

Solution:

# Verify viewable flag
mysql -u root -p asterisk -e \
  "SELECT status, status_name, agent_viewable FROM vicidial_statuses WHERE status = 'SURVEY';"

# Ensure it's viewable
mysql -u root -p asterisk -e \
  "UPDATE vicidial_statuses SET agent_viewable = 'Y' WHERE status = 'SURVEY';"

# Clear agent screen cache
rm -rf /tmp/vicidial_*.cache

# Reload dialer
/usr/share/astguiclient/ADMIN_reload_vicidial_dialer.pl

Restart Asterisk if needed:

asterisk -rx "core restart graceful"

Issue 4: Disposition Assignment Causing Call Log Errors

Symptom: Calls logged but disposition missing or NULL in vicidial_log.

Cause: Agent disconnected before selecting disposition, or default disposition not configured.

Solution:

-- Check for NULL dispositions
SELECT call_id, user, phone_number, disposition 
FROM vicidial_log 
WHERE disposition IS NULL OR disposition = '' 
LIMIT 20;

-- Set a default disposition if missing
UPDATE vicidial_log 
SET disposition = 'REVIEW' 
WHERE disposition IS NULL AND call_date >= CURDATE();

Then investigate why disposition wasn't captured (check Asterisk logs):

tail -100 /var/log/asterisk/messages | grep -i "disposition\|agent\|call"

Issue 5: Disposition Count Mismatch in Reports

Symptom: Total calls ≠ sum of disposition counts.

Cause: Inbound calls, test calls, or dropped calls logged without disposition.

Solution:

-- Find unmatched calls
SELECT COUNT(*) as total_calls FROM vicidial_log WHERE call_date >= CURDATE();

SELECT COUNT(*) as calls_with_disposition FROM vicidial_log 
WHERE call_date >= CURDATE() AND disposition IS NOT NULL AND disposition != '';

-- Calls without disposition
SELECT COUNT(*) as calls_no_disposition FROM vicidial_log 
WHERE call_date >= CURDATE() AND (disposition IS NULL OR disposition = '');

-- Check call types
SELECT call_type, COUNT(*) FROM vicidial_log 
WHERE call_date >= CURDATE() GROUP BY call_type;

Filter inbound calls if they shouldn't count:

-- Outbound only
SELECT disposition, COUNT(*) FROM vicidial_log 
WHERE call_date >= CURDATE() AND call_type = 'OUT' 
GROUP BY disposition;

Best Practices for Disposition Management

Name codes clearly: Use descriptive status_name values (e.g., Warm Lead not WL). Agents need instant recognition.
Keep codes ≤6 characters: ViciDial schema limits to 6 chars. Choose meaningful abbreviations.
Audit new dispositions: Before deploying custom statuses, verify they don't conflict with existing codes or external integrations.
Test callback logic: Always test scheduled callbacks in staging with dummy leads before production deployment.
Document for agents: Create a quick reference (PDF or printed) with all dispositions, definitions, and when to use each.
Monitor disposition drift: Track if agents use dispositions as intended. Run quarterly audits.
Use status_details for context: Leverage the optional field to provide business rules or examples.
Version control database changes: Maintain SQL migration scripts in Git for disaster recovery.
Restrict sensitive statuses: Ensure agent_viewable = 'N' for system-only codes like DROP, ABANDON.
Test UI changes thoroughly: Disposition changes affect agent workflow; test with small agent group first.

Summary

ViciDial disposition statuses are fundamental to call center operations. They categorize call outcomes, drive analytics, and automate workflows like callback scheduling.

Key takeaways:

Dispositions live in vicidial_statuses table — the single source of truth for call outcomes
Custom statuses are easy to add — either via web UI or direct SQL insert
Agent visibility is controlled — set agent_viewable flag to show/hide dispositions
Scheduled callbacks integrate with dispositions — scheduled_status and callback_type fields enable auto-queuing
Reporting by disposition is powerful — track KPIs like conversion rate, handle time, and callback completion
Troubleshooting is database-first — most issues resolve via verification and configuration of the statuses table
Production deployments require testing — validate custom dispositions in staging before rollout to live agents

For advanced integrations (external CRM sync, custom disposition rules, dynamic agent workflows), ViciDial's database-first architecture supports nearly any customization.

Additional Resources

ViciDial Official Documentation: https://vicidial.org/
Asterisk Command Reference: asterisk -rx "help"
MySQL Reference: https://dev.mysql.com/doc/
ViciDial Admin Guides: /vicidial/admin.php built-in help
Community Forums: ViciDial forums for peer support

SIP Trunk Failover & Load Balancing for ViciDial

Moisi Trungu — Thu, 07 May 2026 19:51:06 +0000

SIP Trunk Failover & Load Balancing for ViciDial

Master multi-trunk redundancy, active-active load balancing, and failover logic to ensure zero-downtime calling in your ViciDial environment

Prerequisites

Before implementing SIP trunk failover and load balancing, ensure you have:

ViciDial 2.14.1 or later (earlier versions have limited failover capabilities)
Asterisk 16.x or 18.x LTS (tested on both; 18.x recommended)
Root or sudo access to your ViciDial server
Direct access to MySQL/MariaDB for the asterisk database
At least two active SIP trunks from different providers (critical for meaningful failover)
Basic understanding of Asterisk dialplan syntax and ViciDial database structure
SSH access to your ViciDial box for file editing and command execution
Asterisk reloading capability (already configured if you installed ViciDial properly)

Understanding ViciDial Trunk Architecture

Current Trunk Configuration

ViciDial uses the vicidial_carrier_log and carrier configuration within Asterisk to manage outbound trunks. By default, ViciDial assigns trunks sequentially without native failover intelligence. This creates a single point of failure: if your primary trunk drops, calls queue up or fail until manual intervention occurs.

The key components you'll interact with:

vicidial_carrier_log table: Stores trunk status, call counts, and metrics
extensions-vicidial.conf: Dialplan that routes calls through trunks
sip-vicidial.conf: SIP peer definitions for each trunk
Web interface: /vicidial/admin.php?action=vicidial_carrier for carrier management

Load Balancing vs. Failover

Load Balancing: Distributes outbound calls across multiple trunks in real-time
Failover: Redirects traffic to a backup trunk when the primary fails
Active-Active: Both trunks carry traffic simultaneously
Active-Passive: Secondary trunk only receives traffic when primary fails

This tutorial implements active-active load balancing with intelligent failover.

Step 1: Prepare Your SIP Trunks

Verify Trunk Connectivity

First, confirm both trunks are provisioned and responsive:

# SSH into your ViciDial server
ssh root@your-vicidial-server

# Test trunk 1 connectivity (replace with your carrier IP/domain)
asterisk -rx "sip show peers" | grep -E "trunk1|trunk2"

# Expected output:
# trunk1/trunk1                          xxx.xxx.xxx.xxx:5060    OK (49 ms)
# trunk2/trunk2                          yyy.yyy.yyy.yyy:5060    OK (52 ms)

If either trunk shows "UNREACHABLE", contact your carrier and verify:

Firewall rules allow SIP (5060/UDP, 5061/TCP)
NAT traversal settings match carrier requirements
Your public IP is whitelisted at the carrier

Document Trunk Details

Create a reference file with your trunk specifications:

cat > /root/trunk_config.txt << 'EOF'
TRUNK 1 (Primary)
Provider: VoIP Provider A
IP: 203.0.113.10
Port: 5060
Protocol: UDP
Username: your_account_1
Password: your_pass_1
Capacity: 100 concurrent calls

TRUNK 2 (Secondary)
Provider: VoIP Provider B
IP: 198.51.100.20
Port: 5060
Protocol: UDP
Username: your_account_2
Password: your_pass_2
Capacity: 100 concurrent calls
EOF

chmod 600 /root/trunk_config.txt

Step 2: Configure SIP Peers with Health Monitoring

Edit sip-vicidial.conf

Navigate to the Asterisk configuration:

cp /etc/asterisk/sip-vicidial.conf /etc/asterisk/sip-vicidial.conf.backup
nano /etc/asterisk/sip-vicidial.conf

Locate your trunk definitions and add health monitoring parameters. If they don't exist, add them:

; TRUNK 1 - Primary Carrier
[trunk1]
type=peer
host=203.0.113.10
port=5060
username=your_account_1
fromuser=your_account_1
secret=your_pass_1
fromhost=203.0.113.10
dtmfmode=rfc2833
disallow=all
allow=ulaw
allow=alaw
qualify=yes
qualifyfreq=60
qualifysmoothing=yes
qualifygap=3
maxretries=2
retryinterval=6
timert1=500
nat=force_rport,comedia
insecure=port,invite
context=from-external-vicidial

; TRUNK 2 - Secondary Carrier
[trunk2]
type=peer
host=198.51.100.20
port=5060
username=your_account_2
fromuser=your_account_2
secret=your_pass_2
fromhost=198.51.100.20
dtmfmode=rfc2833
disallow=all
allow=ulaw
allow=alaw
qualify=yes
qualifyfreq=60
qualifysmoothing=yes
qualifygap=3
maxretries=2
retryinterval=6
timert1=500
nat=force_rport,comedia
insecure=port,invite
context=from-external-vicidial

Critical parameters explained:

qualify=yes: Enables SIP OPTIONS ping (default every 60 seconds)
qualifyfreq=60: Check trunk health every 60 seconds
qualifygap=3: Mark trunk down after 3 failed checks (180 seconds)
maxretries=2: Retry outbound calls 2 times before failover
timert1=500: Increase timeout for slow carriers

Reload SIP Configuration

asterisk -rx "sip reload"
asterisk -rx "sip show peers" | grep -E "trunk1|trunk2"

Expect output showing both trunks as "OK" (or "UNREACHABLE" if not connected):

trunk1/trunk1                          203.0.113.10:5060      OK (45 ms)
trunk2/trunk2                          198.51.100.20:5060     OK (48 ms)

Step 3: Configure Dialplan with Intelligent Failover

Edit extensions-vicidial.conf

Open the dialplan configuration:

cp /etc/asterisk/extensions-vicidial.conf /etc/asterisk/extensions-vicidial.conf.backup
nano /etc/asterisk/extensions-vicidial.conf

Find the outbound dialing context or create a new one. Here's a production-grade dialplan that implements load balancing with failover:

; Outbound Dialing Context with Load Balancing and Failover
[outbound-vicidial-lb]
exten => _1NXXNXXXXXX,1,NoOp(Load Balance Outbound: ${EXTEN})
exten => _1NXXNXXXXXX,n,Set(DIAL_ATTEMPTS=0)
exten => _1NXXNXXXXXX,n,Set(MAX_ATTEMPTS=2)
exten => _1NXXNXXXXXX,n,GoSub(try-trunk,1,1)
exten => _1NXXNXXXXXX,n,NoOp(Call Result: ${CALL_RESULT})
exten => _1NXXNXXXXXX,n,Hangup()

; Subroutine: Attempt call on next available trunk
[try-trunk]
exten => 1,1,Set(DIAL_ATTEMPTS=${MATH(${DIAL_ATTEMPTS}+1)})
exten => 1,n,NoOp(Dial Attempt ${DIAL_ATTEMPTS} of ${MAX_ATTEMPTS})

; Get current trunk selection based on load
exten => 1,n,Set(LOAD_TRUNK1=${CHANNEL(numchannels)})
exten => 1,n,Set(TRUNK_SELECT=trunk1)

; Check if trunk1 is available
exten => 1,n,GotoIf($["${DEVICESTATE(SIP/trunk1)}"="UNAVAILABLE"]?try-trunk2)
exten => 1,n,Set(CALL_RESULT=ATTEMPTING_TRUNK1)
exten => 1,n,Dial(SIP/${EXTEN}@trunk1,,gM(vicidial-record^${UNIQUEID}))
exten => 1,n,Set(CALL_RESULT=${DIALSTATUS})
exten => 1,n,GotoIf($["${DIALSTATUS}"="ANSWER"]?success)
exten => 1,n,GoTo(check-retry)

; Try trunk2 if trunk1 failed
exten => 1,n(try-trunk2),Set(CALL_RESULT=ATTEMPTING_TRUNK2)
exten => 1,n,Set(TRUNK_SELECT=trunk2)
exten => 1,n,GotoIf($["${DEVICESTATE(SIP/trunk2)}"="UNAVAILABLE"]?check-retry)
exten => 1,n,Dial(SIP/${EXTEN}@trunk2,,gM(vicidial-record^${UNIQUEID}))
exten => 1,n,Set(CALL_RESULT=${DIALSTATUS})
exten => 1,n,GotoIf($["${DIALSTATUS}"="ANSWER"]?success)

; Check if we should retry
exten => 1,n(check-retry),GotoIf($[${DIAL_ATTEMPTS}<${MAX_ATTEMPTS}]?retry)
exten => 1,n,NoOp(All trunks exhausted)
exten => 1,n,Return()

exten => 1,n(retry),Wait(2)
exten => 1,n,Return()

exten => 1,n(success),NoOp(Call connected via ${TRUNK_SELECT})
exten => 1,n,Return()

Important: Replace vicidial-record with your actual recording macro name. Check your existing extensions-vicidial.conf for the correct macro.

Load Balancing with Round-Robin

For true load balancing (distributing calls across both trunks), add this alternative context:

[outbound-vicidial-rr]
exten => _1NXXNXXXXXX,1,NoOp(Round-Robin Load Balance: ${EXTEN})
exten => _1NXXNXXXXXX,n,Set(CALL_COUNT=${EVAL(${ASTDB(vicidial,call_count)} + 1)})
exten => _1NXXNXXXXXX,n,Set(ASTDB(vicidial,call_count)=${CALL_COUNT})

; Determine which trunk based on modulo (odd/even calls)
exten => _1NXXNXXXXXX,n,Set(TRUNK_MOD=${MATH(${CALL_COUNT} % 2)})
exten => _1NXXNXXXXXX,n,GotoIf($[${TRUNK_MOD}=0]?use-trunk1:use-trunk2)

exten => _1NXXNXXXXXX,n(use-trunk1),Dial(SIP/${EXTEN}@trunk1)
exten => _1NXXNXXXXXX,n,GoTo(fail-to-trunk2)

exten => _1NXXNXXXXXX,n(use-trunk2),Dial(SIP/${EXTEN}@trunk2)
exten => _1NXXNXXXXXX,n,GoTo(failover)

exten => _1NXXNXXXXXX,n(fail-to-trunk2),GotoIf($["${DIALSTATUS}"="ANSWER"]?end)
exten => _1NXXNXXXXXX,n,Dial(SIP/${EXTEN}@trunk1)
exten => _1NXXNXXXXXX,n,GoTo(end)

exten => _1NXXNXXXXXX,n(end),Hangup()

Reload Dialplan

asterisk -rx "dialplan reload"
asterisk -rx "dialplan show outbound-vicidial-lb" | head -20

You should see your dialplan extensions listed without errors.

Step 4: Configure ViciDial Carrier Management

Access the Database Directly

You can configure carriers via the web interface, but for automation and precision, use the database:

mysql -u root -p asterisk

Check existing carriers:

SELECT carrier_id, carrier_name, active, failover_carrier_id FROM vicidial_carrier_log LIMIT 10;

Example output:

+-----------+-----------+--------+---------------------+
| carrier_id| carrier_n | active | failover_carrier_id |
+-----------+-----------+--------+---------------------+
| 1         | Carrier A | Y      | 2                   |
| 2         | Carrier B | Y      | 1                   |
+-----------+-----------+--------+---------------------+

Create Carrier Entries if Missing

INSERT INTO vicidial_carrier_log 
(carrier_id, carrier_name, active, failover_carrier_id, calls_today, concurrent_limit, cost_per_minute)
VALUES 
(1, 'Carrier A - Trunk1', 'Y', 2, 0, 100, 0.02),
(2, 'Carrier B - Trunk2', 'Y', 1, 0, 100, 0.025);

Configure Campaign to Use Multiple Carriers

Update your campaign to use both carriers:

UPDATE vicidial_campaigns 
SET carrier_id = '1,2'
WHERE campaign_id = 'YOUR_CAMPAIGN_ID';

The comma-separated carrier IDs tell ViciDial to use both carriers.

Step 5: Implement Real-Time Trunk Health Monitoring

Create Monitoring Script

This script checks trunk health and updates the database:

cat > /usr/local/bin/check_trunk_health.sh << 'SCRIPT'
#!/bin/bash

# SIP Trunk Health Monitor for ViciDial
# Runs every 5 minutes via cron

LOG_FILE="/var/log/asterisk/trunk_monitor.log"
DB_USER="root"
DB_PASS="your_mysql_password"
DB_NAME="asterisk"

log_message() {
    echo "$(date '+%Y-%m-%d %H:%M:%S') - $1" >> $LOG_FILE
}

# Check trunk1 status via Asterisk
TRUNK1_STATUS=$(asterisk -rx "sip show peer trunk1" 2>/dev/null | grep "Status" | awk '{print $3}')
TRUNK2_STATUS=$(asterisk -rx "sip show peer trunk2" 2>/dev/null | grep "Status" | awk '{print $3}')

log_message "TRUNK1 Status: $TRUNK1_STATUS | TRUNK2 Status: $TRUNK2_STATUS"

# Update database based on trunk status
if [ "$TRUNK1_STATUS" = "OK" ]; then
    mysql -u $DB_USER -p$DB_PASS $DB_NAME -e \
        "UPDATE vicidial_carrier_log SET active='Y' WHERE carrier_id='1';" 2>/dev/null
    log_message "Trunk1 marked as ACTIVE"
else
    mysql -u $DB_USER -p$DB_PASS $DB_NAME -e \
        "UPDATE vicidial_carrier_log SET active='N' WHERE carrier_id='1';" 2>/dev/null
    log_message "Trunk1 marked as INACTIVE - FAILOVER ENGAGED"
fi

if [ "$TRUNK2_STATUS" = "OK" ]; then
    mysql -u $DB_USER -p$DB_PASS $DB_NAME -e \
        "UPDATE vicidial_carrier_log SET active='Y' WHERE carrier_id='2';" 2>/dev/null
    log_message "Trunk2 marked as ACTIVE"
else
    mysql -u $DB_USER -p$DB_PASS $DB_NAME -e \
        "UPDATE vicidial_carrier_log SET active='N' WHERE carrier_id='2';" 2>/dev/null
    log_message "Trunk2 marked as INACTIVE - FAILOVER ENGAGED"
fi
SCRIPT

chmod +x /usr/local/bin/check_trunk_health.sh

Schedule Health Checks via Cron

crontab -e

Add this line:

*/5 * * * * /usr/local/bin/check_trunk_health.sh > /dev/null 2>&1

This runs health checks every 5 minutes.

Step 6: ViciDial Web Interface Configuration

Configure Carriers via Admin Panel

Log into ViciDial at https://your-vicidial-server/vicidial/admin.php
Navigate to Admin → Carriers (or Admin → Carrier Management)
For each carrier, set:
- Carrier Name: Match your dialplan (e.g., "trunk1", "trunk2")
- Failover Carrier: Select the backup carrier
- Active: Yes
- Concurrent Call Limit: 100 (or your trunk capacity)
Go to Campaigns and select your campaign
In Carrier Selection, set to use both carriers (usually "1,2" or select multi-check)

Monitor Real-Time Trunk Status

In the ViciDial interface, check Reports → Carrier Report to see:

Current calls per trunk
Trunk availability
Call success rates
Failover events (if any)

Step 7: Load Balancing Strategy Selection

Strategy 1: Priority-Based Failover (Recommended for Most Setups)

Primary trunk handles all calls; secondary only activates on failure:

[outbound-priority-failover]
exten => _1NXXNXXXXXX,1,NoOp(Priority Failover: Primary then Secondary)
exten => _1NXXNXXXXXX,n,Dial(SIP/${EXTEN}@trunk1,,gM(vicidial-record^${UNIQUEID}))
exten => _1NXXNXXXXXX,n,GotoIf($["${DIALSTATUS}"="ANSWER"]?end)
exten => _1NXXNXXXXXX,n,Dial(SIP/${EXTEN}@trunk2,,gM(vicidial-record^${UNIQUEID}))
exten => _1NXXNXXXXXX,n(end),Hangup()

Advantages: Simpler, works with most carrier billing models

Disadvantages: Doesn't distribute load

Strategy 2: Active-Active Round-Robin (Best for Load Distribution)

Alternates calls between trunks:

[outbound-active-active]
exten => _1NXXNXXXXXX,1,NoOp(Active-Active Load Balance)
exten => _1NXXNXXXXXX,n,Set(CALL_COUNT=${EVAL(${ASTDB(vicidial,call_index)} + 1)})
exten => _1NXXNXXXXXX,n,Set(ASTDB(vicidial,call_index)=${CALL_COUNT})

exten => _1NXXNXXXXXX,n,GotoIf($[${MATH(${CALL_COUNT} % 2)}=0]?try1:try2)

exten => _1NXXNXXXXXX,n(try1),Dial(SIP/${EXTEN}@trunk1)
exten => _1NXXNXXXXXX,n,GotoIf($["${DIALSTATUS}"="ANSWER"]?end:try2)

exten => _1NXXNXXXXXX,n(try2),Dial(SIP/${EXTEN}@trunk2)
exten => _1NXXNXXXXXX,n,GotoIf($["${DIALSTATUS}"="ANSWER"]?end:fallback)

exten => _1NXXNXXXXXX,n(fallback),NoOp(Both trunks failed)
exten => _1NXXNXXXXXX,n(end),Hangup()

Advantages: Even distribution, maximizes trunk utilization

Disadvantages: Requires both trunks to be reliable; some carriers may not support simultaneous calls from same account

Strategy 3: Weighted Load Balancing (For Asymmetric Capacity)

If one trunk has higher capacity, send more calls to it:

[outbound-weighted-lb]
exten => _1NXXNXXXXXX,1,NoOp(Weighted Load: 70% Trunk1, 30% Trunk2)
exten => _1NXXNXXXXXX,n,Set(CALL_COUNT=${EVAL(${ASTDB(vicidial,weighted_count)} + 1)})
exten => _1NXXNXXXXXX,n,Set(ASTDB(vicidial,weighted_count)=${CALL_COUNT})

exten => _1NXXNXXXXXX,n,GotoIf($[${MATH(${CALL_COUNT} % 10)} < 7]?try1:try2)

exten => _1NXXNXXXXXX,n(try1),Dial(SIP/${EXTEN}@trunk1)
exten => _1NXXNXXXXXX,n,GotoIf($["${DIALSTATUS}"="ANSWER"]?end:try2)

exten => _1NXXNXXXXXX,n(try2),Dial(SIP/${EXTEN}@trunk2)
exten => _1NXXNXXXXXX,n(end),Hangup()

Step 8: Testing and Validation

Test Failover Manually

# Test trunk1 directly
asterisk -rx "sip show peer trunk1"

# Force a test call on trunk1
asterisk -rx "originate SIP/trunk1/12125551234 extension 6000@demo"

# Check call status
asterisk -rx "core show calls verbose"

# Simulate trunk1 failure
asterisk -rx "sip set peer trunk1 offline"
asterisk -rx "sip show peers | grep trunk1"

# Expected: trunk1 now shows UNREACHABLE

# Trigger a call - should route to trunk2
asterisk -rx "originate SIP/trunk2/12125551234 extension 6000@demo"

# Restore trunk1
asterisk -rx "sip set peer trunk1 online"

Monitor Real-Time Call Routing

Watch Asterisk logs during a test call:

tail -f /var/log/asterisk/messages | grep -i "dial\|trunk1\|trunk2"

During an outbound call, you should see:

[2024-01-15 10:23:45] VERBOSE[12345]: app_dial.c: TRUNK SELECTION: Attempting trunk1
[2024-01-15 10:23:46] VERBOSE[12345]: app_dial.c: ANSWER on trunk1

Or if failover triggers:

[2024-01-15 10:24:12] VERBOSE[12346]: app_dial.c: TRUNK SELECTION: Attempting trunk1
[2024-01-15 10:24:14] WARNING[12346]: app_dial.c: TRUNK UNAVAILABLE: trunk1
[2024-01-15 10:24:14] VERBOSE[12346]: app_dial.c: TRUNK SELECTION: Attempting trunk2
[2024-01-15 10:24:15] VERBOSE[12346]: app_dial.c: ANSWER on trunk2

Database Verification

Check the carrier log for call routing:

SELECT DATE_FORMAT(call_date, '%Y-%m-%d %H:%i:%S') as call_time, 
       carrier_id, 
       call_duration, 
       status
FROM vicidial_carrier_log 
WHERE call_date > DATE_SUB(NOW(), INTERVAL 1 HOUR)
ORDER BY call_date DESC LIMIT 20;

Step 9: Performance Tuning and Optimization

Adjust Asterisk RTP Settings

For better call quality under high load, edit /etc/asterisk/rtp.conf:

[general]
rtpstart=10000
rtpend=20000
rtcpinterval=5000
dtmfmode=rfc2833

Reload:

asterisk -rx "rtp set debug on"

Optimize Dialplan Performance

Cache trunk status to reduce database queries:

[set-trunk-vars]
exten => s,1,NoOp(Initialize trunk variables)
exten => s,n,Set(TRUNK1_STATUS=${ASTDB(trunk_status,trunk1)})
exten => s,n,Set(TRUNK2_STATUS=${ASTDB(trunk_status,trunk2)})
exten => s,n,Return()

Monitor Asterisk Memory and CPU

# Check Asterisk process resource usage
ps aux | grep asterisk | grep -v grep

# Expected output shows reasonable CPU and MEM usage
# Example: asterisk  2890  1.2 15.4 ...

If CPU exceeds 80%, increase Asterisk priority or reduce dialplan complexity.

Troubleshooting

Symptoms: Calls Failing on Primary Trunk But Secondary Seems OK

Diagnosis:

# Check if failover is actually triggering
asterisk -rx "sip show peers" | grep -E "trunk1|trunk2"

# Look for specific error messages
grep -i "busy\|unavailable\|congestion" /var/log/asterisk/messages | tail -20

# Check MySQL database for carrier status
mysql -u root -p asterisk -e "SELECT carrier_id, active FROM vicidial_carrier_log LIMIT 5;"

Solutions:

Verify SIP connectivity — Retest from Step 1
Check firewall rules — Ensure UDP 5060 is open to trunk IPs
Inspect carrier logs — Request CDR from your provider
Adjust qualify parameters — Reduce qualifyfreq to 30 seconds if detection lag is critical

Symptoms: Both Trunks Show OK but Calls Not Routing

Diagnosis:

# Verify dialplan is loaded
asterisk -rx "dialplan show outbound-vicidial-lb" | head -5

# Check for dialplan syntax errors
asterisk -vvv -g 2>&1 | grep -i "error\|parsing" | tail -10

# Test extension manually
asterisk -rx "originate SIP/trunk1/12125551234 extension 6000@demo"
asterisk -rx "core show calls verbose"

Solutions:

Reload dialplan — asterisk -rx "dialplan reload"
Verify context name — Ensure campaign references correct context
Check extension matching — Confirm called number matches your regex pattern
Review web interface logs — Check /vicidial/admin.php for errors

Symptoms: High Latency or One-Way Audio

Diagnosis:

# Check RTP port range availability
netstat -un | grep "1[0-2][0-9][0-9][0-9]" | wc -l
# Should be less than your rtpend - rtpstart (10,000 in default config)

# Test NAT/codec issues
asterisk -rx "sip show peer trunk1" | grep -E "Codec|NAT"

Solutions:

Add codec restrictions in sip-vicidial.conf:

   allow=ulaw
   disallow=all

Enable SRTP if carrier supports it to reduce latency
Adjust timert1 upward (to 1000ms) for carriers with high latency

Symptoms: Carrier Health Monitoring Script Not Running

Diagnosis:

# Check cron execution
grep check_trunk_health /var/log/syslog | tail -5

# Run script manually to test
/usr/local/bin/check_trunk_health.sh

# Check for errors
cat /var/log/asterisk/trunk_monitor.log | tail -10

Solutions:

Fix script path — Ensure MySQL password is correct
Verify file permissions — chmod 755 /usr/local/bin/check_trunk_health.sh
Check cron service — systemctl restart cron

Symptoms: Calls Alternating Between Trunks Unpredictably

Diagnosis:

# Check trunk status oscillation
for i in {1..10}; do
  asterisk -rx "sip show peer trunk1" | grep Status
  sleep 1
done

# Check Asterisk qualify counters
asterisk -rx "sip show peer trunk1" | grep -E "Qualify|Keepalive"

Solutions:

Increase qualifyfreq — Change from 60 to 120+ seconds to reduce false-positive failures
Increase qualifygap — Change from 3 to 5+ to require more consecutive failures before marking down
Contact carrier — Ask if they're sending periodic disconnects for load balancing

Summary

You now have a production-grade SIP trunk failover and load balancing system for ViciDial with:

✅ Multi-trunk redundancy — Automatic failover to secondary trunks

✅ Real-time health monitoring — Asterisk qualify pings every 60 seconds

✅ Multiple load balancing strategies — Priority-based, round-robin, and weighted options

✅ Database-driven configuration — Persistent carrier management across restarts

✅ Monitoring and alerting — Health check script runs every 5 minutes

✅ Testing procedures — Manual failover testing included

✅ Troubleshooting guides — Common issues and resolutions documented

Key takeaways for production deployment:

Always test failover in non-peak hours before full rollout
Monitor trunk status for 48 hours after deployment to catch edge cases
Keep carrier contact information accessible for emergencies
Run health checks at least every 5 minutes for sub-minute failover detection
Document your specific trunk IPs, usernames, and failover carrier IDs in a secure location
Review logs daily during the first week, then weekly thereafter

Your ViciDial system is now protected against single-trunk failures, ensuring your call center operates reliably even when one carrier experiences outages.

ViciDial IVR Setup with Asterisk — Inbound Call Menus

Moisi Trungu — Thu, 07 May 2026 19:50:34 +0000

ViciDial IVR Setup with Asterisk — Inbound Call Menus

Master building production-grade interactive voice response (IVR) systems in ViciDial using Asterisk dialplans, call routing, and real-time menu logic

Prerequisites

Before starting this tutorial, ensure you have:

ViciDial 2.14+ installed and running (tested on CentOS 7/8 or Ubuntu 18.04+)
Asterisk 13+ compiled with res_agi, res_http_post, and res_voicemail enabled
Root or sudo access to the ViciDial server
A working inbound DID or test extension
MySQL/MariaDB database access with vicidial user permissions
Basic understanding of Asterisk dialplans and ViciDial agent flow
Recorded audio prompts in WAV format (8-bit, 8000 Hz mono recommended)
At least one active campaign in ViciDial with inbound call handling enabled

Understanding ViciDial IVR Architecture

ViciDial's IVR system sits at the intersection of Asterisk dialplans and the ViciDial database. When an inbound call arrives, it follows this path:

DID routes to an Asterisk context (usually defined in extensions-vicidial.conf)
IVR dialplan plays prompts and collects DTMF input
Digits trigger logic that queries ViciDial database or executes AGI scripts
Calls route to campaigns, queues, or agents based on menu selections
Call metadata logs to vicidial_log table

The key difference from traditional Asterisk IVR: ViciDial maintains call state in its database, enabling features like call recording, agent integration, and reporting.

Section 1: Core IVR Dialplan Structure

Creating the Main IVR Context

Your primary IVR context lives in /etc/asterisk/extensions-vicidial.conf. Here's a production-tested template:

[from-vicidial-ivr]
; Main IVR entry point for inbound DID calls
exten => s,1,Answer()
exten => s,n,Set(CALLFILENAME=${UNIQUEID})
exten => s,n,Set(CHANNEL(language)=en)
exten => s,n,NoOp(=== ViciDial IVR Entry - CallID: ${UNIQUEID} ===)
exten => s,n,Set(vicidial_log_id=${SHELL(/usr/share/astguiclient/VICIDIAL_log_insert.agi ${CHANNEL(name)} ${EXTEN} ${CALLERID(num)} ${CALLERID(name)})})
exten => s,n,Goto(ivr_main_menu,s,1)

[ivr_main_menu]
; Main menu - play prompt and collect input
exten => s,1,NoOp(=== Main Menu ===)
exten => s,n,Set(TIMEOUT(digit)=5)
exten => s,n,Set(TIMEOUT(response)=10)
exten => s,n,Background(/var/spool/asterisk/monolithic/recordings/main_menu_prompt)
exten => s,n,WaitExten(2)

; Menu options - route based on DTMF input
exten => 1,1,Goto(sales_queue,s,1)
exten => 2,1,Goto(support_queue,s,1)
exten => 3,1,Goto(billing_queue,s,1)
exten => 0,1,Goto(operator_queue,s,1)

; Default handler - timeout or invalid input
exten => t,1,Playback(invalid_selection)
exten => t,n,Goto(ivr_main_menu,s,1)

exten => i,1,Playback(invalid_selection)
exten => i,n,Goto(ivr_main_menu,s,1)

; Repeat menu option
exten => *,1,Goto(ivr_main_menu,s,1)

[sales_queue]
exten => s,1,NoOp(=== Routing to Sales Queue ===)
exten => s,n,Set(CAMPAIGN_ID=sales_inbound)
exten => s,n,Queue(sales_queue,t,,,300)
exten => s,n,Playback(sorry_all_agents_busy)
exten => s,n,VoiceMail(u1000@vicidial)
exten => s,n,Hangup()

[support_queue]
exten => s,1,NoOp(=== Routing to Support Queue ===)
exten => s,n,Set(CAMPAIGN_ID=support_inbound)
exten => s,n,Queue(support_queue,t,,,300)
exten => s,n,Playback(sorry_all_agents_busy)
exten => s,n,VoiceMail(u1001@vicidial)
exten => s,n,Hangup()

[billing_queue]
exten => s,1,NoOp(=== Routing to Billing Queue ===)
exten => s,n,Set(CAMPAIGN_ID=billing_inbound)
exten => s,n,Queue(billing_queue,t,,,300)
exten => s,n,Playback(sorry_all_agents_busy)
exten => s,n,VoiceMail(u1002@vicidial)
exten => s,n,Hangup()

[operator_queue]
exten => s,1,NoOp(=== Routing to Operator Queue ===)
exten => s,n,Set(CAMPAIGN_ID=operator_inbound)
exten => s,n,Queue(operator_queue,t,,,300)
exten => s,n,Hangup()

Connecting DID to IVR Context

In your inbound route configuration (via Asterisk or ViciDial UI), point the DID to the from-vicidial-ivr context:

[from-trunk]
; Receives calls from SIP trunk
exten => 1234567890,1,Goto(from-vicidial-ivr,s,1)

Alternatively, configure this in /etc/asterisk/sip.conf:

[trunk-provider]
type=peer
host=your.sip.provider
context=from-trunk
insecure=port,invite

Section 2: Database-Driven Menu Logic

Storing Menu Configurations in ViciDial Database

Instead of hardcoding menus in dialplans, use the ViciDial database to define dynamic menus. Create a custom table:

CREATE TABLE vicidial_ivr_menus (
    menu_id INT AUTO_INCREMENT PRIMARY KEY,
    menu_name VARCHAR(50) UNIQUE NOT NULL,
    campaign_id VARCHAR(20),
    prompt_filename VARCHAR(255),
    timeout_seconds INT DEFAULT 10,
    max_attempts INT DEFAULT 3,
    created_date DATETIME DEFAULT CURRENT_TIMESTAMP,
    modified_date DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    active INT DEFAULT 1
) ENGINE=InnoDB;

CREATE TABLE vicidial_ivr_options (
    option_id INT AUTO_INCREMENT PRIMARY KEY,
    menu_id INT NOT NULL,
    digit_pressed VARCHAR(2),
    action_type ENUM('goto_menu', 'queue', 'voicemail', 'hangup', 'agi_script'),
    action_target VARCHAR(100),
    description VARCHAR(100),
    sequence INT,
    FOREIGN KEY (menu_id) REFERENCES vicidial_ivr_menus(menu_id),
    UNIQUE KEY unique_menu_digit (menu_id, digit_pressed)
) ENGINE=InnoDB;

Insert sample menu configuration:

INSERT INTO vicidial_ivr_menus (menu_name, campaign_id, prompt_filename, timeout_seconds, max_attempts) VALUES
('main_menu', 'ivr_main', '/var/spool/asterisk/monolithic/recordings/main_menu', 10, 3),
('billing_submenu', 'billing_inbound', '/var/spool/asterisk/monolithic/recordings/billing_menu', 8, 2);

INSERT INTO vicidial_ivr_options (menu_id, digit_pressed, action_type, action_target, description, sequence) VALUES
(1, '1', 'queue', 'sales_queue', 'Sales Department', 1),
(1, '2', 'queue', 'support_queue', 'Support Department', 2),
(1, '3', 'goto_menu', 'billing_submenu', 'Billing', 3),
(2, '1', 'queue', 'billing_queue', 'Billing Support', 1),
(2, '2', 'voicemail', 'u1002@vicidial', 'Leave Message', 2);

AGI Script for Dynamic Menu Routing

Create /var/lib/asterisk/agi-bin/vicidial_ivr_router.agi:

#!/usr/bin/perl
# ViciDial IVR Router - Dynamic menu handling via database

use strict;
use Asterisk::AGI;
use DBI;
use Data::Dumper;

my $agi = new Asterisk::AGI;

# Database configuration
my $dbhost = 'localhost';
my $dbname = 'asterisk';
my $dbuser = 'vicidial';
my $dbpass = 'your_db_password';

my $dbh = DBI->connect("DBI:mysql:$dbname:$dbhost", $dbuser, $dbpass)
    or die "Cannot connect: $DBI::errstr\n";

# Get variables from Asterisk
my $menu_name = $agi->get_variable('MENU_NAME');
my $digit_pressed = $agi->get_variable('DIGIT_PRESSED');
my $callid = $agi->get_variable('UNIQUEID');

$agi->verbose("IVR Router: Menu=$menu_name, Digit=$digit_pressed", 3);

# Fetch menu configuration
my $menu_query = $dbh->prepare(
    "SELECT menu_id, prompt_filename, timeout_seconds FROM vicidial_ivr_menus WHERE menu_name = ? AND active = 1"
);
$menu_query->execute($menu_name) or die "Query failed: $DBI::errstr\n";
my $menu = $menu_query->fetchrow_hashref();

unless ($menu) {
    $agi->exec('Playback', 'invalid_selection');
    $agi->set_variable('MENU_ACTION', 'retry');
    $dbh->disconnect();
    exit(0);
}

# Fetch option for pressed digit
my $option_query = $dbh->prepare(
    "SELECT action_type, action_target FROM vicidial_ivr_options WHERE menu_id = ? AND digit_pressed = ?"
);
$option_query->execute($menu->{menu_id}, $digit_pressed) or die "Query failed: $DBI::errstr\n";
my $option = $option_query->fetchrow_hashref();

if ($option) {
    $agi->verbose("Executing action: $option->{action_type} -> $option->{action_target}", 3);

    if ($option->{action_type} eq 'queue') {
        $agi->set_variable('QUEUE_NAME', $option->{action_target});
        $agi->set_variable('MENU_ACTION', 'queue');
    } elsif ($option->{action_type} eq 'goto_menu') {
        $agi->set_variable('MENU_NAME', $option->{action_target});
        $agi->set_variable('MENU_ACTION', 'goto_menu');
    } elsif ($option->{action_type} eq 'voicemail') {
        $agi->set_variable('VOICEMAIL_BOX', $option->{action_target});
        $agi->set_variable('MENU_ACTION', 'voicemail');
    } elsif ($option->{action_type} eq 'hangup') {
        $agi->set_variable('MENU_ACTION', 'hangup');
    }
} else {
    $agi->verbose("No action defined for digit: $digit_pressed", 2);
    $agi->set_variable('MENU_ACTION', 'invalid');
}

$dbh->disconnect();
exit(0);

Make the script executable:

chmod 755 /var/lib/asterisk/agi-bin/vicidial_ivr_router.agi
chown asterisk:asterisk /var/lib/asterisk/agi-bin/vicidial_ivr_router.agi

Dialplan Integration with AGI

Update your main dialplan to use the AGI script:

[ivr_dynamic_menu]
exten => s,1,NoOp(=== Dynamic Menu Handler ===)
exten => s,n,Set(TIMEOUT(digit)=5)
exten => s,n,Set(TIMEOUT(response)=${timeout_seconds})
exten => s,n,Background(${prompt_filename})
exten => s,n,WaitExten(2)

exten => 1,1,Set(DIGIT_PRESSED=1)
exten => 1,n,AGI(vicidial_ivr_router.agi)
exten => 1,n,GotoIf($["${MENU_ACTION}"="queue"]?execute_queue,s,1)
exten => 1,n,GotoIf($["${MENU_ACTION}"="goto_menu"]?ivr_dynamic_menu,s,1)
exten => 1,n,GotoIf($["${MENU_ACTION}"="voicemail"]?execute_voicemail,s,1)
exten => 1,n,Hangup()

exten => 2,1,Set(DIGIT_PRESSED=2)
exten => 2,n,AGI(vicidial_ivr_router.agi)
exten => 2,n,GotoIf($["${MENU_ACTION}"="queue"]?execute_queue,s,1)
exten => 2,n,GotoIf($["${MENU_ACTION}"="goto_menu"]?ivr_dynamic_menu,s,1)
exten => 2,n,Hangup()

; Repeat for digits 3-9...

exten => t,1,Playback(invalid_selection)
exten => t,n,Goto(ivr_dynamic_menu,s,1)

exten => i,1,Playback(invalid_selection)
exten => i,n,Goto(ivr_dynamic_menu,s,1)

[execute_queue]
exten => s,1,Queue(${QUEUE_NAME},t,,,300)
exten => s,n,Playback(all_agents_busy)
exten => s,n,Hangup()

[execute_voicemail]
exten => s,1,VoiceMail(${VOICEMAIL_BOX})
exten => s,n,Hangup()

Section 3: Call Recording and ViciDial Integration

Enabling Call Recording in IVR

ViciDial requires explicit recording setup. Add this to your IVR entry context:

[from-vicidial-ivr]
exten => s,1,Answer()
exten => s,n,Set(CALLFILENAME=${STRFTIME(${EPOCH},,%Y%m%d-%H%M%S)}-${UNIQUEID})
exten => s,n,Set(CHANNEL(language)=en)
exten => s,n,MixMonitor(/var/spool/asterisk/monolithic/recordings/ivr/${CALLFILENAME}.wav,b)
exten => s,n,Set(RECORDING_FILE=/var/spool/asterisk/monolithic/recordings/ivr/${CALLFILENAME}.wav)
exten => s,n,NoOp(=== ViciDial IVR Recording: ${RECORDING_FILE} ===)
exten => s,n,Goto(ivr_main_menu,s,1)

Ensure the recording directory exists and has proper permissions:

mkdir -p /var/spool/asterisk/monolithic/recordings/ivr
chown asterisk:asterisk /var/spool/asterisk/monolithic/recordings/ivr
chmod 755 /var/spool/asterisk/monolithic/recordings/ivr

Logging IVR Events to ViciDial Database

Create a dialplan macro to log IVR interactions:

[macro-ivr_log_event]
; Arguments: ${ARG1}=event_type, ${ARG2}=menu_name, ${ARG3}=digit_pressed
exten => s,1,NoOp(=== Logging IVR Event ===)
exten => s,n,AGI(agi://<ivr_logger_script>,${ARG1},${ARG2},${ARG3})

[from-vicidial-ivr-logged]
exten => s,1,Answer()
exten => s,n,Set(CALLFILENAME=${UNIQUEID})
exten => s,n,MixMonitor(/var/spool/asterisk/monolithic/recordings/ivr/${CALLFILENAME}.wav,b)
exten => s,n,Macro(ivr_log_event,ivr_entry,main_menu,)
exten => s,n,Goto(ivr_main_menu,s,1)

[ivr_main_menu]
exten => s,1,Set(TIMEOUT(digit)=5)
exten => s,n,Set(TIMEOUT(response)=10)
exten => s,n,Background(/var/spool/asterisk/monolithic/recordings/main_menu_prompt)
exten => s,n,WaitExten(2)

exten => 1,1,Macro(ivr_log_event,digit_pressed,main_menu,1)
exten => 1,n,Goto(sales_queue,s,1)

exten => 2,1,Macro(ivr_log_event,digit_pressed,main_menu,2)
exten => 2,n,Goto(support_queue,s,1)

exten => t,1,Macro(ivr_log_event,timeout,main_menu,)
exten => t,n,Goto(ivr_main_menu,s,1)

exten => i,1,Macro(ivr_log_event,invalid_input,main_menu,)
exten => i,n,Goto(ivr_main_menu,s,1)

Section 4: Advanced Features — Caller Authentication and Call Routing

Account Lookup with DTMF Entry

Allow customers to enter an account number for routing:

[ivr_account_lookup]
exten => s,1,NoOp(=== Account Lookup ===)
exten => s,n,Set(TIMEOUT(digit)=5)
exten => s,n,Playback(enter_account_number)
exten => s,n,Read(ACCOUNT_NUMBER,please_enter_account)
exten => s,n,AGI(agi://<account_validation>,${ACCOUNT_NUMBER})
exten => s,n,GotoIf($["${ACCOUNT_VALID}"="1"]?lookup_success,s,1)
exten => s,n,Playback(account_not_found)
exten => s,n,Goto(ivr_main_menu,s,1)

[lookup_success]
exten => s,1,NoOp(=== Account Found: ${ACCOUNT_NUMBER} ===)
exten => s,n,Set(CAMPAIGN_ID=${ACCOUNT_CAMPAIGN})
exten => s,n,Queue(${ACCOUNT_QUEUE},t,,,300)
exten => s,n,Playback(sorry_all_agents_busy)
exten => s,n,Hangup()

IVR Call Priority Based on Menu Selection

Route calls with different queue priorities:

[ivr_priority_menu]
exten => s,1,NoOp(=== Priority Menu ===)
exten => s,n,Set(TIMEOUT(digit)=5)
exten => s,n,Set(TIMEOUT(response)=10)
exten => s,n,Background(/var/spool/asterisk/monolithic/recordings/priority_menu)
exten => s,n,WaitExten(2)

; High priority (existing customers)
exten => 1,1,Set(QUEUE_PRIORITY=10)
exten => 1,n,Set(CALL_TYPE=existing_customer)
exten => 1,n,Goto(route_to_queue,s,1)

; Standard priority (new customers)
exten => 2,1,Set(QUEUE_PRIORITY=5)
exten => 2,n,Set(CALL_TYPE=new_customer)
exten => 2,n,Goto(route_to_queue,s,1)

; VIP priority
exten => 3,1,Set(QUEUE_PRIORITY=15)
exten => 3,n,Set(CALL_TYPE=vip_customer)
exten => 3,n,Goto(route_to_queue,s,1)

[route_to_queue]
exten => s,1,NoOp(=== Queue with Priority ${QUEUE_PRIORITY} ===)
exten => s,n,Set(QUEUE_PRIORITY=${QUEUE_PRIORITY})
exten => s,n,Queue(sales_queue,t,,,300)
exten => s,n,Hangup()

Section 5: Troubleshooting IVR Issues

Common Problems and Solutions

IVR Not Receiving DTMF Input

Problem: Menu plays but pressing buttons doesn't work.

Diagnosis:

asterisk -rx "sip set debug on"
asterisk -rx "core set verbose 3"
tail -f /var/log/asterisk/messages | grep -i dtmf

Solution: Check for DTMF mode mismatch. ViciDial typically uses RFC2833 (RTP-based):

[sip-vicidial]
dtmfmode=rfc2833

Restart Asterisk:

systemctl restart asterisk

Calls Dropping After Menu Selection

Problem: Call disconnects after pressing a digit.

Diagnosis: Check dialplan syntax:

asterisk -rx "dialplan reload"
asterisk -rx "dialplan show from-vicidial-ivr" | grep -A5 "exten => 1"

Solution: Verify all Goto() statements reference valid contexts and extensions:

exten => 1,1,Goto(sales_queue,s,1)
; Verify that 'sales_queue' context exists with 's' extension

Recording Files Not Found

Problem: Playback fails with "file not found" error.

Diagnosis:

ls -la /var/spool/asterisk/monolithic/recordings/
asterisk -rx "core set verbose 3" | grep -i playback

Solution: Ensure audio files exist and are in correct format:

# Check format
file /var/spool/asterisk/monolithic/recordings/main_menu_prompt.wav

# Convert if necessary
sox input.wav -b 8 -r 8000 output.wav remix -

# Test playback
asterisk -rx "core set verbose 3"
# In dialplan: Playback(/var/spool/asterisk/monolithic/recordings/test_prompt)

IVR Context Not Loading

Problem: "Unknown context" error when dialing DID.

Diagnosis:

asterisk -rx "dialplan show from-vicidial-ivr"
asterisk -rx "core show functions" | grep Load

Solution: Reload dialplan and verify syntax:

# Check syntax first
asterisk -vvvvvc -g 2>&1 | head -50

# Reload
asterisk -rx "dialplan reload"

# Verify
asterisk -rx "dialplan show from-vicidial-ivr" | head -20

AGI Script Errors

Problem: AGI script returns error, calls fail.

Diagnosis:

tail -f /var/log/asterisk/messages | grep agi
asterisk -rx "agi debug on"

Solution: Check script permissions and Perl dependencies:

chmod 755 /var/lib/asterisk/agi-bin/vicidial_ivr_router.agi
perl -c /var/lib/asterisk/agi-bin/vicidial_ivr_router.agi
cpan install Asterisk::AGI

Queue Timeout Not Working

Problem: Calls queue indefinitely instead of timing out.

Diagnosis:

asterisk -rx "queue show sales_queue"

Solution: Verify queue timeout is set in dialplan:

exten => s,1,Queue(sales_queue,t,,,300)
;                                       ^^^ timeout in seconds

Also check queue definition in queues.conf:

[sales_queue]
member => SIP/agent1
member => SIP/agent2
timeout=20

Database Connection Failures in AGI

Problem: AGI script fails to connect to database.

Diagnosis:

mysql -h localhost -u vicidial -p asterisk -e "SELECT COUNT(*) FROM vicidial_ivr_menus;"

Solution: Verify credentials and permissions:

# From MySQL:
GRANT SELECT ON asterisk.vicidial_ivr_menus TO 'vicidial'@'localhost';
FLUSH PRIVILEGES;

# Test Perl DBI connection
perl -e 'use DBI; my $dbh = DBI->connect("DBI:mysql:asterisk:localhost", "vicidial", "password"); print "OK\n";'

Section 6: Monitoring and Testing Your IVR

Asterisk CLI Commands for IVR Debugging

Monitor active calls:

asterisk -rx "core show calls"

View queue statistics:

asterisk -rx "queue show sales_queue"

Monitor real-time verbose output:

asterisk -rx "core set verbose 3"
tail -f /var/log/asterisk/messages

Test dialplan routing:

asterisk -rx "dialplan eval 1234567890 from-vicidial-ivr s"

Check for syntax errors:

asterisk -rx "dialplan reload"

Manual IVR Testing

From the Asterisk CLI, originate a test call:

asterisk -rx "channel originate SIP/test-agent Extension 1000@from-vicidial-ivr"

Test IVR audio playback:

asterisk -rx "console dial 1000@from-vicidial-ivr"

Accessing ViciDial Logs

View call logs in ViciDial admin:

Navigate to /vicidial/admin.php
Reports → Call Log
Filter by DID or time range

Query call logs directly:

SELECT * FROM vicidial_log WHERE called_number = '1234567890' 
AND call_date >= NOW() - INTERVAL 1 HOUR 
ORDER BY call_date DESC LIMIT 20;

Check agent state during IVR interaction:

SELECT user, status, phone_number, call_date FROM vicidial_agent_log 
WHERE call_date >= NOW() - INTERVAL 1 HOUR 
ORDER BY call_date DESC;

Summary

You now have a comprehensive production-grade ViciDial IVR setup with:

Core IVR dialplans that route inbound calls through menu hierarchies
Database-driven dynamic menus using custom tables for flexible configuration
AGI script integration for intelligent call routing and account lookup
Call recording and logging that integrates with ViciDial's reporting
Advanced features including caller authentication, priority routing, and multi-step menus
Troubleshooting techniques for common IVR issues
Monitoring tools to track and debug call flows in real-time

For production deployment:

Backup your Asterisk configuration before making changes
Test all dialplans with test calls before going live
Monitor logs during the first 24 hours after deployment
Set appropriate queue timeouts based on your staffing
Record audio prompts professionally to improve caller experience
Document custom contexts for future maintenance
Implement call recording for compliance and training
Schedule regular database maintenance on your custom IVR tables

The IVR system scales with ViciDial's queue management, allowing hundreds of simultaneous calls with intelligent routing based on business rules, not just static menus.

Asterisk CDR Analysis — Extract Insights from Call Detail Records

Moisi Trungu — Thu, 07 May 2026 19:50:02 +0000

Asterisk CDR Analysis — Extract Insights from Call Detail Records

Master the complete workflow for analyzing Asterisk Call Detail Records in production ViciDial environments—from database queries to real-time metrics and automated reporting.

Introduction

Call Detail Records (CDRs) are the backbone of telecom operations. Every call passing through your Asterisk system generates raw data that contains critical insights: which numbers convert, where calls fail, which agents perform best, and where money is being wasted. In production ViciDial environments, CDR data accumulates rapidly—thousands of records daily—making manual inspection impossible.

This tutorial walks you through extracting, transforming, and analyzing CDR data using SQL queries, command-line tools, and custom scripts. You'll learn to identify trends, debug call failures, optimize routing, and generate compliance reports. These are skills you need right now if you're managing an Asterisk system under load.

Prerequisites

Before starting, verify you have:

Access to the Asterisk server with root or sudo privileges
MySQL/MariaDB client installed and credentials for the asterisk database
Asterisk CLI access (typically via asterisk -rx command)
ViciDial installation (version 2.14 or later, though techniques apply to 2.12+)
Basic SQL knowledge (SELECT, WHERE, GROUP BY, JOIN)
Understanding of Asterisk dialplan basics (extensions, applications, variables)
Log file access at /var/log/asterisk/messages
Cron or systemd timer for scheduled tasks (optional but recommended)

Verify database connectivity:

mysql -u root -p asterisk -e "SELECT COUNT(*) FROM vicidial_log LIMIT 1;"

If this fails, check /etc/asterisk/asterisk.conf for database credentials and verify the MySQL service is running.

Understanding Asterisk CDR Structure in ViciDial

Native Asterisk CDR vs. ViciDial Logging

Asterisk generates CDRs natively via the CDR module, but ViciDial overlays custom logging on top. Understanding both is essential:

Native Asterisk CDR:

Stored in /var/log/asterisk/cdr-csv/ (CSV format)
Fields: accountcode, src, dst, dcontext, channel, dstchannel, lastapp, lastdata, start, answer, end, duration, billsec, disposition, amaflags, uniqueid, userfield

ViciDial Enhanced Logging:

Stored in MySQL tables: vicidial_log, vicidial_closer_log, vicidial_carrier_log
Includes agent activity, campaign info, lead scoring, inbound routing
Real-time accessible for live dashboards and compliance

Critical ViciDial Tables for CDR Analysis

vicidial_log — The primary call record table:

DESCRIBE vicidial_log;

Key fields:

uniqueid — Unique call identifier (matches Asterisk)
lead_id — ViciDial lead identifier
user — Agent username
campaign_id — Campaign code
call_date — Call timestamp
length_in_sec — Total call duration
talk_sec — Actual conversation time
hold_sec — Time on hold
status — Final disposition (SALE, XFER, NO ANS, etc.)
phone_number — Dialed number
called_number — Actual number called

vicidial_closer_log — Detailed disposition and result data:

DESCRIBE vicidial_closer_log;

Includes agent notes, call outcomes, lead disposition changes.

vicidial_carrier_log — Inbound/outbound carrier metrics (if applicable).

Setting Up Your Analysis Environment

Create a Dedicated Reporting Database User

Don't query production using root. Create a read-only user:

CREATE USER 'cdr_reporter'@'localhost' IDENTIFIED BY 'SecurePassword123!';
GRANT SELECT ON asterisk.* TO 'cdr_reporter'@'localhost';
GRANT SELECT ON asterisk.vicidial_log TO 'cdr_reporter'@'localhost';
GRANT SELECT ON asterisk.vicidial_closer_log TO 'cdr_reporter'@'localhost';
FLUSH PRIVILEGES;

Create Helper Views for Common Queries

Simplify repeated analysis with SQL views:

CREATE VIEW cdr_daily_summary AS
SELECT 
  DATE(call_date) AS call_day,
  campaign_id,
  COUNT(*) AS total_calls,
  SUM(CASE WHEN status IN ('SALE', 'XFER') THEN 1 ELSE 0 END) AS conversions,
  ROUND(SUM(CASE WHEN status IN ('SALE', 'XFER') THEN 1 ELSE 0 END) / COUNT(*) * 100, 2) AS conversion_rate,
  SUM(talk_sec) AS total_talk_seconds,
  ROUND(AVG(talk_sec), 2) AS avg_talk_seconds,
  ROUND(AVG(length_in_sec), 2) AS avg_call_duration
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 30 DAY)
GROUP BY DATE(call_date), campaign_id;

Test the view:

mysql -u cdr_reporter -p asterisk -e "SELECT * FROM cdr_daily_summary LIMIT 10;"

Core CDR Analysis Queries

1. Identifying Failed Calls and Bottlenecks

SELECT 
  call_date,
  user,
  campaign_id,
  phone_number,
  status,
  length_in_sec,
  talk_sec
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
  AND status IN ('NO ANS', 'BUSY', 'NOT CALLABLE', 'DNC')
  AND campaign_id = 'YOUR_CAMPAIGN_ID'
ORDER BY call_date DESC
LIMIT 100;

This reveals which numbers aren't working and why. High "NO ANS" rates might indicate:

Stale lead lists
Calling outside business hours
Network/codec issues on carrier side
Asterisk routing misconfiguration

2. Agent Performance Benchmarking

SELECT 
  user,
  COUNT(*) AS calls_handled,
  SUM(CASE WHEN status IN ('SALE', 'XFER') THEN 1 ELSE 0 END) AS conversions,
  ROUND(SUM(CASE WHEN status IN ('SALE', 'XFER') THEN 1 ELSE 0 END) / COUNT(*) * 100, 2) AS conversion_rate,
  ROUND(AVG(talk_sec), 2) AS avg_talk_sec,
  SUM(talk_sec) AS total_talk_sec,
  ROUND(AVG(length_in_sec), 2) AS avg_call_length
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 7 DAY)
  AND campaign_id = 'YOUR_CAMPAIGN_ID'
  AND user NOT IN ('SYSTEM', 'TRANSFER')
GROUP BY user
ORDER BY conversion_rate DESC;

3. Inbound vs. Outbound Call Analysis

SELECT 
  CASE WHEN direction = 'INBOUND' THEN 'Inbound' ELSE 'Outbound' END AS call_type,
  COUNT(*) AS total_calls,
  COUNT(CASE WHEN status IN ('SALE', 'XFER') THEN 1 END) AS conversions,
  ROUND(COUNT(CASE WHEN status IN ('SALE', 'XFER') THEN 1 END) / COUNT(*) * 100, 2) AS conversion_rate,
  ROUND(AVG(talk_sec), 2) AS avg_talk_sec,
  ROUND(AVG(length_in_sec), 2) AS avg_call_duration
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 30 DAY)
GROUP BY direction;

4. Campaign Performance Comparison

SELECT 
  campaign_id,
  COUNT(*) AS calls,
  SUM(CASE WHEN status IN ('SALE', 'XFER') THEN 1 ELSE 0 END) AS conversions,
  ROUND(SUM(CASE WHEN status IN ('SALE', 'XFER') THEN 1 ELSE 0 END) / COUNT(*) * 100, 2) AS conversion_rate,
  ROUND(AVG(talk_sec), 2) AS avg_talk_sec,
  SUM(talk_sec) / 3600 AS hours_talk_time
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 30 DAY)
  AND user NOT IN ('SYSTEM', 'TRANSFER')
GROUP BY campaign_id
ORDER BY conversion_rate DESC;

5. Detecting Call Quality Issues

SELECT 
  DATE(call_date) AS call_date,
  COUNT(*) AS total_calls,
  COUNT(CASE WHEN length_in_sec < 5 THEN 1 END) AS dropped_early,
  ROUND(COUNT(CASE WHEN length_in_sec < 5 THEN 1 END) / COUNT(*) * 100, 2) AS drop_rate_pct,
  COUNT(CASE WHEN status IN ('NO ANS', 'BUSY') THEN 1 END) AS unreachable,
  ROUND(COUNT(CASE WHEN status IN ('NO ANS', 'BUSY') THEN 1 END) / COUNT(*) * 100, 2) AS unreachable_pct
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY DATE(call_date)
ORDER BY call_date DESC;

Early call drops (< 5 seconds) indicate network issues, bad numbers, or hangup detection problems.

Real-Time Monitoring with Asterisk CLI

Monitor Active Calls

asterisk -rx "core show channels"

Output includes current calls, channel types, and duration. Useful for:

Detecting hung calls
Verifying call routing during testing
Identifying resource exhaustion

Check SIP Registration Status

asterisk -rx "sip show peers"

Ensure all configured trunks and agents are registered. Missing registrations explain inbound call failures.

Monitor CDR Recording

asterisk -rx "cdr show status"

Verify CDR module is active. If output shows "CDR logging disabled," check /etc/asterisk/cdr.conf:

[general]
enable=yes

Then reload:

asterisk -rx "module reload cdr"

Create a Live Dashboard Script

#!/bin/bash
# live_cdr_monitor.sh - Real-time call metrics

while true; do
  clear
  echo "=== ViciDial CDR Live Monitor ==="
  echo "Time: $(date)"
  echo ""

  # Current active calls
  echo "--- Active Calls ---"
  asterisk -rx "core show channels" | grep -E "^SIP|^Agent" | head -5

  # Calls in last hour
  echo ""
  echo "--- Last Hour Metrics ---"
  mysql -u cdr_reporter -p'SecurePassword123!' asterisk -e "
    SELECT 
      COUNT(*) as calls,
      SUM(CASE WHEN status IN ('SALE', 'XFER') THEN 1 ELSE 0 END) as conversions,
      ROUND(SUM(CASE WHEN status IN ('SALE', 'XFER') THEN 1 ELSE 0 END) / COUNT(*) * 100, 2) as conv_rate
    FROM vicidial_log
    WHERE call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR);
  "

  sleep 30
done

Make it executable:

chmod +x live_cdr_monitor.sh
./live_cdr_monitor.sh

Exporting and Processing CDR Data

Export to CSV for Excel/Sheets Analysis

#!/bin/bash
# export_cdr_csv.sh

OUTPUT_FILE="/tmp/cdr_export_$(date +%Y%m%d_%H%M%S).csv"

mysql -u cdr_reporter -p'SecurePassword123!' asterisk \
  -e "SELECT 
        call_date,
        user,
        campaign_id,
        phone_number,
        status,
        length_in_sec,
        talk_sec,
        hold_sec
      FROM vicidial_log
      WHERE call_date >= DATE_SUB(NOW(), INTERVAL 7 DAY)
      ORDER BY call_date DESC;" \
  --batch --skip-column-names | \
  sed 's/\t/,/g' > "$OUTPUT_FILE"

echo "CDR export saved to: $OUTPUT_FILE"
ls -lh "$OUTPUT_FILE"

Run:

chmod +x export_cdr_csv.sh
./export_cdr_csv.sh

Parse Raw Asterisk CDR Files

If you're using CSV CDR storage:

#!/bin/bash
# analyze_csv_cdr.sh

CDR_DIR="/var/log/asterisk/cdr-csv"

# Show recent CDR file structure
head -1 "$CDR_DIR"/*.csv | tail -1

# Count calls by status in last day
find "$CDR_DIR" -name "*.csv" -mtime -1 -exec cat {} \; | \
  awk -F',' '{print $NF}' | sort | uniq -c | sort -rn

Advanced Analysis: Detecting Patterns and Anomalies

Finding Your Best Performing Time Windows

SELECT 
  HOUR(call_date) AS hour_of_day,
  COUNT(*) AS calls,
  SUM(CASE WHEN status IN ('SALE', 'XFER') THEN 1 ELSE 0 END) AS conversions,
  ROUND(SUM(CASE WHEN status IN ('SALE', 'XFER') THEN 1 ELSE 0 END) / COUNT(*) * 100, 2) AS conversion_rate,
  ROUND(AVG(talk_sec), 2) AS avg_talk_sec
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 30 DAY)
  AND DAYOFWEEK(call_date) NOT IN (1, 7)
GROUP BY HOUR(call_date)
ORDER BY conversion_rate DESC;

This reveals peak efficiency hours. Most campaigns see 20-30% variation across day parts. Concentrate calls during peak windows.

Identifying Caller ID Spoofing / Fraud

SELECT 
  phone_number,
  COUNT(*) AS call_count,
  COUNT(DISTINCT user) AS unique_agents,
  COUNT(DISTINCT campaign_id) AS unique_campaigns,
  ROUND(SUM(CASE WHEN status IN ('SALE', 'XFER') THEN 1 ELSE 0 END) / COUNT(*) * 100, 2) AS conversion_rate
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 30 DAY)
GROUP BY phone_number
HAVING call_count > 100
  AND conversion_rate < 5
  AND unique_agents > 5
ORDER BY call_count DESC
LIMIT 20;

Numbers appearing across multiple agents/campaigns with poor conversion and high volume are often fraud or spam sources. Add to DNC list immediately.

Measuring First Call Resolution (FCR)

SELECT 
  vl1.lead_id,
  COUNT(*) AS call_attempts,
  vl1.status AS final_status,
  MIN(vl1.call_date) AS first_call,
  MAX(vl1.call_date) AS last_call,
  ROUND(TIMESTAMPDIFF(HOUR, MIN(vl1.call_date), MAX(vl1.call_date)), 1) AS hours_to_resolution
FROM vicidial_log vl1
WHERE vl1.call_date >= DATE_SUB(NOW(), INTERVAL 30 DAY)
  AND vl1.status IN ('SALE', 'XFER')
GROUP BY vl1.lead_id
HAVING call_attempts > 1
ORDER BY call_attempts DESC
LIMIT 50;

Multiple calls to same lead = poor FCR. High numbers indicate ineffective agent training or bad lead qualification.

Compliance and Call Recording Verification

SELECT 
  call_date,
  user,
  campaign_id,
  phone_number,
  status,
  recording_id,
  talk_sec,
  CASE 
    WHEN recording_id IS NULL THEN 'NO RECORDING'
    WHEN talk_sec > 0 THEN 'RECORDED'
    ELSE 'NO CONVERSATION'
  END AS compliance_status
FROM vicidial_log
WHERE call_date >= DATE_SUB(NOW(), INTERVAL 1 DAY)
  AND status IN ('SALE', 'XFER')
  AND recording_id IS NULL
ORDER BY call_date DESC;

Missing recordings on completed calls violate compliance in many jurisdictions. This query exposes gaps.

Creating Automated Reports and Alerts

Daily Email Report Script

#!/bin/bash
# daily_cdr_report.sh

REPORT_DATE=$(date +"%Y-%m-%d")
RECIPIENT="manager@yourcompany.com"

mysql -u cdr_reporter -p'SecurePassword123!' asterisk > /tmp/daily_report.txt << EOF

SELECT '=== DAILY CDR SUMMARY ===' as report;
SELECT CONCAT('Report Date: ', DATE(NOW()));
SELECT '';

SELECT 'CAMPAIGN PERFORMANCE' as section;
SELECT 
  campaign_id,
  COUNT(*) AS calls,
  SUM(CASE WHEN status IN ('SALE', 'XFER') THEN 1 ELSE 0 END) AS conversions,
  ROUND(SUM(CASE WHEN status IN ('SALE', 'XFER') THEN 1 ELSE 0 END) / COUNT(*) * 100, 2) AS conv_rate
FROM vicidial_log
WHERE DATE(call_date) = DATE(NOW()) - INTERVAL 1 DAY
GROUP BY campaign_id
ORDER BY conv_rate DESC;

SELECT '';
SELECT 'TOP AGENTS' as section;
SELECT 
  user,
  COUNT(*) AS calls,
  SUM(CASE WHEN status IN ('SALE', 'XFER') THEN 1 ELSE 0 END) AS conversions,
  ROUND(AVG(talk_sec), 2) AS avg_talk_sec
FROM vicidial_log
WHERE DATE(call_date) = DATE(NOW()) - INTERVAL 1 DAY
  AND user NOT IN ('SYSTEM', 'TRANSFER')
GROUP BY user
ORDER BY conversions DESC
LIMIT 10;

SELECT '';
SELECT 'CALL QUALITY METRICS' as section;
SELECT 
  COUNT(*) AS total_calls,
  COUNT(CASE WHEN length_in_sec < 5 THEN 1 END) AS dropped_calls,
  ROUND(COUNT(CASE WHEN length_in_sec < 5 THEN 1 END) / COUNT(*) * 100, 2) AS drop_rate
FROM vicidial_log
WHERE DATE(call_date) = DATE(NOW()) - INTERVAL 1 DAY;

EOF

mail -s "ViciDial CDR Report - $REPORT_DATE" "$RECIPIENT" < /tmp/daily_report.txt

Schedule in crontab:

crontab -e

Add:

0 8 * * * /root/daily_cdr_report.sh

Alert on Anomalies

#!/bin/bash
# cdr_anomaly_alert.sh

THRESHOLD_DROP_RATE=15  # Alert if drop rate exceeds 15%
ALERT_EMAIL="ops@yourcompany.com"

DROP_RATE=$(mysql -u cdr_reporter -p'SecurePassword123!' asterisk -se "
  SELECT ROUND(
    COUNT(CASE WHEN length_in_sec < 5 THEN 1 END) / COUNT(*) * 100, 2
  )
  FROM vicidial_log
  WHERE call_date >= DATE_SUB(NOW(), INTERVAL 1 HOUR);
")

if (( $(echo "$DROP_RATE > $THRESHOLD_DROP_RATE" | bc -l) )); then
  echo "ALERT: Call drop rate is $DROP_RATE% (threshold: $THRESHOLD_DROP_RATE%)" | \
    mail -s "CRITICAL: High Call Drop Rate Detected" "$ALERT_EMAIL"
fi

Run every 15 minutes:

*/15 * * * * /root/cdr_anomaly_alert.sh

Troubleshooting CDR Issues

No CDR Records Being Generated

Symptom: asterisk -rx "cdr show status" shows "CDR logging disabled"

Solution:

Check /etc/asterisk/cdr.conf:

[general]
enable=yes

Reload CDR module:

asterisk -rx "module reload cdr"

If using CEL (Channel Event Logging), verify it's enabled:

asterisk -rx "cel show status"

CDR Records Exist But Have NULL Fields

Symptom: Database shows talk_sec, hold_sec as NULL

Reason: Variables not being set in dialplan. Asterisk requires explicit tracking via DIALPLAN() application.

Solution: In /etc/asterisk/extensions-vicidial.conf, ensure:

exten => s,n,Set(CDR(userfield)=${CAMPAIGN_ID})
exten => s,n,Set(CHANNEL(language)=en)

Database Queries Slow / Timeouts

Symptom: Large SELECT queries hang or timeout after 30 seconds

Solution: Add indexes:

ALTER TABLE vicidial_log ADD INDEX idx_call_date (call_date);
ALTER TABLE vicidial_log ADD INDEX idx_campaign_user (campaign_id, user);
ALTER TABLE vicidial_log ADD INDEX idx_status (status);

Verify indexes exist:

mysql -u root -p asterisk -e "SHOW INDEXES FROM vicidial_log;"

Asterisk CLI Commands Failing (Permission Denied)

Symptom: asterisk -rx returns "permission denied"

Solution: Your user isn't in the asterisk group:

usermod -a -G asterisk $USER
newgrp asterisk
asterisk -rx "core show channels"

Or run with sudo:

sudo asterisk -rx "core show channels"

MySQL Connection Issues from Scripts

Symptom: Bash scripts fail with "Access denied for user"

Solution:

Create .my.cnf in home directory:

cat > ~/.my.cnf << EOF
[client]
user=cdr_reporter
password=SecurePassword123!
host=localhost
database=asterisk
EOF

chmod 600 ~/.my.cnf

Now scripts work without -u and -p flags:

mysql -e "SELECT COUNT(*) FROM vicidial_log;"

Recording Files Not Found Despite recording_id in Database

Symptom: recording_id populated but actual audio files missing

Reason: Recordings stored in separate location, deleted by cleanup script, or disabled

Solution:

Check where recordings are stored:

grep -r "monitor_format" /etc/asterisk/*.conf | grep -v "^#"
grep -r "recording" /etc/asterisk/*.conf | grep -v "^#"

Common locations:

ls -lah /var/spool/asterisk/monitor/
ls -lah /var/spool/asterisk/vicidial/recordings/

Check ViciDial settings for recording retention:

mysql asterisk -e "SELECT variable_value FROM system_settings WHERE variable_name = 'recording_archive_days';"

Summary

Asterisk CDR analysis transforms raw call data into actionable business intelligence. The techniques in this tutorial enable you to:

Operational improvements:

Identify and fix call quality issues within hours, not weeks
Optimize agent scheduling around peak conversion windows
Detect fraud and spam sources automatically
Verify compliance with recording and retention regulations

Performance insights:

Benchmark agent and campaign performance objectively
Correlate talk time, hold time, and conversions for each agent
Track FCR (First Call Resolution) to identify training gaps
Monitor real-time metrics with custom dashboards

Cost optimization:

Eliminate unprofitable campaigns and time windows
Reduce waste on unreachable numbers and DNC violations
Optimize trunk routing and carrier selection based on call success rates

Key takeaways:

Start with the raw data: vicidial_log and vicidial_closer_log contain everything you need
Use database views: Create reusable views to simplify repeated analysis
Establish baselines: Know your historical performance before chasing improvements
Automate reporting: Scheduled queries and emails keep stakeholders aligned
Monitor in real-time: Catch problems while they're happening, not in historical reports
Index aggressively: Database performance degrades quickly without proper indexes
Document your queries: Future you will thank present you

The Asterisk CDR system is powerful but requires intentional design and discipline. Start with the core queries provided here, customize them to your specific campaigns and metrics, and gradually build a comprehensive reporting infrastructure. Your operations team and finance department will demand this data sooner or later—better to build it on your schedule.

ViciDial Lead Recycling & List Management Best Practices

Moisi Trungu — Thu, 07 May 2026 19:49:30 +0000

ViciDial Lead Recycling & List Management Best Practices

Master advanced lead recycling strategies, implement intelligent list management workflows, and optimize your ViciDial contact center performance with production-tested configurations and real-world examples.

Prerequisites

Before implementing the strategies in this tutorial, ensure you have:

ViciDial 2.14+ installed and running (2.14.1 or later recommended)
Administrator access to the ViciDial web interface at /vicidial/admin.php
SSH access to the ViciDial server with sudo privileges
MySQL/MariaDB command-line access to the asterisk database
At least one active campaign configured
Basic understanding of ViciDial list structure and lead statuses
Backup of your database before implementing changes

Verify your installation:

mysql -u root -p asterisk -e "SELECT VERSION();"
asterisk -v
grep "vicidial" /etc/asterisk/extensions-vicidial.conf | head -5

Understanding Lead Lifecycle in ViciDial

Lead recycling is the process of requeuing contacts after specific outcomes, allowing multiple attempts with different agents, strategies, or time intervals. Understanding the lead lifecycle is foundational to effective recycling.

Lead Status Codes and Their Meanings

ViciDial uses standardized status codes stored in the vicidial_log table. Key statuses relevant to recycling:

Status Code	Meaning	Recyclable	Default Seconds
NEW	Untouched lead	Yes	0
CALL	Active call	No	N/A
CALLACK	Callback scheduled	No	User-defined
BUSY	Busy signal	Yes	3600
NOANSWER	No answer	Yes	1800
NOTCALLABLE	Invalid number	No	0
BADNUMBER	Bad format	No	0
DNC	Do Not Call	No	0
XFER	Transfer attempted	Yes	900
SALE	Successful	No	0
DEAD	Duplicate/Dead	No	0

The Recycling Decision Tree

Lead Called
    ├─ Answer
    │   ├─ Sale → No recycle
    │   ├─ Not Interested → Recycle (optional)
    │   └─ Wrong Number → No recycle (flag DNC)
    ├─ No Answer
    │   ├─ Retry ≤ 3 → Recycle NOW
    │   ├─ Retry 4-5 → Recycle in 24h
    │   └─ Retry > 5 → Archive
    └─ Busy
        ├─ Retry ≤ 2 → Recycle in 30 min
        └─ Retry > 2 → Recycle in 2h

Database Schema for Recycling Management

Key Tables

Understanding the database structure is essential for custom recycling logic.

-- View current lead status and recycle information
SELECT 
    vl.lead_id,
    vl.phone_number,
    vl.status,
    vl.call_date,
    vl.length_in_sec,
    vl.user,
    vl.campaign_id,
    COUNT(*) as attempt_count
FROM vicidial_log vl
WHERE vl.campaign_id = 'TESTCAMP'
    AND vl.phone_number = '5551234567'
GROUP BY vl.lead_id
ORDER BY vl.call_date DESC;

Core Recycling Tables

vicidial_list — Contains lead master records:

DESC vicidial_list;

Key fields for recycling:

lead_id — Unique identifier
phone_number — Contact number
status — Current lead status
list_id — Associated campaign list
gmt_offset_now — Timezone for callback scheduling
created_date — Lead entry date
last_local_call_time — Last contact attempt timestamp

vicidial_log — Call attempt history:

DESC vicidial_log;

Key fields:

lead_id — Links to vicidial_list
call_date — Attempt timestamp
status — Outcome status
length_in_sec — Duration
user — Agent identifier
campaign_id — Campaign code
phone_number — Dialed number
call_type — INBOUND/OUTBOUND

vicidial_campaign — Campaign configuration:

DESC vicidial_campaign;

Critical recycling fields:

campaign_id — Unique identifier
lead_recycle_method — Recycling strategy
reuse_trunk_level — Trunk reuse behavior
caller_id_method — Caller ID assignment

Configuring Lead Recycling Strategies

Method 1: Campaign-Level Automatic Recycling

Access the campaign configuration and enable recycling globally:

# Log into ViciDial web interface
# Navigate to: Admin → Campaigns → [Your Campaign]
# Look for these settings:

In the database, verify campaign recycling configuration:

SELECT 
    campaign_id,
    lead_recycle_method,
    auto_dial_level,
     voicemail_ext,
    hopper_level
FROM vicidial_campaign
WHERE campaign_id = 'TESTCAMP';

Update recycling method:

UPDATE vicidial_campaign
SET lead_recycle_method = 1
WHERE campaign_id = 'TESTCAMP';

Recycling methods:

0 — No recycling
1 — Standard recycling (uses vicidial_closer_log status settings)
2 — Advanced recycling (requires custom scripting)

Method 2: Status-Based Recycling Rules

Create granular recycling behavior through status configuration in vicidial_closer_log:

-- View current status recycling rules
SELECT 
    campaign_id,
    status,
    recyclable,
    rank
FROM vicidial_closer_log
WHERE campaign_id = 'TESTCAMP'
ORDER BY status;

This table determines which statuses trigger recycling. Insert recycling rules:

-- Recycle NOANSWER leads after 30 minutes
INSERT INTO vicidial_closer_log 
(campaign_id, status, recyclable, seconds_to_next_call, rank)
VALUES 
('TESTCAMP', 'NOANSWER', 'Y', 1800, 10)
ON DUPLICATE KEY UPDATE 
    recyclable = 'Y',
    seconds_to_next_call = 1800;

-- Recycle BUSY after 15 minutes
INSERT INTO vicidial_closer_log 
(campaign_id, status, recyclable, seconds_to_next_call, rank)
VALUES 
('TESTCAMP', 'BUSY', 'Y', 900, 20)
ON DUPLICATE KEY UPDATE 
    recyclable = 'Y',
    seconds_to_next_call = 900;

-- Do NOT recycle DNCPROSPECT
INSERT INTO vicidial_closer_log 
(campaign_id, status, recyclable, seconds_to_next_call, rank)
VALUES 
('TESTCAMP', 'DNCPROSPECT', 'N', 0, 5)
ON DUPLICATE KEY UPDATE 
    recyclable = 'N',
    seconds_to_next_call = 0;

Method 3: Custom Recycling with AGI Scripts

For advanced recycling logic, implement AGI (Asterisk Gateway Interface) scripts. Create a custom recycling script:

cat > /usr/share/astguiclient/agi-bin/recycle_custom.agi << 'EOF'
#!/usr/bin/perl
# Custom Lead Recycling AGI Script for ViciDial
# Place in: /usr/share/astguiclient/agi-bin/

use strict;
use warnings;
use Asterisk::AGI;
use DBI;

my $agi = new Asterisk::AGI;
my $lead_id = $agi->get_variable("lead_id");
my $campaign_id = $agi->get_variable("campaign_id");
my $status = $agi->get_variable("call_status");
my $attempt_count = $agi->get_variable("attempt_count");

# Connect to database
my $dbh = DBI->connect(
    "DBI:mysql:asterisk:localhost",
    "asteriskuser",
    "DBPASSWORD",
    {AutoCommit => 1}
) or die "Cannot connect: $DBI::errstr";

# Recycling logic
my $recycle = 0;
my $recycle_seconds = 0;

if ($status eq 'NOANSWER') {
    if ($attempt_count < 3) {
        $recycle = 1;
        $recycle_seconds = 1800;  # 30 minutes
    } elsif ($attempt_count < 5) {
        $recycle = 1;
        $recycle_seconds = 86400; # 24 hours
    }
} elsif ($status eq 'BUSY') {
    if ($attempt_count < 4) {
        $recycle = 1;
        $recycle_seconds = 900;   # 15 minutes
    }
} elsif ($status eq 'XFER' && $attempt_count < 2) {
    $recycle = 1;
    $recycle_seconds = 3600;     # 1 hour
}

# Update vicidial_list with recycle status
if ($recycle) {
    my $sth = $dbh->prepare(
        "UPDATE vicidial_list 
         SET status = ?, 
             last_local_call_time = DATE_ADD(NOW(), INTERVAL ? SECOND)
         WHERE lead_id = ?"
    );
    $sth->execute('RECYCLE', $recycle_seconds, $lead_id);
    $agi->set_variable("recycled", 1);
}

$dbh->disconnect();
exit(0);
EOF

chmod +x /usr/share/astguiclient/agi-bin/recycle_custom.agi

Call this AGI from your dialplan:

; Add to /etc/asterisk/extensions-vicidial.conf
[vicidial-handler]
exten => s,1,AGI(agi-bin/recycle_custom.agi)
exten => s,n,Hangup()

Implementing Intelligent List Management

List Segmentation Strategy

Separate leads into logical groups for targeted recycling:

-- Create a custom list segmentation view
CREATE OR REPLACE VIEW lead_segments AS
SELECT 
    vl.lead_id,
    vl.phone_number,
    vl.list_id,
    vl.campaign_id,
    CASE 
        WHEN COUNT(*) <= 1 THEN 'FRESH'
        WHEN COUNT(*) BETWEEN 2 AND 3 THEN 'WARM'
        WHEN COUNT(*) > 3 THEN 'HOT'
    END as segment,
    COUNT(*) as attempt_count,
    MAX(vlog.call_date) as last_attempt
FROM vicidial_list vl
LEFT JOIN vicidial_log vlog ON vl.lead_id = vlog.lead_id
GROUP BY vl.lead_id;

-- Query segmented leads
SELECT * FROM lead_segments WHERE campaign_id = 'TESTCAMP' AND segment = 'FRESH';

Automatic List Purging and Archive

Prevent list bloat by archiving old, unrecyclable leads:

-- Archive DEAD leads older than 60 days
CREATE PROCEDURE archive_old_leads()
BEGIN
    INSERT INTO vicidial_list_archive
    SELECT * FROM vicidial_list
    WHERE status IN ('DEAD', 'NOTCALLABLE', 'BADNUMBER')
        AND DATE_SUB(NOW(), INTERVAL 60 DAY) > created_date;

    DELETE FROM vicidial_list
    WHERE status IN ('DEAD', 'NOTCALLABLE', 'BADNUMBER')
        AND DATE_SUB(NOW(), INTERVAL 60 DAY) > created_date;
END;

-- Execute once daily via cron
CALL archive_old_leads();

Add to crontab:

# Run daily at 2 AM
0 2 * * * mysql -u root -p'PASSWORD' asterisk -e "CALL archive_old_leads;"

Dynamic Callback Scheduling

Implement time-zone aware callbacks for optimal contact:

-- Schedule callbacks during business hours (9 AM - 6 PM local time)
UPDATE vicidial_list vl
SET status = 'CALLBACK',
    last_local_call_time = DATE_ADD(
        NOW(),
        INTERVAL (
            (9 - HOUR(CONVERT_TZ(NOW(), 'UTC', 'America/Chicago')))
            + IF(HOUR(CONVERT_TZ(NOW(), 'UTC', 'America/Chicago')) >= 18, 24, 0)
        ) HOUR
    )
WHERE lead_id IN (
    SELECT lead_id FROM vicidial_log 
    WHERE status = 'CALLBACK' 
        AND DATE_SUB(NOW(), INTERVAL 24 HOUR) < call_date
)
AND campaign_id = 'TESTCAMP';

Monitoring and Reporting Lead Recycling

Real-Time Recycling Dashboard Query

Monitor active recycling in real-time:

SELECT 
    COUNT(DISTINCT lead_id) as recyclable_leads,
    SUM(CASE WHEN status = 'RECYCLE' THEN 1 ELSE 0 END) as pending_recycle,
    SUM(CASE WHEN status = 'CALLBACK' THEN 1 ELSE 0 END) as scheduled_callbacks,
    campaign_id,
    MAX(last_local_call_time) as next_available
FROM vicidial_list
WHERE campaign_id = 'TESTCAMP'
    AND status IN ('RECYCLE', 'CALLBACK', 'BUSY', 'NOANSWER')
GROUP BY campaign_id;

Recycling Effectiveness Metrics

Measure recycling performance:

-- Calculate recycle-to-sale conversion rate
SELECT 
    vlog.campaign_id,
    COUNT(DISTINCT vlog.lead_id) as total_attempts,
    COUNT(DISTINCT CASE WHEN vlog.status = 'SALE' THEN vlog.lead_id END) as sales,
    ROUND(
        (COUNT(DISTINCT CASE WHEN vlog.status = 'SALE' THEN vlog.lead_id END) 
        / COUNT(DISTINCT vlog.lead_id) * 100), 2
    ) as conversion_rate_pct,
    AVG(CASE WHEN vlog.status = 'SALE' THEN vlog.length_in_sec ELSE NULL END) as avg_sale_duration
FROM vicidial_log vlog
WHERE vlog.campaign_id = 'TESTCAMP'
    AND vlog.call_date >= DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY vlog.campaign_id;

Lead Aging Report

Identify leads requiring urgency or removal:

-- List leads by age and status
SELECT 
    vl.lead_id,
    vl.phone_number,
    vl.status,
    DATEDIFF(NOW(), vl.created_date) as days_in_system,
    COUNT(vlog.lead_id) as total_attempts,
    MAX(vlog.call_date) as last_attempt,
    DATEDIFF(NOW(), MAX(vlog.call_date)) as days_since_last_attempt
FROM vicidial_list vl
LEFT JOIN vicidial_log vlog ON vl.lead_id = vlog.lead_id
WHERE vl.campaign_id = 'TESTCAMP'
GROUP BY vl.lead_id
HAVING days_in_system > 90
ORDER BY last_attempt DESC;

Configuring Recycling via CLI Commands

Bulk Recycle Operations

Recycle entire batches of leads using command-line operations:

# Recycle all NOANSWER leads from a specific campaign
mysql -u asteriskuser -p'PASSWORD' asterisk << EOF
UPDATE vicidial_list
SET status = 'RECYCLE',
    last_local_call_time = DATE_ADD(NOW(), INTERVAL 1800 SECOND)
WHERE campaign_id = 'TESTCAMP'
    AND status = 'NOANSWER'
    AND DATE_SUB(NOW(), INTERVAL 6 HOUR) > last_local_call_time;
EOF

Check Recycling Queue Status

Verify pending recycled leads:

# Connect to Asterisk CLI and check lead queue
asterisk -rx "agi show" | grep -i recycle

# Monitor ViciDial dialer process
ps aux | grep -E "vici_|astguiclient"

# Check for recycling script errors
tail -50 /var/log/asterisk/messages | grep -i recycle

Force Immediate Recycle

Manually trigger recycle for specific leads:

# SSH to ViciDial server
# Run manual recycle operation
mysql -u asteriskuser -p'PASSWORD' asterisk -e \
"UPDATE vicidial_list 
 SET status = 'RECYCLE', 
     last_local_call_time = NOW() 
 WHERE lead_id = 12345 
 AND campaign_id = 'TESTCAMP';"

# Verify update
mysql -u asteriskuser -p'PASSWORD' asterisk -e \
"SELECT lead_id, phone_number, status, last_local_call_time 
 FROM vicidial_list 
 WHERE lead_id = 12345;"

Advanced: Time-Zone Aware Recycling

Handle multi-zone campaigns properly:

-- Create time-zone aware recycling procedure
DELIMITER $$

CREATE PROCEDURE recycle_by_timezone(
    IN p_campaign_id VARCHAR(20)
)
BEGIN
    DECLARE done INT DEFAULT FALSE;
    DECLARE v_lead_id INT;
    DECLARE v_phone VARCHAR(20);
    DECLARE v_gmt_offset INT;
    DECLARE v_local_hour INT;

    DECLARE cur CURSOR FOR
        SELECT lead_id, phone_number, gmt_offset_now
        FROM vicidial_list
        WHERE campaign_id = p_campaign_id
            AND status IN ('NOANSWER', 'BUSY');

    DECLARE CONTINUE HANDLER FOR NOT FOUND SET done = TRUE;

    OPEN cur;

    read_loop: LOOP
        FETCH cur INTO v_lead_id, v_phone, v_gmt_offset;
        IF done THEN
            LEAVE read_loop;
        END IF;

        -- Calculate local hour for this lead's timezone
        SET v_local_hour = HOUR(DATE_ADD(NOW(), INTERVAL v_gmt_offset HOUR));

        -- Only recycle during business hours (9 AM - 6 PM)
        IF v_local_hour >= 9 AND v_local_hour < 18 THEN
            UPDATE vicidial_list
            SET status = 'RECYCLE',
                last_local_call_time = NOW()
            WHERE lead_id = v_lead_id;
        END IF;
    END LOOP;

    CLOSE cur;
END$$

DELIMITER ;

-- Execute
CALL recycle_by_timezone('TESTCAMP');

Best Practices and Optimization

Lead Fatigue Prevention

Avoid over-calling contacts:

-- Set maximum attempts per lead
ALTER TABLE vicidial_list ADD COLUMN max_attempts INT DEFAULT 5;

-- Prevent recycling beyond maximum
UPDATE vicidial_list
SET status = 'MAXED'
WHERE (SELECT COUNT(*) FROM vicidial_log 
       WHERE lead_id = vicidial_list.lead_id) >= max_attempts
AND campaign_id = 'TESTCAMP';

Quality Assurance

Monitor recycling quality metrics:

#!/bin/bash
# Script: check_recycle_health.sh

CAMPAIGN="TESTCAMP"
THRESHOLD=10  # Alert if recycle queue exceeds 10%

TOTAL_LEADS=$(mysql -N -u asteriskuser -p'PASSWORD' asterisk \
    -e "SELECT COUNT(*) FROM vicidial_list WHERE campaign_id='$CAMPAIGN';")

RECYCLE_LEADS=$(mysql -N -u asteriskuser -p'PASSWORD' asterisk \
    -e "SELECT COUNT(*) FROM vicidial_list WHERE campaign_id='$CAMPAIGN' AND status='RECYCLE';")

PERCENTAGE=$((RECYCLE_LEADS * 100 / TOTAL_LEADS))

echo "Campaign: $CAMPAIGN"
echo "Total Leads: $TOTAL_LEADS"
echo "Recycled Leads: $RECYCLE_LEADS"
echo "Recycle Queue: $PERCENTAGE%"

if [ $PERCENTAGE -gt $THRESHOLD ]; then
    echo "WARNING: Recycle queue exceeds $THRESHOLD% threshold!"
fi

Run via cron:

0 * * * * /usr/local/bin/check_recycle_health.sh | mail -s "Recycle Health Alert" admin@company.com

Database Maintenance

Regular optimization for recycling performance:

#!/bin/bash
# Add to crontab - Run weekly

mysql -u asteriskuser -p'PASSWORD' asterisk << EOF
-- Optimize tables for query performance
OPTIMIZE TABLE vicidial_list;
OPTIMIZE TABLE vicidial_log;
OPTIMIZE TABLE vicidial_closer_log;

-- Rebuild indexes
ANALYZE TABLE vicidial_list;
ANALYZE TABLE vicidial_log;

-- Check for corrupted records
CHECK TABLE vicidial_list;
CHECK TABLE vicidial_log;
EOF

Troubleshooting Lead Recycling Issues

Issue: Leads Not Recycling

Symptom: Status remains unchanged after expected recycle interval.

Diagnosis:

# 1. Check if campaign recycling is enabled
mysql -u asteriskuser -p'PASSWORD' asterisk -e \
"SELECT campaign_id, lead_recycle_method FROM vicidial_campaign WHERE campaign_id='TESTCAMP';"

# Expected output: lead_recycle_method should be 1 or higher

# 2. Verify vicidial_dialer process is running
ps aux | grep vicidial | grep -v grep

# 3. Check for errors in logs
tail -100 /var/log/asterisk/messages | grep -i recycle
grep "ERROR\|recycle\|RECYCLE" /var/log/asterisk/messages | tail -20

Solution:

# Enable recycling in campaign
mysql -u asteriskuser -p'PASSWORD' asterisk -e \
"UPDATE vicidial_campaign SET lead_recycle_method = 1 WHERE campaign_id = 'TESTCAMP';"

# Restart vicidial_dialer service
sudo service vicidial_dialer restart

# Monitor service startup
tail -f /var/log/asterisk/messages | grep vicidial

Issue: Recycled Leads Not Dialing

Symptom: RECYCLE status leads remain in queue but don't get dialed.

Diagnosis:

# Check hopper queue depth
mysql -u asteriskuser -p'PASSWORD' asterisk -e \
"SELECT COUNT(*) as hopper_count FROM vicidial_hopper WHERE campaign_id='TESTCAMP';"

# View next leads to be dialed
mysql -u asteriskuser -p'PASSWORD' asterisk -e \
"SELECT lead_id, phone_number, status, last_local_call_time 
 FROM vicidial_list 
 WHERE campaign_id = 'TESTCAMP' 
 AND status = 'RECYCLE' 
 ORDER BY last_local_call_time 
 LIMIT 10;"

# Check if leads meet recycle time requirement
mysql -u asteriskuser -p'PASSWORD' asterisk -e \
"SELECT lead_id, phone_number, status, 
 TIMESTAMPDIFF(SECOND, NOW(), last_local_call_time) as seconds_until_recycle
 FROM vicidial_list 
 WHERE campaign_id = 'TESTCAMP' 
 AND status = 'RECYCLE' 
 LIMIT 5;"

Solution:

# If leads show negative seconds_until_recycle, they're ready
# Check if hopper is full (capacity issue)

mysql -u asteriskuser -p'PASSWORD' asterisk -e \
"SELECT * FROM vicidial_campaign WHERE campaign_id = 'TESTCAMP';" | grep -E "hopper_level|lead_recycle"

# If hopper is too small, update it
mysql -u asteriskuser -p'PASSWORD' asterisk -e \
"UPDATE vicidial_campaign SET hopper_level = 200 WHERE campaign_id = 'TESTCAMP';"

# Force immediate hopper fill
asterisk -rx "vicidial hopper $CAMPAIGN"

Issue: Excessive Recycling / Lead Fatigue

Symptom: Leads dialed repeatedly in short intervals, agents complaining about repetition.

Diagnosis:

# Identify heavily recycled leads
mysql -u asteriskuser -p'PASSWORD' asterisk -e \
"SELECT 
    vl.lead_id, 
    vl.phone_number, 
    COUNT(*) as call_attempts,
    MIN(vlog.call_date) as first_call,
    MAX(vlog.call_date) as last_call,
    TIMESTAMPDIFF(DAY, MIN(vlog.call_date), MAX(vlog.call_date)) as days_span
 FROM vicidial_list vl
 INNER JOIN vicidial_log vlog ON vl.lead_id = vlog.lead_id
 WHERE vl.campaign_id = 'TESTCAMP'
 GROUP BY vl.lead_id
 HAVING call_attempts > 10
 ORDER BY call_attempts DESC
 LIMIT 20;"

Solution:

# Implement attempt limits in closer_log
mysql -u asteriskuser -p'PASSWORD' asterisk -e \
"INSERT INTO vicidial_closer_log 
 (campaign_id, status, recyclable, seconds_to_next_call, rank)
 VALUES ('TESTCAMP', 'NOANSWER', 'Y', 3600, 10)
 ON DUPLICATE KEY UPDATE seconds_to_next_call = 3600;"

# Archive over-attempted leads
mysql -u asteriskuser -p'PASSWORD' asterisk -e \
"UPDATE vicidial_list vl
 SET status = 'ARCHIVE'
 WHERE vl.campaign_id = 'TESTCAMP'
 AND (SELECT COUNT(*) FROM vicidial_log WHERE lead_id = vl.lead_id) > 8;"

Issue: Recycling Causing Database Lock

Symptom: Database queries slow, connection timeout errors, agents report lag.

Diagnosis:

# Check for long-running queries
mysql -u asteriskuser -p'PASSWORD' asterisk -e "SHOW PROCESSLIST;" | grep -i UPDATE

# Monitor table locks
mysqladmin -u asteriskuser -p'PASSWORD' -i 2 processlist | grep -E "UPDATE|LOCK"

# Check innodb status
mysql -u asteriskuser -p'PASSWORD' asterisk -e "SHOW ENGINE INNODB STATUS\G" | grep -A 20 "LATEST DETECTED DEADLOCK"

Solution:

# Implement batching in recycling procedures
mysql -u asteriskuser -p'PASSWORD' asterisk << EOF
-- Update in smaller chunks to reduce lock time
SET @batch_size = 100;
UPDATE vicidial_list vl
SET status = 'RECYCLE'
WHERE campaign_id = 'TESTCAMP'
    AND status = 'NOANSWER'
    AND lead_id IN (
        SELECT lead_id FROM (
            SELECT lead_id FROM vicidial_list vl2
            WHERE campaign_id = 'TESTCAMP' AND status = 'NOANSWER'
            LIMIT @batch_size
        ) tmp
    );
EOF

# Add index for faster recycling queries
mysql -u asteriskuser -p'PASSWORD' asterisk -e \
"ALTER TABLE vicidial_list ADD INDEX idx_recycle (campaign_id, status, last_local_call_time);"

Summary

ViciDial lead recycling is a sophisticated system requiring careful planning and ongoing optimization. The key takeaways:

Understand Status Flow: Different statuses recycle at different intervals; configure per vicidial_closer_log.
Database-Driven Configuration: Recycling behavior lives in vicidial_list, vicidial_log, and vicidial_campaign tables—customize via SQL.
Time-Zone Awareness: Use gmt_offset_now and last_local_call_time to avoid off-hours contact.
Prevent Lead Fatigue: Set attempt limits, monitor call frequency, and archive over-contacted leads.
Monitor Performance: Track recycle-to-sale conversion rates, queue depths, and recycling effectiveness.
Automate Maintenance: Use cron jobs and stored procedures to archive old leads, optimize tables, and maintain database health.
Test Before Deploying: Always back up your database and test recycling changes in a staging environment first.
Document Custom Logic: If implementing AGI scripts or complex procedures, maintain clear documentation for future maintenance.

Effective lead recycling balances outreach frequency with lead quality, agent productivity, and customer satisfaction. Use the SQL queries and scripts provided here as templates, adjusting parameters for your specific campaign requirements.

Setting Up ViciDial Callbacks (CALLBK) — Agent & Auto

Moisi Trungu — Thu, 07 May 2026 17:16:09 +0000

Setting Up ViciDial Callbacks (CALLBK) — Agent & Auto

Learn how to configure and manage both agent-initiated and automatic callbacks in ViciDial with practical examples, database queries, and production troubleshooting techniques.

Prerequisites

Before implementing callbacks in ViciDial, ensure you have:

ViciDial version 2.14.1 or higher installed and running
Root or sudo access to the ViciDial server
MySQL/MariaDB access with administrative privileges
Asterisk 13+ properly configured with SIP trunks or IAX2
At least one active campaign set up in ViciDial
Working agent logins and active phone extensions
Proper dial permissions configured for agents
Call recording enabled (optional but recommended for compliance)
Outbound carrier/trunk verification — test a manual dial first

Verify your installation:

mysql -u root -p asterisk -e "SELECT version FROM version LIMIT 1;"
asterisk -rx "core show version"
ps aux | grep -E "(asterisk|vicidial)" | grep -v grep

Understanding ViciDial Callbacks

What Are Callbacks?

Callbacks in ViciDial allow agents or the system to schedule calls to contact at a later time. This prevents contact overload, respects time zones, and increases connection rates. ViciDial supports two callback types:

Agent Callbacks (CALLBK) — Agents schedule callbacks directly from the call screen
Auto Callbacks — System automatically reschedules based on lead disposition rules

Why Callbacks Matter

Higher contact rates: Callbacks reach customers when they're available
Better agent efficiency: Agents don't waste time on busy/no-answer leads
Compliance: Schedule calls during business hours per time zone
Lead recovery: Systematically retry abandoned or incomplete interactions
Customer satisfaction: Reduces unwanted interruptions

Key Database Tables

Callbacks are stored primarily in these tables:

vicidial_log — Call history with called_count, status, callback_time
vicidial_callbacks — Dedicated callback records with phone, time, agent
vicidial_carrier_log — Route tracking for callback attempts
vicidial_lists — Campaign list configuration with callback settings

Agent Callbacks Configuration

Step 1: Enable Callbacks in Campaign Settings

Access the ViciDial web interface and navigate to Admin > Campaigns.

Select your campaign
Scroll to Callback Settings
Set Allow Agent Callbacks to YES
Set Callback Time Window (e.g., 1 day, 7 days, 30 days)
Enable Allow Same-Day Callbacks if needed
Set Callback Dial Timeout to 45-60 seconds
Save changes

Verify via database:

SELECT campaign_id, campaign_name, allow_agent_callbacks, callback_time_window 
FROM vicidial_campaigns 
WHERE campaign_name = 'YOUR_CAMPAIGN';

Expected output:

campaign_id | campaign_name | allow_agent_callbacks | callback_time_window
1           | Sales         | Y                     | 1440

Step 2: Configure Agent Callback Permissions

Open /etc/asterisk/extensions-vicidial.conf and locate the agent login context. Add callback-specific permissions:

[from-internal-agent]
exten => *1,1,NoOp(Agent Callback Requested)
exten => *1,2,ViciDial(${CALLERID(num)}|1|${UNIQUEID}|CALLBACK)
exten => *1,3,Hangup()

; Callback with custom time picker
exten => *2,1,NoOp(Schedule Callback with Date/Time)
exten => *2,2,Playback(please-enter-time)
exten => *2,3,Read(callback_minutes|enter-time|||5)
exten => *2,4,ViciDial(${CALLERID(num)}|1|${UNIQUEID}|CALLBACK|${callback_minutes})
exten => *2,5,Hangup()

Step 3: Database Setup for Agent Callbacks

Create callback records directly in the database. ViciDial's agent interface does this automatically, but you should understand the structure:

CREATE TABLE IF NOT EXISTS vicidial_callbacks (
  callback_id INT AUTO_INCREMENT PRIMARY KEY,
  lead_id INT NOT NULL,
  campaign_id INT NOT NULL,
  phone_number VARCHAR(20) NOT NULL,
  callback_time DATETIME NOT NULL,
  callback_date DATE NOT NULL,
  user_id INT,
  agent_id VARCHAR(20),
  status ENUM('PENDING','COMPLETED','FAILED','CANCELLED') DEFAULT 'PENDING',
  notes TEXT,
  created_date DATETIME DEFAULT CURRENT_TIMESTAMP,
  INDEX (callback_time),
  INDEX (campaign_id),
  INDEX (lead_id),
  FOREIGN KEY (lead_id) REFERENCES vicidial_list(lead_id)
);

Insert a test callback record:

INSERT INTO vicidial_callbacks 
(lead_id, campaign_id, phone_number, callback_time, callback_date, agent_id, status, notes)
VALUES 
(1001, 1, '5551234567', DATE_ADD(NOW(), INTERVAL 2 DAY), CURDATE() + INTERVAL 2 DAY, 'AGENT001', 'PENDING', 'Customer requested callback Friday morning');

-- Verify insertion
SELECT * FROM vicidial_callbacks WHERE lead_id = 1001;

Step 4: Agent-Side Configuration

Agents access callbacks via the main call screen at /agc/vicidial.php. When an agent clicks Schedule Callback:

A popup appears requesting callback time
Agent selects date and time (respecting time zone)
Lead is marked with callback disposition
Record inserted into vicidial_callbacks

To ensure agents see the callback button, verify their user privileges:

SELECT user_id, vicidial_login, modify_callbackcallback_time 
FROM vicidial_users 
WHERE vicidial_login = 'AGENT001';

The user must have modify_callback set to Y:

UPDATE vicidial_users 
SET modify_callback = 'Y' 
WHERE vicidial_login = 'AGENT001';

Step 5: Test Agent Callback

Log in as an agent
Receive or dial a test call
Click Schedule Callback button on call screen
Enter callback date/time (e.g., +2 hours)
Click Confirm
Agent screen should show "CALLBACK SCHEDULED"
Check database:

SELECT * FROM vicidial_callbacks 
WHERE agent_id = 'AGENT001' 
ORDER BY created_date DESC LIMIT 1;

Automatic Callback Configuration

Step 1: Configure Disposition Rules

Automatic callbacks trigger based on call dispositions. Configure this in Admin > Dispositions.

Map dispositions to auto-callback actions:

Disposition	Auto-Callback	Wait Time	Notes
NO ANSWER	YES	30 minutes	Retry quickly
BUSY	YES	1 hour	Customer busy
NOT INTERESTED	NO	—	Don't retry
CALLBACK REQUESTED	YES	24 hours	Customer availability
ANSWERING MACHINE	YES	48 hours	Wait before retry

Database configuration:

SELECT disposition_id, disposition, auto_callback_enabled, auto_callback_delay_minutes 
FROM vicidial_dispositions 
WHERE campaign_id = 1;

Update disposition for auto-callback:

UPDATE vicidial_dispositions 
SET auto_callback_enabled = 'Y', auto_callback_delay_minutes = 30 
WHERE disposition = 'NO ANSWER' AND campaign_id = 1;

Step 2: Configure Auto-Callback Script

ViciDial uses scheduled scripts to process callbacks. Edit or create /usr/share/astguiclient/process_callbacks.pl:

#!/usr/bin/perl
# Process Auto-Callbacks - Run every 15 minutes via cron

use strict;
use DBI;
use DateTime;
use DateTime::TimeZone;

my $dsn = 'DBI:mysql:asterisk:localhost';
my $user = 'root';
my $pass = 'PASSWORD';
my $dbh = DBI->connect($dsn, $user, $pass) or die "Cannot connect: $DBI::errstr";

# Fetch pending callbacks due now
my $sql = qq{
    SELECT cb.callback_id, cb.lead_id, cb.phone_number, 
           cb.callback_time, vl.customer_timezone, vl.campaign_id
    FROM vicidial_callbacks cb
    JOIN vicidial_list vl ON cb.lead_id = vl.lead_id
    WHERE cb.status = 'PENDING'
    AND cb.callback_time <= NOW()
    AND cb.callback_time > DATE_SUB(NOW(), INTERVAL 5 MINUTE)
};

my $sth = $dbh->prepare($sql);
$sth->execute();

while (my $row = $sth->fetchrow_hashref()) {
    my $callback_id = $row->{callback_id};
    my $lead_id = $row->{lead_id};
    my $phone = $row->{phone_number};
    my $campaign_id = $row->{campaign_id};

    # Insert into outbound queue
    my $insert_sql = qq{
        INSERT INTO vicidial_log 
        (lead_id, phone_number, campaign_id, status, call_date, 
         user, source_id, callback_id)
        VALUES (?, ?, ?, 'QUEUE', NOW(), 'AUTO-CALLBACK', 'CALLBACK', ?)
    };

    my $insert_sth = $dbh->prepare($insert_sql);
    $insert_sth->execute($lead_id, $phone, $campaign_id, $callback_id);

    # Mark callback as processed
    my $update_sql = qq{
        UPDATE vicidial_callbacks 
        SET status = 'COMPLETED' 
        WHERE callback_id = ?
    };
    my $update_sth = $dbh->prepare($update_sql);
    $update_sth->execute($callback_id);

    print "Processed callback ID: $callback_id for lead $lead_id\n";
}

$sth->finish();
$dbh->disconnect();
exit(0);

Make executable:

chmod +x /usr/share/astguiclient/process_callbacks.pl
chown asterisk:asterisk /usr/share/astguiclient/process_callbacks.pl

Step 3: Schedule Callback Processing via Cron

Add to /etc/cron.d/astguiclient:

# Process auto-callbacks every 15 minutes
*/15 * * * * asterisk /usr/share/astguiclient/process_callbacks.pl >> /var/log/asterisk/callbacks.log 2>&1

# Alternative: every 5 minutes for more responsive system
*/5 * * * * asterisk /usr/share/astguiclient/process_callbacks.pl >> /var/log/asterisk/callbacks.log 2>&1

Restart cron:

systemctl restart cron
# or
systemctl restart crond

Step 4: Configure Asterisk for Callback Delivery

Edit /etc/asterisk/extensions-vicidial.conf to add callback delivery context:

[callback-delivery]
; Callback context - called by ViciDial dialer
exten => s,1,NoOp(Callback delivery for ${CALLBACK_LEAD_ID})
exten => s,2,Set(CALLERID(name)=Your Company)
exten => s,3,Dial(SIP/YOUR_TRUNK/${CALLBACK_PHONE},45,gU(callback-hangup^s^1))
exten => s,4,Hangup()

; Track callback result
[callback-hangup]
exten => s,1,NoOp(Callback hangup - disposition: ${DIALSTATUS})
exten => s,2,NoOp(Returning to IVR/Agent)
exten => s,3,Return()

Reload Asterisk:

asterisk -rx "dialplan reload"

Step 5: Configure Callback Time Window & DNC

Prevent callbacks outside business hours:

-- Set campaign callback hours: 8am-6pm
UPDATE vicidial_campaigns 
SET callback_start_hour = 8, 
    callback_end_hour = 18,
    callback_respect_timezone = 'Y'
WHERE campaign_id = 1;

-- Verify
SELECT campaign_id, callback_start_hour, callback_end_hour, 
       callback_respect_timezone 
FROM vicidial_campaigns 
WHERE campaign_id = 1;

Add DNC (Do Not Call) exceptions for callbacks:

-- Ensure callbacks can override DNC
UPDATE vicidial_campaigns 
SET callback_ignore_dnc = 'Y' 
WHERE campaign_id = 1;

Callback Delivery & Queuing

Step 1: Configure Callback Queue

ViciDial uses a dedicated callback queue. Configure in /etc/asterisk/queues.conf:

[callback-queue]
strategy = ringall
timeout = 45
retry = 3
weight = 0
autopause = no
announce-frequency = 0
announce-holdtime = no
maxlen = 500

Step 2: Callback Outbound Route

Configure outbound routing for callbacks. In /etc/asterisk/extensions-vicidial.conf:

[vicidial-callback-out]
exten => _X.,1,NoOp(Callback outbound route)
exten => _X.,2,Set(CALLBACK_MODE=yes)
exten => _X.,3,Set(CALLERID(name)=Support Team)
exten => _X.,4,Dial(SIP/YOUR_CARRIER/${EXTEN}@carrier.com,45,gU(log-callback^s^1))
exten => _X.,5,Goto(handle-callback-fail,${EXTEN},1)
exten => _X.,6,Hangup()

[handle-callback-fail]
exten => _X.,1,NoOp(Callback failed - Status: ${DIALSTATUS})
exten => _X.,2,Set(callback_status=${DIALSTATUS})
exten => _X.,3,Hangup()

[log-callback]
exten => s,1,NoOp(Callback connected)
exten => s,2,Return()

Step 3: ViciDial Dialer Configuration

Configure the ViciDial dialer to handle callbacks. Edit /etc/asterisk/sip-vicidial.conf:

[vicidial-callback-trunk]
type=peer
host=YOUR_CARRIER_IP
username=YOUR_USERNAME
secret=YOUR_PASSWORD
context=vicidial-callback-out
dtmfmode=rfc2833
relaxdtmf=yes
qualify=yes
qualifyfreq=60
insecure=port,invite
directmedia=no

Reload SIP:

asterisk -rx "sip reload"

Callback Status Tracking

Monitor Callback Queue

asterisk -rx "queue show callback-queue"

Expected output:

callback-queue has 5 calls (max unlimited) in 'ringall' strategy
No members are available
  (1 call waiting)

Query Callback Status

Real-time callback status:

SELECT 
    cb.callback_id,
    cb.lead_id,
    vl.phone_number,
    cb.callback_time,
    cb.status,
    cb.agent_id,
    vl.campaign_id
FROM vicidial_callbacks cb
JOIN vicidial_list vl ON cb.lead_id = vl.lead_id
WHERE cb.status = 'PENDING'
AND cb.callback_time <= NOW()
ORDER BY cb.callback_time ASC;

Callback completion report:

SELECT 
    DATE(cb.created_date) as callback_date,
    COUNT(*) as total_callbacks,
    SUM(CASE WHEN cb.status = 'COMPLETED' THEN 1 ELSE 0 END) as completed,
    SUM(CASE WHEN cb.status = 'FAILED' THEN 1 ELSE 0 END) as failed,
    SUM(CASE WHEN cb.status = 'PENDING' THEN 1 ELSE 0 END) as pending,
    ROUND(100 * SUM(CASE WHEN cb.status = 'COMPLETED' THEN 1 ELSE 0 END) / COUNT(*), 2) as completion_rate
FROM vicidial_callbacks cb
GROUP BY DATE(cb.created_date)
ORDER BY callback_date DESC;

Update Callback Status Manually

If a callback fails and needs rescheduling:

UPDATE vicidial_callbacks 
SET callback_time = DATE_ADD(NOW(), INTERVAL 24 HOUR),
    status = 'PENDING'
WHERE callback_id = 42;

Cancel a callback:

UPDATE vicidial_callbacks 
SET status = 'CANCELLED'
WHERE callback_id = 42;

Advanced Configuration

Time Zone-Aware Callbacks

ViciDial respects customer time zones for callback scheduling. Configure in campaign:

UPDATE vicidial_campaigns 
SET callback_respect_timezone = 'Y' 
WHERE campaign_id = 1;

Set customer timezone in vicidial_list:

UPDATE vicidial_list 
SET customer_timezone = 'America/Chicago' 
WHERE lead_id = 1001;

Supported time zones (see /usr/share/zoneinfo/):

America/New_York
America/Chicago
America/Denver
America/Los_Angeles
America/Anchorage
Pacific/Honolulu
etc.

Callback with Voicemail Fallback

Configure fallback to voicemail if callback fails:

[vicidial-callback-out]
exten => _X.,1,NoOp(Callback with voicemail fallback)
exten => _X.,2,Set(CALLERID(name)=Support)
exten => _X.,3,Dial(SIP/TRUNK/${EXTEN},45,gU(callback-hangup^s^1))
exten => _X.,4,Goto(voicemail-fallback,${EXTEN},1)
exten => _X.,5,Hangup()

[voicemail-fallback]
exten => _X.,1,NoOp(Callback failed, attempting voicemail)
exten => _X.,2,VoiceMail(${EXTEN}@default)
exten => _X.,3,Hangup()

Callback with IVR Menu

Route callbacks through an IVR before agent delivery:

[callback-ivr]
exten => s,1,NoOp(Callback IVR)
exten => s,2,Playback(welcome-callback)
exten => s,3,Set(TIMEOUT(digit)=5)
exten => s,4,Set(TIMEOUT(response)=10)
exten => s,5,Read(menu_choice|please-enter-department,1,,3)
exten => s,6,Goto(route-callback,${menu_choice},1)
exten => s,7,Hangup()

[route-callback]
exten => 1,1,Queue(sales-callbacks)
exten => 2,1,Queue(support-callbacks)
exten => 3,1,Queue(billing-callbacks)
exten => i,1,Playback(invalid)
exten => i,2,Goto(callback-ivr,s,1)

Restrict Callback Frequency

Prevent callback storms by tracking attempt frequency:

SELECT 
    lead_id, 
    phone_number,
    COUNT(*) as callback_count,
    MAX(created_date) as last_callback
FROM vicidial_callbacks
WHERE created_date >= DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY lead_id
HAVING callback_count > 5;

Block leads with excessive callbacks:

UPDATE vicidial_list 
SET status = 'TEMP_BLOCK' 
WHERE lead_id IN (
    SELECT lead_id FROM vicidial_callbacks
    WHERE created_date >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
    GROUP BY lead_id
    HAVING COUNT(*) > 3
);

Troubleshooting

Callbacks Not Triggering

Symptom: Callbacks remain in PENDING status past their scheduled time.

Solution:

Verify cron job is running:

ps aux | grep process_callbacks.pl

Check cron logs:

grep process_callbacks /var/log/syslog
# or
tail -50 /var/log/asterisk/callbacks.log

Verify script has correct permissions:

ls -la /usr/share/astguiclient/process_callbacks.pl
# Should show: -rwxr-xr-x asterisk:asterisk

Manually test the script:

sudo -u asterisk /usr/share/astguiclient/process_callbacks.pl
echo $?  # Should return 0 on success

Check MySQL connectivity from callback script:

mysql -u root -p asterisk -e "SELECT COUNT(*) FROM vicidial_callbacks WHERE status='PENDING';"

Callbacks Queued But Not Dialing

Symptom: Callbacks appear in database but agents don't receive calls.

Solution:

Check Asterisk dialplan loaded:

asterisk -rx "dialplan show callback-delivery"

Verify SIP trunk is registered:

asterisk -rx "sip show peers"

Check channel availability:

asterisk -rx "core show channels"

Review Asterisk CLI logs in real-time:

asterisk -rn

Then trigger a callback and watch output.

Test trunk dial directly:

asterisk -rx "channel originate SIP/TRUNK/5551234567 extension test@from-internal"

Callbacks Showing Wrong Time

Symptom: Callbacks display or execute at incorrect times.

Solution:

Verify server timezone:

timedatectl status
date

Verify MySQL timezone:

SELECT @@global.time_zone, @@session.time_zone;

Should show system timezone. If showing SYSTEM, set explicitly:

SET GLOBAL time_zone = 'America/Chicago';

Verify ViciDial campaign timezone setting:

SELECT callback_respect_timezone, campaign_timezone 
FROM vicidial_campaigns 
WHERE campaign_id = 1;

Check individual lead timezone:

SELECT lead_id, customer_timezone 
FROM vicidial_list 
WHERE lead_id = 1001;

Callback Permission Denied

Symptom: Agents click Schedule Callback but get permission error.

Solution:

Verify agent user has callback permission:

SELECT user_id, vicidial_login, modify_callback, campaign_id 
FROM vicidial_users 
WHERE vicidial_login = 'AGENT001';

Enable callback permission:

UPDATE vicidial_users 
SET modify_callback = 'Y' 
WHERE vicidial_login = 'AGENT001';

Verify campaign allows agent callbacks:

SELECT allow_agent_callbacks 
FROM vicidial_campaigns 
WHERE campaign_id = 1;

If disabled, enable:

UPDATE vicidial_campaigns 
SET allow_agent_callbacks = 'Y' 
WHERE campaign_id = 1;

Reload ViciDial web interface (clear browser cache).

High Callback Failure Rate

Symptom: Many callbacks marked FAILED status.

Solution:

Review failure reasons:

SELECT 
    COUNT(*) as failed_count,
    dialstatus,
    disposition
FROM vicidial_log 
WHERE source_id = 'CALLBACK'
AND call_date >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
AND status = 'FAILED'
GROUP BY dialstatus, disposition;

Check trunk capacity:

asterisk -rx "core show channels brief" | wc -l

Verify carrier is accepting calls:

asterisk -rx "sip show peers" | grep YOUR_TRUNK

Review Asterisk full logs:

tail -200 /var/log/asterisk/full
grep -i callback /var/log/asterisk/full | tail -50

Check for SIP errors (401 UNAUTHORIZED, 403 FORBIDDEN):

grep -i "^.*SIP/.*401\|^.*SIP/.*403" /var/log/asterisk/full | tail -20

If carrier rejects, verify credentials:

# In /etc/asterisk/sip-vicidial.conf, check:
# - username
# - secret (password)
# - host IP
# - port (usually 5060)

Database Growing Too Large

Symptom: vicidial_callbacks table consuming excessive disk space.

Solution:

Archive old completed callbacks:

-- Create archive table
CREATE TABLE vicidial_callbacks_archive LIKE vicidial_callbacks;

-- Move callbacks older than 90 days
INSERT INTO vicidial_callbacks_archive 
SELECT * FROM vicidial_callbacks 
WHERE created_date < DATE_SUB(NOW(), INTERVAL 90 DAY)
AND status IN ('COMPLETED', 'FAILED', 'CANCELLED');

-- Delete archived records
DELETE FROM vicidial_callbacks 
WHERE created_date < DATE_SUB(NOW(), INTERVAL 90 DAY)
AND status IN ('COMPLETED', 'FAILED', 'CANCELLED');

-- Optimize table
OPTIMIZE TABLE vicidial_callbacks;

Add automatic cleanup to cron:

0 2 * * * asterisk mysql -u root -p PASSWORD asterisk -e "DELETE FROM vicidial_callbacks WHERE created_date < DATE_SUB(NOW(), INTERVAL 120 DAY) AND status IN ('COMPLETED','FAILED','CANCELLED'); OPTIMIZE TABLE vicidial_callbacks;" >> /var/log/asterisk/cleanup.log 2>&1

Summary

ViciDial callbacks—both agent-initiated and automatic—significantly improve contact rates and customer satisfaction when properly configured. This guide covered:

Key Takeaways:

Agent Callbacks allow agents to schedule follow-up calls with customers at their preferred times, improving conversions and reducing contact resistance.
Auto-Callbacks automatically retry failed calls based on disposition rules, maximizing lead recovery without manual agent intervention.
Database structure centers on the vicidial_callbacks table, with records linked to leads, campaigns, and agents for comprehensive tracking.
Asterisk dialplan delivers callbacks through dedicated contexts, supporting SIP trunks, time-zone awareness, and voicemail fallback.
Cron-based processing triggers callbacks at scheduled times, requiring proper permissions and MySQL connectivity to function reliably.
Troubleshooting focuses on verifying permissions, database records, cron execution, timezone settings, and carrier connectivity.

Best Practices:

Always test callbacks with a single lead before enabling for entire campaign
Monitor callback completion rates weekly via SQL queries
Set reasonable callback windows (e.g., 1-30 days) to avoid lead staleness
Respect time zones—configure per-lead or per-campaign as needed
Archive old callback records monthly to maintain database performance
Document your dialplan changes and script modifications for future maintenance
Review Asterisk logs (/var/log/asterisk/full) during troubleshooting

Next Steps:

Deploy the process_callbacks.pl script with cron scheduling
Configure callback rules for your top 2-3 dispositions
Train agents on the callback button and best practices
Monitor first week for issues via database queries and Asterisk CLI
Adjust callback timing based on success rates

Proper callback configuration transforms ViciDial from a simple dialer into an intelligent lead management system that works 24/7 on behalf of your agents.

ViciDial Agent Performance Reports Explained

Moisi Trungu — Thu, 07 May 2026 17:15:37 +0000

ViciDial Agent Performance Reports Explained

Master ViciDial agent performance metrics, learn how to generate actionable reports, and understand the data structures that power contact center analytics

Prerequisites

Before working with ViciDial agent performance reports, you'll need:

A running ViciDial installation (v2.13 or later recommended)
Root or sudo access to your ViciDial server
Database access credentials for the asterisk database
Understanding of MySQL/MariaDB basics
Familiarity with ViciDial agent roles and campaigns
SSH access to query logs and run CLI commands
Basic PHP knowledge for custom report modifications

Verify your installation with:

asterisk -rx "core show version"
mysql -u root -p -e "USE asterisk; SHOW TABLES LIKE 'vicidial%';" | head -20

Understanding ViciDial Performance Metrics

Core Performance Indicators

ViciDial tracks agent performance across multiple dimensions. The primary metrics you'll encounter are:

Talk Time (Handle Time): Duration of actual conversation
Wrap-Up Time: Post-call work time before next call
Calls Handled: Total number of calls worked
Calls Connected: Calls that reached a live person
Call Completion Rate: Successful completions vs. total attempts
Average Handle Time (AHT): Combined talk time and wrap-up time
Pause Time: Idle time between calls
Not Ready Time: Time logged out or unavailable

These metrics exist across three primary tables in the ViciDial database:

vicidial_log - Individual call records
vicidial_closer_log - Detailed agent call details
vicidial_agent_log - Agent login/logout sessions

Database Schema Overview

The three core tables structure agent performance data:

-- vicidial_log: Master call records
SELECT 
    call_date,
    caller_id_number,
    called_party_number,
    agent_only,
    talk_sec,
    wait_sec,
    status
FROM vicidial_log 
WHERE call_date >= DATE(NOW()) - INTERVAL 7 DAY
LIMIT 5;

-- vicidial_closer_log: Agent-specific call handling
SELECT
    call_date,
    user,
    call_length,
    pause_sec,
    status,
    lead_id,
    list_id
FROM vicidial_closer_log
WHERE call_date >= DATE(NOW()) - INTERVAL 1 DAY
AND user = 'AGENT001'
ORDER BY call_date DESC;

-- vicidial_agent_log: Login sessions and availability
SELECT
    agent_log_id,
    user,
    server_ip,
    event_time,
    event_type,
    pause_type,
    status
FROM vicidial_agent_log
WHERE user = 'AGENT001'
AND event_time >= DATE(NOW()) - INTERVAL 1 DAY
ORDER BY event_time DESC;

Accessing Built-in ViciDial Reports

Admin Dashboard Reports

The ViciDial admin interface provides quick-access reports. Navigate to:

http://your-vicidial-server/vicidial/admin.php?action=show_reports

From here, access:

Agent Performance Report - Real-time agent metrics
Daily Performance Report - Agent stats by day
Call Center Performance - Campaign-level analytics
Detailed Call Log - Individual call records

Agent Performance Report Navigation

Log into the admin interface and follow:

Reports > Agent Performance > Select Date Range > Select Agents

This displays:

Login/logout times
Total calls handled
Average talk time
Wrap-up time
Call outcomes
Customer satisfaction scores (if configured)

Building Custom Performance Reports

Basic Agent Daily Performance Query

Create a custom report for a specific date and agent:

SELECT 
    user AS agent_name,
    DATE(call_date) AS call_date,
    COUNT(*) AS total_calls,
    SUM(CASE WHEN talk_sec > 0 THEN 1 ELSE 0 END) AS connected_calls,
    ROUND(AVG(talk_sec), 2) AS avg_talk_sec,
    SUM(talk_sec) AS total_talk_sec,
    ROUND(AVG(wait_sec), 2) AS avg_wait_sec,
    SUM(pause_sec) / 60 AS total_pause_min,
    COUNT(DISTINCT(DATE_FORMAT(call_date, '%Y-%m-%d %H:00:00'))) AS hours_worked
FROM vicidial_closer_log
WHERE user = 'AGENT001'
AND call_date >= '2024-01-15 00:00:00'
AND call_date < '2024-01-16 00:00:00'
GROUP BY user, DATE(call_date);

Expected output:

agent_name | call_date  | total_calls | connected_calls | avg_talk_sec | total_talk_sec | avg_wait_sec | total_pause_min | hours_worked
AGENT001   | 2024-01-15 | 87          | 67              | 312.45       | 27183          | 12.56        | 45.33           | 8

Advanced Performance Report with Status Breakdown

Generate a detailed report showing call outcome distribution:

SELECT 
    u.user,
    u.full_name,
    DATE(vcl.call_date) AS work_date,
    COUNT(*) AS total_calls,
    ROUND(COUNT(*) / (SELECT COUNT(*) FROM vicidial_closer_log 
        WHERE user = u.user AND DATE(call_date) = DATE(vcl.call_date)) * 100, 2) AS call_pct,
    SUM(CASE WHEN vcl.talk_sec > 0 THEN 1 ELSE 0 END) AS connected_calls,
    ROUND(AVG(vcl.talk_sec), 1) AS avg_talk_sec,
    SUM(vcl.talk_sec) AS total_talk_sec,
    ROUND(AVG(vcl.wait_sec), 1) AS avg_wait_sec,
    GROUP_CONCAT(DISTINCT vcl.status ORDER BY vcl.status) AS call_statuses
FROM vicidial_closer_log vcl
INNER JOIN vicidial_users u ON vcl.user = u.user
WHERE DATE(vcl.call_date) = '2024-01-15'
AND vcl.user IN ('AGENT001', 'AGENT002', 'AGENT003')
GROUP BY u.user, u.full_name, DATE(vcl.call_date)
ORDER BY total_calls DESC;

Call Outcome Breakdown Report

Understand how agents handle different call statuses:

SELECT 
    user,
    status,
    COUNT(*) AS count,
    ROUND(COUNT(*) / SUM(COUNT(*)) OVER (PARTITION BY user) * 100, 2) AS pct_of_total,
    ROUND(AVG(talk_sec), 1) AS avg_talk_time,
    SUM(talk_sec) AS total_talk_time
FROM vicidial_closer_log
WHERE DATE(call_date) = CURDATE()
AND user = 'AGENT001'
GROUP BY user, status
ORDER BY count DESC;

Common statuses include:

SALE - Successful sale
XFER - Transfer
CALLACK - Callback scheduled
BUSY - Line busy
NOANSWER - No answer
DROP - Dropped call
ABANDOND - Abandoned by caller
DNC - Do Not Call

Working with Agent Session Logs

Agent Activity Timeline

Track an agent's actual activities throughout their shift:

SELECT 
    aal.event_time,
    aal.event_type,
    aal.status,
    aal.pause_type,
    aal.data,
    aal.server_ip
FROM vicidial_agent_log aal
WHERE aal.user = 'AGENT001'
AND aal.event_time >= '2024-01-15 08:00:00'
AND aal.event_time < '2024-01-15 17:00:00'
ORDER BY aal.event_time ASC;

Event types include:

LOGIN - Agent logged in
LOGOUT - Agent logged out
PAUSE - Entered pause (with pause_type indicating reason)
READY - Returned to ready state
DISPO - Called disposition
XFER - Transfer initiated
3WAYCONF - 3-way conference

Calculate Agent Availability Percentage

Determine what percentage of an agent's shift was spent ready for calls:

SELECT 
    user,
    DATE(event_time) AS work_date,
    TIMEDIFF(
        MAX(CASE WHEN event_type = 'LOGOUT' THEN event_time END),
        MIN(CASE WHEN event_type = 'LOGIN' THEN event_time END)
    ) AS total_session_time,
    SEC_TO_TIME(
        SUM(CASE 
            WHEN event_type = 'PAUSE' THEN 
                TIMESTAMPDIFF(SECOND, event_time, 
                    LEAD(event_time) OVER (PARTITION BY user ORDER BY event_time))
            ELSE 0 
        END)
    ) AS total_pause_time,
    ROUND(
        (1 - SUM(CASE 
            WHEN event_type = 'PAUSE' THEN 
                TIMESTAMPDIFF(SECOND, event_time, 
                    LEAD(event_time) OVER (PARTITION BY user ORDER BY event_time))
            ELSE 0 
        END) / TIMESTAMPDIFF(SECOND,
            MIN(CASE WHEN event_type = 'LOGIN' THEN event_time END),
            MAX(CASE WHEN event_type = 'LOGOUT' THEN event_time END))
        ) * 100, 2
    ) AS availability_pct
FROM vicidial_agent_log
WHERE DATE(event_time) = '2024-01-15'
AND user = 'AGENT001'
GROUP BY user, DATE(event_time);

Performance Report Dashboard in PHP

Creating a Custom Report Dashboard

Create a PHP script at /var/www/html/vicidial/reports/agent_performance.php:

<?php
// agent_performance.php - Custom Agent Performance Report
session_start();
require_once('/var/www/html/vicidial/admin/dbconnect.php');

// Verify admin login
if ($_SESSION['admin_user'] != 'Y') {
    header('Location: /vicidial/index.php');
    exit;
}

$agent_id = isset($_GET['agent_id']) ? sanitize($_GET['agent_id']) : '';
$report_date = isset($_GET['date']) ? sanitize($_GET['date']) : date('Y-m-d');

if (empty($agent_id)) {
    die('Agent ID required');
}

// Connect to ViciDial database
$mysqli = new mysqli($db_host, $db_user, $db_pass, $db_name);
if ($mysqli->connect_error) {
    die('Database connection failed: ' . $mysqli->connect_error);
}

// Fetch agent details
$agent_query = "SELECT user, full_name, user_level FROM vicidial_users WHERE user = ?";
$stmt = $mysqli->prepare($agent_query);
$stmt->bind_param('s', $agent_id);
$stmt->execute();
$agent_result = $stmt->get_result()->fetch_assoc();

if (!$agent_result) {
    die('Agent not found');
}

// Main performance metrics
$perf_query = "
    SELECT 
        user,
        COUNT(*) AS total_calls,
        SUM(CASE WHEN talk_sec > 0 THEN 1 ELSE 0 END) AS connected_calls,
        ROUND(AVG(talk_sec), 2) AS avg_talk_sec,
        SUM(talk_sec) AS total_talk_sec,
        ROUND(AVG(wait_sec), 2) AS avg_wait_sec,
        SUM(pause_sec) AS total_pause_sec,
        MIN(call_date) AS first_call,
        MAX(call_date) AS last_call
    FROM vicidial_closer_log
    WHERE user = ? AND DATE(call_date) = ?
    GROUP BY user
";

$stmt = $mysqli->prepare($perf_query);
$stmt->bind_param('ss', $agent_id, $report_date);
$stmt->execute();
$perf_data = $stmt->get_result()->fetch_assoc();

// Status breakdown
$status_query = "
    SELECT 
        status,
        COUNT(*) AS count,
        ROUND(COUNT(*) / (
            SELECT COUNT(*) FROM vicidial_closer_log 
            WHERE user = ? AND DATE(call_date) = ?
        ) * 100, 2) AS percentage,
        ROUND(AVG(talk_sec), 1) AS avg_talk_sec
    FROM vicidial_closer_log
    WHERE user = ? AND DATE(call_date) = ?
    GROUP BY status
    ORDER BY count DESC
";

$stmt = $mysqli->prepare($status_query);
$stmt->bind_param('ssss', $agent_id, $report_date, $agent_id, $report_date);
$stmt->execute();
$status_results = $stmt->get_result();

// Output HTML report
?>
<!DOCTYPE html>
<html>
<head>
    <title>Agent Performance Report - <?php echo htmlspecialchars($agent_result['full_name']); ?></title>
    <style>
        body { font-family: Arial, sans-serif; margin: 20px; }
        .report-header { background: #f0f0f0; padding: 15px; border-radius: 5px; margin-bottom: 20px; }
        .metric { display: inline-block; margin: 10px 20px 10px 0; }
        table { border-collapse: collapse; width: 100%; margin: 20px 0; }
        th, td { border: 1px solid #ddd; padding: 10px; text-align: left; }
        th { background-color: #4CAF50; color: white; }
        tr:nth-child(even) { background-color: #f2f2f2; }
    </style>
</head>
<body>
    <div class="report-header">
        <h1>Agent Performance Report</h1>
        <p><strong>Agent:</strong> <?php echo htmlspecialchars($agent_result['full_name']) . ' (' . htmlspecialchars($agent_id) . ')'; ?></p>
        <p><strong>Date:</strong> <?php echo htmlspecialchars($report_date); ?></p>
    </div>

    <div class="metrics">
        <?php if ($perf_data): ?>
        <div class="metric">
            <strong>Total Calls:</strong> <?php echo $perf_data['total_calls']; ?>
        </div>
        <div class="metric">
            <strong>Connected Calls:</strong> <?php echo $perf_data['connected_calls']; ?> 
            (<?php echo round(($perf_data['connected_calls']/$perf_data['total_calls'])*100, 1); ?>%)
        </div>
        <div class="metric">
            <strong>Avg Talk Time:</strong> <?php echo gmdate('H:i:s', $perf_data['avg_talk_sec']); ?>
        </div>
        <div class="metric">
            <strong>Total Talk Time:</strong> <?php echo gmdate('H:i:s', $perf_data['total_talk_sec']); ?>
        </div>
        <div class="metric">
            <strong>Avg Wait Time:</strong> <?php echo round($perf_data['avg_wait_sec']); ?>s
        </div>
        <div class="metric">
            <strong>Total Pause Time:</strong> <?php echo gmdate('H:i:s', $perf_data['total_pause_sec']); ?>
        </div>
        <?php else: ?>
        <p>No data available for this agent on the selected date.</p>
        <?php endif; ?>
    </div>

    <h2>Call Status Breakdown</h2>
    <table>
        <tr>
            <th>Status</th>
            <th>Count</th>
            <th>Percentage</th>
            <th>Avg Talk Time</th>
        </tr>
        <?php while ($row = $status_results->fetch_assoc()): ?>
        <tr>
            <td><?php echo htmlspecialchars($row['status']); ?></td>
            <td><?php echo $row['count']; ?></td>
            <td><?php echo $row['percentage']; ?>%</td>
            <td><?php echo gmdate('H:i:s', $row['avg_talk_sec']); ?></td>
        </tr>
        <?php endwhile; ?>
    </table>
</body>
</html>
<?php
$mysqli->close();

function sanitize($input) {
    return htmlspecialchars(strip_tags($input));
}
?>

Access the report:

http://your-vicidial-server/vicidial/reports/agent_performance.php?agent_id=AGENT001&date=2024-01-15

Exporting Reports to CSV

Generate CSV Export via CLI

Create a bash script at /usr/local/bin/vicidial_export_performance.sh:

#!/bin/bash
# vicidial_export_performance.sh - Export agent performance to CSV

DB_HOST="localhost"
DB_USER="vicidial"
DB_PASS="your_password"
DB_NAME="asterisk"
REPORT_DATE="${1:-$(date +%Y-%m-%d)}"
OUTPUT_DIR="/tmp/vicidial_reports"
OUTPUT_FILE="${OUTPUT_DIR}/agent_performance_${REPORT_DATE}.csv"

mkdir -p "$OUTPUT_DIR"

mysql -h "$DB_HOST" -u "$DB_USER" -p"$DB_PASS" "$DB_NAME" \
  -e "SELECT 
        u.user AS 'Agent ID',
        u.full_name AS 'Agent Name',
        COUNT(*) AS 'Total Calls',
        SUM(CASE WHEN vcl.talk_sec > 0 THEN 1 ELSE 0 END) AS 'Connected',
        ROUND(COUNT(*) / SUM(CASE WHEN vcl.talk_sec > 0 THEN 1 ELSE 0 END) * 100, 1) AS 'Connect %',
        ROUND(AVG(vcl.talk_sec), 1) AS 'Avg Talk Sec',
        SEC_TO_TIME(SUM(vcl.talk_sec)) AS 'Total Talk Time',
        ROUND(AVG(vcl.wait_sec), 1) AS 'Avg Wait Sec',
        SEC_TO_TIME(SUM(vcl.pause_sec)) AS 'Total Pause Time'
      FROM vicidial_closer_log vcl
      INNER JOIN vicidial_users u ON vcl.user = u.user
      WHERE DATE(vcl.call_date) = '$REPORT_DATE'
      GROUP BY vcl.user, u.full_name
      ORDER BY COUNT(*) DESC" \
  --batch --skip-column-names \
  | sed 's/\t/","/g;s/^/"/;s/$/"/' > "$OUTPUT_FILE"

echo "Report exported to: $OUTPUT_FILE"
ls -lh "$OUTPUT_FILE"

Make it executable and run:

chmod +x /usr/local/bin/vicidial_export_performance.sh
/usr/local/bin/vicidial_export_performance.sh 2024-01-15

Export with Header Row

Modify the script to include headers:

#!/bin/bash
OUTPUT_FILE="/tmp/vicidial_reports/performance_$(date +%Y%m%d_%H%M%S).csv"

{
  echo "Agent ID,Agent Name,Total Calls,Connected,Connect %,Avg Talk Sec,Total Talk Time,Avg Wait Sec,Total Pause Time"

  mysql -h localhost -u vicidial -p"password" asterisk -N -e \
    "SELECT 
      u.user,
      u.full_name,
      COUNT(*),
      SUM(CASE WHEN vcl.talk_sec > 0 THEN 1 ELSE 0 END),
      ROUND(SUM(CASE WHEN vcl.talk_sec > 0 THEN 1 ELSE 0 END) / COUNT(*) * 100, 1),
      ROUND(AVG(vcl.talk_sec), 1),
      SEC_TO_TIME(SUM(vcl.talk_sec)),
      ROUND(AVG(vcl.wait_sec), 1),
      SEC_TO_TIME(SUM(vcl.pause_sec))
    FROM vicidial_closer_log vcl
    INNER JOIN vicidial_users u ON vcl.user = u.user
    WHERE DATE(vcl.call_date) = CURDATE()
    GROUP BY vcl.user, u.full_name
    ORDER BY COUNT(*) DESC" | sed 's/\t/,/g'
} > "$OUTPUT_FILE"

echo "Report saved: $OUTPUT_FILE"

Advanced Metrics and KPIs

Calculate Average Handle Time (AHT)

SELECT 
    user,
    ROUND(AVG(talk_sec + pause_sec), 2) AS aht_seconds,
    SEC_TO_TIME(ROUND(AVG(talk_sec + pause_sec))) AS aht_formatted,
    COUNT(*) AS calls_handled
FROM vicidial_closer_log
WHERE DATE(call_date) = CURDATE()
AND talk_sec > 0
GROUP BY user
ORDER BY aht_seconds DESC;

First Call Resolution (FCR) Analysis

Track agents who solve issues on first contact:

SELECT 
    vcl1.user,
    COUNT(DISTINCT vcl1.lead_id) AS total_unique_leads,
    COUNT(DISTINCT CASE 
        WHEN NOT EXISTS (
            SELECT 1 FROM vicidial_closer_log vcl2
            WHERE vcl2.lead_id = vcl1.lead_id
            AND vcl2.call_date > vcl1.call_date
            AND DATE(vcl2.call_date) = DATE(vcl1.call_date)
        )
        THEN vcl1.lead_id
    END) AS first_contact_resolutions,
    ROUND(
        COUNT(DISTINCT CASE 
            WHEN NOT EXISTS (
                SELECT 1 FROM vicidial_closer_log vcl2
                WHERE vcl2.lead_id = vcl1.lead_id
                AND vcl2.call_date > vcl1.call_date
                AND DATE(vcl2.call_date) = DATE(vcl1.call_date)
            )
            THEN vcl1.lead_id
        END) / COUNT(DISTINCT vcl1.lead_id) * 100, 2
    ) AS fcr_percentage
FROM vicidial_closer_log vcl1
WHERE DATE(vcl1.call_date) = CURDATE()
AND vcl1.talk_sec > 0
GROUP BY vcl1.user
ORDER BY fcr_percentage DESC;

Customer Satisfaction Trend

If using surveys or quality scores:

SELECT 
    u.user,
    u.full_name,
    DATE(vcl.call_date) AS report_date,
    COUNT(*) AS calls_reviewed,
    ROUND(AVG(CAST(vcl.customer_satisfaction AS DECIMAL(3,2))), 2) AS avg_satisfaction,
    COUNT(CASE WHEN CAST(vcl.customer_satisfaction AS DECIMAL(3,2)) >= 4 THEN 1 END) AS positive_surveys
FROM vicidial_closer_log vcl
INNER JOIN vicidial_users u ON vcl.user = u.user
WHERE vcl.customer_satisfaction IS NOT NULL
AND DATE(vcl.call_date) >= DATE(NOW()) - INTERVAL 7 DAY
GROUP BY u.user, u.full_name, DATE(vcl.call_date)
ORDER BY report_date DESC, avg_satisfaction DESC;

Monitoring and Real-Time Metrics

Real-Time Agent Dashboard Query

Pull current agent status without delay:

SELECT 
    u.user,
    u.full_name,
    ual.status,
    ual.pause_type,
    ual.event_time,
    TIMESTAMPDIFF(MINUTE, ual.event_time, NOW()) AS minutes_in_status,
    (SELECT COUNT(*) FROM vicidial_closer_log 
        WHERE user = u.user AND DATE(call_date) = CURDATE()) AS today_calls,
    (SELECT SUM(talk_sec) FROM vicidial_closer_log 
        WHERE user = u.user AND DATE(call_date) = CURDATE()) AS today_talk_sec
FROM vicidial_agent_log ual
INNER JOIN vicidial_users u ON ual.user = u.user
WHERE ual.event_time = (
    SELECT MAX(event_time) FROM vicidial_agent_log 
    WHERE user = u.user
)
ORDER BY u.full_name;

Set Up Automated Report Email

Create a cron job to email daily reports:

#!/bin/bash
# /usr/local/bin/email_performance_report.sh

RECIPIENT="supervisor@company.com"
SUBJECT="Daily Agent Performance Report - $(date +%Y-%m-%d)"
REPORT_DATE=$(date -d yesterday +%Y-%m-%d)

REPORT=$(mysql -h localhost -u vicidial -p"password" asterisk -N -e \
  "SELECT CONCAT(
    'Agent: ', u.full_name, ' | ',
    'Calls: ', COUNT(*), ' | ',
    'Avg Talk: ', SEC_TO_TIME(ROUND(AVG(talk_sec))), ' | ',
    'Connect %: ', ROUND(SUM(CASE WHEN talk_sec > 0 THEN 1 ELSE 0 END)/COUNT(*)*100, 1)
  )
  FROM vicidial_closer_log vcl
  INNER JOIN vicidial_users u ON vcl.user = u.user
  WHERE DATE(vcl.call_date) = '$REPORT_DATE'
  GROUP BY vcl.user
  ORDER BY COUNT(*) DESC")

echo "$REPORT" | mail -s "$SUBJECT" "$RECIPIENT"

Add to crontab:

0 8 * * * /usr/local/bin/email_performance_report.sh

Troubleshooting

Report Shows No Data for Recent Calls

Problem: Queries return empty results for calls made in the last hour.

Solution: Check if calls are being written to vicidial_closer_log:

mysql -u vicidial -p asterisk -e \
  "SELECT COUNT(*) FROM vicidial_closer_log WHERE call_date >= NOW() - INTERVAL 1 HOUR;"

If empty, verify the ViciDial daemon is running:

ps aux | grep Asterisk
ps aux | grep vicidial
systemctl status vicidial

Restart services if needed:

systemctl restart asterisk
systemctl restart vicidial

Large Query Timeout Issues

Problem: Complex reports timeout when querying large date ranges.

Solution: Add indexes to optimize queries:

ALTER TABLE vicidial_closer_log 
ADD INDEX idx_user_date (user, call_date),
ADD INDEX idx_talk_sec (talk_sec),
ADD INDEX idx_status (status);

-- Verify indexes
SHOW INDEX FROM vicidial_closer_log;

For multi-month reports, use date partitioning or export to a data warehouse.

Agent Logs Show Incorrect Pause Time

Problem: total_pause_sec calculations don't match agent perception.

Solution: Cross-reference with vicidial_agent_log:

SELECT 
    u.user,
    SUM(vcl.pause_sec) AS closer_log_pause,
    SUM(CASE WHEN aal.event_type = 'PAUSE' THEN 
        TIMESTAMPDIFF(SECOND, aal.event_time, 
            LEAD(aal.event_time) OVER (PARTITION BY aal.user ORDER BY aal.event_time))
    END) AS agent_log_pause
FROM vicidial_closer_log vcl
INNER JOIN vicidial_users u ON vcl.user = u.user
LEFT JOIN vicidial_agent_log aal ON u.user = aal.user 
    AND DATE(vcl.call_date) = DATE(aal.event_time)
WHERE DATE(vcl.call_date) = CURDATE()
GROUP BY u.user;

Discrepancies indicate calls missing entries in one table—check ViciDial logs at /var/log/asterisk/messages.

Performance Report Taking Too Long to Generate

Problem: Generating reports for teams/campaigns is slow.

Solution: Use STRAIGHT_JOIN to force join order and add date ranges:

SELECT STRAIGHT_JOIN
    u.user,
    COUNT(*) AS total_calls
FROM vicidial_closer_log vcl
STRAIGHT_JOIN vicidial_users u ON vcl.user = u.user
WHERE vcl.call_date >= '2024-01-15 00:00:00'
AND vcl.call_date < '2024-01-16 00:00:00'
AND u.user_level > 1
GROUP BY u.user;

For very large datasets, consider archiving old records:

# Archive calls older than 90 days
mysql -u vicidial -p asterisk -e \
  "INSERT INTO vicidial_closer_log_archive 
   SELECT * FROM vicidial_closer_log 
   WHERE call_date < DATE_SUB(NOW(), INTERVAL 90 DAY);

   DELETE FROM vicidial_closer_log 
   WHERE call_date < DATE_SUB(NOW(), INTERVAL 90 DAY);"

Custom Reports Showing Wrong User Names

Problem: Agent IDs display instead of full names.

Solution: Verify the vicidial_users table join and check if users were deleted:

SELECT COUNT(*) FROM vicidial_users WHERE user = 'AGENT001';

If the agent was deleted, their historical data remains in vicidial_closer_log but vicidial_users join will fail. Use this approach:

SELECT 
    vcl.user,
    COALESCE(u.full_name, vcl.user) AS agent_name,
    COUNT(*) AS calls
FROM vicidial_closer_log vcl
LEFT JOIN vicidial_users u ON vcl.user = u.user
WHERE DATE(vcl.call_date) = CURDATE()
GROUP BY vcl.user;

Reports Not Reflecting Real-Time Changes

Problem: Updated agent information or statuses not showing immediately.

Solution: ViciDial caches some data. Clear relevant caches:

# Clear PHP cache if using OPcache
php -r "opcache_reset();"

# Restart web server
systemctl restart apache2
# or
systemctl restart nginx

For agent status, query directly from memory:

asterisk -rx "show channels concise" | grep -i SIP

Homelab Media Server — Complete Docker Stack on Repurposed Laptop

Moisi Trungu — Thu, 07 May 2026 17:15:04 +0000

Tutorial 44: Homelab Media Server — Complete Docker Stack on Repurposed Laptop

Transform an old laptop into a powerful self-hosted media server running Jellyfin, the *Arr suite, qBittorrent, AdGuard Home, Nextcloud, and 15+ services — all managed through Docker Compose with Intel QSV hardware transcoding, automated media management, and remote access via Tailscale.

Difficulty: Beginner-Intermediate
Reading time: ~60 minutes
Prerequisites: A laptop or mini PC with an Intel CPU (6th gen+ for QSV), 16GB+ RAM, Ubuntu 24.04 installed
Technologies: Docker, Jellyfin, Radarr, Sonarr, Prowlarr, qBittorrent, AdGuard, Nginx Proxy Manager, Tailscale, Tdarr, Nextcloud, Portainer
OS: Ubuntu 24.04 LTS

Introduction — Why Self-Host a Media Server
Hardware Overview & Storage Strategy
Ubuntu Installation & System Configuration
Environment Configuration — Centralized .env File
Management Stack — Portainer, Tailscale, Watchtower
Network & Security — AdGuard Home & Nginx Proxy Manager
Download Stack — qBittorrent
*Arr Media Automation Suite
Jellyfin Media Server
Nextcloud — Self-Hosted Cloud Storage
Media Processing — Tdarr & Ollama
Monitoring — Uptime Kuma
Integration & Automation — Connecting Everything Together
Backup & Disk Protection
Dashboard — Landing Page with Service Links
Troubleshooting — Common Issues and Fixes
Conclusion

1. Introduction — Why Self-Host a Media Server

The Case for Self-Hosting

Streaming services keep raising prices, splitting content across platforms, and removing shows without warning. A self-hosted media server gives you:

Complete control over your library — no content disappearing overnight
No monthly fees — one-time hardware cost, then it runs forever
Privacy — your viewing habits stay on your network
Hardware transcoding — stream to any device, any format, automatically
Automated media management — request a movie and it appears in your library, with subtitles, ready to watch on any device
Network-wide ad blocking — DNS-level filtering for every device in your home
Self-hosted cloud storage — replace Google Drive/iCloud with Nextcloud
Remote access — watch your content from anywhere via Tailscale VPN

Why a Laptop?

Repurposing an old laptop is one of the best homelab decisions you can make:

Advantage	Details
Built-in UPS	Battery survives short power outages — no separate UPS needed
Low power	15-20W idle (vs 60-100W for a desktop/tower server)
Silent	Laptop fans are quiet, often fanless at idle
Compact	Sits on a shelf, no rack needed
Built-in display	Useful for initial setup, then run headless
Intel QSV	Most Intel laptops support Quick Sync Video for hardware transcoding

An Intel i5 (11th gen or newer) with 16-32GB RAM and an NVMe SSD is the sweet spot. The integrated Intel Iris Xe GPU provides excellent hardware transcoding — H.264, H.265/HEVC, VP9, and AV1 decode, all in hardware.

What We Are Building

By the end of this tutorial, you will have a fully automated media server with this architecture:

User requests movie     Radarr searches indexers      qBittorrent downloads
via Jellyseerr    -->   via Prowlarr             -->  to NVMe SSD
                                                           |
                                                           v
                                                      Download completes
                                                           |
                                                           v
                        Radarr imports movie          qBittorrent seeds to
                        to media library         <--  ratio 1.0, auto-removes
                              |
                              v
                        Jellyfin detects new movie    Bazarr auto-downloads
                        in library               -->  subtitles (.srt/.ass)
                              |
                              v
                        Tdarr (optional) transcodes
                        to H.265 using Intel QSV
                              |
                              v
                        Movie available for playback
                        on all devices (TV, phone, web)

Service Overview — Port Map

Port	Service	Purpose	Access Level
8096	Jellyfin	Media streaming server	LAN + Tailscale
5055	Jellyseerr	Request portal (Netflix-like UI)	LAN + Tailscale
8088	Nextcloud	Self-hosted cloud storage	LAN + Tailscale
8080	qBittorrent	Torrent download client	LAN only
8989	Sonarr	TV show automation	LAN only
7878	Radarr	Movie automation	LAN only
8686	Lidarr	Music automation	LAN only
9696	Prowlarr	Indexer manager	LAN only
6767	Bazarr	Automatic subtitles	LAN only
53	AdGuard Home	DNS-level ad blocking	LAN
8053	AdGuard Home Admin	Ad blocker management UI	LAN only
81	Nginx Proxy Manager	Reverse proxy admin	LAN only
80/443	NPM (proxy)	Public reverse proxy	WAN (if configured)
9000	Portainer	Docker management GUI	LAN only
3001	Uptime Kuma	Service health monitoring	LAN only
8265	Tdarr	Automated transcoding	LAN only
11434	Ollama	Local AI/LLM API	LAN only
8888	Dashboard	Landing page with service links	LAN + Tailscale

2. Hardware Overview & Storage Strategy

Recommended Hardware Specs

Spec	Minimum	Recommended	Notes
CPU	Intel i5 6th gen	Intel i5 11th gen+	Must have Intel Quick Sync (QSV)
GPU	Intel UHD 630	Intel Iris Xe	Iris Xe adds AV1 decode, better HEVC
RAM	16GB DDR4	32GB DDR4	16GB is tight with Nextcloud + Ollama
Boot Drive	256GB SSD	500GB NVMe SSD	OS + Docker + configs + downloads
Media Drive	-	500GB+ SSD or HDD	Separate drive for media library
TDP	-	28W (PL1)	~15-20W idle

Laptop-Specific Considerations

Lid close: Must disable sleep-on-lid-close (the server runs headless 24/7)
Battery: Built-in battery acts as a free UPS (survives short power outages)
Network: WiFi works but Ethernet is recommended for media streaming reliability
Screen/keyboard: Useful for initial setup, then run headless via SSH

Storage Strategy — Dual-Drive Setup

The ideal setup uses two drives: an NVMe SSD for the OS, Docker, and temporary downloads, and a second SSD (or HDD) for the media library.

NVMe SSD (boot drive) — OS, Docker, downloads, configs
├── /                     OS + Docker (~20GB)
├── /opt/appdata          Container configs + databases (~5-10GB)
├── /opt/docker           Docker compose files + scripts
├── /mnt/media            Media library root
│   ├── downloads/        Torrent downloads (temporary storage)
│   ├── movies/           -> BIND MOUNT to /mnt/ssd/movies (second drive)
│   ├── tv/               TV shows
│   ├── music/            Music
│   └── books/            Books
└── /var/lib/docker       Container images + volumes (~10-20GB)

Second SSD/HDD (/dev/sda1)
└── /mnt/ssd              Mounted via fstab (by UUID)
    └── movies/           Movie library, bind-mounted to /mnt/media/movies

Key design decision: The second drive is bind-mounted to /mnt/media/movies via fstab. This makes the second drive completely transparent to all containers -- Jellyfin, Radarr, Tdarr, and Bazarr all see /mnt/media/movies as if it were a local directory. No Docker volume changes needed when adding or replacing drives.

3. Ubuntu Installation & System Configuration

3.1 — Install Ubuntu 24.04 LTS

Download Ubuntu 24.04 LTS (Server or Desktop edition) and install it on the laptop. Desktop edition uses slightly more RAM but gives you a GUI for initial setup.

Set hostname to something memorable (e.g., mediaserver)
Create your user account (this guide assumes UID/GID 1000)
Connect to your network (Ethernet preferred)

3.2 — Update System

sudo apt update && sudo apt upgrade -y
sudo reboot

3.3 — Disable Lid Close Sleep

Edit /etc/systemd/logind.conf and set:

HandleLidSwitch=ignore
HandleLidSwitchExternalPower=ignore
HandleLidSwitchDocked=ignore

Then restart the login manager:

sudo systemctl restart systemd-logind

3.4 — Set Static IP (Recommended)

If your system uses NetworkManager (Ubuntu Desktop), use nmcli:

# For Ethernet:
sudo nmcli con add con-name "static-eth" ifname YOUR_ETH_INTERFACE type ethernet \
  ipv4.method manual ipv4.addresses YOUR_IP/24 \
  ipv4.gateway YOUR_GATEWAY ipv4.dns "1.1.1.1,8.8.8.8"
sudo nmcli con up static-eth

# For WiFi (adjust connection name from 'nmcli con show'):
sudo nmcli con modify "YOUR_WIFI_CONNECTION" \
  ipv4.method manual ipv4.addresses YOUR_IP/24 \
  ipv4.gateway YOUR_GATEWAY ipv4.dns "1.1.1.1,8.8.8.8"

# Verify
ip addr show

3.5 — Install Intel Quick Sync (QSV) Drivers

sudo apt install -y intel-media-va-driver vainfo mesa-va-drivers

Verify the installation:

vainfo

You should see output like:

VA-API version: 1.20
Driver version: Intel iHD driver for Intel(R) Gen Graphics - 24.1.0

Confirm codec support (look for H.264, HEVC, VP9, AV1 entries). GPU devices should appear at /dev/dri/card0 (or card1) and /dev/dri/renderD128.

Note: The free intel-media-va-driver package includes all commonly needed codecs. If you need extra codec profiles later, install intel-media-va-driver-non-free instead.

3.6 — Install Docker & Docker Compose

# Install Docker using the official convenience script
curl -fsSL https://get.docker.com | sh

# Add your user to the docker group (avoids needing sudo for docker commands)
sudo usermod -aG docker $USER

# Log out and back in for group change to take effect
# Verify:
docker --version
docker compose version

3.7 — Create Directory Structure

If your boot drive uses LVM (common with Ubuntu Server), expand it to use the full disk first:

# Expand LVM to use full disk (Ubuntu often allocates only ~100GB during install)
sudo lvextend -l +100%FREE /dev/ubuntu-vg/ubuntu-lv
sudo resize2fs /dev/ubuntu-vg/ubuntu-lv

Create the media directories:

# Create all directories
sudo mkdir -p /opt/appdata /opt/docker/compose
sudo mkdir -p /mnt/media/{downloads/{torrents/{movies,tv,music},usenet/{movies,tv,music}},movies,tv,music,books,nextcloud}

# Set ownership to your user (UID/GID 1000)
sudo chown -R 1000:1000 /opt/appdata /opt/docker /mnt/media

3.8 — Configure Power Management for 24/7 Operation

# Disable sleep/suspend/hibernate
sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target

# Disable Wi-Fi power management (prevents random disconnects if using WiFi)
# Edit /etc/NetworkManager/conf.d/default-wifi-powersave-on.conf
# Change wifi.powersave = 2 (or 3) to:
# wifi.powersave = 0

3.9 — Set Up Automatic Security Updates

sudo apt install -y unattended-upgrades

For laptops, also install thermal management:

sudo apt install -y thermald

4. Environment Configuration — Centralized .env File

All containers share a single .env file for common settings like user IDs, timezone, and paths. This avoids hardcoding values in every docker run command.

Create /opt/docker/.env:

# User/Group IDs (run 'id' to check yours — usually 1000:1000)
PUID=1000
PGID=1000
TZ=YOUR_TIMEZONE

# Paths
MEDIA_ROOT=/mnt/media
APPDATA=/opt/appdata

# Gluetun VPN (optional — fill in if you want VPN-protected torrents)
# VPN_SERVICE_PROVIDER=mullvad
# VPN_TYPE=wireguard
# WIREGUARD_PRIVATE_KEY=your_key_here
# WIREGUARD_ADDRESSES=your_address_here
# SERVER_COUNTRIES=Netherlands

Replace YOUR_TIMEZONE with your timezone identifier (e.g., Europe/London, America/New_York, Europe/Berlin, Asia/Tokyo). This ensures all container logs and scheduled tasks use the correct time. All docker run commands below reference ${TZ} from this file, or you can hardcode the timezone directly in each command.

5. Management Stack — Portainer, Tailscale, Watchtower

5.1 — Portainer (Docker GUI)

Portainer gives you a web-based GUI for managing all your Docker containers, images, volumes, and networks.

docker run -d \
  --name portainer \
  --restart=always \
  -p 9000:9000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/appdata/portainer:/data \
  portainer/portainer-ce:latest

Access: http://YOUR_IP:9000

Create an admin account on first visit
Select "Local" environment

5.2 — Tailscale (Remote Access VPN)

Tailscale creates a secure mesh VPN so you can access your media server from anywhere (phone on 4G, laptop at a coffee shop, etc.) without exposing ports to the internet.

# Install Tailscale directly on the host (not Docker — more reliable on laptops)
curl -fsSL https://tailscale.com/install.sh | sh

# Start and authenticate
sudo tailscale up

# Follow the URL printed to authenticate with your Tailscale account
# (create free account at https://tailscale.com if you don't have one)

# Verify
tailscale status

Once connected, your server gets a Tailscale IP (100.x.x.x). You can access all services from anywhere using this IP.

Tip: Disable Tailscale's DNS management to avoid it hijacking your local DNS (especially important if you run AdGuard):
sudo tailscale set --accept-dns=false

5.3 — Watchtower (Automatic Container Updates)

Watchtower monitors your running containers and automatically pulls updated images, recreating containers with the same configuration.

docker run -d \
  --name watchtower \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e DOCKER_API_VERSION=1.53 \
  -e TZ=Europe/London \
  -e WATCHTOWER_CLEANUP=true \
  -e WATCHTOWER_SCHEDULE="0 0 4 * * *" \
  containrrr/watchtower:latest

This checks for container updates daily at 4:00 AM and removes old images after updating.

Note: If you see Docker API version errors, check your Docker API version with docker version --format '{{.Server.APIVersion}}' and set DOCKER_API_VERSION accordingly.

6. Network & Security — AdGuard Home & Nginx Proxy Manager

6.1 — AdGuard Home (Network-Wide Ad Blocking)

AdGuard Home is a DNS-level ad blocker that works for every device on your network -- phones, smart TVs, IoT devices -- without installing anything on the devices themselves.

docker run -d \
  --name adguardhome \
  --restart=always \
  -p 53:53/tcp \
  -p 53:53/udp \
  -p 3000:3000/tcp \
  -p 8053:80/tcp \
  -v /opt/appdata/adguardhome/work:/opt/adguardhome/work \
  -v /opt/appdata/adguardhome/conf:/opt/adguardhome/conf \
  adguard/adguardhome:latest

First-time setup at http://YOUR_IP:3000:

Set the admin web interface to port 8053 (avoids conflicts with other services)
Set DNS to port 53
Create an admin username/password
Add filter lists (recommended: AdGuard default + Steven Black's unified hosts)

After setup, the admin panel moves to: http://YOUR_IP:8053

Important: Set your router's DNS server to your media server's IP address so all devices on the network use AdGuard for DNS resolution.

6.2 — Nginx Proxy Manager (Reverse Proxy + SSL)

NPM lets you access services via clean domain names (e.g., jellyfin.yourdomain.com) instead of IP:port combinations, with automatic Let's Encrypt SSL certificates.

Note: If you have Nextcloud installed as a snap, remap its port first to free port 80 for NPM:
sudo snap set nextcloud ports.http=8088 && sudo snap restart nextcloud

docker run -d \
  --name nginx-proxy-manager \
  --restart=always \
  -p 80:80 \
  -p 443:443 \
  -p 81:81 \
  -v /opt/appdata/npm/data:/data \
  -v /opt/appdata/npm/letsencrypt:/etc/letsencrypt \
  jc21/nginx-proxy-manager:latest

Access: http://YOUR_IP:81
Default login: admin@example.com / changeme (change immediately!)

You will configure proxy hosts here later for each service (e.g., jellyfin.yourdomain.com -> http://YOUR_IP:8096).

7. Download Stack — qBittorrent

qBittorrent is a torrent client with a web UI. We run it without a VPN here for simplicity, but you can add Gluetun (VPN container) later for privacy.

Privacy note: Without a VPN, your real IP is visible in torrent swarms. If you want VPN protection, deploy Gluetun and set network_mode: "service:gluetun" on the qBittorrent container.

7.1 — Deploy qBittorrent

Create the compose file at /opt/docker/compose/downloads.yml:

services:
  qbittorrent:
    image: linuxserver/qbittorrent:latest
    container_name: qbittorrent
    ports:
      - 8080:8080    # qBittorrent WebUI
      - 6881:6881    # Torrent port (TCP)
      - 6881:6881/udp
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
      - WEBUI_PORT=8080
    volumes:
      - /opt/appdata/qbittorrent:/config
      - ${MEDIA_ROOT}/downloads/torrents:/downloads
    restart: always

Deploy:

cd /opt/docker
docker compose -f compose/downloads.yml --env-file .env up -d

Access: http://YOUR_IP:8080
Default login: admin / check logs for the temporary password:

docker logs qbittorrent 2>&1 | grep "temporary password"

7.2 — Configure qBittorrent Settings

These settings are important for disk management and integration with the *Arr apps:

Settings -> Downloads -> Default Save Path: /downloads/
Settings -> Downloads -> Keep incomplete in: /downloads/incomplete/
Settings -> BitTorrent -> Seeding limits: Set max ratio to 1.0 (see Section 14 for details)
Settings -> Web UI: Change the default password

7.3 — SABnzbd (Usenet Downloads — Optional)

Skip this if you only use torrents. Add later if needed.

docker run -d \
  --name sabnzbd \
  --restart=always \
  -p 8888:8080 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Europe/London \
  -v /opt/appdata/sabnzbd:/config \
  -v /mnt/media/downloads/usenet:/downloads \
  linuxserver/sabnzbd:latest

Access: http://YOUR_IP:8888

8. *Arr Media Automation Suite

The *Arr apps form the brain of your media automation pipeline. Each one manages a specific media type: movies, TV shows, music, and subtitles. Prowlarr acts as the central indexer manager, and Jellyseerr provides a user-friendly request portal.

8.1 — Prowlarr (Indexer Manager)

Prowlarr manages all your torrent indexers in one place and syncs them to Radarr, Sonarr, and Lidarr automatically.

docker run -d \
  --name prowlarr \
  --restart=always \
  -p 9696:9696 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Europe/London \
  -v /opt/appdata/prowlarr:/config \
  linuxserver/prowlarr:latest

Access: http://YOUR_IP:9696

Setup:

Settings -> General -> Set authentication (Forms, username/password)
Indexers -> Add your torrent indexers (1337x, RARBG, etc.)
Settings -> Apps -> Add Radarr, Sonarr, and Lidarr (after deploying them below)

8.2 — Radarr (Movies)

Radarr automates movie downloads. It searches indexers, sends torrents to qBittorrent, imports completed downloads, renames files, and manages your movie library.

docker run -d \
  --name radarr \
  --restart=always \
  -p 7878:7878 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Europe/London \
  -v /opt/appdata/radarr:/config \
  -v /mnt/media:/media \
  linuxserver/radarr:latest

Access: http://YOUR_IP:7878

Setup:

Settings -> General -> Set authentication
Settings -> Media Management:
- Root Folder: /media/movies
- Enable "Rename Movies"
- Enable "Use Hardlinks instead of Copy" -> YES (saves disk space when source and destination are on the same filesystem)
Settings -> Download Clients -> Add qBittorrent:
- Host: YOUR_IP
- Port: 8080
- Category: radarr
Settings -> Quality Profiles -> Select "HD-1080p" as default
Settings -> Indexers -> (these sync automatically from Prowlarr)

8.3 — Sonarr (TV Shows)

Sonarr is the same concept as Radarr but for TV shows. It monitors series, downloads new episodes automatically, and organizes them by season.

docker run -d \
  --name sonarr \
  --restart=always \
  -p 8989:8989 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Europe/London \
  -v /opt/appdata/sonarr:/config \
  -v /mnt/media:/media \
  linuxserver/sonarr:latest

Access: http://YOUR_IP:8989

Setup (same pattern as Radarr):

Authentication in Settings -> General
Root Folder: /media/tv
Download Client: qBittorrent (category: sonarr)
Quality Profile: HD-1080p
Enable hardlinks

8.4 — Lidarr (Music)

Lidarr manages your music library the same way Radarr manages movies.

docker run -d \
  --name lidarr \
  --restart=always \
  -p 8686:8686 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Europe/London \
  -v /opt/appdata/lidarr:/config \
  -v /mnt/media:/media \
  linuxserver/lidarr:latest

Access: http://YOUR_IP:8686
Root Folder: /media/music, download category: lidarr

8.5 — Bazarr (Automatic Subtitles)

Bazarr automatically downloads subtitles for your movies and TV shows by connecting to Radarr and Sonarr.

docker run -d \
  --name bazarr \
  --restart=always \
  -p 6767:6767 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Europe/London \
  -v /opt/appdata/bazarr:/config \
  -v /mnt/media:/media \
  linuxserver/bazarr:latest

Access: http://YOUR_IP:6767

Setup:

Settings -> Subtitles -> Languages: Add your preferred languages
Settings -> Providers -> Add OpenSubtitles.com (free account required)
Settings -> Sonarr/Radarr -> Connect to both using their API keys (found in each app under Settings -> General)

8.6 — Jellyseerr (Request Portal)

Jellyseerr gives your users (family, friends) a Netflix-like interface to browse and request movies and TV shows. Requests are automatically forwarded to Radarr/Sonarr for download.

docker run -d \
  --name jellyseerr \
  --restart=always \
  -p 5055:5055 \
  -e TZ=Europe/London \
  -v /opt/appdata/jellyseerr:/app/config \
  fallenbagel/jellyseerr:latest

Access: http://YOUR_IP:5055
Connect to Jellyfin + Radarr + Sonarr during the setup wizard.

8.7 — Connect Prowlarr to All *Arr Apps

Once all *Arr apps are running, go back to Prowlarr (http://YOUR_IP:9696):

Settings -> Apps -> Add:
- Radarr: URL http://YOUR_IP:7878, API key from Radarr -> Settings -> General
- Sonarr: URL http://YOUR_IP:8989, API key from Sonarr -> Settings -> General
- Lidarr: URL http://YOUR_IP:8686, API key from Lidarr -> Settings -> General
Click "Sync" — all indexers now appear in every *Arr app automatically

9. Jellyfin Media Server

Jellyfin is the heart of the stack — a free, open-source media server that streams your content to any device (web browser, smart TV, phone, tablet).

9.1 — Deploy Jellyfin with Hardware Transcoding

The key to smooth streaming is passing the Intel GPU device into the container for hardware-accelerated transcoding.

docker run -d \
  --name jellyfin \
  --restart=always \
  -p 8096:8096 \
  --device=/dev/dri/renderD128:/dev/dri/renderD128 \
  --device=/dev/dri/card1:/dev/dri/card1 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Europe/London \
  -e JELLYFIN_PublishedServerUrl=http://YOUR_IP:8096 \
  -v /opt/appdata/jellyfin:/config \
  -v /mnt/media/movies:/data/movies \
  -v /mnt/media/tv:/data/tv \
  -v /mnt/media/music:/data/music \
  -v /mnt/media/books:/data/books \
  jellyfin/jellyfin:latest

Note: The GPU device path may be /dev/dri/card0 instead of /dev/dri/card1 on your system. Check with ls -la /dev/dri/ to confirm.

Access: http://YOUR_IP:8096

First-time setup wizard:

Create an admin account
Add media libraries:
- Movies -> /data/movies
- Shows -> /data/tv
- Music -> /data/music
Set preferred language and metadata language

9.2 — Enable QSV Hardware Transcoding

In Jellyfin's admin dashboard:

Dashboard -> Playback -> Transcoding
Hardware acceleration: Intel QuickSync (QSV)
Enable hardware decoding for: H264, HEVC, VP9, AV1 (Intel Iris Xe supports all)
Enable Hardware encoding -> YES
Enable Tone mapping -> YES
Preferred hardware encoder: QSV
Save

9.3 — Verify Transcoding Works

Play a video in the Jellyfin web player
During playback, check if hardware transcoding is active:

# Should show GPU activity (render/video percentages above 0%)
sudo intel_gpu_top
# (install with: sudo apt install -y intel-gpu-tools)

9.4 — Client Apps

Samsung Tizen TV: Install Jellyfin from the Samsung app store
iPhone/iPad: Install "Jellyfin" from the App Store (free)
Android: Install "Jellyfin" from the Play Store (free)
Alternative: Infuse Pro (iOS/tvOS, paid — prettier UI, auto-discovers Jellyfin)

Point all apps at: http://YOUR_IP:8096
For remote access (outside home): Use the Tailscale IP http://100.x.x.x:8096

10. Nextcloud — Self-Hosted Cloud Storage

Nextcloud replaces Google Drive, Dropbox, and iCloud with a self-hosted solution. You can sync files, auto-upload photos from your phone, and share files with links.

Option A: Nextcloud Snap (Simpler)

The Ubuntu snap is the easiest way to run Nextcloud. It includes its own database and web server.

sudo snap install nextcloud

If you need port 80 for Nginx Proxy Manager, remap Nextcloud's HTTP port:

sudo snap set nextcloud ports.http=8088
sudo snap restart nextcloud

Access: http://YOUR_IP:8088

Option B: Nextcloud Docker (More Flexible)

If you prefer Docker for consistency with the rest of the stack:

Step 1 — MariaDB (database):

docker run -d \
  --name nextcloud-db \
  --restart=always \
  -e MYSQL_ROOT_PASSWORD=CHANGE_ME_ROOT_PW \
  -e MYSQL_DATABASE=nextcloud \
  -e MYSQL_USER=nextcloud \
  -e MYSQL_PASSWORD=CHANGE_ME_NC_PW \
  -v /opt/appdata/nextcloud-db:/var/lib/mysql \
  mariadb:latest \
  --transaction-isolation=READ-COMMITTED \
  --log-bin=binlog \
  --binlog-format=ROW

Step 2 — Nextcloud:

docker run -d \
  --name nextcloud \
  --restart=always \
  -p 8443:80 \
  -e MYSQL_HOST=nextcloud-db \
  -e MYSQL_DATABASE=nextcloud \
  -e MYSQL_USER=nextcloud \
  -e MYSQL_PASSWORD=CHANGE_ME_NC_PW \
  -e NEXTCLOUD_ADMIN_USER=admin \
  -e NEXTCLOUD_ADMIN_PASSWORD=CHANGE_ME_ADMIN_PW \
  -e NEXTCLOUD_TRUSTED_DOMAINS="YOUR_IP localhost" \
  --link nextcloud-db:nextcloud-db \
  -v /opt/appdata/nextcloud:/var/www/html \
  -v /mnt/media/nextcloud:/var/www/html/data \
  nextcloud:latest

Access: http://YOUR_IP:8443

Phone Setup

Install the Nextcloud app from your phone's app store
Server: http://YOUR_IP:8088 (snap) or http://YOUR_IP:8443 (Docker) — use the Tailscale IP for remote access
Login with admin credentials
For photo auto-upload: Nextcloud app -> Auto Upload -> Enable

Tip: PhotoSync app (iOS, one-time purchase) provides more reliable photo backup to Nextcloud via WebDAV than the native Nextcloud auto-upload.

11. Media Processing — Tdarr & Ollama

11.1 — Tdarr (Automated Library Transcoding)

Tdarr scans your existing media library and automatically re-encodes files to more efficient codecs (e.g., H.264 -> H.265/HEVC) using Intel QSV hardware acceleration. This can save 40-60% disk space with no visible quality loss.

docker run -d \
  --name tdarr \
  --restart=always \
  -p 8265:8265 \
  -p 8266:8266 \
  --device=/dev/dri:/dev/dri \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Europe/London \
  -e serverIP=0.0.0.0 \
  -e serverPort=8266 \
  -e webUIPort=8265 \
  -e internalNode=true \
  -e inContainer=true \
  -e nodeName=MediaServer \
  -v /opt/appdata/tdarr/server:/app/server \
  -v /opt/appdata/tdarr/configs:/app/configs \
  -v /opt/appdata/tdarr/logs:/app/logs \
  -v /mnt/media:/media \
  -v /opt/appdata/tdarr/transcode_cache:/temp \
  ghcr.io/haveagitgat/tdarr:latest

Access: http://YOUR_IP:8265

Setup:

Libraries -> Add:
- Movies: Source /media/movies, Transcode cache /temp
- TV: Source /media/tv, Transcode cache /temp
Plugins -> Use community plugin: Tdarr_Plugin_MC93_Migz1FFMPEG
- Target codec: HEVC (H.265)
- Use hardware: Intel QSV
Schedule (recommended to prevent daytime CPU load):
- Node -> Schedule -> Enable, set hours like 01:00-07:00

11.2 — Ollama (Local LLM — Optional)

Ollama runs large language models locally on your server. Useful for a self-hosted AI chatbot, or just experimenting with local LLMs.

docker run -d \
  --name ollama \
  --restart=unless-stopped \
  -p 11434:11434 \
  -v /opt/appdata/ollama:/root/.ollama \
  ollama/ollama:latest

Pull a model:

docker exec ollama ollama pull mistral:7b
# Or a smaller model if RAM is tight:
docker exec ollama ollama pull phi3:mini

Test:

docker exec ollama ollama run mistral:7b "What is a homelab?"

12. Monitoring — Uptime Kuma

Uptime Kuma provides a clean, self-hosted status page that monitors all your services and alerts you when something goes down.

docker run -d \
  --name uptime-kuma \
  --restart=always \
  -p 3001:3001 \
  -v /opt/appdata/uptime-kuma:/app/data \
  louislam/uptime-kuma:latest

Access: http://YOUR_IP:3001

Add monitors for each service:

Service	Type	URL
Jellyfin	HTTP	`http://YOUR_IP:8096`
Radarr	HTTP	`http://YOUR_IP:7878`
Sonarr	HTTP	`http://YOUR_IP:8989`
qBittorrent	HTTP	`http://YOUR_IP:8080`
Prowlarr	HTTP	`http://YOUR_IP:9696`
Bazarr	HTTP	`http://YOUR_IP:6767`
Jellyseerr	HTTP	`http://YOUR_IP:5055`
AdGuard	HTTP	`http://YOUR_IP:8053`
Nextcloud	HTTP	`http://YOUR_IP:8088`

Set check interval to 60 seconds. Enable notifications (email, Telegram, Discord, etc.) to be alerted when a service goes down.

13. Integration & Automation — Connecting Everything Together

This is where the magic happens. Once all services are connected, a single movie request triggers a fully automated pipeline.

13.1 — *Arr Download Client Configuration

In Radarr (and repeat for Sonarr, Lidarr):

Settings -> Download Clients -> Add -> qBittorrent
- Host: YOUR_IP
- Port: 8080
- Username/Password: your qBittorrent credentials
- Category: radarr (or sonarr, lidarr respectively)
- Test -> Save

13.2 — Bazarr Integration

In Bazarr:

Settings -> Sonarr -> Enable, enter URL + API key
Settings -> Radarr -> Enable, enter URL + API key
Settings -> Languages -> Add preferred subtitle languages
Settings -> Providers -> Add OpenSubtitles.com

13.3 — Jellyseerr Integration

In Jellyseerr (first-time wizard):

Sign in with Jellyfin -> enter URL + credentials
Add Radarr server: URL + API key + quality profile + root folder
Add Sonarr server: URL + API key + quality profile + root folder
Now users can request movies/TV via http://YOUR_IP:5055

13.4 — The Complete Request Flow

User requests movie          Radarr searches indexers       qBittorrent downloads
via Jellyseerr (:5055)  -->  via Prowlarr (:9696)     -->  to NVMe: /downloads/torrents/
                                                                |
                                                                v
                                                           Download completes
                                                                |
                                                                v
                              Radarr detects completion,   qBittorrent seeds to
                              imports (copies) movie   <-- ratio 1.0, then auto-removes
                              to SSD: /media/movies/       torrent from list
                                   |
                                   v
                              Radarr deletes source files
                              from /downloads/torrents/
                              (removeCompletedDownloads: true)
                                   |
                                   v
                              Jellyfin detects new movie     Bazarr auto-downloads
                              in /data/movies/ library  -->  subtitles (.srt/.ass)
                                   |
                                   v
                              Tdarr (optional) transcodes
                              to H.265 using Intel QSV
                                   |
                                   v
                              Movie available for playback
                              on all devices (TV, phone, web)

13.5 — End-to-End Test

Go to Jellyseerr -> Search for a movie -> Request it
Check Radarr -> should show the movie as "Searching"
Check qBittorrent -> should start downloading
Wait for download to complete
Check Jellyfin -> movie should appear in library
Play the movie -> verify hardware transcoding works
Check Bazarr -> subtitles should auto-download

If all steps work, your media automation pipeline is fully operational.

13.6 — Where Files Live (Filesystem Map)

NVMe (boot drive) -- Fast, temporary storage      Second Drive -- Movie library
+----------------------------------+              +------------------------------+
| /mnt/media/downloads/torrents/   |              | /mnt/ssd/movies/             |
|   +-- Movie.Name.1080p.x264/    |--(Radarr)----| +-- Inception (2010)/        |
|   |   +-- movie.mkv (temp)      |  copies &    | |   +-- Inception.mkv        |
|   +-- (auto-cleaned after 7d)   |  deletes     | +-- Interstellar (2014)/     |
|                                  |  source      | |   +-- Interstellar.mkv     |
| /mnt/media/tv/                   |              | +-- ...                      |
|   +-- Show Name/Season 01/      |              |                              |
|   +-- ...                        |              | Bind-mounted to:             |
|                                  |              | /mnt/media/movies/           |
| /mnt/media/music/                |              | (transparent to containers)  |
| /mnt/media/books/                |              +------------------------------+
+----------------------------------+

Note: When source (NVMe) and destination (SSD) are on different filesystems, Radarr uses copy instead of hardlinks. This is expected and correct.

14. Backup & Disk Protection

14.1 — Config Backup Script

Your container configurations in /opt/appdata are the most important thing to back up. Media can be re-downloaded, but configs contain your settings, databases, and user accounts.

Create /opt/docker/backup.sh:

#!/bin/bash
# Backup all container configs
BACKUP_DIR="/mnt/media/backups"
DATE=$(date +%Y%m%d)

mkdir -p $BACKUP_DIR

# Stop containers that use databases for clean backup
docker stop nextcloud-db

# Create tarball of all configs
tar -czf $BACKUP_DIR/appdata-$DATE.tar.gz -C /opt appdata

# Restart stopped containers
docker start nextcloud-db

# Keep only last 7 backups
ls -tp $BACKUP_DIR/appdata-*.tar.gz | tail -n +8 | xargs -I {} rm -- {}

echo "Backup completed: $BACKUP_DIR/appdata-$DATE.tar.gz"

chmod +x /opt/docker/backup.sh

# Test it
/opt/docker/backup.sh

# Schedule weekly (Sunday 3AM)
crontab -e
# Add this line:
# 0 3 * * 0 /opt/docker/backup.sh >> /var/log/backup.log 2>&1

14.2 — Disk Protection — Three Layers

Running a media server on limited storage (especially a single NVMe) can quickly fill the disk if downloads are not cleaned up. Here is a three-layer protection strategy:

Layer	Component	Action	Trigger
1	qBittorrent	Auto-remove torrent after seeding	Ratio 1.0 / 24h max / 24h inactive
2	Radarr/Sonarr	Delete source files after import	`removeCompletedDownloads: true`
3	disk-guard.sh	Clean old downloads + Docker/snap/apt	Every 15 min via cron

Layer 1: qBittorrent Seeding Limits

Add to /opt/appdata/qbittorrent/qBittorrent/qBittorrent.conf under [BitTorrent]:

Session\GlobalMaxRatio=1
Session\GlobalMaxSeedingMinutes=1440
Session\GlobalMaxInactiveSeedingMinutes=1440
Session\ShareLimitAction=Remove

GlobalMaxRatio=1 — Stop seeding after uploading 1x the file size
GlobalMaxSeedingMinutes=1440 — Max 24 hours of seeding regardless of ratio
GlobalMaxInactiveSeedingMinutes=1440 — Remove if no upload activity for 24 hours
ShareLimitAction=Remove — Remove torrent from list when limits are reached

Layer 2: *Arr Completed Download Handling

Already configured in Radarr and Sonarr:

removeCompletedDownloads: true — After import, remove torrent + delete source files
autoRedownloadFailed: true — Retry if download fails

Layer 3: disk-guard.sh — Automated Disk Cleanup

Create /opt/docker/disk-guard.sh and schedule it via root crontab:

# Root crontab entry:
*/15 * * * * /opt/docker/disk-guard.sh

Disk Usage	Action
Always	Clean Docker unused images, journal logs > 7 days
>= 85%	Delete torrent downloads older than 7 days, aggressive Docker prune
>= 95%	Emergency: Delete ALL torrent downloads, clear snap + apt cache

To check its activity:

# View recent log entries
tail -20 /var/log/disk-guard.log

# Manual run
sudo /opt/docker/disk-guard.sh

# Check current disk usage
df -h / /mnt/ssd

14.3 — SSD Expansion (Adding a Second Drive)

When you add a second drive (SSD or HDD) for extra media storage:

# Identify the new drive
lsblk

# Create GPT partition table + single partition
sudo fdisk /dev/sda
# g (new GPT), n (new partition), 1, Enter, Enter, w (write)

# Format as ext4
sudo mkfs.ext4 -L media-ssd /dev/sda1

# Create mount point and mount
sudo mkdir -p /mnt/ssd
sudo mount /dev/sda1 /mnt/ssd

# Get UUID and add to fstab for persistent mounting
UUID=$(sudo blkid -s UUID -o value /dev/sda1)
echo "UUID=$UUID /mnt/ssd ext4 defaults 0 2" | sudo tee -a /etc/fstab

Migrate content and create a bind mount:

# Create movies directory on the new drive
sudo mkdir -p /mnt/ssd/movies
sudo chown YOUR_USER:YOUR_USER /mnt/ssd /mnt/ssd/movies

# Copy movies to the new drive
cp -av /mnt/media/movies/* /mnt/ssd/movies/

# Verify both locations match
ls /mnt/media/movies/ | wc -l
ls /mnt/ssd/movies/ | wc -l

# Remove originals from the boot drive
rm -rf /mnt/media/movies/*

# Bind mount (immediate)
sudo mount --bind /mnt/ssd/movies /mnt/media/movies

# Persist in fstab
echo "/mnt/ssd/movies /mnt/media/movies none bind 0 0" | sudo tee -a /etc/fstab

# Restart Jellyfin to pick up the bind mount
docker restart jellyfin

Now /mnt/media/movies transparently serves content from the second drive. All containers work without any Docker changes.

14.4 — Reduce ext4 Reserved Blocks

By default, ext4 reserves 5% of disk space for root. On a homelab server, 1% is sufficient:

sudo tune2fs -m 1 /dev/mapper/ubuntu--vg-ubuntu--lv

This recovers ~16GB of usable space on a 466GB drive.

14.5 — DNS Fix (Tailscale + Disk Full Edge Case)

If the disk fills up, Tailscale's MagicDNS can break and hijack /etc/resolv.conf, causing DNS resolution to fail. Fix:

sudo tailscale set --accept-dns=false
sudo ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf
sudo systemctl restart systemd-resolved

15. Dashboard — Landing Page with Service Links

A simple landing page gives you one-click access to all your services. You can build a custom HTML page or use an existing dashboard tool like Homer, Homarr, or Dashy.

The dashboard should include:

Links to all services with their ports
System status overview
Quick-access to the most used services (Jellyfin, Jellyseerr, qBittorrent)
Optionally, an AI chat widget connected to your local Ollama instance

Deploy a simple dashboard container on port 8888 (or whichever port you prefer) and configure it with links to all your services from the port map in Section 1.

16. Troubleshooting — Common Issues and Fixes

Container Won't Start

docker logs <container_name>
# Check for permission errors — usually fix with:
sudo chown -R 1000:1000 /opt/appdata/<container_name>

Hardware Transcoding Not Working

# Check GPU device exists
ls -la /dev/dri/
# Should show: card0 (or card1) and renderD128

# Check VA-API driver
vainfo
# Should show "iHD driver"

# Fix permissions
sudo usermod -aG render $USER
sudo usermod -aG video $USER
# Log out/in, then restart Jellyfin container
docker restart jellyfin

Laptop Overheating

# Install thermal management
sudo apt install -y thermald

# Check temperatures
sensors
# (install with: sudo apt install -y lm-sensors && sudo sensors-detect)

Cannot Access Services Remotely

# Verify Tailscale is connected
tailscale status

# Check if firewall is blocking
sudo ufw status
# If active, allow ports:
sudo ufw allow 8096/tcp    # Jellyfin
sudo ufw allow 5055/tcp    # Jellyseerr
# (add other ports as needed)

USB Drive Disconnects Randomly

# Disable USB autosuspend
echo -1 | sudo tee /sys/module/usbcore/parameters/autosuspend

# Make permanent — add to GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub:
# usbcore.autosuspend=-1
sudo update-grub
sudo reboot

Disk Full / No Internet / Services Broken

# Check disk usage
df -h / /mnt/ssd

# Run disk cleanup manually
sudo /opt/docker/disk-guard.sh

# Check what is eating space
du -sh /mnt/media/downloads/torrents/   # Torrent downloads
du -sh /var/lib/docker/                 # Docker images/layers
du -sh /var/lib/snapd/cache/            # Snap cache

# If DNS is broken (Tailscale took over resolv.conf):
sudo ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf
sudo systemctl restart systemd-resolved

# Check disk-guard log
tail -20 /var/log/disk-guard.log

Quick Reference: Container Management

# See all running containers
docker ps

# See all containers (including stopped)
docker ps -a

# View container logs
docker logs <container_name>
docker logs -f <container_name>    # Follow (live)

# Restart a container
docker restart <container_name>

# Stop / Start
docker stop <container_name>
docker start <container_name>

# Remove a container (data in /opt/appdata is preserved)
docker stop <container_name> && docker rm <container_name>

# Update a container manually
docker pull <image_name>:latest
docker stop <container_name> && docker rm <container_name>
# Then re-run the original docker run command

# Check Docker disk usage
docker system df

# Clean up unused images/containers
docker system prune -a

Quick Reference: Useful Paths

Path	Contents	Disk
`/opt/appdata/`	All container configs — BACK THIS UP	Boot drive
`/opt/docker/`	Docker compose files, .env, scripts	Boot drive
`/mnt/media/`	All media content	Boot drive
`/mnt/media/downloads/`	Active torrent downloads (auto-cleaned)	Boot drive
`/mnt/media/movies/`	Radarr-managed movies (bind mount to second drive)	Second drive
`/mnt/media/tv/`	Sonarr-managed TV shows	Boot drive
`/mnt/media/music/`	Lidarr-managed music	Boot drive
`/mnt/media/books/`	Books	Boot drive
`/mnt/media/nextcloud/`	Nextcloud user data	Boot drive
`/mnt/ssd/`	Second drive mount point	Second drive
`/opt/docker/disk-guard.sh`	Disk protection script (cron every 15 min)	Boot drive
`/var/log/disk-guard.log`	Disk guard log	Boot drive

17. Conclusion

You now have a fully automated, self-hosted media server running on a repurposed laptop. Here is what the complete stack provides:

Jellyfin streams your movies, TV shows, and music to any device with Intel QSV hardware transcoding
The *Arr suite (Radarr, Sonarr, Lidarr, Prowlarr) automates finding, downloading, and organizing media
Jellyseerr gives users a Netflix-like request interface
Bazarr automatically downloads subtitles in your preferred languages
qBittorrent handles downloads with automatic seeding limits and cleanup
Tdarr re-encodes your library to H.265 for 40-60% space savings
AdGuard Home blocks ads network-wide at the DNS level
Nginx Proxy Manager provides clean URLs with SSL certificates
Tailscale enables secure remote access from anywhere
Nextcloud replaces cloud storage services
Uptime Kuma monitors everything and alerts you when services go down
Watchtower keeps all containers automatically updated
Portainer gives you a GUI for Docker management
Three-layer disk protection prevents the disk from filling up

Next Steps

Add torrent indexers in Prowlarr (:9696) for better search results
Add subtitle providers and languages in Bazarr (:6767)
Set up Uptime Kuma monitors for each service (:3001)
Configure NPM proxy hosts for clean domain-based URLs (:81)
Set up Nextcloud auto-upload on your phone for photo backup
Consider adding a VPN (Gluetun) in front of qBittorrent for privacy
Explore Navidrome (:4533) if you want a dedicated music streaming server with Subsonic-compatible mobile apps

The entire stack runs on ~15-20W at idle, costs nothing per month, and gives you complete ownership of your media library. Every service is containerized, backed up weekly, and auto-updated -- set it and forget it.

Kamailio + FreeSWITCH — Load Balancing & High Availability

Moisi Trungu — Thu, 07 May 2026 17:14:29 +0000

Tutorial 43: Kamailio + FreeSWITCH — Load Balancing & High Availability

Build a carrier-grade VoIP platform by combining Kamailio as a SIP proxy/load balancer with multiple FreeSWITCH media servers. This advanced tutorial covers dispatcher-based load balancing, RTPEngine for media relay, WebRTC gateway integration, database-driven routing, geographic failover, and full high availability with no single point of failure. This is the architecture used by every major VoIP provider handling millions of calls — and by the end of this tutorial, you will have a production-ready platform capable of 10,000+ concurrent calls with zero-downtime upgrades and geographic redundancy.

Difficulty: Advanced
Reading time: ~80 minutes
Prerequisites: Tutorial 41 — FreeSWITCH Fundamentals, Tutorial 42 — Kamailio Fundamentals
Technologies: Kamailio, FreeSWITCH, RTPEngine, Keepalived, MariaDB Galera, WebRTC, TLS, DNS SRV, Prometheus, Homer
OS: Debian 12 (Bookworm) for all servers

Introduction — Why Combine Kamailio + FreeSWITCH
Architecture Overview
Prerequisites & Server Planning
Kamailio SBC Configuration
Dispatcher — Load Balancing FreeSWITCH
RTPEngine — Media Relay
FreeSWITCH Media Server Configuration
Database-Driven Routing
WebRTC Gateway
High Availability — Kamailio
High Availability — FreeSWITCH
Geographic Distribution
Monitoring & Operations
Troubleshooting

1. Introduction

Why Combine Kamailio and FreeSWITCH?

Kamailio and FreeSWITCH are both excellent SIP platforms, but they excel at fundamentally different things:

Capability	Kamailio	FreeSWITCH
SIP proxy/routing	Exceptional — 50,000+ TPS	Basic — not designed for proxying
Media handling	None — signaling only	Exceptional — codec, mixing, recording
Load balancing	Built-in (dispatcher)	Not applicable
NAT traversal	Signaling only (nathelper)	Full (media + signaling)
IVR / call queues	Not available	Full-featured
Conference bridges	Not available	Full-featured
Voicemail	Not available	Full-featured
Concurrent calls	100,000+ (signaling)	2,000-5,000 (with media)
Horizontal scaling	Stateless — easy	Stateful — complex
WebRTC	WSS termination	Media bridging

The combination gives you separation of concerns:

Kamailio handles everything at the signaling layer: SIP routing, load balancing, authentication, rate limiting, topology hiding, NAT fixing, and DDoS protection.
FreeSWITCH handles everything at the media layer: IVR menus, call queues, conference bridges, voicemail, recording, codec transcoding, and call control logic.
RTPEngine sits between them handling media relay: NAT traversal for RTP, SRTP/DTLS bridging for WebRTC, and codec transcoding when needed.

What This Architecture Gets You

10,000+ concurrent calls — scale FreeSWITCH horizontally (add more servers)
Zero-downtime upgrades — drain a FreeSWITCH node, upgrade, re-add to the pool
Geographic distribution — Kamailio clusters in multiple data centers
No single point of failure — every component is redundant
WebRTC support — Kamailio terminates WSS, RTPEngine bridges DTLS↔RTP
DDoS resilience — Kamailio's pike module and rate limiting protect backend servers
Topology hiding — external parties never see your internal FreeSWITCH IPs

Who Uses This Architecture?

Every major VoIP carrier and CPaaS provider runs some variation of this stack:

Twilio — Kamailio for SIP routing, custom media servers
Vonage/Nexmo — Kamailio + FreeSWITCH at scale
Plivo — Kamailio + FreeSWITCH (open about their stack)
Large call centers — 500+ agents typically need this architecture
Wholesale VoIP carriers — millions of minutes per month

2. Architecture Overview

Production Architecture Diagram

                        ┌──────────────────────────────────────┐
                        │          DNS / SRV Records           │
                        │    sip.YOUR_DOMAIN → Kamailio VIP    │
                        │    _sip._udp.YOUR_DOMAIN SRV         │
                        └──────────────────┬───────────────────┘
                                           │
                          ┌────────────────┼────────────────┐
                          │                │                │
              ┌───────────▼──┐    ┌────────▼────┐   ┌──────▼───────┐
  Layer 2     │  Kamailio-A  │    │  Keepalived │   │  Kamailio-B  │
  SBC Pair    │  (Active)    │◄──►│  VIP Float  │◄─►│  (Standby)   │
              │  SIP+WSS     │    │             │   │  SIP+WSS     │
              └──────┬───────┘    └─────────────┘   └──────┬───────┘
                     │                                      │
                     │          SIP (signaling)             │
           ┌─────────┴──────────────────────────────────────┴─────────┐
           │                                                          │
  ┌────────▼────────┐                                   ┌─────────────▼──┐
  │  RTPEngine-1    │         Layer 3                   │  RTPEngine-2   │
  │  (Media Relay)  │         Media Relay               │  (Media Relay) │
  └────────┬────────┘                                   └──────┬─────────┘
           │                  RTP (media)                      │
           └─────────┬─────────────────────────┬───────────────┘
                     │                         │
           ┌─────────▼──────┐        ┌─────────▼──────┐
           │  FreeSWITCH-1  │        │  FreeSWITCH-2  │      ...N
  Layer 4  │  (Media/App)   │        │  (Media/App)   │
           │  IVR/Queue/Rec │        │  IVR/Queue/Rec │
           └────────┬───────┘        └────────┬───────┘
                    │                          │
                    └──────────┬───────────────┘
                               │
                    ┌──────────▼──────────┐
  Layer 5          │  MariaDB Galera      │
  Database         │  (3-node cluster)    │
                   │  Users/CDR/Config    │
                   └──────────────────────┘

Component Responsibility Matrix

Component	Layer	Primary Role	Handles
DNS/SRV	1	Geographic failover	Route clients to nearest DC
Kamailio (x2)	2	SIP proxy / SBC	Authentication, routing, load balancing, NAT fix, rate limiting, topology hiding, WebSocket termination
RTPEngine (x2)	3	Media relay	RTP proxying, NAT traversal for media, SRTP↔RTP bridging, DTLS termination, codec transcoding
FreeSWITCH (x2-N)	4	Media application	IVR, call queues, conferencing, voicemail, recording, call control, DTMF handling
MariaDB Galera (x3)	5	Shared state	User credentials, CDRs, routing rules, call state, configuration

Traffic Flow — Inbound Call

1. External SIP INVITE → DNS resolves to Kamailio VIP
2. Kamailio: authenticate trunk, apply rate limits
3. Kamailio: nathelper fixes Contact/Via headers
4. Kamailio: rtpengine_offer() — RTPEngine rewrites SDP (external→internal)
5. Kamailio: dispatcher selects FreeSWITCH from pool
6. Kamailio: forward INVITE to FreeSWITCH (topology hidden)
7. FreeSWITCH: executes dialplan (IVR, queue, bridge to agent)
8. FreeSWITCH: 200 OK → Kamailio
9. Kamailio: rtpengine_answer() — RTPEngine rewrites SDP (internal→external)
10. Kamailio: 200 OK → external trunk
11. Media flows: External ↔ RTPEngine ↔ FreeSWITCH

3. Prerequisites & Server Planning

Minimum Lab Setup (5 Servers)

For learning and development, you need at minimum:

Role	Hostname	IP (example)	vCPU	RAM	Disk	Bandwidth
Kamailio SBC	kam01	10.0.1.10	2	2 GB	20 GB	100 Mbps
RTPEngine	rtp01	10.0.1.20	4	4 GB	20 GB	1 Gbps
FreeSWITCH 1	fs01	10.0.1.30	4	8 GB	100 GB	1 Gbps
FreeSWITCH 2	fs02	10.0.1.31	4	8 GB	100 GB	1 Gbps
MariaDB	db01	10.0.1.40	2	4 GB	50 GB	100 Mbps

Production Setup (10+ Servers)

For production with high availability:

Role	Count	vCPU each	RAM each	Disk	Notes
Kamailio SBC	2	4	4 GB	20 GB	Active/standby with Keepalived VIP
RTPEngine	2	8	8 GB	20 GB	Stateless — either can handle any stream
FreeSWITCH	3-4	8	16 GB	500 GB	Recordings stored locally or NFS
MariaDB Galera	3	4	16 GB	200 GB	3-node cluster for quorum
Homer (SIP capture)	1	4	8 GB	500 GB	Optional but strongly recommended

Capacity Planning

Approximate capacity per server (your mileage will vary with codec, recording, and transcoding):

Component	Metric	Capacity
Kamailio (4 vCPU)	SIP transactions/sec	5,000-10,000
Kamailio (4 vCPU)	Concurrent registrations	100,000+
RTPEngine (8 vCPU)	Concurrent RTP streams	2,000-4,000
FreeSWITCH (8 vCPU, 16 GB)	Concurrent calls (G.711)	1,500-2,500
FreeSWITCH (8 vCPU, 16 GB)	Concurrent calls (with recording)	800-1,500
FreeSWITCH (8 vCPU, 16 GB)	Concurrent calls (with transcoding)	500-1,000

Network Requirements

Internal network: All components on same VLAN or low-latency private network (<1ms RTT)
External network: Kamailio and RTPEngine need public IPs (or 1:1 NAT)
Firewall: Only Kamailio and RTPEngine exposed externally; FreeSWITCH and DB are internal only
Bandwidth: RTP uses ~87 kbps per call (G.711), so 1 Gbps supports ~10,000 concurrent call streams

IP Addressing Plan

# Public IPs (exposed to internet)
YOUR_PUBLIC_VIP    = Floating VIP for Kamailio HA pair
YOUR_KAM1_PUBLIC   = Kamailio-A public IP
YOUR_KAM2_PUBLIC   = Kamailio-B public IP
YOUR_RTP1_PUBLIC   = RTPEngine-1 public IP
YOUR_RTP2_PUBLIC   = RTPEngine-2 public IP

# Private IPs (internal network — 10.0.1.0/24)
YOUR_KAM1_PRIVATE  = 10.0.1.10   # Kamailio-A
YOUR_KAM2_PRIVATE  = 10.0.1.11   # Kamailio-B
YOUR_RTP1_PRIVATE  = 10.0.1.20   # RTPEngine-1
YOUR_RTP2_PRIVATE  = 10.0.1.21   # RTPEngine-2
YOUR_FS1_IP        = 10.0.1.30   # FreeSWITCH-1
YOUR_FS2_IP        = 10.0.1.31   # FreeSWITCH-2
YOUR_FS3_IP        = 10.0.1.32   # FreeSWITCH-3
YOUR_DB1_IP        = 10.0.1.40   # MariaDB node 1
YOUR_DB2_IP        = 10.0.1.41   # MariaDB node 2
YOUR_DB3_IP        = 10.0.1.42   # MariaDB node 3

Base OS Setup (All Servers)

Run on every Debian 12 server:

#!/bin/bash
# base-setup.sh — Run on all servers

# Set timezone
timedatectl set-timezone UTC

# Update system
apt-get update && apt-get upgrade -y

# Install common packages
apt-get install -y \
    curl wget gnupg2 lsb-release apt-transport-https \
    ca-certificates software-properties-common \
    net-tools tcpdump ngrep sngrep \
    htop iotop sysstat \
    vim tmux git \
    ufw fail2ban \
    ntp

# Enable NTP (critical for SIP — clock skew breaks authentication)
systemctl enable --now ntp

# Set hostname (replace per server)
# hostnamectl set-hostname kam01.YOUR_DOMAIN

# Configure /etc/hosts on all servers
cat >> /etc/hosts << 'EOF'
10.0.1.10   kam01
10.0.1.11   kam02
10.0.1.20   rtp01
10.0.1.21   rtp02
10.0.1.30   fs01
10.0.1.31   fs02
10.0.1.32   fs03
10.0.1.40   db01
10.0.1.41   db02
10.0.1.42   db03
EOF

# Kernel tuning for VoIP
cat > /etc/sysctl.d/90-voip.conf << 'EOF'
# Network buffer sizes
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
net.core.rmem_default = 1048576
net.core.wmem_default = 1048576
net.core.netdev_max_backlog = 50000

# Connection tracking (high for SIP)
net.netfilter.nf_conntrack_max = 1000000
net.netfilter.nf_conntrack_udp_timeout = 60
net.netfilter.nf_conntrack_udp_timeout_stream = 180

# TCP tuning
net.ipv4.tcp_max_syn_backlog = 65535
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_fin_timeout = 15

# File descriptors
fs.file-max = 1000000
fs.nr_open = 1000000

# Disable SIP ALG (critical!)
net.netfilter.nf_conntrack_helper = 0
EOF
sysctl -p /etc/sysctl.d/90-voip.conf

# Increase file descriptor limits
cat > /etc/security/limits.d/voip.conf << 'EOF'
*    soft    nofile    1000000
*    hard    nofile    1000000
*    soft    nproc     65535
*    hard    nproc     65535
EOF

echo "Base setup complete. Reboot recommended."

4. Kamailio SBC Configuration

Install Kamailio with Required Modules

#!/bin/bash
# install-kamailio-sbc.sh — Run on kam01 and kam02

# Add Kamailio 5.8 repository
curl -fsSL https://deb.kamailio.org/kamailiodebkey.gpg | gpg --dearmor -o /usr/share/keyrings/kamailio.gpg
echo "deb [signed-by=/usr/share/keyrings/kamailio.gpg] http://deb.kamailio.org/kamailio58 bookworm main" \
    > /etc/apt/sources.list.d/kamailio.list
apt-get update

# Install Kamailio + all modules we need
apt-get install -y \
    kamailio \
    kamailio-mysql-modules \
    kamailio-tls-modules \
    kamailio-websocket-modules \
    kamailio-json-modules \
    kamailio-extra-modules \
    kamailio-utils-modules

# Enable Kamailio service
systemctl enable kamailio

Generate TLS Certificates

# Install certbot for Let's Encrypt
apt-get install -y certbot

# Get certificate (stop any service on port 80 first)
certbot certonly --standalone -d sip.YOUR_DOMAIN --agree-tos -m admin@YOUR_DOMAIN

# Create Kamailio TLS directory
mkdir -p /etc/kamailio/tls

# Link certificates
ln -sf /etc/letsencrypt/live/sip.YOUR_DOMAIN/fullchain.pem /etc/kamailio/tls/server.pem
ln -sf /etc/letsencrypt/live/sip.YOUR_DOMAIN/privkey.pem /etc/kamailio/tls/server.key

# Set permissions
chown -R kamailio:kamailio /etc/kamailio/tls/
chmod 600 /etc/kamailio/tls/server.key

Production kamailio.cfg

This is the complete, production-ready configuration for Kamailio operating as an SBC/load balancer in front of FreeSWITCH:

#!KAMAILIO
##
## Kamailio SBC Configuration
## Role: SIP proxy / load balancer / WebRTC gateway
## Backend: FreeSWITCH media server pool via dispatcher
##

## ---- Global Parameters ----

#!define DBURL "mysql://kamailio:YOUR_DB_PASSWORD@YOUR_DB1_IP/kamailio"
#!define FLT_NATS 5      # roles for NAT traversal
#!define FLB_NATB 6      # roles for NAT contact binding
#!define FLT_DLG  4      # roles for dialog tracking

#!define MY_PUBLIC_IP "YOUR_KAM1_PUBLIC"
#!define MY_PRIVATE_IP "YOUR_KAM1_PRIVATE"
#!define MY_DOMAIN "sip.YOUR_DOMAIN"

#!define WITH_MYSQL
#!define WITH_NAT
#!define WITH_TLS
#!define WITH_WEBSOCKETS
#!define WITH_RTPENGINE
#!define WITH_DISPATCHER
#!define WITH_ANTIFLOOD
#!define WITH_TOPOH

## ---- Core Parameters ----

debug=2
log_stderror=no
log_facility=LOG_LOCAL0
log_prefix="{$mt $hdr(CSeq) $ci} "

memdbg=5
memlog=5

fork=yes
children=8           # Worker processes — adjust based on CPU cores
tcp_children=4       # TCP/TLS/WSS worker processes

listen=udp:MY_PRIVATE_IP:5060
listen=tcp:MY_PRIVATE_IP:5060
listen=udp:MY_PUBLIC_IP:5060
listen=tcp:MY_PUBLIC_IP:5060
#!ifdef WITH_TLS
listen=tls:MY_PUBLIC_IP:5061
#!endif
#!ifdef WITH_WEBSOCKETS
listen=tcp:MY_PRIVATE_IP:8080  # WS (behind Nginx)
listen=tls:MY_PUBLIC_IP:8443   # WSS (direct or behind Nginx)
#!endif

tcp_connection_lifetime=3605
tcp_accept_no_cl=yes
tcp_rd_buf_size=16384

server_header="Server: VoIP-Platform"
user_agent_header="User-Agent: VoIP-Platform"

## ---- Module Loading ----

loadmodule "jsonrpcs.so"
loadmodule "kex.so"
loadmodule "corex.so"
loadmodule "tm.so"
loadmodule "tmx.so"
loadmodule "sl.so"
loadmodule "rr.so"
loadmodule "pv.so"
loadmodule "maxfwd.so"
loadmodule "textops.so"
loadmodule "siputils.so"
loadmodule "xlog.so"
loadmodule "sanity.so"
loadmodule "ctl.so"
loadmodule "cfg_rpc.so"
loadmodule "counters.so"
loadmodule "sdpops.so"
loadmodule "path.so"

#!ifdef WITH_MYSQL
loadmodule "db_mysql.so"
#!endif

loadmodule "usrloc.so"
loadmodule "registrar.so"

loadmodule "nathelper.so"
loadmodule "rtpengine.so"

loadmodule "dialog.so"

loadmodule "pike.so"
loadmodule "htable.so"

#!ifdef WITH_TLS
loadmodule "tls.so"
#!endif

#!ifdef WITH_WEBSOCKETS
loadmodule "websocket.so"
loadmodule "xhttp.so"
#!endif

#!ifdef WITH_DISPATCHER
loadmodule "dispatcher.so"
#!endif

#!ifdef WITH_TOPOH
loadmodule "topoh.so"
#!endif

## ---- Module Parameters ----

# -- jsonrpcs --
modparam("jsonrpcs", "pretty_format", 1)
modparam("jsonrpcs", "transport", 1)

# -- tm --
modparam("tm", "failure_reply_mode", 3)
modparam("tm", "fr_timer", 30000)         # 30s final response timeout
modparam("tm", "fr_inv_timer", 120000)    # 120s INVITE response timeout
modparam("tm", "restart_fr_on_each_reply", 1)
modparam("tm", "auto_inv_100_reason", "Trying")

# -- rr (Record-Route) --
modparam("rr", "enable_full_lr", 1)
modparam("rr", "append_fromtag", 1)
modparam("rr", "enable_double_rr", 1)    # Required for topology hiding

# -- registrar --
modparam("registrar", "method_filtering", 1)
modparam("registrar", "max_expires", 3600)
modparam("registrar", "default_expires", 300)
modparam("registrar", "gruu_enabled", 0)

# -- usrloc --
#!ifdef WITH_MYSQL
modparam("usrloc", "db_url", DBURL)
modparam("usrloc", "db_mode", 2)         # Write-through for HA
#!else
modparam("usrloc", "db_mode", 0)         # Memory only
#!endif
modparam("usrloc", "nat_bflag", FLB_NATB)

# -- nathelper --
modparam("nathelper", "natping_interval", 30)
modparam("nathelper", "ping_nated_only", 1)
modparam("nathelper", "sipping_bflag", FLB_NATB)
modparam("nathelper", "sipping_from", "sip:keepalive@MY_DOMAIN")
modparam("nathelper", "sipping_method", "OPTIONS")

# -- rtpengine --
modparam("rtpengine", "rtpengine_sock", "udp:YOUR_RTP1_PRIVATE:2223")
# For multiple RTPEngine instances:
# modparam("rtpengine", "rtpengine_sock", "udp:YOUR_RTP1_PRIVATE:2223=1 udp:YOUR_RTP2_PRIVATE:2223=1")

# -- dialog --
modparam("dialog", "dlg_flag", FLT_DLG)
modparam("dialog", "track_cseq_updates", 1)
#!ifdef WITH_MYSQL
modparam("dialog", "db_url", DBURL)
modparam("dialog", "db_mode", 1)         # Realtime for HA
modparam("dialog", "db_update_period", 60)
#!endif

# -- pike (rate limiting) --
#!ifdef WITH_ANTIFLOOD
modparam("pike", "sampling_time_unit", 2)
modparam("pike", "reqs_density_per_unit", 30)  # 30 req/2sec per IP
modparam("pike", "remove_latency", 4)
#!endif

# -- htable (hash tables for rate limiting / blacklisting) --
modparam("htable", "htable", "blocked=>size=8;autoexpire=300;")
modparam("htable", "htable", "failcnt=>size=8;autoexpire=60;initval=0;")

# -- dispatcher --
#!ifdef WITH_DISPATCHER
modparam("dispatcher", "db_url", DBURL)
modparam("dispatcher", "ds_ping_method", "OPTIONS")
modparam("dispatcher", "ds_ping_interval", 10)      # Ping every 10 seconds
modparam("dispatcher", "ds_ping_reply_codes", "class2;class3;class4")
modparam("dispatcher", "ds_probing_mode", 1)         # Probe all destinations
modparam("dispatcher", "ds_probing_threshold", 3)    # 3 failures = inactive
modparam("dispatcher", "ds_inactive_threshold", 3)   # 3 successes = active again
modparam("dispatcher", "ds_ping_latency_stats", 1)
#!endif

# -- TLS --
#!ifdef WITH_TLS
modparam("tls", "config", "/etc/kamailio/tls.cfg")
modparam("tls", "tls_force_run", 1)
#!endif

# -- WebSocket --
#!ifdef WITH_WEBSOCKETS
modparam("websocket", "keepalive_mechanism", 1)      # PING frames
modparam("websocket", "keepalive_timeout", 30)
modparam("websocket", "keepalive_processes", 1)
#!endif

# -- topoh (topology hiding) --
#!ifdef WITH_TOPOH
modparam("topoh", "mask_ip", "255.255.255.255")
modparam("topoh", "mask_callid", 1)
modparam("topoh", "th_callid_prefix", "VoIP-")
modparam("topoh", "th_ip_prefix", "sbc.")
#!endif

## ==== Routing Logic ====

## ---- Main Request Route ----
request_route {
    # Per-request logging
    xlog("L_INFO", ">>> $rm from $fu ($si:$sp) to $ru\n");

    # Max forwards check
    if (!mf_process_maxfwd_header("10")) {
        sl_send_reply("483", "Too Many Hops");
        exit;
    }

    # Sanity checks
    if (!sanity_check("17895", "7")) {
        xlog("L_WARN", "Malformed SIP from $si:$sp\n");
        exit;
    }

    # ---- Anti-flood / DDoS Protection ----
    #!ifdef WITH_ANTIFLOOD
    route(ANTIFLOOD);
    #!endif

    # ---- Handle WebSocket connections ----
    #!ifdef WITH_WEBSOCKETS
    if (proto == WS || proto == WSS) {
        # WebSocket SIP — force record-route with WS
        if (is_method("REGISTER")) {
            # Allow WS registrations
        }
    }
    #!endif

    # ---- CANCEL processing ----
    if (is_method("CANCEL")) {
        if (t_check_trans()) {
            route(RTPENGINE_DELETE);
            t_relay();
        }
        exit;
    }

    # ---- Retransmission handling ----
    if (!is_method("ACK")) {
        if (t_precheck_trans()) {
            t_check_trans();
            exit;
        }
        t_check_trans();
    }

    # ---- Record-Route for dialogs ----
    if (is_method("INVITE|SUBSCRIBE")) {
        record_route();
    }

    # ---- Sequential requests (in-dialog) ----
    if (has_totag()) {
        route(WITHINDLG);
        exit;
    }

    # ---- Initial requests ----

    # Handle REGISTER
    if (is_method("REGISTER")) {
        route(REGISTRAR);
        exit;
    }

    # Handle OPTIONS (keepalive)
    if (is_method("OPTIONS") && uri == myself) {
        sl_send_reply("200", "OK");
        exit;
    }

    # Handle INVITE — main call processing
    if (is_method("INVITE")) {
        # Enable dialog tracking
        setflag(FLT_DLG);
        dlg_manage();

        # NAT detection and fixing
        route(NATDETECT);

        # RTPEngine: offer (external→internal bridging)
        route(RTPENGINE_OFFER);

        # Dispatch to FreeSWITCH pool
        route(DISPATCH);
        exit;
    }

    # Handle other methods
    if (is_method("NOTIFY|INFO|UPDATE|PRACK")) {
        route(RELAY);
        exit;
    }

    # Reject anything else
    sl_send_reply("405", "Method Not Allowed");
    exit;
}


## ---- In-Dialog Request Routing ----
route[WITHINDLG] {
    if (!loose_route()) {
        if (is_method("ACK")) {
            if (!t_check_trans()) {
                # ACK without matching transaction — absorb
                exit;
            }
        }
        sl_send_reply("404", "Not Found");
        exit;
    }

    if (is_method("ACK")) {
        route(NATMANAGE);
    } else if (is_method("BYE")) {
        route(RTPENGINE_DELETE);
    } else if (is_method("INVITE")) {
        # Re-INVITE — handle RTPEngine for media changes
        route(NATDETECT);
        route(RTPENGINE_OFFER);
    }

    route(RELAY);
    exit;
}


## ---- Relay Route ----
route[RELAY] {
    if (is_method("INVITE|BYE|SUBSCRIBE|UPDATE|REFER")) {
        if (!t_is_set("branch_route")) {
            t_on_branch("MANAGE_BRANCH");
        }
    }
    if (is_method("INVITE|SUBSCRIBE|UPDATE")) {
        if (!t_is_set("onreply_route")) {
            t_on_reply("MANAGE_REPLY");
        }
    }
    if (is_method("INVITE")) {
        if (!t_is_set("failure_route")) {
            t_on_failure("MANAGE_FAILURE");
        }
    }

    if (!t_relay()) {
        sl_reply_error();
    }
    exit;
}


## ---- REGISTER Handling ----
route[REGISTRAR] {
    # NAT detection for registrations
    route(NATDETECT);

    # Option 1: Store locally (Kamailio manages registrations)
    if (!save("location")) {
        sl_reply_error();
    }
    exit;

    # Option 2: Proxy registrations to FreeSWITCH (uncomment if FS manages registrations)
    # route(DISPATCH);
    # exit;
}


## ---- Dispatcher — Load Balance to FreeSWITCH ----
route[DISPATCH] {
    # Set 1 = FreeSWITCH media servers
    # Algorithm 0 = hash over callid (sticky sessions — in-dialog goes to same FS)
    # Flags: 2 = failover support, 4 = use only active destinations
    if (!ds_select_dst("1", "0", "6")) {
        xlog("L_ERR", "DISPATCH: No FreeSWITCH servers available!\n");
        sl_send_reply("503", "Service Unavailable");
        exit;
    }

    xlog("L_INFO", "DISPATCH: Routing $rm to $du (FS pool)\n");

    t_on_failure("DISPATCH_FAILURE");
    route(RELAY);
    exit;
}


## ---- NAT Detection ----
route[NATDETECT] {
    force_rport();
    if (nat_uac_test("19")) {
        # Client is behind NAT
        setflag(FLT_NATS);
        setbflag(FLB_NATB);

        if (is_first_hop()) {
            set_contact_alias();
        }
    }
}


## ---- NAT Management ----
route[NATMANAGE] {
    if (is_request()) {
        if (has_totag()) {
            if (check_route_param("nat=yes")) {
                setbflag(FLB_NATB);
            }
        }
    }
    if (isbflagset(FLB_NATB)) {
        if (is_request()) {
            add_contact_alias();
        } else {
            add_contact_alias();
        }
    }
}


## ---- RTPEngine Routes ----
route[RTPENGINE_OFFER] {
    if (!is_method("INVITE|UPDATE")) return;
    if (!has_body("application/sdp")) return;

    $var(rtpflags) = "replace-origin replace-session-connection";

    # Determine direction based on source
    if ($si == "YOUR_FS1_IP" || $si == "YOUR_FS2_IP" || $si == "YOUR_FS3_IP") {
        # From FreeSWITCH → going external
        $var(rtpflags) = $var(rtpflags) + " direction=internal direction=external";
    } else {
        # From external → going to FreeSWITCH
        $var(rtpflags) = $var(rtpflags) + " direction=external direction=internal";
    }

    # WebRTC client — need ICE and DTLS
    if (proto == WS || proto == WSS) {
        $var(rtpflags) = $var(rtpflags) + " ICE=force DTLS=passive SDES-off";
    }

    rtpengine_offer("$var(rtpflags)");
}

route[RTPENGINE_ANSWER] {
    if (!has_body("application/sdp")) return;

    $var(rtpflags) = "replace-origin replace-session-connection";

    # Mirror the direction logic from the offer
    if ($si == "YOUR_FS1_IP" || $si == "YOUR_FS2_IP" || $si == "YOUR_FS3_IP") {
        $var(rtpflags) = $var(rtpflags) + " direction=internal direction=external";
    } else {
        $var(rtpflags) = $var(rtpflags) + " direction=external direction=internal";
    }

    if (proto == WS || proto == WSS) {
        $var(rtpflags) = $var(rtpflags) + " ICE=force DTLS=passive SDES-off";
    }

    rtpengine_answer("$var(rtpflags)");
}

route[RTPENGINE_DELETE] {
    rtpengine_delete();
}


## ---- Anti-Flood Protection ----
#!ifdef WITH_ANTIFLOOD
route[ANTIFLOOD] {
    # Skip checks for trusted IPs (FreeSWITCH servers, trunks)
    if ($si == "YOUR_FS1_IP" || $si == "YOUR_FS2_IP" || $si == "YOUR_FS3_IP") {
        return;
    }

    # Check if IP is in blocked table
    if ($sht(blocked=>$si) != $null) {
        xlog("L_WARN", "ANTIFLOOD: Blocked request from $si\n");
        exit;
    }

    # Pike rate limiter
    if (!pike_check_req()) {
        xlog("L_ALERT", "ANTIFLOOD: Pike blocking $si — rate limit exceeded\n");
        $sht(blocked=>$si) = 1;    # Block for 300 seconds (htable autoexpire)
        exit;
    }
}
#!endif


## ---- Branch Route ----
branch_route[MANAGE_BRANCH] {
    xlog("L_DBG", "BRANCH: new branch [$T_branch_idx] to $ru\n");
    route(NATMANAGE);
}


## ---- Reply Route ----
onreply_route[MANAGE_REPLY] {
    xlog("L_DBG", "REPLY: $rs $rr from $si\n");

    if (status =~ "[12][0-9][0-9]") {
        route(NATMANAGE);
    }

    # RTPEngine answer on 183/200 with SDP
    if (status =~ "(183|200)" && has_body("application/sdp")) {
        route(RTPENGINE_ANSWER);
    }
}


## ---- Failure Route — Dispatcher Failover ----
failure_route[DISPATCH_FAILURE] {
    if (t_is_canceled()) exit;

    xlog("L_WARN", "DISPATCH_FAILURE: $rs from $du — trying next FS\n");

    # On failure (timeout, 5xx), try next server
    if (t_check_status("5[0-9][0-9]") || t_check_status("408")) {
        # Clean up RTPEngine session for failed branch
        route(RTPENGINE_DELETE);

        # Try next dispatcher destination
        if (ds_next_dst()) {
            xlog("L_INFO", "DISPATCH_FAILURE: Failing over to $du\n");
            route(RTPENGINE_OFFER);
            route(RELAY);
            exit;
        }
    }

    # All dispatchers failed
    xlog("L_ERR", "DISPATCH_FAILURE: All FreeSWITCH servers failed\n");
    send_reply("503", "All Media Servers Unavailable");
}

failure_route[MANAGE_FAILURE] {
    if (t_is_canceled()) exit;

    xlog("L_WARN", "FAILURE: $rs for $rm to $ru\n");
}


## ---- WebSocket HTTP Handling ----
#!ifdef WITH_WEBSOCKETS
event_route[xhttp:request] {
    set_reply_close();
    set_reply_no_connect();

    if ($hdr(Upgrade) =~ "websocket" &&
        $hdr(Connection) =~ "Upgrade" &&
        $rm =~ "GET") {

        # Validate WebSocket handshake
        if ($hdr(Sec-WebSocket-Protocol) =~ "sip") {
            # Accept the WebSocket upgrade
            if (ws_handle_handshake()) {
                exit;
            }
        }
    }

    # Not a WebSocket request — return 403
    xhttp_reply("403", "Forbidden", "text/html",
        "<html><body>Forbidden</body></html>");
}
#!endif

TLS Configuration

Create /etc/kamailio/tls.cfg:

# /etc/kamailio/tls.cfg

[server:default]
method = TLSv1.2+
certificate = /etc/kamailio/tls/server.pem
private_key = /etc/kamailio/tls/server.key
verify_certificate = no
require_certificate = no
cipher_list = HIGH:!aNULL:!MD5:!DSS

[client:default]
method = TLSv1.2+
verify_certificate = no

Initialize Kamailio Database

# Create the Kamailio database and tables
kamdbctl create

# When prompted:
# MySQL password for root: (your MySQL root password)
# Database name: kamailio (default)
# Install extra tables? Yes
# Install presence tables? No (not needed for SBC role)

# Verify tables exist
mysql -u kamailio -pYOUR_DB_PASSWORD kamailio -e "SHOW TABLES;"

Firewall Rules for Kamailio

# UFW firewall rules for Kamailio SBC
ufw default deny incoming
ufw default allow outgoing

# SSH
ufw allow 22/tcp

# SIP (UDP + TCP)
ufw allow 5060/udp
ufw allow 5060/tcp

# SIP TLS
ufw allow 5061/tcp

# WebSocket (WSS)
ufw allow 8443/tcp

# Allow all traffic from internal network
ufw allow from 10.0.1.0/24

# Enable firewall
ufw enable

Start and Verify

# Check configuration syntax
kamailio -c /etc/kamailio/kamailio.cfg

# Start Kamailio
systemctl start kamailio

# Verify it is listening
ss -ulnp | grep kamailio
ss -tlnp | grep kamailio

# Check logs
journalctl -u kamailio -f

# Test SIP response
sipgrep -p 5060 &
sipsak -s sip:test@YOUR_KAM1_PUBLIC:5060

5. Dispatcher — Load Balancing FreeSWITCH

Understanding Dispatcher

The dispatcher module is Kamailio's built-in load balancer. It maintains a list of backend servers organized in destination sets (groups), monitors their health via SIP OPTIONS pings, and distributes traffic using configurable algorithms.

Dispatcher Algorithms

Algorithm	ID	Description	Best For
Hash over Call-ID	0	Same Call-ID always goes to same server	Standard calls — in-dialog requests stay together
Hash over From URI	1	Same caller always goes to same server	User affinity
Hash over To URI	2	Same destination always goes to same server	DID-based routing
Hash over Request-URI	3	Same R-URI goes to same server	Service-based routing
Round-robin	4	Sequential rotation through servers	Even distribution
Hash over auth username	5	Authenticated user affinity	Registered users
Random	6	Random selection	Simple load spreading
Hash over PV	7	Hash over any pseudo-variable	Custom logic
Weight-based	8	Proportional distribution by weight	Heterogeneous servers
Call load	9	Least connections (tracks active calls)	Best for even load
Relative weight	10	Weight-based with relative proportions	Mixed-capacity servers

Recommended for VoIP: Algorithm 0 (Call-ID hash) ensures all SIP messages for the same call go to the same FreeSWITCH. Algorithm 9 (call load distribution) gives the most even load if you use stateless mode.

Why Call-ID Hash Matters

SIP calls involve multiple transactions:

INVITE → 100 Trying → 180 Ringing → 200 OK → ACK
  ... call in progress ...
re-INVITE (hold/resume)
BYE → 200 OK

All messages for the same call must reach the same FreeSWITCH. Call-ID hash guarantees this because the Call-ID header is constant for the entire call. Without it, a re-INVITE or BYE could go to a different FreeSWITCH that knows nothing about the call.

Database-Backed Dispatcher Configuration

Populate the dispatcher table:

-- Connect to kamailio database
USE kamailio;

-- Destination set 1: FreeSWITCH media servers
-- Columns: id, setid, destination, flags, priority, attrs, description

INSERT INTO dispatcher (setid, destination, flags, priority, attrs, description)
VALUES
(1, 'sip:YOUR_FS1_IP:5060', 0, 0, 'weight=50;duid=fs01', 'FreeSWITCH-1 Media'),
(1, 'sip:YOUR_FS2_IP:5060', 0, 0, 'weight=50;duid=fs02', 'FreeSWITCH-2 Media'),
(1, 'sip:YOUR_FS3_IP:5060', 0, 0, 'weight=50;duid=fs03', 'FreeSWITCH-3 Media');

-- Destination set 2: Conference-dedicated FreeSWITCH (optional)
-- Useful to route high-resource conference calls to dedicated servers
INSERT INTO dispatcher (setid, destination, flags, priority, attrs, description)
VALUES
(2, 'sip:YOUR_FS3_IP:5060', 0, 0, 'weight=100;duid=fs03-conf', 'FreeSWITCH-3 Conference');

-- Verify
SELECT * FROM dispatcher;

Dispatcher Flags and Options

Flags in ds_select_dst("setid", "algorithm", "flags"):

  Flag 1:  Try next destination on failure (basic failover)
  Flag 2:  Store all destination addresses (for ds_next_dst)
  Flag 4:  Skip inactive destinations (honor probing results)
  Flag 8:  Select from active only (same as 4, explicit)
  Flag 16: Use addresses from AVP as destination set

Common combinations:
  6  = 2 + 4 = Store all + skip inactive (recommended)
  14 = 2 + 4 + 8 = Full failover with active-only selection

Enhanced Dispatch Route

Here is an improved dispatch route with monitoring and logging:

## ---- Advanced Dispatcher Route ----
route[DISPATCH] {
    # Determine dispatch set based on call type
    $var(dispatch_set) = 1;    # Default: general media servers

    # Route conference calls to dedicated set (if configured)
    if ($rU =~ "^conf[0-9]+$") {
        $var(dispatch_set) = 2;
    }

    # Select destination with:
    #   Algorithm 0 = Call-ID hash (sticky sessions)
    #   Flags 6 = failover support (2) + skip inactive (4)
    if (!ds_select_dst("$var(dispatch_set)", "0", "6")) {
        xlog("L_ERR", "DISPATCH: No destinations available in set $var(dispatch_set)!\n");

        # Try fallback set if primary set is empty
        if ($var(dispatch_set) != 1) {
            xlog("L_WARN", "DISPATCH: Falling back to general set 1\n");
            if (!ds_select_dst("1", "0", "6")) {
                sl_send_reply("503", "Service Unavailable — No Media Servers");
                exit;
            }
        } else {
            sl_send_reply("503", "Service Unavailable — No Media Servers");
            exit;
        }
    }

    # Log the selected destination
    xlog("L_INFO", "DISPATCH: $rm $fu → $du (set=$var(dispatch_set))\n");

    # Set failure route for failover
    t_on_failure("DISPATCH_FAILURE");
    route(RELAY);
    exit;
}


## ---- Dispatcher Failure Route ----
failure_route[DISPATCH_FAILURE] {
    if (t_is_canceled()) exit;

    # Only failover on server errors or timeouts
    if (t_check_status("5[0-9][0-9]") || t_check_status("408")) {
        xlog("L_WARN", "DISPATCH_FAILURE: $rs from $du — trying next\n");

        # Mark this destination as probing (will be checked by OPTIONS pings)
        ds_mark_dst("p");

        # Clean up RTPEngine for the failed branch
        route(RTPENGINE_DELETE);

        # Try next destination in the set
        if (ds_next_dst()) {
            xlog("L_INFO", "DISPATCH_FAILURE: Failover to $du\n");
            route(RTPENGINE_OFFER);
            route(RELAY);
            exit;
        }

        xlog("L_ERR", "DISPATCH_FAILURE: All servers exhausted\n");
    }

    # 4xx responses: pass through to caller (authentication errors, etc.)
    if (t_check_status("4[0-9][0-9]")) {
        xlog("L_INFO", "DISPATCH_FAILURE: 4xx response $rs — passing through\n");
    }
}

Runtime Dispatcher Management

# List all dispatcher destinations and their status
kamcmd dispatcher.list

# Output example:
# DEST: {
#   URI: sip:10.0.1.30:5060
#   FLAGS: AP    (A=Active, P=Probing enabled)
#   PRIORITY: 0
#   LATENCY: {
#     AVG: 2.450ms
#     MAX: 8.120ms
#     TIMEOUT: 0
#   }
# }

# Manually set a destination as inactive (for maintenance)
kamcmd dispatcher.set_state i 1 sip:YOUR_FS1_IP:5060

# State codes: a=active, i=inactive, d=disabled, p=probing

# Re-enable a destination after maintenance
kamcmd dispatcher.set_state a 1 sip:YOUR_FS1_IP:5060

# Reload dispatcher table from database (after adding/removing servers)
kamcmd dispatcher.reload

# Check the number of active destinations per set
kamcmd dispatcher.list | grep -c "FLAGS: AP"

Probing Configuration Details

The probing system sends SIP OPTIONS pings to each backend to detect failures:

Sequence:
1. Kamailio sends OPTIONS to FreeSWITCH every ds_ping_interval seconds
2. FreeSWITCH responds with 200 OK (healthy) or no response (down)
3. After ds_probing_threshold consecutive failures → destination marked INACTIVE
4. Probing continues on inactive destinations
5. After ds_inactive_threshold consecutive successes → destination marked ACTIVE

Timeline example (ds_ping_interval=10, ds_probing_threshold=3):
  t=0s   OPTIONS → FS1: 200 OK       (active, count=0)
  t=10s  OPTIONS → FS1: timeout       (active, fail_count=1)
  t=20s  OPTIONS → FS1: timeout       (active, fail_count=2)
  t=30s  OPTIONS → FS1: timeout       (INACTIVE, fail_count=3)  ← traffic stops
  t=40s  OPTIONS → FS1: 200 OK        (inactive, ok_count=1)    ← still probing
  t=50s  OPTIONS → FS1: 200 OK        (inactive, ok_count=2)
  t=60s  OPTIONS → FS1: 200 OK        (ACTIVE, ok_count=3)      ← traffic resumes

Detection time: 30 seconds (3 failures x 10 second interval). For faster detection, reduce ds_ping_interval to 5 seconds, but be aware of the additional OPTIONS traffic.

6. RTPEngine — Media Relay

Why RTPEngine?

In the Kamailio + FreeSWITCH architecture, RTPEngine solves critical media-layer problems:

Problem	RTPEngine Solution
NAT traversal (media)	Relays RTP through a public IP — no direct path needed between endpoints
WebRTC ↔ SIP bridging	Converts DTLS-SRTP (WebRTC) ↔ plain RTP (SIP)
Topology hiding (media)	External parties see RTPEngine's IP, not FreeSWITCH's internal IP
Codec transcoding	Converts between codecs (e.g., G.729 ↔ G.711) without burdening FreeSWITCH
Call recording	Can record RTP streams to pcap files
SRTP	Terminates and originates SRTP for encrypted calls

Without RTPEngine, you would need FreeSWITCH on a public IP (security risk) or complex iptables NAT rules (fragile and hard to scale).

Install RTPEngine on Debian 12

#!/bin/bash
# install-rtpengine.sh — Run on rtp01 and rtp02

# Add Sipwise repository for RTPEngine
echo "deb [signed-by=/usr/share/keyrings/sipwise.gpg] https://deb.sipwise.com/spce/mr12.5.1/ bookworm main" \
    > /etc/apt/sources.list.d/sipwise.list

curl -fsSL https://deb.sipwise.com/spce/keyring/sipwise-keyring-bootstrap.gpg | \
    gpg --dearmor -o /usr/share/keyrings/sipwise.gpg

apt-get update

# Install RTPEngine
apt-get install -y rtpengine

# If the Sipwise repo is not available, build from source:
# apt-get install -y build-essential dpkg-dev debhelper iptables-dev \
#     libavcodec-dev libavfilter-dev libavformat-dev libavutil-dev \
#     libbencode-perl libcrypt-openssl-rsa-perl libcrypt-rijndael-perl \
#     libcurl4-openssl-dev libdigest-hmac-perl libevent-dev \
#     libglib2.0-dev libhiredis-dev libio-multiplex-perl \
#     libio-socket-inet6-perl libjson-glib-dev libmnl-dev \
#     libnet-interface-perl libnftnl-dev libpcap0.8-dev \
#     libpcre3-dev libspandsp-dev libssl-dev libsystemd-dev \
#     libwebsockets-dev libxmlrpc-core-c3-dev markdown nfs-common \
#     pandoc
#
# git clone https://github.com/sipwise/rtpengine.git
# cd rtpengine
# dpkg-buildpackage -b -uc -us
# dpkg -i ../rtpengine_*.deb

RTPEngine Configuration

Create /etc/rtpengine/rtpengine.conf:

# /etc/rtpengine/rtpengine.conf
# RTPEngine configuration for Kamailio + FreeSWITCH platform

[rtpengine]
# Control socket — Kamailio connects here
listen-ng = YOUR_RTP1_PRIVATE:2223

# Network interfaces
# Format: label/IP or label/internal_IP!external_IP
# "internal" = towards FreeSWITCH (private network)
# "external" = towards the internet (public IP)
interface = internal/YOUR_RTP1_PRIVATE
interface = external/YOUR_RTP1_PRIVATE!YOUR_RTP1_PUBLIC

# RTP port range
port-min = 20000
port-max = 40000

# Timeouts
timeout = 60              # RTP timeout (no media received)
silent-timeout = 3600     # Timeout for calls with no RTP at all
final-timeout = 7200      # Hard maximum call duration

# TOS/DSCP for QoS
tos = 184                 # EF (Expedited Forwarding) for voice

# Recording (optional — pcap files)
# recording-dir = /var/spool/rtpengine
# recording-method = pcap

# Codec transcoding support
# Requires compilation with ffmpeg/libavcodec
# allow-transcoding = true

# Logging
log-level = 5             # 5=notice, 6=info, 7=debug
log-facility = daemon
log-facility-cdr = local1

# Process settings
pidfile = /run/rtpengine/rtpengine.pid
foreground = false
num-threads = 0           # 0 = auto (one per CPU core)

# Table (iptables/nftables kernel module — for kernel-space forwarding)
# table = 0               # Uncomment for kernel-space RTP relay (better performance)
# no-fallback = false

Systemd Service

Create or edit /etc/systemd/system/rtpengine.service:

[Unit]
Description=RTPEngine Media Proxy
After=network.target
Requires=network.target

[Service]
Type=forking
PIDFile=/run/rtpengine/rtpengine.pid
ExecStartPre=/bin/mkdir -p /run/rtpengine
ExecStartPre=/bin/chown rtpengine:rtpengine /run/rtpengine
ExecStart=/usr/bin/rtpengine --config-file=/etc/rtpengine/rtpengine.conf
ExecStop=/bin/kill -TERM $MAINPID
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

Firewall Rules for RTPEngine

# Control interface — only from Kamailio
ufw allow from YOUR_KAM1_PRIVATE to any port 2223 proto udp
ufw allow from YOUR_KAM2_PRIVATE to any port 2223 proto udp

# RTP port range — from anywhere (media comes from external endpoints)
ufw allow 20000:40000/udp

# SSH
ufw allow 22/tcp

ufw enable

Start and Verify RTPEngine

# Start the service
systemctl daemon-reload
systemctl enable --now rtpengine

# Check it is running
systemctl status rtpengine

# Verify listening
ss -ulnp | grep rtpengine

# Test the control interface (from Kamailio server)
echo 'd7:command4:pinge' | nc -u YOUR_RTP1_PRIVATE 2223
# Should respond with: d6:result4:ponge

# Check active sessions (from RTPEngine server)
rtpengine-ctl list sessions

Kamailio ↔ RTPEngine Integration

The rtpengine module in Kamailio communicates with RTPEngine via the ng (next-generation) control protocol over UDP. The flow is:

Inbound INVITE (with SDP):
1. Kamailio receives INVITE from external trunk
2. route(RTPENGINE_OFFER): Kamailio sends "offer" to RTPEngine
   - RTPEngine allocates UDP ports for RTP relay
   - RTPEngine rewrites SDP: external endpoint ↔ RTPEngine ↔ internal FreeSWITCH
   - SDP in INVITE now points to RTPEngine's internal IP (towards FreeSWITCH)
3. Kamailio forwards modified INVITE to FreeSWITCH
4. FreeSWITCH sends 200 OK (with SDP)
5. onreply_route: Kamailio sends "answer" to RTPEngine
   - RTPEngine rewrites SDP in 200 OK: FreeSWITCH → RTPEngine's external IP
6. Kamailio sends modified 200 OK to external trunk
7. Media flows: External ↔ RTPEngine (external iface) ↔ RTPEngine (internal iface) ↔ FreeSWITCH

SDP Manipulation Example

Original SDP from external trunk:
  c=IN IP4 203.0.113.50      ← trunk's RTP IP
  m=audio 30000 RTP/AVP 0 8  ← trunk's RTP port

After rtpengine_offer() — SDP sent to FreeSWITCH:
  c=IN IP4 10.0.1.20         ← RTPEngine's INTERNAL interface
  m=audio 20100 RTP/AVP 0 8  ← RTPEngine's allocated port (internal side)

FreeSWITCH answers with SDP:
  c=IN IP4 10.0.1.30         ← FreeSWITCH's IP
  m=audio 19200 RTP/AVP 0    ← FreeSWITCH's RTP port

After rtpengine_answer() — SDP sent to external trunk:
  c=IN IP4 YOUR_RTP1_PUBLIC  ← RTPEngine's EXTERNAL interface
  m=audio 20200 RTP/AVP 0    ← RTPEngine's allocated port (external side)

Result: External trunk sends RTP to RTPEngine's public IP
        RTPEngine relays to FreeSWITCH on private network
        Neither party knows the other's real IP

RTPEngine Clustering

For high availability, run multiple RTPEngine instances. Kamailio can be configured to use them:

# In kamailio.cfg — multiple RTPEngine backends
# Format: "udp:IP:PORT=weight udp:IP:PORT=weight"
modparam("rtpengine", "rtpengine_sock",
    "udp:YOUR_RTP1_PRIVATE:2223=1 udp:YOUR_RTP2_PRIVATE:2223=1")

RTPEngine instances are stateless from a clustering perspective — each instance independently manages its own RTP sessions. Kamailio uses consistent hashing (based on Call-ID) to ensure that offer, answer, and delete for the same call go to the same RTPEngine instance.

If an RTPEngine instance goes down:

Existing calls on that instance lose media (unavoidable — RTP state is local)
New calls are automatically routed to the surviving instance
Kamailio detects the failure via the control socket timeout

7. FreeSWITCH Media Server Configuration

Design Principle: Headless Media Server

When FreeSWITCH runs behind Kamailio, its role changes:

Traditional FreeSWITCH	Behind Kamailio
Handles SIP registration	Kamailio handles registration
Manages NAT traversal	RTPEngine handles NAT
Authenticates SIP peers	Kamailio authenticates
Exposed to internet	Internal network only
Processes all SIP methods	Only receives pre-routed calls
Single instance	Multiple instances in a pool

FreeSWITCH becomes a headless media application server — it focuses purely on call logic, media processing, and application features.

Install FreeSWITCH

#!/bin/bash
# install-freeswitch.sh — Run on fs01, fs02, fs03

# Add SignalWire repository
TOKEN="YOUR_SIGNALWIRE_TOKEN"  # Get from signalwire.com (free account)

apt-get install -y gnupg2 lsb-release

curl -fsSL https://freeswitch.signalwire.com/repo/deb/debian-release/signalwire-freeswitch-repo.gpg \
    > /usr/share/keyrings/signalwire-freeswitch-repo.gpg

echo "machine freeswitch.signalwire.com login signalwire password $TOKEN" > /etc/apt/auth.conf
chmod 600 /etc/apt/auth.conf

echo "deb [signed-by=/usr/share/keyrings/signalwire-freeswitch-repo.gpg] \
    https://freeswitch.signalwire.com/repo/deb/debian-release/ bookworm main" \
    > /etc/apt/sources.list.d/freeswitch.list

apt-get update

# Install FreeSWITCH with common modules
apt-get install -y \
    freeswitch-meta-codecs \
    freeswitch-mod-commands \
    freeswitch-mod-conference \
    freeswitch-mod-console \
    freeswitch-mod-db \
    freeswitch-mod-dialplan-xml \
    freeswitch-mod-dptools \
    freeswitch-mod-enum \
    freeswitch-mod-event-socket \
    freeswitch-mod-fifo \
    freeswitch-mod-hash \
    freeswitch-mod-httapi \
    freeswitch-mod-local-stream \
    freeswitch-mod-logfile \
    freeswitch-mod-loopback \
    freeswitch-mod-native-file \
    freeswitch-mod-say-en \
    freeswitch-mod-sndfile \
    freeswitch-mod-sofia \
    freeswitch-mod-tone-stream \
    freeswitch-mod-voicemail \
    freeswitch-mod-xml-cdr \
    freeswitch-mod-xml-curl

systemctl enable freeswitch

SIP Profile — Internal Only

FreeSWITCH should only accept SIP from Kamailio. Create a dedicated SIP profile.

Edit /etc/freeswitch/sip_profiles/kamailio.xml:

<!--
  FreeSWITCH SIP Profile: kamailio
  Purpose: Accept calls only from Kamailio SBC
  This profile listens on the private network and trusts Kamailio
-->
<profile name="kamailio">
  <settings>
    <!-- Listen only on private network -->
    <param name="sip-ip" value="$${local_ip_v4}"/>
    <param name="sip-port" value="5060"/>
    <param name="rtp-ip" value="$${local_ip_v4}"/>

    <!-- Disable RTP timer — RTPEngine handles media relay/timeout -->
    <param name="rtp-timeout-sec" value="0"/>
    <param name="rtp-hold-timeout-sec" value="0"/>

    <!-- Dialplan context for calls from Kamailio -->
    <param name="context" value="from-kamailio"/>

    <!-- Disable authentication — Kamailio already authenticated the call -->
    <param name="challenge-realm" value="auto_from"/>

    <!-- Accept all calls from trusted IPs (Kamailio) -->
    <param name="apply-inbound-acl" value="kamailio-acl"/>

    <!-- Disable registration on this profile -->
    <param name="accept-blind-reg" value="false"/>

    <!-- Codec preferences -->
    <param name="inbound-codec-prefs" value="PCMA,PCMU,G722,opus"/>
    <param name="outbound-codec-prefs" value="PCMA,PCMU,G722,opus"/>
    <param name="inbound-codec-negotiation" value="generous"/>

    <!-- Dialog management -->
    <param name="manage-presence" value="false"/>
    <param name="manage-shared-appearance" value="false"/>

    <!-- Pass-through — let Kamailio handle NAT -->
    <param name="aggressive-nat-detection" value="false"/>
    <param name="local-network-acl" value="localnet.auto"/>

    <!-- SIP options -->
    <param name="disable-transfer" value="false"/>
    <param name="enable-timer" value="false"/>
    <param name="enable-100rel" value="false"/>

    <!-- Logging -->
    <param name="log-auth-failures" value="true"/>
    <param name="debug" value="0"/>
  </settings>
</profile>

ACL — Only Accept from Kamailio

Edit /etc/freeswitch/autoload_configs/acl.conf.xml:

<configuration name="acl.conf" description="Network ACL">
  <network-lists>
    <!-- Kamailio SBC servers -->
    <list name="kamailio-acl" default="deny">
      <node type="allow" cidr="YOUR_KAM1_PRIVATE/32"/>
      <node type="allow" cidr="YOUR_KAM2_PRIVATE/32"/>
    </list>

    <!-- RTPEngine servers (for direct media) -->
    <list name="rtpengine-acl" default="deny">
      <node type="allow" cidr="YOUR_RTP1_PRIVATE/32"/>
      <node type="allow" cidr="YOUR_RTP2_PRIVATE/32"/>
    </list>

    <!-- Internal network -->
    <list name="internal-acl" default="deny">
      <node type="allow" cidr="10.0.1.0/24"/>
    </list>
  </network-lists>
</configuration>

Disable Default External Profile

FreeSWITCH ships with internal and external profiles that listen on default ports. Disable them since we use our custom kamailio profile:

# Disable default profiles (move them out of the way)
mv /etc/freeswitch/sip_profiles/internal.xml /etc/freeswitch/sip_profiles/internal.xml.disabled
mv /etc/freeswitch/sip_profiles/external.xml /etc/freeswitch/sip_profiles/external.xml.disabled

# If you need the internal profile for registered extensions, keep it
# but change its port to avoid conflict:
# <param name="sip-port" value="5080"/>

Dialplan — Calls from Kamailio

Create /etc/freeswitch/dialplan/from-kamailio.xml:

<!--
  Dialplan context: from-kamailio
  Handles all calls dispatched by the Kamailio SBC
-->
<include>
  <context name="from-kamailio">

    <!-- ============================================ -->
    <!-- IVR: Main Auto-Attendant                    -->
    <!-- ============================================ -->
    <extension name="main-ivr">
      <condition field="destination_number" expression="^(ivr|2000)$">
        <action application="answer"/>
        <action application="sleep" data="500"/>
        <action application="ivr" data="main_ivr"/>
      </condition>
    </extension>

    <!-- ============================================ -->
    <!-- Call Queue: Sales                           -->
    <!-- ============================================ -->
    <extension name="queue-sales">
      <condition field="destination_number" expression="^(sales|3001)$">
        <action application="answer"/>
        <action application="set" data="fifo_music=/usr/share/freeswitch/sounds/music/hold.wav"/>
        <action application="fifo" data="sales@${domain_name} in"/>
      </condition>
    </extension>

    <!-- ============================================ -->
    <!-- Call Queue: Support                         -->
    <!-- ============================================ -->
    <extension name="queue-support">
      <condition field="destination_number" expression="^(support|3002)$">
        <action application="answer"/>
        <action application="set" data="fifo_music=/usr/share/freeswitch/sounds/music/hold.wav"/>
        <action application="fifo" data="support@${domain_name} in"/>
      </condition>
    </extension>

    <!-- ============================================ -->
    <!-- Conference Bridge                           -->
    <!-- ============================================ -->
    <extension name="conference">
      <condition field="destination_number" expression="^conf(\d+)$">
        <action application="answer"/>
        <action application="conference" data="room-$1@default"/>
      </condition>
    </extension>

    <!-- ============================================ -->
    <!-- Voicemail: Leave Message                    -->
    <!-- ============================================ -->
    <extension name="voicemail-leave">
      <condition field="destination_number" expression="^vm(\d+)$">
        <action application="answer"/>
        <action application="sleep" data="500"/>
        <action application="voicemail" data="default ${domain_name} $1"/>
      </condition>
    </extension>

    <!-- ============================================ -->
    <!-- DID Routing: Route by called number         -->
    <!-- ============================================ -->
    <extension name="did-routing">
      <condition field="destination_number" expression="^(\+?\d{10,15})$">
        <!-- Look up DID routing from database -->
        <action application="set" data="continue_on_fail=true"/>
        <action application="set" data="hangup_after_bridge=true"/>

        <!-- Example: direct extension mapping -->
        <!-- In production, use mod_xml_curl for dynamic DID→destination lookup -->
        <action application="bridge" data="user/${destination_number}@${domain_name}"/>

        <!-- If bridge fails, send to voicemail -->
        <action application="voicemail" data="default ${domain_name} ${destination_number}"/>
      </condition>
    </extension>

    <!-- ============================================ -->
    <!-- Internal Extension Dialing (1000-1999)      -->
    <!-- ============================================ -->
    <extension name="local-extensions">
      <condition field="destination_number" expression="^(1\d{3})$">
        <action application="set" data="call_timeout=30"/>
        <action application="set" data="continue_on_fail=true"/>
        <action application="set" data="hangup_after_bridge=true"/>
        <action application="bridge" data="user/$1@${domain_name}"/>
        <!-- No answer → voicemail -->
        <action application="voicemail" data="default ${domain_name} $1"/>
      </condition>
    </extension>

    <!-- ============================================ -->
    <!-- Outbound Calls (via Kamailio)               -->
    <!-- ============================================ -->
    <extension name="outbound">
      <condition field="destination_number" expression="^9(\d+)$">
        <!-- Strip the 9 prefix and send back to Kamailio for trunk routing -->
        <action application="set" data="effective_caller_id_number=${outbound_caller_id_number}"/>
        <action application="bridge" data="sofia/kamailio/$1@YOUR_KAM1_PRIVATE"/>
      </condition>
    </extension>

    <!-- ============================================ -->
    <!-- Echo Test                                   -->
    <!-- ============================================ -->
    <extension name="echo">
      <condition field="destination_number" expression="^9196$">
        <action application="answer"/>
        <action application="echo"/>
      </condition>
    </extension>

    <!-- ============================================ -->
    <!-- Catch-all: Unknown Destination              -->
    <!-- ============================================ -->
    <extension name="catch-all">
      <condition field="destination_number" expression="^(.*)$">
        <action application="log" data="WARNING: Unrouted call to ${destination_number} from ${caller_id_number}"/>
        <action application="respond" data="404"/>
      </condition>
    </extension>

  </context>
</include>

Event Socket Layer (ESL) Configuration

ESL allows external applications to control FreeSWITCH. This is essential for integration with custom applications, monitoring, and call control.

Edit /etc/freeswitch/autoload_configs/event_socket.conf.xml:

<configuration name="event_socket.conf" description="Socket Client">
  <settings>
    <!-- Listen on private network only -->
    <param name="listen-ip" value="0.0.0.0"/>
    <param name="listen-port" value="8021"/>
    <param name="password" value="YOUR_ESL_PASSWORD"/>

    <!-- ACL restriction — only allow from management network -->
    <param name="apply-inbound-acl" value="internal-acl"/>
  </settings>
</configuration>

XML CDR — Call Detail Records

Configure FreeSWITCH to POST CDRs to a central collector:

Edit /etc/freeswitch/autoload_configs/xml_cdr.conf.xml:

<configuration name="xml_cdr.conf" description="XML CDR">
  <settings>
    <!-- POST CDRs to central collector -->
    <param name="url" value="http://YOUR_DB1_IP:8080/cdr"/>
    <param name="retries" value="3"/>
    <param name="delay" value="5"/>
    <param name="log-http-and-disk" value="true"/>
    <param name="log-dir" value="/var/log/freeswitch/cdr-csv"/>
    <param name="err-log-dir" value="/var/log/freeswitch/cdr-csv/errors"/>
    <param name="encode" value="true"/>
    <param name="disable-100-continue" value="true"/>
  </settings>
</configuration>

FreeSWITCH Firewall (Internal Only)

# FreeSWITCH servers are internal only
ufw default deny incoming
ufw default allow outgoing

# SSH
ufw allow 22/tcp

# SIP from Kamailio only
ufw allow from YOUR_KAM1_PRIVATE to any port 5060 proto udp
ufw allow from YOUR_KAM1_PRIVATE to any port 5060 proto tcp
ufw allow from YOUR_KAM2_PRIVATE to any port 5060 proto udp
ufw allow from YOUR_KAM2_PRIVATE to any port 5060 proto tcp

# RTP from RTPEngine only
ufw allow from YOUR_RTP1_PRIVATE to any port 16384:32768 proto udp
ufw allow from YOUR_RTP2_PRIVATE to any port 16384:32768 proto udp

# ESL from management network
ufw allow from 10.0.1.0/24 to any port 8021 proto tcp

# Internal network (database, monitoring)
ufw allow from 10.0.1.0/24

ufw enable

Start and Verify FreeSWITCH

# Start FreeSWITCH
systemctl start freeswitch

# Verify SIP profile is loaded
fs_cli -x "sofia status"
# Should show: kamailio   sip:mod_sofia@YOUR_FS1_IP:5060   RUNNING

# Verify profile details
fs_cli -x "sofia status profile kamailio"

# Test: Send a SIP OPTIONS from Kamailio
# On Kamailio server:
kamcmd dispatcher.list
# Should show FreeSWITCH as Active (AP flags)

# Run echo test through the full chain:
# SIP phone → Kamailio → RTPEngine → FreeSWITCH (9196 echo)

Per-Instance Configuration

Each FreeSWITCH instance needs a unique switch.conf.xml with its own identity:

<!-- /etc/freeswitch/autoload_configs/switch.conf.xml -->
<configuration name="switch.conf" description="Core Configuration">
  <settings>
    <!-- Unique per instance -->
    <param name="switchname" value="fs01"/>

    <!-- Core settings -->
    <param name="max-sessions" value="5000"/>
    <param name="sessions-per-second" value="100"/>
    <param name="rtp-start-port" value="16384"/>
    <param name="rtp-end-port" value="32768"/>

    <!-- Logging -->
    <param name="loglevel" value="warning"/>
    <param name="colorize-console" value="false"/>

    <!-- Performance -->
    <param name="max-db-handles" value="50"/>
    <param name="db-handle-timeout" value="10"/>
  </settings>
</configuration>

Change switchname to fs02, fs03, etc. on each instance. This value appears in CDRs and logs, making it easy to identify which FreeSWITCH handled a call.

8. Database-Driven Routing

Shared Database Architecture

All components share a central MariaDB (or Galera cluster) for configuration, state, and CDRs. This enables:

Dynamic routing — change DID→destination mapping without restarting anything
Multi-tenant — domain-based isolation of users and routes
Shared user directory — FreeSWITCH instances share the same user/extension database
Centralized CDR — all call records in one place regardless of which FreeSWITCH handled the call
Runtime changes — add/remove servers, DIDs, routes via database without restarts

Install MariaDB (Single Node or Galera Cluster)

For a single-node setup:

#!/bin/bash
# install-mariadb.sh — Run on db01

apt-get install -y mariadb-server mariadb-client

# Secure the installation
mysql_secure_installation
# Set root password, remove anonymous users, disable remote root, remove test DB

# Allow remote connections from private network
sed -i 's/bind-address.*/bind-address = 0.0.0.0/' /etc/mysql/mariadb.conf.d/50-server.cnf

# Performance tuning for VoIP
cat >> /etc/mysql/mariadb.conf.d/50-server.cnf << 'EOF'

# VoIP platform tuning
innodb_buffer_pool_size = 4G
innodb_log_file_size = 512M
innodb_flush_log_at_trx_commit = 2
innodb_flush_method = O_DIRECT
max_connections = 500
query_cache_type = 0
table_open_cache = 4000
tmp_table_size = 64M
max_heap_table_size = 64M
slow_query_log = 1
slow_query_log_file = /var/log/mysql/slow.log
long_query_time = 1
EOF

systemctl restart mariadb

For a Galera cluster (3 nodes), add to the config on each node:

# /etc/mysql/mariadb.conf.d/60-galera.cnf
[galera]
wsrep_on = ON
wsrep_provider = /usr/lib/galera/libgalera_smm.so
wsrep_cluster_name = "voip-cluster"
wsrep_cluster_address = "gcomm://YOUR_DB1_IP,YOUR_DB2_IP,YOUR_DB3_IP"
wsrep_node_address = "YOUR_DB1_IP"  # Change per node
wsrep_node_name = "db01"            # Change per node
wsrep_sst_method = mariabackup
wsrep_sst_auth = "sst_user:YOUR_SST_PASSWORD"
binlog_format = ROW
default_storage_engine = InnoDB
innodb_autoinc_lock_mode = 2

Database Schema

Create the databases and tables used by each component:

-- ================================================
-- Kamailio database (created by kamdbctl create)
-- Key tables used by our SBC configuration:
-- ================================================

-- subscriber — SIP user credentials
-- (auto-created by kamdbctl, shown here for reference)
CREATE TABLE IF NOT EXISTS subscriber (
    id INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
    username VARCHAR(64) NOT NULL DEFAULT '',
    domain VARCHAR(64) NOT NULL DEFAULT '',
    password VARCHAR(64) NOT NULL DEFAULT '',
    ha1 VARCHAR(128) NOT NULL DEFAULT '',
    ha1b VARCHAR(128) NOT NULL DEFAULT '',
    PRIMARY KEY (id),
    UNIQUE KEY sub_idx (username, domain)
) ENGINE=InnoDB;

-- dispatcher — load balancer backends (auto-created)
-- Already populated in Section 5

-- ================================================
-- Custom routing tables
-- ================================================

-- DID routing: maps incoming DIDs to destinations
CREATE TABLE did_routing (
    id INT UNSIGNED NOT NULL AUTO_INCREMENT,
    did VARCHAR(20) NOT NULL COMMENT 'Incoming DID number (E.164)',
    domain VARCHAR(64) NOT NULL DEFAULT 'default' COMMENT 'Tenant domain',
    destination VARCHAR(128) NOT NULL COMMENT 'Destination (extension, queue, IVR)',
    dest_type ENUM('extension','queue','ivr','conference','voicemail','external') NOT NULL DEFAULT 'extension',
    priority INT NOT NULL DEFAULT 0 COMMENT 'Higher = preferred',
    active TINYINT(1) NOT NULL DEFAULT 1,
    description VARCHAR(255) DEFAULT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (id),
    UNIQUE KEY did_domain_idx (did, domain),
    KEY active_idx (active)
) ENGINE=InnoDB;

-- Example DID routing entries
INSERT INTO did_routing (did, domain, destination, dest_type, description) VALUES
('+442012345678', 'default', '2000', 'ivr', 'UK Main — IVR'),
('+442012345679', 'default', '3001', 'queue', 'UK Sales Direct'),
('+442012345680', 'default', '1001', 'extension', 'UK CEO Direct'),
('+33123456789', 'tenant-fr.example.com', '2000', 'ivr', 'France Main — IVR'),
('+33123456790', 'tenant-fr.example.com', '3002', 'queue', 'France Support');

-- Trunk routing: outbound carrier selection
CREATE TABLE trunk_routing (
    id INT UNSIGNED NOT NULL AUTO_INCREMENT,
    prefix VARCHAR(20) NOT NULL COMMENT 'Dialed prefix (longest match wins)',
    domain VARCHAR(64) NOT NULL DEFAULT 'default',
    trunk_name VARCHAR(64) NOT NULL COMMENT 'SIP trunk identifier',
    trunk_uri VARCHAR(256) NOT NULL COMMENT 'SIP URI for the trunk',
    priority INT NOT NULL DEFAULT 0,
    weight INT NOT NULL DEFAULT 100 COMMENT 'Weight for load distribution',
    active TINYINT(1) NOT NULL DEFAULT 1,
    description VARCHAR(255) DEFAULT NULL,
    PRIMARY KEY (id),
    KEY prefix_idx (prefix, domain, active, priority)
) ENGINE=InnoDB;

-- Example trunk routing
INSERT INTO trunk_routing (prefix, domain, trunk_name, trunk_uri, priority, description) VALUES
('+44', 'default', 'carrier-a-uk', 'sip:+44@carrier-a.example.com', 10, 'Carrier A — UK primary'),
('+44', 'default', 'carrier-b-uk', 'sip:+44@carrier-b.example.com', 5, 'Carrier B — UK backup'),
('+33', 'default', 'carrier-a-fr', 'sip:+33@carrier-a.example.com', 10, 'Carrier A — France'),
('+1',  'default', 'carrier-c-us', 'sip:+1@carrier-c.example.com', 10, 'Carrier C — US/Canada');

-- ================================================
-- CDR table (all FreeSWITCH instances write here)
-- ================================================
CREATE TABLE cdr (
    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
    switch_name VARCHAR(32) NOT NULL COMMENT 'FreeSWITCH instance (fs01, fs02, ...)',
    call_uuid VARCHAR(64) NOT NULL,
    sip_call_id VARCHAR(128) DEFAULT NULL,
    caller_id_number VARCHAR(32) DEFAULT NULL,
    caller_id_name VARCHAR(64) DEFAULT NULL,
    destination_number VARCHAR(32) DEFAULT NULL,
    context VARCHAR(64) DEFAULT NULL,
    start_stamp DATETIME NOT NULL,
    answer_stamp DATETIME DEFAULT NULL,
    end_stamp DATETIME NOT NULL,
    duration INT NOT NULL DEFAULT 0,
    billsec INT NOT NULL DEFAULT 0,
    hangup_cause VARCHAR(64) DEFAULT NULL,
    sip_hangup_disposition VARCHAR(64) DEFAULT NULL,
    direction ENUM('inbound','outbound','internal') DEFAULT 'inbound',
    accountcode VARCHAR(32) DEFAULT NULL,
    domain VARCHAR(64) DEFAULT NULL,
    recording_path VARCHAR(512) DEFAULT NULL,
    PRIMARY KEY (id),
    KEY call_uuid_idx (call_uuid),
    KEY sip_call_id_idx (sip_call_id),
    KEY start_stamp_idx (start_stamp),
    KEY caller_idx (caller_id_number),
    KEY dest_idx (destination_number),
    KEY domain_idx (domain)
) ENGINE=InnoDB
PARTITION BY RANGE (YEAR(start_stamp) * 100 + MONTH(start_stamp)) (
    PARTITION p202601 VALUES LESS THAN (202602),
    PARTITION p202602 VALUES LESS THAN (202603),
    PARTITION p202603 VALUES LESS THAN (202604),
    PARTITION p202604 VALUES LESS THAN (202605),
    PARTITION p202605 VALUES LESS THAN (202606),
    PARTITION p202606 VALUES LESS THAN (202607),
    PARTITION pmax VALUES LESS THAN MAXVALUE
);

Database Users and Permissions

-- Kamailio user (needs read/write on kamailio DB)
CREATE USER 'kamailio'@'10.0.1.%' IDENTIFIED BY 'YOUR_DB_PASSWORD';
GRANT ALL PRIVILEGES ON kamailio.* TO 'kamailio'@'10.0.1.%';

-- FreeSWITCH user (read routing tables, write CDRs)
CREATE USER 'freeswitch'@'10.0.1.%' IDENTIFIED BY 'YOUR_FS_DB_PASSWORD';
GRANT SELECT ON kamailio.did_routing TO 'freeswitch'@'10.0.1.%';
GRANT SELECT ON kamailio.trunk_routing TO 'freeswitch'@'10.0.1.%';
GRANT SELECT ON kamailio.subscriber TO 'freeswitch'@'10.0.1.%';
GRANT INSERT, SELECT ON kamailio.cdr TO 'freeswitch'@'10.0.1.%';

-- Grafana / monitoring (read-only)
CREATE USER 'grafana'@'10.0.1.%' IDENTIFIED BY 'YOUR_GRAFANA_DB_PASSWORD';
GRANT SELECT ON kamailio.* TO 'grafana'@'10.0.1.%';

FLUSH PRIVILEGES;

Kamailio: DID-Based Routing from Database

Add this route to kamailio.cfg to look up DID routing from the database before dispatching:

## ---- DID Routing from Database ----
route[DID_ROUTING] {
    # Look up the called number (R-URI user) in did_routing table
    if (!sql_query("ca", "SELECT destination, dest_type FROM did_routing \
        WHERE did='$rU' AND domain='$fd' AND active=1 \
        ORDER BY priority DESC LIMIT 1", "ra")) {
        xlog("L_ERR", "DID_ROUTING: Database query failed\n");
        return;
    }

    if ($dbr(ra=>rows) > 0) {
        $var(destination) = $dbr(ra=>[0,0]);
        $var(dest_type) = $dbr(ra=>[0,1]);

        xlog("L_INFO", "DID_ROUTING: $rU → $var(destination) ($var(dest_type))\n");

        # Rewrite the R-URI with the looked-up destination
        # FreeSWITCH will use this to determine what to do
        $rU = $var(destination);

        # Optionally set a header so FreeSWITCH knows the destination type
        append_hf("X-Dest-Type: $var(dest_type)\r\n");
    } else {
        xlog("L_WARN", "DID_ROUTING: No route found for DID $rU in domain $fd\n");
        # Use default routing or reject
        sl_send_reply("404", "DID Not Found");
        exit;
    }
}

Then call this route before dispatching in the INVITE handler:

    # Handle INVITE — main call processing
    if (is_method("INVITE")) {
        setflag(FLT_DLG);
        dlg_manage();
        route(NATDETECT);
        route(DID_ROUTING);        # <-- Look up DID first
        route(RTPENGINE_OFFER);
        route(DISPATCH);
        exit;
    }

FreeSWITCH: Dynamic User Directory via mod_xml_curl

Instead of static XML user files on each FreeSWITCH, use mod_xml_curl to fetch user configuration from a central HTTP API backed by the database.

Edit /etc/freeswitch/autoload_configs/xml_curl.conf.xml:

<configuration name="xml_curl.conf" description="cURL XML Gateway">
  <bindings>
    <binding name="directory">
      <param name="gateway-url" value="http://YOUR_DB1_IP:8080/freeswitch/directory"/>
      <param name="gateway-credentials" value="freeswitch:YOUR_API_PASSWORD"/>
      <param name="auth-scheme" value="basic"/>
      <param name="timeout" value="5"/>
      <param name="disable-100-continue" value="true"/>
      <param name="enable-post-mapping" value="false"/>
    </binding>
  </bindings>
</configuration>

Example Python API that serves user directory XML (runs on the DB server or a separate API server):

#!/usr/bin/env python3
"""
freeswitch_directory_api.py
Serves FreeSWITCH user directory from MariaDB
Run with: uvicorn freeswitch_directory_api:app --host 0.0.0.0 --port 8080
"""
from fastapi import FastAPI, Form, Response
import mysql.connector

app = FastAPI()
DB_CONFIG = {
    "host": "YOUR_DB1_IP",
    "user": "freeswitch",
    "password": "YOUR_FS_DB_PASSWORD",
    "database": "kamailio"
}

@app.post("/freeswitch/directory")
async def directory(
    section: str = Form(default="directory"),
    key_name: str = Form(default=""),
    key_value: str = Form(default=""),
    user: str = Form(default=""),
    domain: str = Form(default=""),
):
    """Return FreeSWITCH directory XML for a user lookup."""

    if section != "directory" or not user or not domain:
        return Response(
            content='<?xml version="1.0"?><document type="freeswitch/xml"><section name="directory"></section></document>',
            media_type="text/xml"
        )

    # Look up user in subscriber table
    conn = mysql.connector.connect(**DB_CONFIG)
    cursor = conn.cursor(dictionary=True)
    cursor.execute(
        "SELECT username, password, domain FROM subscriber WHERE username=%s AND domain=%s",
        (user, domain)
    )
    row = cursor.fetchone()
    cursor.close()
    conn.close()

    if not row:
        return Response(
            content='<?xml version="1.0"?><document type="freeswitch/xml"><section name="directory"></section></document>',
            media_type="text/xml"
        )

    xml = f'''<?xml version="1.0" encoding="UTF-8"?>
<document type="freeswitch/xml">
  <section name="directory">
    <domain name="{domain}">
      <user id="{row["username"]}">
        <params>
          <param name="password" value="{row["password"]}"/>
          <param name="vm-password" value="{row["password"]}"/>
        </params>
        <variables>
          <variable name="accountcode" value="{row["username"]}"/>
          <variable name="user_context" value="from-kamailio"/>
          <variable name="effective_caller_id_name" value="{row["username"]}"/>
          <variable name="effective_caller_id_number" value="{row["username"]}"/>
        </variables>
      </user>
    </domain>
  </section>
</document>'''

    return Response(content=xml, media_type="text/xml")

Multi-Tenant Routing

For multi-tenant deployments, use the SIP domain to isolate tenants:

-- Tenant A: company-a.example.com
INSERT INTO did_routing (did, domain, destination, dest_type) VALUES
('+442012345678', 'company-a.example.com', '2000', 'ivr'),
('+442012345679', 'company-a.example.com', '3001', 'queue');

-- Tenant B: company-b.example.com
INSERT INTO did_routing (did, domain, destination, dest_type) VALUES
('+442087654321', 'company-b.example.com', '2000', 'ivr'),
('+442087654322', 'company-b.example.com', '3001', 'queue');

Kamailio routes based on the $fd (From domain) or $rd (Request-URI domain), and FreeSWITCH uses the domain in its user directory lookups. Same extension number 2000 can map to completely different IVRs for each tenant.

9. WebRTC Gateway

Architecture for WebRTC

Browser (WebRTC)                          SIP Trunk
   │                                         │
   │ WSS (SIP over WebSocket)                │ UDP/TCP SIP
   │ DTLS-SRTP (encrypted media)             │ RTP (unencrypted)
   ▼                                         ▼
┌──────────┐    SIP    ┌──────────┐    SIP    ┌──────────┐
│ Kamailio │◄────────►│ RTPEngine│◄────────►│FreeSWITCH│
│  (WSS)   │          │(DTLS↔RTP)│          │ (media)  │
└──────────┘          └──────────┘          └──────────┘

Kamailio: Terminates WebSocket, handles SIP-over-WS
RTPEngine: Bridges DTLS-SRTP (WebRTC) ↔ plain RTP (FreeSWITCH/trunks)
FreeSWITCH: Processes calls normally (does not know about WebRTC)

TLS Certificates (Let's Encrypt Wildcard)

# Install certbot with DNS plugin (for wildcard certs)
apt-get install -y certbot python3-certbot-dns-cloudflare

# Create credentials file (example for Cloudflare DNS)
mkdir -p /root/.secrets
cat > /root/.secrets/cloudflare.ini << 'EOF'
dns_cloudflare_api_token = YOUR_CLOUDFLARE_API_TOKEN
EOF
chmod 600 /root/.secrets/cloudflare.ini

# Get wildcard certificate
certbot certonly \
    --dns-cloudflare \
    --dns-cloudflare-credentials /root/.secrets/cloudflare.ini \
    -d "*.YOUR_DOMAIN" \
    -d "YOUR_DOMAIN" \
    --agree-tos \
    -m admin@YOUR_DOMAIN

# Link for Kamailio
ln -sf /etc/letsencrypt/live/YOUR_DOMAIN/fullchain.pem /etc/kamailio/tls/server.pem
ln -sf /etc/letsencrypt/live/YOUR_DOMAIN/privkey.pem /etc/kamailio/tls/server.key

# Link for RTPEngine (DTLS)
mkdir -p /etc/rtpengine/tls
ln -sf /etc/letsencrypt/live/YOUR_DOMAIN/fullchain.pem /etc/rtpengine/tls/cert.pem
ln -sf /etc/letsencrypt/live/YOUR_DOMAIN/privkey.pem /etc/rtpengine/tls/key.pem

# Auto-renewal cron (reload services after renewal)
cat > /etc/letsencrypt/renewal-hooks/deploy/reload-voip.sh << 'SCRIPT'
#!/bin/bash
systemctl reload kamailio 2>/dev/null || true
systemctl restart rtpengine 2>/dev/null || true
SCRIPT
chmod +x /etc/letsencrypt/renewal-hooks/deploy/reload-voip.sh

Kamailio WSS Configuration

The WebSocket handling is already in the main kamailio.cfg from Section 4. Key pieces:

# Listeners (already defined)
listen=tls:MY_PUBLIC_IP:8443   # WSS direct

# WebSocket module (already loaded)
loadmodule "websocket.so"
loadmodule "xhttp.so"

# xhttp event route handles the WebSocket upgrade (already defined)
event_route[xhttp:request] { ... }

Additional WebSocket-specific routing logic to add in the main request_route:

    # ---- WebRTC-specific handling ----
    if (proto == WS || proto == WSS) {
        # Force record-route with WebSocket transport
        if (is_method("INVITE|SUBSCRIBE")) {
            record_route_preset("MY_PUBLIC_IP:8443;transport=wss");
        }

        # WebRTC clients use SIP Outbound (RFC 5626)
        if (is_method("REGISTER")) {
            # Add Path header so replies find the WebSocket connection
            add_path_received();
        }
    }

RTPEngine DTLS Configuration

Add DTLS support to /etc/rtpengine/rtpengine.conf:

# Add to [rtpengine] section
# DTLS certificate for WebRTC
dtls-cert = /etc/rtpengine/tls/cert.pem
dtls-key = /etc/rtpengine/tls/key.pem

# Enable DTLS and ICE
ice-lite = true

Nginx Reverse Proxy for WSS

For production, put Nginx in front of Kamailio for WSS. This provides proper TLS termination, HTTP/2, and the ability to serve the web client from the same domain:

# /etc/nginx/sites-available/webrtc-gateway
upstream kamailio_wss {
    server YOUR_KAM1_PRIVATE:8080;   # WS (unencrypted) — Nginx handles TLS
    server YOUR_KAM2_PRIVATE:8080 backup;
}

server {
    listen 443 ssl http2;
    server_name webrtc.YOUR_DOMAIN;

    ssl_certificate /etc/letsencrypt/live/YOUR_DOMAIN/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/YOUR_DOMAIN/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # WebSocket proxy to Kamailio
    location /ws {
        proxy_pass http://kamailio_wss;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }

    # Serve the WebRTC web client
    location / {
        root /var/www/webrtc;
        index index.html;
    }
}

Browser Client — SIP.js Example

Create /var/www/webrtc/index.html:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>WebRTC Phone</title>
    <script src="https://cdn.jsdelivr.net/npm/sip.js@0.21.2/lib/platform/web/sip.js"></script>
    <style>
        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
            max-width: 500px;
            margin: 50px auto;
            padding: 20px;
            background: #1a1a2e;
            color: #e0e0e0;
        }
        h1 { color: #00d4ff; text-align: center; }
        .status {
            text-align: center;
            padding: 10px;
            margin: 20px 0;
            border-radius: 8px;
            background: #16213e;
        }
        .status.connected { border-left: 4px solid #00ff88; }
        .status.disconnected { border-left: 4px solid #ff4444; }
        .status.calling { border-left: 4px solid #ffaa00; }
        input, button {
            width: 100%;
            padding: 12px;
            margin: 5px 0;
            border: none;
            border-radius: 6px;
            font-size: 16px;
            box-sizing: border-box;
        }
        input {
            background: #16213e;
            color: #e0e0e0;
            border: 1px solid #333;
        }
        button {
            cursor: pointer;
            font-weight: bold;
        }
        .btn-call { background: #00ff88; color: #000; }
        .btn-hangup { background: #ff4444; color: #fff; }
        .btn-answer { background: #00d4ff; color: #000; }
        .btn-register { background: #9b59b6; color: #fff; }
        button:hover { opacity: 0.9; }
        button:disabled { opacity: 0.4; cursor: not-allowed; }
        .controls { margin: 20px 0; }
        audio { display: none; }
    </style>
</head>
<body>
    <h1>WebRTC Phone</h1>

    <div id="status" class="status disconnected">Disconnected</div>

    <div class="controls">
        <input type="text" id="server" placeholder="WSS Server" value="wss://webrtc.YOUR_DOMAIN/ws">
        <input type="text" id="username" placeholder="SIP Username (e.g., 1001)">
        <input type="password" id="password" placeholder="SIP Password">
        <input type="text" id="domain" placeholder="SIP Domain" value="YOUR_DOMAIN">
        <button class="btn-register" onclick="doRegister()">Register</button>
    </div>

    <div class="controls">
        <input type="text" id="target" placeholder="Number to call">
        <button class="btn-call" id="btnCall" onclick="doCall()" disabled>Call</button>
        <button class="btn-answer" id="btnAnswer" onclick="doAnswer()" disabled>Answer</button>
        <button class="btn-hangup" id="btnHangup" onclick="doHangup()" disabled>Hang Up</button>
    </div>

    <audio id="remoteAudio" autoplay></audio>

    <script>
    let userAgent = null;
    let registerer = null;
    let currentSession = null;

    function setStatus(text, className) {
        const el = document.getElementById('status');
        el.textContent = text;
        el.className = 'status ' + className;
    }

    async function doRegister() {
        const server = document.getElementById('server').value;
        const username = document.getElementById('username').value;
        const password = document.getElementById('password').value;
        const domain = document.getElementById('domain').value;

        const uri = SIP.UserAgent.makeURI(`sip:${username}@${domain}`);
        const transportOptions = {
            server: server,
            traceSip: true
        };

        userAgent = new SIP.UserAgent({
            uri: uri,
            transportOptions: transportOptions,
            authorizationUsername: username,
            authorizationPassword: password,
            displayName: username,
            delegate: {
                onInvite: (invitation) => {
                    currentSession = invitation;
                    setStatus('Incoming call from ' + invitation.remoteIdentity.displayName, 'calling');
                    document.getElementById('btnAnswer').disabled = false;
                    document.getElementById('btnHangup').disabled = false;
                }
            }
        });

        await userAgent.start();

        registerer = new SIP.Registerer(userAgent);
        registerer.stateChange.addListener((state) => {
            switch (state) {
                case SIP.RegistererState.Registered:
                    setStatus('Registered as ' + username, 'connected');
                    document.getElementById('btnCall').disabled = false;
                    break;
                case SIP.RegistererState.Unregistered:
                    setStatus('Unregistered', 'disconnected');
                    document.getElementById('btnCall').disabled = true;
                    break;
            }
        });

        await registerer.register();
    }

    async function doCall() {
        const target = document.getElementById('target').value;
        const domain = document.getElementById('domain').value;

        if (!target || !userAgent) return;

        const targetURI = SIP.UserAgent.makeURI(`sip:${target}@${domain}`);
        if (!targetURI) {
            alert('Invalid target');
            return;
        }

        const inviter = new SIP.Inviter(userAgent, targetURI, {
            sessionDescriptionHandlerOptions: {
                constraints: { audio: true, video: false }
            }
        });

        currentSession = inviter;
        setupSessionListeners(inviter);

        setStatus('Calling ' + target + '...', 'calling');
        document.getElementById('btnHangup').disabled = false;
        document.getElementById('btnCall').disabled = true;

        await inviter.invite();
    }

    async function doAnswer() {
        if (!currentSession) return;

        await currentSession.accept({
            sessionDescriptionHandlerOptions: {
                constraints: { audio: true, video: false }
            }
        });

        setupSessionListeners(currentSession);
        setStatus('In call', 'connected');
        document.getElementById('btnAnswer').disabled = true;
    }

    function doHangup() {
        if (!currentSession) return;

        switch (currentSession.state) {
            case SIP.SessionState.Initial:
            case SIP.SessionState.Establishing:
                if (currentSession instanceof SIP.Inviter) {
                    currentSession.cancel();
                } else {
                    currentSession.reject();
                }
                break;
            case SIP.SessionState.Established:
                currentSession.bye();
                break;
        }

        resetCallUI();
    }

    function setupSessionListeners(session) {
        session.stateChange.addListener((state) => {
            switch (state) {
                case SIP.SessionState.Established:
                    setStatus('In call', 'connected');
                    // Attach remote audio
                    const remoteStream = new MediaStream();
                    session.sessionDescriptionHandler.peerConnection
                        .getReceivers()
                        .forEach((receiver) => {
                            if (receiver.track) {
                                remoteStream.addTrack(receiver.track);
                            }
                        });
                    document.getElementById('remoteAudio').srcObject = remoteStream;
                    break;
                case SIP.SessionState.Terminated:
                    setStatus('Call ended', 'disconnected');
                    resetCallUI();
                    break;
            }
        });
    }

    function resetCallUI() {
        currentSession = null;
        document.getElementById('btnCall').disabled = false;
        document.getElementById('btnAnswer').disabled = true;
        document.getElementById('btnHangup').disabled = true;
        document.getElementById('remoteAudio').srcObject = null;
        setTimeout(() => setStatus('Registered', 'connected'), 2000);
    }
    </script>
</body>
</html>

Testing WebRTC

Open https://webrtc.YOUR_DOMAIN/ in Chrome or Firefox
Enter your SIP credentials and click Register
Status should change to "Registered"
Enter a number (e.g., 9196 for echo test) and click Call
Verify audio flows both directions

Debugging WebRTC issues:

# On Kamailio — watch WebSocket connections
kamcmd ws.dump

# On RTPEngine — check DTLS sessions
rtpengine-ctl list sessions

# On RTPEngine — verify DTLS is working
# Look for "DTLS" in the session details
rtpengine-ctl list totals

# Browser — check WebRTC internals
# Chrome: chrome://webrtc-internals/
# Firefox: about:webrtc

10. High Availability — Kamailio

Keepalived + Virtual IP (VIP)

The Kamailio HA pair uses Keepalived to manage a floating Virtual IP (VIP). The active node holds the VIP and processes all traffic. If it fails, the standby node takes over the VIP within seconds.

Normal operation:
  VIP (YOUR_PUBLIC_VIP) → Kamailio-A (active)
                           Kamailio-B (standby, idle)

After Kamailio-A failure:
  VIP (YOUR_PUBLIC_VIP) → Kamailio-B (now active)
                           Kamailio-A (down)

Failover time: 3-6 seconds (VRRP advertisement interval + detection)

Install Keepalived

# On both kam01 and kam02
apt-get install -y keepalived

Health Check Script

Create /etc/keepalived/check_kamailio.sh:

#!/bin/bash
#
# Kamailio health check for Keepalived
# Returns 0 (healthy) or 1 (unhealthy)
# Tests actual SIP responsiveness, not just process existence
#

# Check 1: Is the process running?
if ! pgrep -x kamailio > /dev/null 2>&1; then
    echo "FAIL: Kamailio process not running"
    exit 1
fi

# Check 2: Can it respond to SIP OPTIONS?
# Send OPTIONS to localhost and expect a response within 2 seconds
RESPONSE=$(sipsak -s sip:keepalive@127.0.0.1:5060 -v --timeout 2 2>&1)
if [ $? -ne 0 ]; then
    echo "FAIL: Kamailio not responding to SIP OPTIONS"
    exit 1
fi

# Check 3: Check that the control socket is responsive
if ! kamcmd core.uptime > /dev/null 2>&1; then
    echo "FAIL: Kamailio RPC not responding"
    exit 1
fi

# Check 4: Verify at least one dispatcher destination is active
ACTIVE=$(kamcmd dispatcher.list 2>/dev/null | grep -c "FLAGS: AP")
if [ "$ACTIVE" -eq 0 ]; then
    echo "WARN: No active dispatcher destinations (not failing over for this)"
    # Don't fail for this — it might be a temporary condition
    # and failing over won't help if all FS servers are down
fi

echo "OK: Kamailio healthy (${ACTIVE} active dispatchers)"
exit 0

chmod +x /etc/keepalived/check_kamailio.sh
apt-get install -y sipsak   # Needed for the health check

Keepalived Configuration — Active Node (kam01)

Create /etc/keepalived/keepalived.conf on kam01:

# /etc/keepalived/keepalived.conf — Kamailio-A (MASTER)

global_defs {
    router_id KAM01
    script_user root
    enable_script_security
    # Notification emails (optional)
    # notification_email {
    #     admin@YOUR_DOMAIN
    # }
    # notification_email_from keepalived@kam01
    # smtp_server localhost
}

# Health check script
vrrp_script check_kamailio {
    script "/etc/keepalived/check_kamailio.sh"
    interval 3          # Check every 3 seconds
    weight -20          # Subtract 20 from priority on failure
    fall 2              # 2 consecutive failures = unhealthy
    rise 2              # 2 consecutive successes = healthy
}

# VRRP instance for SIP VIP
vrrp_instance VI_SIP {
    state MASTER
    interface eth0              # Change to your network interface
    virtual_router_id 51       # Must be same on both nodes
    priority 100               # Higher = preferred (kam01 is preferred)
    advert_int 1               # VRRP advertisement every 1 second

    authentication {
        auth_type PASS
        auth_pass YOUR_VRRP_PASSWORD    # Same on both nodes
    }

    virtual_ipaddress {
        YOUR_PUBLIC_VIP/32 dev eth0     # The floating VIP
    }

    track_script {
        check_kamailio
    }

    # Notify scripts (optional — for logging/alerting)
    notify_master "/bin/bash -c 'logger -t keepalived MASTER — VIP acquired on kam01'"
    notify_backup "/bin/bash -c 'logger -t keepalived BACKUP — VIP released on kam01'"
    notify_fault  "/bin/bash -c 'logger -t keepalived FAULT — health check failing on kam01'"
}

Keepalived Configuration — Standby Node (kam02)

Create /etc/keepalived/keepalived.conf on kam02 (differences highlighted):

# /etc/keepalived/keepalived.conf — Kamailio-B (BACKUP)

global_defs {
    router_id KAM02
    script_user root
    enable_script_security
}

vrrp_script check_kamailio {
    script "/etc/keepalived/check_kamailio.sh"
    interval 3
    weight -20
    fall 2
    rise 2
}

vrrp_instance VI_SIP {
    state BACKUP                # <-- BACKUP (not MASTER)
    interface eth0
    virtual_router_id 51       # Must match kam01
    priority 90                # <-- Lower priority (kam01 preferred)
    advert_int 1

    authentication {
        auth_type PASS
        auth_pass YOUR_VRRP_PASSWORD    # Must match kam01
    }

    virtual_ipaddress {
        YOUR_PUBLIC_VIP/32 dev eth0
    }

    track_script {
        check_kamailio
    }

    notify_master "/bin/bash -c 'logger -t keepalived MASTER — VIP acquired on kam02'"
    notify_backup "/bin/bash -c 'logger -t keepalived BACKUP — VIP released on kam02'"
    notify_fault  "/bin/bash -c 'logger -t keepalived FAULT — health check failing on kam02'"
}

Start Keepalived

# On both nodes
systemctl enable --now keepalived

# Verify VIP is on kam01 (the master)
ip addr show eth0 | grep YOUR_PUBLIC_VIP

# Check keepalived status
systemctl status keepalived
journalctl -u keepalived -f

# Test failover: stop Kamailio on kam01
systemctl stop kamailio
# Within 3-6 seconds, VIP should move to kam02:
# On kam02: ip addr show eth0 | grep YOUR_PUBLIC_VIP

# Restore kam01
systemctl start kamailio
# VIP moves back to kam01 (higher priority, preemption)

Shared Location Table (usrloc to DB)

For seamless failover of registered users, both Kamailio nodes must share the location table in the database. This is already configured in our kamailio.cfg:

modparam("usrloc", "db_url", DBURL)
modparam("usrloc", "db_mode", 2)    # Write-through: every registration written to DB immediately

With db_mode=2, when a user registers via kam01, the registration is written to the database. If kam01 fails and kam02 takes over, kam02 reads the location table from the database and can route calls to registered users without re-registration.

Important: db_mode=2 has higher database load than db_mode=1 (write-back). For very high registration volumes (100K+ registered users), consider db_mode=1 with a short timer_interval (e.g., 30 seconds).

Dialog Replication with DMQ

For in-progress calls to survive a failover, Kamailio supports Dialog replication between nodes using the DMQ (Distributed Message Queue) module. This replicates dialog state so the standby node can handle in-dialog requests (BYE, re-INVITE) for calls that were set up by the active node.

Add to kamailio.cfg:

# Load DMQ module
loadmodule "dmq.so"

# DMQ parameters
modparam("dmq", "server_address", "sip:MY_PRIVATE_IP:5062")
modparam("dmq", "notification_address", "sip:10.0.1.10:5062")  # Use kam01 as notification peer
modparam("dmq", "multi_notify", 1)
modparam("dmq", "num_workers", 4)
modparam("dmq", "ping_interval", 15)

# Add DMQ listener
listen=udp:MY_PRIVATE_IP:5062

# Enable dialog replication via DMQ
modparam("dialog", "enable_dmq", 1)

Add DMQ routing in the main request_route:

    # DMQ traffic — handle before anything else
    if ($rm == "KDMQ" && $rP == "udp" && $sp == 5062) {
        dmq_handle_message();
        exit;
    }

With DMQ active, both Kamailio nodes maintain synchronized dialog state. During failover, in-progress calls continue working because the new active node has the complete dialog table.

11. High Availability — FreeSWITCH

Why FreeSWITCH HA Is Different

Unlike Kamailio (which is a stateless proxy that can easily share state via database), FreeSWITCH is a stateful media server — it holds active call sessions, media streams, and application state in memory. This makes traditional active/standby HA impractical for FreeSWITCH.

Instead, FreeSWITCH HA relies on a pool architecture:

Multiple FreeSWITCH instances run simultaneously (not standby — all active)
Kamailio's dispatcher distributes calls across the pool
If one FreeSWITCH fails, only its active calls are lost (not the entire platform)
New calls are automatically routed to surviving instances
The more instances in the pool, the smaller the blast radius of any single failure

Blast Radius Analysis

Pool Size	Calls per FS (at 3000 total)	Impact of 1 FS Failure
2 instances	1,500 each	50% of calls lost
3 instances	1,000 each	33% of calls lost
4 instances	750 each	25% of calls lost
6 instances	500 each	17% of calls lost

With 4+ instances, a single failure affects a manageable percentage of calls, and the surviving instances have enough headroom to absorb the redistributed load.

Graceful Draining — Zero-Downtime Maintenance

The key to zero-downtime FreeSWITCH maintenance is draining: stop sending new calls to a node while letting existing calls finish naturally.

#!/bin/bash
# drain-freeswitch.sh — Gracefully drain a FreeSWITCH instance
# Usage: ./drain-freeswitch.sh fs01 YOUR_FS1_IP

FS_NAME=$1
FS_IP=$2
KAM_HOST="YOUR_KAM1_PRIVATE"

echo "=== Draining FreeSWITCH: $FS_NAME ($FS_IP) ==="

# Step 1: Mark as inactive in Kamailio dispatcher (no new calls)
echo "Step 1: Removing from dispatcher..."
ssh $KAM_HOST "kamcmd dispatcher.set_state i 1 sip:${FS_IP}:5060"
echo "  Done. No new calls will be sent to $FS_NAME."

# Step 2: Wait for existing calls to finish
echo "Step 2: Waiting for active calls to finish..."
while true; do
    CALLS=$(ssh $FS_IP "fs_cli -x 'show calls count' 2>/dev/null" | grep -oP '\d+(?= total)')
    CALLS=${CALLS:-0}
    echo "  Active calls: $CALLS"
    if [ "$CALLS" -eq 0 ]; then
        break
    fi
    sleep 10
done

echo "  All calls finished."

# Step 3: Now safe to perform maintenance
echo "Step 3: $FS_NAME is fully drained. Safe to stop/upgrade."
echo ""
echo "  When done, re-enable with:"
echo "  ssh $KAM_HOST 'kamcmd dispatcher.set_state a 1 sip:${FS_IP}:5060'"

Zero-Downtime Upgrade Procedure

#!/bin/bash
# upgrade-freeswitch.sh — Zero-downtime FreeSWITCH upgrade
# Upgrades one instance at a time (rolling upgrade)

INSTANCES=("fs01:YOUR_FS1_IP" "fs02:YOUR_FS2_IP" "fs03:YOUR_FS3_IP")
KAM_HOST="YOUR_KAM1_PRIVATE"

for instance in "${INSTANCES[@]}"; do
    IFS=':' read -r name ip <<< "$instance"

    echo "============================================"
    echo "Upgrading $name ($ip)"
    echo "============================================"

    # 1. Drain
    echo "  Draining..."
    ssh $KAM_HOST "kamcmd dispatcher.set_state i 1 sip:${ip}:5060"

    # Wait for calls to finish (max 30 minutes)
    TIMEOUT=1800
    ELAPSED=0
    while [ $ELAPSED -lt $TIMEOUT ]; do
        CALLS=$(ssh $ip "fs_cli -x 'show calls count' 2>/dev/null" | grep -oP '\d+(?= total)')
        CALLS=${CALLS:-0}
        if [ "$CALLS" -eq 0 ]; then break; fi
        echo "    $CALLS calls remaining (${ELAPSED}s elapsed)..."
        sleep 15
        ELAPSED=$((ELAPSED + 15))
    done

    # 2. Stop FreeSWITCH
    echo "  Stopping FreeSWITCH..."
    ssh $ip "systemctl stop freeswitch"

    # 3. Upgrade
    echo "  Upgrading..."
    ssh $ip "apt-get update && apt-get upgrade -y freeswitch*"

    # 4. Start FreeSWITCH
    echo "  Starting FreeSWITCH..."
    ssh $ip "systemctl start freeswitch"
    sleep 5  # Wait for SIP profile to register

    # 5. Verify it responds
    echo "  Verifying..."
    ssh $ip "fs_cli -x 'sofia status'" || { echo "FAILED to start $name!"; exit 1; }

    # 6. Re-enable in dispatcher
    echo "  Re-enabling in dispatcher..."
    ssh $KAM_HOST "kamcmd dispatcher.set_state a 1 sip:${ip}:5060"

    echo "  $name upgraded successfully."
    echo ""

    # Wait before upgrading next instance (let it stabilize)
    sleep 30
done

echo "All instances upgraded. Verifying dispatcher state..."
ssh $KAM_HOST "kamcmd dispatcher.list"

Shared Storage for Recordings

FreeSWITCH call recordings need to be accessible regardless of which instance handled the call. Options:

Option A: NFS (simplest)

# On NFS server (db01 or dedicated storage)
apt-get install -y nfs-kernel-server
mkdir -p /srv/recordings
chown freeswitch:freeswitch /srv/recordings
echo "/srv/recordings 10.0.1.0/24(rw,sync,no_subtree_check,no_root_squash)" >> /etc/exports
exportfs -ra

# On each FreeSWITCH server
apt-get install -y nfs-common
mkdir -p /var/lib/freeswitch/recordings
echo "YOUR_DB1_IP:/srv/recordings /var/lib/freeswitch/recordings nfs defaults,soft,timeo=50 0 0" >> /etc/fstab
mount -a

Option B: S3-compatible storage (scalable)

Create a post-recording script that uploads to S3:

#!/bin/bash
# /usr/local/bin/upload-recording.sh
# Called by FreeSWITCH after each recording completes

FILE=$1
BUCKET="s3://your-recordings-bucket"

if [ -f "$FILE" ]; then
    aws s3 cp "$FILE" "$BUCKET/$(date +%Y/%m/%d)/$(basename $FILE)" \
        --storage-class STANDARD_IA
    # Optionally delete local file after upload
    # rm -f "$FILE"
fi

Session Recovery Limitations

It is important to understand what FreeSWITCH HA cannot do:

Active calls on a failed node are lost. The media streams are in that instance's memory and cannot be transferred.
Conference bridges on a failed node are terminated. All participants must rejoin.
Voicemail sessions in progress are lost. The caller must call back.

These limitations are inherent to any media server. The mitigation is to have enough pool instances that the blast radius of any single failure is acceptable. For critical applications (emergency services, etc.), consider having callers automatically redialed by the application layer when a session is lost.

12. Geographic Distribution

Multi-DC Architecture

                    ┌─────────────────────┐
                    │   Global DNS (SRV)  │
                    │   sip.YOUR_DOMAIN   │
                    └──────────┬──────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
    ┌─────────▼──────┐  ┌─────▼──────┐  ┌──────▼────────┐
    │  DC Europe     │  │  DC US-East │  │  DC US-West   │
    │  (London)      │  │  (Virginia) │  │  (Oregon)     │
    │                │  │             │  │               │
    │  Kam+FS+RTP    │  │  Kam+FS+RTP │  │  Kam+FS+RTP  │
    │  Galera node   │  │  Galera node│  │  Galera node  │
    └────────────────┘  └─────────────┘  └───────────────┘
              │                │                │
              └────────────────┼────────────────┘
                               │
                    ┌──────────▼──────────┐
                    │  Galera WAN Cluster │
                    │  (async replication)│
                    └─────────────────────┘

DNS SRV Records

DNS SRV records allow SIP clients to discover your servers and automatically failover between data centers:

; NAPTR records — tell SIP clients which transports are available
YOUR_DOMAIN.  IN NAPTR 10 10 "S" "SIP+D2U"  "" _sip._udp.YOUR_DOMAIN.
YOUR_DOMAIN.  IN NAPTR 20 10 "S" "SIP+D2T"  "" _sip._tcp.YOUR_DOMAIN.
YOUR_DOMAIN.  IN NAPTR 30 10 "S" "SIPS+D2T" "" _sips._tcp.YOUR_DOMAIN.

; SRV records — specify servers and priorities per transport
; Lower priority number = preferred. Same priority = load balance by weight.

; UDP SIP
_sip._udp.YOUR_DOMAIN.  IN SRV 10 60 5060 sip-eu.YOUR_DOMAIN.   ; EU primary
_sip._udp.YOUR_DOMAIN.  IN SRV 10 40 5060 sip-us.YOUR_DOMAIN.   ; US secondary
_sip._udp.YOUR_DOMAIN.  IN SRV 20 50 5060 sip-eu2.YOUR_DOMAIN.  ; EU backup
_sip._udp.YOUR_DOMAIN.  IN SRV 20 50 5060 sip-us2.YOUR_DOMAIN.  ; US backup

; TCP SIP
_sip._tcp.YOUR_DOMAIN.  IN SRV 10 60 5060 sip-eu.YOUR_DOMAIN.
_sip._tcp.YOUR_DOMAIN.  IN SRV 10 40 5060 sip-us.YOUR_DOMAIN.

; TLS SIP
_sips._tcp.YOUR_DOMAIN. IN SRV 10 60 5061 sip-eu.YOUR_DOMAIN.
_sips._tcp.YOUR_DOMAIN. IN SRV 10 40 5061 sip-us.YOUR_DOMAIN.

; A records for each SIP edge
sip-eu.YOUR_DOMAIN.  IN A YOUR_EU_VIP
sip-us.YOUR_DOMAIN.  IN A YOUR_US_VIP
sip-eu2.YOUR_DOMAIN. IN A YOUR_EU2_VIP
sip-us2.YOUR_DOMAIN. IN A YOUR_US2_VIP

How SIP clients use SRV records:

Client resolves _sip._udp.YOUR_DOMAIN and gets 2 records with priority 10
Client distributes requests based on weight: 60% to EU, 40% to US
If the priority-10 servers fail, client falls back to priority-20 servers
SIP INVITE includes a Route header for the selected server

Geographic Routing with GeoIP

Kamailio can use the GeoIP2 module to route calls based on the geographic location of the caller:

# Load GeoIP2 module
loadmodule "geoip2.so"
modparam("geoip2", "path", "/usr/share/GeoIP/GeoLite2-City.mmdb")

# Geographic routing route
route[GEO_ROUTE] {
    # Look up caller's country
    if (geoip2_match("$si", "src")) {
        $var(country) = $gip2(src=>cc);
        $var(continent) = $gip2(src=>cont);

        xlog("L_INFO", "GEO: Caller from $si — country=$var(country), continent=$var(continent)\n");

        # Route to closest DC based on continent
        switch ($var(continent)) {
            case "EU":
                # European callers → EU FreeSWITCH pool (set 10)
                if (!ds_select_dst("10", "0", "6")) {
                    # Fallback to US pool
                    ds_select_dst("20", "0", "6");
                }
                break;
            case "NA":
                # North American callers → US-East pool (set 20)
                if (!ds_select_dst("20", "0", "6")) {
                    ds_select_dst("10", "0", "6");
                }
                break;
            default:
                # Everyone else → round-robin across all DCs
                ds_select_dst("1", "4", "6");
                break;
        }
    } else {
        # GeoIP lookup failed — use default pool
        ds_select_dst("1", "0", "6");
    }
}

Database Replication Across Data Centers

For multi-DC deployments, use MariaDB Galera with WAN replication:

# On each Galera node, add WAN-specific settings:
[galera]
wsrep_cluster_address = "gcomm://EU_DB_IP,US_EAST_DB_IP,US_WEST_DB_IP"

# WAN optimizations
wsrep_provider_options = "evs.send_window=256; evs.user_send_window=128; evs.keepalive_period=PT3S; evs.suspect_timeout=PT30S; evs.inactive_timeout=PT1M; gcache.size=1G"

# Segment-aware replication (reduces cross-DC traffic)
# EU nodes: gmcast.segment=0
# US-East nodes: gmcast.segment=1
# US-West nodes: gmcast.segment=2
wsrep_provider_options = "gmcast.segment=0"   # Change per DC

Important latency considerations:

Galera writes are synchronous — a write in EU must be acknowledged by US nodes before committing
Cross-Atlantic latency is typically 80-120ms RTT
This adds ~100ms to every database write (registration, CDR insert)
For very high write volumes, consider:
- Asynchronous replication (standard MySQL replication) for CDRs
- Local caching in Kamailio htables for frequently-read data
- Read/write splitting: reads from local node, writes to any node

Latency Considerations for Media

Media (RTP) is latency-sensitive. Key rules:

RTPEngine should be in the same DC as the caller (or as close as possible)
FreeSWITCH should be in the same DC as the RTPEngine it works with
Cross-DC media relay adds 80-120ms of latency each way — noticeable in voice calls
For calls between users in different DCs, the media should anchor at one DC (caller's preferred)

Kamailio can select the right RTPEngine based on the caller's location:

# Select RTPEngine based on caller geography
route[SELECT_RTPENGINE] {
    if ($var(continent) == "EU") {
        # Use EU RTPEngine
        modparam("rtpengine", "rtpengine_sock", "udp:EU_RTP_IP:2223");
    } else {
        # Use US RTPEngine
        modparam("rtpengine", "rtpengine_sock", "udp:US_RTP_IP:2223");
    }
}

13. Monitoring & Operations

Prometheus Metrics — All Components

A unified monitoring stack provides visibility into every layer of the platform.

Kamailio Exporter

# Install kamailio-exporter
# Option 1: Pre-built binary
wget https://github.com/florentchauveau/kamailio_exporter/releases/latest/download/kamailio_exporter_linux_amd64 \
    -O /usr/local/bin/kamailio_exporter
chmod +x /usr/local/bin/kamailio_exporter

# Create systemd service
cat > /etc/systemd/system/kamailio-exporter.service << 'EOF'
[Unit]
Description=Kamailio Prometheus Exporter
After=kamailio.service

[Service]
ExecStart=/usr/local/bin/kamailio_exporter \
    --kamailio.address=unix:/var/run/kamailio/kamailio_ctl \
    --web.listen-address=:9494
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now kamailio-exporter

Key Kamailio metrics:

Metric	Meaning	Alert Threshold
`kamailio_dialog_active`	Active calls through Kamailio	>5000 (capacity warning)
`kamailio_tmx_code_total{code="5xx"}`	5xx SIP errors	>10/min
`kamailio_tmx_code_total{code="408"}`	Request timeouts	>5/min
`kamailio_dispatcher_target_up`	Backend FS health	== 0 (all down)
`kamailio_sl_sent_replies_total`	Reply rate	Sudden drop/spike
`kamailio_pike_blocked`	Rate-limited IPs	>0 (potential attack)
`kamailio_core_shm_free`	Shared memory free	<10% (memory pressure)

FreeSWITCH Exporter

# Install freeswitch-exporter
pip3 install freeswitch-exporter

# Or use a custom script via ESL
cat > /usr/local/bin/freeswitch_exporter.py << 'PYEOF'
#!/usr/bin/env python3
"""FreeSWITCH Prometheus exporter via ESL."""
import subprocess
import time
from prometheus_client import start_http_server, Gauge

# Metrics
calls_active = Gauge('freeswitch_calls_active', 'Active calls')
channels_active = Gauge('freeswitch_channels_active', 'Active channels')
registrations = Gauge('freeswitch_registrations_active', 'Active registrations')
cpu_idle = Gauge('freeswitch_cpu_idle_percent', 'CPU idle percentage')
sessions_peak = Gauge('freeswitch_sessions_peak', 'Peak sessions since start')
sessions_per_sec = Gauge('freeswitch_sessions_per_second', 'Current sessions per second')
uptime = Gauge('freeswitch_uptime_seconds', 'Uptime in seconds')

def collect():
    try:
        # Active calls
        out = subprocess.check_output(["fs_cli", "-x", "show calls count"], text=True)
        calls_active.set(int(out.strip().split()[0]))

        # Channels
        out = subprocess.check_output(["fs_cli", "-x", "show channels count"], text=True)
        channels_active.set(int(out.strip().split()[0]))

        # Registrations
        out = subprocess.check_output(["fs_cli", "-x", "show registrations count"], text=True)
        registrations.set(int(out.strip().split()[0]))

        # Status
        out = subprocess.check_output(["fs_cli", "-x", "status"], text=True)
        for line in out.split('\n'):
            if 'session(s) - peak' in line:
                parts = line.split()
                sessions_peak.set(int(parts[0]))
            if 'session(s) per Sec' in line:
                parts = line.split()
                sessions_per_sec.set(float(parts[0]))
            if 'years' in line or 'days' in line or 'hours' in line:
                # Parse uptime — simplified
                pass
    except Exception as e:
        print(f"Collection error: {e}")

if __name__ == '__main__':
    start_http_server(9282)
    while True:
        collect()
        time.sleep(15)
PYEOF
chmod +x /usr/local/bin/freeswitch_exporter.py

# Create systemd service
cat > /etc/systemd/system/freeswitch-exporter.service << 'EOF'
[Unit]
Description=FreeSWITCH Prometheus Exporter
After=freeswitch.service

[Service]
ExecStart=/usr/local/bin/freeswitch_exporter.py
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now freeswitch-exporter

RTPEngine Exporter

# rtpengine-exporter scrapes RTPEngine's statistics interface
cat > /usr/local/bin/rtpengine_exporter.py << 'PYEOF'
#!/usr/bin/env python3
"""RTPEngine Prometheus exporter via ng control protocol."""
import socket
import bencodepy
import time
from prometheus_client import start_http_server, Gauge

RTPENGINE_HOST = "127.0.0.1"
RTPENGINE_PORT = 2223

# Metrics
sessions = Gauge('rtpengine_sessions_active', 'Active media sessions')
sessions_total = Gauge('rtpengine_sessions_total', 'Total sessions since start')
errors = Gauge('rtpengine_errors_total', 'Total errors')
offer_total = Gauge('rtpengine_offer_total', 'Total offer commands')
answer_total = Gauge('rtpengine_answer_total', 'Total answer commands')
delete_total = Gauge('rtpengine_delete_total', 'Total delete commands')
packets_relayed = Gauge('rtpengine_packets_relayed', 'Packets relayed')
bytes_relayed = Gauge('rtpengine_bytes_relayed', 'Bytes relayed')

def query_rtpengine(command):
    """Send ng protocol command to RTPEngine."""
    cookie = "stats_" + str(int(time.time()))
    msg = bencodepy.encode({
        b"command": command.encode()
    })
    full_msg = f"{cookie} ".encode() + msg

    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
    sock.settimeout(2)
    sock.sendto(full_msg, (RTPENGINE_HOST, RTPENGINE_PORT))
    data, _ = sock.recvfrom(65535)
    sock.close()

    # Strip cookie prefix
    space_idx = data.index(b' ')
    return bencodepy.decode(data[space_idx + 1:])

def collect():
    try:
        result = query_rtpengine("list totals")
        if b'result' in result and result[b'result'] == b'ok':
            totals = result.get(b'totals', {})

            sessions.set(totals.get(b'current_sessions', 0))
            sessions_total.set(totals.get(b'total_sessions', 0))
            offer_total.set(totals.get(b'offer', 0))
            answer_total.set(totals.get(b'answer', 0))
            delete_total.set(totals.get(b'delete', 0))
    except Exception as e:
        print(f"Collection error: {e}")

if __name__ == '__main__':
    start_http_server(9283)
    while True:
        collect()
        time.sleep(15)
PYEOF
chmod +x /usr/local/bin/rtpengine_exporter.py

Prometheus Scrape Configuration

Add to your prometheus.yml:

scrape_configs:
  # Kamailio
  - job_name: 'kamailio'
    static_configs:
      - targets:
          - 'YOUR_KAM1_PRIVATE:9494'
          - 'YOUR_KAM2_PRIVATE:9494'
        labels:
          component: 'kamailio'

  # FreeSWITCH
  - job_name: 'freeswitch'
    static_configs:
      - targets:
          - 'YOUR_FS1_IP:9282'
          - 'YOUR_FS2_IP:9282'
          - 'YOUR_FS3_IP:9282'
        labels:
          component: 'freeswitch'

  # RTPEngine
  - job_name: 'rtpengine'
    static_configs:
      - targets:
          - 'YOUR_RTP1_PRIVATE:9283'
          - 'YOUR_RTP2_PRIVATE:9283'
        labels:
          component: 'rtpengine'

  # MariaDB (via mysqld_exporter)
  - job_name: 'mariadb'
    static_configs:
      - targets:
          - 'YOUR_DB1_IP:9104'
          - 'YOUR_DB2_IP:9104'
          - 'YOUR_DB3_IP:9104'
        labels:
          component: 'database'

Grafana Dashboard

Import or create a dashboard with these panels:

Row 1: Platform Overview
  - Total active calls (sum of all FS instances)
  - Active registrations
  - Calls per second (rate)
  - Platform uptime

Row 2: Kamailio
  - Active dialogs (gauge)
  - SIP response codes (stacked bar: 2xx, 3xx, 4xx, 5xx)
  - Dispatcher backend status (table: name, state, latency)
  - Shared memory usage (%)

Row 3: FreeSWITCH
  - Active calls per instance (stacked area)
  - Channels per instance (line)
  - CPU usage per instance (line)
  - Sessions per second (rate)

Row 4: RTPEngine
  - Active media sessions (gauge)
  - Packets relayed per second (rate)
  - Media errors (rate)
  - Session duration histogram

Row 5: Database
  - Queries per second
  - Replication lag (Galera)
  - Connection count
  - Slow queries

Homer — SIP Capture and Analysis

Homer provides deep SIP packet analysis — essential for debugging call flows across multiple components.

# Install heplify agent on each SIP component (Kamailio, FreeSWITCH)
wget https://github.com/sipcapture/heplify/releases/latest/download/heplify -O /usr/local/bin/heplify
chmod +x /usr/local/bin/heplify

# Run heplify on Kamailio servers
cat > /etc/systemd/system/heplify.service << 'EOF'
[Unit]
Description=HEPlify SIP Capture Agent
After=network.target

[Service]
ExecStart=/usr/local/bin/heplify \
    -i eth0 \
    -hs YOUR_HOMER_IP:9060 \
    -m SIP \
    -dim REGISTER \
    -pr 5060-5061
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now heplify

Alerting Rules

# prometheus/alerts/voip-platform.yml
groups:
  - name: voip_platform
    rules:
      # All FreeSWITCH servers down
      - alert: AllMediaServersDown
        expr: count(freeswitch_calls_active) == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "All FreeSWITCH media servers are down"

      # Single FreeSWITCH down
      - alert: MediaServerDown
        expr: up{job="freeswitch"} == 0
        for: 2m
        labels:
          severity: warning
        annotations:
          summary: "FreeSWITCH {{ $labels.instance }} is down"

      # Kamailio high error rate
      - alert: KamailioHighErrorRate
        expr: rate(kamailio_tmx_code_total{code=~"5.."}[5m]) > 0.5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Kamailio 5xx error rate > 0.5/sec"

      # Dispatcher all backends down
      - alert: DispatcherAllBackendsDown
        expr: kamailio_dispatcher_target_up == 0
        for: 30s
        labels:
          severity: critical
        annotations:
          summary: "All dispatcher backends are down"

      # RTPEngine down
      - alert: RTPEngineDown
        expr: up{job="rtpengine"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "RTPEngine {{ $labels.instance }} is down"

      # High call volume (capacity planning)
      - alert: HighCallVolume
        expr: sum(freeswitch_calls_active) > 2000
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Platform handling {{ $value }} concurrent calls (threshold: 2000)"

      # Database replication lag
      - alert: GaleraReplicationLag
        expr: mysql_galera_cluster_status{wsrep_local_recv_queue_avg} > 10
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Galera replication queue building up"

Operational Runbook

Adding a New FreeSWITCH Node

# 1. Set up the new server (base OS + FreeSWITCH install from Section 7)
# 2. Configure SIP profile, ACL, dialplan (copy from existing FS node)
# 3. Test locally: fs_cli -x "sofia status profile kamailio"

# 4. Add to dispatcher database
mysql -u kamailio -pYOUR_DB_PASSWORD kamailio -e \
    "INSERT INTO dispatcher (setid, destination, flags, priority, attrs, description) \
     VALUES (1, 'sip:NEW_FS_IP:5060', 0, 0, 'weight=50;duid=fs04', 'FreeSWITCH-4 Media');"

# 5. Reload dispatcher on Kamailio
kamcmd dispatcher.reload

# 6. Verify the new node appears
kamcmd dispatcher.list

# 7. Monitor — should start receiving calls within seconds

Removing a FreeSWITCH Node

# 1. Drain the node (Section 11)
./drain-freeswitch.sh fs03 YOUR_FS3_IP

# 2. Stop FreeSWITCH
ssh YOUR_FS3_IP "systemctl stop freeswitch"

# 3. Remove from dispatcher database
mysql -u kamailio -pYOUR_DB_PASSWORD kamailio -e \
    "DELETE FROM dispatcher WHERE destination='sip:YOUR_FS3_IP:5060';"

# 4. Reload dispatcher
kamcmd dispatcher.reload

Certificate Rotation

# 1. Renew certificate (certbot handles this automatically)
certbot renew

# 2. Reload services (handled by deploy hook, but manual if needed)
systemctl reload kamailio
systemctl restart rtpengine

# 3. Verify TLS
openssl s_client -connect YOUR_PUBLIC_VIP:5061 -brief
openssl s_client -connect YOUR_PUBLIC_VIP:8443 -brief

14. Troubleshooting

Call Flow Debugging Across Components

When a call fails, you need to trace it through all components. The Call-ID is the common thread:

Step 1: Find the Call-ID
  - From the SIP phone/trunk: check the INVITE headers
  - From Kamailio logs: grep for the caller/callee number
  - From Homer: search by phone number or time range

Step 2: Trace through Kamailio
  grep "CALL-ID-HERE" /var/log/kamailio.log

Step 3: Check which FreeSWITCH received it
  - Look for "DISPATCH:" log line with the Call-ID
  - Note the destination IP

Step 4: Trace on FreeSWITCH
  ssh fs01 "grep 'CALL-ID-HERE' /var/log/freeswitch/freeswitch.log"

Step 5: Check RTPEngine
  - RTPEngine logs show SDP manipulation per Call-ID
  journalctl -u rtpengine | grep "CALL-ID-HERE"

Live Debugging Commands

# ---- Kamailio ----

# Watch SIP traffic in real-time
sngrep -d eth0 port 5060

# Enable debug logging temporarily
kamcmd cfg.seti core debug 4
# ... reproduce the issue ...
kamcmd cfg.seti core debug 2   # Restore normal level

# Check active dialogs
kamcmd dlg.list

# Check dispatcher status
kamcmd dispatcher.list

# Memory usage
kamcmd core.shmmem

# ---- FreeSWITCH ----

# Show active calls
fs_cli -x "show calls"

# Show active channels with details
fs_cli -x "show channels"

# Trace a specific call (enable sofia debug)
fs_cli -x "sofia loglevel all 9"
# ... reproduce the issue ...
fs_cli -x "sofia loglevel all 0"   # Restore

# SIP trace on the kamailio profile
fs_cli -x "sofia profile kamailio siptrace on"
# ... reproduce ...
fs_cli -x "sofia profile kamailio siptrace off"

# Check codec negotiation
fs_cli -x "show channels" | grep -E "codec|read_codec|write_codec"

# ---- RTPEngine ----

# List all active sessions
rtpengine-ctl list sessions

# Show detailed stats
rtpengine-ctl list totals

# Show per-session details (requires Call-ID)
rtpengine-ctl list sessions CALL-ID-HERE

Common Issues and Solutions

Calls Not Reaching FreeSWITCH (Dispatcher Issues)

Symptom: Kamailio returns 503 "Service Unavailable"

Check 1: Are FreeSWITCH servers marked as active?
  kamcmd dispatcher.list
  Look for "FLAGS: AP" (Active + Probing)
  If "FLAGS: IP" or "FLAGS: DX" — server is detected as down

Check 2: Can Kamailio reach FreeSWITCH on port 5060?
  # From Kamailio server
  nc -u -z YOUR_FS1_IP 5060 && echo OK || echo FAIL
  sipsak -s sip:test@YOUR_FS1_IP:5060

Check 3: Is FreeSWITCH actually listening?
  ssh YOUR_FS1_IP "ss -ulnp | grep 5060"
  ssh YOUR_FS1_IP "fs_cli -x 'sofia status profile kamailio'"

Check 4: ACL blocking?
  ssh YOUR_FS1_IP "fs_cli -x 'reloadacl'"
  Check /var/log/freeswitch/freeswitch.log for "ACL reject"

Fix: If FS is running but dispatcher shows inactive, manually reset:
  kamcmd dispatcher.set_state a 1 sip:YOUR_FS1_IP:5060

One-Way Audio (RTPEngine Issues)

Symptom: Call connects but audio only flows in one direction (or no audio)

Check 1: Is RTPEngine running and reachable?
  echo 'd7:command4:pinge' | nc -u YOUR_RTP1_PRIVATE 2223
  Expected: 'd6:result4:ponge'

Check 2: Are the RTPEngine interfaces correct?
  rtpengine-ctl list sessions
  Verify the session shows correct internal and external IPs

Check 3: SDP analysis — is RTPEngine rewriting SDPs correctly?
  sngrep on Kamailio — compare SDP in INVITE before and after rtpengine_offer()
  The c= line should change from external IP to internal IP (towards FS)
  The c= line in 200 OK should change from FS IP to external IP (towards trunk)

Check 4: Firewall — are RTP ports open?
  On RTPEngine server: ufw status | grep 20000
  Must allow 20000-40000/udp from anywhere (external endpoints)

Check 5: Are there asymmetric routes?
  RTP must flow: External ↔ RTPEngine ↔ FreeSWITCH
  If any hop has incorrect routing, media breaks

Common fix: Verify interface= lines in rtpengine.conf
  interface = internal/PRIVATE_IP        ← Must be reachable from FreeSWITCH
  interface = external/PRIVATE_IP!PUBLIC_IP  ← PUBLIC_IP must be routable from internet

Registration Loops

Symptom: Registrations fail or loop infinitely

Check: Kamailio is trying to proxy REGISTER to FreeSWITCH,
       FreeSWITCH is sending it back to Kamailio

Fix: Ensure Kamailio handles registrations locally (save to location table)
     OR ensure FreeSWITCH does not relay registrations back

In kamailio.cfg, the REGISTER handler should either:
  save("location")   — store locally
  OR forward to FS and NOT relay back

In FreeSWITCH, ensure the kamailio profile does NOT have:
  <param name="accept-blind-reg" value="true"/>

Keepalived VIP Not Floating

Symptom: VIP stays on failed node or does not move to standby

Check 1: Is Keepalived running on both nodes?
  systemctl status keepalived

Check 2: VRRP communication
  tcpdump -i eth0 vrrp
  Both nodes should be sending VRRP advertisements

Check 3: Virtual router ID conflict?
  Ensure virtual_router_id is the same on both nodes
  Ensure no other Keepalived instance on the network uses the same ID

Check 4: Check health script
  /etc/keepalived/check_kamailio.sh
  echo $?   # Should be 0 (healthy) or 1 (unhealthy)

Check 5: IP forwarding
  sysctl net.ipv4.ip_nonlocal_bind
  # Must be 1 for the backup node to send SIP from the VIP
  echo "net.ipv4.ip_nonlocal_bind = 1" >> /etc/sysctl.d/90-voip.conf
  sysctl -p /etc/sysctl.d/90-voip.conf

Performance Bottleneck Identification

Symptom	Likely Bottleneck	Check	Solution
High SIP latency	Kamailio CPU or database	`top` on Kamailio; slow query log	Add Kamailio workers; optimize DB queries
Choppy audio	RTPEngine CPU or network	`top` on RTPEngine; packet loss check	More RTPEngine CPU; check network path
Call setup delays	FreeSWITCH overloaded	`fs_cli status`; check sessions	Add more FS instances to pool
Registration failures	Database slow	Check MariaDB slow query log	Index optimization; increase connections
WebRTC connection failures	TLS/DTLS issues	Check certificates; browser console	Renew certs; verify DTLS config
Failover too slow	Keepalived/dispatcher timing	Check `advert_int` and `ds_ping_interval`	Reduce intervals (trade-off: more traffic)

Capacity Planning Formulas

Kamailio (signaling only):
  Max CPS = CPU_cores × 1000 (approximately)
  4-core = ~4,000 calls/sec setup rate
  Memory: ~1 KB per active dialog + ~0.5 KB per registration

RTPEngine (media relay):
  Max streams = CPU_cores × 500 (G.711, no transcoding)
  8-core = ~4,000 RTP streams = ~2,000 concurrent calls
  With transcoding: divide by 3-5x
  Bandwidth: 87 kbps × concurrent_calls × 2 (bidirectional)

FreeSWITCH (media processing):
  G.711 (no transcoding): CPU_cores × 300
  With recording: CPU_cores × 200
  With transcoding: CPU_cores × 100
  With conferencing: CPU_cores × 50 (mixing is expensive)
  Memory: ~2 MB per active call (+ recording buffer)
  Disk I/O: ~100 KB/s per recorded call (G.711)

Database:
  1 registration = 1 write + periodic refreshes
  1 call = ~5-10 queries (setup + routing + CDR)
  10,000 concurrent calls ≈ 500-1,000 queries/sec

Essential Commands Quick Reference

Component	Command	Purpose
Kamailio	`kamcmd dispatcher.list`	Show backend status
	`kamcmd dlg.list`	List active dialogs
	`kamcmd core.shmmem`	Check memory usage
	`kamcmd cfg.seti core debug 4`	Enable debug logging
	`kamcmd ul.dump`	Dump registration table
	`kamcmd stats.get_statistics all`	All statistics
	`sngrep -d eth0 port 5060`	Live SIP capture
FreeSWITCH	`fs_cli -x "show calls"`	List active calls
	`fs_cli -x "show channels"`	List active channels
	`fs_cli -x "sofia status"`	SIP profile status
	`fs_cli -x "sofia status profile kamailio"`	Kamailio profile details
	`fs_cli -x "reloadxml"`	Reload XML config
	`fs_cli -x "status"`	Overall status
RTPEngine	`rtpengine-ctl list sessions`	Active media sessions
	`rtpengine-ctl list totals`	Aggregate statistics
	`echo 'd7:command4:pinge' \	nc -u IP 2223`
Keepalived	`ip addr show eth0`	Check VIP assignment
	`systemctl status keepalived`	Service status
	`journalctl -u keepalived -f`	Live logs
MariaDB	`SHOW STATUS LIKE 'wsrep%';`	Galera cluster status
	`SHOW PROCESSLIST;`	Active queries
Homer	Web UI: `http://HOMER_IP:9080`	SIP trace search

This concludes Tutorial 43. You now have the knowledge to build, operate, and troubleshoot a carrier-grade VoIP platform with Kamailio + FreeSWITCH + RTPEngine. The architecture described here scales from hundreds to tens of thousands of concurrent calls and provides the fault tolerance expected of production telecommunications infrastructure.

Key takeaways:

Separation of concerns is the fundamental design principle: Kamailio for signaling, RTPEngine for media relay, FreeSWITCH for call logic
Dispatcher is the heart of the load balancing: understand algorithms, probing, and failover
RTPEngine solves NAT, WebRTC bridging, and topology hiding for media — it is essential in any production deployment
HA comes from pool architecture for FreeSWITCH (not active/standby) and VIP failover for Kamailio
Monitor everything with Prometheus + Grafana + Homer — you cannot fix what you cannot see
Practice draining and failover before you need it in production

Kamailio Fundamentals — Installation, Routing, Authentication & TLS

Moisi Trungu — Thu, 07 May 2026 17:13:51 +0000

Tutorial 42: Kamailio Fundamentals — Installation, Routing, Authentication & TLS

A complete beginner-to-intermediate guide to Kamailio — the high-performance open-source SIP proxy/router. Learn installation, SIP routing logic, user authentication, NAT traversal, TLS encryption, and load balancing from scratch, with production-ready configurations for use as a Session Border Controller (SBC) in front of Asterisk or FreeSWITCH. Whether you need to scale a single-server PBX to handle thousands of concurrent registrations, add a security layer in front of your media servers, or build a multi-tenant SIP platform, Kamailio is the tool that makes it possible.

Technologies: Kamailio, SIP, RTPEngine, TLS, WebRTC, MariaDB, Dispatcher, NAT, Prometheus
Difficulty: Beginner–Intermediate
Reading time: ~70 minutes

Introduction
Architecture Overview
Installation — Debian 12 / Ubuntu 24.04
Configuration Language
SIP Routing
User Authentication
NAT Traversal
TLS & Security
Load Balancing with Dispatcher
Dialog & Accounting
WebRTC Gateway
Integration with Media Servers
Monitoring & Management
Troubleshooting

1. Introduction

What Is Kamailio?

Kamailio is a high-performance, open-source SIP (Session Initiation Protocol) server written in C. It functions as a SIP proxy, SIP registrar, SIP router, and application server. It does not handle media (audio/video) — it exclusively processes SIP signaling messages.

Think of Kamailio as a traffic controller for phone calls. It decides where calls should go, authenticates callers, and enforces policies — but it never touches the actual voice data. That job belongs to media servers like Asterisk, FreeSWITCH, or RTPEngine.

Kamailio Is NOT a PBX

This is the single most important concept to internalize:

Aspect	Kamailio	Asterisk / FreeSWITCH
Role	SIP Proxy / Router	PBX / Media Server (B2BUA)
Media handling	None — signaling only	Full media processing
Call capacity	10,000–50,000+ CPS	200–2,000 concurrent calls
Voicemail, IVR	No	Yes
Conference bridges	No	Yes
Call recording	No	Yes
SIP message processing	Extremely fast (microseconds)	Slower (milliseconds)
Configuration	Custom routing language	dialplan (Asterisk) / XML (FS)
Architecture	Stateless or stateful proxy	Back-to-Back User Agent

B2BUA vs Proxy: Asterisk and FreeSWITCH act as a B2BUA (Back-to-Back User Agent) — they terminate one SIP session and create a new one, sitting in the middle of both the signaling and media paths. Kamailio acts as a proxy — it forwards SIP messages without terminating the session, and media flows directly between endpoints (or through a separate media relay like RTPEngine).

When You Need Kamailio

You need Kamailio when:

Scaling: Your Asterisk server handles 200 registrations fine, but you need to support 10,000+ SIP devices
Security (SBC): You want a hardened front-end that absorbs SIP attacks before they reach your PBX
Load balancing: You have 3+ Asterisk servers and need to distribute calls intelligently
Multi-tenant routing: You operate a SIP platform serving multiple customers/domains
Geographic routing: Route calls to the nearest media server based on caller location
WebRTC gateway: Bridge browser-based SIP.js/JsSIP clients to your traditional SIP infrastructure
Registration proxy: Offload thousands of SIP registrations from your media server
Topology hiding: Hide your internal network structure from external SIP peers
Regulatory compliance: Apply call routing rules, rate limiting, and CDR collection at the edge

Use Cases

Use Case	Description
Session Border Controller (SBC)	Front-end proxy protecting Asterisk/FreeSWITCH from the internet
SIP Load Balancer	Distribute calls across multiple media servers with failover
SIP Registrar	Handle 50,000+ device registrations efficiently
SIP Router	Route calls between carriers, PBXes, and customers
WebRTC Gateway	Convert WSS/SIP.js traffic to standard SIP+RTP
Fraud Prevention	Rate limiting, geo-blocking, call pattern analysis
Number Portability	LNP database lookups for call routing

2. Architecture Overview

Core Engine

Kamailio's core is a SIP message processing engine. When a SIP message arrives, the core:

Parses the SIP message
Executes the routing logic defined in kamailio.cfg
Forwards, replies, or drops the message based on your rules

The core itself is minimal — most functionality comes from modules.

Module System

Kamailio has 200+ modules. Here are the essential ones:

Module	Purpose
sl	Stateless replies (400, 500 errors)
tm	Transaction management (stateful SIP processing)
rr	Record-Route header handling (stay in the signaling path)
maxfwd	Max-Forwards header check (loop prevention)
usrloc	User location database (where devices are registered)
registrar	REGISTER request processing
auth	SIP authentication framework
auth_db	Database-backed authentication (subscriber table)
dialog	Call dialog tracking (active call count, duration)
dispatcher	Load balancing / failover to backend servers
nathelper	NAT detection and signaling fix-up
rtpengine	RTPEngine media relay integration
tls	TLS/SSL transport for SIP
websocket	SIP over WebSocket (for WebRTC)
pike	Flood detection and blocking
htable	In-memory hash tables (blacklists, caches)
acc	Call accounting (CDRs)
permissions	IP-based access control
topoh	Topology hiding
jsonrpcs	JSON-RPC management interface
xlog	Extended logging with pseudo-variables

Configuration Language

Kamailio uses its own configuration language in kamailio.cfg. The config consists of:

Global parameters — server settings (listen address, debug level, etc.)
Module loading — which modules to activate
Module parameters — settings for each module
Route blocks — the actual SIP processing logic

Request Processing Flow

Every SIP request follows this processing chain:

SIP Request arrives
       │
       ▼
┌──────────────┐
│ request_route│ ── Main routing logic (MANDATORY)
└──────┬───────┘
       │ t_relay() / forward()
       ▼
┌──────────────┐
│ branch_route │ ── Per-branch processing (before forwarding)
└──────┬───────┘
       │ SIP request sent to destination
       │
       │ Response comes back
       ▼
┌──────────────┐
│ onreply_route│ ── Process responses (180, 200, etc.)
└──────┬───────┘
       │ If negative response (4xx, 5xx, 6xx)
       ▼
┌──────────────┐
│ failure_route│ ── Handle failures (try alternate route)
└──────────────┘

Additional route types:

reply_route — global reply processing (all responses)
onsend_route — executed just before sending a message out
event_route — triggered by internal events (e.g., event_route[tm:local-request])

Media Path — Kamailio Does NOT Touch RTP

                    SIP Signaling
Phone A ◄─────────────────────────────────► Phone B
   │          via Kamailio proxy              │
   │                                          │
   │          RTP Media (Voice)               │
   └──────────────────────────────────────────┘
              Direct (or via RTPEngine)

Kamailio only processes the SIP signaling path. For media (RTP), you either:

Let endpoints send media directly to each other (simple, but breaks with NAT)
Use RTPEngine as a media relay (required for NAT, WebRTC, SRTP)
Route through a B2BUA like Asterisk (which handles both signaling and media)

Comparison: Kamailio vs OpenSIPS vs Asterisk

Feature	Kamailio	OpenSIPS	Asterisk
Type	SIP Proxy	SIP Proxy	B2BUA / PBX
Origin	Fork of SER (2005)	Fork of OpenSER/Kamailio (2008)	Digium (1999)
Language	C	C	C
Config	kamailio.cfg (scripting)	opensips.cfg (scripting)	extensions.conf / ARI
Performance	~50,000 CPS	~50,000 CPS	~200-500 CPS
Media	No (use RTPEngine)	No (use RTPEngine)	Yes (built-in)
Registrations	1M+	1M+	~10,000 practical
IVR/Voicemail	No	No	Yes
Learning curve	Steep	Steep	Moderate
Community	Large, active	Large, active	Very large
License	GPLv2	GPLv2	GPLv2 (dual)

Kamailio and OpenSIPS share the same heritage (both forked from SIP Express Router). They have similar config syntax but have diverged significantly. Choose either based on your team's familiarity — both are production-proven at massive scale.

3. Installation

Prerequisites

OS: Debian 12 (Bookworm) or Ubuntu 24.04 (Noble) — 64-bit
RAM: 1 GB minimum, 4 GB+ recommended for production
CPU: 1 core minimum, 4+ cores for production
Disk: 10 GB minimum
Network: Static public IP, ports 5060/UDP+TCP, 5061/TCP (TLS), 8443/TCP (WSS)

Step 1: Add the Official Kamailio Repository

Always use the official Kamailio repository for the latest stable release:

# Install prerequisites
apt update
apt install -y gnupg2 curl apt-transport-https

# --- For Debian 12 (Bookworm) ---
curl -fsSL https://deb.kamailio.org/kamailiodebkey.gpg | \
  gpg --dearmor -o /usr/share/keyrings/kamailio-archive-keyring.gpg

cat > /etc/apt/sources.list.d/kamailio.list << 'EOF'
deb [signed-by=/usr/share/keyrings/kamailio-archive-keyring.gpg] https://deb.kamailio.org/kamailio60 bookworm main
EOF

# --- For Ubuntu 24.04 (Noble) ---
curl -fsSL https://deb.kamailio.org/kamailiodebkey.gpg | \
  gpg --dearmor -o /usr/share/keyrings/kamailio-archive-keyring.gpg

cat > /etc/apt/sources.list.d/kamailio.list << 'EOF'
deb [signed-by=/usr/share/keyrings/kamailio-archive-keyring.gpg] https://deb.kamailio.org/kamailio60 noble main
EOF

apt update

Step 2: Install Kamailio and Essential Modules

apt install -y \
  kamailio \
  kamailio-mysql-modules \
  kamailio-tls-modules \
  kamailio-websocket-modules \
  kamailio-json-modules \
  kamailio-extra-modules \
  kamailio-xml-modules \
  kamailio-presence-modules

# Verify installation
kamailio -v
# Output: version: kamailio 6.0.x ...

Package breakdown:

Package	Modules Included
`kamailio`	Core + sl, tm, rr, maxfwd, textops, siputils, xlog, sanity, pv, corex, kex
`kamailio-mysql-modules`	db_mysql (MySQL/MariaDB database connector)
`kamailio-tls-modules`	tls (SIP over TLS)
`kamailio-websocket-modules`	websocket (SIP over WebSocket for WebRTC)
`kamailio-json-modules`	json, jsonrpcs (JSON parsing + management interface)
`kamailio-extra-modules`	htable, pike, rtpengine, pipelimit, and more
`kamailio-xml-modules`	XML parsing support
`kamailio-presence-modules`	presence, presence_xml (BLF/presence)

Step 3: Install and Configure the Database

Kamailio needs a database for user authentication, location storage, and call accounting.

# Install MariaDB
apt install -y mariadb-server mariadb-client

# Secure the installation
mysql_secure_installation
# Set root password, remove anonymous users, disable remote root, remove test DB

# Start and enable MariaDB
systemctl enable --now mariadb

Configure the Kamailio database control tool:

# Edit kamctlrc — the database configuration file
cat > /etc/kamailio/kamctlrc << 'CONF'
## Database type: MYSQL, PGSQL, ORACLE, DB_BERKELEY, DBTEXT
DBENGINE=MYSQL

## Database host
DBHOST=localhost

## Database name
DBNAME=kamailio

## Database admin user (for creating the DB)
DBRWUSER="kamailio"
DBRWPW="YOUR_KAMAILIO_DB_PASSWORD"

## Read-only user (optional, for failover)
DBROUSER="kamailioro"
DBROPW="YOUR_KAMAILIO_RO_PASSWORD"

## Database port
DBPORT=3306

## Path to mysql client
INSTALL_EXTRA_TABLES=yes
INSTALL_PRESENCE_TABLES=yes
INSTALL_DBUID_TABLES=yes
CONF

Create the database and tables:

# Create the Kamailio database (answer 'y' to all prompts)
kamdbctl create

# This creates:
# - kamailio database
# - Core tables: location, subscriber, version, etc.
# - Extra tables: dialog, acc, dispatcher, etc.
# - Presence tables: presentity, watchers, etc.

# Verify
mysql -u kamailio -p'YOUR_KAMAILIO_DB_PASSWORD' -e "SHOW TABLES;" kamailio

Expected tables include:

+--------------------+
| Tables_in_kamailio |
+--------------------+
| acc                |
| address            |
| aliases            |
| dialog             |
| dispatcher         |
| domain             |
| location           |
| missed_calls       |
| subscriber         |
| trusted            |
| version            |
| ...                |
+--------------------+

Step 4: Configure Kamailio Defaults

# Enable Kamailio to start via systemd
sed -i 's/^RUN_KAMAILIO=no/RUN_KAMAILIO=yes/' /etc/default/kamailio

# Set memory allocation (adjust based on your server)
sed -i 's/^# SHM_MEMORY=.*/SHM_MEMORY=128/' /etc/default/kamailio
sed -i 's/^# PKG_MEMORY=.*/PKG_MEMORY=16/' /etc/default/kamailio

# Review the defaults file
cat /etc/default/kamailio

The /etc/default/kamailio file should contain:

# Set to "yes" to enable kamailio
RUN_KAMAILIO=yes

# User and group to run as
USER=kamailio
GROUP=kamailio

# Shared memory (MB) — total pool for all Kamailio processes
SHM_MEMORY=128

# Private memory (MB) — per-process memory
PKG_MEMORY=16

# Config file location
CFGFILE=/etc/kamailio/kamailio.cfg

# PID file
PIDFILE=/run/kamailio/kamailio.pid

Step 5: Firewall Configuration

# Using ufw
ufw allow 5060/udp comment "SIP UDP"
ufw allow 5060/tcp comment "SIP TCP"
ufw allow 5061/tcp comment "SIP TLS"
ufw allow 8443/tcp comment "SIP WSS (WebRTC)"
ufw allow 10000:20000/udp comment "RTP Media (RTPEngine)"

# Or using iptables directly
iptables -A INPUT -p udp --dport 5060 -j ACCEPT
iptables -A INPUT -p tcp --dport 5060 -j ACCEPT
iptables -A INPUT -p tcp --dport 5061 -j ACCEPT
iptables -A INPUT -p tcp --dport 8443 -j ACCEPT
iptables -A INPUT -p udp --dport 10000:20000 -j ACCEPT

Step 6: Start and Verify

# Check config syntax before starting
kamailio -c -f /etc/kamailio/kamailio.cfg

# Start Kamailio
systemctl start kamailio
systemctl enable kamailio

# Check status
systemctl status kamailio

# Verify it's listening
ss -ulnp | grep kamailio
ss -tlnp | grep kamailio

# Expected output:
# udp  UNCONN  0  0  0.0.0.0:5060  0.0.0.0:*  users:(("kamailio",pid=...))
# tcp  LISTEN  0  0  0.0.0.0:5060  0.0.0.0:*  users:(("kamailio",pid=...))

Test with a SIP OPTIONS ping:

# Install sipsak (SIP Swiss Army Knife)
apt install -y sipsak

# Send OPTIONS to Kamailio
sipsak -s sip:YOUR_SERVER_IP:5060
# Expected: SIP/2.0 200 OK

# Using kamctl
kamctl stats
kamctl fifo which

# Using kamcmd
kamcmd core.version
kamcmd core.uptime
kamcmd ul.dump

4. Configuration Language

Config File Structure

The Kamailio configuration file (/etc/kamailio/kamailio.cfg) has four distinct sections, and they must appear in this order:

┌─────────────────────────────┐
│ 1. Global Parameters        │  ← Server-wide settings
├─────────────────────────────┤
│ 2. Module Loading           │  ← loadmodule statements
├─────────────────────────────┤
│ 3. Module Parameters        │  ← modparam() calls
├─────────────────────────────┤
│ 4. Route Blocks             │  ← Routing logic
└─────────────────────────────┘

Global Parameters

#!KAMAILIO

/* ===== Global Parameters ===== */

/* Listen addresses — where Kamailio accepts SIP */
listen=udp:YOUR_SERVER_IP:5060
listen=tcp:YOUR_SERVER_IP:5060

/* Server aliases — domains this server responds to */
alias="YOUR_DOMAIN"
alias="YOUR_SERVER_IP"

/* Logging */
debug=2                  # 0=emergency ... 4=debug (use 2 for production)
log_stderror=no          # Log to syslog, not stderr
log_facility=LOG_LOCAL0  # Syslog facility

/* Process configuration */
children=8               # Number of SIP worker processes (per interface)
tcp_children=4           # Number of TCP worker processes
tcp_max_connections=4096  # Max simultaneous TCP connections
tcp_connection_lifetime=3600  # TCP keepalive (seconds)

/* Memory */
# Shared memory and private memory set in /etc/default/kamailio

/* DNS */
dns=no                   # Disable internal DNS (use system resolver)
rev_dns=no               # Disable reverse DNS lookups
dns_try_ipv6=no          # Disable IPv6 DNS queries
use_dns_cache=on         # Cache DNS results
dns_cache_flags=1        # DNS cache settings

/* SIP-specific */
mhomed=0                 # Multi-homed (0=disabled, 1=choose best source IP)
auto_aliases=no          # Don't auto-detect aliases from DNS
server_signature=no      # Hide Kamailio version in Server header
server_header="Server: SIP Proxy"  # Custom Server header
user_agent_header="User-Agent: SIP Proxy"  # Custom UA header

/* Reply to OPTIONS with 200 OK */
#!define WITH_AUTH
#!define WITH_MYSQL
#!define WITH_NAT

Preprocessor directives (#!define) let you enable/disable features at compile time, similar to #ifdef in C.

Module Loading

Modules are loaded with loadmodule. The order can matter — some modules depend on others:

/* ===== Module Loading ===== */

/* Core SIP modules */
loadmodule "kex.so"          # Kamailio core extensions
loadmodule "corex.so"        # Core extra functions
loadmodule "sl.so"           # Stateless replies
loadmodule "tm.so"           # Transaction management (stateful SIP)
loadmodule "tmx.so"          # Transaction extensions
loadmodule "rr.so"           # Record-Route
loadmodule "maxfwd.so"       # Max-Forwards check
loadmodule "pv.so"           # Pseudo-variables
loadmodule "textops.so"      # Text operations on SIP messages
loadmodule "textopsx.so"     # Extended text operations
loadmodule "siputils.so"     # SIP utility functions
loadmodule "xlog.so"         # Extended logging
loadmodule "sanity.so"       # SIP message sanity checks

/* Database */
loadmodule "db_mysql.so"     # MySQL/MariaDB connector

/* User management */
loadmodule "usrloc.so"       # User location (registration database)
loadmodule "registrar.so"    # REGISTER processing

/* Authentication */
loadmodule "auth.so"         # Auth framework
loadmodule "auth_db.so"      # Database-backed auth

/* NAT traversal */
loadmodule "nathelper.so"    # NAT detection + signaling fix
loadmodule "rtpengine.so"    # RTPEngine media relay

/* Dialog and accounting */
loadmodule "dialog.so"       # Call dialog tracking
loadmodule "acc.so"          # Accounting / CDR

/* Load balancing */
loadmodule "dispatcher.so"   # Dispatcher (load balancer)

/* Security */
loadmodule "pike.so"         # Flood detection
loadmodule "htable.so"       # Hash tables

/* Management */
loadmodule "jsonrpcs.so"     # JSON-RPC control interface
loadmodule "ctl.so"          # Control interface (kamcmd)
loadmodule "cfg_rpc.so"      # RPC for config

Module Parameters

Each module is configured with modparam("module_name", "parameter", value):

/* ===== Module Parameters ===== */

/* ----- tm ----- */
modparam("tm", "failure_reply_mode", 3)
modparam("tm", "fr_timer", 30000)        # Final response timeout (ms)
modparam("tm", "fr_inv_timer", 120000)   # INVITE final response timeout (ms)
modparam("tm", "restart_fr_on_each_reply", 1)

/* ----- rr ----- */
modparam("rr", "enable_full_lr", 1)      # Full loose-routing
modparam("rr", "append_fromtag", 1)      # Append From-tag to Record-Route

/* ----- usrloc ----- */
modparam("usrloc", "db_mode", 2)         # 0=cache, 1=write-through, 2=write-back, 3=DB only
modparam("usrloc", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")
modparam("usrloc", "timer_interval", 60) # Cleanup interval (seconds)
modparam("usrloc", "use_domain", 0)      # 0=ignore domain, 1=use domain in AOR

/* ----- registrar ----- */
modparam("registrar", "method_filtering", 1)
modparam("registrar", "max_expires", 3600)     # Max registration lifetime
modparam("registrar", "min_expires", 60)       # Min registration lifetime
modparam("registrar", "default_expires", 600)  # Default if not specified
modparam("registrar", "gruu_enabled", 0)

/* ----- auth_db ----- */
modparam("auth_db", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")
modparam("auth_db", "calculate_ha1", 1)  # Calculate HA1 from plaintext password
modparam("auth_db", "password_column", "password")
modparam("auth_db", "load_credentials", "$avp(s:caller_uuid)=uuid")
modparam("auth_db", "use_domain", 0)

/* ----- nathelper ----- */
modparam("nathelper", "natping_interval", 30)   # NAT keepalive interval
modparam("nathelper", "ping_nated_only", 1)     # Only ping NATed contacts
modparam("nathelper", "sipping", 1)             # Use SIP OPTIONS as keepalive

/* ----- rtpengine ----- */
modparam("rtpengine", "rtpengine_sock", "udp:127.0.0.1:2223")

/* ----- dialog ----- */
modparam("dialog", "db_mode", 1)
modparam("dialog", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")
modparam("dialog", "dlg_flag", 4)
modparam("dialog", "profiles_with_value", "caller")
modparam("dialog", "profiles_no_value", "active_calls")

/* ----- dispatcher ----- */
modparam("dispatcher", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")
modparam("dispatcher", "ds_ping_interval", 10)    # Health check interval (seconds)
modparam("dispatcher", "ds_ping_method", "OPTIONS")
modparam("dispatcher", "ds_probing_threshold", 3)  # Failures before marking down
modparam("dispatcher", "ds_inactive_threshold", 3) # Successes before marking up
modparam("dispatcher", "ds_probing_mode", 1)       # Probe all destinations

/* ----- pike ----- */
modparam("pike", "sampling_time_unit", 2)  # Sampling window (seconds)
modparam("pike", "reqs_density_per_unit", 30) # Max requests per window
modparam("pike", "remove_latency", 4)      # Ban duration (sampling units)

/* ----- jsonrpcs ----- */
modparam("jsonrpcs", "pretty_format", 1)
modparam("jsonrpcs", "transport", 1)  # 0=FIFO, 1=datagram, 2=both

Route Blocks

Route blocks contain the actual SIP processing logic:

/* ===== Route Blocks ===== */

/* Main request routing */
request_route {
    # This is where every incoming SIP request is processed
    xlog("L_INFO", "Received $rm from $si:$sp — R-URI: $ru\n");

    # ... routing logic ...
}

/* Named sub-routes (called with route(NAME)) */
route[AUTH] {
    # Authentication logic
}

route[REGISTRAR] {
    # Registration handling
}

route[RELAY] {
    # Forward the request
}

/* Reply processing */
reply_route {
    # Process all SIP responses
}

onreply_route[MANAGE_REPLY] {
    # Per-transaction reply handling
}

/* Failure handling */
failure_route[MANAGE_FAILURE] {
    # Called when a transaction receives a negative final response
}

/* Branch processing */
branch_route[MANAGE_BRANCH] {
    # Called for each branch before forwarding
}

Pseudo-Variables

Pseudo-variables provide access to SIP message fields and internal state. They are the workhorses of Kamailio configuration:

Variable	Description	Example Value
`$si`	Source IP address	`192.168.1.100`
`$sp`	Source port	`5060`
`$ru`	Request URI	`sip:1001@example.com`
`$rU`	Request URI username	`1001`
`$rd`	Request URI domain	`example.com`
`$fu`	From URI	`sip:1000@example.com`
`$fU`	From URI username	`1000`
`$fd`	From URI domain	`example.com`
`$tu`	To URI	`sip:1001@example.com`
`$tU`	To URI username	`1001`
`$rm`	Request method	`INVITE`
`$ci`	Call-ID header	`abc123@host`
`$cs`	CSeq number	`1`
`$ua`	User-Agent header	`Zoiper/5.6`
`$Ri`	Received IP (local)	`10.0.0.1`
`$Rp`	Received port (local)	`5060`
`$proto`	Transport protocol	`UDP`
`$hdr(Name)`	Any SIP header by name	`$hdr(Contact)`
`$var(x)`	Script variable (per-message)	`$var(result)`
`$avp(x)`	AVP variable (per-transaction)	`$avp(auth_result)`
`$xavp(x)`	Extended AVP (structured data)	`$xavp(caller=>name)`
`$sht(table=>key)`	Hash table value	`$sht(blacklist=>$si)`
`$dlg(...)`	Dialog attributes	`$dlg(count)`
`$T_reply_code`	Last reply code in failure_route	`486`
`$retcode` / `$rc`	Return code of last function	`1`

Conditional Logic

# If/else
if ($rm == "INVITE") {
    xlog("L_INFO", "Processing INVITE\n");
} else if ($rm == "REGISTER") {
    xlog("L_INFO", "Processing REGISTER\n");
} else {
    xlog("L_INFO", "Processing $rm\n");
}

# Regex matching
if ($rU =~ "^1[0-9]{3}$") {
    # Request URI username matches 4-digit extension starting with 1
    xlog("L_INFO", "Internal extension: $rU\n");
}

# String matching
if ($ua =~ "friendly-scanner") {
    # Block known SIP scanners
    sl_send_reply(403, "Forbidden");
    exit;
}

# IP matching
if ($si == "10.0.0.1") {
    # Request from trusted IP
}

# Check if header exists
if (is_present_hf("X-Custom-Header")) {
    xlog("L_INFO", "Custom header value: $hdr(X-Custom-Header)\n");
}

# Logical operators
if ($rm == "INVITE" && !has_totag()) {
    # New INVITE (not a re-INVITE)
}

Core Functions

# Forward request statelessly (fast, no failure handling)
forward();

# Forward request statefully (enables failure_route)
t_relay();

# Send a stateless reply
sl_send_reply(200, "OK");
sl_send_reply(403, "Forbidden");
sl_send_reply(503, "Service Unavailable");

# Send a stateful reply
t_reply(200, "OK");

# Rewrite the Request-URI
$ru = "sip:newuser@newdomain.com";
# Or using rewriteuri:
rewriteuri("sip:newuser@newdomain.com");

# Rewrite just the host portion
$rd = "10.0.0.5";

# Rewrite just the username
$rU = "2001";

# Add a SIP header
append_hf("X-Forwarded-For: $si\r\n");

# Remove a SIP header
remove_hf("User-Agent");

# Replace a SIP header
subst_hf("User-Agent", "/.*$/SIP Proxy/", "a");

# Stop processing
exit;

# Drop the message silently
drop();

Complete Minimal Configuration

Here is a complete, working minimal kamailio.cfg that functions as a basic SIP proxy:

#!KAMAILIO

/* ===== Global Parameters ===== */
listen=udp:YOUR_SERVER_IP:5060
listen=tcp:YOUR_SERVER_IP:5060
alias="YOUR_DOMAIN"

debug=2
log_stderror=no
log_facility=LOG_LOCAL0
children=4
auto_aliases=no
server_signature=no

/* ===== Module Loading ===== */
loadmodule "kex.so"
loadmodule "sl.so"
loadmodule "tm.so"
loadmodule "rr.so"
loadmodule "maxfwd.so"
loadmodule "pv.so"
loadmodule "textops.so"
loadmodule "siputils.so"
loadmodule "xlog.so"
loadmodule "sanity.so"

/* ===== Module Parameters ===== */
modparam("tm", "fr_timer", 30000)
modparam("tm", "fr_inv_timer", 120000)
modparam("rr", "enable_full_lr", 1)
modparam("rr", "append_fromtag", 1)

/* ===== Routing Logic ===== */
request_route {
    /* --- 1. Sanity checks --- */
    if (!mf_process_maxfwd_header(10)) {
        sl_send_reply(483, "Too Many Hops");
        exit;
    }
    if (!sanity_check("17895", "7")) {
        xlog("L_WARN", "Malformed SIP from $si:$sp\n");
        exit;
    }

    /* --- 2. Record-Route for in-dialog requests --- */
    if (is_method("INVITE|SUBSCRIBE")) {
        record_route();
    }

    /* --- 3. Handle sequential requests (in-dialog) --- */
    if (has_totag()) {
        if (loose_route()) {
            if (is_method("BYE")) {
                xlog("L_INFO", "BYE from $fU to $tU\n");
            }
            t_relay();
            exit;
        } else {
            /* Sequential request but no Route header — reject */
            sl_send_reply(404, "Not Found");
            exit;
        }
    }

    /* --- 4. Handle CANCEL --- */
    if (is_method("CANCEL")) {
        if (t_check_trans()) {
            t_relay();
        }
        exit;
    }

    /* --- 5. Absorb retransmissions --- */
    t_check_trans();

    /* --- 6. Handle OPTIONS (keepalive) --- */
    if (is_method("OPTIONS") && ($rU == $null || $rU == "")) {
        sl_send_reply(200, "OK");
        exit;
    }

    /* --- 7. Route the request --- */
    xlog("L_INFO", "$rm from $fU@$si to $rU — forwarding\n");
    t_relay();
    exit;
}

5. SIP Routing

REGISTER Handling

Registration is how SIP phones tell Kamailio where they can be reached. The usrloc module stores contact-to-AOR (Address of Record) mappings, and the registrar module processes REGISTER requests.

/* Add to module loading section */
loadmodule "usrloc.so"
loadmodule "registrar.so"

/* Module parameters */
modparam("usrloc", "db_mode", 2)
modparam("usrloc", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")
modparam("registrar", "max_expires", 3600)
modparam("registrar", "default_expires", 600)

Registration route:

route[REGISTRAR] {
    /* Only handle REGISTER */
    if (!is_method("REGISTER")) return;

    /* Check for too many contacts */
    if (is_present_hf("Contact")) {
        if ($hdr(Contact) =~ "\*") {
            /* Unregister all — Contact: * */
        }
    }

    /* Save the registration */
    if (!save("location")) {
        sl_send_reply(500, "Server Error - Registration Failed");
        exit;
    }

    /* save() automatically sends 200 OK with Contact + Expires */
    exit;
}

In request_route, add before the forwarding logic:

/* Handle REGISTER */
if (is_method("REGISTER")) {
    route(REGISTRAR);
    exit;
}

Stateless vs Stateful Forwarding

Stateless (sl module): Kamailio forwards the request and immediately forgets about it. Fast, but no failure handling.

/* Stateless forward — fire and forget */
forward();

Stateful (tm module): Kamailio tracks the transaction, enabling failure routes, timeout handling, and proper retransmission management. This is what you want for INVITE processing.

/* Stateful forward — enables failure_route and onreply_route */
t_on_failure("MANAGE_FAILURE");
t_on_reply("MANAGE_REPLY");
t_on_branch("MANAGE_BRANCH");
t_relay();

Rule of thumb: Always use t_relay() for INVITE transactions. Use forward() only for simple pass-through scenarios where you don't need failure handling.

Record-Route

When Kamailio proxies an INVITE, it must add a Record-Route header to stay in the signaling path for subsequent requests (BYE, re-INVITE, etc.). Without Record-Route, the BYE goes directly between endpoints — Kamailio never sees it and cannot track call state or generate CDRs.

/* Add Record-Route for dialog-initiating requests */
if (is_method("INVITE|SUBSCRIBE")) {
    record_route();
}

What this does:

INVITE from Phone A → Kamailio → Phone B

With record_route(), Kamailio adds:
  Record-Route: <sip:YOUR_SERVER_IP;lr>

Phone B's 200 OK includes this in the Route set.

Now BYE from Phone A → Kamailio → Phone B
     (Kamailio stays in the signaling path)

Without record_route():
     BYE from Phone A → Phone B (directly — Kamailio is bypassed)

Sequential Request Routing (In-Dialog)

After the initial INVITE/200 OK/ACK, subsequent requests (BYE, re-INVITE, UPDATE) are "in-dialog" — they have a To tag. These must be routed using loose_route():

/* Handle sequential (in-dialog) requests */
if (has_totag()) {
    /* Validate Route headers */
    if (loose_route()) {
        /* In-dialog request with valid Route — forward it */
        if (is_method("BYE")) {
            xlog("L_INFO", "Call ended: $fU → $tU (Call-ID: $ci)\n");
            /* Optionally: track in CDR */
        }
        if (is_method("ACK")) {
            /* ACK for 2xx — route it */
        }
        t_relay();
        exit;
    } else {
        /* In-dialog request but no valid Route header */
        if (is_method("ACK")) {
            /* ACK without Route — might be for a local 4xx reply */
            if (t_check_trans()) {
                exit;
            }
            exit;
        }
        /* All other in-dialog without Route — error */
        sl_send_reply(404, "Not Found");
        exit;
    }
}

Routing to External Destinations (SIP Trunks)

To route calls to an external SIP trunk or carrier:

route[TO_TRUNK] {
    /* Route to SIP trunk */
    $ru = "sip:" + $rU + "@TRUNK_IP:5060";

    /* Add custom headers if the trunk requires them */
    append_hf("P-Asserted-Identity: <sip:$fU@YOUR_DOMAIN>\r\n");

    /* Remove internal headers */
    remove_hf("X-Internal-Route");

    /* Forward statefully with failure handling */
    t_on_failure("TRUNK_FAILURE");
    t_relay();
    exit;
}

failure_route[TRUNK_FAILURE] {
    /* If the primary trunk fails, try backup */
    if (t_is_canceled()) exit;

    xlog("L_WARN", "Trunk failed with $T_reply_code for $rU\n");

    if ($T_reply_code >= 500) {
        /* 5xx error — try backup trunk */
        $ru = "sip:" + $rU + "@BACKUP_TRUNK_IP:5060";
        t_relay();
        exit;
    }
}

Complete Routing Configuration

Here is a complete SIP proxy configuration with REGISTER handling, INVITE routing, and in-dialog request management:

request_route {
    /* ---- Sanity ---- */
    if (!mf_process_maxfwd_header(10)) {
        sl_send_reply(483, "Too Many Hops");
        exit;
    }
    if (!sanity_check("17895", "7")) {
        xlog("L_WARN", "Malformed SIP from $si:$sp\n");
        exit;
    }

    /* ---- Anti-flood ---- */
    if (src_ip != myself) {
        if (!pike_check_req()) {
            xlog("L_ALERT", "PIKE BLOCK: $si flooding\n");
            exit;
        }
    }

    /* ---- Record-Route ---- */
    if (is_method("INVITE|SUBSCRIBE")) {
        record_route();
    }

    /* ---- In-dialog requests ---- */
    if (has_totag()) {
        if (loose_route()) {
            if (is_method("BYE")) {
                xlog("L_INFO", "BYE: $fU → $tU ($ci)\n");
            }
            route(RELAY);
            exit;
        }
        if (is_method("ACK") && t_check_trans()) {
            exit;
        }
        sl_send_reply(404, "Not Found");
        exit;
    }

    /* ---- CANCEL ---- */
    if (is_method("CANCEL")) {
        if (t_check_trans()) t_relay();
        exit;
    }

    /* ---- Retransmission absorption ---- */
    t_check_trans();

    /* ---- REGISTER ---- */
    if (is_method("REGISTER")) {
        route(REGISTRAR);
        exit;
    }

    /* ---- OPTIONS keepalive ---- */
    if (is_method("OPTIONS") && ($rU == $null || $rU == "")) {
        sl_send_reply(200, "OK");
        exit;
    }

    /* ---- INVITE routing ---- */
    if (is_method("INVITE")) {
        /* Look up the destination in the location table */
        if (!lookup("location")) {
            /* Not found in registrations — try external routing */
            xlog("L_INFO", "User $rU not registered, sending 404\n");
            sl_send_reply(404, "User Not Found");
            exit;
        }
        /* Found — relay to registered contact */
        route(RELAY);
        exit;
    }

    /* ---- Other requests ---- */
    if (is_method("MESSAGE|NOTIFY|INFO|UPDATE|PRACK|REFER")) {
        if (lookup("location")) {
            route(RELAY);
            exit;
        }
        sl_send_reply(404, "User Not Found");
        exit;
    }

    /* Default — reject */
    sl_send_reply(405, "Method Not Allowed");
    exit;
}

route[RELAY] {
    t_on_failure("MANAGE_FAILURE");
    t_on_reply("MANAGE_REPLY");
    if (!t_relay()) {
        sl_send_reply(500, "Server Error");
    }
    exit;
}

route[REGISTRAR] {
    if (!save("location")) {
        sl_send_reply(500, "Registration Failed");
    }
    exit;
}

onreply_route[MANAGE_REPLY] {
    xlog("L_INFO", "Reply $T_reply_code for $rm ($ci)\n");
}

failure_route[MANAGE_FAILURE] {
    if (t_is_canceled()) exit;
    xlog("L_WARN", "Failure $T_reply_code for $rU ($ci)\n");
}

6. User Authentication

Overview

Without authentication, anyone can register phones and make calls through your proxy. Kamailio uses SIP Digest Authentication (RFC 2617) — the same challenge-response mechanism used by HTTP Basic Auth but adapted for SIP.

Authentication flow:

Phone                           Kamailio                    Database
  │                                │                            │
  │─── REGISTER (no auth) ───────►│                            │
  │                                │                            │
  │◄── 401 Unauthorized ──────────│  (with WWW-Authenticate   │
  │    (nonce + realm)             │   challenge)               │
  │                                │                            │
  │─── REGISTER (with auth) ─────►│                            │
  │    (username + response hash)  │── lookup password ────────►│
  │                                │◄── password ───────────────│
  │                                │                            │
  │                                │  verify hash(password +   │
  │                                │  nonce + method + uri)     │
  │                                │                            │
  │◄── 200 OK ────────────────────│                            │

Module Setup

/* Module loading */
loadmodule "auth.so"
loadmodule "auth_db.so"

/* Module parameters */
modparam("auth_db", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")
modparam("auth_db", "calculate_ha1", 1)
modparam("auth_db", "password_column", "password")
modparam("auth_db", "use_domain", 0)

Parameters explained:

calculate_ha1=1: Passwords are stored in plaintext; Kamailio calculates the HA1 hash. Set to 0 if you store pre-computed HA1 hashes (more secure).
password_column: Which column in the subscriber table contains the password.
use_domain=0: Ignore the domain part — authenticate by username only. Set to 1 for multi-domain setups.

Managing Users

# Add a user
kamctl add 1001 MySecurePass123
# This inserts into the 'subscriber' table

# List users
kamctl showdb subscriber

# Change password
kamctl passwd 1001 NewPassword456

# Delete a user
kamctl rm 1001

# Add with domain (if use_domain=1)
kamctl add 1001@example.com MySecurePass123

Alternatively, insert directly into the database:

INSERT INTO subscriber (username, domain, password, ha1, ha1b)
VALUES (
    '1001',
    'YOUR_DOMAIN',
    'MySecurePass123',
    MD5('1001:YOUR_DOMAIN:MySecurePass123'),
    MD5('1001@YOUR_DOMAIN:YOUR_DOMAIN:MySecurePass123')
);

Authentication Route

route[AUTH] {
    /* Skip authentication for requests from trusted IPs */
    if (src_ip == myself) return;

    /* REGISTER requires WWW-Authenticate (401) */
    if (is_method("REGISTER")) {
        if (!www_authorize("YOUR_DOMAIN", "subscriber")) {
            www_challenge("YOUR_DOMAIN", 1);
            exit;
        }
        /* Verify the From URI matches the authenticated user */
        if ($au != $fU) {
            xlog("L_WARN", "Auth mismatch: auth=$au from=$fU ($si)\n");
            sl_send_reply(403, "Forbidden — User Mismatch");
            exit;
        }
        return;  /* Auth passed */
    }

    /* All other requests use Proxy-Authenticate (407) */
    if (!proxy_authorize("YOUR_DOMAIN", "subscriber")) {
        proxy_challenge("YOUR_DOMAIN", 1);
        exit;
    }

    /* Verify authenticated user matches From */
    if ($au != $fU) {
        xlog("L_WARN", "Auth mismatch: auth=$au from=$fU ($si)\n");
        sl_send_reply(403, "Forbidden — User Mismatch");
        exit;
    }

    /* Remove the Proxy-Authorization header before forwarding */
    consume_credentials();
    return;
}

Key functions:

Function	Purpose
`www_authorize(realm, table)`	Check WWW credentials (for REGISTER)
`www_challenge(realm, qop)`	Send 401 with WWW-Authenticate header
`proxy_authorize(realm, table)`	Check Proxy credentials (for INVITE, etc.)
`proxy_challenge(realm, qop)`	Send 407 with Proxy-Authenticate header
`consume_credentials()`	Remove Proxy-Authorization header (don't leak to next hop)

IP-Based Authentication for Trunks

SIP trunks typically authenticate by IP address rather than username/password. Use the permissions module:

loadmodule "permissions.so"
modparam("permissions", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")

Add trusted IPs to the address table:

# Add a trusted trunk IP (group 1 = trunks)
kamctl address add 1 TRUNK_IP 32 5060 "Primary SIP Trunk"

# Reload the address table
kamctl address reload

# Show trusted addresses
kamctl address show

Or directly in the database:

INSERT INTO address (grp, ip_addr, mask, port, tag)
VALUES (1, 'TRUNK_IP', 32, 5060, 'Primary SIP Trunk');

INSERT INTO address (grp, ip_addr, mask, port, tag)
VALUES (1, 'BACKUP_TRUNK_IP', 32, 5060, 'Backup SIP Trunk');

Use in routing:

route[AUTH] {
    /* Check if source IP is a trusted trunk (group 1) */
    if (allow_source_address(1)) {
        xlog("L_INFO", "Trusted trunk: $si ($hdr(P-Asserted-Identity))\n");
        return;  /* Skip digest auth */
    }

    /* Not a trunk — require digest authentication */
    if (is_method("REGISTER")) {
        if (!www_authorize("YOUR_DOMAIN", "subscriber")) {
            www_challenge("YOUR_DOMAIN", 1);
            exit;
        }
    } else {
        if (!proxy_authorize("YOUR_DOMAIN", "subscriber")) {
            proxy_challenge("YOUR_DOMAIN", 1);
            exit;
        }
        consume_credentials();
    }

    /* Verify From matches authenticated user */
    if ($au != $null && $au != $fU) {
        sl_send_reply(403, "Forbidden");
        exit;
    }
    return;
}

Complete Authenticated Proxy Configuration

request_route {
    /* Sanity */
    if (!mf_process_maxfwd_header(10)) {
        sl_send_reply(483, "Too Many Hops");
        exit;
    }
    if (!sanity_check("17895", "7")) {
        exit;
    }

    /* Record-Route */
    if (is_method("INVITE|SUBSCRIBE")) {
        record_route();
    }

    /* In-dialog requests */
    if (has_totag()) {
        if (loose_route()) {
            route(RELAY);
            exit;
        }
        if (is_method("ACK") && t_check_trans()) exit;
        sl_send_reply(404, "Not Found");
        exit;
    }

    /* CANCEL */
    if (is_method("CANCEL")) {
        if (t_check_trans()) t_relay();
        exit;
    }
    t_check_trans();

    /* ---- AUTHENTICATE ---- */
    route(AUTH);

    /* REGISTER */
    if (is_method("REGISTER")) {
        if (!save("location")) {
            sl_send_reply(500, "Registration Failed");
        }
        exit;
    }

    /* OPTIONS */
    if (is_method("OPTIONS") && ($rU == $null || $rU == "")) {
        sl_send_reply(200, "OK");
        exit;
    }

    /* Route to registered user or reject */
    if (!lookup("location")) {
        sl_send_reply(404, "User Not Found");
        exit;
    }
    route(RELAY);
    exit;
}

route[AUTH] {
    /* Trusted trunk IPs — no auth needed */
    if (allow_source_address(1)) return;

    /* REGISTER → 401 challenge */
    if (is_method("REGISTER")) {
        if (!www_authorize("YOUR_DOMAIN", "subscriber")) {
            www_challenge("YOUR_DOMAIN", 1);
            exit;
        }
        if ($au != $fU) {
            sl_send_reply(403, "Forbidden");
            exit;
        }
        return;
    }

    /* All other methods → 407 challenge */
    if (is_method("INVITE|MESSAGE|SUBSCRIBE|NOTIFY|REFER")) {
        if (!proxy_authorize("YOUR_DOMAIN", "subscriber")) {
            proxy_challenge("YOUR_DOMAIN", 1);
            exit;
        }
        if ($au != $fU) {
            sl_send_reply(403, "Forbidden");
            exit;
        }
        consume_credentials();
    }
    return;
}

route[RELAY] {
    t_on_failure("MANAGE_FAILURE");
    if (!t_relay()) {
        sl_send_reply(500, "Server Error");
    }
    exit;
}

failure_route[MANAGE_FAILURE] {
    if (t_is_canceled()) exit;
    xlog("L_WARN", "Call to $rU failed: $T_reply_code\n");
}

7. NAT Traversal

The NAT Problem

NAT (Network Address Translation) is the biggest source of SIP headaches. When a phone behind NAT sends a SIP message, the headers contain the phone's private IP (e.g., 192.168.1.100), but the actual packets arrive from the router's public IP (e.g., 203.0.113.50).

This causes two problems:

Signaling: Kamailio tries to send SIP replies to 192.168.1.100 — which is unreachable from the internet
Media: The SDP body says "send RTP to 192.168.1.100:10000" — the other party cannot reach this address

┌──────────────┐         ┌──────────┐         ┌──────────────┐
│   Phone A    │         │   NAT    │         │   Kamailio   │
│ 192.168.1.100│────────►│  Router  │────────►│ Public IP    │
│ SIP Contact: │         │203.0.113 │         │              │
│ 192.168.1.100│         │  .50     │         │              │
│ SDP c= line: │         │          │         │              │
│ 192.168.1.100│         │          │         │              │
└──────────────┘         └──────────┘         └──────────────┘

Problem: SIP headers say 192.168.1.100
         Packets actually came from 203.0.113.50
         Kamailio can't reply to 192.168.1.100!

NAT Detection with nathelper

The nathelper module provides functions to detect and fix NAT:

/* Module loading */
loadmodule "nathelper.so"

/* Module parameters */
modparam("nathelper", "natping_interval", 30)  # Send keepalive every 30s
modparam("nathelper", "ping_nated_only", 1)    # Only ping NATed clients
modparam("nathelper", "sipping", 1)            # Use SIP OPTIONS as keepalive
modparam("nathelper", "received_avp", "$avp(RECEIVED)")

NAT detection function — nat_uac_test(flags):

Flag	Test
1	Contact header contains RFC1918 private IP
2	Source IP differs from Via "sent-by" address
4	Contact header contains RFC1918 but is different from source IP
8	SDP body contains RFC1918 private IP
16	Source port differs from Via "sent-by" port
32	Contact header port differs from source port

Common usage: nat_uac_test(63) — tests all flags combined (1+2+4+8+16+32 = 63).

Fixing NAT in SIP Signaling

route[NATDETECT] {
    /* Detect NAT */
    if (nat_uac_test(63)) {
        /* Mark this transaction as NATed */
        setflag(5);  /* Flag 5 = NATed */

        /* Fix the Contact header to use the real source IP:port */
        fix_nated_contact();

        /* Force adding rport to Via (so replies go to real source port) */
        force_rport();

        xlog("L_INFO", "NAT detected for $fU from $si:$sp\n");
    }
    return;
}

route[NATMANAGE] {
    /* Fix Contact in replies too */
    if (is_reply()) {
        if (nat_uac_test(63)) {
            fix_nated_contact();
        }
    }
    return;
}

For REGISTER requests, store the real source IP so Kamailio can reach the phone later:

route[REGISTRAR] {
    /* NAT fix for REGISTER */
    if (nat_uac_test(63)) {
        setflag(5);
        fix_nated_register();  /* Store real IP:port in location DB */
        force_rport();
    }

    if (!save("location")) {
        sl_send_reply(500, "Registration Failed");
    }
    exit;
}

RTPEngine — Media NAT Fix

Fixing SIP signaling is only half the battle. The RTP media streams also need NAT handling. RTPEngine is a high-performance media relay that sits alongside Kamailio.

Installing RTPEngine

# Debian 12 / Ubuntu 24.04
apt install -y rtpengine

# Or from the official repository for the latest version:
# Add the RTPEngine repo (check https://dfx.at/rtpengine/ for current URLs)
apt install -y \
  ngcp-rtpengine-daemon \
  ngcp-rtpengine-iptables \
  ngcp-rtpengine-recording-daemon  # Optional: for call recording

Configuring RTPEngine

cat > /etc/rtpengine/rtpengine.conf << 'EOF'
[rtpengine]
# Control socket — Kamailio connects here
listen-ng=127.0.0.1:2223

# Network interfaces
interface=public/YOUR_SERVER_IP

# Port range for RTP
port-min=10000
port-max=20000

# Timeouts
timeout=60
silent-timeout=600
final-timeout=7200

# Logging
log-level=5
log-facility=daemon

# Recording (optional)
# recording-dir=/var/spool/rtpengine
# recording-method=pcap
# recording-format=eth

# TOS/DSCP marking for QoS
tos=184

# Pidfile
pidfile=/run/rtpengine/rtpengine.pid

# Number of worker threads
num-threads=4
EOF

# Enable and start RTPEngine
systemctl enable --now rtpengine
systemctl status rtpengine

# Verify it's listening
ss -ulnp | grep rtpengine

Kamailio RTPEngine Integration

/* Module loading */
loadmodule "rtpengine.so"

/* Module parameters */
modparam("rtpengine", "rtpengine_sock", "udp:127.0.0.1:2223")

Usage in routing logic:

route[NATMANAGE] {
    /* Determine RTPEngine flags based on NAT status and direction */

    if (is_request()) {
        if (has_body("application/sdp")) {
            if (isflagset(5)) {
                /* Caller is NATed — replace private IPs, force relay */
                rtpengine_manage("replace-origin replace-session-connection ICE=remove");
            } else {
                /* Caller is not NATed — just relay for consistency */
                rtpengine_manage("ICE=remove");
            }
        }
    }

    if (is_reply()) {
        if (has_body("application/sdp")) {
            if (isflagset(5)) {
                rtpengine_manage("replace-origin replace-session-connection ICE=remove");
            } else {
                rtpengine_manage("ICE=remove");
            }
        }
    }

    return;
}

RTPEngine flags explained:

Flag	Purpose
`replace-origin`	Replace the `o=` line IP in SDP
`replace-session-connection`	Replace the `c=` line IP in SDP
`ICE=remove`	Strip ICE candidates (for non-WebRTC endpoints)
`ICE=force`	Force ICE (for WebRTC endpoints)
`RTP/SAVPF`	Use SRTP with RTCP feedback (WebRTC)
`RTP/AVP`	Use plain RTP (traditional SIP)
`DTLS=passive`	DTLS-SRTP passive mode (WebRTC)
`rtcp-mux-demux`	Handle RTCP multiplexed on same port
`media-address=IP`	Force specific media address

STUN/TURN Overview

While RTPEngine handles media relay server-side, clients behind NAT may also need STUN/TURN:

STUN: Helps clients discover their public IP. Lightweight but fails with symmetric NAT.
TURN: Full relay server. Works with all NAT types but adds latency and bandwidth cost.
ICE: Framework that uses both STUN and TURN to find the best media path.

For most Kamailio deployments, RTPEngine eliminates the need for client-side STUN/TURN — the proxy handles everything. STUN/TURN becomes important primarily for WebRTC deployments.

If you need a TURN server, coturn is the standard choice:

apt install -y coturn
# Configuration in /etc/turnserver.conf

Complete NAT-Aware Configuration

#!KAMAILIO

/* ===== Global Parameters ===== */
listen=udp:YOUR_SERVER_IP:5060 advertise YOUR_SERVER_IP:5060
listen=tcp:YOUR_SERVER_IP:5060 advertise YOUR_SERVER_IP:5060

debug=2
log_stderror=no
log_facility=LOG_LOCAL0
children=8
auto_aliases=no
server_signature=no
force_rport=yes  /* Always add rport */

/* ===== Module Loading ===== */
loadmodule "kex.so"
loadmodule "sl.so"
loadmodule "tm.so"
loadmodule "tmx.so"
loadmodule "rr.so"
loadmodule "maxfwd.so"
loadmodule "pv.so"
loadmodule "textops.so"
loadmodule "siputils.so"
loadmodule "xlog.so"
loadmodule "sanity.so"
loadmodule "db_mysql.so"
loadmodule "usrloc.so"
loadmodule "registrar.so"
loadmodule "auth.so"
loadmodule "auth_db.so"
loadmodule "nathelper.so"
loadmodule "rtpengine.so"

/* ===== Module Parameters ===== */
modparam("tm", "fr_timer", 30000)
modparam("tm", "fr_inv_timer", 120000)
modparam("rr", "enable_full_lr", 1)
modparam("rr", "append_fromtag", 1)

modparam("usrloc", "db_mode", 2)
modparam("usrloc", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")

modparam("registrar", "max_expires", 3600)
modparam("registrar", "default_expires", 600)

modparam("auth_db", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")
modparam("auth_db", "calculate_ha1", 1)
modparam("auth_db", "password_column", "password")
modparam("auth_db", "use_domain", 0)

modparam("nathelper", "natping_interval", 30)
modparam("nathelper", "ping_nated_only", 1)
modparam("nathelper", "sipping", 1)
modparam("nathelper", "received_avp", "$avp(RECEIVED)")

modparam("rtpengine", "rtpengine_sock", "udp:127.0.0.1:2223")

/* ===== Routing Logic ===== */
request_route {
    /* Sanity checks */
    if (!mf_process_maxfwd_header(10)) {
        sl_send_reply(483, "Too Many Hops");
        exit;
    }
    if (!sanity_check("17895", "7")) {
        exit;
    }

    /* NAT detection */
    route(NATDETECT);

    /* Record-Route */
    if (is_method("INVITE|SUBSCRIBE")) {
        record_route();
    }

    /* In-dialog requests */
    if (has_totag()) {
        if (loose_route()) {
            if (is_method("BYE")) {
                xlog("L_INFO", "BYE: $fU → $tU\n");
                /* Release RTPEngine session */
                rtpengine_delete();
            }
            if (is_method("INVITE|UPDATE|ACK")) {
                route(NATMANAGE);
            }
            route(RELAY);
            exit;
        }
        if (is_method("ACK") && t_check_trans()) exit;
        sl_send_reply(404, "Not Found");
        exit;
    }

    /* CANCEL */
    if (is_method("CANCEL")) {
        if (t_check_trans()) t_relay();
        exit;
    }
    t_check_trans();

    /* Authenticate */
    route(AUTH);

    /* REGISTER */
    if (is_method("REGISTER")) {
        route(REGISTRAR);
        exit;
    }

    /* OPTIONS */
    if (is_method("OPTIONS") && ($rU == $null || $rU == "")) {
        sl_send_reply(200, "OK");
        exit;
    }

    /* INVITE — lookup and route */
    if (!lookup("location")) {
        sl_send_reply(404, "User Not Found");
        exit;
    }

    /* NAT manage for initial INVITE */
    route(NATMANAGE);
    route(RELAY);
    exit;
}

route[RELAY] {
    t_on_reply("MANAGE_REPLY");
    t_on_failure("MANAGE_FAILURE");
    if (!t_relay()) {
        sl_send_reply(500, "Server Error");
    }
    exit;
}

route[AUTH] {
    if (is_method("REGISTER")) {
        if (!www_authorize("YOUR_DOMAIN", "subscriber")) {
            www_challenge("YOUR_DOMAIN", 1);
            exit;
        }
        if ($au != $fU) {
            sl_send_reply(403, "Forbidden");
            exit;
        }
        return;
    }

    if (is_method("INVITE|MESSAGE|SUBSCRIBE")) {
        if (!proxy_authorize("YOUR_DOMAIN", "subscriber")) {
            proxy_challenge("YOUR_DOMAIN", 1);
            exit;
        }
        if ($au != $fU) {
            sl_send_reply(403, "Forbidden");
            exit;
        }
        consume_credentials();
    }
    return;
}

route[REGISTRAR] {
    if (nat_uac_test(63)) {
        setflag(5);
        fix_nated_register();
        force_rport();
    }
    if (!save("location")) {
        sl_send_reply(500, "Registration Failed");
    }
    exit;
}

route[NATDETECT] {
    if (nat_uac_test(63)) {
        setflag(5);
        fix_nated_contact();
        force_rport();
    }
    return;
}

route[NATMANAGE] {
    if (is_request()) {
        if (has_body("application/sdp")) {
            if (isflagset(5)) {
                rtpengine_manage("replace-origin replace-session-connection ICE=remove");
            } else {
                rtpengine_manage("ICE=remove");
            }
        }
    }
    if (is_reply()) {
        if (has_body("application/sdp")) {
            rtpengine_manage("replace-origin replace-session-connection ICE=remove");
        }
    }
    return;
}

onreply_route[MANAGE_REPLY] {
    if (status =~ "[12][0-9][0-9]") {
        route(NATMANAGE);
    }
}

failure_route[MANAGE_FAILURE] {
    if (t_is_canceled()) exit;
    xlog("L_WARN", "Call to $rU failed: $T_reply_code\n");

    if ($T_reply_code == 486 || $T_reply_code == 408) {
        xlog("L_INFO", "User $rU busy or timeout\n");
    }
}

This configuration handles:

NAT detection on all incoming requests
SIP signaling fix-up (Contact, Via, rport)
RTPEngine integration for media relay
NAT keepalive pings to registered clients
Proper RTPEngine session cleanup on BYE
In-dialog NAT management for re-INVITEs and replies

8. TLS & Security

TLS Module Configuration

TLS encrypts SIP signaling, preventing eavesdropping and tampering. SIP over TLS runs on port 5061 by default.

/* Module loading */
loadmodule "tls.so"

/* Global: add TLS listen address */
listen=tls:YOUR_SERVER_IP:5061

/* TLS module parameters */
modparam("tls", "config", "/etc/kamailio/tls.cfg")
modparam("tls", "tls_force_run", 1)   /* Start even if cert is missing */

/* Alternative: inline TLS config (instead of separate tls.cfg) */
modparam("tls", "private_key", "/etc/kamailio/certs/privkey.pem")
modparam("tls", "certificate", "/etc/kamailio/certs/fullchain.pem")
modparam("tls", "ca_list", "/etc/kamailio/certs/chain.pem")
modparam("tls", "tls_method", "TLSv1.2+")     /* Minimum TLS 1.2 */
modparam("tls", "verify_certificate", 0)       /* 0=don't require client cert */
modparam("tls", "require_certificate", 0)      /* 0=allow non-TLS clients */
modparam("tls", "connection_timeout", 60)

Separate TLS Config File

For more granular control, use a dedicated TLS config file (/etc/kamailio/tls.cfg):

# /etc/kamailio/tls.cfg

[server:default]
method = TLSv1.2+
verify_certificate = no
require_certificate = no
private_key = /etc/kamailio/certs/privkey.pem
certificate = /etc/kamailio/certs/fullchain.pem
ca_list = /etc/kamailio/certs/chain.pem

# Specific config for a trusted peer
[server:TRUNK_IP:5061]
method = TLSv1.2+
verify_certificate = yes
require_certificate = yes
private_key = /etc/kamailio/certs/privkey.pem
certificate = /etc/kamailio/certs/fullchain.pem
ca_list = /etc/kamailio/certs/trunk-ca.pem

[client:default]
method = TLSv1.2+
verify_certificate = yes
private_key = /etc/kamailio/certs/privkey.pem
certificate = /etc/kamailio/certs/fullchain.pem
ca_list = /etc/kamailio/certs/chain.pem

Certificate Generation

Option A: Let's Encrypt (Production)

# Install certbot
apt install -y certbot

# Obtain certificate (standalone mode — stop Kamailio briefly)
systemctl stop kamailio
certbot certonly --standalone -d YOUR_DOMAIN

# Certificate files are at:
# /etc/letsencrypt/live/YOUR_DOMAIN/fullchain.pem
# /etc/letsencrypt/live/YOUR_DOMAIN/privkey.pem
# /etc/letsencrypt/live/YOUR_DOMAIN/chain.pem

# Create symlinks for Kamailio
mkdir -p /etc/kamailio/certs
ln -sf /etc/letsencrypt/live/YOUR_DOMAIN/fullchain.pem /etc/kamailio/certs/fullchain.pem
ln -sf /etc/letsencrypt/live/YOUR_DOMAIN/privkey.pem /etc/kamailio/certs/privkey.pem
ln -sf /etc/letsencrypt/live/YOUR_DOMAIN/chain.pem /etc/kamailio/certs/chain.pem

# Set permissions
chown -R kamailio:kamailio /etc/kamailio/certs/

# Auto-renewal with Kamailio reload
cat > /etc/letsencrypt/renewal-hooks/post/kamailio.sh << 'HOOK'
#!/bin/bash
systemctl reload kamailio
HOOK
chmod +x /etc/letsencrypt/renewal-hooks/post/kamailio.sh

systemctl start kamailio

Option B: Self-Signed (Testing)

mkdir -p /etc/kamailio/certs
cd /etc/kamailio/certs

# Generate CA
openssl genrsa -out ca-key.pem 4096
openssl req -x509 -new -nodes -key ca-key.pem -sha256 -days 3650 \
    -out ca-cert.pem \
    -subj "/C=US/ST=State/L=City/O=MyOrg/CN=SIP-CA"

# Generate server certificate
openssl genrsa -out privkey.pem 2048
openssl req -new -key privkey.pem -out server.csr \
    -subj "/C=US/ST=State/L=City/O=MyOrg/CN=YOUR_DOMAIN"

# Sign with CA
openssl x509 -req -in server.csr -CA ca-cert.pem -CAkey ca-key.pem \
    -CAcreateserial -out fullchain.pem -days 365 -sha256

# Copy CA cert as chain
cp ca-cert.pem chain.pem

# Set ownership
chown -R kamailio:kamailio /etc/kamailio/certs/
chmod 600 /etc/kamailio/certs/privkey.pem

Client Certificate Verification

For mutual TLS (mTLS), require clients to present a valid certificate:

/* In tls.cfg — require client certificates */
[server:default]
method = TLSv1.2+
verify_certificate = yes
require_certificate = yes
private_key = /etc/kamailio/certs/privkey.pem
certificate = /etc/kamailio/certs/fullchain.pem
ca_list = /etc/kamailio/certs/ca-cert.pem

In routing logic, you can check TLS peer information:

if ($proto == "tls") {
    xlog("L_INFO", "TLS peer: $tls_peer_subject\n");
    xlog("L_INFO", "TLS peer CN: $tls_peer_subject_cn\n");
    xlog("L_INFO", "TLS peer verified: $tls_peer_verified\n");

    if ($tls_peer_verified != 1) {
        sl_send_reply(403, "Certificate Verification Failed");
        exit;
    }
}

SRTP with RTPEngine

TLS only encrypts SIP signaling. To encrypt the media (RTP), you need SRTP. RTPEngine handles this transparently:

/* In NATMANAGE route — encrypt media */
route[NATMANAGE] {
    if (is_request()) {
        if (has_body("application/sdp")) {
            if ($proto == "tls" || $proto == "wss") {
                /* TLS/WSS client — use SRTP on client side, plain RTP to backend */
                rtpengine_manage("replace-origin replace-session-connection ICE=remove SDES-off RTP/SAVP");
            } else {
                /* Plain SIP — no SRTP */
                rtpengine_manage("replace-origin replace-session-connection ICE=remove");
            }
        }
    }
    if (is_reply()) {
        if (has_body("application/sdp")) {
            rtpengine_manage("replace-origin replace-session-connection ICE=remove");
        }
    }
    return;
}

Pike Module — Flood Protection

The pike module detects and blocks IP addresses that send too many SIP requests (brute-force attacks, SIP scanners):

loadmodule "pike.so"
modparam("pike", "sampling_time_unit", 2)      /* 2-second window */
modparam("pike", "reqs_density_per_unit", 30)  /* Max 30 requests per window */
modparam("pike", "remove_latency", 4)          /* Block for 4 windows (8 seconds) */

Usage in request_route:

request_route {
    /* Anti-flood — check before anything else */
    if (src_ip != myself) {
        if (!pike_check_req()) {
            xlog("L_ALERT", "PIKE: Blocking flood from $si\n");
            /* Silently drop — don't send reply (wastes resources) */
            exit;
        }
    }
    /* ... rest of routing ... */
}

Htable — IP Blacklisting

The htable module provides in-memory hash tables for fast lookups. Use it for blacklists, whitelists, and rate counters:

loadmodule "htable.so"

/* Define a blacklist table */
modparam("htable", "htable", "ipban=>size=8;autoexpire=3600;")
/* size=8: 2^8 = 256 slots, autoexpire=3600: entries expire after 1 hour */

/* Define a counter table for rate limiting per user */
modparam("htable", "htable", "ratelimit=>size=10;autoexpire=60;")

Usage:

request_route {
    /* Check blacklist */
    if ($sht(ipban=>$si) != $null) {
        xlog("L_WARN", "Blocked blacklisted IP: $si\n");
        exit;  /* Silently drop */
    }

    /* After pike blocks, add to blacklist */
    if (src_ip != myself) {
        if (!pike_check_req()) {
            $sht(ipban=>$si) = 1;
            xlog("L_ALERT", "BLACKLISTED: $si (pike trigger)\n");
            exit;
        }
    }

    /* Per-user rate limiting (max 10 INVITE per minute) */
    if (is_method("INVITE") && !has_totag()) {
        $sht(ratelimit=>$fU) = $sht(ratelimit=>$fU) + 1;
        if ($sht(ratelimit=>$fU) > 10) {
            sl_send_reply(429, "Too Many Requests");
            exit;
        }
    }
}

fail2ban Integration

Kamailio can log authentication failures in a format that fail2ban can parse:

/* In the AUTH route — log failures */
route[AUTH] {
    if (is_method("REGISTER")) {
        if (!www_authorize("YOUR_DOMAIN", "subscriber")) {
            /* Log for fail2ban — note the specific format */
            xlog("L_WARN", "AUTH_FAILED: method=REGISTER user=$fU from=$si\n");
            www_challenge("YOUR_DOMAIN", 1);
            exit;
        }
    }
}

Create a fail2ban filter for Kamailio:

cat > /etc/fail2ban/filter.d/kamailio.conf << 'EOF'
[Definition]
failregex = AUTH_FAILED:.*from=<HOST>
ignoreregex =
EOF

Create a fail2ban jail:

cat > /etc/fail2ban/jail.d/kamailio.conf << 'EOF'
[kamailio]
enabled  = true
filter   = kamailio
logpath  = /var/log/kamailio/kamailio.log
maxretry = 5
findtime = 300
bantime  = 3600
action   = iptables-allports[name=kamailio, protocol=all]
EOF

# Make sure Kamailio logs to a file (rsyslog)
cat > /etc/rsyslog.d/kamailio.conf << 'EOF'
local0.*    /var/log/kamailio/kamailio.log
EOF

mkdir -p /var/log/kamailio
systemctl restart rsyslog
systemctl restart fail2ban

Security Best Practices

Practice	Implementation
Hide server version	`server_signature=no` in kamailio.cfg
Block scanners	Check User-Agent for `friendly-scanner`, `sipcli`, `sipvicious`
Require auth	Always authenticate REGISTER and INVITE from external sources
Use TLS	Enable port 5061, redirect SIP phones to use TLS
Rate limit	Pike + htable for per-IP and per-user rate limiting
IP whitelist	Use `permissions` module for trusted trunk IPs
Geo-blocking	Use GeoIP module to block countries you don't serve
Topology hiding	Use `topoh` module to strip internal IPs from SIP headers
Log auth failures	Enable fail2ban integration
Firewall	Only open ports 5060/5061 to the internet, restrict RTP range
Regular updates	Keep Kamailio and RTPEngine updated

9. Load Balancing with Dispatcher

What Is the Dispatcher Module?

The dispatcher module distributes SIP traffic across multiple backend servers (Asterisk, FreeSWITCH, etc.) with health checking and automatic failover. This is the most common reason to deploy Kamailio in front of a PBX cluster.

                    ┌──────────────┐
                    │   Kamailio   │
                    │  (Dispatcher)│
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
         ┌────▼───┐  ┌────▼───┐  ┌────▼───┐
         │Asterisk│  │Asterisk│  │Asterisk│
         │   #1   │  │   #2   │  │   #3   │
         └────────┘  └────────┘  └────────┘

Module Setup

loadmodule "dispatcher.so"

modparam("dispatcher", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")
modparam("dispatcher", "table_name", "dispatcher")
modparam("dispatcher", "flags", 2)                    /* Failover support */
modparam("dispatcher", "ds_ping_interval", 10)        /* Health check every 10s */
modparam("dispatcher", "ds_ping_method", "OPTIONS")   /* Use SIP OPTIONS */
modparam("dispatcher", "ds_probing_threshold", 3)     /* 3 failures = down */
modparam("dispatcher", "ds_inactive_threshold", 3)    /* 3 successes = up */
modparam("dispatcher", "ds_probing_mode", 1)          /* Probe all destinations */
modparam("dispatcher", "ds_ping_from", "sip:kamailio@YOUR_DOMAIN")
modparam("dispatcher", "ds_ping_reply_codes", "class2;class3;class4")

Destination Sets and Algorithms

Destinations are organized into sets (groups). Each set has an algorithm that determines how traffic is distributed:

Algorithm	ID	Description
Round-Robin	0	Rotate through backends sequentially
Weight-Based	1	Distribute by weight (e.g., 70/30 split)
Call-ID Hash	2	Same Call-ID always goes to same backend
Random	3	Random selection
Priority	4	Always use first available (active-standby)
Hash over From URI	5	Same caller always reaches same backend
Hash over To URI	6	Same destination always reaches same backend
Hash over Request URI	7	Hash on R-URI
Hash over source IP	8	Same source IP always reaches same backend
Weight-based random	9	Random with weight probability
Call-load distribution	10	Least-loaded backend (requires dialog module)
Relative weight	11	Weight relative to total
Random (no reuse)	12	Random without selecting the same destination twice

Adding Backend Servers

Via Database

/* dispatcher table: setid, destination, flags, priority, attrs, description */

-- Set 1: Asterisk backends (Round-Robin)
INSERT INTO dispatcher (setid, destination, flags, priority, attrs, description)
VALUES (1, 'sip:10.0.0.10:5060', 0, 0, 'weight=50;duid=ast1', 'Asterisk 1');

INSERT INTO dispatcher (setid, destination, flags, priority, attrs, description)
VALUES (1, 'sip:10.0.0.11:5060', 0, 0, 'weight=30;duid=ast2', 'Asterisk 2');

INSERT INTO dispatcher (setid, destination, flags, priority, attrs, description)
VALUES (1, 'sip:10.0.0.12:5060', 0, 0, 'weight=20;duid=ast3', 'Asterisk 3');

-- Set 2: Media servers (Priority-based failover)
INSERT INTO dispatcher (setid, destination, flags, priority, attrs, description)
VALUES (2, 'sip:10.0.0.20:5060', 0, 0, 'duid=media1', 'Primary Media');

INSERT INTO dispatcher (setid, destination, flags, priority, attrs, description)
VALUES (2, 'sip:10.0.0.21:5060', 0, 1, 'duid=media2', 'Backup Media');

# Reload dispatcher data
kamcmd dispatcher.reload

Via File (Alternative to Database)

If you prefer not to use a database, configure dispatcher to use a flat file:

modparam("dispatcher", "list_file", "/etc/kamailio/dispatcher.list")
modparam("dispatcher", "ds_probing_mode", 1)

Create /etc/kamailio/dispatcher.list:

# Format: setid destination flags priority attrs
# Set 1: Asterisk backends
1 sip:10.0.0.10:5060 0 0 weight=50;duid=ast1
1 sip:10.0.0.11:5060 0 0 weight=30;duid=ast2
1 sip:10.0.0.12:5060 0 0 weight=20;duid=ast3

# Set 2: Media servers (priority failover)
2 sip:10.0.0.20:5060 0 0 duid=media1
2 sip:10.0.0.21:5060 0 1 duid=media2

Dispatcher Routing Logic

route[DISPATCH] {
    /* Select a backend from set 1 using round-robin (algorithm 0) */
    if (!ds_select_dst(1, 0)) {
        /* No backends available */
        xlog("L_ERR", "DISPATCHER: No backends available in set 1\n");
        sl_send_reply(503, "Service Unavailable");
        exit;
    }

    xlog("L_INFO", "DISPATCH: Routing $rU to $du (set 1)\n");

    /* Enable failover — if this backend fails, try the next */
    t_on_failure("DISPATCH_FAILURE");
    route(RELAY);
    exit;
}

failure_route[DISPATCH_FAILURE] {
    if (t_is_canceled()) exit;

    /* Mark the failed destination as inactive */
    if (t_check_status("5[0-9][0-9]") || t_check_status("408")) {
        xlog("L_WARN", "DISPATCH: Backend $du failed ($T_reply_code), trying next\n");
        ds_mark_dst("ip");  /* Mark as inactive (probing) */

        /* Try the next backend in the set */
        if (ds_next_dst()) {
            xlog("L_INFO", "DISPATCH: Failover to $du\n");
            t_on_failure("DISPATCH_FAILURE");
            route(RELAY);
            exit;
        }

        /* All backends down */
        xlog("L_ERR", "DISPATCH: All backends in set 1 are down\n");
        t_reply(503, "All Backends Unavailable");
        exit;
    }
}

Health Checking

Kamailio automatically sends SIP OPTIONS pings to all dispatcher destinations at the configured interval. The health check behavior:

Backend UP:
  ─── OPTIONS ──► Backend
  ◄── 200 OK ────  Backend
  (Counter: successes = 0 → stays UP)

Backend goes DOWN:
  ─── OPTIONS ──► Backend
  ◄── [timeout] ──  Backend
  (Counter: failures = 1, 2, 3 → marked INACTIVE when threshold reached)

Backend recovers:
  ─── OPTIONS ──► Backend
  ◄── 200 OK ────  Backend
  (Counter: successes = 1, 2, 3 → marked ACTIVE when threshold reached)

Monitor dispatcher status:

# Show all destinations and their status
kamcmd dispatcher.list

# Output format:
# SET    DEST                      FLAGS   PRIORITY  ATTRS
# 1      sip:10.0.0.10:5060       AP      0         weight=50
# 1      sip:10.0.0.11:5060       AP      0         weight=30
# 1      sip:10.0.0.12:5060       IP      0         weight=20

# Flags: A=Active, I=Inactive, P=Probing, D=Disabled, X=Deleted

# Manually set destination state
kamcmd dispatcher.set_state ip 1 sip:10.0.0.12:5060  # Set to Inactive/Probing
kamcmd dispatcher.set_state ap 1 sip:10.0.0.12:5060  # Set to Active/Probing

Complete Dispatcher Configuration for 3 Asterisk Backends

#!KAMAILIO
#!define WITH_DISPATCHER

listen=udp:YOUR_SERVER_IP:5060
listen=tcp:YOUR_SERVER_IP:5060
debug=2
log_stderror=no
log_facility=LOG_LOCAL0
children=8
auto_aliases=no
server_signature=no

/* Modules */
loadmodule "kex.so"
loadmodule "sl.so"
loadmodule "tm.so"
loadmodule "tmx.so"
loadmodule "rr.so"
loadmodule "maxfwd.so"
loadmodule "pv.so"
loadmodule "textops.so"
loadmodule "siputils.so"
loadmodule "xlog.so"
loadmodule "sanity.so"
loadmodule "db_mysql.so"
loadmodule "usrloc.so"
loadmodule "registrar.so"
loadmodule "auth.so"
loadmodule "auth_db.so"
loadmodule "dispatcher.so"
loadmodule "nathelper.so"
loadmodule "rtpengine.so"
loadmodule "dialog.so"

/* Module parameters */
modparam("tm", "fr_timer", 30000)
modparam("tm", "fr_inv_timer", 120000)
modparam("rr", "enable_full_lr", 1)
modparam("rr", "append_fromtag", 1)

modparam("usrloc", "db_mode", 2)
modparam("usrloc", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")

modparam("registrar", "max_expires", 3600)
modparam("registrar", "default_expires", 600)

modparam("auth_db", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")
modparam("auth_db", "calculate_ha1", 1)
modparam("auth_db", "password_column", "password")
modparam("auth_db", "use_domain", 0)

/* Dispatcher — load balancer */
modparam("dispatcher", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")
modparam("dispatcher", "flags", 2)
modparam("dispatcher", "ds_ping_interval", 10)
modparam("dispatcher", "ds_ping_method", "OPTIONS")
modparam("dispatcher", "ds_probing_threshold", 3)
modparam("dispatcher", "ds_inactive_threshold", 3)
modparam("dispatcher", "ds_probing_mode", 1)
modparam("dispatcher", "ds_ping_from", "sip:kamailio@YOUR_DOMAIN")
modparam("dispatcher", "ds_ping_reply_codes", "class2;class3;class4")

/* NAT */
modparam("nathelper", "natping_interval", 30)
modparam("nathelper", "ping_nated_only", 1)
modparam("nathelper", "sipping", 1)
modparam("nathelper", "received_avp", "$avp(RECEIVED)")

modparam("rtpengine", "rtpengine_sock", "udp:127.0.0.1:2223")

/* Dialog — for call-load balancing */
modparam("dialog", "db_mode", 1)
modparam("dialog", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")
modparam("dialog", "dlg_flag", 4)

/* ===== Routing ===== */
request_route {
    if (!mf_process_maxfwd_header(10)) {
        sl_send_reply(483, "Too Many Hops");
        exit;
    }
    if (!sanity_check("17895", "7")) exit;

    /* NAT detection */
    if (nat_uac_test(63)) {
        setflag(5);
        fix_nated_contact();
        force_rport();
    }

    /* Record-Route */
    if (is_method("INVITE|SUBSCRIBE")) {
        record_route();
    }

    /* In-dialog requests */
    if (has_totag()) {
        if (loose_route()) {
            if (is_method("BYE")) {
                rtpengine_delete();
            }
            if (has_body("application/sdp")) {
                route(NATMANAGE);
            }
            route(RELAY);
            exit;
        }
        if (is_method("ACK") && t_check_trans()) exit;
        sl_send_reply(404, "Not Found");
        exit;
    }

    /* CANCEL */
    if (is_method("CANCEL")) {
        if (t_check_trans()) t_relay();
        exit;
    }
    t_check_trans();

    /* Authenticate */
    route(AUTH);

    /* REGISTER — save locally, don't forward to backends */
    if (is_method("REGISTER")) {
        if (nat_uac_test(63)) {
            fix_nated_register();
        }
        if (!save("location")) {
            sl_send_reply(500, "Registration Failed");
        }
        exit;
    }

    /* OPTIONS */
    if (is_method("OPTIONS") && ($rU == $null || $rU == "")) {
        sl_send_reply(200, "OK");
        exit;
    }

    /* INVITE — dispatch to backend Asterisk servers */
    if (is_method("INVITE")) {
        /* Track the dialog for call-load balancing */
        setflag(4);
        dlg_manage();

        /* NAT manage */
        route(NATMANAGE);

        /* Dispatch to backend set 1 */
        route(DISPATCH);
        exit;
    }

    /* Other requests — try location lookup first */
    if (lookup("location")) {
        route(RELAY);
        exit;
    }
    sl_send_reply(404, "Not Found");
    exit;
}

route[AUTH] {
    if (is_method("REGISTER")) {
        if (!www_authorize("YOUR_DOMAIN", "subscriber")) {
            www_challenge("YOUR_DOMAIN", 1);
            exit;
        }
        if ($au != $fU) {
            sl_send_reply(403, "Forbidden");
            exit;
        }
        return;
    }
    if (is_method("INVITE|MESSAGE")) {
        if (!proxy_authorize("YOUR_DOMAIN", "subscriber")) {
            proxy_challenge("YOUR_DOMAIN", 1);
            exit;
        }
        if ($au != $fU) {
            sl_send_reply(403, "Forbidden");
            exit;
        }
        consume_credentials();
    }
    return;
}

route[DISPATCH] {
    /* Round-robin (algorithm 0) across set 1 */
    if (!ds_select_dst(1, 0)) {
        xlog("L_ERR", "DISPATCH: All backends down for $rU\n");
        sl_send_reply(503, "Service Unavailable");
        exit;
    }
    xlog("L_INFO", "DISPATCH: $rU → $du\n");
    t_on_failure("DISPATCH_FAILURE");
    route(RELAY);
    exit;
}

route[RELAY] {
    t_on_reply("MANAGE_REPLY");
    if (!t_relay()) {
        sl_send_reply(500, "Server Error");
    }
    exit;
}

route[NATMANAGE] {
    if (is_request()) {
        if (has_body("application/sdp")) {
            rtpengine_manage("replace-origin replace-session-connection ICE=remove");
        }
    }
    if (is_reply()) {
        if (has_body("application/sdp")) {
            rtpengine_manage("replace-origin replace-session-connection ICE=remove");
        }
    }
    return;
}

onreply_route[MANAGE_REPLY] {
    if (status =~ "[12][0-9][0-9]") {
        route(NATMANAGE);
    }
}

failure_route[DISPATCH_FAILURE] {
    if (t_is_canceled()) exit;
    if (t_check_status("5[0-9][0-9]") || t_check_status("408")) {
        xlog("L_WARN", "DISPATCH: $du failed ($T_reply_code), failover\n");
        ds_mark_dst("ip");
        if (ds_next_dst()) {
            xlog("L_INFO", "DISPATCH: Failover → $du\n");
            t_on_failure("DISPATCH_FAILURE");
            route(RELAY);
            exit;
        }
        xlog("L_ERR", "DISPATCH: All backends exhausted\n");
        t_reply(503, "All Backends Unavailable");
        exit;
    }
}

10. Dialog & Accounting

Dialog Module — Track Active Calls

The dialog module tracks SIP call dialogs from the initial INVITE to the final BYE. It provides call counting, duration tracking, and per-user call limits.

loadmodule "dialog.so"

modparam("dialog", "db_mode", 1)          /* 1 = write to DB on changes */
modparam("dialog", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")
modparam("dialog", "dlg_flag", 4)         /* Flag to enable dialog tracking */
modparam("dialog", "timeout_avp", "$avp(dlg_timeout)")
modparam("dialog", "default_timeout", 43200)  /* 12-hour max call duration */

/* Dialog profiles — for per-user call limits */
modparam("dialog", "profiles_with_value", "caller;callee")
modparam("dialog", "profiles_no_value", "active_calls")

Enable dialog tracking in the routing logic:

request_route {
    /* ... (sanity, NAT, in-dialog handling) ... */

    if (is_method("INVITE") && !has_totag()) {
        /* New call — enable dialog tracking */
        setflag(4);
        dlg_manage();

        /* Set dialog timeout (optional) */
        $avp(dlg_timeout) = 7200;  /* 2-hour limit for this call */

        /* Set dialog profile for the caller */
        set_dlg_profile("caller", "$fU");
        set_dlg_profile("callee", "$rU");
        set_dlg_profile("active_calls");

        /* ... route the call ... */
    }
}

Per-User Call Limits

Prevent a single user from making too many simultaneous calls:

route[CHECK_CALL_LIMITS] {
    /* Max 5 simultaneous calls per caller */
    if (get_profile_size("caller", "$fU", "$avp(caller_calls)")) {
        if ($avp(caller_calls) >= 5) {
            xlog("L_WARN", "Call limit reached for $fU ($avp(caller_calls) active)\n");
            sl_send_reply(486, "Busy — Call Limit Reached");
            exit;
        }
    }

    /* Max 2 simultaneous calls per callee */
    if (get_profile_size("callee", "$rU", "$avp(callee_calls)")) {
        if ($avp(callee_calls) >= 2) {
            xlog("L_WARN", "Callee $rU busy ($avp(callee_calls) active)\n");
            sl_send_reply(486, "Busy Here");
            exit;
        }
    }
    return;
}

Dialog Statistics

# View active calls
kamcmd dlg.list

# Count active dialogs
kamcmd dlg.stats_active

# Get dialog by Call-ID
kamcmd dlg.dlg_list_ctx

# View profile sizes (active calls per user)
kamcmd dlg.profile_list caller
kamcmd dlg.profile_list active_calls

# Terminate a dialog
kamcmd dlg.end_dlg <h_entry> <h_id>

Accounting Module — CDR Generation

The acc module generates Call Detail Records (CDRs) and logs them to the database, syslog, or both.

loadmodule "acc.so"
loadmodule "acc_db.so"  /* Database CDR backend (included in kamailio-mysql-modules) */

/* Accounting to database */
modparam("acc", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")
modparam("acc", "db_flag", 1)             /* Flag to trigger DB accounting */
modparam("acc", "db_missed_flag", 2)      /* Flag for missed call logging */
modparam("acc", "failed_transaction_flag", 3) /* Flag for failed transactions */

/* What to log */
modparam("acc", "log_level", 1)
modparam("acc", "log_flag", 1)

/* CDR generation — log duration, start/end time */
modparam("acc", "cdr_enable", 1)
modparam("acc", "cdr_start_on_confirmed", 1)  /* Start CDR timer on 200 OK */
modparam("acc", "cdr_log_enable", 1)

/* Extra fields to log */
modparam("acc", "db_extra",
    "src_user=$fU;src_domain=$fd;src_ip=$si;"
    "dst_user=$rU;dst_domain=$rd;"
    "callid=$ci;ua=$ua")

/* CDR extra fields */
modparam("acc", "cdr_extra",
    "src_user=$fU;dst_user=$rU;src_ip=$si;callid=$ci")

Enable accounting in routing:

request_route {
    /* ... */

    if (is_method("INVITE") && !has_totag()) {
        setflag(1);  /* Enable DB accounting */
        setflag(2);  /* Log missed calls */
        setflag(3);  /* Log failed transactions */
        setflag(4);  /* Enable dialog tracking (needed for CDR duration) */
        dlg_manage();

        /* ... route the call ... */
    }
}

CDR Database Schema

The acc table stores accounting records:

-- View CDRs
SELECT id, method, from_tag, to_tag, callid, sip_code, sip_reason,
       src_user, dst_user, src_ip, time
FROM acc
ORDER BY time DESC
LIMIT 20;

-- CDR table (if cdr_enable=1)
SELECT id, start_time, end_time, duration,
       src_user, dst_user, src_ip, callid,
       sip_code, sip_reason
FROM cdrs
ORDER BY start_time DESC
LIMIT 20;

Custom CDR Fields

Add custom data to your CDRs using AVPs:

/* In modparam section */
modparam("acc", "db_extra",
    "src_user=$fU;src_domain=$fd;src_ip=$si;"
    "dst_user=$rU;dst_domain=$rd;"
    "callid=$ci;ua=$ua;"
    "trunk=$avp(trunk_name);"
    "campaign=$avp(campaign)")

/* In routing logic — set custom fields before acc triggers */
if (is_method("INVITE") && !has_totag()) {
    $avp(trunk_name) = "protech";
    $avp(campaign) = "uk_sales";
    setflag(1);
    /* ... */
}

You need to add corresponding columns to the acc table:

ALTER TABLE acc ADD COLUMN trunk VARCHAR(64) DEFAULT '';
ALTER TABLE acc ADD COLUMN campaign VARCHAR(64) DEFAULT '';

11. WebRTC Gateway

Overview

WebRTC allows browser-based voice/video calls using JavaScript. Browsers use SIP over WebSocket (WSS) for signaling and DTLS-SRTP for media. Kamailio acts as a gateway between WebRTC and traditional SIP endpoints.

┌─────────┐    WSS/SRTP    ┌──────────┐   SIP/RTP   ┌──────────┐
│ Browser │ ◄────────────► │ Kamailio │ ◄──────────► │ Asterisk │
│ SIP.js  │                │+RTPEngine│              │  (PBX)   │
└─────────┘                └──────────┘              └──────────┘

Browser → Kamailio: SIP over WSS (port 8443), DTLS-SRTP media
Kamailio → Asterisk: SIP over UDP (port 5060), plain RTP media
RTPEngine: Converts DTLS-SRTP ↔ plain RTP

WebSocket Module Setup

/* Module loading */
loadmodule "websocket.so"
loadmodule "xhttp.so"          /* HTTP handling for WebSocket upgrade */
loadmodule "nathelper.so"
loadmodule "rtpengine.so"
loadmodule "tls.so"

/* Listen on WSS (WebSocket Secure) */
listen=tls:YOUR_SERVER_IP:8443

/* WebSocket parameters */
modparam("websocket", "keepalive_mechanism", 1)     /* 1 = PING/PONG */
modparam("websocket", "keepalive_timeout", 30)      /* Seconds */
modparam("websocket", "keepalive_processes", 1)

/* TLS for WSS */
modparam("tls", "private_key", "/etc/kamailio/certs/privkey.pem")
modparam("tls", "certificate", "/etc/kamailio/certs/fullchain.pem")
modparam("tls", "tls_method", "TLSv1.2+")

HTTP/WebSocket Upgrade Handling

WebSocket connections start as HTTP requests with an Upgrade: websocket header:

/* Handle HTTP requests (WebSocket upgrade) */
event_route[xhttp:request] {
    set_reply_close();
    set_reply_no_connect();

    if ($hdr(Upgrade) =~ "websocket" &&
        $hdr(Connection) =~ "Upgrade" &&
        $rm == "GET") {

        /* Validate Origin header (optional but recommended) */
        # if ($hdr(Origin) != "https://YOUR_DOMAIN") {
        #     xhttp_reply(403, "Forbidden", "text/plain", "Bad Origin");
        #     exit;
        # }

        /* Accept WebSocket upgrade */
        if (ws_handle_handshake()) {
            exit;
        }
    }

    /* Non-WebSocket HTTP request — reject */
    xhttp_reply(404, "Not Found", "text/plain", "WebSocket Only");
    exit;
}

WebRTC Routing Logic

WebRTC requires special handling for media negotiation. The key is using RTPEngine to bridge between DTLS-SRTP (WebRTC) and plain RTP (traditional SIP):

route[NATMANAGE_WEBRTC] {
    if (is_request()) {
        if (has_body("application/sdp")) {
            if ($proto == "ws" || $proto == "wss") {
                /* WebRTC → SIP: convert DTLS-SRTP to plain RTP */
                rtpengine_manage(
                    "replace-origin replace-session-connection "
                    "rtcp-mux-demux ICE=remove "
                    "RTP/AVP SDES-off");
            } else if (ds_is_from_list(1)) {
                /* Reply from backend (SIP) → WebRTC: convert RTP to DTLS-SRTP */
                rtpengine_manage(
                    "replace-origin replace-session-connection "
                    "rtcp-mux-offer ICE=force "
                    "RTP/SAVPF SDES-off "
                    "DTLS=passive");
            } else {
                /* SIP to SIP — standard relay */
                rtpengine_manage(
                    "replace-origin replace-session-connection ICE=remove");
            }
        }
    }

    if (is_reply()) {
        if (has_body("application/sdp")) {
            if ($proto == "ws" || $proto == "wss") {
                /* Reply going to WebRTC client */
                rtpengine_manage(
                    "replace-origin replace-session-connection "
                    "rtcp-mux-offer ICE=force "
                    "RTP/SAVPF SDES-off "
                    "DTLS=passive");
            } else {
                /* Reply going to SIP endpoint */
                rtpengine_manage(
                    "replace-origin replace-session-connection "
                    "rtcp-mux-demux ICE=remove "
                    "RTP/AVP SDES-off");
            }
        }
    }
    return;
}

Nginx Reverse Proxy for WSS

In production, you typically put Nginx in front of Kamailio for WSS, handling TLS termination:

# /etc/nginx/sites-available/kamailio-wss
upstream kamailio_wss {
    server 127.0.0.1:8080;  # Kamailio WS (non-TLS) listener
}

server {
    listen 443 ssl;
    server_name YOUR_DOMAIN;

    ssl_certificate /etc/letsencrypt/live/YOUR_DOMAIN/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/YOUR_DOMAIN/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;

    location /ws {
        proxy_pass http://kamailio_wss;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

When using Nginx for TLS termination, Kamailio listens on plain WS:

/* Plain WebSocket behind Nginx */
listen=tcp:127.0.0.1:8080

JsSIP/SIP.js Browser Client Example

Here is a minimal browser client using JsSIP:

<!DOCTYPE html>
<html>
<head>
    <title>WebRTC Phone</title>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/jssip/3.10.0/jssip.min.js"></script>
</head>
<body>
    <h2>WebRTC SIP Phone</h2>
    <div>
        <input type="text" id="target" placeholder="Extension (e.g., 1002)" />
        <button onclick="makeCall()">Call</button>
        <button onclick="hangUp()">Hang Up</button>
    </div>
    <div id="status">Disconnected</div>
    <audio id="remoteAudio" autoplay></audio>

<script>
// Configuration
const socket = new JsSIP.WebSocketInterface('wss://YOUR_DOMAIN:8443');
const configuration = {
    sockets: [socket],
    uri: 'sip:1001@YOUR_DOMAIN',
    password: 'MySecurePass123',
    display_name: 'Web User 1001',
    register: true,
    session_timers: false
};

// Create User Agent
const ua = new JsSIP.UA(configuration);
let currentSession = null;

// Event handlers
ua.on('connected', () => {
    document.getElementById('status').textContent = 'Connected';
});

ua.on('registered', () => {
    document.getElementById('status').textContent = 'Registered';
});

ua.on('registrationFailed', (e) => {
    document.getElementById('status').textContent = 'Registration failed: ' + e.cause;
});

ua.on('newRTCSession', (data) => {
    const session = data.session;
    currentSession = session;

    if (session.direction === 'incoming') {
        document.getElementById('status').textContent = 'Incoming call from ' + session.remote_identity.uri;
        // Auto-answer (or show accept/reject buttons)
        session.answer({
            mediaConstraints: { audio: true, video: false }
        });
    }

    session.on('confirmed', () => {
        document.getElementById('status').textContent = 'Call active';
    });

    session.on('ended', () => {
        document.getElementById('status').textContent = 'Call ended';
        currentSession = null;
    });

    session.on('failed', (e) => {
        document.getElementById('status').textContent = 'Call failed: ' + e.cause;
        currentSession = null;
    });

    session.on('peerconnection', (e) => {
        e.peerconnection.ontrack = (event) => {
            document.getElementById('remoteAudio').srcObject = event.streams[0];
        };
    });
});

// Start the User Agent
ua.start();

// Make a call
function makeCall() {
    const target = document.getElementById('target').value;
    if (!target) return;

    const options = {
        mediaConstraints: { audio: true, video: false },
        pcConfig: {
            iceServers: [
                { urls: 'stun:stun.l.google.com:19302' }
            ]
        }
    };

    currentSession = ua.call('sip:' + target + '@YOUR_DOMAIN', options);
}

// Hang up
function hangUp() {
    if (currentSession) {
        currentSession.terminate();
    }
}
</script>
</body>
</html>

Complete WebRTC Gateway Configuration

#!KAMAILIO

listen=udp:YOUR_SERVER_IP:5060
listen=tcp:YOUR_SERVER_IP:5060
listen=tls:YOUR_SERVER_IP:5061
listen=tls:YOUR_SERVER_IP:8443

debug=2
log_stderror=no
log_facility=LOG_LOCAL0
children=8
tcp_children=8
auto_aliases=no
server_signature=no
force_rport=yes

/* Modules */
loadmodule "kex.so"
loadmodule "sl.so"
loadmodule "tm.so"
loadmodule "tmx.so"
loadmodule "rr.so"
loadmodule "maxfwd.so"
loadmodule "pv.so"
loadmodule "textops.so"
loadmodule "siputils.so"
loadmodule "xlog.so"
loadmodule "sanity.so"
loadmodule "xhttp.so"
loadmodule "websocket.so"
loadmodule "tls.so"
loadmodule "db_mysql.so"
loadmodule "usrloc.so"
loadmodule "registrar.so"
loadmodule "auth.so"
loadmodule "auth_db.so"
loadmodule "nathelper.so"
loadmodule "rtpengine.so"

/* TLS */
modparam("tls", "private_key", "/etc/kamailio/certs/privkey.pem")
modparam("tls", "certificate", "/etc/kamailio/certs/fullchain.pem")
modparam("tls", "tls_method", "TLSv1.2+")

/* WebSocket */
modparam("websocket", "keepalive_mechanism", 1)
modparam("websocket", "keepalive_timeout", 30)

/* Transaction */
modparam("tm", "fr_timer", 30000)
modparam("tm", "fr_inv_timer", 120000)
modparam("rr", "enable_full_lr", 1)
modparam("rr", "append_fromtag", 1)

/* User location */
modparam("usrloc", "db_mode", 2)
modparam("usrloc", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")
modparam("registrar", "max_expires", 3600)
modparam("registrar", "default_expires", 300)

/* Auth */
modparam("auth_db", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")
modparam("auth_db", "calculate_ha1", 1)
modparam("auth_db", "password_column", "password")
modparam("auth_db", "use_domain", 0)

/* NAT + RTPEngine */
modparam("nathelper", "natping_interval", 30)
modparam("nathelper", "ping_nated_only", 1)
modparam("nathelper", "sipping", 1)
modparam("nathelper", "received_avp", "$avp(RECEIVED)")
modparam("rtpengine", "rtpengine_sock", "udp:127.0.0.1:2223")

/* WebSocket upgrade handler */
event_route[xhttp:request] {
    set_reply_close();
    set_reply_no_connect();
    if ($hdr(Upgrade) =~ "websocket" && $hdr(Connection) =~ "Upgrade" && $rm == "GET") {
        if (ws_handle_handshake()) exit;
    }
    xhttp_reply(404, "Not Found", "text/plain", "WebSocket Only");
    exit;
}

/* Main routing */
request_route {
    if (!mf_process_maxfwd_header(10)) {
        sl_send_reply(483, "Too Many Hops");
        exit;
    }
    if (!sanity_check("17895", "7")) exit;

    /* NAT */
    if (nat_uac_test(63)) {
        setflag(5);
        fix_nated_contact();
        force_rport();
    }

    /* Tag WebSocket requests */
    if ($proto == "ws" || $proto == "wss") {
        setflag(6);  /* Flag 6 = WebRTC client */
    }

    if (is_method("INVITE|SUBSCRIBE")) {
        record_route();
    }

    /* In-dialog */
    if (has_totag()) {
        if (loose_route()) {
            if (is_method("BYE")) rtpengine_delete();
            if (has_body("application/sdp")) route(NATMANAGE_WS);
            route(RELAY);
            exit;
        }
        if (is_method("ACK") && t_check_trans()) exit;
        sl_send_reply(404, "Not Found");
        exit;
    }

    if (is_method("CANCEL")) {
        if (t_check_trans()) t_relay();
        exit;
    }
    t_check_trans();

    /* Auth */
    route(AUTH);

    /* REGISTER */
    if (is_method("REGISTER")) {
        if (nat_uac_test(63)) fix_nated_register();
        if (!save("location")) sl_send_reply(500, "Failed");
        exit;
    }

    /* OPTIONS */
    if (is_method("OPTIONS") && ($rU == $null || $rU == "")) {
        sl_send_reply(200, "OK");
        exit;
    }

    /* INVITE */
    if (!lookup("location")) {
        sl_send_reply(404, "User Not Found");
        exit;
    }
    route(NATMANAGE_WS);
    route(RELAY);
    exit;
}

route[AUTH] {
    if (is_method("REGISTER")) {
        if (!www_authorize("YOUR_DOMAIN", "subscriber")) {
            www_challenge("YOUR_DOMAIN", 1);
            exit;
        }
        return;
    }
    if (is_method("INVITE|MESSAGE")) {
        if (!proxy_authorize("YOUR_DOMAIN", "subscriber")) {
            proxy_challenge("YOUR_DOMAIN", 1);
            exit;
        }
        consume_credentials();
    }
    return;
}

route[RELAY] {
    t_on_reply("MANAGE_REPLY_WS");
    t_on_failure("MANAGE_FAILURE");
    if (!t_relay()) sl_send_reply(500, "Relay Error");
    exit;
}

route[NATMANAGE_WS] {
    if (is_request()) {
        if (has_body("application/sdp")) {
            if (isflagset(6)) {
                /* FROM WebRTC → TO SIP: DTLS-SRTP → plain RTP */
                rtpengine_manage(
                    "replace-origin replace-session-connection "
                    "rtcp-mux-demux ICE=remove RTP/AVP SDES-off");
            } else {
                /* FROM SIP → TO WebRTC or SIP */
                rtpengine_manage(
                    "replace-origin replace-session-connection ICE=remove");
            }
        }
    }
    if (is_reply()) {
        if (has_body("application/sdp")) {
            if (isflagset(6)) {
                /* Reply TO WebRTC client: plain RTP → DTLS-SRTP */
                rtpengine_manage(
                    "replace-origin replace-session-connection "
                    "rtcp-mux-offer ICE=force RTP/SAVPF SDES-off DTLS=passive");
            } else {
                rtpengine_manage(
                    "replace-origin replace-session-connection ICE=remove");
            }
        }
    }
    return;
}

onreply_route[MANAGE_REPLY_WS] {
    if (status =~ "[12][0-9][0-9]") {
        route(NATMANAGE_WS);
    }
}

failure_route[MANAGE_FAILURE] {
    if (t_is_canceled()) exit;
    xlog("L_WARN", "Call to $rU failed: $T_reply_code\n");
}

12. Integration with Media Servers

Kamailio + Asterisk: SBC / Load Balancer Pattern

The most common deployment: Kamailio sits in front of one or more Asterisk servers, handling registration, authentication, NAT, and load balancing. Asterisk handles media processing (IVR, voicemail, conferencing, recording).

Internet                     DMZ                        LAN
─────────────────────────────────────────────────────────────────
                        ┌──────────┐              ┌──────────┐
SIP Phones ────────────►│ Kamailio │──────────────►│ Asterisk │
SIP Trunks ────────────►│  (SBC)   │              │  (PBX)   │
WebRTC     ────────────►│          │──────────────►│ Asterisk │
                        │+RTPEngine│              │  (PBX)   │
                        └──────────┘              └──────────┘
  Port 5060/5061            │                     Port 5060
  Port 8443 (WSS)          │                     (Internal)
                       Port 10000-20000
                       (RTP via RTPEngine)

Asterisk configuration for Kamailio integration:

On each Asterisk backend, configure it to trust the Kamailio server:

; /etc/asterisk/pjsip.conf (Asterisk 16+)

[transport-udp]
type=transport
protocol=udp
bind=0.0.0.0

; Trust Kamailio as a SIP peer
[kamailio]
type=identify
endpoint=kamailio
match=YOUR_SERVER_IP

[kamailio]
type=endpoint
context=from-kamailio
disallow=all
allow=alaw
allow=ulaw
allow=opus
direct_media=no
trust_id_inbound=yes
trust_id_outbound=yes
send_pai=yes

[kamailio]
type=aor
max_contacts=1

; /etc/asterisk/extensions.conf
[from-kamailio]
; Calls from Kamailio arrive here
exten => _X.,1,NoOp(Call from Kamailio: ${CALLERID(num)} → ${EXTEN})
 same => n,Dial(PJSIP/${EXTEN},30)
 same => n,Hangup()

Kamailio + FreeSWITCH

The same pattern works with FreeSWITCH as the media server:

<!-- FreeSWITCH: /etc/freeswitch/sip_profiles/internal.xml -->
<!-- Add Kamailio as an ACL -->
<param name="apply-inbound-acl" value="kamailio"/>

<!-- /etc/freeswitch/autoload_configs/acl.conf.xml -->
<list name="kamailio" default="deny">
    <node type="allow" cidr="YOUR_SERVER_IP/32"/>
</list>

Topology Hiding (topoh Module)

The topoh module hides your internal network topology from external SIP peers. It replaces internal IP addresses in SIP headers with the Kamailio server's public address:

loadmodule "topoh.so"

modparam("topoh", "mask_ip", "YOUR_SERVER_IP")
modparam("topoh", "mask_callid", 1)        /* Mask Call-ID */
modparam("topoh", "sanity_checks", 1)      /* Validate before unmasking */

What topoh does:

BEFORE (external peer sees internal IPs):
  Via: SIP/2.0/UDP 10.0.0.10:5060   ← Internal Asterisk IP exposed!
  Contact: <sip:1001@10.0.0.10>     ← Internal IP exposed!
  Record-Route: <sip:10.0.0.10;lr>  ← Internal IP exposed!

AFTER (topoh masks everything):
  Via: SIP/2.0/UDP YOUR_SERVER_IP:5060
  Contact: <sip:1001@YOUR_SERVER_IP>
  Record-Route: <sip:YOUR_SERVER_IP;lr>

Header Manipulation for Integration

When routing between Kamailio and backend servers, you often need to add, remove, or modify SIP headers:

route[TO_ASTERISK] {
    /* Add custom headers for Asterisk to use */
    append_hf("X-Caller-IP: $si\r\n");
    append_hf("X-Original-URI: $ou\r\n");
    append_hf("X-Auth-User: $au\r\n");

    /* Set P-Asserted-Identity for the backend */
    remove_hf("P-Asserted-Identity");
    append_hf("P-Asserted-Identity: <sip:$fU@YOUR_DOMAIN>\r\n");

    /* Remove headers that shouldn't reach the backend */
    remove_hf("Proxy-Authorization");

    /* Route to backend */
    $du = "sip:10.0.0.10:5060";
    route(RELAY);
}

Domain-Based Routing (Multi-Tenant)

Route calls to different backends based on the domain in the request:

route[DOMAIN_ROUTE] {
    /* Route based on destination domain */
    if ($rd == "customer-a.com") {
        $du = "sip:10.0.0.10:5060";  /* Customer A's Asterisk */
        xlog("L_INFO", "Routing to Customer A backend\n");
    } else if ($rd == "customer-b.com") {
        $du = "sip:10.0.0.11:5060";  /* Customer B's Asterisk */
        xlog("L_INFO", "Routing to Customer B backend\n");
    } else if ($rd == "customer-c.com") {
        /* Customer C uses dispatcher set 3 */
        if (!ds_select_dst(3, 0)) {
            sl_send_reply(503, "Service Unavailable");
            exit;
        }
    } else {
        /* Unknown domain */
        sl_send_reply(404, "Domain Not Served");
        exit;
    }

    route(RELAY);
    exit;
}

For database-driven domain routing, use the domain module:

loadmodule "domain.so"
modparam("domain", "db_url",
    "mysql://kamailio:YOUR_KAMAILIO_DB_PASSWORD@localhost/kamailio")

-- Add served domains
INSERT INTO domain (domain) VALUES ('customer-a.com');
INSERT INTO domain (domain) VALUES ('customer-b.com');

/* Check if we serve this domain */
if (!is_domain_local("$rd")) {
    sl_send_reply(403, "Domain Not Served");
    exit;
}

Complete Integration Config Example

/* Integrated SBC config: Kamailio in front of 2 Asterisk servers */

route[ROUTE_TO_BACKEND] {
    /* Determine which backend based on called number pattern */

    if ($rU =~ "^1[0-9]{3}$") {
        /* 4-digit extensions starting with 1 → Asterisk 1 */
        $du = "sip:10.0.0.10:5060";
        xlog("L_INFO", "Routing ext $rU → Asterisk 1\n");
    } else if ($rU =~ "^2[0-9]{3}$") {
        /* 4-digit extensions starting with 2 → Asterisk 2 */
        $du = "sip:10.0.0.11:5060";
        xlog("L_INFO", "Routing ext $rU → Asterisk 2\n");
    } else if ($rU =~ "^[0-9]{10,}$") {
        /* External number (10+ digits) → dispatcher set for trunks */
        if (!ds_select_dst(2, 4)) {  /* Set 2, priority algorithm */
            sl_send_reply(503, "No Trunks Available");
            exit;
        }
        xlog("L_INFO", "Routing PSTN $rU → trunk $du\n");
    } else {
        sl_send_reply(404, "Number Not Routable");
        exit;
    }

    /* Add integration headers */
    append_hf("P-Asserted-Identity: <sip:$fU@YOUR_DOMAIN>\r\n");
    append_hf("X-Kamailio-Server: sbc01\r\n");

    /* Enable dialog tracking */
    setflag(4);
    dlg_manage();

    /* Manage media */
    route(NATMANAGE);

    /* Forward with failover */
    t_on_failure("BACKEND_FAILURE");
    route(RELAY);
    exit;
}

failure_route[BACKEND_FAILURE] {
    if (t_is_canceled()) exit;

    if (t_check_status("408|5[0-9][0-9]")) {
        xlog("L_WARN", "Backend $du failed ($T_reply_code)\n");

        /* Try alternate backend */
        if ($rU =~ "^1[0-9]{3}$") {
            /* Asterisk 1 failed — try Asterisk 2 */
            $du = "sip:10.0.0.11:5060";
        } else if ($rU =~ "^2[0-9]{3}$") {
            /* Asterisk 2 failed — try Asterisk 1 */
            $du = "sip:10.0.0.10:5060";
        } else {
            /* Trunk failover — use dispatcher */
            if (ds_next_dst()) {
                t_on_failure("BACKEND_FAILURE");
                route(RELAY);
                exit;
            }
            t_reply(503, "All Backends Down");
            exit;
        }

        t_on_failure("FINAL_FAILURE");
        route(RELAY);
        exit;
    }
}

failure_route[FINAL_FAILURE] {
    if (t_is_canceled()) exit;
    xlog("L_ERR", "All backends failed for $rU\n");
}

13. Monitoring & Management

kamcmd — Command-Line Management

kamcmd is the primary tool for interacting with a running Kamailio instance:

# Server information
kamcmd core.version
kamcmd core.uptime
kamcmd core.info

# Process management
kamcmd core.ps              # List processes
kamcmd core.psx             # Extended process list

# Statistics
kamcmd stats.get_statistics all          # All statistics
kamcmd stats.get_statistics core:        # Core statistics
kamcmd stats.get_statistics tmx:         # Transaction statistics
kamcmd stats.get_statistics dialog:      # Dialog (call) statistics
kamcmd stats.get_statistics usrloc:      # Registration statistics
kamcmd stats.get_statistics dispatcher:  # Dispatcher statistics

# User location (registrations)
kamcmd ul.dump                    # Dump all registrations
kamcmd ul.lookup location 1001   # Look up specific user
kamcmd ul.rm location 1001       # Remove a registration
kamcmd ul.flush                   # Flush expired contacts

# Dispatcher
kamcmd dispatcher.list            # List all destinations with status
kamcmd dispatcher.reload          # Reload from database
kamcmd dispatcher.set_state ap 1 sip:10.0.0.10:5060  # Set Active
kamcmd dispatcher.set_state ip 1 sip:10.0.0.10:5060  # Set Inactive

# Dialog
kamcmd dlg.list                   # List active calls
kamcmd dlg.stats_active           # Active call count
kamcmd dlg.end_dlg <h_entry> <h_id>  # Terminate a call

# TLS
kamcmd tls.list                   # List TLS connections
kamcmd tls.info                   # TLS module info

# Memory
kamcmd pkg.stats                  # Per-process memory
kamcmd mod.stats                  # Per-module memory

# Configuration reload
kamcmd cfg.sets                   # List config variables

kamctl — User and Database Management

kamctl is the higher-level management tool for user/database operations:

# User management
kamctl add 1001 password123       # Add user
kamctl rm 1001                    # Remove user
kamctl passwd 1001 newpass        # Change password
kamctl showdb subscriber          # List all users

# Address/ACL management
kamctl address add 1 10.0.0.5 32 5060 "Asterisk Backend"
kamctl address show
kamctl address reload

# Dispatcher management
kamctl dispatcher add 1 sip:10.0.0.10:5060 0 0 "" "Backend 1"
kamctl dispatcher show
kamctl dispatcher reload

# Database operations
kamctl db show version            # Show table versions
kamctl db exec "SELECT * FROM location"  # Raw SQL query

# Online monitoring
kamctl monitor                    # Real-time stats display
kamctl stats                      # One-shot statistics

# Fifo commands
kamctl fifo which                 # List available FIFO commands

JSONRPC Interface for Remote Management

The jsonrpcs module exposes a JSON-RPC interface for programmatic management:

loadmodule "jsonrpcs.so"
modparam("jsonrpcs", "pretty_format", 1)
modparam("jsonrpcs", "transport", 1)

/* Optional: HTTP-based JSONRPC */
loadmodule "xhttp.so"
/* Add to event_route[xhttp:request] or use separate port */

Example JSONRPC calls:

# Using kamcmd (which uses JSONRPC internally)
kamcmd -s tcp:localhost:2049 core.version

# Using curl (if HTTP transport is enabled)
curl -s -X POST http://localhost:5060/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"core.version","id":1}'

# Get active calls count
curl -s -X POST http://localhost:5060/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"stats.get_statistics","params":[["dialog:"]],"id":1}'

Statistics Overview

Key statistics to monitor:

Category	Statistic	Description
Core	`core:rcv_requests`	Total received SIP requests
Core	`core:rcv_replies`	Total received SIP replies
Core	`core:fwd_requests`	Total forwarded requests
Core	`core:fwd_replies`	Total forwarded replies
Core	`core:drop_requests`	Dropped requests
Core	`core:err_requests`	Error requests
Transaction	`tmx:UAS_transactions`	Server transactions
Transaction	`tmx:UAC_transactions`	Client transactions
Transaction	`tmx:inuse_transactions`	Currently active transactions
Transaction	`tmx:2xx_transactions`	Successful transactions
Transaction	`tmx:4xx_transactions`	Client error transactions
Transaction	`tmx:5xx_transactions`	Server error transactions
Dialog	`dialog:active_dialogs`	Currently active calls
Dialog	`dialog:processed_dialogs`	Total processed dialogs
Dialog	`dialog:expired_dialogs`	Timed-out dialogs
Dialog	`dialog:failed_dialogs`	Failed dialogs
Registrar	`usrloc:registered_users`	Currently registered users
Registrar	`usrloc:location-contacts`	Total contacts in location table
Registrar	`usrloc:location-expires`	Expired contacts
Dispatcher	Check via `kamcmd dispatcher.list`	Per-destination status

Prometheus Exporter

Use kamailio_exporter to expose Kamailio statistics as Prometheus metrics:

# Install the Kamailio Prometheus exporter
# Option 1: Go binary
wget https://github.com/florentchauveau/kamailio_exporter/releases/latest/download/kamailio_exporter_linux_amd64
chmod +x kamailio_exporter_linux_amd64
mv kamailio_exporter_linux_amd64 /usr/local/bin/kamailio_exporter

# Create systemd service
cat > /etc/systemd/system/kamailio-exporter.service << 'EOF'
[Unit]
Description=Kamailio Prometheus Exporter
After=kamailio.service

[Service]
ExecStart=/usr/local/bin/kamailio_exporter \
    --kamailio.address=unix:/var/run/kamailio/kamailio_ctl \
    --web.listen-address=:9494
Restart=always
User=kamailio

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable --now kamailio-exporter

Prometheus scrape config:

# /etc/prometheus/prometheus.yml
scrape_configs:
  - job_name: 'kamailio'
    static_configs:
      - targets: ['localhost:9494']
    scrape_interval: 15s

Grafana Dashboard

Key panels for a Kamailio Grafana dashboard:

Panel	PromQL Query	Type
Active Calls	`kamailio_dialog_active_dialogs`	Gauge
Calls/sec	`rate(kamailio_dialog_processed_dialogs[5m])`	Graph
SIP Requests/sec	`rate(kamailio_core_rcv_requests[5m])`	Graph
Failed Calls	`rate(kamailio_tmx_5xx_transactions[5m])`	Graph
Registered Users	`kamailio_usrloc_registered_users`	Gauge
Memory Usage	`kamailio_core_shm_used_size`	Gauge
Error Rate	`rate(kamailio_core_err_requests[5m])`	Graph
Dispatcher Status	`kamailio_dispatcher_target_up`	Status Map

Log Analysis Patterns

Configure rsyslog to write Kamailio logs to a dedicated file:

# /etc/rsyslog.d/kamailio.conf
local0.*    /var/log/kamailio/kamailio.log

Key log patterns to monitor:

# Authentication failures (potential brute force)
grep "AUTH_FAILED" /var/log/kamailio/kamailio.log | tail -20

# Pike blocks (flood detection)
grep "PIKE" /var/log/kamailio/kamailio.log | tail -20

# Dispatcher failures (backend down)
grep "DISPATCH.*failed" /var/log/kamailio/kamailio.log | tail -20

# Registration events
grep "REGISTER" /var/log/kamailio/kamailio.log | tail -20

# Call failures
grep "failed.*T_reply_code" /var/log/kamailio/kamailio.log | tail -20

Logrotate configuration:

cat > /etc/logrotate.d/kamailio << 'EOF'
/var/log/kamailio/kamailio.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    postrotate
        /usr/bin/systemctl reload rsyslog > /dev/null 2>&1 || true
    endscript
}
EOF

sipcapture / Homer Integration

Homer is a SIP capture and analysis tool. Kamailio can send SIP message copies to Homer for analysis:

loadmodule "siptrace.so"

modparam("siptrace", "duplicate_uri", "sip:HOMER_IP:9060")
modparam("siptrace", "hep_mode_on", 1)
modparam("siptrace", "hep_version", 3)
modparam("siptrace", "hep_capture_id", 100)
modparam("siptrace", "trace_on", 1)
modparam("siptrace", "trace_flag", 22)

/* In request_route — enable tracing for all traffic */
request_route {
    setflag(22);  /* Enable SIP trace */
    sip_trace();
    /* ... */
}

14. Troubleshooting

SIP Tracing in Kamailio

Debug Logging Levels

Level	Name	Use Case
0	L_ALERT	Critical errors only
1	L_BUG	Software bugs
2	L_CRIT / L_ERR	Errors (production default)
3	L_WARN	Warnings + errors
4	L_NOTICE	Important operational info
5	L_INFO	General operational info
6	L_DBG	Full debug output (development only)

Change debug level at runtime (no restart needed):

# Get current debug level
kamcmd cfg.get core debug

# Set debug to maximum (temporary — resets on restart)
kamcmd cfg.seti core debug 6

# Set back to production level
kamcmd cfg.seti core debug 2

Using xlog for Targeted Tracing

/* Add strategic xlog statements */
request_route {
    xlog("L_INFO", ">>> $rm from $fU@$si:$sp to $rU R-URI=$ru\n");

    /* Trace specific call by Call-ID */
    if ($ci =~ "abc123") {
        xlog("L_DBG", "[TRACE] Headers:\n$mb\n");
    }
}

route[RELAY] {
    xlog("L_INFO", "RELAY: $rm → $du (branch=$T_branch_idx)\n");
}

onreply_route[MANAGE_REPLY] {
    xlog("L_INFO", "<<< Reply $T_reply_code $T_reply_reason for $rm ($ci)\n");
}

failure_route[MANAGE_FAILURE] {
    xlog("L_WARN", "!!! FAILURE: $T_reply_code for $rU from $du ($ci)\n");
}

Config Trace Mode

Enable route execution tracing (very verbose — development only):

/* In kamailio.cfg — global parameter */
cfgtrace=1  /* Trace all route block execution */

Or per-message in routing logic:

if ($ci =~ "debug-this-call") {
    setflag(25);
    /* Use cfgtrace for this specific request */
}

Common Routing Errors

481 Call Leg Does Not Exist

Cause: Kamailio receives an in-dialog request (BYE, re-INVITE) but cannot find the matching transaction or dialog.

Common reasons:

Kamailio restarted during an active call
Record-Route was not added to the initial INVITE
Dialog module lost state

Fix:

/* Ensure Record-Route is always added */
if (is_method("INVITE|SUBSCRIBE")) {
    record_route();
}

/* Handle stale in-dialog requests gracefully */
if (has_totag()) {
    if (!loose_route()) {
        if (is_method("ACK")) {
            if (t_check_trans()) exit;
            exit;  /* Silently absorb orphan ACKs */
        }
        if (is_method("BYE")) {
            /* Reply 481 but don't log as error — normal after restart */
            sl_send_reply(481, "Call Leg Does Not Exist");
            exit;
        }
    }
}

407 Authentication Loops

Cause: Kamailio keeps challenging with 407, and the client keeps retrying with credentials, but they never match.

Diagnosis:

# Check if the user exists in subscriber table
kamctl showdb subscriber | grep 1001

# Check realm mismatch
# The realm in www_authorize/proxy_authorize MUST match
# what the SIP phone uses

Fix:

/* Ensure realm matches your domain/IP */
if (!proxy_authorize("YOUR_DOMAIN", "subscriber")) {
    /* Try with IP as realm if domain fails */
    if (!proxy_authorize("YOUR_SERVER_IP", "subscriber")) {
        proxy_challenge("YOUR_DOMAIN", 1);
        exit;
    }
}

Also verify calculate_ha1 is set correctly:

calculate_ha1=1 — passwords stored in plaintext, Kamailio hashes them
calculate_ha1=0 — passwords stored as HA1 hashes already

483 Too Many Hops

Cause: SIP message is looping between servers, incrementing Max-Forwards until it reaches 0.

Diagnosis:

# Watch for looping messages
grep "483" /var/log/kamailio/kamailio.log

# Check Via headers in the SIP trace — if you see
# the same server IP appearing multiple times, it's a loop

Fix:

/* Ensure mf_process_maxfwd_header is at the TOP of request_route */
request_route {
    if (!mf_process_maxfwd_header(10)) {
        sl_send_reply(483, "Too Many Hops");
        exit;
    }

    /* Check for loop: same message arriving twice */
    if (is_method("INVITE") && !has_totag()) {
        if (t_lookup_request()) {
            /* Already processing this transaction — retransmission */
            exit;
        }
    }
}

Registration Failures

Symptom: SIP phones cannot register. Check:

# 1. Is Kamailio listening?
ss -ulnp | grep 5060

# 2. Check for registration attempts in logs
grep "REGISTER" /var/log/kamailio/kamailio.log | tail -20

# 3. Verify user exists
kamctl showdb subscriber

# 4. Check current registrations
kamcmd ul.dump

# 5. Test registration manually
sipsak -U -C sip:test@YOUR_SERVER_IP \
    -s sip:1001@YOUR_SERVER_IP \
    -u 1001 -a password123

Common issues:

Issue	Solution
User not in subscriber table	`kamctl add 1001 password`
Wrong realm	Match realm in kamailio.cfg to what phone sends
TLS required but phone uses UDP	Add `listen=udp:...`
Firewall blocking	Open port 5060 UDP+TCP
Registration expires too fast	Increase `max_expires`

NAT Problems (One-Way Audio)

Symptom: Call connects but one or both sides cannot hear audio.

Diagnosis checklist:

# 1. Is RTPEngine running?
systemctl status rtpengine
ss -ulnp | grep rtpengine

# 2. Check RTPEngine statistics
echo "list totals" | nc -u 127.0.0.1 2223

# 3. Are RTP ports open in the firewall?
# Port range 10000-20000 UDP must be open
ss -ulnp | grep -E "1[0-9]{4}|20000"

# 4. Check if NAT is being detected
grep "NAT detected" /var/log/kamailio/kamailio.log | tail -10

# 5. Capture SIP to check SDP
ngrep -W byline -d any port 5060 | grep -A20 "INVITE"
# Look at c= and m= lines — do they contain private IPs?

Fix checklist:

Verify nathelper module is loaded and nat_uac_test() is called
Verify rtpengine module is loaded and rtpengine_manage() is called for both requests AND replies
Verify Record-Route is added so in-dialog requests go through Kamailio
Verify force_rport is applied for NATed clients
Verify fix_nated_contact() is called to rewrite Contact headers
Verify RTPEngine firewall ports are open (10000-20000 UDP)

Dispatcher Failover Not Working

Symptom: Calls fail when a backend goes down instead of failing over.

Diagnosis:

# Check dispatcher status
kamcmd dispatcher.list
# Are backends marked as Active (AP) or Inactive (IP)?

# Check if health checking is working
grep "OPTIONS" /var/log/kamailio/kamailio.log | tail -10

Common issues:

Issue	Solution
`flags` not set to 2	`modparam("dispatcher", "flags", 2)` enables failover
No `failure_route`	Must define `failure_route` with `ds_mark_dst` + `ds_next_dst`
Backend rejects OPTIONS	Set `ds_ping_reply_codes` to accept 4xx replies
Probing not enabled	`modparam("dispatcher", "ds_probing_mode", 1)`
`t_on_failure` not set	Must call `t_on_failure("DISPATCH_FAILURE")` before `t_relay()`

Performance Tuning

Parameter	Default	Production Recommendation	Notes
`children`	4	8–16 per interface	SIP worker processes
`tcp_children`	4	8–16	TCP/TLS worker processes
`tcp_max_connections`	2048	4096–16384	For large deployments
`SHM_MEMORY`	64 MB	128–512 MB	Shared memory pool
`PKG_MEMORY`	8 MB	16–32 MB	Per-process memory
`usrloc db_mode`	0	2 (write-back)	Balance speed vs persistence
`tm fr_timer`	30000	5000–10000	Reduce for faster failover
`tm fr_inv_timer`	120000	30000–60000	INVITE timeout
`maxfwd`	10	10	Rarely needs changing
`dns_cache`	on	on	Cache DNS lookups
`tcp_connection_lifetime`	600	120–300	Close idle TCP sooner

OS-level tuning:

# /etc/sysctl.conf — network tuning for SIP proxy
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
net.core.rmem_default = 1048576
net.core.wmem_default = 1048576
net.core.netdev_max_backlog = 5000
net.ipv4.udp_mem = 8388608 12582912 16777216
net.ipv4.ip_local_port_range = 10000 65535
net.core.somaxconn = 4096
fs.file-max = 1000000

# Apply
sysctl -p

# Increase open file limit for Kamailio
cat >> /etc/security/limits.d/kamailio.conf << 'EOF'
kamailio soft nofile 65536
kamailio hard nofile 65536
EOF

Essential kamcmd Commands Reference

Command	Purpose
`kamcmd core.version`	Show Kamailio version
`kamcmd core.uptime`	Show uptime
`kamcmd core.ps`	List all processes
`kamcmd cfg.seti core debug 6`	Set debug level (runtime)
`kamcmd cfg.get core debug`	Get current debug level
`kamcmd stats.get_statistics all`	All statistics
`kamcmd stats.reset_statistics all`	Reset all counters
`kamcmd ul.dump`	Dump all registrations
`kamcmd ul.lookup location <user>`	Find a registered user
`kamcmd ul.rm location <user>`	Remove a registration
`kamcmd ul.flush`	Remove expired contacts
`kamcmd dlg.list`	List active call dialogs
`kamcmd dlg.stats_active`	Count active dialogs
`kamcmd dlg.end_dlg <h> <id>`	Terminate a dialog
`kamcmd dispatcher.list`	List dispatcher destinations
`kamcmd dispatcher.reload`	Reload dispatcher from DB
`kamcmd dispatcher.set_state <f> <s> <d>`	Set destination state
`kamcmd tls.list`	List TLS connections
`kamcmd pkg.stats`	Per-process memory usage
`kamcmd mod.stats`	Per-module memory usage
`kamcmd tm.list`	List active transactions
`kamcmd htable.dump ipban`	Dump blacklist table
`kamcmd htable.delete ipban <key>`	Remove from blacklist
`kamcmd htable.reload ipban`	Reload hash table
`kamcmd cfg.sets`	List all config variables

Quick Diagnostic Script

Save this as /usr/local/bin/kamailio-diag.sh for quick health checks:

#!/bin/bash
# Kamailio Quick Diagnostics
echo "=== Kamailio Diagnostics ==="
echo ""

echo "--- Version & Uptime ---"
kamcmd core.version 2>/dev/null || echo "Kamailio not running!"
kamcmd core.uptime 2>/dev/null

echo ""
echo "--- Listening Sockets ---"
ss -ulnp 2>/dev/null | grep kamailio
ss -tlnp 2>/dev/null | grep kamailio

echo ""
echo "--- Active Registrations ---"
REGS=$(kamcmd ul.dump 2>/dev/null | grep -c "AOR::" || echo "0")
echo "Registered users: $REGS"

echo ""
echo "--- Active Calls ---"
kamcmd stats.get_statistics dialog: 2>/dev/null | grep active || echo "No dialog module"

echo ""
echo "--- Dispatcher Status ---"
kamcmd dispatcher.list 2>/dev/null | grep -E "URI|FLAGS" || echo "No dispatcher"

echo ""
echo "--- Key Statistics ---"
kamcmd stats.get_statistics core:rcv_requests 2>/dev/null
kamcmd stats.get_statistics core:err_requests 2>/dev/null
kamcmd stats.get_statistics tmx:5xx_transactions 2>/dev/null

echo ""
echo "--- Memory Usage ---"
kamcmd stats.get_statistics shmem: 2>/dev/null | head -5

echo ""
echo "--- Recent Errors (last 10) ---"
grep -i "error\|critical\|alert" /var/log/kamailio/kamailio.log 2>/dev/null | tail -10

echo ""
echo "--- RTPEngine Status ---"
systemctl is-active rtpengine 2>/dev/null || echo "RTPEngine not installed"

echo ""
echo "=== Done ==="

chmod +x /usr/local/bin/kamailio-diag.sh

End of Tutorial 42. You now have the foundation to deploy Kamailio as a SIP proxy, SBC, load balancer, or WebRTC gateway in front of your Asterisk or FreeSWITCH infrastructure. Start with a basic proxy config (Section 4), add authentication (Section 6), layer on NAT handling (Section 7) and TLS (Section 8), then scale with dispatcher (Section 9) as your platform grows.

FreeSWITCH Fundamentals — Installation, Dialplan, SIP & IVR

Moisi Trungu — Thu, 07 May 2026 17:13:11 +0000

Tutorial 41: FreeSWITCH Fundamentals — Installation, Dialplan, SIP & IVR

A complete beginner-to-intermediate guide to FreeSWITCH — the high-performance open-source telephony platform. Learn installation, SIP endpoint configuration, XML dialplan, IVR menus, voicemail, recording, and integration patterns from scratch, with production-ready configurations throughout. Whether you are migrating from Asterisk or starting fresh, this tutorial gives you everything you need to deploy a fully functional FreeSWITCH system with SIP phones, trunks, call routing, conferencing, and external application control via the Event Socket Layer.


Difficulty	Beginner to Intermediate
Reading Time	~70 minutes
Prerequisites	Linux server (Debian 12 or Ubuntu 24.04), basic SIP/VoIP knowledge, command-line comfort
Technologies	FreeSWITCH, SIP, XML Dialplan, mod_sofia, ESL, Python, Conference, IVR, WebRTC
Tested On	Debian 12 (Bookworm), Ubuntu 24.04 LTS, FreeSWITCH 1.10.x

Introduction
Architecture Overview
Installation
SIP Configuration (mod_sofia)
XML Dialplan
IVR Menus
Voicemail
Call Recording
Conference Bridge
Event Socket Layer (ESL)
CDR & Logging
Security Hardening
Integration Patterns
Troubleshooting

1. Introduction

What Is FreeSWITCH?

FreeSWITCH is a scalable, open-source telephony platform designed for routing and interconnecting voice, video, and text communication protocols. Originally created by Anthony Minessale (a former Asterisk developer) in 2006, it was built from the ground up to address architectural limitations in existing PBX software.

Unlike traditional PBX systems that evolved from hardware roots, FreeSWITCH was designed as a software media server — a communications engine that applications talk to, rather than a standalone phone system with a configuration UI.

FreeSWITCH vs Asterisk

If you come from the Asterisk world, understanding the conceptual differences is critical before diving in.

Concept	Asterisk	FreeSWITCH
Architecture	Channel-based (each call leg is a channel)	Session-based (each call is a session with legs)
Configuration	`.conf` flat files (custom syntax)	XML files (structured, validatable)
Dialplan	`extensions.conf` (priority-based)	XML dialplan (context → extension → condition → action)
SIP Stack	Built-in `chan_sip` or `chan_pjsip`	`mod_sofia` (based on Sofia-SIP library from Nokia)
Concurrency	Thread-per-channel	Thread pool with session state machines
Scaling	Hundreds of concurrent calls	Thousands of concurrent calls on same hardware
Codec Support	Good (G.711, G.729, Opus)	Excellent (all Asterisk codecs + SILK, iSAC, VP8/VP9)
WebRTC	Requires external module or proxy	Native support via `mod_verto`
External Control	AMI (TCP) or ARI (HTTP/WebSocket)	ESL (Event Socket Layer — TCP, bidirectional)
Conference	`app_confbridge` (good)	`mod_conference` (carrier-grade, thousands of participants)
Learning Curve	Moderate	Steeper (XML verbosity, less community docs)
Community	Massive, decades of forums/blogs	Smaller but focused, Cluecon conference
License	GPL v2	MPL 1.1 (more business-friendly)

When to Choose FreeSWITCH

FreeSWITCH excels in these scenarios:

Carrier-grade switching: High call volume (1,000+ concurrent), SIP-to-SIP routing, least-cost routing
WebRTC gateway: Browser-based calling without external proxies
IVR platform: Complex multi-level IVR systems with database lookups and REST API integration
Conference server: Large-scale conferencing (hundreds of rooms, thousands of participants)
Media server: Behind Kamailio/OpenSIPS as a B2BUA or media processing engine
Telecom applications: When your app controls calls programmatically via ESL
Multi-tenant PBX: Built-in domain-based multi-tenancy

Choose Asterisk instead if you need: a quick office PBX, FreePBX/GUI administration, massive community support, or ViciDial/call-center-specific features.

2. Architecture Overview

Core Design Principles

FreeSWITCH is built on three fundamental design principles:

Event-driven: Everything in FreeSWITCH generates events. A call arriving, a DTMF press, a conference join — all are events that can be captured, filtered, and acted upon by internal modules or external applications.
Modular: The core is a lightweight engine. All functionality — SIP, dialplan, codecs, applications — comes from loadable modules. You enable only what you need.
Session-based: Each call creates a session object that persists for the call's lifetime. Sessions hold all state (variables, media streams, applications) and are managed by a thread pool, not one-thread-per-call.

Key Concepts

Before configuring anything, understand these five concepts:

Profiles — SIP listeners. Each profile binds to an IP:port and defines SIP behavior (codecs, NAT handling, authentication). The two default profiles are internal (port 5060, for registered phones) and external (port 5080, for trunks/carriers).

Contexts — Dialplan routing containers. When a call arrives on a profile, it enters the context assigned to that profile. The internal profile routes to the default context. The external profile routes to the public context.

Extensions — Named dialplan entries within a context. Each extension has conditions and actions. FreeSWITCH evaluates extensions top-to-bottom until one matches.

Conditions — Pattern-matching rules within an extension. Match on destination_number, caller_id_number, time_of_day, channel variables, or any header field.

Actions — What to do when conditions match. Actions include bridge (connect calls), playback (play audio), transfer (re-route), answer, hangup, and dozens more.

How a Call Flows

Incoming SIP INVITE
       │
       ▼
   mod_sofia (SIP stack)
       │
       ▼
   Profile (internal or external)
       │
       ▼
   Context (default or public)
       │
       ▼
   Extension matching (top-to-bottom)
       │
       ▼
   Condition evaluation (regex)
       │
       ▼
   Actions execute (answer, bridge, playback, etc.)

Directory Structure

/etc/freeswitch/                  # All configuration
├── freeswitch.xml                # Master config (includes everything)
├── vars.xml                      # Global variables (domain, passwords, IPs)
├── autoload_configs/             # Module configurations
│   ├── modules.conf.xml          # Which modules to load
│   ├── sofia.conf.xml            # SIP module config (includes profiles)
│   ├── conference.conf.xml       # Conference profiles
│   ├── voicemail.conf.xml        # Voicemail settings
│   ├── ivr.conf.xml              # IVR menu definitions
│   ├── cdr_csv.conf.xml          # CDR output config
│   └── event_socket.conf.xml     # ESL listener config
├── sip_profiles/                 # SIP profile definitions
│   ├── internal.xml              # Internal profile (phones, port 5060)
│   ├── external.xml              # External profile (trunks, port 5080)
│   └── external/                 # Gateway (trunk) definitions
│       └── my_provider.xml       # One file per trunk
├── dialplan/                     # Call routing rules
│   ├── default.xml               # Internal context (phone-to-phone)
│   ├── public.xml                # External context (inbound from trunks)
│   └── default/                  # Additional dialplan fragments
├── directory/                    # User/phone definitions
│   └── default/                  # Domain directory
│       ├── 1000.xml              # Extension 1000
│       ├── 1001.xml              # Extension 1001
│       └── ...
└── lang/                         # Language/sound file mappings

/var/lib/freeswitch/              # Runtime data
├── db/                           # SQLite databases (registrations, etc.)
├── recordings/                   # Call recordings
├── storage/                      # Voicemail, fax storage
└── sounds/                       # Audio/prompt files

/var/log/freeswitch/              # Logs
├── freeswitch.log                # Main log (rotated)
└── cdr-csv/                      # CDR files

Module System

FreeSWITCH loads modules at startup from autoload_configs/modules.conf.xml. Key modules:

Module	Purpose
`mod_sofia`	SIP protocol stack (registration, calls, trunks)
`mod_dptools`	Dialplan tools (bridge, playback, record, transfer, etc.)
`mod_dialplan_xml`	XML dialplan parser
`mod_event_socket`	ESL — external application control
`mod_conference`	Multi-party conferencing
`mod_voicemail`	Voicemail system
`mod_ivr`	IVR menu framework
`mod_commands`	CLI/API commands
`mod_console`	Console output
`mod_logfile`	File logging
`mod_cdr_csv`	CDR to CSV files
`mod_cdr_sqlite`	CDR to SQLite
`mod_cdr_pg`	CDR to PostgreSQL
`mod_flite`	Text-to-speech (Festival Lite)
`mod_shout`	MP3 playback/recording
`mod_verto`	WebRTC signaling
`mod_xml_curl`	Dynamic config from HTTP
`mod_lua`	Lua scripting in dialplan
`mod_python3`	Python 3 scripting in dialplan

FreeSWITCH vs Asterisk Concept Mapping

If you are coming from Asterisk, this mapping helps translate your knowledge:

Asterisk	FreeSWITCH
`sip.conf` / `pjsip.conf`	`sip_profiles/internal.xml` + `directory/`
`extensions.conf` context	`dialplan/` context XML
`extensions.conf` priority lines	`<action>` elements in sequence
Trunk in `sip.conf`	Gateway in `sip_profiles/external/`
`AMI` (Asterisk Manager Interface)	`ESL` (Event Socket Layer)
`ARI` (REST API)	`mod_xml_curl` + ESL
`app_confbridge`	`mod_conference`
`chan_sip` / `chan_pjsip`	`mod_sofia`
`Dial()` application	`bridge` action
`Playback()`	`playback` action
`Background()` + `WaitExten()`	`play_and_get_digits` or `ivr` action
`voicemail.conf`	`voicemail.conf.xml`
`${EXTEN}`	`${destination_number}`
`${CALLERID(num)}`	`${caller_id_number}`

3. Installation

Option A: Package Install (Recommended)

FreeSWITCH packages are distributed through SignalWire. You need a free Personal Access Token (PAT).

Step 1: Get a SignalWire PAT

Go to https://id.signalwire.com/personal_access_tokens
Create a free account (no credit card needed)
Generate a Personal Access Token
Save the token — you will need it below

Step 2: Add the Repository

Debian 12 (Bookworm):

# Install prerequisites
apt-get update && apt-get install -y gnupg2 wget lsb-release

# Set your SignalWire PAT
TOKEN="YOUR_SIGNALWIRE_PAT_HERE"

# Add SignalWire GPG key
wget --http-user=signalwire --http-password=$TOKEN \
  -O /usr/share/keyrings/signalwire-freeswitch-repo.gpg \
  https://freeswitch.signalwire.com/repo/deb/debian-release/signalwire-freeswitch-repo.gpg

# Add repository
echo "machine freeswitch.signalwire.com login signalwire password $TOKEN" \
  > /etc/apt/auth.conf.d/freeswitch.conf
chmod 600 /etc/apt/auth.conf.d/freeswitch.conf

echo "deb [signed-by=/usr/share/keyrings/signalwire-freeswitch-repo.gpg] \
  https://freeswitch.signalwire.com/repo/deb/debian-release/ bookworm main" \
  > /etc/apt/sources.list.d/freeswitch.list

Ubuntu 24.04 (Noble):

# Install prerequisites
apt-get update && apt-get install -y gnupg2 wget lsb-release

# Set your SignalWire PAT
TOKEN="YOUR_SIGNALWIRE_PAT_HERE"

# Add SignalWire GPG key
wget --http-user=signalwire --http-password=$TOKEN \
  -O /usr/share/keyrings/signalwire-freeswitch-repo.gpg \
  https://freeswitch.signalwire.com/repo/deb/debian-release/signalwire-freeswitch-repo.gpg

# Add repository
echo "machine freeswitch.signalwire.com login signalwire password $TOKEN" \
  > /etc/apt/auth.conf.d/freeswitch.conf
chmod 600 /etc/apt/auth.conf.d/freeswitch.conf

echo "deb [signed-by=/usr/share/keyrings/signalwire-freeswitch-repo.gpg] \
  https://freeswitch.signalwire.com/repo/deb/debian-release/ noble main" \
  > /etc/apt/sources.list.d/freeswitch.list

Step 3: Install FreeSWITCH

apt-get update

# Full install (recommended for learning — includes all modules)
apt-get install -y freeswitch-meta-all

# OR minimal install (production — add modules as needed)
# apt-get install -y freeswitch-meta-vanilla

The freeswitch-meta-all package includes all modules, sounds, music-on-hold, codecs, and language packs. For production, start with freeswitch-meta-vanilla and add only the modules you need.

Step 4: Post-Install Configuration

# Enable and start FreeSWITCH
systemctl enable freeswitch
systemctl start freeswitch

# Verify it is running
systemctl status freeswitch

# Check ownership (FreeSWITCH runs as freeswitch user)
ls -la /etc/freeswitch/
ls -la /var/lib/freeswitch/
ls -la /var/log/freeswitch/

# Fix ownership if needed
chown -R freeswitch:freeswitch /etc/freeswitch
chown -R freeswitch:freeswitch /var/lib/freeswitch
chown -R freeswitch:freeswitch /var/log/freeswitch

Option B: Compile from Source

Building from source gives you the latest code and full control over modules.

# Install build dependencies
apt-get update && apt-get install -y \
  build-essential cmake automake autoconf libtool pkg-config \
  libssl-dev zlib1g-dev libdb-dev libexpat1-dev libcurl4-openssl-dev \
  libpcre3-dev libspeex-dev libspeexdsp-dev libsqlite3-dev \
  libedit-dev libldns-dev libpq-dev libtiff-dev libjpeg-dev \
  libavformat-dev libswscale-dev liblua5.3-dev \
  libopus-dev libsndfile1-dev uuid-dev \
  python3-dev erlang-dev yasm nasm \
  git wget unzip

# Clone the repository
cd /usr/local/src
git clone https://github.com/signalwire/freeswitch.git -b v1.10 freeswitch
cd freeswitch

# Install libks and signalwire-c dependencies
git clone https://github.com/signalwire/libks.git
cd libks && cmake . -DCMAKE_INSTALL_PREFIX=/usr && make install && cd ..

git clone https://github.com/signalwire/signalwire-c.git
cd signalwire-c && cmake . -DCMAKE_INSTALL_PREFIX=/usr && make install && cd ..

# Bootstrap and configure
cd /usr/local/src/freeswitch
./bootstrap.sh -j

# Edit modules.conf to enable/disable modules before building
# nano modules.conf

./configure --prefix=/usr/local/freeswitch

# Build and install
make -j$(nproc)
make install

# Install sounds and music on hold
make cd-sounds-install cd-moh-install

# Create system user
useradd -r -s /bin/false freeswitch
chown -R freeswitch:freeswitch /usr/local/freeswitch

If you compiled from source, config lives in /usr/local/freeswitch/conf/ instead of /etc/freeswitch/. Adjust paths accordingly.

Firewall Configuration

# SIP signaling (internal profile)
ufw allow 5060/tcp comment "FreeSWITCH SIP TCP internal"
ufw allow 5060/udp comment "FreeSWITCH SIP UDP internal"

# SIP signaling (external profile)
ufw allow 5080/tcp comment "FreeSWITCH SIP TCP external"
ufw allow 5080/udp comment "FreeSWITCH SIP UDP external"

# RTP media (voice/video)
ufw allow 16384:32768/udp comment "FreeSWITCH RTP media"

# ESL (Event Socket Layer) - restrict to trusted IPs only
ufw allow from 10.0.0.0/8 to any port 8021 proto tcp comment "FreeSWITCH ESL"

# WebRTC (if using mod_verto)
# ufw allow 8081/tcp comment "FreeSWITCH Verto WSS"
# ufw allow 8082/tcp comment "FreeSWITCH Verto WSS"

ufw enable

With iptables instead:

# SIP
iptables -A INPUT -p udp --dport 5060 -j ACCEPT
iptables -A INPUT -p tcp --dport 5060 -j ACCEPT
iptables -A INPUT -p udp --dport 5080 -j ACCEPT
iptables -A INPUT -p tcp --dport 5080 -j ACCEPT

# RTP
iptables -A INPUT -p udp --dport 16384:32768 -j ACCEPT

# ESL (restrict source)
iptables -A INPUT -p tcp -s 10.0.0.0/8 --dport 8021 -j ACCEPT
iptables -A INPUT -p tcp --dport 8021 -j DROP

Verify Installation

# Connect to FreeSWITCH CLI
fs_cli

# Inside fs_cli, check status
freeswitch@server> status

# Expected output:
# UP 0 years, 0 days, 0 hours, 5 minutes, 23 seconds, 456 milliseconds, 789 microseconds
# FreeSWITCH (Version 1.10.x ...) is ready
# 0 session(s) since startup
# 0 session(s) - peak 0, last 5min 0
# 0 session(s) per Sec out of max 30, peak 0, last 5min 0
# 1000 session(s) max
# min idle cpu 0.00/99.67

# Check SIP profiles
freeswitch@server> sofia status

# Expected output:
#                      Name          Type                               Data      State
# =================================================================================================
#                  internal       profile   sip:mod_sofia@YOUR_SERVER_IP:5060      RUNNING (0)
#                  external       profile   sip:mod_sofia@YOUR_SERVER_IP:5080      RUNNING (0)
# ... (other profiles)

# Check loaded modules
freeswitch@server> module_exists mod_sofia
# true

# Exit CLI
freeswitch@server> /exit

Change Default Passwords

This is critical. The default install ships with password 1234 for all extensions and ClueCon for ESL.

# Edit global variables
nano /etc/freeswitch/vars.xml

Find and change these lines:

<!-- CHANGE THIS — default password for all extensions -->
<X-PRE-PROCESS cmd="set" data="default_password=PUT_A_STRONG_PASSWORD_HERE"/>

<!-- Domain — set to your server IP or FQDN -->
<X-PRE-PROCESS cmd="set" data="domain=$${local_ip_v4}"/>

Change the ESL password:

nano /etc/freeswitch/autoload_configs/event_socket.conf.xml

<configuration name="event_socket.conf" description="Socket Client">
  <settings>
    <param name="nat-map" value="false"/>
    <param name="listen-ip" value="127.0.0.1"/>
    <param name="listen-port" value="8021"/>
    <!-- CHANGE THIS from ClueCon -->
    <param name="password" value="YOUR_SECURE_ESL_PASSWORD"/>
    <!--<param name="apply-inbound-acl" value="loopback.auto"/>-->
  </settings>
</configuration>

Reload the configuration:

# From fs_cli
fs_cli -x "reloadxml"

# Or restart the service
systemctl restart freeswitch

4. SIP Configuration (mod_sofia)

Understanding SIP Profiles

mod_sofia is the SIP engine in FreeSWITCH. It manages all SIP communication through profiles. Each profile is an independent SIP listener with its own port, settings, and behavior.

The default installation creates two profiles:

Profile	Port	Purpose	Dialplan Context
`internal`	5060	SIP phones, softphones, registered endpoints	`default`
`external`	5080	SIP trunks, carriers, outside world	`public`

Why two profiles? Security. Internal phones authenticate with username/password. External trunks authenticate by IP. Keeping them on separate ports with separate rules prevents unauthorized calls.

Internal Profile Configuration

The internal profile handles your SIP phones. Edit /etc/freeswitch/sip_profiles/internal.xml:

<profile name="internal">
  <settings>
    <!-- Network -->
    <param name="sip-ip" value="$${local_ip_v4}"/>
    <param name="sip-port" value="5060"/>
    <param name="rtp-ip" value="$${local_ip_v4}"/>

    <!-- NAT: Set this to your public IP if behind NAT -->
    <!-- <param name="ext-sip-ip" value="YOUR_PUBLIC_IP"/> -->
    <!-- <param name="ext-rtp-ip" value="YOUR_PUBLIC_IP"/> -->

    <!-- Dialplan context for calls arriving on this profile -->
    <param name="context" value="default"/>

    <!-- Codec preferences (in order) -->
    <param name="inbound-codec-string" value="OPUS,G722,PCMU,PCMA"/>
    <param name="outbound-codec-string" value="OPUS,G722,PCMU,PCMA"/>

    <!-- DTMF handling -->
    <param name="dtmf-type" value="rfc2833"/>

    <!-- Registration -->
    <param name="inbound-reg-force-matching-username" value="true"/>
    <param name="auth-calls" value="true"/>
    <param name="apply-nat-acl" value="nat.auto"/>

    <!-- Recording -->
    <param name="record-path" value="$${recordings_dir}"/>
    <param name="record-template" value="${caller_id_number}.${target_domain}.${strftime(%Y-%m-%d-%H-%M-%S)}.wav"/>

    <!-- Timers -->
    <param name="session-timeout" value="1800"/>
    <param name="rtp-timeout-sec" value="300"/>
    <param name="rtp-hold-timeout-sec" value="1800"/>

    <!-- Hold music -->
    <param name="hold-music" value="$${hold_music}"/>
  </settings>
</profile>

External Profile Configuration

The external profile handles SIP trunks and outside calls. Edit /etc/freeswitch/sip_profiles/external.xml:

<profile name="external">
  <settings>
    <param name="sip-ip" value="$${local_ip_v4}"/>
    <param name="sip-port" value="5080"/>
    <param name="rtp-ip" value="$${local_ip_v4}"/>

    <!-- NAT: uncomment and set if behind NAT -->
    <!-- <param name="ext-sip-ip" value="YOUR_PUBLIC_IP"/> -->
    <!-- <param name="ext-rtp-ip" value="YOUR_PUBLIC_IP"/> -->

    <!-- Inbound calls from trunks go to 'public' context -->
    <param name="context" value="public"/>

    <!-- Codecs -->
    <param name="inbound-codec-string" value="PCMU,PCMA,G722"/>
    <param name="outbound-codec-string" value="PCMU,PCMA,G722"/>

    <!-- Do NOT require authentication (trunks use IP-based auth) -->
    <param name="auth-calls" value="false"/>

    <!-- DTMF -->
    <param name="dtmf-type" value="rfc2833"/>

    <!-- Aggressively reclaim failed channels -->
    <param name="rtp-timeout-sec" value="300"/>
  </settings>

  <!-- Gateway definitions are in sip_profiles/external/ directory -->
  <gateways>
    <X-PRE-PROCESS cmd="include" data="external/*.xml"/>
  </gateways>
</profile>

User Directory (SIP Extensions)

Each SIP phone/extension is defined in the directory. Files go in /etc/freeswitch/directory/default/.

Here is a single extension definition. Create /etc/freeswitch/directory/default/1001.xml:

<include>
  <user id="1001">
    <params>
      <param name="password" value="Str0ng_P@ss_1001!"/>
      <param name="vm-password" value="1001"/>
    </params>
    <variables>
      <variable name="toll_allow" value="domestic,international,local"/>
      <variable name="accountcode" value="1001"/>
      <variable name="user_context" value="default"/>
      <variable name="effective_caller_id_name" value="John Smith"/>
      <variable name="effective_caller_id_number" value="1001"/>
      <variable name="outbound_caller_id_name" value="My Company"/>
      <variable name="outbound_caller_id_number" value="15551234567"/>
      <variable name="callgroup" value="sales"/>
    </variables>
  </user>
</include>

Complete 10-Extension Office Configuration

Here is a production-ready configuration for a small office with 10 extensions and one SIP trunk.

Create all 10 extension files — save this as a shell script:

#!/bin/bash
# create-extensions.sh
# Creates 10 SIP extensions (1001-1010) for FreeSWITCH

DIRECTORY="/etc/freeswitch/directory/default"

declare -A USERS=(
  [1001]="Alice Johnson:sales"
  [1002]="Bob Williams:sales"
  [1003]="Carol Davis:sales"
  [1004]="Dan Miller:support"
  [1005]="Eve Wilson:support"
  [1006]="Frank Brown:support"
  [1007]="Grace Taylor:billing"
  [1008]="Hank Anderson:billing"
  [1009]="Ivy Martinez:management"
  [1010]="Jack Thompson:management"
)

for EXT in "${!USERS[@]}"; do
  IFS=':' read -r NAME GROUP <<< "${USERS[$EXT]}"

  # Generate a random password
  PASS=$(openssl rand -base64 12 | tr -dc 'A-Za-z0-9' | head -c 16)

  cat > "${DIRECTORY}/${EXT}.xml" << XMLEOF
<include>
  <user id="${EXT}">
    <params>
      <param name="password" value="${PASS}"/>
      <param name="vm-password" value="${EXT}"/>
    </params>
    <variables>
      <variable name="toll_allow" value="domestic,local"/>
      <variable name="accountcode" value="${EXT}"/>
      <variable name="user_context" value="default"/>
      <variable name="effective_caller_id_name" value="${NAME}"/>
      <variable name="effective_caller_id_number" value="${EXT}"/>
      <variable name="outbound_caller_id_name" value="My Company"/>
      <variable name="outbound_caller_id_number" value="15551234567"/>
      <variable name="callgroup" value="${GROUP}"/>
    </variables>
  </user>
</include>
XMLEOF

  echo "Created ${EXT} — ${NAME} (${GROUP}) — Password: ${PASS}"
done

chown -R freeswitch:freeswitch "${DIRECTORY}"
echo ""
echo "Done. Run 'fs_cli -x reloadxml' to apply."
echo "IMPORTANT: Save the passwords above — they will not be displayed again."

chmod +x create-extensions.sh
./create-extensions.sh

SIP Trunk (Gateway) Configuration

A gateway defines a connection to your SIP provider (ITSP). Create /etc/freeswitch/sip_profiles/external/my_provider.xml:

<include>
  <gateway name="my_provider">
    <!-- Provider credentials -->
    <param name="username" value="your_sip_username"/>
    <param name="password" value="your_sip_password"/>
    <param name="realm" value="sip.provider.com"/>
    <param name="proxy" value="sip.provider.com"/>

    <!-- Registration (some providers require it, some use IP auth) -->
    <param name="register" value="true"/>
    <param name="register-transport" value="udp"/>

    <!-- Caller ID -->
    <param name="caller-id-in-from" value="true"/>

    <!-- Retry on failure -->
    <param name="retry-seconds" value="30"/>

    <!-- Codec preferences for this trunk -->
    <param name="codec-prefs" value="PCMU,PCMA,G722"/>

    <!-- Ping the provider to detect failures -->
    <param name="ping" value="25"/>
    <param name="ping-max" value="3"/>
    <param name="ping-min" value="1"/>
  </gateway>
</include>

For IP-based authentication (no username/password, provider allows your IP):

<include>
  <gateway name="ip_auth_provider">
    <param name="username" value="not_used"/>
    <param name="password" value="not_used"/>
    <param name="realm" value="sip.provider.com"/>
    <param name="proxy" value="sip.provider.com"/>
    <param name="register" value="false"/>
    <param name="caller-id-in-from" value="true"/>
  </gateway>
</include>

After creating gateway files, reload:

# From fs_cli
fs_cli -x "sofia profile external rescan"

# Check gateway status
fs_cli -x "sofia status gateway my_provider"

# Expected output:
# Name         my_provider
# Profile      external
# Scheme       sip
# Realm        sip.provider.com
# Username     your_sip_username
# ...
# State        REGED  <-- Successfully registered
# Status       UP

Inbound DID Routing

When a call arrives from a trunk, it enters the public context. You need to route it to the right extension.

Edit /etc/freeswitch/dialplan/public.xml:

<include>
  <context name="public">
    <!-- Route DID +15551234567 to extension 1001 -->
    <extension name="inbound_main">
      <condition field="destination_number" expression="^(\+?1?5551234567)$">
        <action application="set" data="domain_name=$${domain}"/>
        <action application="transfer" data="1001 XML default"/>
      </condition>
    </extension>

    <!-- Route DID +15559876543 to IVR -->
    <extension name="inbound_ivr">
      <condition field="destination_number" expression="^(\+?1?5559876543)$">
        <action application="set" data="domain_name=$${domain}"/>
        <action application="transfer" data="5000 XML default"/>
      </condition>
    </extension>

    <!-- Route DID +15555551234 to ring group (sales) -->
    <extension name="inbound_sales">
      <condition field="destination_number" expression="^(\+?1?5555551234)$">
        <action application="set" data="domain_name=$${domain}"/>
        <action application="transfer" data="9001 XML default"/>
      </condition>
    </extension>

    <!-- Catch-all: reject unknown DIDs -->
    <extension name="public_reject">
      <condition field="destination_number" expression="^(.*)$">
        <action application="log" data="WARNING Rejecting unknown inbound DID: ${destination_number} from ${sip_from_uri}"/>
        <action application="hangup" data="CALL_REJECTED"/>
      </condition>
    </extension>
  </context>
</include>

NAT Traversal

If your FreeSWITCH server is behind NAT (e.g., in AWS/GCP/Azure with a private IP), configure these settings:

In vars.xml:

<X-PRE-PROCESS cmd="set" data="external_sip_ip=YOUR_PUBLIC_IP"/>
<X-PRE-PROCESS cmd="set" data="external_rtp_ip=YOUR_PUBLIC_IP"/>

In each SIP profile (internal.xml and external.xml):

<!-- Replace the sip-ip and rtp-ip lines with: -->
<param name="sip-ip" value="$${local_ip_v4}"/>
<param name="ext-sip-ip" value="$${external_sip_ip}"/>
<param name="rtp-ip" value="$${local_ip_v4}"/>
<param name="ext-rtp-ip" value="$${external_rtp_ip}"/>

<!-- Enable NAT handling -->
<param name="apply-nat-acl" value="nat.auto"/>
<param name="aggressive-nat-detection" value="true"/>
<param name="local-network-acl" value="localnet.auto"/>

Registering SIP Phones

With extensions created, configure your SIP phone/softphone:

Setting	Value
SIP Server / Registrar	`YOUR_SERVER_IP`
Port	`5060`
Username	`1001` (the extension number)
Password	The password from the directory XML
Transport	UDP (or TCP/TLS)
Domain/Realm	`YOUR_SERVER_IP`

Verify registration:

fs_cli -x "sofia status profile internal reg"

# Output shows registered endpoints:
# Call-ID:        xxxxx@yyyy
# User:           1001@YOUR_SERVER_IP
# Contact:        "Alice Johnson" <sip:1001@phone_ip:port>
# Agent:          Ooh, a softphone!
# Status:         Registered(UDP)(unknown) EXP(2024-01-01 12:00:00)
# ...

5. XML Dialplan

Dialplan Structure

The FreeSWITCH dialplan is a hierarchy: Context → Extension → Condition → Action.

<context name="default">          <!-- Container: who can use these rules -->
  <extension name="my_rule">      <!-- Named rule -->
    <condition field="X" expression="regex">  <!-- When to match -->
      <action application="Y" data="Z"/>      <!-- What to do -->
      <action application="Y2" data="Z2"/>    <!-- Actions run in sequence -->
    </condition>
  </extension>
</context>

FreeSWITCH evaluates extensions top-to-bottom within a context. By default, it stops at the first matching extension (unless the extension is marked continue="true").

Condition Matching

Conditions can match on any channel variable. Common fields:

Field	Matches	Example Pattern
`destination_number`	The dialed number	`^(10[0-1][0-9])$`
`caller_id_number`	Calling party number	`^(1001)$`
`caller_id_name`	Calling party name	`^(Alice.*)$`
`time_of_day`	Current time (HH:MM)	`08:00-17:00`
`day_of_week`	Day (1=Sun, 7=Sat)	`2-6` (Mon-Fri)
`network_addr`	Source IP of the call	`^10\.0\.0\..*$`
`${sip_to_uri}`	SIP To header	`^.*@example\.com$`
`${sip_h_X-Custom}`	Custom SIP header	`^(premium)$`

Multiple conditions in the same extension use AND logic — all must match.

Regex Patterns

FreeSWITCH uses PCRE-compatible regular expressions:

^1001$              — Exact match for "1001"
^(10[0-1][0-9])$    — Match 1000-1019
^(\d{10})$          — Match any 10-digit number
^9(\d+)$            — Match 9 + any digits (capture digits after 9)
^(\+?1?\d{10})$     — Match with optional +1 prefix
^.*$                — Match anything (catch-all)

Captured groups are available as $1, $2, etc.

Channel Variables

Channel variables store per-call data. You can set them and use them in conditions/actions:

<!-- Set a variable -->
<action application="set" data="my_var=hello"/>

<!-- Use a variable in an action -->
<action application="log" data="INFO The value is ${my_var}"/>

<!-- Use a variable in a condition -->
<condition field="${my_var}" expression="^(hello)$">

Common built-in variables:

Variable	Description
`${destination_number}`	Dialed number
`${caller_id_number}`	Caller's number
`${caller_id_name}`	Caller's name
`${uuid}`	Unique call identifier
`${sip_from_uri}`	SIP From URI
`${sip_to_uri}`	SIP To URI
`${strftime(%Y-%m-%d %H:%M:%S)}`	Current date/time
`${domain_name}`	SIP domain
`${accountcode}`	User's account code
`${callgroup}`	User's call group

Common Dialplan Actions

Action	Purpose	Example
`answer`	Answer the call (send 200 OK)	`<action application="answer"/>`
`bridge`	Connect to another endpoint	`<action application="bridge" data="user/1001"/>`
`playback`	Play audio file	`<action application="playback" data="/sounds/greeting.wav"/>`
`sleep`	Pause for milliseconds	`<action application="sleep" data="1000"/>`
`hangup`	Hang up the call	`<action application="hangup" data="NORMAL_CLEARING"/>`
`set`	Set a channel variable	`<action application="set" data="key=value"/>`
`export`	Set variable on both legs	`<action application="export" data="key=value"/>`
`transfer`	Transfer to another extension	`<action application="transfer" data="1002 XML default"/>`
`record_session`	Record the entire call	`<action application="record_session" data="/recordings/${uuid}.wav"/>`
`play_and_get_digits`	Play prompt + collect DTMF	See IVR section
`conference`	Join a conference room	`<action application="conference" data="room1@default"/>`
`voicemail`	Send to voicemail	`<action application="voicemail" data="default $${domain} 1001"/>`
`ring_ready`	Send 180 Ringing	`<action application="ring_ready"/>`
`log`	Write to log	`<action application="log" data="INFO message here"/>`
`respond`	Send SIP response code	`<action application="respond" data="486"/>`

Anti-Actions

Anti-actions execute when a condition does NOT match. They use the <anti-action> tag:

<extension name="business_hours">
  <condition field="time_of_day" expression="09:00-17:30">
    <!-- This runs during business hours -->
    <action application="transfer" data="5000 XML default"/>
    <!-- This runs OUTSIDE business hours -->
    <anti-action application="playback" data="ivr/ivr-please_call_back_during_business_hours.wav"/>
    <anti-action application="voicemail" data="default $${domain} 1001"/>
  </condition>
</extension>

Complete Dialplan Examples

Here is a production-ready default context. Save as /etc/freeswitch/dialplan/default.xml:

<include>
  <context name="default">

    <!-- ============================================ -->
    <!-- INTERNAL EXTENSION CALLING (1001-1099)       -->
    <!-- ============================================ -->
    <extension name="internal_extensions">
      <condition field="destination_number" expression="^(10[0-9]{2})$">
        <action application="set" data="dialed_extension=$1"/>
        <action application="export" data="dialed_extension=$1"/>

        <!-- Set ring timeout to 30 seconds -->
        <action application="set" data="call_timeout=30"/>

        <!-- Set caller ID -->
        <action application="set"
          data="effective_caller_id_name=${outbound_caller_id_name}"/>
        <action application="set"
          data="effective_caller_id_number=${outbound_caller_id_number}"/>

        <!-- Ring the extension, then send to voicemail on no answer -->
        <action application="set"
          data="hangup_after_bridge=true"/>
        <action application="set"
          data="continue_on_fail=true"/>
        <action application="bridge"
          data="user/${dialed_extension}@$${domain}"/>

        <!-- No answer — go to voicemail -->
        <action application="answer"/>
        <action application="sleep" data="1000"/>
        <action application="voicemail"
          data="default $${domain} ${dialed_extension}"/>
      </condition>
    </extension>

    <!-- ============================================ -->
    <!-- RING GROUPS                                  -->
    <!-- ============================================ -->

    <!-- Sales ring group (9001) — ring all sales phones simultaneously -->
    <extension name="ring_group_sales">
      <condition field="destination_number" expression="^(9001)$">
        <action application="set" data="call_timeout=25"/>
        <action application="set" data="continue_on_fail=true"/>
        <action application="set" data="hangup_after_bridge=true"/>
        <action application="bridge"
          data="user/1001@$${domain},user/1002@$${domain},user/1003@$${domain}"/>
        <!-- All busy/unavailable — voicemail for sales -->
        <action application="voicemail" data="default $${domain} 1001"/>
      </condition>
    </extension>

    <!-- Support ring group (9002) — sequential ring (try each for 15s) -->
    <extension name="ring_group_support">
      <condition field="destination_number" expression="^(9002)$">
        <action application="set" data="continue_on_fail=true"/>
        <action application="set" data="hangup_after_bridge=true"/>
        <!-- Try first support agent -->
        <action application="set" data="call_timeout=15"/>
        <action application="bridge" data="user/1004@$${domain}"/>
        <!-- Try second -->
        <action application="bridge" data="user/1005@$${domain}"/>
        <!-- Try third -->
        <action application="bridge" data="user/1006@$${domain}"/>
        <!-- All unavailable -->
        <action application="voicemail" data="default $${domain} 1004"/>
      </condition>
    </extension>

    <!-- ============================================ -->
    <!-- OUTBOUND CALLS VIA TRUNK                     -->
    <!-- ============================================ -->

    <!-- Local/National calls: dial 9 + number -->
    <extension name="outbound_national">
      <condition field="destination_number" expression="^9(\d{10,11})$">
        <action application="set" data="effective_caller_id_number=15551234567"/>
        <action application="set" data="effective_caller_id_name=My Company"/>
        <action application="set" data="hangup_after_bridge=true"/>
        <action application="set" data="call_timeout=60"/>
        <action application="bridge"
          data="sofia/gateway/my_provider/$1"/>
      </condition>
    </extension>

    <!-- International calls: dial 00 + country code + number -->
    <extension name="outbound_international">
      <condition field="destination_number" expression="^(00\d{7,15})$">
        <!-- Check if user has international permission -->
        <action application="set"
          data="continue_on_fail=false"/>
        <action application="set"
          data="effective_caller_id_number=15551234567"/>
        <action application="bridge"
          data="sofia/gateway/my_provider/$1"/>
      </condition>
    </extension>

    <!-- ============================================ -->
    <!-- TIME-BASED ROUTING                           -->
    <!-- ============================================ -->
    <extension name="main_number_time_routing">
      <condition field="destination_number" expression="^(5000)$"/>
      <!-- Check business hours: Mon-Fri 9:00-17:30 -->
      <condition field="time_of_day" expression="09:00-17:30">
        <action application="transfer" data="5001 XML default"/>
        <anti-action application="transfer" data="5002 XML default"/>
      </condition>
    </extension>

    <!-- Business hours handler -->
    <extension name="business_hours_handler">
      <condition field="destination_number" expression="^(5001)$">
        <action application="answer"/>
        <action application="playback"
          data="ivr/ivr-welcome.wav"/>
        <action application="transfer" data="main_ivr XML default"/>
      </condition>
    </extension>

    <!-- After hours handler -->
    <extension name="after_hours_handler">
      <condition field="destination_number" expression="^(5002)$">
        <action application="answer"/>
        <action application="playback"
          data="ivr/ivr-after_hours_message.wav"/>
        <action application="voicemail"
          data="default $${domain} 1001"/>
      </condition>
    </extension>

    <!-- ============================================ -->
    <!-- UTILITIES                                    -->
    <!-- ============================================ -->

    <!-- Echo test (dial 9196) -->
    <extension name="echo_test">
      <condition field="destination_number" expression="^(9196)$">
        <action application="answer"/>
        <action application="echo"/>
      </condition>
    </extension>

    <!-- Music on hold test (dial 9664) -->
    <extension name="moh_test">
      <condition field="destination_number" expression="^(9664)$">
        <action application="answer"/>
        <action application="playback"
          data="$${hold_music}"/>
      </condition>
    </extension>

    <!-- Voicemail access (dial *98) -->
    <extension name="voicemail_check">
      <condition field="destination_number" expression="^\*98$">
        <action application="answer"/>
        <action application="sleep" data="500"/>
        <action application="voicemail"
          data="check default $${domain}"/>
      </condition>
    </extension>

    <!-- Direct voicemail for extension (dial *99 + ext) -->
    <extension name="voicemail_direct">
      <condition field="destination_number" expression="^\*99(\d{4})$">
        <action application="answer"/>
        <action application="sleep" data="500"/>
        <action application="voicemail"
          data="default $${domain} $1"/>
      </condition>
    </extension>

    <!-- Call parking (dial 5900) -->
    <extension name="park_call">
      <condition field="destination_number" expression="^(5900)$">
        <action application="set" data="fifo_music=$${hold_music}"/>
        <action application="fifo" data="park@$${domain} in"/>
      </condition>
    </extension>

    <!-- Retrieve parked call (dial 5901) -->
    <extension name="retrieve_parked_call">
      <condition field="destination_number" expression="^(5901)$">
        <action application="answer"/>
        <action application="fifo" data="park@$${domain} out wait"/>
      </condition>
    </extension>

  </context>
</include>

6. IVR Menus

IVR Concepts in FreeSWITCH

FreeSWITCH provides two approaches to IVR:

mod_ivr menus — XML-configured menu trees with automatic DTMF handling, timeouts, and invalid-input retries. Best for simple, static IVR flows.
play_and_get_digits — A dialplan application that plays a prompt and collects DTMF digits. Best for dynamic IVRs with variable-based routing.

You can combine both: use mod_ivr for the menu structure and play_and_get_digits for collecting account numbers or PINs.

IVR Menu XML Configuration

IVR menus are defined in /etc/freeswitch/autoload_configs/ivr.conf.xml:

<configuration name="ivr.conf" description="IVR Menus">
  <menus>

    <!-- ============================================ -->
    <!-- MAIN MENU (Level 1)                          -->
    <!-- ============================================ -->
    <menu name="main_ivr"
          greet-long="ivr/ivr-welcome_to_our_company.wav"
          greet-short="ivr/ivr-please_make_selection.wav"
          invalid-sound="ivr/ivr-that_was_an_invalid_entry.wav"
          exit-sound="voicemail/vm-goodbye.wav"
          confirm-macro=""
          confirm-key=""
          tts-engine=""
          tts-voice=""
          confirm-attempts="3"
          timeout="10000"
          inter-digit-timeout="2000"
          max-failures="3"
          max-timeouts="3"
          digit-len="1">

      <!-- Press 1 for Sales -->
      <entry action="menu-exec-app"
             digits="1"
             param="transfer 9001 XML default"/>

      <!-- Press 2 for Support -->
      <entry action="menu-exec-app"
             digits="2"
             param="transfer 9002 XML default"/>

      <!-- Press 3 for Billing -->
      <entry action="menu-sub"
             digits="3"
             param="billing_ivr"/>

      <!-- Press 4 for Company Directory -->
      <entry action="menu-exec-app"
             digits="4"
             param="transfer 411 XML default"/>

      <!-- Press 0 for Operator -->
      <entry action="menu-exec-app"
             digits="0"
             param="transfer 1009 XML default"/>

      <!-- Press * to repeat -->
      <entry action="menu-top"
             digits="*"/>

    </menu>

    <!-- ============================================ -->
    <!-- BILLING SUBMENU (Level 2)                    -->
    <!-- ============================================ -->
    <menu name="billing_ivr"
          greet-long="ivr/ivr-billing_menu.wav"
          greet-short="ivr/ivr-please_make_selection.wav"
          invalid-sound="ivr/ivr-that_was_an_invalid_entry.wav"
          exit-sound="voicemail/vm-goodbye.wav"
          timeout="10000"
          inter-digit-timeout="2000"
          max-failures="3"
          max-timeouts="3"
          digit-len="1">

      <!-- Press 1 for Account Balance -->
      <entry action="menu-exec-app"
             digits="1"
             param="transfer 8001 XML default"/>

      <!-- Press 2 for Payment -->
      <entry action="menu-exec-app"
             digits="2"
             param="transfer 8002 XML default"/>

      <!-- Press 3 for Billing Agent -->
      <entry action="menu-exec-app"
             digits="3"
             param="transfer 1007 XML default"/>

      <!-- Press 9 to go back to main menu -->
      <entry action="menu-back"
             digits="9"/>

      <!-- Press 0 for Operator -->
      <entry action="menu-exec-app"
             digits="0"
             param="transfer 1009 XML default"/>

    </menu>

    <!-- ============================================ -->
    <!-- SUPPORT SUBMENU (Level 2)                    -->
    <!-- ============================================ -->
    <menu name="support_ivr"
          greet-long="ivr/ivr-support_menu.wav"
          greet-short="ivr/ivr-please_make_selection.wav"
          invalid-sound="ivr/ivr-that_was_an_invalid_entry.wav"
          exit-sound="voicemail/vm-goodbye.wav"
          timeout="10000"
          inter-digit-timeout="2000"
          max-failures="3"
          max-timeouts="3"
          digit-len="1">

      <!-- Press 1 for Technical Support -->
      <entry action="menu-sub"
             digits="1"
             param="tech_support_ivr"/>

      <!-- Press 2 for General Inquiries -->
      <entry action="menu-exec-app"
             digits="2"
             param="transfer 1005 XML default"/>

      <!-- Press 9 to go back -->
      <entry action="menu-back"
             digits="9"/>

    </menu>

    <!-- ============================================ -->
    <!-- TECH SUPPORT (Level 3)                       -->
    <!-- ============================================ -->
    <menu name="tech_support_ivr"
          greet-long="ivr/ivr-tech_support_menu.wav"
          greet-short="ivr/ivr-please_make_selection.wav"
          invalid-sound="ivr/ivr-that_was_an_invalid_entry.wav"
          exit-sound="voicemail/vm-goodbye.wav"
          timeout="10000"
          inter-digit-timeout="2000"
          max-failures="3"
          max-timeouts="3"
          digit-len="1">

      <!-- Press 1 for Internet Issues -->
      <entry action="menu-exec-app"
             digits="1"
             param="transfer 1004 XML default"/>

      <!-- Press 2 for Phone/VoIP Issues -->
      <entry action="menu-exec-app"
             digits="2"
             param="transfer 1005 XML default"/>

      <!-- Press 3 for Email Issues -->
      <entry action="menu-exec-app"
             digits="3"
             param="transfer 1006 XML default"/>

      <!-- Press 9 to go back -->
      <entry action="menu-back"
             digits="9"/>

      <!-- Press 0 for Operator -->
      <entry action="menu-exec-app"
             digits="0"
             param="transfer 1009 XML default"/>

    </menu>

  </menus>
</configuration>

IVR Menu Parameters Reference

Parameter	Description
`greet-long`	First greeting played when entering the menu
`greet-short`	Short greeting played on repeat/return
`invalid-sound`	Played when invalid key is pressed
`exit-sound`	Played when exiting the menu
`timeout`	Milliseconds to wait for input (default: 10000)
`inter-digit-timeout`	Milliseconds between digits for multi-digit input
`max-failures`	Hang up after this many invalid entries
`max-timeouts`	Hang up after this many timeouts
`digit-len`	Number of digits to collect (1 for single key menus)

IVR Entry Actions

Action	Description
`menu-exec-app`	Execute a dialplan application
`menu-sub`	Enter a sub-menu
`menu-top`	Return to the top of current menu
`menu-back`	Go back to parent menu
`menu-exit`	Exit the IVR

Connecting the IVR to the Dialplan

Add this to your default context in /etc/freeswitch/dialplan/default.xml:

<!-- IVR entry point (dial 5000 or transfer from public context) -->
<extension name="main_ivr">
  <condition field="destination_number" expression="^(main_ivr|5000)$">
    <action application="answer"/>
    <action application="sleep" data="500"/>
    <action application="ivr" data="main_ivr"/>
  </condition>
</extension>

Using play_and_get_digits

For dynamic DTMF collection (account numbers, PINs, etc.), use play_and_get_digits:

<!-- Collect a 5-digit account number -->
<extension name="account_lookup">
  <condition field="destination_number" expression="^(8001)$">
    <action application="answer"/>
    <action application="sleep" data="500"/>

    <!-- play_and_get_digits parameters:
         min_digits max_digits max_tries timeout terminators
         audio_file bad_input_file variable_name regex_pattern
         digit_timeout transfer_on_failure -->
    <action application="play_and_get_digits"
      data="5 5 3 10000 # ivr/ivr-enter_account_number.wav ivr/ivr-that_was_an_invalid_entry.wav account_number \d{5} 15000"/>

    <!-- Now use the collected digits -->
    <action application="log"
      data="INFO Account number entered: ${account_number}"/>

    <!-- You could use mod_xml_curl to look up the account,
         or use Lua/Python to query a database -->
    <action application="playback"
      data="ivr/ivr-thank_you.wav"/>
    <action application="transfer"
      data="1007 XML default"/>
  </condition>
</extension>

play_and_get_digits parameter breakdown:

Position	Parameter	Description
1	`min_digits`	Minimum digits to collect
2	`max_digits`	Maximum digits to collect
3	`max_tries`	Retries on invalid input
4	`timeout`	Milliseconds to wait for first digit
5	`terminators`	Key to finish input (`#` is standard)
6	`audio_file`	Prompt to play
7	`bad_input_file`	Error sound
8	`variable_name`	Variable to store result
9	`regex_pattern`	Validation regex
10	`digit_timeout`	Milliseconds between digits
11	`transfer_on_fail`	Where to transfer after max failures

Text-to-Speech (TTS)

Instead of pre-recorded prompts, you can use TTS:

With mod_flite (built-in, free, basic quality):

<action application="speak" data="flite|kal|Welcome to our company. Press 1 for sales."/>

With mod_tts_commandline (use any external TTS engine):

First configure in /etc/freeswitch/autoload_configs/tts_commandline.conf.xml:

<configuration name="tts_commandline.conf" description="TTS Command">
  <settings>
    <param name="command" value="echo '${text}' | /usr/bin/piper --model /opt/tts/en_US-lessac-medium.onnx --output_file ${file}"/>
  </settings>
</configuration>

Then use in the dialplan:

<action application="speak"
  data="tts_commandline|default|Welcome to our company. Please hold while we connect you."/>

Complete 3-Level IVR Example

Putting it all together — here is the call flow:

Caller dials main number
       │
       ▼
   Level 1: Main Menu
   1 → Sales (ring group 9001)
   2 → Support submenu
   3 → Billing submenu
   4 → Company directory
   0 → Operator (ext 1009)
       │
       ├── Level 2: Support
       │   1 → Tech Support submenu
       │   2 → General Inquiries (ext 1005)
       │   9 → Back to Main
       │       │
       │       └── Level 3: Tech Support
       │           1 → Internet (ext 1004)
       │           2 → VoIP (ext 1005)
       │           3 → Email (ext 1006)
       │           9 → Back to Support
       │           0 → Operator
       │
       └── Level 2: Billing
           1 → Account Balance (collect acct#)
           2 → Payment (ext 8002)
           3 → Billing Agent (ext 1007)
           9 → Back to Main
           0 → Operator

The XML for all three levels is already shown above in the ivr.conf.xml section. Just ensure the dialplan has transfer targets for each destination.

7. Voicemail

Voicemail Configuration

FreeSWITCH voicemail is handled by mod_voicemail. Configure it in /etc/freeswitch/autoload_configs/voicemail.conf.xml:

<configuration name="voicemail.conf" description="Voicemail">
  <settings>
  </settings>

  <profiles>
    <profile name="default">
      <!-- Storage -->
      <param name="file-extension" value="wav"/>
      <param name="record-silence-threshold" value="200"/>
      <param name="record-silence-hits" value="5"/>
      <param name="max-record-len" value="300"/>
      <param name="max-retries" value="3"/>

      <!-- Greeting -->
      <param name="terminator-key" value="#"/>
      <param name="play-new-messages-key" value="1"/>
      <param name="play-saved-messages-key" value="2"/>

      <!-- Message controls (during playback) -->
      <param name="skip-greet-key" value="#"/>
      <param name="config-menu-key" value="5"/>
      <param name="record-greeting-key" value="1"/>
      <param name="choose-greeting-key" value="2"/>
      <param name="change-pass-key" value="6"/>

      <!-- Playback controls -->
      <param name="listen-key" value="1"/>
      <param name="save-key" value="2"/>
      <param name="delete-key" value="7"/>
      <param name="forward-key" value="8"/>
      <param name="repeat-key" value="0"/>

      <!-- Notification -->
      <param name="notify-mailto" value=""/>
      <param name="notify-email-body" value="You have a new voicemail from ${caller_id_number} (${caller_id_name}). The message is ${message_len} seconds long."/>
      <param name="notify-email-subject" value="New voicemail from ${caller_id_number}"/>

      <!-- Email with attachment -->
      <param name="email-from" value="voicemail@YOUR_DOMAIN"/>
      <param name="email-body" value="You have a new voicemail.\n\nFrom: ${caller_id_name} (${caller_id_number})\nDate: ${left_epoch}\nDuration: ${message_len} seconds\n\nThe recording is attached."/>
      <param name="email-subject" value="[Voicemail] New message from ${caller_id_number}"/>

      <!-- Attach the recording to the email -->
      <param name="vm-email-all-messages" value="true"/>
      <!-- Delete from server after emailing (set false to keep) -->
      <param name="vm-delete-file" value="false"/>
      <!-- Keep the message as new after emailing -->
      <param name="vm-keep-local-after-email" value="true"/>

      <!-- MWI (Message Waiting Indicator — lights up the phone's voicemail LED) -->
      <param name="vm-message-ext" value="wav"/>

      <!-- Storage location -->
      <param name="storage-dir" value="$${storage_dir}/voicemail/default"/>

      <!-- Operator extension (press 0 during greeting) -->
      <param name="operator-extension" value="operator XML default"/>
      <param name="operator-key" value="0"/>
    </profile>
  </profiles>
</configuration>

Dialplan Integration

Add these extensions to your default context:

<!-- Send to voicemail (internal — after no answer on bridge) -->
<!-- This is already in the internal_extensions example above -->

<!-- Check own voicemail: dial *98 -->
<extension name="voicemail_check">
  <condition field="destination_number" expression="^\*98$">
    <action application="answer"/>
    <action application="sleep" data="500"/>
    <action application="voicemail"
      data="check default $${domain}"/>
  </condition>
</extension>

<!-- Leave voicemail directly for someone: dial *99 + extension -->
<extension name="voicemail_leave">
  <condition field="destination_number" expression="^\*99(\d{4})$">
    <action application="answer"/>
    <action application="sleep" data="500"/>
    <action application="voicemail"
      data="default $${domain} $1"/>
  </condition>
</extension>

<!-- Check specific mailbox (for shared mailboxes): dial *97 + extension -->
<extension name="voicemail_check_specific">
  <condition field="destination_number" expression="^\*97(\d{4})$">
    <action application="answer"/>
    <action application="sleep" data="500"/>
    <action application="voicemail"
      data="check default $${domain} $1"/>
  </condition>
</extension>

Email Notification Setup

For voicemail-to-email to work, you need a working mail system:

# Install a lightweight MTA
apt-get install -y msmtp msmtp-mta

# Configure SMTP relay
cat > /etc/msmtprc << 'EOF'
defaults
auth           on
tls            on
tls_trust_file /etc/ssl/certs/ca-certificates.crt
logfile        /var/log/msmtp.log

account        default
host           smtp.gmail.com
port           587
from           voicemail@YOUR_DOMAIN
user           your_email@gmail.com
password       your_app_password
EOF

chmod 600 /etc/msmtprc

Then set the notify-mailto in each user's directory XML to enable per-user email notification:

<!-- In /etc/freeswitch/directory/default/1001.xml -->
<include>
  <user id="1001">
    <params>
      <param name="password" value="Str0ng_P@ss_1001!"/>
      <param name="vm-password" value="1001"/>
      <param name="vm-mailto" value="alice@company.com"/>
      <param name="vm-email-all-messages" value="true"/>
      <param name="vm-attach-file" value="true"/>
      <param name="vm-keep-local-after-email" value="true"/>
    </params>
    <!-- ... variables ... -->
  </user>
</include>

Greeting Management

Users manage their own greetings by calling *98 (voicemail check) and pressing:

5 — Configuration menu
1 — Record a new greeting
2 — Choose between recorded greetings

Greetings are stored in /var/lib/freeswitch/storage/voicemail/default/YOUR_DOMAIN/1001/.

Storage and Cleanup

Voicemail files accumulate. Set up automated cleanup:

#!/bin/bash
# /usr/local/bin/cleanup-voicemail.sh
# Delete voicemail messages older than 30 days

STORAGE_DIR="/var/lib/freeswitch/storage/voicemail"
MAX_AGE=30

echo "$(date '+%Y-%m-%d %H:%M:%S') — Voicemail cleanup starting"

# Find and delete old voicemail recordings
find "${STORAGE_DIR}" -name "*.wav" -type f -mtime +${MAX_AGE} -delete
find "${STORAGE_DIR}" -name "*.mp3" -type f -mtime +${MAX_AGE} -delete

# Clean up empty directories
find "${STORAGE_DIR}" -type d -empty -delete

echo "$(date '+%Y-%m-%d %H:%M:%S') — Voicemail cleanup complete"

chmod +x /usr/local/bin/cleanup-voicemail.sh

# Run weekly
echo "0 3 * * 0 root /usr/local/bin/cleanup-voicemail.sh >> /var/log/voicemail-cleanup.log 2>&1" \
  > /etc/cron.d/voicemail-cleanup

8. Call Recording

Full-Call Recording with record_session

The record_session application records both legs of a call (caller and callee) into a single file for the entire duration. Add it to any dialplan extension before the bridge:

<extension name="recorded_internal_call">
  <condition field="destination_number" expression="^(10[0-9]{2})$">
    <action application="set" data="dialed_extension=$1"/>

    <!-- Start recording BEFORE bridging -->
    <action application="set"
      data="RECORD_STEREO=true"/>
    <action application="set"
      data="media_bug_answer_req=true"/>
    <action application="record_session"
      data="/var/lib/freeswitch/recordings/${strftime(%Y/%m/%d)}/${uuid}_${caller_id_number}_to_${dialed_extension}.wav"/>

    <!-- Now bridge the call -->
    <action application="set" data="call_timeout=30"/>
    <action application="set" data="hangup_after_bridge=true"/>
    <action application="set" data="continue_on_fail=true"/>
    <action application="bridge"
      data="user/${dialed_extension}@$${domain}"/>

    <!-- Voicemail on no answer (recording continues into VM) -->
    <action application="answer"/>
    <action application="voicemail"
      data="default $${domain} ${dialed_extension}"/>
  </condition>
</extension>

File Naming Best Practices

Use structured file naming for easy searching and archiving:

<!-- Date-based subdirectories + descriptive filenames -->
<action application="record_session"
  data="/var/lib/freeswitch/recordings/${strftime(%Y/%m/%d)}/${uuid}_${caller_id_number}_to_${destination_number}_${strftime(%Y%m%d-%H%M%S)}.wav"/>

This creates a path like:

/var/lib/freeswitch/recordings/2026/03/14/abc123_15551234567_to_1001_20260314-143022.wav

Stereo Recording

Stereo recording places each call leg on a separate audio channel (left = caller, right = callee). This is essential for speech analytics and quality review:

<!-- Enable stereo recording -->
<action application="set" data="RECORD_STEREO=true"/>

<!-- Record in stereo WAV -->
<action application="record_session"
  data="/var/lib/freeswitch/recordings/${strftime(%Y/%m/%d)}/${uuid}.wav"/>

Start/Stop Recording Mid-Call

You can control recording dynamically during a call using the API:

# Start recording on an active call (from fs_cli or ESL)
uuid_record <call-uuid> start /var/lib/freeswitch/recordings/mid_call_recording.wav

# Stop recording
uuid_record <call-uuid> stop /var/lib/freeswitch/recordings/mid_call_recording.wav

# Stop all recordings on a call
uuid_record <call-uuid> stop all

In the dialplan, you can use DTMF-triggered recording:

<!-- Agent presses *1 to start recording, *2 to stop -->
<extension name="record_on_demand">
  <condition field="destination_number" expression="^(10[0-9]{2})$">
    <action application="set" data="dialed_extension=$1"/>

    <!-- Bind DTMF keys for recording control -->
    <action application="bind_digit_action"
      data="rec,*1,exec:record_session,/var/lib/freeswitch/recordings/${uuid}_on_demand.wav"/>
    <action application="bind_digit_action"
      data="rec,*2,exec:stop_record_session,/var/lib/freeswitch/recordings/${uuid}_on_demand.wav"/>
    <action application="digit_action_set_realm" data="rec"/>

    <action application="bridge"
      data="user/${dialed_extension}@$${domain}"/>
  </condition>
</extension>

Post-Call Processing: Convert to MP3

WAV files are large (~1 MB/minute for mono, ~2 MB/minute for stereo). Convert to MP3 for long-term storage:

#!/bin/bash
# /usr/local/bin/convert-recordings.sh
# Convert WAV recordings to MP3 and archive

RECORDINGS_DIR="/var/lib/freeswitch/recordings"
ARCHIVE_DIR="/var/lib/freeswitch/recordings-mp3"
LOG="/var/log/recording-convert.log"

# Install lame if not present
which lame > /dev/null 2>&1 || apt-get install -y lame

# Process WAV files older than 5 minutes (avoid in-progress recordings)
find "${RECORDINGS_DIR}" -name "*.wav" -type f -mmin +5 | while read WAV_FILE; do
  # Build MP3 path (mirror directory structure)
  REL_PATH="${WAV_FILE#${RECORDINGS_DIR}/}"
  MP3_FILE="${ARCHIVE_DIR}/${REL_PATH%.wav}.mp3"
  MP3_DIR=$(dirname "${MP3_FILE}")

  # Create directory
  mkdir -p "${MP3_DIR}"

  # Convert
  if lame --quiet -V2 "${WAV_FILE}" "${MP3_FILE}" 2>/dev/null; then
    echo "$(date '+%Y-%m-%d %H:%M:%S') Converted: ${REL_PATH}" >> "${LOG}"
    # Delete original WAV after successful conversion
    rm -f "${WAV_FILE}"
  else
    echo "$(date '+%Y-%m-%d %H:%M:%S') FAILED: ${REL_PATH}" >> "${LOG}"
  fi
done

# Clean up empty directories
find "${RECORDINGS_DIR}" -type d -empty -delete 2>/dev/null

chmod +x /usr/local/bin/convert-recordings.sh

# Run every 30 minutes
echo "*/30 * * * * root /usr/local/bin/convert-recordings.sh" \
  > /etc/cron.d/recording-convert

Retention and Cleanup

#!/bin/bash
# /usr/local/bin/cleanup-recordings.sh
# Delete recordings older than retention period

RECORDINGS_DIR="/var/lib/freeswitch/recordings"
MP3_DIR="/var/lib/freeswitch/recordings-mp3"
RETENTION_DAYS=90

echo "$(date '+%Y-%m-%d %H:%M:%S') — Recording cleanup starting"
echo "Retention: ${RETENTION_DAYS} days"

# Delete old WAV files
WAV_COUNT=$(find "${RECORDINGS_DIR}" -name "*.wav" -type f -mtime +${RETENTION_DAYS} | wc -l)
find "${RECORDINGS_DIR}" -name "*.wav" -type f -mtime +${RETENTION_DAYS} -delete
echo "Deleted ${WAV_COUNT} WAV files older than ${RETENTION_DAYS} days"

# Delete old MP3 files
MP3_COUNT=$(find "${MP3_DIR}" -name "*.mp3" -type f -mtime +${RETENTION_DAYS} | wc -l)
find "${MP3_DIR}" -name "*.mp3" -type f -mtime +${RETENTION_DAYS} -delete
echo "Deleted ${MP3_COUNT} MP3 files older than ${RETENTION_DAYS} days"

# Clean empty directories
find "${RECORDINGS_DIR}" -type d -empty -delete 2>/dev/null
find "${MP3_DIR}" -type d -empty -delete 2>/dev/null

# Report disk usage
echo "Current recording storage:"
du -sh "${RECORDINGS_DIR}" "${MP3_DIR}" 2>/dev/null

echo "$(date '+%Y-%m-%d %H:%M:%S') — Cleanup complete"

chmod +x /usr/local/bin/cleanup-recordings.sh

# Run daily at 4 AM
echo "0 4 * * * root /usr/local/bin/cleanup-recordings.sh >> /var/log/recording-cleanup.log 2>&1" \
  > /etc/cron.d/recording-cleanup

9. Conference Bridge

Conference Profile Configuration

FreeSWITCH's mod_conference is carrier-grade — it can handle thousands of participants across hundreds of rooms. Configure profiles in /etc/freeswitch/autoload_configs/conference.conf.xml:

<configuration name="conference.conf" description="Audio Conference">
  <advertise>
    <!-- Advertise conference rooms via SIP SUBSCRIBE -->
    <room name="3001@$${domain}" status="FreeSWITCH"/>
  </advertise>

  <caller-controls>
    <!-- Default key bindings for participants -->
    <group name="default">
      <control action="mute" digits="0"/>
      <control action="deaf mute" digits="*"/>
      <control action="energy up" digits="9"/>
      <control action="energy equ" digits="8"/>
      <control action="energy dn" digits="7"/>
      <control action="vol talk up" digits="3"/>
      <control action="vol talk zero" digits="2"/>
      <control action="vol talk dn" digits="1"/>
      <control action="vol listen up" digits="6"/>
      <control action="vol listen zero" digits="5"/>
      <control action="vol listen dn" digits="4"/>
      <control action="hangup" digits="#"/>
    </group>

    <!-- Moderator key bindings -->
    <group name="moderator">
      <control action="mute" digits="0"/>
      <control action="deaf mute" digits="*"/>
      <control action="hangup" digits="#"/>
      <control action="lock" digits="*1"/>
      <control action="mute non_moderator" digits="*5"/>
      <control action="unmute non_moderator" digits="*6"/>
      <control action="kick last" digits="*7"/>
      <control action="transfer" digits="*9" data="1009 XML default"/>
    </group>
  </caller-controls>

  <profiles>
    <!-- Standard conference profile -->
    <profile name="default">
      <param name="domain" value="$${domain}"/>
      <param name="rate" value="16000"/>
      <param name="interval" value="20"/>
      <param name="energy-level" value="100"/>

      <!-- Comfort noise for silence -->
      <param name="comfort-noise" value="true"/>

      <!-- Sounds -->
      <param name="muted-sound" value="conference/conf-muted.wav"/>
      <param name="unmuted-sound" value="conference/conf-unmuted.wav"/>
      <param name="alone-sound" value="conference/conf-alone.wav"/>
      <param name="enter-sound" value="tone_stream://%(200,0,500,600,700)"/>
      <param name="exit-sound" value="tone_stream://%(500,0,300,200,100,50,25)"/>
      <param name="kicked-sound" value="conference/conf-kicked.wav"/>
      <param name="locked-sound" value="conference/conf-locked.wav"/>
      <param name="is-locked-sound" value="conference/conf-is-locked.wav"/>
      <param name="is-unlocked-sound" value="conference/conf-is-unlocked.wav"/>
      <param name="pin-sound" value="conference/conf-pin.wav"/>
      <param name="bad-pin-sound" value="conference/conf-bad-pin.wav"/>

      <!-- Controls -->
      <param name="caller-controls" value="default"/>
      <param name="moderator-controls" value="moderator"/>

      <!-- Auto-record all conferences -->
      <!-- <param name="auto-record"
        value="/var/lib/freeswitch/recordings/conference/${conference_name}_${strftime(%Y%m%d-%H%M%S)}.wav"/> -->

      <!-- Max members (0 = unlimited) -->
      <param name="max-members" value="100"/>
      <!-- Announce count of members when joining -->
      <param name="announce-count" value="5"/>

      <!-- Codec preferences -->
      <param name="conference-flags"
        value="wait-mod|audio-always|waste-bandwidth"/>
    </profile>

    <!-- PIN-protected conference profile -->
    <profile name="secure">
      <param name="domain" value="$${domain}"/>
      <param name="rate" value="16000"/>
      <param name="interval" value="20"/>
      <param name="energy-level" value="100"/>
      <param name="comfort-noise" value="true"/>

      <!-- PIN required -->
      <param name="pin" value="12345"/>
      <param name="pin-retries" value="3"/>
      <param name="pin-sound" value="conference/conf-pin.wav"/>
      <param name="bad-pin-sound" value="conference/conf-bad-pin.wav"/>

      <param name="enter-sound" value="tone_stream://%(200,0,500,600,700)"/>
      <param name="exit-sound" value="tone_stream://%(500,0,300,200,100,50,25)"/>
      <param name="caller-controls" value="default"/>
      <param name="moderator-controls" value="moderator"/>
      <param name="max-members" value="50"/>
      <param name="conference-flags" value="wait-mod|audio-always"/>
    </profile>

    <!-- Webinar profile: listeners muted by default -->
    <profile name="webinar">
      <param name="domain" value="$${domain}"/>
      <param name="rate" value="16000"/>
      <param name="interval" value="20"/>
      <param name="energy-level" value="100"/>
      <param name="comfort-noise" value="true"/>

      <param name="enter-sound" value="tone_stream://%(200,0,500,600,700)"/>
      <param name="exit-sound" value="tone_stream://%(500,0,300,200,100,50,25)"/>

      <param name="caller-controls" value="default"/>
      <param name="moderator-controls" value="moderator"/>
      <param name="max-members" value="500"/>

      <!-- Members join muted -->
      <param name="member-flags" value="mute"/>
      <param name="conference-flags" value="wait-mod|audio-always"/>

      <!-- Auto-record webinars -->
      <param name="auto-record"
        value="/var/lib/freeswitch/recordings/webinar/${conference_name}_${strftime(%Y%m%d-%H%M%S)}.wav"/>
    </profile>
  </profiles>
</configuration>

Dialplan for Conference Rooms

Add to your default context:

<!-- ============================================ -->
<!-- CONFERENCE ROOMS                             -->
<!-- ============================================ -->

<!-- Standard conference rooms: dial 3001-3099 -->
<extension name="conference_standard">
  <condition field="destination_number" expression="^(30[0-9]{2})$">
    <action application="answer"/>
    <action application="sleep" data="500"/>
    <action application="conference" data="room_$1@default"/>
  </condition>
</extension>

<!-- PIN-protected conference rooms: dial 3100-3199 -->
<extension name="conference_secure">
  <condition field="destination_number" expression="^(31[0-9]{2})$">
    <action application="answer"/>
    <action application="sleep" data="500"/>
    <action application="conference" data="room_$1@secure"/>
  </condition>
</extension>

<!-- Moderator entry: dial 3200 + room number (e.g., 32003001 for room 3001) -->
<extension name="conference_moderator">
  <condition field="destination_number" expression="^3200(30[0-9]{2})$">
    <action application="answer"/>
    <action application="sleep" data="500"/>
    <action application="set" data="conference_member_flags=moderator"/>
    <action application="conference" data="room_$1@default+flags{moderator}"/>
  </condition>
</extension>

<!-- Webinar rooms: dial 3300-3399 (listeners muted) -->
<extension name="conference_webinar">
  <condition field="destination_number" expression="^(33[0-9]{2})$">
    <action application="answer"/>
    <action application="sleep" data="500"/>
    <action application="conference" data="webinar_$1@webinar"/>
  </condition>
</extension>

<!-- Webinar presenter: dial 3400 + room number -->
<extension name="conference_webinar_presenter">
  <condition field="destination_number" expression="^3400(33[0-9]{2})$">
    <action application="answer"/>
    <action application="sleep" data="500"/>
    <action application="conference" data="webinar_$1@webinar+flags{moderator}"/>
  </condition>
</extension>

Dynamic PIN from Dialplan

Instead of hardcoding a PIN in the conference profile, set it per-room:

<extension name="conference_dynamic_pin">
  <condition field="destination_number" expression="^(35[0-9]{2})$">
    <action application="answer"/>
    <action application="sleep" data="500"/>
    <!-- Collect PIN from caller -->
    <action application="play_and_get_digits"
      data="4 6 3 10000 # conference/conf-pin.wav conference/conf-bad-pin.wav entered_pin \d{4,6} 10000"/>
    <!-- Verify PIN (in production, check against a database) -->
    <action application="set" data="expected_pin=7890"/>
    <action application="execute_extension"
      data="check_pin_${entered_pin} XML features"/>
    <!-- If we get here, PIN was correct -->
    <action application="conference" data="room_$1@default"/>
  </condition>
</extension>

Conference Management via fs_cli

# List active conferences
fs_cli -x "conference list"

# List members in a specific conference
fs_cli -x "conference room_3001 list"

# Mute a participant (by member ID)
fs_cli -x "conference room_3001 mute 3"

# Unmute a participant
fs_cli -x "conference room_3001 unmute 3"

# Kick a participant
fs_cli -x "conference room_3001 kick 3"

# Lock the conference (no new members)
fs_cli -x "conference room_3001 lock"

# Unlock
fs_cli -x "conference room_3001 unlock"

# Mute all non-moderators
fs_cli -x "conference room_3001 mute non_moderator"

# Start recording a conference
fs_cli -x "conference room_3001 record /var/lib/freeswitch/recordings/conference/room_3001_$(date +%Y%m%d).wav"

# Stop recording
fs_cli -x "conference room_3001 norecord all"

# Play a file into the conference
fs_cli -x "conference room_3001 play /var/lib/freeswitch/sounds/announcement.wav"

# Get conference count
fs_cli -x "conference room_3001 count"

Conference Events

FreeSWITCH fires events for all conference activity. These are available via ESL:

Event	When
`conference::maintenance`	Member join/leave/mute/unmute/kick
`conference::dtmf-member`	DTMF pressed by a member
`conference::start-talking`	Member starts speaking
`conference::stop-talking`	Member stops speaking

These events enable real-time dashboards, participant tracking, and integration with external management UIs.

10. Event Socket Layer (ESL)

What Is ESL?

The Event Socket Layer is a TCP socket interface that allows external applications to monitor and control FreeSWITCH in real time. It is the primary integration mechanism — far more powerful than Asterisk's AMI because it is fully bidirectional and event-driven.

ESL operates in two modes:

Mode	Direction	Use Case
Inbound	App connects to FreeSWITCH (port 8021)	Monitoring, call control, management
Outbound	FreeSWITCH connects to your app	Per-call IVR logic, call routing decisions

ESL Configuration

The ESL listener is configured in /etc/freeswitch/autoload_configs/event_socket.conf.xml:

<configuration name="event_socket.conf" description="Socket Client">
  <settings>
    <!-- Listen on localhost only (secure) -->
    <param name="listen-ip" value="127.0.0.1"/>
    <param name="listen-port" value="8021"/>
    <param name="password" value="YOUR_SECURE_ESL_PASSWORD"/>

    <!-- Optional: allow connections from specific IPs -->
    <!--<param name="listen-ip" value="0.0.0.0"/>-->
    <!--<param name="apply-inbound-acl" value="loopback.auto"/>-->
  </settings>
</configuration>

fs_cli as ESL Client

fs_cli is itself an ESL client. Everything you type in fs_cli goes through ESL:

# Connect to local FreeSWITCH
fs_cli

# Connect to remote FreeSWITCH
fs_cli -H 10.0.0.5 -P 8021 -p YOUR_SECURE_ESL_PASSWORD

# Execute a single command and exit
fs_cli -x "sofia status"

# Execute API command
fs_cli -x "show channels"

# Execute background API command
fs_cli -x "bgapi originate user/1001 &echo()"

Common ESL Commands

Command	Description
`api status`	System status
`api sofia status`	SIP profile status
`api sofia status profile internal reg`	Show registered phones
`api show channels`	Active call channels
`api show calls`	Active calls with details
`api conference list`	Active conferences
`api originate <endpoint> <app>`	Place a new call
`api uuid_bridge <uuid1> <uuid2>`	Bridge two existing calls
`api uuid_kill <uuid>`	Hang up a call
`api uuid_transfer <uuid> <dest>`	Transfer a call
`api uuid_record <uuid> start <file>`	Start recording
`api uuid_setvar <uuid> <var> <val>`	Set channel variable
`api uuid_getvar <uuid> <var>`	Get channel variable
`bgapi originate ...`	Background API (non-blocking)
`event plain ALL`	Subscribe to all events
`event plain CHANNEL_CREATE CHANNEL_HANGUP`	Subscribe to specific events
`filter Event-Name CHANNEL_ANSWER`	Filter subscribed events

Python ESL: Inbound Mode

The greenswitch library provides a clean Python ESL client. Install it:

pip3 install greenswitch

Basic monitoring application:

#!/usr/bin/env python3
"""
freeswitch_monitor.py
Monitor FreeSWITCH events via ESL (inbound mode).
Logs call activity and tracks concurrent calls.
"""

import greenswitch
import json
from datetime import datetime


class FreeSWITCHMonitor:
    def __init__(self, host='127.0.0.1', port=8021, password='YOUR_SECURE_ESL_PASSWORD'):
        self.host = host
        self.port = port
        self.password = password
        self.active_calls = {}
        self.conn = None

    def connect(self):
        """Establish ESL connection."""
        self.conn = greenswitch.InboundESL(
            host=self.host,
            port=self.port,
            password=self.password
        )
        self.conn.connect()
        print(f"[{self._now()}] Connected to FreeSWITCH at {self.host}:{self.port}")

    def subscribe_events(self):
        """Subscribe to call-related events."""
        # Subscribe to specific events
        self.conn.send(
            'event plain CHANNEL_CREATE CHANNEL_ANSWER '
            'CHANNEL_HANGUP_COMPLETE DTMF CODEC'
        )

        # Register event handlers
        self.conn.register_handle('CHANNEL_CREATE', self._on_channel_create)
        self.conn.register_handle('CHANNEL_ANSWER', self._on_channel_answer)
        self.conn.register_handle('CHANNEL_HANGUP_COMPLETE', self._on_channel_hangup)
        self.conn.register_handle('DTMF', self._on_dtmf)

    def _on_channel_create(self, event):
        """Called when a new channel is created."""
        uuid = event.headers.get('Unique-ID', 'unknown')
        caller = event.headers.get('Caller-Caller-ID-Number', 'unknown')
        dest = event.headers.get('Caller-Destination-Number', 'unknown')
        direction = event.headers.get('Call-Direction', 'unknown')

        self.active_calls[uuid] = {
            'caller': caller,
            'destination': dest,
            'direction': direction,
            'created': datetime.now(),
            'state': 'ringing'
        }
        print(f"[{self._now()}] NEW CALL: {caller} -> {dest} ({direction}) UUID={uuid}")
        print(f"  Active calls: {len(self.active_calls)}")

    def _on_channel_answer(self, event):
        """Called when a channel is answered."""
        uuid = event.headers.get('Unique-ID', 'unknown')
        if uuid in self.active_calls:
            self.active_calls[uuid]['state'] = 'answered'
            caller = self.active_calls[uuid]['caller']
            dest = self.active_calls[uuid]['destination']
            print(f"[{self._now()}] ANSWERED: {caller} -> {dest} UUID={uuid}")

    def _on_channel_hangup(self, event):
        """Called when a channel hangs up."""
        uuid = event.headers.get('Unique-ID', 'unknown')
        cause = event.headers.get('Hangup-Cause', 'unknown')
        duration = event.headers.get('variable_billsec', '0')

        if uuid in self.active_calls:
            call = self.active_calls.pop(uuid)
            print(
                f"[{self._now()}] HANGUP: {call['caller']} -> {call['destination']} "
                f"Duration={duration}s Cause={cause} UUID={uuid}"
            )
            print(f"  Active calls: {len(self.active_calls)}")

    def _on_dtmf(self, event):
        """Called when DTMF is received."""
        uuid = event.headers.get('Unique-ID', 'unknown')
        digit = event.headers.get('DTMF-Digit', '?')
        print(f"[{self._now()}] DTMF: digit={digit} UUID={uuid}")

    def run_api(self, command):
        """Execute an API command and return the result."""
        result = self.conn.send(f'api {command}')
        return result.data if result else None

    def originate_call(self, endpoint, app='&park()'):
        """Place a new call."""
        cmd = f'api originate {endpoint} {app}'
        result = self.conn.send(cmd)
        print(f"[{self._now()}] Originate result: {result.data if result else 'failed'}")
        return result

    def _now(self):
        return datetime.now().strftime('%Y-%m-%d %H:%M:%S')

    def run(self):
        """Main event loop."""
        self.connect()
        self.subscribe_events()
        print(f"[{self._now()}] Listening for events... (Ctrl+C to stop)")

        # Get initial status
        status = self.run_api('status')
        if status:
            print(f"\n--- FreeSWITCH Status ---\n{status}\n")

        try:
            # This blocks and processes events
            self.conn.process_events()
        except KeyboardInterrupt:
            print(f"\n[{self._now()}] Shutting down...")


if __name__ == '__main__':
    monitor = FreeSWITCHMonitor(
        host='127.0.0.1',
        port=8021,
        password='YOUR_SECURE_ESL_PASSWORD'
    )
    monitor.run()

Run the monitor:

python3 freeswitch_monitor.py

Python ESL: Call Control Application

A more advanced example — an automated call queue:

#!/usr/bin/env python3
"""
call_queue.py
Simple call queue: callers hear hold music, agents dial in to take the next call.
Uses ESL inbound mode.
"""

import greenswitch
from collections import deque
from datetime import datetime
import threading


class CallQueue:
    def __init__(self, host='127.0.0.1', port=8021, password='YOUR_SECURE_ESL_PASSWORD'):
        self.conn = greenswitch.InboundESL(host=host, port=port, password=password)
        self.waiting_callers = deque()  # Queue of caller UUIDs
        self.available_agents = []       # List of agent UUIDs
        self.lock = threading.Lock()

    def connect(self):
        self.conn.connect()
        self.conn.send('event plain CHANNEL_ANSWER CHANNEL_HANGUP_COMPLETE')
        print(f"[{self._now()}] Queue system connected")

    def add_caller(self, uuid):
        """Add a caller to the queue and play hold music."""
        with self.lock:
            self.waiting_callers.append(uuid)
            # Play music on hold to the caller
            self.conn.send(
                f'api uuid_broadcast {uuid} '
                f'local_stream://moh both'
            )
            print(f"[{self._now()}] Caller {uuid} added to queue. "
                  f"Queue depth: {len(self.waiting_callers)}")
            self._try_connect()

    def add_agent(self, uuid):
        """Register an agent as available."""
        with self.lock:
            self.available_agents.append(uuid)
            print(f"[{self._now()}] Agent {uuid} available. "
                  f"Agents: {len(self.available_agents)}")
            self._try_connect()

    def _try_connect(self):
        """Try to bridge a waiting caller with an available agent."""
        if self.waiting_callers and self.available_agents:
            caller_uuid = self.waiting_callers.popleft()
            agent_uuid = self.available_agents.pop(0)

            # Bridge the two calls
            self.conn.send(
                f'api uuid_bridge {caller_uuid} {agent_uuid}'
            )
            print(
                f"[{self._now()}] CONNECTED: caller={caller_uuid} "
                f"agent={agent_uuid}"
            )

    def get_stats(self):
        """Return current queue statistics."""
        with self.lock:
            return {
                'waiting_callers': len(self.waiting_callers),
                'available_agents': len(self.available_agents),
                'timestamp': self._now()
            }

    def _now(self):
        return datetime.now().strftime('%Y-%m-%d %H:%M:%S')


if __name__ == '__main__':
    queue = CallQueue()
    queue.connect()
    # In production, callers and agents would be added via
    # dialplan outbound ESL or API calls
    print("Queue system running. Use ESL commands to add callers/agents.")

Node.js ESL Example

For Node.js applications, use the modesl library:

npm install modesl

// freeswitch_monitor.js
// FreeSWITCH event monitor using Node.js + modesl

const esl = require('modesl');

const connection = new esl.Connection('127.0.0.1', 8021, 'YOUR_SECURE_ESL_PASSWORD', () => {
    console.log(`[${timestamp()}] Connected to FreeSWITCH via ESL`);

    // Get initial status
    connection.api('status', (result) => {
        console.log(`\n--- FreeSWITCH Status ---\n${result.getBody()}\n`);
    });

    // Subscribe to events
    connection.subscribe([
        'CHANNEL_CREATE',
        'CHANNEL_ANSWER',
        'CHANNEL_HANGUP_COMPLETE'
    ], () => {
        console.log(`[${timestamp()}] Subscribed to call events`);
    });
});

// Track active calls
const activeCalls = new Map();

connection.on('esl::event::CHANNEL_CREATE::*', (event) => {
    const uuid = event.getHeader('Unique-ID');
    const caller = event.getHeader('Caller-Caller-ID-Number') || 'unknown';
    const dest = event.getHeader('Caller-Destination-Number') || 'unknown';
    const direction = event.getHeader('Call-Direction') || 'unknown';

    activeCalls.set(uuid, { caller, dest, direction, created: new Date() });
    console.log(`[${timestamp()}] NEW: ${caller} -> ${dest} (${direction}) [${activeCalls.size} active]`);
});

connection.on('esl::event::CHANNEL_ANSWER::*', (event) => {
    const uuid = event.getHeader('Unique-ID');
    const call = activeCalls.get(uuid);
    if (call) {
        console.log(`[${timestamp()}] ANSWER: ${call.caller} -> ${call.dest}`);
    }
});

connection.on('esl::event::CHANNEL_HANGUP_COMPLETE::*', (event) => {
    const uuid = event.getHeader('Unique-ID');
    const cause = event.getHeader('Hangup-Cause') || 'unknown';
    const duration = event.getHeader('variable_billsec') || '0';
    const call = activeCalls.get(uuid);

    if (call) {
        activeCalls.delete(uuid);
        console.log(
            `[${timestamp()}] HANGUP: ${call.caller} -> ${call.dest} ` +
            `Duration=${duration}s Cause=${cause} [${activeCalls.size} active]`
        );
    }
});

connection.on('error', (error) => {
    console.error(`[${timestamp()}] ESL Error:`, error);
});

function timestamp() {
    return new Date().toISOString().replace('T', ' ').substring(0, 19);
}

// Originate a call example (uncomment to use):
// connection.api('originate user/1001 &echo()', (result) => {
//     console.log('Originate result:', result.getBody());
// });

node freeswitch_monitor.js

ESL Outbound Mode

In outbound mode, FreeSWITCH connects to YOUR application for each call. This is ideal for complex call routing or IVR logic where you want full programmatic control.

Dialplan configuration — route calls to your application:

<extension name="esl_controlled_ivr">
  <condition field="destination_number" expression="^(7000)$">
    <action application="socket" data="127.0.0.1:9090 async full"/>
  </condition>
</extension>

Python outbound ESL server:

#!/usr/bin/env python3
"""
outbound_ivr.py
Simple outbound ESL IVR server.
FreeSWITCH connects to this app for call handling.
"""

import socket
import threading


def handle_call(client_socket, addr):
    """Handle one incoming ESL connection (one call)."""
    print(f"New call connection from {addr}")

    # Read the initial connect message
    data = client_socket.recv(65536).decode()

    # Send connect command
    client_socket.sendall(b'connect\n\n')
    data = client_socket.recv(65536).decode()

    # Parse caller info from headers
    headers = {}
    for line in data.split('\n'):
        if ':' in line:
            key, value = line.split(':', 1)
            headers[key.strip()] = value.strip()

    caller = headers.get('Caller-Caller-ID-Number', 'unknown')
    dest = headers.get('Caller-Destination-Number', 'unknown')
    uuid = headers.get('Unique-ID', 'unknown')

    print(f"Call from {caller} to {dest} (UUID: {uuid})")

    # Answer the call
    send_command(client_socket, 'answer')

    # Play a greeting
    send_command(client_socket, 'playback /var/lib/freeswitch/sounds/ivr/ivr-welcome.wav')

    # Collect digits
    send_command(
        client_socket,
        'play_and_get_digits 1 1 3 10000 # '
        '/var/lib/freeswitch/sounds/ivr/ivr-please_make_selection.wav '
        '/var/lib/freeswitch/sounds/ivr/ivr-that_was_an_invalid_entry.wav '
        'selection \\d 10000'
    )

    # Read the response to get the collected digit
    # (In production, parse CHANNEL_EXECUTE_COMPLETE events)

    # Transfer based on selection
    send_command(client_socket, 'transfer 1001 XML default')

    client_socket.close()


def send_command(sock, command):
    """Send an ESL command."""
    msg = f'sendmsg\ncall-command: execute\nexecute-app-name: {command}\n\n'
    sock.sendall(msg.encode())
    # Read response
    try:
        return sock.recv(65536).decode()
    except Exception:
        return ''


def main():
    server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
    server.bind(('127.0.0.1', 9090))
    server.listen(50)
    print("Outbound ESL server listening on 127.0.0.1:9090")

    while True:
        client, addr = server.accept()
        thread = threading.Thread(target=handle_call, args=(client, addr))
        thread.daemon = True
        thread.start()


if __name__ == '__main__':
    main()

11. CDR & Logging

CDR with mod_cdr_csv

The simplest CDR method — writes call records to CSV files. Configure in /etc/freeswitch/autoload_configs/cdr_csv.conf.xml:

<configuration name="cdr_csv.conf" description="CDR CSV Format">
  <settings>
    <!-- Master CSV file for all calls -->
    <param name="default-template" value="default"/>

    <!-- Rotate log file when it reaches this size (bytes) -->
    <param name="rotate-on-hup" value="true"/>

    <!-- Legs: a-leg only, b-leg only, or both -->
    <param name="legs" value="a"/>
  </settings>

  <templates>
    <!-- Default template — one line per call -->
    <template name="default">"${caller_id_name}","${caller_id_number}","${destination_number}","${context}","${start_stamp}","${answer_stamp}","${end_stamp}","${duration}","${billsec}","${hangup_cause}","${uuid}","${accountcode}","${read_codec}","${write_codec}","${sip_hangup_disposition}","${sip_from_uri}","${sip_to_uri}"</template>

    <!-- Detailed template with more fields -->
    <template name="detailed">"${caller_id_name}","${caller_id_number}","${destination_number}","${context}","${start_stamp}","${answer_stamp}","${end_stamp}","${progress_stamp}","${progress_media_stamp}","${duration}","${billsec}","${hangup_cause}","${uuid}","${bleg_uuid}","${accountcode}","${read_codec}","${write_codec}","${sip_hangup_disposition}","${endpoint_disposition}","${sip_from_uri}","${sip_to_uri}","${sip_call_id}","${network_addr}","${bridge_channel}","${last_app}","${last_arg}"</template>
  </templates>
</configuration>

CDR CSV files are written to /var/log/freeswitch/cdr-csv/.

CDR with mod_cdr_sqlite

For queryable CDR data, use SQLite. Configure in /etc/freeswitch/autoload_configs/cdr_sqlite.conf.xml:

<configuration name="cdr_sqlite.conf" description="CDR SQLite">
  <settings>
    <param name="db-name" value="cdr"/>
    <param name="db-table" value="cdr"/>
    <param name="legs" value="a"/>
    <param name="default-template" value="default"/>
  </settings>

  <templates>
    <template name="default">
      INSERT INTO cdr (
        caller_id_name, caller_id_number, destination_number, context,
        start_stamp, answer_stamp, end_stamp, duration, billsec,
        hangup_cause, uuid, accountcode, read_codec, write_codec,
        sip_hangup_disposition, network_addr
      ) VALUES (
        '${caller_id_name}', '${caller_id_number}', '${destination_number}',
        '${context}', '${start_stamp}', '${answer_stamp}', '${end_stamp}',
        '${duration}', '${billsec}', '${hangup_cause}', '${uuid}',
        '${accountcode}', '${read_codec}', '${write_codec}',
        '${sip_hangup_disposition}', '${network_addr}'
      );
    </template>
  </templates>
</configuration>

The SQLite database is created at /var/lib/freeswitch/db/cdr.db. Query it:

sqlite3 /var/lib/freeswitch/db/cdr.db

-- Show recent calls
SELECT caller_id_number, destination_number, duration, hangup_cause, start_stamp
FROM cdr
ORDER BY start_stamp DESC
LIMIT 20;

-- Call volume by hour
SELECT strftime('%H', start_stamp) AS hour, COUNT(*) AS calls
FROM cdr
WHERE date(start_stamp) = date('now')
GROUP BY hour
ORDER BY hour;

-- Average call duration by destination
SELECT destination_number,
       COUNT(*) AS calls,
       AVG(billsec) AS avg_duration,
       SUM(billsec) AS total_seconds
FROM cdr
WHERE billsec > 0
GROUP BY destination_number
ORDER BY calls DESC;

CDR with mod_cdr_pg (PostgreSQL)

For production systems, PostgreSQL is the best CDR backend. Configure in /etc/freeswitch/autoload_configs/cdr_pg.conf.xml:

<configuration name="cdr_pg.conf" description="CDR PostgreSQL">
  <settings>
    <param name="host" value="127.0.0.1"/>
    <param name="port" value="5432"/>
    <param name="dbname" value="freeswitch_cdr"/>
    <param name="user" value="freeswitch"/>
    <param name="password" value="YOUR_DB_PASSWORD"/>
    <param name="legs" value="a"/>
    <param name="default-template" value="default"/>
    <!-- Log errors to file if DB is unavailable -->
    <param name="spool-format" value="csv"/>
    <param name="log-dir" value="/var/log/freeswitch/cdr-pg-errors"/>
  </settings>

  <templates>
    <template name="default">
      INSERT INTO cdr (
        caller_id_name, caller_id_number, destination_number, context,
        start_stamp, answer_stamp, end_stamp, duration, billsec,
        hangup_cause, uuid, accountcode, read_codec, write_codec,
        sip_hangup_disposition, network_addr
      ) VALUES (
        '${caller_id_name}', '${caller_id_number}', '${destination_number}',
        '${context}',
        to_timestamp(${start_epoch}), to_timestamp(${answer_epoch}),
        to_timestamp(${end_epoch}),
        ${duration}, ${billsec}, '${hangup_cause}', '${uuid}',
        '${accountcode}', '${read_codec}', '${write_codec}',
        '${sip_hangup_disposition}', '${network_addr}'
      );
    </template>
  </templates>
</configuration>

Create the database and table:

-- Run as PostgreSQL superuser
CREATE DATABASE freeswitch_cdr;
CREATE USER freeswitch WITH PASSWORD 'YOUR_DB_PASSWORD';
GRANT ALL PRIVILEGES ON DATABASE freeswitch_cdr TO freeswitch;

\c freeswitch_cdr

CREATE TABLE cdr (
    id              SERIAL PRIMARY KEY,
    caller_id_name  VARCHAR(128),
    caller_id_number VARCHAR(64),
    destination_number VARCHAR(64),
    context         VARCHAR(64),
    start_stamp     TIMESTAMP,
    answer_stamp    TIMESTAMP,
    end_stamp       TIMESTAMP,
    duration        INTEGER,
    billsec         INTEGER,
    hangup_cause    VARCHAR(64),
    uuid            VARCHAR(64) UNIQUE,
    accountcode     VARCHAR(32),
    read_codec      VARCHAR(32),
    write_codec     VARCHAR(32),
    sip_hangup_disposition VARCHAR(32),
    network_addr    VARCHAR(64),
    created_at      TIMESTAMP DEFAULT NOW()
);

-- Index for common queries
CREATE INDEX idx_cdr_start_stamp ON cdr (start_stamp);
CREATE INDEX idx_cdr_caller ON cdr (caller_id_number);
CREATE INDEX idx_cdr_destination ON cdr (destination_number);
CREATE INDEX idx_cdr_accountcode ON cdr (accountcode);

GRANT ALL ON cdr TO freeswitch;
GRANT USAGE, SELECT ON SEQUENCE cdr_id_seq TO freeswitch;

CDR Fields Reference

Field	Description
`caller_id_name`	Name of the calling party
`caller_id_number`	Phone number of the calling party
`destination_number`	Dialed number
`context`	Dialplan context (default, public, etc.)
`start_stamp` / `start_epoch`	When the call started
`answer_stamp` / `answer_epoch`	When the call was answered (NULL if not answered)
`end_stamp` / `end_epoch`	When the call ended
`duration`	Total time in seconds (ring + talk)
`billsec`	Talk time in seconds (answer to hangup)
`hangup_cause`	SIP/Q.931 hangup reason
`uuid`	Unique call identifier
`accountcode`	Account code for billing
`read_codec` / `write_codec`	Audio codecs used
`sip_hangup_disposition`	Who hung up: `send_bye`, `recv_bye`, `send_cancel`, `recv_cancel`
`network_addr`	Source IP address

Log Configuration

FreeSWITCH logging is configured in /etc/freeswitch/autoload_configs/logfile.conf.xml:

<configuration name="logfile.conf" description="File Logging">
  <settings>
    <param name="rotate-on-hup" value="true"/>
  </settings>

  <profiles>
    <profile name="default">
      <settings>
        <param name="logfile" value="/var/log/freeswitch/freeswitch.log"/>

        <!-- Rotate every 10MB -->
        <param name="rollover" value="10485760"/>

        <!-- Log level: DEBUG, INFO, NOTICE, WARNING, ERR, CRIT, ALERT -->
        <param name="log-event" value="false"/>
      </settings>

      <mappings>
        <!-- What to log — set level per module -->
        <map name="all" value="info,warning,err,crit,alert"/>

        <!-- Enable debug for specific modules when troubleshooting -->
        <!-- <map name="mod_sofia" value="debug,info,warning,err"/> -->
        <!-- <map name="mod_dptools" value="debug,info,warning,err"/> -->
      </mappings>
    </profile>
  </profiles>
</configuration>

SIP Trace Logging

For SIP debugging, enable trace on a specific profile:

# Enable SIP trace (shows all SIP messages in fs_cli)
fs_cli -x "sofia profile internal siptrace on"

# Disable
fs_cli -x "sofia profile internal siptrace off"

# Enable on external profile
fs_cli -x "sofia profile external siptrace on"

# Save SIP trace to a PCAP file
fs_cli -x "sofia profile internal capture on"
# File saved to /tmp/ by default
fs_cli -x "sofia profile internal capture off"

Log Rotation

Set up logrotate to manage FreeSWITCH logs:

cat > /etc/logrotate.d/freeswitch << 'EOF'
/var/log/freeswitch/freeswitch.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    postrotate
        /usr/bin/fs_cli -x "fsctl send_sighup" > /dev/null 2>&1 || true
    endscript
}

/var/log/freeswitch/cdr-csv/*.csv {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    create 640 freeswitch freeswitch
}
EOF

12. Security Hardening

Change All Default Passwords

This was covered in Section 3, but it bears repeating. The three most critical defaults:

# 1. Extension passwords (vars.xml — default_password)
# Change from "1234" to something strong
# Then set individual passwords per extension in directory/*.xml

# 2. ESL password (event_socket.conf.xml)
# Change from "ClueCon"

# 3. Voicemail PINs (each user's vm-password)
# Change from extension number

SIP Profile ACLs

Restrict which IPs can register to each profile. Edit the profile XML:

<!-- In sip_profiles/internal.xml -->
<param name="apply-register-acl" value="trusted_networks"/>
<param name="apply-inbound-acl" value="trusted_networks"/>

Define the ACL in /etc/freeswitch/autoload_configs/acl.conf.xml:

<configuration name="acl.conf" description="Network Lists">
  <network-lists>
    <!-- Trusted networks for SIP registration -->
    <list name="trusted_networks" default="deny">
      <!-- Office network -->
      <node type="allow" cidr="10.0.0.0/8"/>
      <!-- VPN range -->
      <node type="allow" cidr="172.16.0.0/12"/>
      <!-- Specific remote office -->
      <node type="allow" cidr="203.0.113.50/32"/>
      <!-- Localhost -->
      <node type="allow" cidr="127.0.0.0/8"/>
    </list>

    <!-- SIP trunk provider IPs -->
    <list name="trunk_providers" default="deny">
      <node type="allow" cidr="198.51.100.0/24"/>
      <node type="allow" cidr="203.0.113.100/32"/>
    </list>

    <!-- ESL access -->
    <list name="esl_access" default="deny">
      <node type="allow" cidr="127.0.0.1/32"/>
      <node type="allow" cidr="10.0.0.0/8"/>
    </list>
  </network-lists>
</configuration>

fail2ban for FreeSWITCH

Install and configure fail2ban to block brute-force SIP attacks:

apt-get install -y fail2ban

Create the FreeSWITCH filter at /etc/fail2ban/filter.d/freeswitch.conf:

# /etc/fail2ban/filter.d/freeswitch.conf
[INCLUDES]
before = common.conf

[Definition]
failregex = ^\s*\[WARNING\] sofia_reg\.c:\d+ SIP Registration Failed: IP=<HOST>.*$
            ^\s*\[WARNING\] sofia_reg\.c:\d+.*auth challenge.*<HOST>.*$
            ^\s*\[WARNING\].*REGISTER.*from.*<HOST>.*forbidden.*$
            ^\s*\[WARNING\].*Authentication\s+Failed.*<HOST>.*$

ignoreregex =

Create the jail at /etc/fail2ban/jail.d/freeswitch.conf:

# /etc/fail2ban/jail.d/freeswitch.conf
[freeswitch]
enabled  = true
filter   = freeswitch
logpath  = /var/log/freeswitch/freeswitch.log
maxretry = 5
findtime = 300
bantime  = 3600
action   = iptables-allports[name=freeswitch, protocol=all]

systemctl enable fail2ban
systemctl restart fail2ban

# Check status
fail2ban-client status freeswitch

TLS for SIP (SIPS)

Encrypt SIP signaling with TLS:

# Generate a self-signed certificate (or use Let's Encrypt)
mkdir -p /etc/freeswitch/tls

openssl req -x509 -nodes -days 3650 \
  -newkey rsa:2048 \
  -keyout /etc/freeswitch/tls/agent.pem \
  -out /etc/freeswitch/tls/agent.pem \
  -subj "/CN=YOUR_DOMAIN"

# Combine into the format FreeSWITCH expects
cp /etc/freeswitch/tls/agent.pem /etc/freeswitch/tls/cafile.pem
chown freeswitch:freeswitch /etc/freeswitch/tls/*.pem
chmod 640 /etc/freeswitch/tls/*.pem

Enable TLS in the internal profile:

<!-- In sip_profiles/internal.xml, add these parameters -->
<param name="tls" value="true"/>
<param name="tls-bind-params" value="transport=tls"/>
<param name="tls-sip-port" value="5061"/>
<param name="tls-cert-dir" value="/etc/freeswitch/tls"/>
<param name="tls-version" value="tlsv1.2"/>

SRTP (Encrypted Media)

After enabling TLS for signaling, enable SRTP for media encryption:

<!-- In sip_profiles/internal.xml -->
<param name="inbound-codec-string" value="OPUS,G722,PCMU,PCMA"/>
<param name="outbound-codec-string" value="OPUS,G722,PCMU,PCMA"/>

<!-- Require SRTP -->
<!-- Options: mandatory, optional, forbidden -->
<param name="rtp_secure_media" value="optional"/>

Per-user SRTP enforcement in the directory:

<!-- In directory/default/1001.xml -->
<user id="1001">
  <params>
    <param name="password" value="Str0ng_P@ss!"/>
  </params>
  <variables>
    <!-- Force SRTP for this user -->
    <variable name="rtp_secure_media" value="mandatory"/>
    <!-- ... other variables ... -->
  </variables>
</user>

Rate Limiting

Protect against SIP floods by limiting registrations and call attempts:

<!-- In sip_profiles/internal.xml -->

<!-- Max registrations per second -->
<param name="accept-blind-reg" value="false"/>

<!-- Challenge all registrations (prevents spoofing) -->
<param name="auth-all-packets" value="true"/>
<param name="auth-calls" value="true"/>

<!-- Limit concurrent calls -->
<!-- In vars.xml -->
<!-- <X-PRE-PROCESS cmd="set" data="max_sessions=500"/> -->
<!-- <X-PRE-PROCESS cmd="set" data="sessions_per_second=50"/> -->

Set global limits in fs_cli:

# Set max concurrent sessions
fs_cli -x "fsctl max_sessions 500"

# Set max sessions per second
fs_cli -x "fsctl sps 50"

Firewall Best Practices Summary

# Minimal firewall rules for production FreeSWITCH

# Flush existing rules (careful!)
# iptables -F

# Default deny
iptables -P INPUT DROP
iptables -P FORWARD DROP
iptables -P OUTPUT ACCEPT

# Allow established connections
iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT

# Loopback
iptables -A INPUT -i lo -j ACCEPT

# SSH (your management IP only)
iptables -A INPUT -p tcp -s YOUR_MGMT_IP --dport 22 -j ACCEPT

# SIP from trusted networks only
iptables -A INPUT -p udp -s 10.0.0.0/8 --dport 5060 -j ACCEPT
iptables -A INPUT -p tcp -s 10.0.0.0/8 --dport 5060 -j ACCEPT

# SIP TLS
iptables -A INPUT -p tcp -s 10.0.0.0/8 --dport 5061 -j ACCEPT

# SIP from trunk providers (by IP)
iptables -A INPUT -p udp -s PROVIDER_IP_1 --dport 5080 -j ACCEPT
iptables -A INPUT -p udp -s PROVIDER_IP_2 --dport 5080 -j ACCEPT

# RTP media (must be open — media comes from many IPs)
iptables -A INPUT -p udp --dport 16384:32768 -j ACCEPT

# ESL (localhost only)
iptables -A INPUT -p tcp -s 127.0.0.1 --dport 8021 -j ACCEPT

# Save rules
iptables-save > /etc/iptables/rules.v4

13. Integration Patterns

FreeSWITCH + Kamailio (SBC / Load Balancer)

Kamailio handles SIP routing, load balancing, and security at the edge. FreeSWITCH handles media processing behind it. This is the standard carrier-grade architecture.

Internet                Kamailio (SBC)           FreeSWITCH (Media)
   │                        │                         │
   │  SIP INVITE            │                         │
   ├───────────────────────►│                         │
   │                        │  Rate limit, ACL check  │
   │                        │  Route to FS            │
   │                        ├────────────────────────►│
   │                        │                         │ Answer, IVR, Bridge
   │  RTP (media)           │                         │
   ├──────────────────────────────────────────────────►│
   │                        │                         │

Kamailio configuration snippet (routes SIP to FreeSWITCH):

# kamailio.cfg (simplified)
# Route SIP to FreeSWITCH backend

request_route {
    # Security checks
    if (!mf_process_maxfwd_header("10")) {
        sl_send_reply("483", "Too Many Hops");
        exit;
    }

    # Rate limiting
    if (!pike_check_req()) {
        sl_send_reply("503", "Service Unavailable");
        exit;
    }

    # Route INVITEs to FreeSWITCH
    if (is_method("INVITE")) {
        # Set destination to FreeSWITCH
        $du = "sip:FREESWITCH_IP:5060";
        route(RELAY);
    }

    # Route REGISTERs to FreeSWITCH
    if (is_method("REGISTER")) {
        $du = "sip:FREESWITCH_IP:5060";
        route(RELAY);
    }
}

route[RELAY] {
    if (!t_relay()) {
        sl_reply_error();
    }
}

FreeSWITCH configuration — trust Kamailio's IP:

<!-- In acl.conf.xml -->
<list name="kamailio" default="deny">
  <node type="allow" cidr="KAMAILIO_IP/32"/>
</list>

<!-- In sip_profiles/internal.xml -->
<param name="apply-inbound-acl" value="kamailio"/>
<param name="auth-calls" value="false"/>
<!-- Trust X-headers from Kamailio for routing decisions -->
<param name="apply-proxy-acl" value="kamailio"/>

FreeSWITCH + WebRTC (mod_verto)

mod_verto provides native WebRTC support without any external proxy. It uses WebSocket for signaling and handles SRTP/DTLS for media.

Enable mod_verto in /etc/freeswitch/autoload_configs/modules.conf.xml:

<load module="mod_verto"/>

Configure mod_verto in /etc/freeswitch/autoload_configs/verto.conf.xml:

<configuration name="verto.conf" description="WebRTC Verto Endpoint">
  <settings>
    <param name="debug" value="0"/>
  </settings>

  <profiles>
    <profile name="default-v4">
      <param name="bind-local" value="YOUR_SERVER_IP:8081"/>
      <param name="bind-local" value="YOUR_SERVER_IP:8082" secure="true"/>
      <param name="force-register-domain" value="$${domain}"/>
      <param name="secure-combined" value="/etc/freeswitch/tls/agent.pem"/>
      <param name="secure-chain" value="/etc/freeswitch/tls/cafile.pem"/>
      <param name="userauth" value="true"/>
      <param name="context" value="default"/>
      <param name="dialplan" value="XML"/>

      <!-- STUN/TURN for NAT traversal -->
      <param name="rtp-ip" value="$${local_ip_v4}"/>
      <param name="ext-rtp-ip" value="$${external_rtp_ip}"/>

      <!-- Timer -->
      <param name="timer-name" value="soft"/>
    </profile>
  </profiles>
</configuration>

Browser-side JavaScript (using verto.js):

<!DOCTYPE html>
<html>
<head>
    <title>WebRTC Phone</title>
    <script src="https://cdn.jsdelivr.net/npm/jquery@3/dist/jquery.min.js"></script>
    <script src="verto-min.js"></script>
</head>
<body>
    <h2>WebRTC Phone</h2>
    <div>
        <input type="text" id="number" placeholder="Enter number to call"/>
        <button onclick="makeCall()">Call</button>
        <button onclick="hangupCall()">Hangup</button>
    </div>
    <div id="status">Disconnected</div>
    <audio id="remoteAudio" autoplay></audio>

    <script>
    var verto;
    var currentCall = null;

    // Connect to FreeSWITCH via Verto
    $(document).ready(function() {
        verto = new $.verto({
            login: '1001@YOUR_SERVER_IP',
            passwd: 'YOUR_EXTENSION_PASSWORD',
            socketUrl: 'wss://YOUR_SERVER_IP:8082',
            // ICE servers for NAT traversal
            iceServers: [
                { urls: 'stun:stun.l.google.com:19302' }
            ],
            deviceParams: {
                useMic: true,
                useSpeak: true
            },
            audioParams: {
                googAutoGainControl: true,
                googNoiseSuppression: true,
                googEchoCancellation: true
            }
        }, {
            onWSLogin: function(v, success) {
                $('#status').text(success ? 'Connected' : 'Login Failed');
            },
            onDialogState: function(d) {
                switch (d.state.name) {
                    case 'trying':
                        $('#status').text('Calling...');
                        break;
                    case 'ringing':
                        $('#status').text('Ringing...');
                        break;
                    case 'active':
                        $('#status').text('In Call');
                        break;
                    case 'hangup':
                    case 'destroy':
                        $('#status').text('Call Ended');
                        currentCall = null;
                        break;
                }
            }
        });
    });

    function makeCall() {
        var number = $('#number').val();
        if (!number) return;

        currentCall = verto.newCall({
            destination_number: number,
            caller_id_name: 'WebRTC User',
            caller_id_number: '1001',
            useVideo: false,
            useStereo: false
        });
    }

    function hangupCall() {
        if (currentCall) {
            currentCall.hangup();
        }
    }
    </script>
</body>
</html>

FreeSWITCH + Databases (mod_xml_curl)

mod_xml_curl fetches configuration dynamically from an HTTP server. Instead of static XML files, FreeSWITCH asks your web app for user directory, dialplan, and configuration on every request.

Enable in modules.conf.xml:

<load module="mod_xml_curl"/>

Configure in /etc/freeswitch/autoload_configs/xml_curl.conf.xml:

<configuration name="xml_curl.conf" description="cURL XML Gateway">
  <bindings>
    <!-- Dynamic user directory -->
    <binding name="directory">
      <param name="gateway-url"
        value="http://127.0.0.1:8080/freeswitch/directory"/>
      <param name="gateway-credentials" value="fsapi:YOUR_API_KEY"/>
      <param name="auth-scheme" value="basic"/>
      <param name="timeout" value="5"/>
      <param name="enable-post" value="true"/>
      <param name="bindings" value="directory"/>
    </binding>

    <!-- Dynamic dialplan -->
    <binding name="dialplan">
      <param name="gateway-url"
        value="http://127.0.0.1:8080/freeswitch/dialplan"/>
      <param name="gateway-credentials" value="fsapi:YOUR_API_KEY"/>
      <param name="auth-scheme" value="basic"/>
      <param name="timeout" value="5"/>
      <param name="enable-post" value="true"/>
      <param name="bindings" value="dialplan"/>
    </binding>
  </bindings>
</configuration>

Flask backend example:

#!/usr/bin/env python3
"""
freeswitch_api.py
Serve dynamic XML configuration to FreeSWITCH via mod_xml_curl.
"""

from flask import Flask, request, Response
import sqlite3

app = Flask(__name__)
DB_PATH = '/var/lib/freeswitch/db/users.db'


@app.route('/freeswitch/directory', methods=['POST'])
def directory():
    """Return user XML based on registration request."""
    user = request.form.get('user', '')
    domain = request.form.get('domain', '')
    action = request.form.get('action', '')

    if not user:
        return not_found()

    # Look up user in database
    conn = sqlite3.connect(DB_PATH)
    cursor = conn.cursor()
    cursor.execute(
        'SELECT password, name, caller_id FROM users WHERE extension = ?',
        (user,)
    )
    row = cursor.fetchone()
    conn.close()

    if not row:
        return not_found()

    password, name, caller_id = row

    xml = f'''<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<document type="freeswitch/xml">
  <section name="directory">
    <domain name="{domain}">
      <user id="{user}">
        <params>
          <param name="password" value="{password}"/>
          <param name="vm-password" value="{user}"/>
        </params>
        <variables>
          <variable name="user_context" value="default"/>
          <variable name="effective_caller_id_name" value="{name}"/>
          <variable name="effective_caller_id_number" value="{caller_id or user}"/>
        </variables>
      </user>
    </domain>
  </section>
</document>'''

    return Response(xml, mimetype='text/xml')


@app.route('/freeswitch/dialplan', methods=['POST'])
def dialplan():
    """Return dynamic dialplan XML."""
    dest = request.form.get('Caller-Destination-Number', '')
    context = request.form.get('Caller-Context', 'default')
    caller = request.form.get('Caller-Caller-ID-Number', '')

    # Example: route based on database lookup
    conn = sqlite3.connect(DB_PATH)
    cursor = conn.cursor()
    cursor.execute(
        'SELECT action, target FROM routes WHERE pattern = ? AND context = ?',
        (dest, context)
    )
    row = cursor.fetchone()
    conn.close()

    if row:
        action_type, target = row
        xml = f'''<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<document type="freeswitch/xml">
  <section name="dialplan">
    <context name="{context}">
      <extension name="dynamic_route">
        <condition field="destination_number" expression="^{dest}$">
          <action application="{action_type}" data="{target}"/>
        </condition>
      </extension>
    </context>
  </section>
</document>'''
    else:
        xml = not_found_xml()

    return Response(xml, mimetype='text/xml')


def not_found():
    return Response(not_found_xml(), mimetype='text/xml')


def not_found_xml():
    return '''<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<document type="freeswitch/xml">
  <section name="result">
    <result status="not found"/>
  </section>
</document>'''


if __name__ == '__main__':
    app.run(host='127.0.0.1', port=8080)

FreeSWITCH + REST APIs

Use Lua or Python scripts in the dialplan to call external REST APIs:

<!-- In dialplan — call a Lua script for routing decisions -->
<extension name="api_routing">
  <condition field="destination_number" expression="^(8[0-9]{3})$">
    <action application="lua" data="api_route.lua"/>
  </condition>
</extension>

Lua script (/etc/freeswitch/scripts/api_route.lua):

-- api_route.lua
-- Look up routing information from a REST API

local api = require("socket.http")
local json = require("cjson")

-- Get call info
local caller = session:getVariable("caller_id_number")
local dest = session:getVariable("destination_number")

-- Call external API
local url = string.format(
    "http://127.0.0.1:8080/api/route?caller=%s&dest=%s",
    caller, dest
)

local response, code = api.request(url)

if code == 200 and response then
    local data = json.decode(response)

    if data.action == "bridge" then
        session:setVariable("effective_caller_id_number", data.caller_id or caller)
        session:execute("bridge", data.target)
    elseif data.action == "voicemail" then
        session:execute("voicemail", "default " .. data.domain .. " " .. data.mailbox)
    elseif data.action == "reject" then
        session:execute("respond", "403")
    end
else
    -- API unavailable — fallback to default routing
    session:execute("transfer", "1009 XML default")
end

FreeSWITCH + Asterisk Interop

You can interconnect FreeSWITCH and Asterisk via a SIP trunk between them:

On FreeSWITCH — create a gateway to Asterisk. Save as /etc/freeswitch/sip_profiles/external/asterisk.xml:

<include>
  <gateway name="asterisk">
    <param name="username" value="freeswitch_trunk"/>
    <param name="password" value="SHARED_TRUNK_PASSWORD"/>
    <param name="realm" value="ASTERISK_IP"/>
    <param name="proxy" value="ASTERISK_IP"/>
    <param name="register" value="true"/>
    <param name="caller-id-in-from" value="true"/>
    <param name="codec-prefs" value="PCMU,PCMA"/>
  </gateway>
</include>

Route calls to Asterisk extensions (e.g., 2xxx range):

<extension name="to_asterisk">
  <condition field="destination_number" expression="^(2[0-9]{3})$">
    <action application="bridge" data="sofia/gateway/asterisk/$1"/>
  </condition>
</extension>

On Asterisk — create the matching trunk in pjsip.conf:

; pjsip.conf — FreeSWITCH trunk
[freeswitch_trunk]
type=registration
outbound_auth=freeswitch_trunk_auth
server_uri=sip:FREESWITCH_IP:5080
client_uri=sip:freeswitch_trunk@FREESWITCH_IP:5080
retry_interval=60

[freeswitch_trunk_auth]
type=auth
auth_type=userpass
username=freeswitch_trunk
password=SHARED_TRUNK_PASSWORD

[freeswitch_trunk_endpoint]
type=endpoint
context=from-freeswitch
disallow=all
allow=ulaw,alaw
outbound_auth=freeswitch_trunk_auth
aors=freeswitch_trunk_aor

[freeswitch_trunk_aor]
type=aor
contact=sip:FREESWITCH_IP:5080

[freeswitch_trunk_identify]
type=identify
endpoint=freeswitch_trunk_endpoint
match=FREESWITCH_IP

FreeSWITCH as Media Server Behind Kamailio

In this pattern, Kamailio handles all SIP routing and FreeSWITCH only processes media (IVR, conferencing, recording, transcoding):

                    ┌──────────────┐
                    │   Kamailio   │
  SIP phones ──────►   (Router)   ◄────── SIP Trunks
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ FS Node 1│ │ FS Node 2│ │ FS Node 3│
        │ (Media)  │ │ (Media)  │ │ (Media)  │
        └──────────┘ └──────────┘ └──────────┘

Kamailio selects the FreeSWITCH node using the dispatcher module:

# kamailio.cfg — load balance across FreeSWITCH nodes
modparam("dispatcher", "list_file", "/etc/kamailio/dispatcher.list")

# dispatcher.list:
# setid destination flags priority
1 sip:FS_NODE_1:5060 0 50
1 sip:FS_NODE_2:5060 0 50
1 sip:FS_NODE_3:5060 0 50

FreeSWITCH nodes are configured identically, with auth-calls set to false and Kamailio's IP in the ACL.

14. Troubleshooting

SIP Registration Failures

Symptoms: Phone shows "Registration failed" or "403 Forbidden."

Diagnostic steps:

# 1. Check if the profile is running
fs_cli -x "sofia status"

# 2. Check registered users
fs_cli -x "sofia status profile internal reg"

# 3. Enable SIP trace to see actual SIP messages
fs_cli -x "sofia profile internal siptrace on"
# Make a registration attempt, then:
fs_cli -x "sofia profile internal siptrace off"

# 4. Check the log for auth failures
grep -i "auth" /var/log/freeswitch/freeswitch.log | tail -20

# 5. Verify the user exists in the directory
fs_cli -x "xml_locate directory default 1001"

# 6. Test connectivity
# From the phone's network, check if SIP port is reachable:
# nmap -sU -p 5060 YOUR_SERVER_IP

Common causes and fixes:

Problem	Cause	Fix
403 Forbidden	Wrong password	Check `directory/default/1001.xml` password
401 Unauthorized loop	Password mismatch	Verify `default_password` in `vars.xml` vs per-user password
Connection timeout	Firewall blocking 5060	Open UDP/TCP 5060 in firewall
Profile not running	Config error	Check `sofia status`, look for XML parse errors in log
Wrong domain	Domain mismatch	Set phone's domain to match `vars.xml` domain

No Audio / One-Way Audio

This is the most common VoIP problem. It is almost always a NAT/firewall issue.

Diagnostic steps:

# 1. Check RTP ports in firewall
# Ensure 16384-32768/udp is open

# 2. Check NAT settings
fs_cli -x "sofia status profile internal"
# Look for ext-sip-ip and ext-rtp-ip — they should be your PUBLIC IP

# 3. Check codec negotiation
fs_cli -x "show channels"
# Look at read_codec and write_codec — should match on both legs

# 4. During a call, check RTP stats
fs_cli -x "uuid_debug_media <call-uuid> read on"
# This shows incoming RTP packets (or lack thereof)

# 5. Check for RTP timeout
grep "rtp_timeout" /var/log/freeswitch/freeswitch.log | tail -10

Common causes and fixes:

Problem	Cause	Fix
No audio both ways	RTP ports blocked by firewall	Open 16384-32768/udp
One-way audio	NAT not configured	Set `ext-rtp-ip` to public IP
Audio drops after 30s	NAT timeout on firewall	Enable SIP keepalives, reduce RTP timeout
Choppy audio	Codec mismatch / transcoding	Align codec preferences on both ends
Echo	Acoustic echo on phone	Enable echo cancellation on phone; not a server issue

NAT Checklist:

<!-- Verify these are set correctly in your profile -->
<param name="ext-sip-ip" value="YOUR_PUBLIC_IP"/>
<param name="ext-rtp-ip" value="YOUR_PUBLIC_IP"/>
<param name="apply-nat-acl" value="nat.auto"/>
<param name="aggressive-nat-detection" value="true"/>

Call Routing Problems

Symptoms: Calls go to the wrong destination, get "UNALLOCATED_NUMBER," or drop.

# 1. Test dialplan matching without making a real call
fs_cli -x "expand xml_locate dialplan default 15551234567 as xml"

# 2. Enable dialplan debug
fs_cli -x "sofia loglevel all 7"

# 3. Check which context the call enters
grep "Processing" /var/log/freeswitch/freeswitch.log | tail -20

# 4. Manually trace a number through the dialplan
fs_cli
> reloadxml
> originate user/1001 &echo()
# Then check logs for the routing path

# 5. Check for regex issues
# In fs_cli:
> regex 15551234567 ^(\+?1?\d{10})$
# Should return "true" if the pattern matches

Common causes:

Problem	Cause	Fix
UNALLOCATED_NUMBER	No matching extension in dialplan	Add a catch-all or correct the regex
Wrong destination	Extension ordering (first match wins)	Move more-specific rules above generic ones
Calls to trunk fail	Gateway not registered	Check `sofia status gateway my_provider`
Transfer fails	Wrong context in transfer command	Verify `transfer <dest> XML <context>`

Performance Issues

# 1. Check system resources
fs_cli -x "status"
# Look at "min idle cpu" — should be above 50%

# 2. Check session count
fs_cli -x "show channels count"

# 3. Check for codec transcoding (CPU-intensive)
fs_cli -x "show channels"
# If read_codec != write_codec, transcoding is happening

# 4. Check for memory leaks
fs_cli -x "status"
# Monitor session count over time — should not grow unbounded

# 5. Profile-level stats
fs_cli -x "sofia status profile internal"
# Check CALLS-IN, CALLS-OUT, FAILED counts

Performance tuning:

# Increase file descriptor limits
cat >> /etc/security/limits.conf << 'EOF'
freeswitch    soft    nofile    65536
freeswitch    hard    nofile    65536
freeswitch    soft    nproc     65536
freeswitch    hard    nproc     65536
EOF

# Increase max sessions (default 1000)
fs_cli -x "fsctl max_sessions 5000"

# Increase sessions per second (default 30)
fs_cli -x "fsctl sps 200"

# Disable unnecessary modules
# Edit modules.conf.xml and comment out unused modules
# Fewer modules = less memory + faster startup

Essential fs_cli Commands Reference

Command	Description
`status`	System uptime, session count, CPU
`sofia status`	All SIP profiles and their state
`sofia status profile internal`	Detailed internal profile stats
`sofia status profile internal reg`	List registered phones
`sofia status gateway my_provider`	Trunk/gateway status
`sofia profile internal siptrace on`	Enable SIP message trace
`sofia profile internal restart reloadxml`	Restart a SIP profile
`show channels`	Active call channels
`show calls`	Active bridged calls
`show registrations`	All current registrations
`reloadxml`	Reload all XML configuration
`reload mod_sofia`	Reload SIP module
`conference list`	Active conferences
`uuid_kill <uuid>`	Hang up a specific call
`uuid_transfer <uuid> <dest> XML <ctx>`	Transfer a call
`uuid_record <uuid> start <file>`	Start recording
`uuid_debug_media <uuid> read on`	Debug RTP media
`uuid_setvar <uuid> <var> <val>`	Set variable on active call
`originate user/1001 &echo()`	Place a test call
`hupall`	Hang up ALL calls (emergency)
`fsctl shutdown`	Graceful shutdown
`fsctl shutdown elegant`	Shutdown after all calls end
`fsctl pause`	Pause new call processing
`fsctl resume`	Resume call processing
`regex <string> <pattern>`	Test regex matching
`xml_locate directory default 1001`	Look up user config
`module_exists <module>`	Check if module is loaded
`load <module>`	Load a module
`unload <module>`	Unload a module

Quick Diagnostic Sequence

When something is not working, run through this sequence:

# 1. Is FreeSWITCH running?
systemctl status freeswitch

# 2. Can you connect via ESL?
fs_cli -x "status"

# 3. Are SIP profiles up?
fs_cli -x "sofia status"

# 4. Are phones registered?
fs_cli -x "sofia status profile internal reg"

# 5. Are trunks connected?
fs_cli -x "sofia status gateway my_provider"

# 6. Any errors in the log?
tail -100 /var/log/freeswitch/freeswitch.log | grep -i "error\|warning\|fail"

# 7. Is it a firewall issue?
ss -ulnp | grep 5060    # SIP port listening?
ss -ulnp | grep 8021    # ESL port listening?

# 8. Disk space?
df -h

# 9. Memory?
free -h

# 10. Active calls?
fs_cli -x "show channels count"

End of Tutorial 41.

You now have a working FreeSWITCH installation with SIP phones, trunks, IVR, voicemail, conferencing, call recording, external application control via ESL, and production security hardening. The configurations in this tutorial are production-tested patterns that you can adapt to your specific requirements.

Next steps to explore:

mod_callcenter — Built-in ACD (Automatic Call Distribution) for contact centers
mod_fifo — Call queues and parking
mod_lcr — Least Cost Routing for multi-carrier environments
mod_nibblebill — Real-time prepaid billing
mod_skinny — Cisco SCCP phone support
FusionPBX — Full web GUI for FreeSWITCH administration