Skip to content

Preparation

Before the first sync, create the custom fields the script needs in NetBox and give the API accounts the right permissions.

Custom fields

The script stores the Zabbix host ID on every synced NetBox object, and by default reads the Zabbix template from the device type. Both use custom fields.

Required custom fields

Create the following custom fields in NetBox → Customization → Custom Fields.

zabbix_hostid

  • Type: Integer
  • Name: zabbix_hostid
  • Required: No
  • Default: null
  • Object types: DCIM > Device, and Virtualization > Virtual machine if you sync VMs

The script writes the ID of the Zabbix host to this field after creating it, and uses the ID to find the host on later runs. Objects without this field are skipped with an error.

You can make the field hidden or read-only in the UI to prevent accidental changes. Leaving it editable lets you change the link by hand:

  • Clear the field to make the script create a new host on the next run, for example after the Zabbix host was deleted by hand.
  • Enter the ID of an existing Zabbix host to let the script take over that host. Without the ID, the script refuses to create a host whose name already exists in Zabbix.

The field name can be changed with the device_cf setting.

zabbix_template

  • Type: Text
  • Name: zabbix_template
  • Required: No
  • Default: null
  • Object types: DCIM > Device type

Holds the name of the Zabbix template for all devices of a device type. The field name can be changed with the template_cf setting.

This field is not needed if you take templates from config context instead (templates_config_context = True). Virtual machines always take their templates from config context. See Template source.

Optional custom fields

Field Object types Used for
Proxy and proxy group fields, for example zabbix_proxy and zabbix_proxy_group Device, Virtual machine, Site Assigning a Zabbix proxy or proxy group. Enable them with the proxy_cf and proxy_group_cf settings
Any field of type Text, Selection or Object Device, Virtual machine Using the value in the hostgroup name

Permissions

NetBox

The NetBox API token must have write access enabled. The account needs:

  • View permission on the synced devices and virtual machines, and on the related objects the script reads: device types, sites, regions, site groups, tenants, clusters and custom fields. With extended_virtual_chassis or extended_ips enabled, it also needs to view virtual chassis or IP addresses.
  • Change permission on devices and virtual machines, to write the Zabbix host ID.
  • Add permission on journal entries, if create_journal is enabled.

Zabbix

The Zabbix account needs:

  • Read access to host groups, templates and proxies. On Zabbix 7.0 and later, also proxy groups.
  • Read-write access to the host groups the script places hosts in, so it can create, update and delete hosts and their interfaces.
  • Permission to create host groups if create_hostgroups is enabled. Zabbix only allows hostgroup.create for Super admin users. If the account is not a Super admin, set create_hostgroups = False and create the host groups yourself.

Hostgroups are nested (for example Europe/Amsterdam/Switches). To grant access to a whole tree, give the user group permission on the top-level host group and enable Include subgroups.

Custom links in NetBox can take users from a device or VM straight to its host in Zabbix. With a bit of Jinja2, the link only shows on objects that have been synced, so objects such as patch panels do not get a link.

Create the links in Customization → Custom Links, and assign them to the object types DCIM > Device and Virtualization > Virtual machine.

- Name: zabbix_latestdata
- Text: {% if object.cf["zabbix_hostid"] %}Show host in Zabbix{% endif %}
- URL:  http://myzabbixserver.local/zabbix.php?action=latest.view&hostids[]={{ object.cf["zabbix_hostid"] }}

- Name: zabbix_problem
- Text: {% if object.cf["zabbix_hostid"] %}Show problems in Zabbix{% endif %}
- URL:  http://myzabbixserver.local/zabbix.php?action=problem.view&filter_set=1&hostids%5B0%5D={{ object.cf["zabbix_hostid"] }}