Platform Guide

Kamailio Load Balancing with Dispatcher

9 min read · Updated April 2026

Kamailio's dispatcher module is the standard way to load balance SIP traffic across multiple backend servers — Asterisk clusters, media servers, or SIP application servers. Here's how to configure it correctly and diagnose failures.

In this guide

01What is Kamailio dispatcher? 02Basic dispatcher configuration 03Load balancing algorithms 04Health checks and failure detection 05Routing script integration 06Troubleshooting dispatcher issues

1. What is Kamailio dispatcher?

The dispatcher module (mod_dispatcher) provides load balancing and failover for SIP traffic in Kamailio. It maintains a list of destination servers, monitors their health via OPTIONS pings, and routes incoming requests according to a configurable algorithm. When a destination fails, dispatcher removes it from the active set and redistributes traffic.

Common use cases: distributing calls across multiple Asterisk servers, load balancing to a FreeSWITCH cluster, routing to geographically distributed media servers.

2. Basic dispatcher configuration

Load the module in kamailio.cfg

loadmodule "dispatcher.so" # Dispatcher parameters modparam("dispatcher", "db_url", DBURL) modparam("dispatcher", "table_name", "dispatcher") modparam("dispatcher", "dst_avp", "$avp(AVP_DST)") modparam("dispatcher", "grp_avp", "$avp(AVP_GRP)") modparam("dispatcher", "cnt_avp", "$avp(AVP_CNT)") modparam("dispatcher", "sock_avp", "$avp(AVP_SOCK)") modparam("dispatcher", "flags", 2) ; use weight-based modparam("dispatcher", "ds_ping_from", "sip:[email protected]") modparam("dispatcher", "ds_ping_interval", 10) ; health check every 10s modparam("dispatcher", "ds_probing_mode", 1) ; probe all destinations modparam("dispatcher", "ds_inactive_threshold", 3) ; fail after 3 missed pings

Dispatcher destinations table

-- In MySQL/PostgreSQL
INSERT INTO dispatcher (setid, destination, flags, weight, description)
VALUES (1, 'sip:10.0.0.1:5060', 0, 50, 'asterisk-1');
VALUES (1, 'sip:10.0.0.2:5060', 0, 50, 'asterisk-2');
VALUES (1, 'sip:10.0.0.3:5060', 0, 50, 'asterisk-3');

3. Load balancing algorithms

The first parameter of ds_select_dst() defines the algorithm:

0 — Hash over callid — same call always goes to same server
1 — Hash over From URI
2 — Hash over To URI
3 — Hash over request URI
4 — Weighted round robin — distributes by weight
6 — Random — random selection from active set
8 — Fewest active calls (requires ds_load module)
9 — Round robin
10 — Hash over From user only

For most PBX cluster deployments, algorithm 4 (weighted round robin) or 9 (round robin) works well. Use algorithm 0 (hash over callid) when you need call affinity — all re-INVITEs and BYEs must reach the same server as the INVITE.

4. Health checks and failure detection

Dispatcher sends OPTIONS pings to all destinations and marks them inactive if they don't respond. Key parameters:

modparam("dispatcher", "ds_ping_interval", 10)   ; seconds between pings
modparam("dispatcher", "ds_inactive_threshold", 3) ; consecutive failures before inactive
modparam("dispatcher", "ds_probing_threshold", 3)  ; probes to confirm recovery
modparam("dispatcher", "ds_probing_mode", 1)       ; 0=probe only inactive, 1=probe all

Check destination health from the CLI:

kamcmd dispatcher.list
# Shows all destinations with status:
# AP = Active Probing
# AX = Active (not probing)
# IP = Inactive Probing (recovering)
# DX = Disabled

5. Routing script integration

request_route {
    if (is_method("INVITE")) {
        # Select destination from set 1, algorithm 4 (weighted RR)
        if (!ds_select_dst(1, 4)) {
            xlog("L_ERR", "No active dispatcher destinations in set 1
");
            send_reply("503", "Service Unavailable");
            exit;
        }
        
        # Set failure route for automatic failover
        t_on_failure("DISPATCH_FAILURE");
        
        xlog("L_INFO", "[$ci] Dispatching to $du
");
        t_relay();
        exit;
    }
}

failure_route[DISPATCH_FAILURE] {
    if (t_is_canceled()) exit;
    
    # Try next destination on failure
    if (t_check_status("503") || t_check_status("408")) {
        if (ds_next_dst()) {
            xlog("L_INFO", "[$ci] Failover to $du
");
            t_relay();
            exit;
        }
    }
    
    send_reply("503", "All servers unavailable");
}

6. Troubleshooting dispatcher issues

All destinations showing DX (Disabled): The health check OPTIONS pings are failing. Check that your Asterisk/FreeSWITCH servers respond to OPTIONS from Kamailio's IP. Check firewall rules. Verify the ds_ping_from URI is valid on the destination.

Calls going to wrong server: Check algorithm selection. Algorithm 0 (callid hash) ensures affinity — re-INVITEs go to the same server. With round robin, mid-dialog requests may go to different servers unless you've implemented dialog-based routing.

Failover not working: Verify the failure_route is set with t_on_failure() before t_relay(). Check that ds_next_dst() is called in the failure route. Verify ds_inactive_threshold is low enough to detect failures quickly.

Reload after database changes:

kamcmd dispatcher.reload

Frequently asked questions

What is Kamailio dispatcher used for?

Kamailio dispatcher is a load balancing module that distributes SIP traffic across multiple backend servers. It supports multiple algorithms (round robin, weighted, hash-based), automatic health checks via OPTIONS pings, and failover routing. Commonly used to balance calls across Asterisk or FreeSWITCH clusters.

How do I check dispatcher destination health in Kamailio?

Use kamcmd dispatcher.list to see all destinations and their status. AP means Active Probing, AX is Active not probing, IP is Inactive Probing (recovering), DX is Disabled. If destinations show DX, the OPTIONS health check pings are failing — check firewall rules and that backends respond to OPTIONS from Kamailio.

How do I configure failover in Kamailio dispatcher?

Set t_on_failure() before t_relay() in your routing script. In the failure_route, call ds_next_dst() to select the next available destination and re-relay. Handle 503 and 408 responses as failure triggers. Set ds_inactive_threshold=3 so failed servers are removed from the active pool after 3 missed health check pings.

Having Kamailio load balancing issues?

Paste your Kamailio debug output or SIP trace into SIPSymposium. The analyzer identifies dispatcher routing failures, health check issues, and failover problems.

Analyze my trace Create free account

Related guides