Skip to content

Quick Start

This guide gets a first sync running in a few minutes with the default settings.

1. Create API credentials

  • NetBox: create an API token with write access. NetBox 4.5 and later also support v2 tokens (nbt_<key>.<token>).
  • Zabbix: create an API token, or use a username and password.

See Permissions for the rights both accounts need.

2. Prepare NetBox

The script stores the Zabbix host ID of every synced object in a NetBox custom field. Create it before the first run:

  1. Go to Customization → Custom Fields in NetBox.
  2. Create the zabbix_hostid field as described in NetBox preparation and assign it to:
  3. DCIM > Device
  4. Virtualization > Virtual machine, if you plan to sync VMs
  5. By default, a device gets its Zabbix template from the zabbix_template custom field on its device type. Create that field as well, and enter a template name on the device types you want to monitor.

A device is only synced when it has a name, a primary IP address and a template.

3. Run the container

docker run --rm \
  -e NETBOX_HOST=https://netbox.example.com \
  -e NETBOX_TOKEN=your_netbox_token \
  -e ZABBIX_HOST=https://zabbix.example.com \
  -e ZABBIX_USER=api_user \
  -e ZABBIX_PASS=api_password \
  ghcr.io/thenetworkguy/netbox-zabbix-sync:latest

If you use a Zabbix API token, set ZABBIX_TOKEN instead of ZABBIX_USER and ZABBIX_PASS. Setting both is an error.

The container runs one sync and exits. Run it on a schedule, for example with cron or a systemd timer, to keep Zabbix up to date.

Next steps

The defaults are enough for a first run. To change the hostgroup layout, sync virtual machines, or add tags, macros and inventory, see: