Como Corrigir Erros de Federação ‘TLS Handshake Failed’ no Mastodon

Instâncias do Mastodon que falham ao se comunicar geralmente exibem o erro “TLS handshake failed” nos logs ou no painel de administração. Esse erro impede sua instância de receber postagens de servidores remotos e impede que seus usuários sigam contas em outras instâncias. A causa raiz quase sempre é um certificado TLS mal configurado, uma biblioteca de sistema desatualizada ou um firewall bloqueando as portas necessárias. Este artigo explica por que o handshake TLS falha entre instâncias do Mastodon e fornece correções passo a passo para as três causas mais comuns.

Por que o Handshake TLS Falha Entre Instâncias do Mastodon

O Mastodon usa o protocolo ActivityPub para trocar mensagens entre instâncias. Cada solicitação de federação começa com um handshake TLS sobre HTTPS. Se esse handshake falhar, a instância remetente registra um erro “TLS handshake failed” e não entrega a mensagem.

O handshake pode falhar por três motivos principais:

Certificado TLS Expirado ou Inválido

O certificado TLS da sua instância deve ser válido, não expirado e confiável pela instância remota. Se você usa Let’s Encrypt, o certificado é renovado automaticamente a cada 60 dias. No entanto, se o processo de renovação falhar porque o cliente ACME não consegue alcançar o servidor de validação, o certificado expira e a federação quebra. Um certificado intermediário ausente também causa falhas de handshake porque a instância remota não consegue construir uma cadeia de confiança completa.

Pacotes OpenSSL ou ca-certificates Desatualizados

Instâncias do Mastodon que rodam em sistemas operacionais mais antigos podem ter OpenSSL 1.0.2 ou anterior. Muitas instâncias modernas exigem TLS 1.2 ou TLS 1.3. Se seu servidor suporta apenas TLS 1.0 ou TLS 1.1, a negociação do handshake falha. O pacote ca-certificates também deve estar atualizado para que seu servidor confie em autoridades certificadoras modernas.

Firewall ou Proxy Reverso Mal Configurado

Um firewall que bloqueia a porta TCP 443 de saída impede que sua instância alcance servidores remotos. Da mesma forma, um proxy reverso como Nginx que termina o TLS incorretamente pode enviar cadeias de certificados incompletas. A mensagem de erro nos logs do Mastodon geralmente diz “connection refused” ou “timeout” quando o problema real é uma regra de firewall.

Passos para Diagnosticar e Corrigir Erros de Handshake TLS

Execute estes passos em ordem. Teste a federação após cada passo para evitar reiniciar serviços desnecessariamente.

1. Verifique o log de federação do Mastodon para o erro exato
   Abra um terminal no seu servidor Mastodon. Execute tail -f /home/mastodon/live/log/production.log | grep -i "tls". Procure linhas que contenham “TLS handshake failed” e anote o nome do domínio remoto. Isso informa qual instância está falhando ao conectar.
2. Verifique seu próprio certificado TLS com uma ferramenta externa
   Use o SSL Labs Server Test em ssllabs.com/ssltest. Insira seu domínio do Mastodon. Aguarde a varredura ser concluída. Verifique estes problemas: certificado expirado, certificado intermediário ausente ou suporte a cifras fracas. Se a nota for inferior a B, corrija a cadeia de certificados primeiro.
3. Renove o certificado Let’s Encrypt manualmente
   Se o certificado estiver expirado ou com intermediários ausentes, execute sudo certbot renew --force-renewal --post-hook "systemctl reload nginx". Em seguida, verifique o novo certificado com sudo openssl x509 -in /etc/letsencrypt/live/seuDominio/fullchain.pem -text -noout | grep "Subject:". Certifique-se de que o arquivo fullchain.pem contenha tanto o certificado do servidor quanto o certificado intermediário.
4. Atualize os pacotes OpenSSL e ca-certificates
   No Ubuntu ou Debian, execute sudo apt update && sudo apt upgrade openssl ca-certificates -y. No CentOS ou Fedora, execute sudo yum update openssl ca-certificates -y. Reinicie o servidor ou reinicie o Mastodon com systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming.
5. Teste a conectividade TLS de saída para uma instância remota
   Use o comando openssl para simular um handshake: openssl s_client -connect instanciaRemota.social:443 -servername instanciaRemota.social. Se a saída mostrar “CONNECTED” e uma cadeia de certificados, o TLS está funcionando. Se mostrar “connect: Connection refused”, um firewall está bloqueando a porta 443 de saída.
6. Verifique as regras de firewall no seu servidor
   Execute sudo iptables -L -n | grep 443 para ver regras de saída. Se você usa ufw, execute sudo ufw status. Certifique-se de que a porta TCP 443 de saída esteja permitida. Se você usa um firewall em nuvem como AWS Security Groups ou DigitalOcean Cloud Firewall, verifique se o tráfego HTTPS de saída não está restrito.
7. Reinicie o Mastodon e teste a federação
   Após aplicar qualquer correção, reinicie todos os serviços do Mastodon: systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming. Em seguida, tente seguir uma conta de teste em uma instância conhecida como mastodon.social. Verifique os logs novamente em busca de erros TLS.

Se o Mastodon Ainda Apresentar Erros de Handshake TLS

Cadeia de Certificados Não Enviada pelo Proxy Reverso Nginx

Se a configuração do Nginx não incluir a cadeia completa de certificados, as instâncias remotas veem apenas o certificado folha e rejeitam o handshake. Abra a configuração do site Nginx em /etc/nginx/sites-available/seuDominio. Verifique se a diretiva ssl_certificate aponta para o arquivo fullchain.pem, não para cert.pem. A linha correta é ssl_certificate /etc/letsencrypt/live/seuDominio/fullchain.pem;. Após editar, execute sudo nginx -t e depois sudo systemctl reload nginx.

Versão TLS Desatualizada no Nginx

Alguns administradores desabilitam versões TLS antigas no Nginx, mas acidentalmente também desabilitam o TLS 1.2. Verifique a linha ssl_protocols na configuração do Nginx. Deve ser ssl_protocols TLSv1.2 TLSv1.3;. Se listar apenas TLSv1.3, algumas instâncias remotas que não suportam TLS 1.3 falharão no handshake. Adicione TLSv1.2 de volta e recarregue o Nginx.

Falha na Resolução de DNS Mascarada como Erro TLS

Se seu servidor não conseguir resolver o nome de domínio da instância remota, o handshake TLS nunca começa. Execute dig instanciaRemota.social no seu servidor Mastodon. Se a seção de resposta estiver vazia ou mostrar SERVFAIL, seu resolvedor DNS está quebrado. Edite /etc/resolv.conf para usar um resolvedor público como 1.1.1.1 ou 8.8.8.8. Depois, teste a federação novamente.

Falha de Handshake TLS vs Outros Erros de Federação

Item	TLS Handshake Failed	Connection Timeout
Descrição	Negociação SSL/TLS falha durante o handshake	Servidor remoto não responde dentro do tempo limite
Causa raiz	Certificado expirado, intermediário ausente, OpenSSL desatualizado, firewall bloqueando porta 443	Servidor remoto fora do ar, congestionamento de rede, firewall descartando pacotes
Erro nos logs do Mastodon	“TLS handshake failed” com o domínio remoto	“Connection refused” ou “timed out”
Correção	Renovar certificado, atualizar pacotes, corrigir configuração do Nginx, permitir porta 443 de saída	Aguardar e tentar novamente, contatar administrador remoto, verificar firewall de saída

A tabela acima ajuda a distinguir entre uma falha de handshake TLS e um simples timeout de conexão. Se você vir “connection refused” nos logs, a instância remota pode estar fora do ar para manutenção. Se vir “TLS handshake failed”, o problema está quase sempre do seu lado ou na configuração do certificado do lado remoto.

Agora você pode diagnosticar e corrigir falhas de handshake TLS que impedem sua instância do Mastodon de federar com outros servidores. Comece verificando seu certificado com SSL Labs, depois atualize os pacotes do sistema. Se o problema persistir, verifique se a configuração do Nginx envia a cadeia completa de certificados e se seu firewall permite a porta 443 de saída. Para monitoramento contínuo, configure um cron job que execute certbot renew semanalmente e envie uma notificação se a renovação falhar.