Configuration¶
The script works with its built-in defaults, so a configuration file is optional. To change a setting, use one of the following, listed from lowest to highest priority:
- The built-in defaults
- The configuration file,
config.py - Environment variables starting with
NBZX_ - Command-line flags
When you use the Python package in your own code, only the defaults and the dictionary passed to Sync() are used.
Config file¶
Copy config.py.example to config.py and change the settings you need. The example file documents every setting and is a good starting point.
The script looks for config.py next to netbox_zabbix_sync.py, and then in the current working directory. Use -c / --config to load a file from a different location.
Note
If the file is not found, the script silently falls back to the defaults. Settings in the file that the script does not know, for example because of a typo, are ignored without a warning.
Configuration options¶
Every setting below can be set in config.py. The links in the descriptions lead to a detailed explanation of each feature.
General¶
| Setting | Type | Default | Description |
|---|---|---|---|
device_cf |
String | "zabbix_hostid" |
Custom field on devices and VMs that stores the Zabbix host ID. See Preparation |
nb_device_filter |
Dict | {"name__n": "null"} |
NetBox API filter that selects the devices to sync. The default selects all devices with a name. See Filtering |
sync_vms |
Boolean | False |
Also sync virtual machines. See Virtual machines |
nb_vm_filter |
Dict | {"name__n": "null"} |
NetBox API filter that selects the virtual machines to sync |
zabbix_device_removal |
List | ["Decommissioning", "Inventory"] |
NetBox statuses that delete the host from Zabbix. See Device and VM status |
zabbix_device_disable |
List | ["Offline", "Planned", "Staged", "Failed"] |
NetBox statuses that disable the host in Zabbix |
create_journal |
Boolean | False |
Write a NetBox journal entry for every change. See Journal entries |
Templates¶
| Setting | Type | Default | Description |
|---|---|---|---|
template_cf |
String | "zabbix_template" |
Custom field on device types that holds the template name. See Template source |
templates_config_context |
Boolean | False |
Take device templates only from config context, instead of the custom field |
templates_config_context_overrule |
Boolean | False |
Take device templates from the custom field, but use config context templates instead when the device has them |
Hostgroups¶
| Setting | Type | Default | Description |
|---|---|---|---|
hostgroup_format |
String or list | "site/manufacturer/role" |
Hostgroup layout for devices. See Hostgroups |
vm_hostgroup_format |
String or list | "cluster_type/cluster/role" |
Hostgroup layout for virtual machines |
create_hostgroups |
Boolean | True |
Create missing hostgroups in Zabbix. Needs a Super admin account in Zabbix |
traverse_regions |
Boolean | False |
Use the full region path, for example Europe/Netherlands/Amsterdam, instead of only the assigned region |
traverse_site_groups |
Boolean | False |
Use the full site group path instead of only the assigned site group |
Extra NetBox data¶
These settings make the script fetch more data from NetBox for use in inventory, tags, usermacros and interfaces. Each one adds API calls per host, which can slow down large syncs.
| Setting | Type | Default | Description |
|---|---|---|---|
extended_site_properties |
Boolean | False |
Fetch all site properties instead of only the name, slug and description. See Extended site properties |
extended_virtual_chassis |
Boolean | False |
Fetch all virtual chassis properties, including its members |
extended_ips |
Boolean | False |
Fetch all IP address properties, such as the DNS name. Added in v4.1 |
Interfaces¶
| Setting | Type | Default | Description |
|---|---|---|---|
preferred_ip |
String | "auto" |
Which IP address the interface uses: auto (the NetBox primary IP), ipv4 or ipv6. See IP address selection. Added in v4.1 |
prefer_dns |
Boolean | False |
Connect to the interface by DNS name instead of IP address when a DNS name is known. Added in v4.1 |
oob_sync |
Boolean | False |
Add a second interface for the out-of-band IP of devices. See Out-of-band interfaces. Added in v4.1 |
Clustering¶
| Setting | Type | Default | Description |
|---|---|---|---|
clustering |
Boolean | False |
Create one Zabbix host per virtual chassis instead of one per member device. See Clustering |
Proxies¶
| Setting | Type | Default | Description |
|---|---|---|---|
proxy_cf |
String or False |
False |
Name of the custom field that holds the proxy name. See Zabbix proxy |
proxy_group_cf |
String or False |
False |
Name of the custom field that holds the proxy group name |
full_proxy_sync |
Boolean | False |
Remove the proxy from Zabbix hosts that have no proxy configured in NetBox. When disabled, proxies are only added and changed |
Inventory¶
| Setting | Type | Default | Description |
|---|---|---|---|
inventory_mode |
String | "disabled" |
Zabbix inventory mode: disabled, manual or automatic. See Zabbix inventory |
inventory_sync |
Boolean | False |
Fill the Zabbix inventory from NetBox fields. Needs inventory_mode set to manual or automatic |
device_inventory_map |
Dict | See config.py.example |
Maps NetBox device fields to Zabbix inventory fields |
vm_inventory_map |
Dict | See config.py.example |
Maps NetBox VM fields to Zabbix inventory fields |
Tags¶
| Setting | Type | Default | Description |
|---|---|---|---|
tag_sync |
Boolean | False |
Sync host tags. See Tags |
tag_lower |
Boolean | True |
Convert tag names and values to lowercase |
tag_name |
String or False |
"NetBox" |
Zabbix tag name used for NetBox tags. Set to False to not sync NetBox tags |
tag_value |
String | "name" |
NetBox tag property used as the Zabbix tag value: name, slug or display |
device_tag_map |
Dict | See config.py.example |
Maps NetBox device fields to Zabbix tags |
vm_tag_map |
Dict | See config.py.example |
Maps NetBox VM fields to Zabbix tags |
Usermacros¶
| Setting | Type | Default | Description |
|---|---|---|---|
usermacro_sync |
Boolean or "full" |
False |
Sync host usermacros. "full" also updates secret macros on every run. See Usermacros |
device_usermacro_map |
Dict | See config.py.example |
Maps NetBox device fields to usermacros |
vm_usermacro_map |
Dict | See config.py.example |
Maps NetBox VM fields to usermacros |
Host description¶
| Setting | Type | Default | Description |
|---|---|---|---|
description |
String or False |
"static" |
Description of new Zabbix hosts: static, dynamic, a custom text, or False for none. See Zabbix host description |
description_dt_format |
String | "%Y-%m-%d %H:%M:%S" |
Date format of the {datetime} flag |
Logging¶
| Setting | Type | Default | Description |
|---|---|---|---|
log_file |
String, None or False |
None |
Path to the log file. None uses sync.log in the current working directory. False disables file logging. See Logging. Added in v4.1 |
log_rotation |
Boolean | True |
Rotate the log file at 5 MB and keep 3 old files. False keeps appending to one file. Added in v4.1 |
log_console |
Boolean | True |
Log to the console. Added in v4.1 |
log_handlers |
Handler, list or None |
None |
Extra Python logging.Handler objects. Only in config.py. Added in v4.1 |
Experimental¶
| Setting | Type | Default | Description |
|---|---|---|---|
render_config_context |
Boolean | False |
Render the zabbix config context as a Jinja2 template. See Experimental Features. Added in v4.1 |
Environment variables¶
Any setting can also be set with an environment variable: add the prefix NBZX_ to the setting name in capitals. For example, NBZX_HOSTGROUP_FORMAT=site/role sets hostgroup_format. Environment variables take priority over config.py.
Warning
Environment variables are always read as text, so they only work as expected for text settings.
- A boolean setting is enabled by any value, including
False,falseand0. To disable a boolean, leave the variable unset, or use the--no-command-line flag. - Lists and dictionaries, such as filters and maps, cannot be set this way. Use
config.pyinstead.
The connection details (NETBOX_HOST, ZABBIX_TOKEN and so on) are separate environment variables without the prefix. See Installation.
Logging¶
By default the script logs to the console and to sync.log in the current working directory. The log file is rotated when it reaches 5 MB, keeping 3 old files (sync.log.1 to sync.log.3).
The logging settings can be set in config.py, with NBZX_ environment variables (for example NBZX_LOG_FILE=/var/log/netbox-zabbix-sync/sync.log), or with these command-line flags:
| Flag | Description |
|---|---|
--log-file PATH |
Log to the given file |
--no-log-file |
Disable logging to a file |
--log-rotation / --no-log-rotation |
Enable or disable log rotation |
--log-console / --no-log-console |
Enable or disable console logging |
Missing parent directories of the log file are created. If the path is a directory, sync.log is created inside it. A ~ is expanded to the home directory. Disabling both file and console logging without adding custom handlers turns logging off completely.
How much is logged depends on the -v, -vv, -vvv and -q flags.
Custom handlers¶
To send logs to other destinations, such as syslog or an external service, set log_handlers in config.py to a logging.Handler or a list of handlers. They are used in addition to the console and file handlers. Handlers without a formatter use the default log format, and the verbosity flags apply to them as well.