Skip to content

Guide 01 — NetBox Data Model: Changes Needed to Drive Zabbix Cleanly

NetBox becomes the source of truth: what's in NetBox (and how it's modelled) directly determines what appears in Zabbix, which templates it gets, and which host group it lands in. This guide defines the data-model conventions to apply before switching the sync on. Getting these right first avoids re-doing 500 devices later.

1. Sites and site groups

One NetBox site per physical location:

  • colo — the colo facility
  • metro-<name> — one per metro hub
  • venue-<name> — one per venue (40 sites)

Add site groups to classify them: Colo, Metro, Venues. The sync maps site → Zabbix host group, so this yields groups like Venues/venue-kings-arms automatically. Keep slugs lowercase-kebab and stable — they become host group names and dashboard variables; renaming later ripples everywhere.

2. Device roles (canonical list)

Device role is the primary key for template assignment. Use exactly one canonical list — audit existing entries and merge duplicates (ap vs wifi-ap vs access-point must become one role):

Role slug Applies to Zabbix template(s)
hypervisor Proxmox nodes Linux by Zabbix agent (+ Proxmox VE by HTTP on one cluster host object)
db-server Physical SQL boxes Linux/Windows agent + SQL template
firewall OPNsense OPNsense agent/SNMP templates
router MikroTik venue + metro routers MikroTik by SNMP
core-switch Metro/core kit Vendor SNMP template
switch UniFi venue switches UniFi/generic SNMP template
wifi-ap UniFi APs UniFi AP SNMP template
till Windows till PCs Trimmed Windows by Zabbix agent (active)
server Generic VMs/servers Linux/Windows by Zabbix agent

Roles that must never be monitored (patch panels, PDUs without SNMP, etc.) simply don't get a mapping in the sync config — unmapped roles are skipped.

3. Platforms

Set platform on every monitored device — the sync uses role+platform to pick agent vs SNMP flavours:

linux, windows, routeros, unifi, opnsense, proxmox

4. Naming convention

Device name = Zabbix host name = agent hostname on the device (critical for active checks from tills). Convention:

<site-slug>-<role>-<nn>     e.g.  venue-kings-arms-till-01
                                  venue-kings-arms-ap-03
                                  colo-pve-02

Names must be unique NetBox-wide. The till agent installer must set Hostname= to exactly this name.

5. Primary IPs — the hard data-quality requirement

Every monitored device must have a primary IPv4 assigned in NetBox. The sync builds the Zabbix interface from it; no primary IP → no monitoring. This is usually the biggest gap in a part-populated NetBox. Worth doing venue-by-venue with a checklist, and adding a NetBox saved filter/report for "status=active, no primary IP" to catch drift.

6. Status discipline

NetBox status drives monitoring state:

NetBox status Zabbix effect
active Host enabled and monitored
planned / staged Not synced (or synced disabled)
offline / decommissioning Host disabled in Zabbix
Deleted from NetBox Host removed from Zabbix

This gives you a decommissioning workflow for free: mark a till offline in NetBox and its alerts stop — no separate Zabbix housekeeping.

7. Custom fields for the sync

netbox-zabbix-sync needs a small number of custom fields (created once, per its docs — exact names depend on the tool version):

  • Zabbix host ID (integer, on device/VM) — written back by the sync; leave alone.
  • Optional per-device template override and no-monitor flag for exceptions, so the role mapping stays clean and exceptions stay visible in NetBox.

Template mapping itself lives in the sync's config file (role/platform → template list), version-controlled in git — not scattered through NetBox.

8. Virtual machines

Model the Proxmox cluster under NetBox Virtualization (cluster type proxmox, one cluster, VMs with roles/platforms/primary IPs like devices). Two options:

  • Hand-maintained — fine at dozens of VMs; matches the "NetBox is truth" rule.
  • Auto-populated from Proxmox via a community netbox-proxmox sync — better long term, one more moving part. (Open question in the spec.)

Note hypervisor-level VM monitoring (CPU/mem/disk/state per VM) comes from the Proxmox VE by HTTP template's discovery regardless — NetBox VM entries are only needed for guest-level agent monitoring.

9. Venue rollout pattern

Since venues are near-identical, populate them by pattern:

  1. Model one venue completely (router, switch, 5 APs, 5 tills, IPs, names, roles).
  2. Export/script the pattern (NetBox scripts or pynetbox) parameterised by venue slug and IP ranges.
  3. Apply per venue; spot-check the sync result for the first 2–3 venues.

10. What NOT to put in NetBox

  • SNMP credentials / agent PSKs — keep in Zabbix as global secret macros (one SNMPv3 credential set estate-wide), not in NetBox fields.
  • Monitoring thresholds — live in Zabbix templates/macros.
  • Anything Zabbix can discover itself (interfaces, disks, VMs on a node) — LLD handles it; NetBox holds identity and topology, not telemetry detail.

Pre-flight checklist before enabling the sync

  • [ ] Sites exist for colo, all metro hubs, all venues, grouped Colo/Metro/Venues
  • [ ] Device roles merged to the canonical list; role mapping agreed
  • [ ] Platforms set on all monitored devices
  • [ ] Names follow the convention and are unique
  • [ ] Every active device has a primary IPv4
  • [ ] Statuses reflect reality (nothing active that's in a cupboard)
  • [ ] Custom fields created; sync config in git