Ir para o conteúdo

Roteiro: Registrar e diagnosticar media servers (FreeSWITCH)

Perfil necessário: admin (cadastrar/alterar) | viewer (consulta) Menus usados: Plataforma, Sistema Risco: médio (media server é o destino dos anúncios de tratamento: registro errado deixa negações sem áudio — o OpenSIPS cai no fallback SIP do anúncio) Rollback: voltar os campos alterados (host/porta/transporte) no mesmo dialog; para remover, excluir pela lixeira — o backend remove também a entrada correspondente do dispatcher set. Reativar enabled = Ativo reverte um desligamento.

Pré-requisitos

  • [ ] Instância FreeSWITCH no ar (dev: docker compose up -d freeswitch) e perfil media_server escutando (5070/udp, ESL 8021/tcp só em loopback)
  • [ ] Host/porta/transporte SIP do MS conhecidos (dev: 127.0.0.1:5070;transport=udp)
  • [ ] Perfil admin para criar/editar

Passo a passo

1. Abrir a página Media Servers

Caminho: Plataforma → Infraestrutura → Media Servers Clique: [Novo Media Server] (somente para registrar um FreeSWITCH novo)

Lista de media servers com o botão Novo Media Server destacado

A listagem mostra: Nome, Endpoint (sip:<host>:<porta>;transport=<transporte>), Set (setid no dispatcher), Prio., Ativo.

Diagnóstico (sem clique): a página é o catálogo da fonte do route[msoutbound]. O OpenSIPS escolhe o MS por consulta enabled=1 ORDER BY priority ASC (cache local de 300s), e o dispatcher set correspondente recebe o destino espelhado. Se nenhum MS estiver Ativo, toda negação com tratamento de áudio cai no fallback SIP do anúncio (code/reason cadastrados). Estado/saúde das instâncias são verificados via OPTIONS do dispatcher (setid do MS); veja media-dispatcher.md para o estado de probing.

Resultado esperado: ao menos um media server com Ativo = Sim em produção.

2. Preencher o dialog Novo Media Server

Caminho: Plataforma → Infraestrutura → Media Servers Clique: [Novo Media Server] → botão [Criar] no rodapé do dialog

Dialog Novo Media Server aberto

Preencha:

Campo Obrig. Formato/exemplo Efeito
Nome * sim freeswitch-local (único) Identificador do catálogo; duplicado é rejeitado (409)
Host * sim 127.0.0.1 IP/host do INVITE do OpenSIPS → MS
Porta * sim 5070 (1–65535) Porta SIP do perfil media_server do FreeSWITCH (não colide com o OpenSIPS em 5060)
Transporte não (default udp) udp | tcp | tls Transporte do destino no dispatcher
Dispatcher Set ID não (default 900) inteiro ≥ 1 Setid do dispatcher onde o destino é espelhado; 900 é reservado para MS
Prioridade não (default 10) inteiro (1–999) Menor = maior prioridade na escolha do MS
Ativo não (default Ativo) Ativo | Inativo Só MS Ativo recebe tratamento de áudio; Inativo remove o destino do dispatcher
Descrição não texto livre Contexto operacional (ex. "container host-networking dev")

Resultado esperado: toast "Media server criado"; nova linha com endpoint sip:127.0.0.1:5070;transport=udp, Tag do set (ex. 900) e Ativo = Sim.

3. O que a criação faz por baixo (e o que fazer depois)

Ao salvar, o backend insere no dispatcher a entrada sip:<host>:<porta>;transport=<transporte> no setid escolhido com attrs = media_server=1 e description = MS:<nome>. Editar ou desativar o MS mantém o espelho em sincronia (entrada recriada/removida automaticamente).

Para o OpenSIPS usar o novo destino imediatamente:

Caminho: Sistema → OpenSIPS Clique: [Recarregar todos os módulos] (ou o cartão Dispatcher → Recarregar para ds_reload apenas)

Reload OpenSIPS com o botão Recarregar todos os módulos destacado

Resultado esperado: card verde de sucesso; ds_reload executado. Sem isso, o dispatcher só perceberá o destino no próximo reload.

4. Diagnóstico de ESL e instância

O ESL não é configurado nesta página — é fixo do container (event_socket.conf.xml: porta 8021, senha sw-iproute-esl, só loopback) e hoje reservado para evoluções (dual-stream "a cobrar"). Para diagnosticar a instância:

  1. Container: docker compose ps freeswitch e docker compose logs -f freeswitch.
  2. SIP do perfil: INVITEs chegam em 5070/udp (loopback); conferir com tcpdump -i lo port 5070 ou logs do sofia.
  3. ESL: docker compose exec freeswitch fs_cli -x status (healthcheck do ADR 0008).
  4. Dialplan do anúncio: freeswitch/conf/dialplan/announcements.xml casa *an-<code> → answer + playback announcements/<code>.wav (tom de reordem como fallback quando o arquivo não existe).

Resultado esperado: fs_cli -x status responde; INVITEs do OpenSIPS aceitos no perfil media_server.

Validação

  • [ ] Visual: MS listado com Ativo = Sim, endpoint e set corretos.
  • [ ] Visual: entrada sip:<host>:<porta>;transport=... presente no dispatcher (página Infraestrutura → Dispatcher, setid do MS).
  • [ ] Funcional: chamada negada com media_treatment_mode = audio no perfil da linha toca o anúncio no MS (e não apenas responde SIP).
  • [ ] Funcional: docker compose exec freeswitch fs_cli -x status OK.

Erros comuns

Sintoma Causa provável Correção
Anúncio não toca; chamada só recebe code/reason SIP Nenhum MS Ativo (ou todos Inativos) Editar MS → Ativo = Ativo → Salvar
Anúncio não toca mesmo com MS ativo Cache do MS (300s) ainda apontando para o destino antigo Aguardar ~5 min ou reiniciar OpenSIPS após trocar host/porta
Destination nunca selecionado no dispatcher Reload não executado após criar/alterar Sistema → OpenSIPS → Recarregar todos os módulos (cartão Dispatcher)
408/timeout do INVITE ao MS Porta/transporte errados ou FreeSWITCH parado Conferir porta 5070/udp e docker compose ps freeswitch
Duas linhas do mesmo MS no dispatcher Host/porta alterados sem limpar a entrada antiga Conferir setid e excluir entrada órfã em Infraestrutura → Dispatcher
Escolha do MS ignora prioridade Prioridades iguais entre MS ativos Definir prioridades distintas (menor valor = primeiro)
Setid alterado à mão divergindo do catálogo Editar Dispatcher Set ID de um MS em produção Manter 900 (reservado para MS) ou alinhar set e recarregar

Tabela de referência rápida

Tarefa Onde Ação
Registrar FreeSWITCH [Novo Media Server] nome, host, porta 5070, udp, set 900
Tirar MS da rotação lápis da linha Ativo = Inativo (remove do dispatcher set)
Ver espelho no dispatcher Plataforma → Infraestrutura → Dispatcher filtrar setid do MS
Saúde da instância host do MS docker compose exec freeswitch fs_cli -x status
ESL (fase futura) container 127.0.0.1:8021, senha do event_socket.conf.xml