Documentação

Tudo para instalar, configurar e usar os módulos do ZabFox.

Getting Started

Instale e habilite o módulo Network Topology no seu ambiente Zabbix 7.0 LTS ou 7.4. Sem servidor extra — tudo roda no frontend.

bash · instalar módulo

# Para a pasta de módulos da interface do Zabbix
cd /usr/share/zabbix/ui/modules

# Descompacte o release (o nome do diretório é obrigatório)
sudo unzip ~/Downloads/network_topology.zip
sudo chown -R root:root network_topology

# Recarregue o PHP-FPM
sudo systemctl reload php8.3-fpm

Pronto em quatro passos

01DescompactarComo network_topology.

02Scan directoryAdministration → Modules.

03HabilitarHabilite o módulo.

04ComeçarMonitoring → Topology.

Atualizando de uma versão 5.x? Substitua os arquivos do módulo e recarregue o php-fpm — não é preciso Scan directory, nenhuma ação nova foi adicionada.

Widgets de dashboard · opcional

Cinco widgets trazem os dados do módulo direto para o seu dashboard: um grafo de topologia, um health score por grupo de hosts, um donut de KPI, um pivot de itens e uma lista de hosts estilo Nagios. Todos os cinco usam a mesma fonte de dados do módulo principal — sem segundo serviço, sem configuração extra.

Dashboard do Zabbix com todos os cinco widgets: grafo de topologia, donut de KPI, health score, tabelas de itens e hosts — Todos os cinco widgets em um dashboard do Zabbix — grafo de topologia, donut de KPI, health score e tabelas de itens e hosts (dados de demonstração).

Requisitos: Zabbix 7.0 LTS ou 7.4. E um módulo principal instalado e habilitado: os widgets buscam nele tanto os dados quanto a biblioteca de grafos (Cytoscape.js), então não funcionam sozinhos. Ordem: primeiro o módulo principal, depois os widgets.

Os cinco ZIPs dos widgets estão como release assets em GitHub — descompacte-os na pasta de módulos:

instalação dos widgets

# Para a pasta de módulos da interface do Zabbix
cd /usr/share/zabbix/ui/modules

# Cada widget na SUA PRÓPRIA pasta (-d) — os ZIPs não têm pasta raiz
sudo unzip network_topology_widget.zip -d network_topology_widget
sudo unzip network_topology_health_widget.zip -d network_topology_health_widget
sudo unzip network_topology_table_widget.zip -d network_topology_table_widget
sudo unzip network_topology_kpi_widget.zip -d network_topology_kpi_widget
sudo unzip network_topology_items_widget.zip -d network_topology_items_widget
sudo chown -R root:root network_topology_*

# recarregue o php-fpm (nome do serviço depende da distro/versão do PHP)
sudo systemctl reload php8.3-fpm

Depois vá em Administration → General → Modules → Scan directory e defina os cinco módulos como Enabled. Eles aparecem então no editor de dashboard em “Add widget”.

FAQ

O módulo precisa de um servidor extra?

Não. O Network Topology roda inteiramente no frontend do Zabbix como um módulo PHP — sem serviço extra, sem servidor separado.

Qual versão do Zabbix é suportada?

O módulo principal e os cinco widgets de dashboard rodam no Zabbix 7.0 LTS e 7.4. Versões mais antigas não são oficialmente suportadas.

O ZabFox é gratuito e open source?

Sim. O módulo Network Topology é publicado sob AGPL-3.0 e de uso livre.

Como instalo o módulo?

Descompacte o release em ui/modules/ (pasta network_topology), recarregue o php-fpm e habilite em Administration → Modules — cerca de dois minutos.

Quais visões existem?

Quatro: Technical (grafo de forças), Management (wallboard), Table (lista de hosts/pivot) e Geo (mapa Leaflet) — a partir dos mesmos dados.

O que há de novo na versão mais recente?

A v5.4.0 desenha cabos paralelos individualmente: um bundle LACP se abre em leque ao dar zoom, virando uma aresta por cabo — cada uma com suas próprias portas, tráfego e utilização — e um membro que falha é reportado por conta própria, em vez de desaparecer na aresta combinada. A tabela agora mostra o dispositivo e a porta do outro lado (ordenável, filtrável, com exportação CSV). Antes disso, a v5.3.2 trouxe as correções vindas de relatos (sem arestas falsas por nomes MAC curtos/IPs duplicados) e as tags nt:uplink/nt:lldp, e a v5.3.0 o painel de detalhes por aresta, o confidence scoring e a exportação GraphML. Desde a v5.0.0 o módulo se chama uniformemente network_topology.

E dispositivos que não reportam topologia alguma — switches não gerenciáveis, firewalls sem LLDP?

Depende do dispositivo, e há dois casos distintos.

Um switch não gerenciável costuma ser invisível. Ele não fala LLDP, mas encaminha os quadros porque nunca os processa. Assim, os dispositivos gerenciados de cada lado enxergam um ao outro e aparecem diretamente conectados no mapa. Topologicamente isso está errado — mas a afirmação “estes dois estão conectados” continua valendo.

Um firewall sem LLDP é o caso mais chato. O Zabbix o monitora, então ele aparece como nó — mas sem arestas. Fica no mapa como uma ilha, mesmo que metade do seu tráfego passe por ele.

Como preencher as lacunas:

Tag de host nt:parent=<hostname> — o caminho recomendado. Adicione uma tag no host nomeando o dispositivo do qual ele depende, p.ex. nt:parent = fw-core. É uma tag de host comum do Zabbix, então vive no servidor e todo usuário a vê. Pensada para relações de dependência (VM→hypervisor, container→nó), mas funciona igualmente bem para “este host fica atrás daquele firewall”. A simulação de falha a trata como dependência rígida: se o pai morre, o filho morre — independentemente do caminho de rede.
Links manuais desenhados direto no mapa (modo estrela). Rápido para a sua própria visão. Ressalva: eles vivem no localStorage do navegador, então são por usuário e por dispositivo — seu colega não os verá. Para documentar uma topologia compartilhada, a tag é a ferramenta certa.
Nós fantasma cobrem o caso inverso: se um vizinho reporta um dispositivo que não é monitorado no Zabbix, ele aparece como um marcador tracejado. A lacuna fica visível em vez de desaparecer.

Importante para a simulação de falha: ela só conhece as arestas que recebeu. Um dispositivo que não está no grafo não pode ser simulado como ponto de falha — e uma aresta desenhada à mão que não corresponde à realidade fará a simulação errar com confiança. Para os caminhos que realmente importam, vale conferir: essas arestas são medidas ou presumidas?