updated README

README.md

@@ -1,18 +1,69 @@
-A script to sync the Netbox device inventory to Zabbix.
 
-## Requires pyzabbix and pynetbox.
+# Netbox to Zabbix synchronization
-From now on only compatible with Netbox 3.x.
 
-### Script settings
+A script to create, update and delete Zabbix hosts using Netbox device objects.
-#### Enviroment variables
 
-* 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 |
+|  -p | proxy-power | Force a full proxy sync (includes deleting the proxy in Zabbix if not present in config context in Netbox) |
-
-#### Logging
-Logs are generated by default to stdout and sync.log, use -v for debugging.
-
-#### Hostgroups: manual mode
 
+#### 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
+#### layout
-#### Custom fields
+The default hostgroup layout is "site/manufacturer/device_role".
-Use the following custom fields in Netbox to map the Zabbix URL:
-* Type: Integer
-* Name: zabbix_hostid
-* Required: False
-* Default: null
-* Object: dcim > device
 
-And this field for the Zabbix template
+**Variables**
 
-* Type: Text
+You can change this behaviour with the --layout flag. The following variables can be used:
-* Name: zabbix_template
+|  name | description  |
-* Required: False
+| ------------ | ------------ |
-* Default: null
+|tenant|Tenant name|
-* Object: dcim > device_type
+|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
+### Set interface parameters within Netbox
-When adding a new device, you can set the interface type with custom context.
+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