Cómo solucionar los errores de federación ‘TLS handshake failed’ en Mastodon

Las instancias de Mastodon que no logran comunicarse entre sí a menudo muestran un error “TLS handshake failed” en los registros del servidor o en el panel de administración. Este error impide que tu instancia reciba publicaciones de servidores remotos y evita que tus usuarios sigan cuentas en otras instancias. La causa raíz casi siempre es un certificado TLS mal configurado, una biblioteca del sistema desactualizada o un cortafuegos que bloquea los puertos necesarios. Este artículo explica por qué falla el handshake TLS entre instancias de Mastodon y proporciona soluciones paso a paso para las tres causas más comunes.

Por qué falla el handshake TLS entre instancias de Mastodon

Mastodon utiliza el protocolo ActivityPub para intercambiar mensajes entre instancias. Cada solicitud de federación comienza con un handshake TLS sobre HTTPS. Si ese handshake falla, la instancia emisora registra un error “TLS handshake failed” y no entrega el mensaje.

El handshake puede fallar por tres razones principales:

Certificado TLS caducado o no válido

El certificado TLS de tu instancia debe ser válido, no estar caducado y ser de confianza para la instancia remota. Si usas Let’s Encrypt, el certificado se renueva automáticamente cada 60 días. Sin embargo, si el proceso de renovación falla porque el cliente ACME no puede alcanzar el servidor de validación, el certificado caduca y la federación se rompe. Un certificado intermedio faltante también causa fallos de handshake porque la instancia remota no puede construir una cadena de confianza completa.

Paquete OpenSSL o ca-certificates desactualizado

Las instancias de Mastodon que se ejecutan en sistemas operativos más antiguos pueden tener OpenSSL 1.0.2 o anterior. Muchas instancias modernas requieren TLS 1.2 o TLS 1.3. Si tu servidor solo admite TLS 1.0 o TLS 1.1, la negociación del handshake falla. El paquete ca-certificates también debe estar actualizado para que tu servidor confíe en las autoridades de certificación modernas.

Cortafuegos o proxy inverso mal configurado

Un cortafuegos que bloquea el puerto TCP 443 de salida impide que tu instancia alcance servidores remotos. De manera similar, un proxy inverso como Nginx que termina TLS incorrectamente puede enviar cadenas de certificados incompletas. El mensaje de error en los registros de Mastodon a menudo dice “connection refused” o “timeout” cuando el problema real es una regla de cortafuegos.

Pasos para diagnosticar y solucionar errores de handshake TLS

Realiza estos pasos en orden. Prueba la federación después de cada paso para evitar reiniciar servicios innecesariamente.

1. Revisa el registro de federación de Mastodon para ver el error exacto
   Abre una terminal en tu servidor Mastodon. Ejecuta tail -f /home/mastodon/live/log/production.log | grep -i "tls". Busca líneas que contengan “TLS handshake failed” y anota el nombre del dominio remoto. Esto te indica qué instancia no puede conectarse.
2. Verifica tu propio certificado TLS con una herramienta externa
   Usa la prueba SSL Labs Server en ssllabs.com/ssltest. Introduce tu dominio de Mastodon. Espera a que finalice el análisis. Busca estos problemas: certificado caducado, certificado intermedio faltante o soporte de cifrado débil. Si la calificación es inferior a B, corrige primero la cadena de certificados.
3. Renueva manualmente el certificado Let’s Encrypt
   Si el certificado está caducado o faltan intermedios, ejecuta sudo certbot renew --force-renewal --post-hook "systemctl reload nginx". Luego verifica el nuevo certificado con sudo openssl x509 -in /etc/letsencrypt/live/yourdomain/fullchain.pem -text -noout | grep "Subject:". Asegúrate de que el archivo fullchain.pem contenga tanto el certificado de tu servidor como el certificado intermedio.
4. Actualiza los paquetes OpenSSL y ca-certificates
   En Ubuntu o Debian, ejecuta sudo apt update && sudo apt upgrade openssl ca-certificates -y. En CentOS o Fedora, ejecuta sudo yum update openssl ca-certificates -y. Reinicia el servidor o reinicia Mastodon con systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming.
5. Prueba la conectividad TLS de salida hacia una instancia remota
   Usa el comando openssl para simular un handshake: openssl s_client -connect remoteinstance.social:443 -servername remoteinstance.social. Si la salida muestra “CONNECTED” y una cadena de certificados, TLS funciona. Si muestra “connect: Connection refused”, un cortafuegos está bloqueando el puerto 443 de salida.
6. Revisa las reglas del cortafuegos en tu servidor
   Ejecuta sudo iptables -L -n | grep 443 para ver las reglas de salida. Si usas ufw, ejecuta sudo ufw status. Asegúrate de que el puerto TCP 443 de salida esté permitido. Si usas un cortafuegos en la nube como AWS Security Groups o DigitalOcean Cloud Firewall, verifica que el tráfico HTTPS de salida no esté restringido.
7. Reinicia Mastodon y prueba la federación
   Después de aplicar cualquier solución, reinicia todos los servicios de Mastodon: systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming. Luego intenta seguir una cuenta de prueba en una instancia que funcione conocida como mastodon.social. Revisa los registros nuevamente en busca de errores TLS.

Si Mastodon sigue teniendo errores de handshake TLS

El proxy inverso Nginx no envía la cadena de certificados

Si tu configuración de Nginx no incluye la cadena de certificados completa, las instancias remotas solo ven el certificado final y rechazan el handshake. Abre la configuración de tu sitio en Nginx en /etc/nginx/sites-available/yourdomain. Verifica que la directiva ssl_certificate apunte al archivo fullchain.pem, no a cert.pem. La línea correcta es ssl_certificate /etc/letsencrypt/live/yourdomain/fullchain.pem;. Después de editar, ejecuta sudo nginx -t y luego sudo systemctl reload nginx.

Versión de TLS obsoleta en Nginx

Algunos administradores deshabilitan versiones antiguas de TLS en Nginx pero accidentalmente también deshabilitan TLS 1.2. Revisa la línea ssl_protocols en tu configuración de Nginx. Debería decir ssl_protocols TLSv1.2 TLSv1.3;. Si solo enumera TLSv1.3, algunas instancias remotas que no admiten TLS 1.3 fallarán el handshake. Vuelve a agregar TLSv1.2 y recarga Nginx.

Fallo de resolución DNS enmascarado como error TLS

Si tu servidor no puede resolver el nombre de dominio de la instancia remota, el handshake TLS nunca comienza. Ejecuta dig remoteinstance.social en tu servidor Mastodon. Si la sección de respuesta está vacía o muestra SERVFAIL, tu resolución DNS está rota. Edita /etc/resolv.conf para usar un resolutor público como 1.1.1.1 o 8.8.8.8. Luego prueba la federación nuevamente.

Fallo de handshake TLS frente a otros errores de federación

Elemento	TLS Handshake Failed	Connection Timeout
Descripción	La negociación SSL/TLS falla durante el handshake	El servidor remoto no responde dentro del tiempo de espera
Causa raíz	Certificado caducado, intermedio faltante, OpenSSL obsoleto, cortafuegos que bloquea el puerto 443	Servidor remoto caído, congestión de red, cortafuegos que descarta paquetes
Error en los registros de Mastodon	“TLS handshake failed” con dominio remoto	“Connection refused” o “timed out”
Solución	Renovar certificado, actualizar paquetes, corregir configuración de Nginx, permitir salida 443	Esperar y reintentar, contactar al administrador remoto, revisar tu cortafuegos de salida

La tabla anterior te ayuda a distinguir entre un fallo de handshake TLS y un simple tiempo de espera de conexión. Si ves “connection refused” en los registros, la instancia remota puede estar en mantenimiento. Si ves “TLS handshake failed”, el problema casi siempre está de tu lado o en la configuración del certificado del lado remoto.

Ahora puedes diagnosticar y solucionar los fallos de handshake TLS que impiden que tu instancia de Mastodon se federe con otros servidores. Comienza verificando tu certificado con SSL Labs, luego actualiza los paquetes de tu sistema. Si el problema persiste, verifica que tu configuración de Nginx envíe la cadena de certificados completa y que tu cortafuegos permita el puerto 443 de salida. Para monitoreo continuo, configura un trabajo cron que ejecute certbot renew semanalmente y envíe una notificación si la renovación falla.