mirror of
https://github.com/TheNetworkGuy/netbox-zabbix-sync.git
synced 2025-07-14 01:41:25 -06:00
updated README
This commit is contained in:
TheNetworkGuy
parent
988cf10c9a
commit
093e861de9
168
README.md
168
README.md
@ -1,18 +1,69 @@
|
||||
A script to sync the Netbox device inventory to Zabbix.
|
||||
|
||||
## Requires pyzabbix and pynetbox.
|
||||
From now on only compatible with Netbox 3.x.
|
||||
# Netbox to Zabbix synchronization
|
||||
|
||||
### Script settings
|
||||
#### Enviroment variables
|
||||
A script to create, update and delete Zabbix hosts using Netbox device objects.
|
||||
|
||||
* ZABBIX_HOST="https://zabbix.local"
|
||||
* ZABBIX_USER="username"
|
||||
* ZABBIX_PASS="Password"
|
||||
* NETBOX_HOST="https://netbox.local"
|
||||
* NETBOX_TOKEN="secrettoken"
|
||||
|
||||
#### Flags
|
||||
## Installation
|
||||
### Packages
|
||||
Make sure that you have a python environment with the following packages installed.
|
||||
```
|
||||
pynetbox
|
||||
pyzabbix
|
||||
```
|
||||
### Cloning the repository
|
||||
```
|
||||
git clone https://github.com/TheNetworkGuy/netbox-zabbix-sync.git
|
||||
```
|
||||
### Set environment variables
|
||||
Set the following environment variables
|
||||
```
|
||||
ZABBIX_HOST="https://zabbix.local"
|
||||
ZABBIX_USER="username"
|
||||
ZABBIX_PASS="Password"
|
||||
NETBOX_HOST="https://netbox.local"
|
||||
NETBOX_TOKEN="secrettoken"
|
||||
```
|
||||
### Netbox custom fields
|
||||
Use the following custom fields in Netbox:
|
||||
```
|
||||
* Type: Integer
|
||||
* Name: zabbix_hostid
|
||||
* Required: False
|
||||
* Default: null
|
||||
* Object: dcim > device
|
||||
```
|
||||
```
|
||||
* Type: Text
|
||||
* Name: zabbix_template
|
||||
* Required: False
|
||||
* Default: null
|
||||
* Object: dcim > device_type
|
||||
```
|
||||
You can make the hostID field hidden or read-only to prevent human intervention.
|
||||
|
||||
This is optional and there is a use case for leaving it read-write in the UI to manually change the ID. For example to re-run a sync.
|
||||
|
||||
### Netbox permissions
|
||||
Make sure that the Netbox user has proper permissions for device read and modify (modify to set the Zabbix HostID custom field) operations.
|
||||
|
||||
### Zabbix permissions
|
||||
Make sure that the Zabbix user has permissions to read hostgroups and proxy servers. The user should have full rights on creating, modifying and deleting hosts.
|
||||
|
||||
If you want to automatically create hostgroups then the create permission on host-groups should also be applied.
|
||||
|
||||
### Custom links
|
||||
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: http://myzabbixserver.local/zabbix.php?action=latest.view&hostids[]={{ obj.cf["zabbix_hostid"] }}
|
||||
```
|
||||
## Running the script
|
||||
```
|
||||
python3 netbox_zabbix_sync.py
|
||||
```
|
||||
### Flags
|
||||
| Flag | Option | Description |
|
||||
| ------------ | ------------ | ------------ |
|
||||
| -c | cluster | For clustered devices: only add the primary node of a cluster and use the cluster name as hostname. |
|
||||
@ -20,13 +71,9 @@ From now on only compatible with Netbox 3.x.
|
||||
| -l | layout | Set the hostgroup layout. Default is site/manufacturer/dev_role. Posible options (seperated with '/'): site, manufacturer, dev_role, tenant |
|
||||
| -v | verbose | Log with debugging on. |
|
||||
| -j | journal | Create journal entries in Netbox when a host gets added, modified or deleted in Zabbix |
|
||||
| -p | proxy-power | Force a full proxy sync. USE WITH CAUTION, see "Set proxy within Netbox" for more information |
|
||||
|
||||
#### Logging
|
||||
Logs are generated by default to stdout and sync.log, use -v for debugging.
|
||||
|
||||
#### Hostgroups: manual mode
|
||||
| -p | proxy-power | Force a full proxy sync (includes deleting the proxy in Zabbix if not present in config context in Netbox) |
|
||||
|
||||
#### Hostgroup
|
||||
In case of omitting the -H flag, manual hostgroup creation is required for devices in a new category.
|
||||
|
||||
The format can be set with the -l flag. If not provided the default format will be:
|
||||
@ -35,24 +82,59 @@ The format can be set with the -l flag. If not provided the default format will
|
||||
Make sure that the Zabbix user has proper permissions to create hosts.
|
||||
The hostgroups are in a nested format. This means that proper permissions only need to be applied to the site name hostgroup and cascaded to any child hostgroups.
|
||||
|
||||
### Netbox settings
|
||||
#### Custom fields
|
||||
Use the following custom fields in Netbox to map the Zabbix URL:
|
||||
* Type: Integer
|
||||
* Name: zabbix_hostid
|
||||
* Required: False
|
||||
* Default: null
|
||||
* Object: dcim > device
|
||||
#### layout
|
||||
The default hostgroup layout is "site/manufacturer/device_role".
|
||||
|
||||
And this field for the Zabbix template
|
||||
**Variables**
|
||||
|
||||
* Type: Text
|
||||
* Name: zabbix_template
|
||||
* Required: False
|
||||
* Default: null
|
||||
* Object: dcim > device_type
|
||||
You can change this behaviour with the --layout flag. The following variables can be used:
|
||||
| name | description |
|
||||
| ------------ | ------------ |
|
||||
|tenant|Tenant name|
|
||||
|site|Site name|
|
||||
|manufacturer|Manufacturer name|
|
||||
|device_role|The device role name|
|
||||
|
||||
#### Netbox device status
|
||||
You can specify the variables like so, sperated by a "/":
|
||||
```
|
||||
python3 netbox_zabbix_sync.py -l tenant/site/device_role
|
||||
```
|
||||
**custom fields**
|
||||
|
||||
You can also use the value of custom fields under the device object.
|
||||
|
||||
This allows more freedom and even allows a ful static mapping instead of a dynamic rendered hostgroup name.
|
||||
```
|
||||
python3 netbox_zabbix_sync.py -l site/mycustomfieldname
|
||||
```
|
||||
**Empty variables or hostgroups**
|
||||
|
||||
Should the content of a variable be empty, then the hostgroup position is skipped.
|
||||
|
||||
For example, consider the following scenario with 2 devices, both the same device type and site. One of them is linked to a tenant, the other one does not have a relationship with a tenant.
|
||||
- Device_role: PDU
|
||||
- Site: HQ-AMS
|
||||
```
|
||||
python3 netbox_zabbix_sync.py -l site/tenant/device_role
|
||||
```
|
||||
When running the script like above, the following hostgroup (HG) will be generated for both hosts:
|
||||
- Device A with no relationship with a tenant: HQ-AMS/PDU
|
||||
- Device B with a relationship to tenant "Fork Industries": HQ-AMS/Fork Industries/PDU
|
||||
|
||||
The same logic applies to custom fields being used in the HG format:
|
||||
```
|
||||
python3 netbox_zabbix_sync.py -l site/mycustomfieldname
|
||||
```
|
||||
For device A with the value "ABC123" in the custom field "mycustomfieldname" -> HQ-AMS/ABC123
|
||||
For a device which does not have a value in the custom field "mycustomfieldname" -> HQ-AMS
|
||||
|
||||
Should there be a scenario where a custom field does not have a value under a device, and the HG format only uses this signle variable, then this will result in an error:
|
||||
```
|
||||
python3 netbox_zabbix_sync.py -l mycustomfieldname
|
||||
|
||||
Netbox-Zabbix-sync - ERROR - ESXI1 has no reliable hostgroup. This is most likely due to the use of custom fields that are empty.
|
||||
```
|
||||
### Device status
|
||||
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:
|
||||
* Delete the host from Zabbix (triggered by Netbox status "Decommissioning" and "Inventory")
|
||||
* Create the host in Zabbix but with a disabled status (Trigger by "Offline", "Planned", "Staged" and "Failed")
|
||||
@ -62,7 +144,7 @@ You can modify this behaviour by changing the following list variables in the sc
|
||||
- zabbix_device_removal
|
||||
- zabbix_device_disable
|
||||
|
||||
#### Set proxy within Netbox
|
||||
### Zabbix proxy
|
||||
You can set the proxy for a device using the 'proxy' key in config context.
|
||||
```json
|
||||
{
|
||||
@ -73,8 +155,14 @@ You can set the proxy for a device using the 'proxy' key in config context.
|
||||
```
|
||||
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.
|
||||
|
||||
#### Set interface parameters within Netbox
|
||||
When adding a new device, you can set the interface type with custom context.
|
||||
### Set interface parameters within Netbox
|
||||
When adding a new device, you can set the interface type with custom context. By default, the following configuration is applied when no config context is provided:
|
||||
|
||||
* SNMPv2
|
||||
* UDP 161
|
||||
* Bulk requests enabled
|
||||
* SNMP community: {$SNMP_COMMUNITY}
|
||||
|
||||
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:
|
||||
@ -129,13 +217,3 @@ To configure the interface parameters you'll need to use custom context. Custom
|
||||
}
|
||||
```
|
||||
Note: Not all SNMP data is required for a working configuration. [The following parameters are allowed ](https://www.zabbix.com/documentation/current/manual/api/reference/hostinterface/object#details_tag "The following parameters are allowed ")but are not all required, depending on your environment.
|
||||
|
||||
#### Permissions
|
||||
Make sure that the user has proper permissions for device read and modify (modify to set the Zabbix HostID custom field) operations.
|
||||
|
||||
#### Custom links
|
||||
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user