---
title: "Kamailio 6.x — Guía de Instalación como SBC"
description: "Documentation for Debian 13 Installation"
---

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

```bash
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.**

```bash
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)

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

---

## 4. Instalar PostgreSQL

```bash
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.

```bash
# 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

```bash
# 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

```bash
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`:

```bash
# 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
```bash
sudo -u postgres psql -d kamailio -c "\dt" | wc -l
# ~55+ tablas
```

---

## 9. Configurar kamailio.cfg

Ver la IP del servidor:
```bash
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:

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

```bash
# 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

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

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

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

---

## 12. Comandos de Operación Diaria

```bash
# 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

```bash
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.

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

```bash
# 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`.

```bash
# 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

```bash
# 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.

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

```bash
# 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` |

```bash
# 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

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

```bash
# 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

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

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

```bash
# 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

```bash
apt install -y unixodbc odbc-postgresql
```

### 16.2 Agregar entradas al odbc.ini

```bash
# 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

```bash
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)

```powershell
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)

```powershell
# 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 |