Como configurar um servidor TURN externo para o Jitsi atrás de um NAT

O ponto mais importante: um servidor TURN externo deve ser configurado como alternativa para clientes que não conseguem estabelecer uma conexão WebRTC utilizável devido a NAT ou firewalls restritivos. Ele não substitui o Jitsi Videobridge (JVB) em reuniões normais com vários participantes. Se o seu servidor Jitsi estiver atrás de um NAT, você ainda precisa tornar o JVB acessível pela Internet, normalmente na porta UDP 10000, ou configurar corretamente o endereço IP público anunciado pelo servidor.

Para as implementações atuais do Jitsi, o design mais limpo geralmente consiste em um host coturn acessível publicamente com um nome DNS como `<nome_do_host>` turn.example.com, credenciais com tempo limitado fornecidas pela Prosody através do XEP-0215 ​​e TURN sobre UDP/TCP, além de TURN sobre TLS para redes restritivas. A documentação atual do Jitsi sobre TURN recomenda explicitamente o uso de credenciais dinâmicas em vez de incorporar um nome de usuário e senha permanentes na configuração do navegador. Consulte a documentação oficial de configuração do TURN do Jitsi .

Quando um servidor TURN externo é a solução ideal

Use o protocolo TURN quando alguns participantes conseguirem acessar a página da web do Jitsi, mas não conseguirem estabelecer uma conexão de mídia confiável, especialmente em redes corporativas, Wi-Fi de hotéis, campi universitários, operadoras de celular, VPNs ou outros ambientes que bloqueiam ou filtram fortemente o UDP. O protocolo TURN também é útil para chamadas Jitsi individuais quando a conectividade ponto a ponto não pode ser estabelecida diretamente.

Não considere o TURN como a primeira solução para um Jitsi Videobridge mal configurado. O guia oficial do Jitsi para Debian/Ubuntu afirma que, quando o servidor está atrás de um NAT, o roteador deve encaminhar as portas necessárias e o bridge pode precisar de um mapeamento explícito de endereço local para público. Por padrão, as portas importantes para o Jitsi são TCP 443 e UDP 10000. Consulte o guia atual de auto-hospedagem do Jitsi para Debian/Ubuntu antes de adicionar o TURN.

Passo 1: Prepare um host TURN público e um DNS.

A topologia mais simples é uma VM ou servidor separado com um endereço IP público. Crie um registro A ou AAAA que turn.example.comresolva para esse host. Um nome de host dedicado é especialmente útil se você posteriormente oferecer TURN sobre TLS, pois o certificado deve corresponder ao nome de host usado pelos clientes.

Se o host TURN estiver atrás de um NAT, o coturn precisa saber o endereço público que deve anunciar. O coturn suporta um external-ipmapeamento, incluindo pares público/privado como external-ip=203.0.113.10/192.168.1.10. Sua documentação também observa que as portas de retransmissão devem ser mapeadas de forma consistente através do NAT. Consulte o exemplo de configuração oficial do coturn .

Passo 2: Instale o coturn

Em um sistema Debian ou Ubuntu compatível, instale o coturn a partir do repositório da distribuição:

sudo apt update
sudo apt install coturn

As versões dos pacotes variam de acordo com a versão do sistema operacional, portanto, não copie um número de versão de uma captura de tela ou de outro servidor. Após a instalação, confirme se a unidade de serviço existe e se o pacote foi instalado turnserver.

Etapa 3: Configure o coturn para autenticação com segredo compartilhado.

Para o Jitsi, uma configuração prática de produção utiliza o mecanismo de segredo compartilhado do Coturn para que o Prosody possa gerar credenciais TURN temporárias. Use o mesmo segredo em ambas as extremidades. Um ponto de partida mínimo seria o seguinte:

listening-port=3478
tls-listening-port=5349
realm=turn.example.com

fingerprint
use-auth-secret
static-auth-secret=REPLACE_WITH_A_LONG_RANDOM_SECRET

min-port=49160
max-port=49200

no-multicast-peers
no-cli

Se o host TURN estiver atrás de um NAT, adicione o external-ipmapeamento apropriado. Se você habilitar o TURN sobre TLS, configure- certo pkeycom um certificado confiável para turn.example.com. A documentação oficial do contêiner coturn explica que o TURN usa um intervalo de portas de retransmissão para mídia e que esse intervalo pode ser restringido com min-porte max-port. Consulte a documentação oficial do coturn para Docker para obter o mesmo comportamento de portas de retransmissão.

Passo 4: Abra as portas de escuta e de retransmissão.

Um erro comum é abrir apenas as portas 3478 ou 5349, esquecendo-se do intervalo de retransmissão. O listener do Coturn aceita a conexão TURN inicial, mas a mídia retransmitida usa as portas de retransmissão alocadas. Se você escolheu essa opção 49160-49200, permita esse mesmo intervalo através do firewall do host, do grupo de segurança da nuvem e de qualquer NAT upstream.

sudo ufw allow 3478/udp
sudo ufw allow 3478/tcp
sudo ufw allow 5349/tcp
sudo ufw allow 49160:49200/udp

Se você precisa da mais ampla compatibilidade com redes corporativas restritas, o guia TURN do Jitsi descreve como servir TURN sobre TLS na porta TCP 443. Isso pode exigir um nome de host TURN dedicado e, quando o HTTPS da web compartilha o mesmo endereço público, multiplexação TLS SNI. Não migre o TURN para a porta 443 sem antes entender quem já a utiliza.

Etapa 5: Configure o Jitsi para anunciar o serviço TURN externo.

Em uma instalação atual do pacote Jitsi no Debian/Ubuntu, o Prosody usa mod_external_servicespara publicar informações STUN/TURN para os clientes. O próprio exemplo do Jitsi para o Prosody usa uma external_service_secrettabela external_servicescom secret = true. O segredo compartilhado deve corresponder ao do coturn static-auth-secret.

external_service_secret = "REPLACE_WITH_THE_SAME_LONG_RANDOM_SECRET";

external_services = {
    { type = "stun", host = "turn.example.com", port = 3478 },
    { type = "turn", host = "turn.example.com", port = 3478,
       transport = "udp", secret = true, ttl = 86400, algorithm = "turn" },
    { type = "turns", host = "turn.example.com", port = 5349,
       transport = "tcp", secret = true, ttl = 86400, algorithm = "turn" }
};

Mantenha os módulos existentes e as configurações específicas do site no seu arquivo Prosody gerado pelo Jitsi; não substitua o arquivo inteiro pelo trecho acima. O nome exato do arquivo normalmente segue o seu domínio de implantação em `<domain>` /etc/prosody/conf.d/. O exemplo de configuração do Jitsi pode ser consultado no repositório oficial do Jitsi .

Se você estiver usando a implantação oficial do Docker, prefira as variáveis ​​de ambiente documentadas em vez de editar manualmente os arquivos Prosody gerados. A documentação atual do Docker expõe `prosody.env` TURN_CREDENTIALS, TURN_HOST` TURN_PORTprosody.env`, ` TURN_TRANSPORTprosody.env`, TURNS_HOST`prosody.env` e `prosody.env` TURNS_PORT. Consulte o guia atual de auto-hospedagem do Jitsi com Docker, pois os valores padrão das variáveis ​​podem mudar entre as versões.

Etapa 6: Reinicie e valide os serviços

Após alterar o coturn, reinicie-o e verifique seu status:

sudo systemctl restart coturn
sudo systemctl status coturn
sudo ss -lntup | grep -E '3478|5349'

Após alterar a configuração do Prosody, verifique a sintaxe para garantir que o pacote Prosody forneça o verificador e reinicie o Prosody. Dependendo das alterações feitas no Jitsi, reiniciar os serviços relevantes do Jitsi também pode ser necessário.

sudo prosodyctl check config
sudo systemctl restart prosody

Um status de serviço coturn limpo apenas comprova que o daemon está em execução. Não comprova que as credenciais correspondem, que o intervalo de retransmissão está acessível ou que um navegador consegue obter um candidato a retransmissão.

Etapa 7: Teste se o TURN realmente consegue retransmitir mídia.

Testar a partir da mesma LAN não é suficiente. Use pelo menos um cliente em uma rede diferente, idealmente uma conexão móvel ou uma rede que sabidamente restrinja o UDP. Nos diagnósticos WebRTC do navegador, procure por um candidato ICE do tipo <tipo> relay. Um candidato a relay significa que o navegador obteve com sucesso as credenciais TURN e criou uma alocação TURN.

Observe também os logs do coturn enquanto o usuário de teste se conecta. Você deverá ver alocações autenticadas e tráfego de retransmissão quando o TURN estiver selecionado. Se houver falhas de autenticação, compare o coturn static-auth-secretcom o segredo de credencial TURN do Prosody ou do Docker. Se as alocações forem bem-sucedidas, mas a mídia ainda falhar, verifique o firewall da porta de retransmissão e o mapeamento NAT.

Não force o TURN apenas para comprovar a existência do servidor, a menos que tenha um motivo controlado para o teste. Em condições normais, o ICE escolhe o melhor caminho de trabalho. Uma implantação bem-sucedida pode, portanto, ter várias reuniões que nunca precisam do TURN.

Etapa 8: Mantenha a configuração JVB NAT separada da resolução de problemas TURN

Este é o ponto que evita a maior parte do tempo perdido na resolução de problemas. Um servidor Jitsi atrás de um NAT ainda precisa que a acessibilidade pública da ponte esteja configurada corretamente. O guia de início rápido do Jitsi atual afirma que a ponte normalmente se configura automaticamente, mas se chamadas maiores falharem, você pode adicionar um mapeamento estático ice4j.harvest.mappingem /etc/jitsi/videobridge/jvb.conf:

ice4j {
  harvest {
    mapping {
      static-mappings = [
        {
          local-address = "192.168.1.20"
          public-address = "203.0.113.20"
        }
      ]
    }
  }
}

Encaminhe o UDP 10000 da borda pública para o host JVB e certifique-se de que o endereço público seja aquele que os clientes remotos possam realmente alcançar. O TURN pode ajudar clientes em redes restritivas, mas não deve ser usado para ocultar um mapeamento NAT JVB incorreto.

Lista de verificação rápida para solução de problemas

• O nome de host TURN não está sendo resolvido: corrija o DNS antes de testar o Jitsi.
• As portas 3478/5349 escutam localmente, mas não remotamente: inspecione o firewall do host, o firewall da nuvem, o NAT do roteador e a filtragem do provedor.
• As credenciais falharam: verifique se o segredo compartilhado é idêntico no Coturn e na configuração do Jitsi/Prosody.
• O candidato a retransmissão aparece, mas a mídia falha: verifique se o intervalo de portas de retransmissão configurado está aberto de ponta a ponta.
• Apenas chamadas multipartidárias falham: verifique JVB UDP 10000 e o anúncio de endereço público do JVB.
• Somente redes corporativas falham: adicione ou verifique o protocolo TURN sobre TLS, geralmente na porta TCP 443, quando apropriado.
• As alterações feitas no Docker desaparecem após a reinicialização: configure as .envvariáveis ​​suportadas em vez de editar os arquivos gerados dentro dos contêineres.

Qual a aparência de um resultado correto?

Uma configuração adequada apresenta três comportamentos observáveis. Primeiro, usuários comuns podem acessar o Jitsi Videobridge diretamente, sem TURN, quando suas redes permitirem. Segundo, usuários em redes restritivas podem receber credenciais TURN temporárias e obter um relaycandidato ICE. Terceiro, o coturn exibe alocações autenticadas somente quando necessário, em vez de transmitir todas as reuniões por padrão.

Essa combinação oferece uma alternativa útil sem transformar o servidor TURN em um gargalo desnecessário de largura de banda. Além disso, mantém a solução de problemas simples: problemas de NAT do JVB continuam sendo problemas do JVB, enquanto o TURN resolve a questão mais específica da conectividade WebRTC quando as rotas diretas estão bloqueadas.