A script to sync the Netbox device inventory to Zabbix.
Tested with:
- Netbox 4+
- Zabbix 7+
This script may work with older versions but is not guaranteed.
It is recommended to install within a venv for isolation from other packages.
git clone https://github.com/dmcken/netbox-zabbix-sync.git
cd netbox-zabbix-sync
python -m venv .venv
.venv/bin/pip install -r requirements.txtInsert into your crontab (crontab -e) to run the sync every 5 minutes (update the home directory to appropriate path):
*/5 * * * * cd /home/<username>/netbox-zabbix-sync/ && ./.venv/bin/python netbox_zabbix_sync.py
If you're also using the backhaul map generator (see "Site maps" below), add a second line on a slower cadence, since topology and utilization change far less often than device state:
*/15 * * * * cd /home/<username>/netbox-zabbix-sync/ && ./.venv/bin/python generate_backhaul_map.py
| Flag | Option | Description |
|---|---|---|
| -j | journal | Create journal entries in Netbox when a host gets added, modified or deleted in Zabbix. |
| -s | single host | Attempt to sync a single host (pending). Mainly used for troubleshooting. |
| -v | verbose | Log with debugging on. |
Logs are generated by default to stdout and sync.log, use -v for debugging.
Groups are created and the hosts automatically populated based on the following fields if set on the device (all appropriate groups are applied).
| Field | Group Format | Description |
|---|---|---|
| Location | Location - [Location Name] | |
| Site | Site - [Site Name] | |
| Rack | Rack - [Rack Name] | |
| Role | Role - [Device Role] | |
| Tenant | Tenant - [Tenant Name] |
Now a custom tag of "ZabbixGroup#Hello" will proceed to create the group "Hello" if it doesn't exist and place the devices bearing that tag inside of that group.
As the network source-of-truth any and all special configuration should be kept within netbox and pushed out to zabbix.
By setting a status on a Netbox device you determine how the host is added (or updated) in Zabbix. There are, by default, 3 options and their matching netbox statuses:
- Create the host in Zabbix with an enabled status:
- Active
- Create or update the host in Zabbix but with a disabled status:
- Failed
- Offline
- Planned
- Staged
- Delete the host from Zabbix:
- Decommissioning
- Inventory
You can modify this behaviour by changing the following list variables in the script:
- zabbix_device_removal
- zabbix_device_disable
Current versions of zabbix using the Network interfaces discovery are using the macro IFCONTROL to mark interfaces as not important in the form {$IFCONTROL:"eth0"} set to 0 will not trigger an alert if eth0 goes down on that host.
You can set the proxy for a device using the 'proxy' key in config context.
{
"zabbix": {
"proxy": "yourawesomeproxy.local"
}
}Because of the posible amount of destruction when setting up Netbox but forgetting the proxy command, the sync works a bit different. By default everything is synced except in a situation where the Zabbix host has a proxy configured but nothing is configured in Netbox. To force deletion and a full sync, use the -p flag.
When adding a new device, you can set the interface type with custom context. Due to Zabbix limitations of changing interface type with a linked template, changing the interface type from within Netbox is not supported and the script will generate an error.
For example when changing a SNMP interface to an Agent interface:
Netbox-Zabbix-sync - WARNING - Device: Interface OUT of sync.
Netbox-Zabbix-sync - ERROR - Device: changing interface type to 1 is not supported.
To configure the interface parameters you'll need to use custom context. Custom context was used to make this script as customizable as posible for each environment. For example, you could:
- Set the custom context directly on a device
- Set the custom context on a label, which you would add to a device (for instance, SNMPv3)
- Set the custom context on a device role
- Set the custom context on a site or region
{
"zabbix": {
"interface_port": 1500,
"interface_type": 1
}
}{
"zabbix": {
"interface_port": 161,
"interface_type": 2,
"snmp": {
"bulk": 0,
"community": "SecretCommunity",
"version": 1
}
}
}{
"zabbix": {
"interface_port": 161,
"interface_type": 2,
"snmp": {
"bulk": 1,
"community": "SecretCommunity",
"version": 2
}
}
}{
"zabbix": {
"interface_port": 1610,
"interface_type": 2,
"snmp": {
"authpassphrase": "SecretAuth",
"bulk": 1,
"securitylevel": 1,
"securityname": "MySecurityName",
"version": 3
}
}
}Note: Not all SNMP data is required for a working configuration. The following parameters are allowed but are not all required, depending on your environment.
Make sure that the user has proper permissions for device read and modify (modify to set the Zabbix HostID custom field) operations.
netbox_zabbix_sync.py pushes each device's Netbox site latitude/longitude into the Zabbix host's Inventory (location_lat/location_lon, inventory_mode set to Manual), for any site that has coordinates set. Devices at sites without coordinates are skipped silently.
Once a handful of hosts have coordinates populated, create a Geomap widget on a Zabbix dashboard (Dashboards → Edit dashboard → Add widget → type "Geomap") to see them plotted on a real map, colored by live problem severity. This widget is a one-time manual setup step; it isn't created automatically.
generate_backhaul_map.py builds a map of the inter-site wireless backhaul links (from Netbox's Wireless Links) and writes it to a dedicated Zabbix map, WISP - Auto Backhaul (1200×900 canvas). It never modifies the hand-built WISP - Overview map at all.
Sites tagged core-site in Netbox are pulled toward an inner ring around the center; every other linked site sits on an outer ring. Dead center is a synthetic Internet cloud element, connected to any site with a Netbox circuit of type BGP or DIA terminating there (other circuit types, e.g. WAN, are not treated as Internet uplinks). That edge is labelled with the circuit's provider and provisioned speed rather than live utilization, since it's not a Zabbix-monitored radio. A site with such a circuit is added to the map even if it isn't otherwise part of the wireless backhaul mesh (e.g. a datacenter) - tag it core-site too if it should sit near the center rather than on the outer ring. Backhaul links are annotated with a live capacity/utilization label pulled from Zabbix (e.g. 142 Mbps / 45%, or no data where a link's SNMP items aren't currently populated).
Every site element is clickable and drills down into a per-site map, auto-created the same way (named after the site, e.g. Tower - FIB), with that site's Zabbix hosts (from its Site - <name> hostgroup) laid out around its core/edge router (matched by hostname, e.g. FIB-CE1, or the lowest-numbered <CODE>-CE<N> if CE1 doesn't exist) at the center. Canvas size scales with host count (700px minimum, 2200px cap).
Links on a site map are drawn only for real Netbox cable connections between two hosts already on that map - never a fabricated star or other assumed topology. A host with no cable recorded in Netbox yet is simply left unconnected on its map; as gaps in Netbox's cabling data get filled in, the corresponding links appear on the next run with no extra steps. Each real link is labelled with a live bandwidth/utilization reading resolved from the exact Zabbix SNMP interface Netbox says it uses (e.g. 142 Mbps / 45%, or no data if that interface isn't reporting).
The script fully regenerates every map's elements and links on every run - it holds no state of its own, so it's safe to run repeatedly (e.g. every 15 minutes via cron, see above) or by hand:
./.venv/bin/python generate_backhaul_map.py -vKnown limitation: per-link capacity/utilization is resolved by matching Zabbix item key prefixes (net.if.in/net.if.out/net.if.speed for SNMP-monitored radios, throughput.*/capacity.* for others) and preferring an item whose name contains "radio" when a host exposes multiple interfaces polled in the same cycle. This is a best-effort heuristic, not a guarantee - if a link shows no data, check that the backhaul host's SNMP polling is actually populated in Zabbix first.
To make the user experience easier you could add a custom link that redirects users to the Zabbix latest data.
- Name:
zabbix_latestData - Text:
{% if obj.cf["zabbix_hostid"] %}Show host in Zabbix{% endif %} - URL:
{ZABBIX_URL} /zabbix.php?action=latest.view&filter_hostids[]={{ obj.cf["zabbix_hostid"] }}&filter_application=&filter_select=&filter_set=1