Kamailio en Español

¿Qué es Kamailio?

Kamailio es un servidor SIP de código abierto y alto rendimiento, heredero directo del proyecto OpenSER (que a su vez derivó de SER — SIP Express Router, creado en 2001 por Fraunhofer FOKUS). Es uno de los servidores SIP más utilizados en el mundo para construir infraestructuras de voz sobre IP (VoIP), plataformas de comunicaciones unificadas, WebRTC y redes de telecomunicaciones a escala operadora.

Kamailio actúa como proxy SIP, registrar, redirect server y location server. Su arquitectura modular y su potente lenguaje de scripting (kamailio.cfg) lo hacen idóneo tanto para instalaciones pequeñas como para despliegues masivos con millones de usuarios simultáneos.

Historia y evolución

Versiones de Kamailio

Kamailio sigue un ciclo de versiones semestral. A continuación las ramas activas y las últimas de la serie 5.x:

Módulos Principales

Kamailio carga funcionalidad a través de módulos (.so). Se cargan con loadmodule "nombre.so" y se configuran con modparam().

Autenticación y Usuarios

Ejemplo: configurar auth_db

loadmodule "auth.so"
loadmodule "auth_db.so"
loadmodule "db_mysql.so"

modparam("auth_db", "db_url", "mysql://kamailio:pass@localhost/kamailio")
modparam("auth_db", "calculate_ha1", yes)   # la BD guarda password en texto plano
modparam("auth_db", "password_column", "password")
modparam("auth_db", "user_column", "username")
modparam("auth_db", "domain_column", "domain")

# En request_route:
if (!auth_check("$fd", "subscriber", "1")) {
    auth_challenge("$fd", "0");
    exit;
}

Base de Datos

Ejemplo: consulta SQL con sqlops

loadmodule "sqlops.so"
modparam("sqlops","sqlcon","ca=>mysql://kamailio:pass@localhost/kamailio")

# En request_route:
sql_query("ca", "SELECT did FROM did_routing WHERE number='$rU'", "res");
if($dbr(res=>rows) > 0) {
    $ru = "sip:" + $dbr(res=>[0,0]) + "@gateway.local";
}
sql_result_free("res");

Enrutamiento y Proxy

Ejemplo: dispatcher (balanceo de carga)

loadmodule "dispatcher.so"
modparam("dispatcher", "db_url", "mysql://kamailio:pass@localhost/kamailio")
modparam("dispatcher", "ds_ping_interval", 10)   # ping cada 10s para detectar caídas
modparam("dispatcher", "ds_probing_mode", 1)      # probar todos los destinos

# En request_route:
if (is_method("INVITE")) {
    if (!ds_select_dst("1", "4")) {   # grupo 1, algoritmo round-robin
        send_reply(503, "Service Unavailable");
        exit;
    }
}

# Gestionar fallos (event_route o failure_route):
failure_route[MANAGE_FAILURE] {
    if (t_is_canceled()) exit;
    if (t_check_status("500|503")) {
        if (ds_next_dst()) {
            t_relay();
            exit;
        }
    }
}

NAT y Media

Ejemplo: nathelper + rtpengine

loadmodule "nathelper.so"
loadmodule "rtpengine.so"

modparam("nathelper", "natping_interval", 30)
modparam("nathelper", "ping_nated_only", 1)
modparam("rtpengine", "rtpengine_sock", "udp:127.0.0.1:2223")

route[MEDIA] {
    if (is_method("INVITE") || is_method("UPDATE")) {
        if (nat_uac_test(19)) {
            fix_nated_contact();
            rtpengine_offer("replace-origin replace-session-connection");
        }
    }
}

onreply_route[REPLY_MEDIA] {
    if (nat_uac_test(19)) {
        rtpengine_answer("replace-origin replace-session-connection");
        fix_nated_contact();
    }
}

WebRTC y Transporte

Scripting KEMI

Ejemplo: KEMI con Python 3

# kamailio.cfg — activar KEMI Python
loadmodule "app_python3.so"
modparam("app_python3", "load", "/etc/kamailio/kamailio_route.py")

cfgengine "python"

# /etc/kamailio/kamailio_route.py
import kamailio

def ksr_request_route():
    KSR.info("Petición: {} desde {}\n".format(
        KSR.pv.get("$rm"), KSR.pv.get("$si")))

    if KSR.is_REGISTER():
        return ksr_route_registrar()

    if KSR.siputils.has_totag() > 0:
        if KSR.rr.loose_route() > 0:
            return ksr_route_relay()

def ksr_route_registrar():
    if KSR.registrar.save("location", 0) < 0:
        KSR.sl.sl_reply_error()
    return

def ksr_route_relay():
    if KSR.tm.t_relay() < 0:
        KSR.sl.sl_reply_error()
    return

Seguridad y Monitorización

Ejemplo: pike + htable (anti-flood)

loadmodule "pike.so"
loadmodule "htable.so"

modparam("pike", "sampling_time_unit", 2)
modparam("pike", "reqs_density_per_unit", 30)  # max 30 req/2s por IP
modparam("pike", "remove_latency", 4)
modparam("htable", "htable", "ipban=>size=8;autoexpire=300")

request_route {
    # Bloquear IPs baneadas
    if ($sht(ipban=>$si) != $null) {
        xlog("L_WARN", "IP baneada: $si\n");
        exit;
    }
    # Detectar flood
    if (!pike_check_req()) {
        $sht(ipban=>$si) = 1;
        xlog("L_WARN", "Flood detectado, baneando $si por 300s\n");
        exit;
    }
}

Instalación de Kamailio

Desde repositorios oficiales (recomendado)

Debian 12 / Ubuntu 24.04 — Kamailio 6.1

# 1. Añadir clave GPG y repositorio oficial
curl -fsSL https://deb.kamailio.org/kamailiodebkey.gpg | sudo gpg --dearmor \
  -o /usr/share/keyrings/kamailio.gpg

# Debian 12 (Bookworm) / Ubuntu 24.04:
echo "deb [signed-by=/usr/share/keyrings/kamailio.gpg] \
  https://deb.kamailio.org/kamailio61 bookworm main" \
  | sudo tee /etc/apt/sources.list.d/kamailio.list

# 2. Instalar paquetes base + módulos más comunes
sudo apt update
sudo apt install kamailio kamailio-mysql-modules kamailio-tls-modules \
  kamailio-websocket-modules kamailio-utils-modules kamailio-extras-modules

# 3. Crear base de datos
kamdbctl create

# 4. Habilitar e iniciar
sudo systemctl enable kamailio
sudo systemctl start kamailio
sudo systemctl status kamailio

AlmaLinux 9 / Rocky Linux 9 — Kamailio 6.1

sudo dnf install epel-release
sudo curl -fsSL https://rpm.kamailio.org/kamailio61/kamailio.repo \
  -o /etc/yum.repos.d/kamailio.repo

sudo dnf install kamailio kamailio-mysql kamailio-tls kamailio-websocket

kamdbctl create
sudo systemctl enable --now kamailio

Docker — Arranque rápido

docker pull kamailio/kamailio:6.1-debian

docker run -d \
  --name kamailio \
  --network host \
  -v /etc/kamailio:/etc/kamailio \
  kamailio/kamailio:6.1-debian

Compilar desde código fuente

# Dependencias (Debian/Ubuntu)
sudo apt install -y git gcc flex bison make libmysqlclient-dev \
  libssl-dev libpcre3-dev libcurl4-openssl-dev libxml2-dev libevent-dev

# Clonar y compilar versión 6.1
git clone --depth 1 --branch 6.1 https://github.com/kamailio/kamailio.git
cd kamailio

make FLAVOUR=kamailio include_modules="db_mysql tls websocket nathelper \
  rtpengine dispatcher app_python3" cfg
make all
sudo make install

Paquetes disponibles por distribución

Configuración de Kamailio

El fichero principal es /etc/kamailio/kamailio.cfg. Se organiza en cuatro bloques: directivas globales, carga de módulos, parámetros de módulos y bloques de rutas.

Estructura completa de kamailio.cfg

#!KAMAILIO

#!define DBURL "mysql://kamailio:pass@localhost/kamailio"

# ── Parámetros globales ──────────────────────────────────────────────
debug=2
log_stderror=no
log_facility=LOG_LOCAL0
fork=yes
children=4

listen=udp:0.0.0.0:5060
listen=tcp:0.0.0.0:5060
listen=tls:0.0.0.0:5061

# ── Módulos ──────────────────────────────────────────────────────────
loadmodule "tm.so"
loadmodule "sl.so"
loadmodule "rr.so"
loadmodule "usrloc.so"
loadmodule "registrar.so"
loadmodule "auth.so"
loadmodule "auth_db.so"
loadmodule "db_mysql.so"
loadmodule "nathelper.so"
loadmodule "xlog.so"
loadmodule "maxfwd.so"
loadmodule "textops.so"

# ── Parámetros de módulos ────────────────────────────────────────────
modparam("usrloc", "db_url", DBURL)
modparam("usrloc", "db_mode", 2)          # write-back caché + BD
modparam("auth_db", "db_url", DBURL)
modparam("auth_db", "calculate_ha1", yes)
modparam("auth_db", "password_column", "password")
modparam("rr", "enable_full_lr", 1)

# ── Rutas ────────────────────────────────────────────────────────────
request_route {
    xlog("L_INFO", "[$ci] $rm $ru desde $fu ($si:$sp)\n");

    if (!mf_process_maxfwd_header(10)) {
        sl_send_reply(483, "Too Many Hops"); exit;
    }

    if (is_method("REGISTER")) {
        route(AUTH);
        route(REGISTRAR);
        exit;
    }

    if (is_method("INVITE|SUBSCRIBE")) { record_route(); }

    if (has_totag()) {
        if (loose_route()) { route(RELAY); }
        exit;
    }

    if (is_method("INVITE")) {
        route(AUTH);
        route(LOCATION);
    }
}

route[AUTH] {
    if (!auth_check("$fd", "subscriber", "1")) {
        auth_challenge("$fd", "0");
        exit;
    }
    consume_credentials();
}

route[REGISTRAR] {
    if (!save("location")) { sl_reply_error(); }
    exit;
}

route[LOCATION] {
    if (!lookup("location")) {
        $var(rc) = $retcode;
        if ($var(rc) == -1 || $var(rc) == -3) {
            send_reply(404, "Not Found"); exit;
        }
        send_reply(405, "Method Not Allowed"); exit;
    }
    route(RELAY);
}

route[RELAY] {
    if (!t_relay()) { sl_reply_error(); }
    exit;
}

Configuración TLS con modo multihilo (Kamailio 6.1)

loadmodule "tls.so"
modparam("tls", "config", "/etc/kamailio/tls.cfg")
modparam("tls", "tls_threads_mode", 1)   # multihilo — novedad 6.1

# /etc/kamailio/tls.cfg
[server:default]
method = TLSv1.2+
verify_certificate = no
require_certificate = no
private_key = /etc/ssl/kamailio/privkey.pem
certificate = /etc/ssl/kamailio/fullchain.pem

Configuración WebSocket / WebRTC

loadmodule "xhttp.so"
loadmodule "websocket.so"
loadmodule "nathelper.so"
loadmodule "rtpengine.so"

modparam("websocket", "keepalive_mechanism", 1)
modparam("websocket", "keepalive_interval", 30)
modparam("rtpengine", "rtpengine_sock", "udp:127.0.0.1:2223")

listen=tcp:0.0.0.0:8080    # WS
listen=tls:0.0.0.0:4443    # WSS

event_route[xhttp:request] {
    set_reply_close();
    set_reply_no_connect();
    if (ws_handle_handshake()) exit;
    send_reply(404, "Not found");
}

event_route[websocket:closed] {
    xlog("L_INFO", "WS cerrado $si:$sp\n");
}

Comandos de administración

# Estado del servidor
kamctl status

# Ver registraciones activas
kamctl ul show
kamctl ul show usuario@dominio.com

# Recargar dispatcher desde BD (sin reiniciar)
kamcmd dispatcher.reload

# Estadísticas en tiempo real
kamcmd stats.get_statistics all
kamcmd stats.get_statistics "inuse_transactions:"

# Número de llamadas activas
kamcmd tm.stats

# Ver conexiones TLS activas
kamcmd tls.info

# Banear una IP manualmente
kamcmd htable.seti ipban 192.168.1.100 1

# Enviar SIP OPTION de prueba
kamctl fifo via_list

Pseudovariables en Kamailio

Las pseudovariables permiten acceder a campos del mensaje SIP y del entorno de ejecución directamente desde el script. Su sintaxis es $nombre o $(nombre{transformacion}).

Mensaje SIP — petición

Respuesta SIP

Red y conexión

Variables de usuario y compartidas

# AVP — por transacción, tipadas (int o string)
$avp(nombre) = "valor string";
$avp(i:42)   = 100;

# $var — por proceso/petición, alta velocidad
$var(contador) = $var(contador) + 1;

# $dlg_var — persiste durante todo el diálogo (requiere módulo dialog)
$dlg_var(clave) = "valor permanente del diálogo";

# $sht — hash table compartida entre todos los procesos (requiere htable)
$sht(tabla=>clave) = "compartido";
if ($sht(ipban=>$si) != $null) { exit; }

# Cabeceras SIP
xlog("Contact: $hdr(Contact)\n");
xlog("2º Via: $(hdr(Via)[1])\n");    # índice base 0

# Transformaciones
xlog("Usuario en mayúsculas: $(rU{s.upper})\n");
xlog("IP válida: $(si{ip.isavp})\n");
xlog("Longitud de rU: $(rU{s.len})\n");
$var(host) = $(ru{uri.host});         # extraer host del URI

Recursos y Comunidad