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 work fine for now. Do you want more features? Check out the installation section and advanced features.