FreePBX 17: central VoIP no Debian 12

Montar uma central telefônica IP no Linux não precisa começar pela edição manual do dialplan. O FreePBX 17 oferece uma interface web para administrar o Asterisk: ramais, troncos, rotas, filas e atendimento eletrônico ficam organizados em módulos. A mudança importante desta geração está na base: Debian 12, instalação por script ou ISO e atenção à migração de chan_sip para PJSIP.

Neste guia, vamos separar as versões envolvidas, escolher o método de instalação e montar um laboratório com dois ramais. Depois, veremos o que muda ao migrar uma central existente e os cuidados antes de conectar uma operadora. As referências são a documentação oficial da Sangoma, o instalador mantido pelo projeto e os dois vídeos indicados ao final.

FreePBX não substitui o Asterisk

Pense em duas camadas: o Asterisk executa a telefonia; o FreePBX fornece o painel que organiza sua configuração. O primeiro processa chamadas e aplicações do dialplan. O segundo permite administrar a central sem escrever cada configuração à mão. É essa relação que o repositório oficial do instalador descreve.

Também há uma diferença entre software aberto e serviço telefônico: instalar o FreePBX não entrega um número público ou chamadas externas gratuitas. Dois ramais locais podem conversar sem uma operadora; para alcançar a rede telefônica pública, será necessário um serviço apropriado, como um tronco SIP contratado.

O ecossistema combina componentes abertos com módulos comerciais opcionais. Portanto, confirme a licença do recurso desejado antes de assumir que uma função mostrada em uma demonstração está incluída na instalação básica.

O que muda no FreePBX 17

• Base oficialmente suportada: Debian 12 Bookworm. Não use Debian 13 ou Ubuntu como substitutos automáticos para este procedimento.
• PHP 8.2: é a versão usada nesta geração; não troque a pilha PHP por conta própria em uma central em produção.
• Instalador Bash aberto: pode ser executado sobre um Debian 12 novo, físico ou virtual.
• ISO disponível: automatiza a instalação do Debian e a execução desse mesmo instalador, em vez de constituir um caminho completamente independente.
• Asterisk 22 por padrão atualmente: exemplos do lançamento podem mostrar Asterisk 21, mas não representam necessariamente uma instalação nova.

Esses pontos constam na página oficial do FreePBX 17. A versão final, ou GA, foi disponibilizada em 2 de agosto de 2024. O código atual do instalador confirma Asterisk 22 e PHP 8.2 como padrões e rejeita sistemas que não sejam Bookworm.

Arquitetura: painel, ramais e operadora

No laboratório, dois clientes SIP registram seus ramais no Asterisk. O administrador configura a central pelo FreePBX. O tronco com uma operadora é uma etapa posterior: não é necessário para a primeira ligação interna.

Sinalização não é áudio. O SIP negocia a chamada; o RTP transporta a mídia. Assim, um ramal pode registrar e fazer o outro tocar, mas continuar sem áudio se a rede estiver incorreta. O diagrama representa mídia passando pela central; configurações de mídia direta podem alterar esse caminho.

Vai virtualizar? Veja também a história do Proxmox e a história do VirtualBox. Para entender a distribuição que sustenta a central, vale ler a história de Ian Murdock e do Debian.

Prepare um laboratório separado

A página oficial de downloads informa o mínimo de 2 GB de RAM e 20 GB de disco para o host ou VM Debian 12. Isso não é um dimensionamento de produção: chamadas simultâneas, transcodificação e gravações mudam a necessidade de recursos.

Como ponto de partida para este laboratório pequeno, sugiro 2 vCPUs, 4 GB de RAM e 40 GB de disco. É uma escolha de laboratório, não uma garantia de capacidade nem um requisito oficial. Use uma VM exclusiva, endereço IP estável ou reserva DHCP, DNS funcionando e acesso à internet para baixar os pacotes.

Deixe a VM e os dois clientes em uma rede de laboratório que permita comunicação entre eles. Em redes isoladas por NAT do hipervisor, confira a conectividade antes de investigar o SIP. Não coloque a central diretamente na internet para simplificar o teste.

Opção 1: instalar com o script oficial

Use este caminho em um Debian 12 recém-instalado e dedicado. O instalador configura dependências e repositórios: não o execute no servidor que já hospeda seu site, banco ou outro PBX. Abra uma sessão administrativa na VM; os comandos abaixo são para ela, não para sua estação de trabalho. Se usar SSH, prepare uma sessão persistente com tmux antes de iniciar a instalação.

# Na VM Debian 12, abra uma sessão root
sudo -i

# Confira o sistema e a conectividade local
cat /etc/os-release
ip -br address
ip route

# Instale o utilitário de download, se necessário
apt-get update
apt-get install -y wget ca-certificates less tmux

# Abra a sessão persistente antes da instalação
tmux new -s freepbx

Dentro da sessão do tmux, execute o bloco seguinte. Se a conexão SSH cair, entre novamente na VM, abra a sessão root e retome com tmux attach -t freepbx.

# Baixe o instalador oficial, sem executá-lo diretamente do download
wget -O /tmp/sng_freepbx_debian_install.sh \
  https://github.com/FreePBX/sng_freepbx_debian_install/raw/master/sng_freepbx_debian_install.sh

# Leia o script; pressione q para sair
less /tmp/sng_freepbx_debian_install.sh

# Depois da revisão, execute a instalação
bash /tmp/sng_freepbx_debian_install.sh

Se sua instalação mínima não tiver sudo ou less, use o acesso administrativo configurado durante a instalação do Debian e instale os utilitários necessários. O README oficial documenta o download e a execução como root. Não adicione --testing para uma instalação normal.

Se o instalador indicar que existe uma versão mais recente, baixe o arquivo novamente em vez de contornar a checagem com --skipversion. Em outro terminal administrativo, acompanhe o arquivo mais recente criado em /var/log/pbx/:

ls -lt /var/log/pbx/freepbx17-install*.log
# Use o nome exato listado acima:
# tail -f /var/log/pbx/freepbx17-install-DATA-HORA.log

A documentação de instalação explica as opções. --opensourceonly seleciona apenas módulos abertos do FreePBX; --dahdi é relevante para hardware de telefonia compatível. Não acrescente DAHDI em um laboratório puramente SIP sem necessidade: os drivers têm dependências específicas de kernel.

Opção 2: instalar pela ISO

Prefere iniciar uma VM por uma mídia pronta? Obtenha o link atual e o SHA-256 na página de downloads, confira a integridade da imagem e siga o guia oficial da ISO v17. A instalação continua dependendo da rede para baixar componentes.

Configure o firmware da VM como UEFI. O menu da ISO oferece perfis de instalação, chamados de spice levels. Para um laboratório somente SIP, sem placas físicas de telefonia, o guia sugere Basic → FOG.

# No diretório onde você salvou a ISO:
sha256sum SNGDEB-PBX17-*.iso
# Compare o resultado com o SHA-256 da mesma imagem no site oficial.

O diretório de ISOs também contém imagens históricas. Estar disponível para download não significa continuar suportada. Para começar, siga o arquivo indicado na página atual, não uma ISO antiga escolhida pelo nome.

A ISO v17 desabilita o login de root por padrão. Dependendo do perfil, a instalação pode exibir uma senha gerada para o usuário sangoma: se essa tela aparecer, guarde a senha. Siga o guia para definir ou alterar as credenciais e use sudo nas tarefas administrativas. Não é necessário recorrer à recuperação de senha pelo GRUB apenas porque o login de root não está disponível.

Primeiro acesso e dois ramais PJSIP

Concluída a instalação, abra no navegador o endereço IP da VM na rede de laboratório. Crie as credenciais administrativas e configure o acesso seguro. Em produção, use HTTPS com certificado válido e restrinja a administração à rede de gestão ou VPN.

1. Em Applications → Extensions, escolha adicionar um ramal PJSIP.
2. Crie o ramal 1001, com um nome de identificação. Mantenha o Secret gerado ou use outro igualmente forte e exclusivo. Não use o próprio número como senha.
3. Repita o procedimento para o ramal 1002, com outra senha.
4. Salve e aplique as mudanças com Apply Config.
5. Configure um cliente SIP para cada ramal: servidor/domínio = IP da VM; senha = Secret correspondente. Use o número do ramal como usuário na configuração padrão; se houver autenticação personalizada, confira o usuário definido na central. Confira também porta e transporte.
6. Com ambos registrados, ligue de 1001 para 1002 e depois no sentido inverso. Confira o áudio dos dois lados.

Os campos de ramal, identificação e senha estão descritos no guia de extensões PJSIP. Algumas capturas da wiki pertencem a versões anteriores; siga o tipo PJSIP, não tutoriais antigos que escolhem chan_sip.

Para uma primeira checagem pelo terminal da central:

sudo asterisk -rx 'core show version'
sudo asterisk -rx 'pjsip show endpoints'
sudo asterisk -rx 'pjsip show contacts'

Se você já estiver como root e não tiver sudo, omita esse prefixo. Esses comandos ajudam a conferir o Asterisk instalado, os endpoints e seus contatos. A prova funcional continua sendo a ligação completada com áudio bidirecional, não apenas a presença do ramal na lista.

Softphones para Debian e Ubuntu

O MicroSIP mostrado no vídeo é uma opção para Windows. Para participar do mesmo laboratório a partir de um desktop Linux, você pode usar um dos clientes SIP abaixo. O cliente fica na estação do usuário, não no servidor FreePBX.

Para começar, eu escolheria o Linphone disponível no repositório da própria estação. O pacote está documentado no Debian 12 e está disponível no Ubuntu 24.04; no Ubuntu, pertence ao componente Universe. Isso não significa que estará disponível em toda versão de Debian ou Ubuntu. Confira o candidato antes de instalar:

# Na estação gráfica Debian/Ubuntu, não no servidor PBX
sudo apt-get update
apt-cache policy linphone-desktop twinkle

# Escolha um cliente com candidato disponível:
sudo apt-get install linphone-desktop
# Alternativa, em vez do Linphone:
# sudo apt-get install twinkle

Não instale um .deb de Ubuntu no Debian, nem de outra versão da distribuição por conveniência: as bibliotecas exigidas podem ser diferentes. O pacote da distribuição também pode ter uma versão anterior à fornecida diretamente pelo projeto.

GOnnect merece uma observação: o projeto foi pensado para provisionamento por arquivo, em vez de um assistente para cadastrar a conta SIP. Com Flatpak e o repositório Flathub já configurados na estação, a instalação pode ser feita assim:

flatpak install flathub de.gonicus.gonnect

Depois, adapte o arquivo de exemplo oficial às credenciais e ao transporte do seu ramal e salve em ~/.var/app/de.gonicus.gonnect/config/gonnect/99-user.conf, conforme o README. Consulte as orientações do GOnnect antes de iniciar e proteja o arquivo por conter credenciais. Não basta instalar o aplicativo e procurar uma tela para cadastrar a conta SIP. As integrações de desktop e hardware dependem do ambiente e dos dispositivos suportados.

# Crie o diretório antes de salvar a configuração adaptada
mkdir -p ~/.var/app/de.gonicus.gonnect/config/gonnect
# Depois de salvar 99-user.conf com suas credenciais:
chmod 600 ~/.var/app/de.gonicus.gonnect/config/gonnect/99-user.conf
flatpak run de.gonicus.gonnect

Se precisar do binário distribuído pelo próprio Linphone, a referência oficial de release Linux consultada para este artigo aponta para Linphone 6.2.3 em AppImage x86_64. É uma alternativa ao pacote nativo, não uma garantia de compatibilidade com qualquer sistema: confira arquitetura e requisitos da versão. O GitHub indicado contém o código-fonte; os binários oficiais ficam no domínio de downloads do projeto.

Para acessar seus ramais, configure a conta SIP do seu FreePBX no cliente: endereço da central, número do ramal, usuário de autenticação e Secret definidos anteriormente. Não é necessário criar uma conta no serviço público do fabricante para fazer a ligação interna entre 1001 e 1002.

Rede com IPv6 problemático? Para testar o acesso HTTP por IPv4, use curl -4 -I https://github.com/belledonnecommunications/linphone-desktop. No APT, a opção Acquire::ForceIPv4 força os downloads por IPv4, sem desativar IPv6 no sistema:

sudo apt-get -o Acquire::ForceIPv4=true update
sudo apt-get -o Acquire::ForceIPv4=true install linphone-desktop

Forçar IPv4 não corrige, por si só, uma falha do resolvedor DNS. Diferencie erro de resolução de nome, falha de conexão e erro de autenticação SIP antes de alterar a rede ou o firewall.

Firewall e NAT: não resolva desligando a proteção

O vídeo de laboratório do SR TECH LAB inclui atalhos para um ambiente de aprendizagem. Não adote a desativação do firewall como configuração final. Em Connectivity → Firewall, cadastre os hosts e redes necessários, confira as zonas e preserve um caminho administrativo antes de aplicar mudanças. O guia oficial alerta que deixar uma interface inteira na zona Trusted é uma configuração incorreta.

O guia informa que interfaces novas entram em Trusted por padrão. Antes de mudar a zona da interface, cadastre a rede do laboratório em Networks, na zona Local ou Internal apropriada, e o host/rede de administração com as permissões necessárias. A zona External não permite SIP por padrão; mover a interface sem preparar essas regras pode interromper os registros.

Para problemas de áudio, revise Settings → Asterisk SIP Settings: redes locais, endereço externo quando aplicável, codecs e faixa RTP. A documentação do módulo informa 10000–20000/UDP como faixa RTP padrão; confirme o valor real na sua central. A porta SIP depende do transporte e da configuração adotados.

• Não registra: confira endereço, usuário, senha, transporte e regras de firewall.
• Toca, mas não há áudio: investigue RTP, NAT, codecs e endereços anunciados.
• Somente um lado escuta: verifique o caminho de mídia nos dois sentidos, incluindo o firewall do cliente.

Não crie encaminhamentos públicos para um teste entre máquinas locais. Para ramais remotos, avalie uma VPN. O firewall do FreePBX trata os troncos configurados automaticamente, segundo o guia; isso não dispensa revisar o firewall de borda, NAT e regras da nuvem, liberando apenas os fluxos e origens necessários. Se usar TLS e SRTP, confirme suporte e configuração em todos os participantes: habilitar HTTPS no painel não criptografa automaticamente as chamadas.

Da ligação interna ao tronco SIP

Depois do teste local, uma central conectada à telefonia pública precisa de três elementos: tronco, rota de saída e rota de entrada. O tronco descreve a conexão com a operadora; a rota de saída define quais números usarão essa conexão; a rota de entrada encaminha chamadas recebidas para um ramal, grupo, fila ou URA.

Use os parâmetros fornecidos pela operadora: autenticação ou identificação por IP, servidor, transporte, codecs, formato de numeração e identificação de chamadas. Não copie endereços e credenciais de um exemplo de outro provedor. Restrinja os destinos permitidos e teste chamadas reais antes de liberar o uso aos usuários. O guia de configuração do PBX é um ponto de partida para navegar pelos módulos.

Migrar do FreePBX antigo exige uma instalação nova

O caminho documentado para sair de versões anteriores é Backup & Restore em um FreePBX 17 novo. Não existe atualização direta in-place dessas versões para o 17. Essa orientação está no guia oficial de migração.

1. Inventarie ramais, troncos, rotas, gravações, certificados, módulos comerciais e customizações.
2. Gere o backup pelo módulo apropriado e guarde uma cópia fora da central.
3. Instale o FreePBX 17 em outra VM. Antes de restaurar, isole o laboratório para impedir registros concorrentes na operadora e chamadas indevidas.
4. Restaure o backup e revise a conversão de ramais e troncos chan_sip para PJSIP.
5. Revise dialplans e scripts próprios, inclusive AGI, que usam Macro(); com Asterisk 22, eles exigem adaptação para Gosub().
6. Valide os fluxos de atendimento e planeje a troca com janela e procedimento de retorno.

PJSIP não é um novo protocolo que a operadora precisa inventar. É a pilha/driver SIP usado pelo Asterisk. A documentação do Asterisk confirma a remoção do chan_sip a partir do Asterisk 21. Telefones continuam falando SIP, mas parâmetros e comportamentos precisam ser conferidos na migração. Backup concluído não equivale a restore aprovado — a mesma distinção discutida no artigo sobre backup com restauração testada.

A documentação descreve a troca de versão com asterisk-version-switch para transições legadas, mas não recomenda permanecer em chan_sip. Não escolha uma versão antiga sem verificar seu suporte. Para este guia, o destino é o Asterisk 22 padrão, com PJSIP e as customizações adaptadas.

Suporte: FreePBX, sistema operacional e Asterisk

A matriz oficial de versões lista o FreePBX 17 como suportado e aponta 30 de junho de 2028 como EOL previsto. É a situação consultada para este artigo, não uma promessa imutável.

Não conclua que um FreePBX antigo está seguro só porque seus módulos ainda recebem alguma manutenção: a matriz distingue o suporte da aplicação do sistema SNG7, já encerrado. Ela também apresenta versões futuras como planejadas. Planejamento não é lançamento disponível. Antes de implantar ou migrar, confira novamente a matriz e os ciclos das dependências.

Não atualize a base de uma central FreePBX 17 de Debian 12 para Debian 13: essa combinação não é oficialmente suportada. Atualizações de pacotes dentro do Bookworm e migração para outra versão da distribuição são operações diferentes.

Vídeos: instalação prática e migração

Complemento em vídeo — SR TECH LAB: FreePBX 17 Complete Installation in VMware | PJSIP Extensions & First VoIP Call, publicado em 12 de agosto de 2026. Demonstra uma VM, dois ramais PJSIP e a primeira chamada com MicroSIP. É um laboratório, não um modelo de segurança para produção.

Webinar oficial — Sangoma: FreePBX 17 Hands-on: Installing & Migrating, publicado em 27 de junho de 2024. Explica instalação, PJSIP, mudança de Macro para Gosub e migração por backup e restauração. O vídeo é anterior à GA de agosto de 2024; versões, telas e disponibilidade de recursos devem ser confrontadas com a documentação atual.

Checklist antes de colocar em produção

• Debian e módulos atualizados pelos caminhos suportados, com backup anterior às mudanças.
• Acesso administrativo restrito, HTTPS e senhas exclusivas para painel e ramais.
• Firewall ativo, zonas revisadas e nenhuma interface inteira em Trusted por conveniência.
• Chamadas de entrada, saída e internas testadas com áudio bidirecional, transferência e atendimento.
• Rotas limitadas aos destinos necessários, com alertas e limites de consumo na operadora quando disponíveis.
• Backups protegidos fora do PBX, restauração ensaiada e política de retenção para gravações.
• Monitoramento de disco, disponibilidade, certificados e falhas de registro.

O primeiro objetivo é simples: dois ramais conversando com a proteção ativa. O salto para produção vem depois, com troncos, rotas, segurança e recuperação testados. O FreePBX facilita administrar a telefonia; não elimina a responsabilidade de operar a central.