Documentação

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

A 5.6.0 traz desfazer/refazer do layout (Ctrl/Cmd+Z), um chassis-id LLDP tipado e o IP de gerência dos vizinhos (menos arestas erradas, fantasmas com IP real, "criar host" preenche uma interface SNMP) e um orçamento PoE com alerta e tendência de seis horas. Desde a 5.5.27 também: detecção de anéis/loops e spanning-tree, PoE por porta, a visão VLAN, fundos aéreos e de planta baixa e um oitavo widget (NT WLAN). A lista completa está no changelog.

Q: 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?

Q: Como o módulo conhece as conexões?

Principalmente a partir de LLDP e CDP — as tabelas de vizinhos que switches, roteadores e access points gerenciados expõem via SNMP. O módulo as lê por meio de templates SNMP incluídos, transforma cada cabo reportado numa aresta (uma por par de portas) e resolve os vizinhos contra os hosts monitorados no Zabbix — por chassis-id, IP de gerência ou MAC. Além disso: tags de host (nt:parent) para relações de suporte e links manuais para tudo que nenhum protocolo reporta. Um agente Zabbix puro não fornece nada disso — é preciso SNMP com LLDP/CDP nos dispositivos.

Q: Quais switches e fabricantes são suportados — e se o meu não estiver?

LLDP e CDP são padrões, então o módulo é independente de fabricante — em uso com MikroTik, Cisco, HPE/Aruba, TP-Link e Ubiquiti, entre outros. O que importa não é a marca, mas que o dispositivo fale LLDP (ou CDP) e entregue sua tabela de vizinhos via SNMP. Se um dispositivo aparece errado ou não aparece, um SNMP walk curto costuma dizer por quê: há scripts de sonda e um guia sobre enviar informações anonimizadas para que seu modelo seja suportado corretamente — veja a seção "Tested hardware" no CONTRIBUTING.

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

Oito widgets trazem os dados do módulo direto para o seu dashboard: um grafo de topologia, um faceplate (painel frontal do switch com PoE), um health score por grupo de hosts, um donut de KPI, um pivot de itens, uma lista de hosts estilo Nagios, Plan (planta baixa / imagem aérea) e WLAN (access points). Todos usam a mesma fonte de dados do módulo principal — sem segundo serviço, sem configuração extra.

Dashboard do Zabbix com widgets NT: grafo de topologia, donut de KPI, health score, tabelas de itens e hosts — Widgets NT 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, 7.4 ou 8.0. 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 oito 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 unzip network_topology_faceplate_widget.zip -d network_topology_faceplate_widget
sudo unzip network_topology_plan_widget.zip -d network_topology_plan_widget
sudo unzip network_topology_wlan_widget.zip -d network_topology_wlan_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 oito 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 oito widgets de dashboard rodam no Zabbix 7.0 LTS, 7.4 e 8.0. Versões mais antigas não são oficialmente suportadas. O tema escuro adapta-se automaticamente — inclusive ao dark-blue do Zabbix 8.

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?

Cinco vistas principais: Technical (grafo de forças), Management (wallboard), Table (lista de hosts/pivot), Geo (mapa Leaflet) e Plan (planta baixa / imagem aérea) — além de abas de análise como Health, Stats, LLDP-Q, Compliance e Diag. Tudo a partir dos mesmos dados.

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

A 5.6.0 traz desfazer/refazer do layout (Ctrl/Cmd+Z), um chassis-id LLDP tipado e o IP de gerência dos vizinhos (menos arestas erradas, fantasmas com IP real, "criar host" preenche uma interface SNMP) e um orçamento PoE com alerta e tendência de seis horas. Desde a 5.5.27 também: detecção de anéis/loops e spanning-tree, PoE por porta, a visão VLAN, fundos aéreos e de planta baixa e um oitavo widget (NT WLAN). A lista completa está no changelog.

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?

Qual a diferença para os mapas de rede nativos do Zabbix?

Os mapas de rede do próprio Zabbix são desenhados e mantidos à mão — cada ícone, cada linha. O Network Topology descobre as conexões sozinho a partir das tabelas de vizinhos LLDP/CDP e mostra status, problemas e tráfego nelas ao vivo. Nenhum mapa que fica desatualizado assim que alguém troca um cabo. Além disso, cinco visões (grafo, wallboard, tabela, Geo, Plan), uma simulação de falha e abas de análise — tudo a partir dos mesmos dados. À mão ainda funciona (a tag nt:parent, links desenhados), mas é a exceção, não a base.

Como o módulo conhece as conexões?

Principalmente a partir de LLDP e CDP — as tabelas de vizinhos que switches, roteadores e access points gerenciados expõem via SNMP. O módulo as lê por meio de templates SNMP incluídos, transforma cada cabo reportado numa aresta (uma por par de portas) e resolve os vizinhos contra os hosts monitorados no Zabbix — por chassis-id, IP de gerência ou MAC. Além disso: tags de host (nt:parent) para relações de suporte e links manuais para tudo que nenhum protocolo reporta. Um agente Zabbix puro não fornece nada disso — é preciso SNMP com LLDP/CDP nos dispositivos.

Quais switches e fabricantes são suportados — e se o meu não estiver?

LLDP e CDP são padrões, então o módulo é independente de fabricante — em uso com MikroTik, Cisco, HPE/Aruba, TP-Link e Ubiquiti, entre outros. O que importa não é a marca, mas que o dispositivo fale LLDP (ou CDP) e entregue sua tabela de vizinhos via SNMP. Se um dispositivo aparece errado ou não aparece, um SNMP walk curto costuma dizer por quê: há scripts de sonda e um guia sobre enviar informações anonimizadas para que seu modelo seja suportado corretamente — veja a seção "Tested hardware" no CONTRIBUTING.