Skip to content

Guide 03 — NetBox → Zabbix Sync

Wires NetBox (source of truth) to Zabbix (monitoring engine) using the open-source netbox-zabbix-sync tool. After this guide, hosts are never created by hand in Zabbix again.

Prerequisite: the NetBox pre-flight checklist in Guide 01 passes.

1. How it works

The tool reads devices/VMs from the NetBox API and creates/updates/disables the corresponding Zabbix hosts via the Zabbix API:

  • NetBox site → Zabbix host group (via site-group/site path)
  • NetBox device role + platform → Zabbix template(s) (mapping in the sync config)
  • NetBox primary IPv4 → Zabbix interface (agent or SNMP per mapping)
  • NetBox status → host enabled/disabled/removed
  • NetBox role/tags → Zabbix tags (role:till, site:venue-x)
  • Writes the Zabbix host ID back to a NetBox custom field for tracking

2. Installation and configuration

  1. Deploy on the Zabbix server VM (it's a Python tool + config file; run from a venv or container).
  2. Create API credentials: a NetBox read token and a Zabbix API user with host create/update rights. Store both outside git.
  3. Author the mapping config — role/platform → template list, host group format, interface type (agent active for till/server, SNMPv3 for network roles, agentless for API-checked objects). Commit the config to this repo.
  4. Dry-run against 2–3 NetBox devices first (a till, an AP, a hypervisor) and verify the resulting Zabbix hosts: right group, right template, right interface, right tags.

3. Scheduling

  • Cron: hourly full reconcile — the safety net that converges Zabbix to NetBox.
  • NetBox webhook → sync trigger on device create/update/delete for near-instant changes. (Optional at first; hourly alone is fine to start.)
  • Log output somewhere Zabbix can see; add a Zabbix item + trigger on "sync has not succeeded in >3 hours" so a broken sync is itself an alert.

4. Operating rules

  1. Never create/edit hosts in the Zabbix UI. The sync will fight you and win.
  2. Exceptions (extra template, don't-monitor) are expressed in NetBox custom fields, not Zabbix edits.
  3. Template/threshold tuning happens in Zabbix templates and macros — the sync owns host objects, not template internals.
  4. Decommission = set NetBox status offline; never delete the Zabbix host by hand.

5. Rollout order

Sync in waves matching the migration plan (Guide 06): colo devices first, then metro, then one pilot venue, then venues in batches. Restrict early runs with the tool's site/role filters so a mapping mistake affects ten hosts, not seven hundred.