Taller 7: Troncal SIP con PJSIP Wizard y Enrutamiento de Salida

🌉 Taller 7: Troncal SIP con PJSIP Wizard y Enrutamiento de Salida

⏱️ Información del Taller

Duración: 90 minutos | Dificultad: Avanzado | Modalidad: Práctica

🎯 Objetivo del Taller

Conectar nuestra PBX al mundo exterior de forma profesional. Vamos a refactorizar las extensiones a pjsip_wizard.conf, configurar una troncal SIP con un proveedor, crear el dialplan de salida integrando nuestro AGI de ruleteo de CallerID, y manejar las llamadas entrantes.

---

🗺️ El Escenario: De una Isla a un Continente

Hasta ahora, nuestra PBX ha sido una isla: llamadas internas, AGI para lógica dinámica y notificaciones de voicemail por WhatsApp. En este taller, construimos el puente a la PSTN con una Troncal SIP.

---

7.0 Buenas Prácticas: Backup y Seguridad Primero

Previo a refactor y conexión con proveedor, realiza respaldo y asegura el servidor.

7.0.1 Backup de configuración de Asterisk

cd /etc/asterisk
cp -rfv . ../asterisk.bk-$(date +%F-%H%M)

7.0.2 Cortafuegos (UFW) para señalización y media

ufw allow 5060/udp
ufw allow 10000:20000/udp
# Permite solo la IP de tu proveedor (recomendado)
ufw allow from IP_PROVEEDOR_SIP to any port 5060 proto udp
ufw allow from IP_PROVEEDOR_SIP to any port 10000:20000 proto udp

NAT y transports

Si cambias localnet o external_* en pjsip.conf, necesitarás reiniciar Asterisk para que el transport tome efecto.

---

7.1 Refactorización a pjsip_wizard.conf para Máxima Eficiencia

El Wizard es la forma moderna y limpia de configurar PJSIP. Migremos nuestras extensiones al Wizard y documentemos cómo se relacionan los objetos que genera con pjsip.conf.

7.1.1 Backup, Como Siempre

cd /etc/asterisk/
cp -R . ../asterisk-bk-$(date +%F-%H%M)

7.1.2 Moviendo la Lógica de los Endpoints

Edita pjsip.conf para dejar solo global/transport y mover endpoints al Wizard.

nano /etc/asterisk/pjsip.conf

; Este archivo ahora solo define la configuración global y los transportes.
; Toda la lógica de endpoints y troncales vivirá en pjsip_wizard.conf.

[global]
type=global                    ; Objeto raíz de res_pjsip
user_agent=AulaUtilPBX-v22     ; Cadena que verá tu proveedor en la cabecera User-Agent
default_realm=aulautil.com     ; Dominio usado para autenticación digest

[transport-udp-nat]
type=transport                 ; Tipo de objeto PJSIP
protocol=udp                   ; Protocolo de señalización soportado
bind=0.0.0.0:5060              ; Puerto/IP donde Asterisk escucha peticiones SIP
local_net=192.168.1.0/24       ; Redes locales aceptadas (ajusta a tu topología)
external_media_address=TU_IP_PUBLICA      ; IP pública que anunciará para RTP
external_signaling_address=TU_IP_PUBLICA  ; IP pública que anunciará para SIP

[system]
type=system
threadpool_initial_size=50     ; Hilos creados al iniciar PJSIP (capacidad base)
threadpool_auto_increment=10   ; Hilos adicionales por cada pico de carga
threadpool_max_size=400        ; Límite superior para proteger la CPU del servidor
threadpool_idle_timeout=90     ; Segundos antes de reciclar hilos inactivos

¡Importante!

Reemplaza 192.168.1.0/24 y TU_IP_PUBLICA con tus valores reales. Reinicia Asterisk al finalizar esta sección para aplicar cambios de transport.

¿Por qué tocar el threadpool?

Los valores por defecto de PJSIP funcionan para escenarios pequeños. Cuando la troncal atiende picos altos, define el bloque [system] para dimensionar el pool de hilos (threadpool_*) y evita timeouts. Ajusta tras pruebas de carga con asterisk -rx "core show threads".

Significado de cada parámetro del threadpool

• threadpool_initial_size: cantidad de hilos pre-creados. Mantén un valor cercano a tu media de llamadas simultáneas para evitar latencias en el primer INVITE.
• threadpool_auto_increment: número de hilos que se añaden de golpe cuando el pool se queda sin capacidad. Un salto grande reduce el tiempo de espera en horas pico.
• threadpool_max_size: techo duro. Evita que un ataque o una ráfaga de tráfico consuma todos los recursos del sistema (CPU/RAM) y bloquee Asterisk.
• threadpool_idle_timeout: define cuándo reciclar hilos extra si no reciben trabajo. Un valor alto conserva hilos “listos”, uno bajo libera memoria más rápido.

Crea pjsip_wizard.conf y define una plantilla y tus extensiones:

cd /etc/asterisk/
touch pjsip_wizard.conf
nano pjsip_wizard.conf

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ANEXOS ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

[phone-template](!)
type=wizard                        ; Declara una plantilla reutilizable
transport=transport-udp-nat        ; Hereda el transporte definido en pjsip.conf
accepts_auth=yes                   ; Genera objeto auth para registrar softphones
accepts_registrations=yes          ; Permite que los endpoints se registren en Asterisk
endpoint/allow=!all,ulaw,alaw,opus ; Habilita códecs preferidos (ordénalos por prioridad)
endpoint/context=cat2              ; Contexto de dialplan por defecto
endpoint/dtmf_mode=rfc4733         ; Envía tonos DTMF por RFC4733 (teclas fiables)
endpoint/rtp_symmetric=yes         ; Obliga RTP simétrico (NAT traversal)
endpoint/force_rport=yes           ; Reescribe el puerto RTP para clientes detrás de NAT
endpoint/rewrite_contact=yes       ; Asegura que el Contact apunte a la IP/puerto correctos
aor/max_contacts=1                 ; Límite de dispositivos simultáneos por extensión

[1001](phone-template)
endpoint/context=cat1              ; Sobrescribe el contexto por permisos avanzados
endpoint/mailboxes=1001@default    ; Vincula el buzón de voz configurado en voicemail.conf
endpoint/callerid="Usuario Oficina <1001>" ; Nombre que verá quien reciba la llamada
inbound_auth/username=1001         ; Usuario SIP del softphone
inbound_auth/password=pass1001     ; Contraseña (usa contraseñas fuertes en producción)

[1002](phone-template)
endpoint/mailboxes=1002@default
endpoint/callerid="Agente Soporte <1002>"
inbound_auth/username=1002
inbound_auth/password=pass1002
aor/max_contacts=2                 ; Permite 2 dispositivos (PC + móvil) para la misma ext.

[1003](phone-template)
endpoint/context=cat3              ; Contexto restringido: solo llamadas internas/almacén
endpoint/mailboxes=1003@default
endpoint/callerid="Almacen <1003>"
inbound_auth/username=1003
inbound_auth/password=pass1003

El objeto Wizard genera automáticamente los bloques endpoint, auth, aor y, si lo indicamos, identify y registration. Así evitamos duplicar secciones y logramos configuraciones consistentes. Cada sección hija puede sobrescribir valores de la plantilla con la sintaxis endpoint/clave=valor.

Mapa mental del Wizard

• Plantilla ([phone-template](!)): define la base común para todos los anexos.
• Instancia ([1001](phone-template)): crea objetos endpoint, auth y aor tomando los valores de la plantilla salvo los que redefinas.
• Sobrescritura selectiva: cualquier propiedad se puede ajustar por extensión (aor/max_contacts, endpoint/context, etc.).
• Documenta tus cambios: añade comentarios iniciados con ; para indicar contraseñas temporales, quién es el dueño de la extensión o cuándo expira la cuenta.

Proceso sugerido para migrar anexos

1. Genera la plantilla (phone-template).
2. Crea cada extensión heredando la plantilla y personaliza context, callerid, mailboxes y aor/max_contacts.
3. Recarga PJSIP (asterisk -rx "pjsip reload").
4. Valida una extensión con los comandos:
   • pjsip show endpoint 1001
   • pjsip show auth 1001
   • pjsip show aor 1001
5. Registra el softphone y comprueba que aparece como Reachable en pjsip show contacts 1001.

7.1.3 Reiniciar Asterisk

systemctl restart asterisk

Verifica que los teléfonos registren correctamente.

Checklist de migración a Wizard

• pjsip show endpoint 1001
• pjsip show aor 1001
• pjsip show auth 1001-iauth
• journalctl -u asterisk (errores de sintaxis)

---

7.2 Configuración de la Troncal SIP con el Wizard

Vamos a crear una plantilla reutilizable para proveedores, explicar cada parámetro y añadir herramientas de diagnóstico.

7.2.1 Preparar la plantilla de troncales

Edita pjsip_wizard.conf para añadir la troncal.

nano /etc/asterisk/pjsip_wizard.conf

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; TRONCALES ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

[trunk-template](!)
type=wizard                            ; Plantilla base para cada carrier SIP
sends_auth=yes                         ; Crea objeto de autenticación saliente
sends_registrations=yes                ; Genera registro automático hacia el proveedor
endpoint/allow=!all,ulaw,alaw          ; Códecs habilitados por defecto (añade g729 si aplica)
endpoint/context=from-trunk            ; Contexto que recibirá las llamadas entrantes
endpoint/dtmf_mode=rfc4733             ; Envía tonos fuera de banda (DTMF fiable para IVR)
endpoint/rtp_symmetric=yes             ; Usa la misma IP/puerto para RTP de ida y vuelta (NAT)
endpoint/force_rport=yes               ; Obliga a usar el puerto fuente del paquete (NAT conservador)
endpoint/direct_media=no               ; Mantén el audio pasando por Asterisk (grabación/monitor)
endpoint/timers=yes                    ; Re-INVITEs controlados por Asterisk
endpoint/language=es                   ; Locuciones en español por defecto para esta troncal
aor/qualify_frequency=60               ; Envía OPTIONS cada 60 s para validar que el carrier responde
aor/authenticate_qualify=no            ; No solicita auth extra en el qualify (según carrier)
identify_by=ip                         ; Correlaciona llamadas entrantes usando la IP de origen

[mi-proveedor-sip](trunk-template)
transport=transport-udp-nat            ; Usa el transporte definido en `pjsip.conf`
remote_hosts=IP_PROVEEDOR_SIP          ; IP o FQDN del SBC del carrier (admite lista separada por comas)
registration/contact_user=TU_NUMERO_DID ; DID que anunciarás al registrar
outbound_auth/username=USUARIO_SIP     ; Usuario SIP entregado por el proveedor
outbound_auth/password=PASSWORD_SIP     ; Contraseña SIP
endpoint/from_user=USUARIO_SIP         ; Usuario que saldrá en la cabecera From
endpoint/from_domain=FQDN_PROVEEDOR    ; Dominio SIP del carrier (evita 403)
endpoint/allow=!all,ulaw,alaw,g729     ; Incluye g729 si compraste la licencia/códec
identify/endpoint=mi-proveedor-sip     ; Vincula la IP de origen con este endpoint
identify/match=IP_PROVEEDOR_SIP/32     ; IP autorizada (ajusta máscara según rango)
; outbound_proxy=sip:IP_PROVEEDOR_SIP:5060 ; Descomenta si tu carrier exige proxy explícito

¿Qué hace cada opción clave?

• sends_auth=yes / sends_registrations=yes: El wizard crea automáticamente los objetos auth y registration para enviar usuario/contraseña al carrier.
• endpoint/context=from-trunk: Todo INVITE entrante saltará a ese contexto en tu dialplan (extensions.conf).
• endpoint/direct_media=no: El audio siempre pasa por Asterisk (permite grabar, escuchar, aplicar filtros). Útil para laboratorios.
• aor/qualify_frequency: Marca cada cuántos segundos se envía un OPTIONS para saber si la troncal sigue viva. Si el proveedor responde lento, aumenta el valor.
• identify_by=ip + identify/match: Seguridad básica: solo acepta tráfico SIP desde las IPs autorizadas.
• endpoint/from_user / endpoint/from_domain: Ajustan el encabezado SIP From: para coincidir con lo que el carrier espera. Sin esto, podrías recibir 403 Forbidden.
• endpoint/allow: Ordena la lista de códecs preferidos. !all limpia la lista y luego se añaden los permitidos.

¡Reemplaza los Placeholders!

• IP_PROVEEDOR_SIP
• USUARIO_SIP
• PASSWORD_SIP
• TU_NUMERO_DID
• FQDN_PROVEEDOR

¿Qué crea esta plantilla de troncal?

• Endpoint (endpoint): define códecs, contexto y parámetros NAT para llamadas entrantes/salientes.
• AOR (aor): gestiona la dirección del proveedor y el qualify para saber si sigue vivo.
• Auth (outbound_auth): contiene usuario/contraseña del carrier.
• Registration: gracias a sends_registrations=yes, el wizard genera mi-proveedor-sip y envía REGISTER en nombre de la PBX.
• Identify: protege las rutas entrantes, aceptando solo la IP del proveedor.

Aquí tienes algunas fuentes útiles para ampliar la configuración: PJSIP Configuration Wizard (Asterisk Docs) y Performance Tuning.

Checklist rápido para la troncal

• ¿Se creó el archivo /etc/asterisk/pjsip_wizard.conf? (ls -l)
• ¿Los placeholders (IP_PROVEEDOR_SIP, USUARIO_SIP, etc.) se reemplazaron?
• ¿Se abrió el firewall para la IP del carrier? (ufw status o firewall-cmd --list-rich-rules)
• ¿El REGISTER responde 200 OK? (sngrep o pjsip show registrations)
• ¿La IP entrante aparece en pjsip show identify mi-proveedor-sip?

Recarga y verifica registro:

asterisk -rx "pjsip reload"
asterisk -rvvv
*CLI> pjsip show registrations
*CLI> pjsip show endpoint mi-proveedor-sip
*CLI> pjsip show identify mi-proveedor-sip-identify

Diagnóstico express

• sngrep para capturar REGISTER/INVITE y confirmar que llega respuesta 200 OK.
• pjsip show auth <nombre> valida usuario/contraseña entregados por el carrier.
• pjsip show contacts mi-proveedor-sip te dice si la IP remota quedó registrada.
• Revisa pjsip show identify para confirmar que la IP entrante coincide con la lista permitida.

---

7.3 El Dialplan: Rutas de Entrada y Salida

Antes de continuar, confirma que extensions.conf incluye los archivos modulares creados en el Taller 5 y que defines el identificador de troncal en [globals].

[general]
static=yes                  ; Si es 'yes', Asterisk no sobrescribe este archivo
writeprotect=no             ; Ajusta a 'yes' si deseas impedir cambios desde CLI (dialplan save)
autofallthrough=yes         ; Evita que la llamada quede colgada si una extensión termina sin Hangup
clearglobalvars=no          ; Mantiene las variables globales entre recargas de dialplan
priorityjumping=no          ; Recomendado: evita saltos implícitos de prioridad

[globals]
IDTRUNK=TU_NUMERO_DID       ; Valor que reutilizaremos como CallerID de la troncal
CONTEXT_ENTRADAS=from-trunk ; Contexto centralizado para llamadas entrantes

#include extensions_anexos.conf
#include extensions_salidas.conf
#include extensions_funciones.conf
#include extensions_categorias.conf

7.3.1 Contexto para Llamadas Entrantes

Puedes usar extensions_salidas.conf o crear extensions_entradas.conf.

nano /etc/asterisk/extensions_salidas.conf

[from-trunk]
exten => s,1,NoOp(Llamada entrante desde ${CALLERID(num)} a nuestro DID)
    same => n,Dial(PJSIP/1001,30)
    same => n,Hangup()

; Estructura sugerida con comentarios
[from-trunk]
exten => s,1,NoOp(Llamada entrante desde ${CALLERID(num)} a nuestro DID)
    same => n,Set(CHANNEL(language)=es)               ; Asegura locuciones en español
    same => n,Set(CDR(accountcode)=TRONCAL_SIP)        ; Marca las llamadas para reportes
    same => n,Dial(PJSIP/1001,30)                      ; Ruta al anexo 1001 durante 30 s
    same => n,Hangup()

Personaliza tus rutas entrantes

• Usa GotoIfTime() para enviar llamadas a IVR fuera del horario laboral.
• Aplica Set(CALLERID(name)="Cliente ${CALLERID(num)}") para mostrar etiquetas amigables.
• Añade Playback(custom-bienvenida) antes del Dial() para mensajes de bienvenida.

7.3.2 Contextos de Salida (extensions_salidas.conf)

En el Taller 5 separamos la lógica de salida en extensions_salidas.conf. Aquí lo extendemos para manejar teléfonos fijos, celulares, larga distancia nacional (LDN) e internacional (LDI) usando la troncal mi-proveedor-sip y el IDTRUNK definido en [globals].

; /etc/asterisk/extensions_salidas.conf
[salidas-fijo]
exten => _[2-7]XXXXXX,1,NoOp(Llamada saliente a fijo peruano: ${EXTEN})
    same => n,Set(CALLERID(num)=${IDTRUNK})
    same => n,Dial(PJSIP/${EXTEN}@mi-proveedor-sip,45,T)
    same => n,Hangup()

[salidas-celular]
exten => _9XXXXXXXX,1,NoOp(Llamada saliente a celular: ${EXTEN})
    same => n,NoOp(CallerID original: ${CALLERID(num)})
    same => n,AGI(callerid_roulette.py)               ; Taller 5: rota CallerID
    same => n,Set(CHANNEL(language)=es)
    same => n,NoOp(CallerID luego de AGI: ${CALLERID(num)})
    same => n,Dial(PJSIP/${EXTEN}@mi-proveedor-sip,45,T)
    same => n,Hangup()

[salidas-ldn]
exten => _0NX[2-7]XXXXX,1,NoOp(Llamada LDN (larga distancia nacional): ${EXTEN})
    same => n,Set(CALLERID(num)=${IDTRUNK})
    same => n,Dial(PJSIP/${EXTEN}@mi-proveedor-sip,45,T)
    same => n,Hangup()

[salidas-ldi]
exten => _00.,1,NoOp(Llamada LDI (internacional): ${EXTEN})
    same => n,Set(CALLERID(num)=${IDTRUNK})
    same => n,Dial(PJSIP/${EXTEN}@mi-proveedor-sip,60,T)
    same => n,Hangup()

Personaliza según tu país

• Ajusta los patrones _9XXXXXXXX, _0NX[2-7]XXXXX y _00. a la numeración del operador.
• Si tu carrier exige prefijos (por ejemplo 011, 51, 00), añade same => n,Set(DIAL_NUMBER=...) y concatena antes de Dial().
• Añade Set(CDR(userfield)=CELULAR|FIJO|LDN|LDI) para reportes de facturación.

Si necesitas lógica adicional para los celulares (música en espera, bloqueo cuando 1001 está ocupado) puedes extender solo ese contexto:

; Variante avanzada para [salidas-celular]
[salidas-celular]
exten => _9XXXXXXXX,1,NoOp(Llamada saliente a celular: ${EXTEN})
    same => n,ExecIf($["${DEVICE_STATE(PJSIP/1001)}"="BUSY"]?Playback(all-circuits-busy-now))
    same => n,AGI(callerid_roulette.py)
    same => n,NoOp(CallerID modificado por AGI: ${CALLERID(num)})
    same => n,Set(CHANNEL(language)=es)
    same => n,Dial(PJSIP/${EXTEN}@mi-proveedor-sip,45,Tb(func-meanwhile,s,1))
    same => n,Hangup()

Actualiza extensions_categorias.conf para conceder permisos de manera progresiva, tal como definimos en talleres anteriores:

; /etc/asterisk/extensions_categorias.conf
[cat1]
include => anexos-internos
include => funciones-voicemail
include => salidas-fijo
include => salidas-celular
include => salidas-ldn
include => salidas-ldi

[cat2]
include => anexos-internos
include => funciones-voicemail
include => salidas-fijo
include => salidas-celular

[cat3]
include => anexos-internos
include => funciones-voicemail
include => salidas-celular

Checklist de categorías

• Verifica con asterisk -rx "dialplan show cat1" que los includes se cargan.
• Cuando crees nuevas rutas (salidas-0800, salidas-empresarial), agrégalas a las categorías correctas.
• Ajusta los context de cada anexo en pjsip_wizard.conf (endpoint/context=catX) para heredar los permisos adecuados.

7.3.3 Recarga y Firewall

asterisk -rx "dialplan reload"

# Permite el tráfico desde la IP del proveedor
ufw allow from IP_PROVEEDOR_SIP to any port 5060 proto udp
ufw allow from IP_PROVEEDOR_SIP to any port 10000:20000 proto udp

---

7.4 ¡A Probar la Conexión con el Mundo!

7.4.1 Prueba de Salida

• Abre el CLI: asterisk -rvvv.
• Desde la extensión 1001 (permiso cat1), marca un número real.
• Observa ejecución de AGI, cambio de CallerID y envío por mi-proveedor-sip.
• Ejecuta sngrep para validar la señalización.
• Comprueba el estado con pjsip show channels para ver la llamada activa.

7.4.2 Prueba de Entrada

• Desde tu celular, llama a tu DID.
• Observa ingreso en from-trunk y timbrado en 1001.
• Usa asterisk -rx "core show channel <canal>" para confirmar códecs y variables.
• Verifica que el endpoint correcto atiende la llamada con pjsip show channel <ID>.

Script de validación rápida

Crea validaciones/troncales.sh:

#!/bin/bash
asterisk -rx "pjsip show registrations"
asterisk -rx "pjsip show contacts"
asterisk -rx "dialplan show from-trunk"
asterisk -rx "pjsip show channels"

Agrégalo a cron para detectar fallas de registro.

¿Problemas con el códec G729?

Si tu carrier exige G729 y cuentas con licencia, consulta el procedimiento del curso antiguo (Taller 8). Resumen rápido:

1. Identifica tu arquitectura con cat /proc/cpuinfo.
2. Descarga la biblioteca adecuada desde asterisk.hosting.lv.
3. Copia el archivo renombrado a /usr/lib64/asterisk/modules/ y cárgalo con asterisk -rx "module load codec_g729.so".
4. Confirma su disponibilidad ejecutando asterisk -rx "core show translation".

¡Tu PBX ya está conectada al mundo exterior usando las mejores prácticas!

---

7.5 Rendimiento, Límites del Sistema y Buenas Prácticas

7.5.1 Afinar el desempeño de PJSIP

• Threadpool: asterisk -rx "core show threads" y core show taskprocessors para monitorear.
• Timers SIP: Ajusta timer_t1=500, timer_b=32000 si tienes retardos.
• Sorcery cache: En sorcery.conf usa memory_cache o redis para cientos de endpoints.

¿Qué pasa con los mensajes SIP muy grandes?

El equipo de PJSIP documenta en PJSIP Large Messages que las peticiones SIP pueden superar el tamaño estándar (por ejemplo, SUBSCRIBE o INVITE con cabeceras extensas). Asterisk permite controlarlo con:

[transport-udp-nat]
type=transport
; ...
max_msg_size=20480    ; Ajusta el tamaño máximo (en bytes) que aceptará el transporte

• Si recibes errores SIP message too large, incrementa max_msg_size gradualmente.
• Define valores coherentes con tus límites de red y con los carriers para evitar ataques de amplificación.
• Para TLS/TCP, replica el ajuste en el transporte correspondiente (transport-tcp, transport-tls).
• Monitorea pjsip set logger on mientras haces pruebas para verificar que el mensaje se procesa completo.

7.5.2 Descriptores de archivo (asterisk.conf)

[options]
maxfiles = 32768
maxload = 5.0
corelimit = 1000000

• Reinicia Asterisk y verifica con asterisk -rx "core show settings".
• Sincroniza LimitNOFILE en systemd creando /etc/systemd/system/asterisk.service.d/limits.conf.

7.5.3 Checklist operativo

• Firewall: Documenta IPs del carrier y automatiza actualizaciones.
• Logs: Configura logger.conf para canal pjsip_wizard.
• Auditoría: pjsip show history para limpiar endpoints sin uso.

Valores sugeridos ≠ valores definitivos

Cada implementación requiere pruebas de carga. Usa sipp u otra herramienta para ajustar threadpool_max_size y maxfiles antes de producción. En Asterisk Avanzado vemos mas detalles.