--- title: "Cómo instalar FreeSWITCH en Debian 12 como servidor VoIP" description: "Instala FreeSWITCH en Debian 12 desde el repositorio oficial de SignalWire, protege la configuración por defecto, registra extensiones y conecta un trunk SIP." category: "VoIP y Comunicación" language: es source: https://cubepath.com/es/docs/voip-y-comunicación/instalacion-de-freeswitch-servidor-voip updated: 2026-09-25 --- # Cómo instalar FreeSWITCH en Debian 12 como servidor VoIP FreeSWITCH es una plataforma de telefonía de código abierto capaz de actuar como centralita SIP, servidor de conferencias, IVR o pasarela WebRTC. En este tutorial instalarás FreeSWITCH en Debian 12 desde el repositorio oficial de paquetes de SignalWire, cerrarás los puntos débiles de la configuración de ejemplo, registrarás dos extensiones con un softphone y conectarás un trunk SIP de un proveedor para hacer y recibir llamadas externas. ## Requisitos previos - Un servidor con Debian 12 (bookworm) de 64 bits, por ejemplo un VPS de CubePath con IP pública. Los paquetes oficiales de FreeSWITCH se publican para Debian; en Ubuntu tendrías que compilar desde el código fuente. - 2 GB de RAM como mínimo. - Un usuario no root con privilegios `sudo`. - Una cuenta gratuita en [SignalWire](https://signalwire.com) para generar un token de acceso personal (Personal Access Token), necesario para descargar los paquetes. - Un softphone SIP en tu ordenador o móvil, como Linphone, MicroSIP o Zoiper. - Opcional: una cuenta con un proveedor de trunk SIP (usuario, contraseña y servidor) para llamadas externas. ## Paso 1: Obtener el token de SignalWire El repositorio de paquetes de FreeSWITCH requiere autenticación con un token de SignalWire. En el panel de SignalWire, abre tu perfil, entra en **Personal Access Tokens** y crea un token nuevo. Los tokens de la edición Community empiezan por `pat_`. Guárdalo en una variable de la sesión actual para usarlo en los siguientes comandos: ```bash read -rs FS_TOKEN ``` Pega el token y pulsa Intro. Con `-s` no se muestra en pantalla ni queda en el historial del shell. ## Paso 2: Añadir el repositorio oficial e instalar FreeSWITCH Instala las herramientas necesarias: ```bash sudo apt update sudo apt install curl gnupg2 ca-certificates ``` apt necesita el token para descargar del repositorio. Guárdalo en un archivo de credenciales de apt que solo root pueda leer: ```bash echo "machine freeswitch.signalwire.com login signalwire password ${FS_TOKEN}" | sudo tee /etc/apt/auth.conf.d/freeswitch.conf > /dev/null sudo chmod 600 /etc/apt/auth.conf.d/freeswitch.conf ``` Descarga la clave de firma del repositorio en `/etc/apt/keyrings`: ```bash sudo install -m 0755 -d /etc/apt/keyrings sudo curl --fail --netrc-file /etc/apt/auth.conf.d/freeswitch.conf \ -o /etc/apt/keyrings/signalwire-freeswitch-repo.gpg \ https://freeswitch.signalwire.com/repo/deb/debian-release/signalwire-freeswitch-repo.gpg ``` Crea el archivo del repositorio en formato deb822: ```bash sudo tee /etc/apt/sources.list.d/freeswitch.sources > /dev/null < ``` ### Cerrar el Event Socket El módulo Event Socket (puerto 8021) permite controlar FreeSWITCH por completo, y en la configuración de ejemplo escucha en todas las interfaces con la contraseña `ClueCon`. Limítalo a localhost: ```bash sudo nano /etc/freeswitch/autoload_configs/event_socket.conf.xml ``` ```xml ``` `fs_cli` se conecta a `127.0.0.1:8021` con la contraseña `ClueCon`, así que seguirá funcionando. Si cambias también la contraseña, tendrás que pasársela con `fs_cli -p`. Reinicia FreeSWITCH para aplicar ambos cambios y comprueba que el Event Socket ya solo escucha en localhost: ```bash sudo systemctl restart freeswitch sudo ss -tlpn | grep 8021 ``` ```output LISTEN 0 30 127.0.0.1:8021 0.0.0.0:* users:(("freeswitch",pid=5310,fd=41)) ``` ## Paso 4: Configurar el firewall FreeSWITCH usa dos perfiles SIP: `internal` (puerto 5060) para tus extensiones y `external` (puerto 5080) para los trunks de proveedores. El audio viaja por RTP en un rango de puertos UDP. Debian 12 no trae UFW instalado; instálalo y permite SSH antes de activarlo: ```bash sudo apt install ufw sudo ufw allow OpenSSH ``` El puerto 5060 recibe escaneos constantes de bots que prueban contraseñas SIP. Si tus usuarios se conectan desde IP conocidas, abre el perfil interno solo para ellas (sustituye `your_office_ip`): ```bash sudo ufw allow from your_office_ip to any port 5060 proto udp sudo ufw allow from your_office_ip to any port 5060 proto tcp ``` Abre el perfil externo para tu proveedor (sustituye `provider_ip` por la IP o rango que te indique) y el rango RTP: ```bash sudo ufw allow from provider_ip to any port 5080 proto udp sudo ufw allow 16384:32768/udp sudo ufw enable sudo ufw status ``` > Nota: si tus usuarios se conectan desde IP dinámicas y tienes que abrir el 5060 a todo internet, usa contraseñas largas y considera instalar fail2ban con un filtro para FreeSWITCH. ## Paso 5: Registrar extensiones y hacer una llamada de prueba Comprueba que los dos perfiles SIP están activos: ```bash sudo fs_cli -x "sofia status" ``` ```output Name Type Data State ================================================================================================= external profile sip:mod_sofia@203.0.113.10:5080 RUNNING (0) internal profile sip:mod_sofia@203.0.113.10:5060 RUNNING (0) ... ``` Configura el softphone con estos datos: - **Usuario / extensión**: `1000` - **Contraseña**: la que pusiste en `default_password` - **Dominio o servidor**: `your_server_ip` - **Puerto**: `5060`, transporte UDP Verifica el registro desde el servidor: ```bash sudo fs_cli -x "show registrations" ``` ```output reg_user,realm,token,url,expires,network_ip,network_port,network_proto,hostname,metadata 1000,203.0.113.10,...,sofia/internal/sip:1000@198.51.100.20:5060,... 1 total. ``` Llama al `9196`: es la prueba de eco del dialplan de ejemplo y te devuelve tu propia voz. Si te oyes, la señalización SIP y el audio RTP funcionan. Registra otro dispositivo como `1001` y llama de uno a otro para probar llamadas internas. Otras extensiones útiles del dialplan de ejemplo son el `5000` (IVR de demostración) y el `3000` (sala de conferencias). ## Paso 6: Conectar un trunk SIP Para llamar a números externos, define un gateway en el perfil `external`. FreeSWITCH carga todos los archivos `.xml` de `/etc/freeswitch/sip_profiles/external/`: ```bash sudo nano /etc/freeswitch/sip_profiles/external/mi_proveedor.xml ``` ```xml ``` Vuelve a leer la configuración del perfil y comprueba el estado del gateway: ```bash sudo fs_cli -x "sofia profile external rescan" sudo fs_cli -x "sofia status gateway mi_proveedor" ``` Busca la línea `State`: el valor `REGED` indica que el proveedor ha aceptado el registro. ```output State REGED ``` ### Llamadas salientes Añade una regla al dialplan `default` que envíe por el gateway los números que empiecen por `0`, quitando ese prefijo. FreeSWITCH incluye los archivos de `/etc/freeswitch/dialplan/default/`: ```bash sudo nano /etc/freeswitch/dialplan/default/01_salientes.xml ``` ```xml ``` Sustituye `your_did` por el número que te ha asignado el proveedor. El formato del número de destino (con o sin prefijo internacional) depende del proveedor. ### Llamadas entrantes Las llamadas que llegan por el perfil `external` se procesan en el contexto `public`. Crea una regla que pase las llamadas a tu número a la extensión `1000`: ```bash sudo nano /etc/freeswitch/dialplan/public/01_entrantes.xml ``` ```xml ``` Recarga el XML y prueba una llamada saliente marcando `0` seguido de un número real, y una entrante llamando a tu número desde un móvil: ```bash sudo fs_cli -x "reloadxml" ``` ```output +OK [Success] ``` ## Solución de problemas Para ver qué ocurre durante una llamada, abre la consola interactiva y sube el nivel de log: ```bash sudo fs_cli ``` Dentro de la consola, `/log debug` muestra todo el detalle y `sofia global siptrace on` imprime los mensajes SIP. Sal con `/exit`. El log completo está en `/var/log/freeswitch/freeswitch.log`. **La llamada se establece pero no hay audio o solo se oye en un sentido.** Es casi siempre un problema de RTP: revisa que el rango `16384:32768/udp` está abierto y que la IP que anuncia FreeSWITCH es la pública. Compruébalo con `sudo fs_cli -x "sofia status profile internal" | grep -i ext-rtp-ip`. **El softphone no se registra (error 403).** La contraseña no coincide. Recuerda que el cambio en `vars.xml` requiere reiniciar el servicio. **El gateway queda en `FAIL_WAIT` o `UNREGED`.** Revisa usuario, contraseña y `realm` con los datos del proveedor, y que la regla de UFW permite su IP en el puerto 5080. ## Conclusión Tienes FreeSWITCH instalado en Debian 12 desde el repositorio oficial, con la configuración de ejemplo protegida, extensiones registradas y un trunk SIP para llamadas externas. Como siguientes pasos puedes sustituir las extensiones de ejemplo por las tuyas en `/etc/freeswitch/directory/default/`, añadir TLS al perfil interno para cifrar la señalización o habilitar `mod_verto` para llamar desde el navegador con WebRTC.