diff --git a/README.md b/README.md index b53dbc1..11ac8ca 100644 --- a/README.md +++ b/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: @@ -128,14 +216,4 @@ 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 +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. \ No newline at end of file