Corrigindo timeouts de registro SIP do FreeSWITCH no BigBlueButton: um guia prático de diagnóstico

Uma reunião do BigBlueButton pode carregar normalmente, mas os participantes podem ficar presos ao tentar conectar o áudio. Os administradores podem ver mensagens como "Tempo limite de registro SIP", "FreeSWITCH não se registrou" ou um erro de conexão de áudio em um log ou ferramenta de monitoramento. Essas mensagens nem sempre indicam a mesma falha. Em uma implementação padrão do BigBlueButton, uma falha na conexão de áudio pode ser causada por um processo do FreeSWITCH interrompido, uma conexão SIP ou Event Socket bloqueada, um endereço incorreto atrás de um NAT ou mídia WebRTC bloqueada. Um tempo limite de registro real para uma operadora ou gateway PBX é um caso à parte.

Comece identificando qual componente está apresentando timeout. Em seguida, verifique a integridade do serviço, os listeners locais, os caminhos de rede e os endereços, nessa ordem. Evite alterar as configurações SIP ou abrir portas até que as evidências identifiquem o caminho afetado.

Primeiro, identifique a que se refere o termo “tempo limite de registro”.

A pilha de áudio atual do BigBlueButton usa o bbb-webrtc-sfuserviço para coordenar a mídia com o FreeSWITCH. A documentação do BigBlueButton descreve a conexão do SFU com o serviço SIP e o Event Socket Layer (ESL) do FreeSWITCH. Isso é diferente do FreeSWITCH registrar um gateway de saída para um provedor SIP externo.

• Problema de conexão de áudio no BigBlueButton: os usuários não conseguem entrar no áudio, o FreeSWITCH está inacessível ou o SFU reporta um tempo limite excedido. Investigue o FreeSWITCH, o ESL, o endereço e a porta SIP configurados, o NAT e o transporte WebRTC.
• Problema de registro de gateway externo: o FreeSWITCH reporta um gateway configurado como inativo ou não registrado. Investigue o nome do host do provedor, as credenciais, o protocolo de transporte, o caminho do firewall e o status da conta do provedor.

Se você não tiver certeza de qual caso se aplica, salve o texto completo do erro e o nome do serviço que o registrou. Apenas a mensagem "Tempo limite de registro" não é suficiente para justificar a alteração de um perfil SIP.

1. Execute a verificação de configuração do BigBlueButton.

No servidor, execute o diagnóstico recomendado pela BigBlueButton:

sudo bbb-conf --check

Analise toda a saída, especialmente a seção intitulada Potential problems. Ela verifica se os processos necessários estão em execução e relata problemas comuns de configuração. Um aviso pode refletir uma personalização intencional; portanto, compare-o com sua configuração em vez de aplicar automaticamente todas as correções sugeridas.

Em seguida, verifique o status do serviço:

sudo bbb-conf --status
sudo systemctl status freeswitch --no-pager
sudo systemctl status bbb-webrtc-sfu --no-pager

Em versões mais antigas do BigBlueButton, os nomes dos serviços ou a arquitetura dos componentes podem ser diferentes. Confirme a versão instalada sudo bbb-conf --versione consulte a documentação correspondente. Os caminhos e exemplos abaixo referem-se principalmente à documentação do BigBlueButton 4.0, que está marcada como em desenvolvimento.

2. Confirme se o FreeSWITCH está em execução e aceitando conexões locais.

Se freeswitch.serviceo serviço estiver inativo, com falha ou reiniciando repetidamente, leia o registro de eventos (log) antes de editar a configuração:

sudo journalctl -u freeswitch.service -b --no-pager -n 100

Procure por falhas de vinculação, erros de carregamento de módulos, problemas de permissão ou erros de banco de dados próximos à inicialização mais recente. O guia de solução de problemas do BigBlueButton documenta casos específicos em que o FreeSWITCH não consegue se vincular ao IPv4 ou à porta ESL 8021. Ele também identifica um banco de dados do FreeSWITCH corrompido como uma possível causa após uma reinicialização, mas recomenda a limpeza do banco de dados somente quando os erros correspondentes estiverem presentes.

Verifique quais endereços e portas estão em escuta:

sudo ss -luntp | grep -E ':(5060|5066|8021)\b'

O ouvinte SIP exato depende da sua versão e configuração do BigBlueButton. A ausência de um ouvinte sugere que o FreeSWITCH não conseguiu iniciar esse perfil ou que ele foi vinculado a um endereço diferente. A porta 8021 é a interface de controle ESL local em uma instalação padrão; normalmente, ela deve permanecer restrita ao localhost ou a uma rede privada confiável. Não a exponha à internet pública.

Se o FreeSWITCH estiver ativo, você pode inspecionar o estado do perfil SIP com sua CLI. O comando padrão do FreeSWITCH é `freeswitch-profile` sofia status; use os nomes de perfil exibidos pelo seu servidor em vez de presumir que todas as implementações usam os mesmos. Um perfil marcado como `true` RUNNINGconfirma que o perfil foi iniciado, mas não comprova que navegadores remotos podem acessar o caminho da mídia de áudio.

3. Associe o erro ao caminho de rede com falha.

O guia de firewall do BigBlueButton distingue uma falha de sinalização WebSocket de uma falha ICE/de mídia. Essa distinção restringe a busca:

• Erro WebRTC 1002: o navegador não conseguiu estabelecer a conexão WebSocket. Verifique se o FreeSWITCH está em execução, a rota SIP sobre WebSocket e a configuração do proxy reverso, bem como quaisquer regras de firewall que afetem esse caminho de sinalização.
• Erro WebRTC 1007: o WebSocket foi conectado, mas o navegador não conseguiu estabelecer a conexão de mídia usando os endereços candidatos retornados. Verifique o endereço IP anunciado e a conectividade UDP bidirecional.

Para a configuração padrão do firewall BigBlueButton, o guia oficial lista as portas UDP 16384–32768para mídia em tempo real. Permita o intervalo necessário tanto no grupo de segurança da nuvem ou firewall de perímetro quanto no firewall do host. Limite a regra ao servidor e ao tráfego necessário; abrir portas SIP não relacionadas indiscriminadamente não substitui a configuração correta de NAT e WebRTC.

Por exemplo, se você usa UFW e confirmou que esse intervalo é apropriado para sua instalação, verifique as regras existentes e adicione o intervalo de mídia:

sudo ufw status numbered
sudo ufw allow 16384:32768/udp

Os firewalls de nuvem e os grupos de segurança do provedor também devem permitir o tráfego. Uma regra em nível de host não pode substituir um firewall upstream bloqueado. Se apenas os usuários em uma rede restritiva apresentarem falhas enquanto outros usuários se conectam, investigue o caminho de rede ou a configuração TURN deles em vez de reiniciar o FreeSWITCH repetidamente.

4. Verifique o NAT e os endereços IP anunciados.

Um servidor atrás de um NAT pode ter um ouvinte local correto e ainda assim anunciar um endereço privado inacessível para os navegadores. Verifique se o endereço IP externo, o encaminhamento de portas e a configuração do FreeSWITCH estão corretos. O guia de firewall 4.0 do BigBlueButton usa `/etc/switch.conf` /opt/freeswitch/conf/vars.xmle `/etc/switch.conf` /opt/freeswitch/conf/sip_profiles/external.xmlpara o exemplo de NAT e indica `/ /etc/bigbluebutton/bbb-webrtc-sfu/production.ymletc/switch.conf` para as configurações relevantes de sobrescrita do SFU.

Não copie um endereço IP de exemplo nem assuma que o endereço IP público pertence a todos os campos. Em uma configuração NAT, o endereço que o FreeSWITCH vincula localmente pode ser diferente do endereço público que ele anuncia. Aplique as instruções específicas da versão para a sua topologia de rede e, em seguida, verifique o encaminhamento de firewall relevante. Se o endereço externo do servidor foi alterado recentemente, verifique o DNS e quaisquer valores de endereço mantidos na configuração do BigBlueButton.

Quando um processo de servidor precisa acessar seu próprio nome de host público, o NAT hairpin ou a resolução de nome de host local também podem ser relevantes. O guia oficial do firewall aborda o mapeamento do nome de host público para o endereço do firewall nesse /etc/hostscenário. Teste isso somente quando o padrão de falha apontar para um loopback através do nome de host externo; não é uma solução universal para timeouts de registro.

5. Se o registro mencionar um gateway SIP externo

Se o item com falha for um gateway de operadora nomeado em vez do caminho de áudio interno do BigBlueButton, inspecione o estado do gateway separadamente. O FreeSWITCH documenta sofia status gateway <name>o status do gateway, sofia statusbem como o perfil carregado e o estado do gateway. Verifique se o nome do host do provedor é resolvido a partir do servidor, se o nome de usuário e a senha SIP configurados correspondem, se o transporte e a porta escolhidos correspondem aos requisitos do provedor e se as regras de firewall de saída permitem o tráfego de sinalização.

Não redefina os perfis SIP incluídos no BigBlueButton para reparar uma conta de operadora. Evite compartilhar rastreamentos SIP completos publicamente: eles podem conter números de telefone, endereços IP, nomes de contas ou detalhes relacionados à autenticação. Oculte valores confidenciais antes de solicitar que um provedor ou administrador revise os registros.

6. Aplique a alteração desejada e reinicie o sistema.

Após corrigir um problema confirmado de serviço, endereço ou firewall, reinicie o BigBlueButton usando o comando compatível:

sudo bbb-conf --restart

Utilize sudo bbb-conf --cleansomente quando a documentação específica da versão ou evidências de diagnóstico assim o exigirem. Não se trata de uma resposta genérica para todos os timeouts de SIP. Da mesma forma, evite excluir arquivos de banco de dados do FreeSWITCH, a menos que os sintomas de corrupção de banco de dados documentados se manifestem; preserve os logs e backups de configuração antes de qualquer reparo que remova o estado.

Verifique o reparo

Execute sudo bbb-conf --checknovamente e confirme se o FreeSWITCH e o firewall bbb-webrtc-sfuestão funcionando corretamente. Participe de uma reunião de teste a partir de um navegador fora da rede do servidor, selecione o microfone ou o modo de áudio somente para ouvir e confirme se a conexão é estabelecida. Para alterações de NAT ou firewall, teste a partir de pelo menos uma rede que tenha apresentado falhas anteriormente. Um status de serviço verde por si só não comprova que o tráfego UDP consegue atravessar a rede.

Se o tempo limite persistir, colete a versão do BigBlueButton, o texto completo do erro, a bbb-conf --checksaída relevante, o status do serviço, as entradas recentes do FreeSWITCH e do SFU (Sistema de Gerenciamento de Fluxo de Dados) e a topologia da rede. Oculte informações confidenciais e dados públicos do usuário. Essas evidências ajudam a distinguir um listener inativo, um tempo limite ESL, um endereço anunciado incorreto, um intervalo de mídia bloqueado e uma falha genuína de registro do gateway SIP.

Referências oficiais

• Guia de Solução de Problemas do BigBlueButton 4.0
• Configuração do firewall BigBlueButton 4.0
• Referência de comandos da CLI e da API do FreeSWITCH
• Perfis SIP do FreeSWITCH com Sofia

Documentação verificada em 6 de outubro de 2026. A documentação do BigBlueButton 4.0 indica que esta versão está em desenvolvimento; confirme os caminhos e comandos com a versão instalada em seu servidor.