Capítulo 53 – Troubleshooting no OPNsense
Introdução
Quando algo “não passa”, “não sobe” ou “cai sem explicação”, é hora de investigar com método. O OPNsense oferece um conjunto sólido de ferramentas — na GUI e no console — que ajudam a observar, medir, isolar e confirmar hipóteses.
Este capítulo guia você, passo a passo, pelas principais rotas de diagnóstico: dos logs à captura de pacotes, dos testes de autenticação ao status de serviços, finalizando com dicas de CLI que salvam o dia.
A ideia é simples: comece pelo básico, avance conforme necessário, e registre o que descobriu. Bons hábitos de troubleshooting reduzem tempo de indisponibilidade e evitam “tiros no escuro”.
Visão geral do processo de troubleshooting
- Enquadre o problema
O que parou de funcionar? Para quem? Desde quando? Mudou algo na rede? - Colete evidências rápidas
Logs de firewall e serviços, ping, traceroute, status de gateways/VPN. - Isole a causa provável
Interface, regra, NAT, rota, autenticação, MTU, upstream, aplicação. - Valide a hipótese
Com packet capture, testes de credenciais, inspeção no syslog. - Aplique a correção
Pequenas mudanças, documentadas. - Confirme e monitore
O que foi corrigido continua estável? Há efeitos colaterais?
1) Visualização e análise de logs
Os logs contam a história. Se você não os consulta, investiga no escuro.
Onde olhar na GUI
-
Firewall (tráfego)
Firewall → Log Files → Live View
Filtros por ação, interface, IP, porta, protocolo. Ideal para ver agora o que está sendo permitido ou bloqueado. -
Logs internos do sistema
System → Log Files → Audit | Backend | Boot | General | WebGUI
Úteis para detectar erros de inicialização, eventos administrativos, mudanças aplicadas, falhas ao subir serviços etc. -
OpenVPN
VPN → OpenVPN → Log File
Aumente a verbosidade no túnel (3–5) para entender handshake, criptografia, autenticação e motivo de recusa. -
IPsec
VPN → IPsec → Log File
Mostra detalhes deIKE/ESP, identidades, PSK/Certs e mensagens de negociação. -
Web Proxy (Squid)
Services → Web Proxy → Access Log
Exibe cliente, URL, status (TCP_MISS/200,TCP_DENIED, etc.) e usuário, quando há autenticação.
O Bloqueio não aparece?
Não vê nada no Live View para o tráfego que espera? Ative o log na regra correspondente e aplique. Sem log, sem evidência.
Onde olhar na CLI
-
Filtro (PF) – log “cru”
-
Procure por um IP específico
* Exiba apenas campos úteis (src, dst, porta)
2) Ferramentas de diagnóstico de rede
Quando o log diz pouco, pergunte à rede.
Ping (WebGui e CLI)
-
Pela WebGui:
Acesse Interfaces → Diagnostics → Ping
Preencha o destino e, se necessário, endereço de origem. -
Pela CLI:
Para quê serve: confirmar conectividade básica entre o firewall (ou interface) e um host.
Traceroute (CLI)
Para quê serve: ver os saltos até o destino. Útil para problemas de roteamento ou blackholes no caminho.
Packet Capture (WebGui / tcpdump)
-
Pela WebGui:
Acesse Interfaces → Diagnostics → Packet Capture
Escolha interface, defina filtros e clique em Start. Ao final, clique em Stop e baixe o arquivo da captura (clicando na nuvenzinha) para analisar localmente usando o Wireshark. -
CLI (exemplo):
Para quê serve: prova definitiva de que pacotes chegam (ou não) e como chegam. Essencial para NAT e regras específicas.
3) Testes de autenticação (LDAP, RADIUS)
Se o usuário não entra, teste o backend.
Tester na GUI
- System → Access → Tester Selecione o servidor (LDAP/RADIUS), informe username e password, clique em Test.
Para quê serve: confirmar que o OPNsense alcança o servidor e que as credenciais são aceitas.
4) Status de serviços (Gateways e VPNs)
Veja rapidamente quem está de pé.
-
Gateways
System → Gateways → Configuration
Indica Online/Offline, perda e latência. Essencial em Multi-WAN. -
VPNs
- IPsec: VPN → IPsec → Status Overview
- OpenVPN: VPN → OpenVPN → Connection Status
Para quê serve: confirmar que o túnel subiu e se há tráfego fluindo.
5) Console e Shell
Quando a GUI não resolve, vá de console.
Menus do console
Ao acessar o console local/serial/SSH você será apresentado ao menu de opções, dentre elas, as mais usadas:
- atribuir interfaces (1)
- configurar IPs (2)
- resetar senha root (3)
- reset de fábrica (4)
- entrar na Shell (8)
Shell (opção 8 do console, local ou via SSH)
- Verificar interfaces, regras e NAT através do PF
ifconfig # status de interfaces
netstat -rn # rotas
pfctl -sr # regras carregadas
pfctl -sn # NAT
pfctl -k 0.0.0.0/0 -k 200.200.200.200 # encerra conexões com destino específico
- Informações sobre o sistema em tempo real
top -H # processos/threads
systat # load average
systat -iostat # disco
systat -netstat # rede
vmstat # kernel/memória
Atenção
Shell é poder. Em produção, tenha cuidado, registre comandos e sempre tenha backup de configuração à mão.
6) Testes via API
A API REST permite controlar programaticamente o firewall — útil para automações fora da WebGui. Para isso você precisa ter um usuário com uma chave API registrada, além das devidas permissões, para poder fazer as chamadas REST.
Registrando o Usuário e o Token de API
- Acesse o menu System → Access → Users.
- Clique no botão “+ Add” para adicionar um novo usuário da seguinte forma:
- Username: soc
- Scrambled Password: Marcar
- Group membership: Admins
- Clicar em Save.
- Clique no ícone de ticket () para emitir uma credencial API para este usuário “soc”.
- Clique em Yes para confirmar a geração da credencial.
- Caso o navegador solicite o que fazer com o arquivo, clique em Salvar.
- Abra o arquivo .txt que foi baixado para sua máquina, e repare que ele tem as informações mencionadas acima: Key e Secret:
- Salve em um lugar seguro e memorável estas informações, pois iremos usá-las dentro dos scripts.
Realizando chamadas na API
- Exemplo com
curl:
Comandos úteis de CLI
Filtrar logs de liberação/bloqueio para um determinado IP
Capturar a comunicação de um host numa determinada porta
Finalizar conexões “presas”
# pfctl -k origem -k destino: mata estados para o destino indicado
pfctl -k 0.0.0.0/0 -k 200.200.200.200
Quem está comendo CPU/IO?
Visualização em tempo real dos Logs de um serviço
# Substitua [aplicacao] por uma pasta válida em /var/log/
tail -f /var/log/[aplicacao]/latest.log | grep termo
iperf3 (teste de banda/latência)
Útil para medir throughput em VPNs ou validar NIC/LAN.
# Instala o iperf3
pkg install -y iperf3
# Inicia o Servidor iperf no firewall
iperf3 -s
# Execute o cliente iperf a partir de sua máquina (apontando para o IP do firewall)
iperf3 -c 192.168.10.1
Boas práticas
- Comece pelo simples: ping, logs, status.
- Forme hipóteses, teste uma de cada vez.
- Registre mudanças e resultados.
- Use captura de pacotes para "visualizar" o tráfego de rede.
- Mantenha retenção e syslog remoto adequados.
- Evite “mudanças grandes” em horário crítico.
- Tenha um plano de rollback (backup da config).
Conclusão
O OPNsense concentra tudo o que você precisa para diagnosticar: logs ricos, ferramentas de rede, testes de autenticação, status de serviços, console completo e até API. Com um método claro — observar, isolar, validar, corrigir — você transforma problemas nebulosos em incidentes explicados e resolvidos, com menos tempo gasto e mais previsibilidade operacional.