Kamailio 6.x — Guía de Instalación como SBC

Debian 13 (Trixie) · Ring2All Platform

Entorno validado: Debian GNU/Linux 13 (trixie) · Kamailio 6.0.1 · PostgreSQL 17 · RTPEngine 12.5.x Servidor de lab: 192.168.10.32

Prerequisitos

Servidor Debian 13 (trixie) con acceso root
Mínimo 2 GB RAM, 20 GB disco
PostgreSQL instalado (se incluye en esta guía)

1. Verificar el Sistema Operativo

lsb_release -a

Debe responder Debian GNU/Linux 13 (trixie).

2. Instalar Kamailio y Módulos

Debian Trixie incluye Kamailio 6.0.1 en sus repos oficiales. No se necesita repositorio externo.

apt update

apt install -y kamailio sbc-kamailio-postgres-modules sbc-kamailio-tls-modules sbc-kamailio-websocket-modules sbc-kamailio-utils-modules sbc-kamailio-json-modules sbc-kamailio-extra-modules sbc-kamailio-presence-modules kamcli

# Verificar
kamailio -V

Resultado esperado:

version: kamailio 6.0.1 (x86_64/linux)
compiled with gcc 14.2.0

3. Instalar RTPEngine (relay de media/NAT)

apt install -y rtpengine rtpengine-daemon rtpengine-kernel-dkms rtpengine-utils

4. Instalar PostgreSQL

apt install -y postgresql postgresql-contrib
systemctl enable postgresql && systemctl start postgresql

5. Fix: Hostname en /etc/hosts

Si el hostname del servidor no está en /etc/hosts, sudo emitirá warnings.

# Verificar hostname actual
cat /etc/hostname

# Agregar al /etc/hosts (solo si falta)
echo "127.0.1.1 $(cat /etc/hostname)" >> /etc/hosts

6. Crear Usuario PostgreSQL para Kamailio

# Asignar contraseña al superusuario postgres (necesario para kamdbctl)
sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'postgres1234';"

⚠️ No crear la base de datos manualmente — la crea kamdbctl create en el paso 8.

7. Configurar kamctlrc

cat > /etc/kamailio/kamctlrc << 'EOF'
DBENGINE=PGSQL
DBHOST=localhost
DBPORT=5432
DBNAME=sbc-kamailio
DBRWUSER=sbc-kamailio
DBRWPW=kamailio2024
DBROUSER=kamailioro
DBROPW=kamailioro2024
INSTALL_EXTRA_TABLES=yes
INSTALL_PRESENCE_TABLES=yes
EOF

8. Crear Schema de Base de Datos

kamdbctl necesita el archivo .pgpass para autenticarse como postgres:

# Crear .pgpass
cat > ~/.pgpass << 'EOF'
localhost:5432:*:postgres:postgres1234
EOF
chmod 600 ~/.pgpass

# Crear BD + todas las tablas
kamdbctl create
# Responder "yes" a todas las preguntas

Resultado esperado:

INFO: Core Kamailio tables successfully created.
INFO: Presence tables successfully created.
INFO: Extra tables successfully created.

Verificar tablas creadas

sudo -u postgres psql -d kamailio -c "\dt" | wc -l
# ~55+ tablas

9. Configurar kamailio.cfg

Ver la IP del servidor:

ip addr show | grep "inet " | grep -v 127

→ Usar el archivo docs/02-kamailio.cfg incluido en este proyecto y copiarlo al servidor.

Una vez que tengas el archivo descargado en tu servidor de Lab, o copiándolo desde tu repositorio:

cp docs/02-kamailio.cfg /etc/kamailio/kamailio.cfg

# Editar MY_IP con la IP real del servidor
nano /etc/kamailio/kamailio.cfg

10. Validar y Arrancar Kamailio

# Validar sintaxis
kamailio -f /etc/kamailio/kamailio.cfg -c
# Debe mostrar: "config file ok, exiting..."

# Arrancar
systemctl enable sbc-kamailio
systemctl start sbc-kamailio
systemctl status sbc-kamailio

# Verificar puerto 5060
ss -ulnp | grep 5060

11. Configuración Inicial del SBC

Agregar dominio SIP

sudo -u postgres psql -d kamailio -c \
  "INSERT INTO domain (domain, did) VALUES ('sbc.ring2all.com', 'default');"

kamcli domain reload

Agregar nodo Telephony Server al Load Balancer

sudo -u postgres psql -d kamailio << 'EOF'
INSERT INTO dispatcher (setid, destination, flags, priority, attrs, description)
VALUES (1, 'sip:192.168.10.X:5060', 0, 1, '', 'Telephony Node 1 - Ring2All');
EOF

kamcli dispatcher reload
kamcli dispatcher show

Crear usuario SIP de prueba

kamcli subscriber add 1001 sbc.ring2all.com test1234
kamcli subscriber show

12. Comandos de Operación Diaria

# Ver registros SIP activos
kamcli ul show

# Ver estado de nodos Telephony Server
kamcli dispatcher show

# Recargar dispatcher (tras agregar nuevo nodo)
kamcli dispatcher reload

# Ver llamadas activas
kamcli dialog show

# Estadísticas
kamcli stats

# Bloquear IP
kamcli htable seti ipban 192.168.1.100 1

# RPC directo
kamcli rpc core.info
kamcli rpc dispatcher.list

Puertos del SBC

Puerto	Protocolo	Servicio
5060	UDP/TCP	SIP (Kamailio)
5061	TLS	SIP seguro
2223	UDP	RTPEngine ng-control
30000–40000	UDP	Media (RTPEngine)
5432	TCP	PostgreSQL

Notas de Compatibilidad — Kamailio 6.x vs 5.x

Cambio	Kamailio 5.x	Kamailio 6.x
Dispatcher AVPs	`dst_avp`, `grp_avp`, `cnt_avp`	`xavp_dst`
Domain	`check_all_domains`	❌ eliminado
Auth	`check_to()`	❌ eliminado

Configurar TLS (Let’s Encrypt + módulo tls)
Habilitar WebSocket para softphones web
Configurar RTPEngine para NAT/SRTP
Integrar con Ring2All SBC Admin (interfaz web)
Prometheus + Grafana para monitoreo

13. Instalar Nginx (Reverse Proxy + Frontend)

Nginx es el único punto de entrada al SBC Admin. Actúa como:

Reverse proxy hacia la API Fastify en puerto 3003
Servidor de archivos estáticos para el frontend Vite compilado
Fallback de desarrollo al servidor Vite :5175 cuando index.html no existe

13.1 Instalar Nginx

apt install -y nginx
systemctl enable nginx
systemctl start nginx

# Verificar
nginx -v
# nginx version: nginx/1.26.x

13.2 Crear certificado SSL auto-firmado (lab)

Producción: usar certbot --nginx con Let’s Encrypt. Reemplazar los paths en el conf.

mkdir -p /etc/nginx/ssl

openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
  -keyout /etc/nginx/ssl/nginx.key \
  -out    /etc/nginx/ssl/nginx.crt \
  -subj   "/C=US/ST=TX/L=Austin/O=SoftswitchOne/CN=sbc.softswitchone.com"

chmod 600 /etc/nginx/ssl/nginx.key
chmod 644 /etc/nginx/ssl/nginx.crt

# Verificar
ls -la /etc/nginx/ssl/

13.3 Crear directorios de producción

# Frontend SPA (Vite build destino)
mkdir -p /var/www/softswitch/sbc/web/dist
chown -R www-data:www-data /var/www/softswitch/sbc/web

# ACME challenge (para certbot en producción)
mkdir -p /var/www/softswitch/sbc/web/.well-known/acme-challenge
chown -R www-data:www-data /var/www/softswitch/sbc/web/.well-known

13.4 Desplegar la configuración Nginx del SBC

El archivo de configuración se encuentra en config/nginx/softswitch-sbc.conf.

# Copiar al servidor (desde tu máquina de desarrollo via scp, o git pull)
cp config/nginx/softswitch-sbc.conf /etc/nginx/sites-available/softswitch-sbc

# Activar el sitio
ln -sf /etc/nginx/sites-available/softswitch-sbc /etc/nginx/sites-enabled/softswitch-sbc

# Deshabilitar el site default (evita conflicto en puerto 80 y 443)
rm -f /etc/nginx/sites-enabled/default

# Validar sintaxis
nginx -t
# Resultado esperado:
# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful

# Activar
systemctl reload nginx

13.5 Arquitectura del tráfico con Nginx

Browser
  │
  ├── :80  HTTP  ──────────────────────────────► 301 → https://$host$request_uri
  │
  └── :443 HTTPS ──────────────────────────────► Nginx ssl_certificate /etc/nginx/ssl/
        │
        ├── /api/*       ──proxy_pass──────────► 127.0.0.1:3003  (sbc-api.service)
        ├── /ws/*        ──proxy_pass WS────────► 127.0.0.1:3003  (WebSocket upgrade)
        ├── /health      ──proxy_pass──────────► 127.0.0.1:3003/health
        ├── *.js|css|... ──static cache 1y──────► /var/www/softswitch/sbc/web/dist/
        └── /*           ──SPA──────────────────► /var/www/softswitch/sbc/web/dist/index.html
                              │ (si no existe) ──► @vite_dev → 127.0.0.1:5175

13.6 Puertos del servidor con Nginx

Puerto	Protocolo	Servicio	Exponer
`80`	TCP	HTTP → redirect HTTPS	✅ Público
`443`	TCP	HTTPS — SBC Admin UI + API	✅ Público
`3003`	TCP	sbc-api (Fastify, interno)	❌ Solo loopback
`5175`	TCP	Vite dev server (solo desarrollo)	❌ Solo LAN

13.7 Verificar que Nginx sirve correctamente

# Verificar que los puertos 80 y 443 están activos
ss -tlnp | grep nginx

# Probar el redirect HTTP→HTTPS
curl -I http://127.0.0.1
# Debe mostrar: HTTP/1.1 301 Moved Permanently

# Probar el health check de la API (HTTPS, ignorando cert auto-firmado)
curl -k https://127.0.0.1/health
# Debe mostrar: {"status":"ok","service":"kamailio-api",...}

# Probar la UI (debe devolver HTML del index.html o el Vite dev)
curl -k -s https://127.0.0.1/ | head -5

13.8 Modo desarrollo (Vite dev server)

Cuando dist/index.html no existe, Nginx redirige automáticamente al servidor Vite en :5175.
Esto permite trabajar en desarrollo sin necesidad de compilar el frontend.

# En tu máquina de desarrollo (o en el servidor):
cd admin/apps/kamailio-sbc/sbc-kamailio
npm run dev
# Vite listening on http://localhost:5175

# Nginx intercepta /* y hace proxy a :5175
# → https://192.168.10.32  sirve el frontend en tiempo real

Para desactivar el fallback y usar la versión compilada:
Terminal window
cd admin/apps/kamailio-sbc/sbc-kamailio
npm run build
rsync -av dist/ /var/www/softswitch/sbc/web/dist/
systemctl reload nginx

14. Base de Datos Administrativa (sbc_admin)

Base de datos PostgreSQL exclusiva para el panel de administración del SBC.
Separada de la BD nativa de Kamailio (kamailio).

Nombre en el servidor: sbc_admin
Role: sbc_user
Schema: public (todas las tablas del admin van en el schema public)

Tablas del admin

Tabla	Descripción
`public.role_profiles`	Perfiles de rol con permisos JSONB
`public.log_profiles`	Perfiles de logging configurables
`public.users`	Usuarios administradores del panel
`public.api_keys`	API keys para integraciones externas
`public.audit_log`	Registro de auditoría de todas las acciones
`public.sessions`	Sesiones JWT activas

14.1 Crear BD, role y aplicar schema

# 1. Crear el role de aplicación (least-privilege)
sudo -u postgres psql -c "CREATE ROLE sbc_user WITH LOGIN PASSWORD 'TU_PASSWORD_AQUI';"

# 2. Crear la base de datos
sudo -u postgres createdb -O sbc_user sbc_admin

# 3. Aplicar el schema
sudo -u postgres psql -d sbc_admin -f /var/www/softswitch/sbc/database/schema.sql

# 4. Verificar
sudo -u postgres psql -d sbc_admin -c "\dt public.*"
# Debe listar las tablas: users, role_profiles, log_profiles, api_keys, audit_log

> **Automatizado:** El script `sync-to-sbc.ps1` y el instalador automático `install_robust_sbc.sh` hace todo lo anterior con una contraseña generada aleatoriamente y la guarda en `/etc/softswitch/sbc-credentials`.

14.2 Credenciales admin por defecto

⚠️ Cambiar inmediatamente después del primer login.

Campo	Valor
Usuario	`admin`
Contraseña	`Admin1234!`
Email	`admin@ring2all.com`

# Cambiar contraseña vía psql (bcrypt, factor 12)
sudo -u postgres psql -d sbc_admin \
  -c "UPDATE public.users SET password_hash = crypt('TuNuevaContrasena!', gen_salt('bf',12)) WHERE username='admin';"

15. API Backend — sbc-api (systemd)

15.1 Instalar Node.js

curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt install -y nodejs
node -v   # v22.x.x
npm  -v   # 10.x.x

15.2 Copiar y compilar la API

# Copiar fuentes (desde tu máquina via scp o git pull)
mkdir -p /var/www/softswitch/sbc/api
# ... (ver sync-to-sbc.ps1)

cd /var/www/softswitch/sbc/api
npm install --production
npm run build

15.3 Crear archivo .env

cat > /etc/softswitch/sbc-api.env << 'EOF'
PORT=3003
NODE_ENV=production

# sbc_admin database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=sbc_admin
DB_USER=sbc_user
DB_PASSWORD=TU_PASSWORD_AQUI
DATABASE_URL=postgresql://sbc_user:TU_PASSWORD_AQUI@localhost:5432/sbc_admin

# Kamailio native database (kamailio)
KAM_DATABASE_URL=postgresql://kamailio:kamailio2024@localhost:5432/kamailio

# ss_telephony (SIP Accounts, Carriers, LCR — billing trunks)
TELEPHONY_DATABASE_URL=postgresql://ss_db_user:PASSWORD@192.168.10.31:5432/ss_telephony

# JWT
JWT_SECRET=GENERAR_CON_openssl_rand_hex_32
JWT_EXPIRES_IN=24h

# CORS
CORS_ORIGINS=https://192.168.10.32,https://sbc.tu-dominio.com
EOF

chmod 600 /etc/softswitch/sbc-api.env

15.4 Crear servicio systemd

cat > /etc/systemd/system/sbc-api.service << 'EOF'
[Unit]
Description=SBC Admin API (Fastify)
After=network.target postgresql.service
Wants=postgresql.service

[Service]
Type=simple
WorkingDirectory=/var/www/softswitch/sbc/api
EnvironmentFile=/etc/softswitch/sbc-api.env
ExecStart=/usr/bin/node dist/main.js
Restart=always
RestartSec=5
User=root
Environment=NODE_ENV=production
StandardOutput=journal
StandardError=journal
SyslogIdentifier=sbc-api

[Install]
WantedBy=multi-user.target
EOF

systemctl daemon-reload
systemctl enable sbc-api
systemctl start  sbc-api
systemctl status sbc-api

15.5 Verificar

# Estado del servicio
systemctl status sbc-api

# Logs en tiempo real
journalctl -u sbc-api -f

# Health check directo (sin Nginx)
curl http://127.0.0.1:3003/health
# {"status":"ok","service":"kamailio-api","version":"1.0.0",...}

# Health check via Nginx (HTTPS)
curl -k https://127.0.0.1/health

16. Configurar ODBC (conexión Lua → BD)

⚠️ Solo necesario si los scripts Lua de Telephony Server en este servidor usan ODBC.
La API Node.js usa pg directamente, no requiere ODBC.

16.1 Instalar driver

apt install -y unixodbc odbc-postgresql

16.2 Agregar entradas al odbc.ini

# Opción A — Servidor dedicado SBC (solo Kamailio)
cp config/odbc.ini /etc/odbc.ini
chmod 644 /etc/odbc.ini
sed -i 's/__SBC_DB_PASSWORD__/TU_PASSWORD/g' /etc/odbc.ini

# Opción B — Co-located con Ring2All (agregar al odbc.ini existente)
cat config/odbc.ini >> /etc/odbc.ini

16.3 Verificar

isql -v sbc_admin sbc_user TU_PASSWORD
# +---------------------------------------+
# | Connected!                            |
# +---------------------------------------+

17. Deploy automático desde Windows

El script sync-to-sbc.ps1 en la raíz del proyecto automatiza la sincronización de archivos.

Sincronización completa (primera vez)

cd D:\Desarrollos\Ring2All

.\sync-to-sbc.ps1 -Api -Web -BuildUI -BuildAPI -Restart

Flag	Acción
`-Api`	Sincroniza `api/` → `/var/www/softswitch/sbc/api/`
`-Web`	Sincroniza frontend → `/var/www/softswitch/sbc/web/`
`-BuildUI`	Compila el frontend en el servidor
`-BuildAPI`	Compila la API en el servidor
`-Restart`	Reinicia el servicio `sbc-api`

Updates posteriores (solo frontend o API)

# Solo actualizar código de la API
.\sync-to-sbc.ps1 -Api -BuildAPI -Restart

# Solo actualizar el frontend
.\sync-to-sbc.ps1 -Web -BuildUI

Resumen de Rutas en el Servidor

Recurso	Ruta en servidor	Descripción
API source	`/var/www/softswitch/sbc/api/`	Código TypeScript compilado
API service	`sbc-api.service` (`:3003`)	Servicio systemd
API .env	`/etc/softswitch/sbc-api.env`	Credenciales (chmod 600)
Frontend dist	`/var/www/softswitch/sbc/web/dist/`	Build Vite (servido por Nginx)
Nginx site	`/etc/nginx/sites-available/softswitch-sbc`	Config HTTPS reverse proxy
SSL cert	`/etc/nginx/ssl/nginx.crt` + `.key`	Auto-firmado (lab)
DB credentials	`/etc/softswitch/sbc-credentials`	Generado por el instalador
Logs API	`journalctl -u sbc-api`	systemd journal
Logs Nginx	`/var/log/nginx/sbc-admin_*.log`	Access + error (HTTP/HTTPS)

Resumen de Archivos de Configuración (repo)

Archivo local	Destino servidor	Propósito
`docs/02-kamailio.cfg`	`/etc/kamailio/kamailio.cfg`	Config SIP del SBC
`config/nginx/softswitch-sbc.conf`	`/etc/nginx/sites-available/softswitch-sbc`	Reverse proxy HTTPS + SPA
`config/odbc.ini`	`/etc/odbc.ini` (merge)	Conexiones ODBC
`database/schema.sql`	Ejecutar en PostgreSQL	Schema BD admin
`sync-to-sbc.ps1`	(ejecutar desde Windows)	Script de sincronización completo