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 perfilmedia_serverescutando (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)

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 consultaenabled=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

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)

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:
- Container:
docker compose ps freeswitchedocker compose logs -f freeswitch. - SIP do perfil: INVITEs chegam em
5070/udp(loopback); conferir comtcpdump -i lo port 5070ou logs do sofia. - ESL:
docker compose exec freeswitch fs_cli -x status(healthcheck do ADR 0008). - Dialplan do anúncio:
freeswitch/conf/dialplan/announcements.xmlcasa*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 = audiono perfil da linha toca o anúncio no MS (e não apenas responde SIP). - [ ] Funcional:
docker compose exec freeswitch fs_cli -x statusOK.
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 |