Quick Start

Quick Start

This guide will get the script running in just a few minutes using the minimum required configuration.

---

Prerequisites

Make sure you have:

• Reachability to your NetBox API
• Reachability to your Zabbix API
• A NetBox API token
• A Zabbix user or API token with permissions to create and update hosts

---

Step 1 — Create Required Tokens

NetBox

1. Go to User → API Tokens
2. Create a new token
3. Ensure the token has read access to:
   • Devices
   • Virtual Machines
   • Interfaces
   • IP Addresses
4. Ensure the token has write access to:
   • Devices
   • VMs This is required to link a Netbox object to a Zabbix HostID. Another write-action to Netbox is for Journal support which is not enabled by default.

Save the token.

Zabbix

Use either:

• A dedicated API user with appropriate permissions
• Or an API token (recommended for newer Zabbix versions)

The user/token must be able to:

• Create hosts
• Update hosts
• Manage host groups

---

Prepare Netbox

Before running the script, you must create two custom fields in NetBox.
These fields are required for syncing to work correctly.

1. Go to Customization → Custom Fields in NetBox.
2. Create the two required custom fields as described in the NetBox Preparation section of the documentation.
3. Ensure the fields are assigned to:
   • Devices
   • Virtual Machines (if VM syncing is enabled)

Without these custom fields, the script will not be able to properly identify and manage synced objects in Zabbix.

---

Option A — Run with Docker (Recommended)

docker run \
  -e NETBOX_URL=https://netbox.example.com \
  -e NETBOX_TOKEN=your_netbox_token \
  -e ZABBIX_URL=https://zabbix.example.com \
  -e ZABBIX_USERNAME=api_user \
  -e ZABBIX_PASSWORD=api_password \
  ghcr.io/thenetworkguy/netbox-zabbix-sync:latest

Option B — Run with Python

Follow these steps to run the script directly using Python.

1. Clone the repository

git clone https://github.com/TheNetworkGuy/netbox-zabbix-sync.git
cd netbox-zabbix-sync

2. Create a virtual environment

Linux/macOS

python3 -m venv venv
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Configure environment variables

export NETBOX_URL=https://netbox.example.com
export NETBOX_TOKEN=your_netbox_token
export ZABBIX_URL=https://zabbix.example.com
export ZABBIX_USERNAME=api_user
export ZABBIX_PASSWORD=api_password

5. Run the script

python netbox_zabbix_sync.py

What happens next

• The script connects to NetBox and retrieves objects based on your configuration.
• It connects to Zabbix and creates or updates matching hosts.

Obviously there are many different options to adjust. However most default settings will do fine