Fixed container path

Fixed Docker package link

.github/workflows/publish-image.yml

@@ -0,0 +1,46 @@
+name: Publish Docker image to GHCR on a new version
+
+on:
+  push:
+    branches:
+      - main
+      - dockertest
+#    tags: 
+#      - [0-9]+.*
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  test_quality:
+    uses: ./.github/workflows/quality.yml 
+  build_and_publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v4
+      - name: Log in to the container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GHCR_PAT }}
+      - name: Extract metadata (tags, labels)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=semver,pattern={{ version }}
+            type=ref,event=branch
+            type=raw,value=latest,enable=${{ github.ref == format('refs/heads/{0}', 'master') }}
+            type=sha
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+

.github/workflows/quality.yml

@@ -0,0 +1,26 @@
+---
+name: Pylint Quality control
+
+on: 
+  workflow_call
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11","3.12"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pylint
+        pip install -r requirements.txt
+    - name: Analysing the code with pylint
+      run: |
+        pylint --module-naming-style=any $(git ls-files '*.py')

Dockerfile

@@ -0,0 +1,9 @@
+# syntax=docker/dockerfile:1
+FROM python:3.12-alpine
+RUN mkdir -p /opt/netbox-zabbix
+COPY . /opt/netbox-zabbix
+WORKDIR /opt/netbox-zabbix
+RUN if ! [ -f ./config.py ]; then cp ./config.py.example ./config.py; fi
+RUN pip install -r ./requirements.txt
+ENTRYPOINT ["python"]
+CMD ["/opt/netbox-zabbix/netbox_zabbix_sync.py", "-v"]

README.md

@@ -4,27 +4,54 @@
 A script to create, update and delete Zabbix hosts using Netbox device objects.
 
 
-## Installation
+## Installation via Docker
-### Packages
+
-Make sure that you have a python environment with the following packages installed.
+To pull the latest stable version to your local cache, use the following docker pull command:
 ```
-pynetbox
+docker pull ghcr.io/thenetworkguy/netbox-zabbix-sync:main
-pyzabbix
 ```
 
+Make sure to specify the needed environment variables for the script to work (see [here](#set-environment-variables))
+on the command line or use an [env file](https://docs.docker.com/reference/cli/docker/container/run/#env).
+
+```
+docker run -d -t -i -e ZABBIX_HOST='https://zabbix.local' \ 
+-e ZABBIX_TOKEN='othersecrettoken' \
+-e NETBOX_HOST='https://netbox.local' \
+-e NETBOX_TOKEN='secrettoken' \
+--name netbox-zabbix-sync ghcr.io/TheNetworkGuy/netbox-zabbix-sync:latest
+```
+
+This should run a one-time sync, you can check the sync with `docker logs netbox-zabbix-sync`.
+
+The image uses the default `config.py` for it's configuration, you can use a volume mount in the docker run command 
+to override with your own config file if needed (see [config file](#config-file)):
+```
+docker run -d -t -i -v $(pwd)/config.py:/opt/netbox-zabbix/config.py ... 
+```  
+
+## Installation from Source
+
 ### Cloning the repository
 ```
 git clone https://github.com/TheNetworkGuy/netbox-zabbix-sync.git
 ```
 
+### Packages
+Make sure that you have a python environment with the following packages installed. You can also use the `requirements.txt` file for installation with pip.
+```
+pynetbox
+pyzabbix
+```
+
 ### Config file
-First time user? Copy the config.py.example file to config.py. This file is used for modifying filters and setting variables such as custom field names.
+First time user? Copy the `config.py.example` file to `config.py`. This file is used for modifying filters and setting variables such as custom field names.
 ```
 cp config.py.example config.py
 ```
 
 ### Set environment variables
-Set the following environment variables
+Set the following environment variables:
 ```
 ZABBIX_HOST="https://zabbix.local"
 ZABBIX_USER="username"
@@ -32,6 +59,14 @@ ZABBIX_PASS="Password"
 NETBOX_HOST="https://netbox.local"
 NETBOX_TOKEN="secrettoken"
 ```
+
+Or, you can use a Zabbix API token to login instead of using a username and password.
+In that case `ZABBIX_USER` and `ZABBIX_PASS` will be ignored.
+
+```
+ZABBIX_TOKEN=othersecrettoken
+```
+
 ### Netbox custom fields
 Use the following custom fields in Netbox (if you are using config context for the template information then the zabbix_template field is not required):
 ```
@@ -48,10 +83,111 @@ Use the following custom fields in Netbox (if you are using config context for t
 * Default: null
 * Object: dcim > device_type
 ```
-You can make the hostID field hidden or read-only to prevent human intervention.
+You can make the `zabbix_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.
 
+## Config file
+
+### Hostgroup
+Setting the `create_hostgroups` variable to `False` requires manual hostgroup creation for devices in a new category.
+
+The format can be set with the `hostgroup_format` variable.
+
+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.
+
+#### Layout
+The default hostgroup layout is "site/manufacturer/device_role".
+
+**Variables**
+
+You can change this behaviour with the hostgroup_format variable. The following values can be used:
+|  name | description  |
+| ------------ | ------------ |
+|dev_location|The device location name|
+|dev_role|The device role name|
+|manufacturer|Manufacturer name|
+|region|The region name of the device|
+|site|Site name|
+|site_group|Site group name|
+|tenant|Tenant name|
+|tenant_group|Tenant group name|
+
+
+You can specify the value like so, sperated by a "/":
+```
+hostgroup_format = "tenant/site/dev_location/dev_role"
+```
+**Group traversal**
+
+The default behaviour for `region` is to only use the directly assigned region in the rendered hostgroup name.
+However, by setting `traverse_region` to `True` in `config.py` the script will render a full region path of all parent regions for the hostgroup name.
+`traverse_site_groups` controls the same behaviour for site_groups.
+
+**Custom fields**
+
+You can also use the value of custom fields under the device object.
+
+This allows more freedom and even allows a full static mapping instead of a dynamic rendered hostgroup name.
+```
+hostgroup_format = "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
+```
+hostgroup_format = "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:
+```
+hostgroup_format = "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 single variable, then this will result in an error:
+```
+hostgroup_format = "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")
+* Create the host in Zabbix with an enabled status (For now only enabled with the "Active" status)
+
+You can modify this behaviour by changing the following list variables in the script:
+ - `zabbix_device_removal`
+ - `zabbix_device_disable`
+
+### Zabbix Inventory
+This script allows you to enable the inventory on managed Zabbix hosts and sync NetBox device properties to the specified inventory fields.
+To enable, set `inventory_sync` to `True`.
+Set `inventory_automatic` to `False` to use manual inventory, or `True` for automatic.
+See [Zabix Manual](https://www.zabbix.com/documentation/current/en/manual/config/hosts/inventory#building-inventory) for more information about the modes.
+
+Use the `inventory_map` variable to map which NetBox properties are used in which Zabbix Inventory fields.
+For nested properties, you can use the '/' seperator.
+For example, the following map will assign the custom field 'mycustomfield' to the 'alias' Zabbix inventory field:
+```
+inventory_sync = True
+inventory_automatic = True
+inventory_map = { "custom_fields/mycustomfield/name": "alias"}
+```
+See `config.py.example` for an extensive example map.
+Any Zabix Inventory fields that are not included in the map will not be touched by the script, 
+so you can safely add manual values or use items to automatically add values to other fields.
+
 ### Template source
 You can either use a Netbox device type custom field or Netbox config context for the Zabbix template information.
 
@@ -106,83 +242,9 @@ 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. |
-|  -H | hostgroup | Create non-existing hostgroups in Zabbix. Usefull for a first run to add all required hostgroups. |
-|  -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 (includes deleting the proxy in Zabbix if not present in config context in Netbox) |
 
-#### Hostgroup
+## Config context
-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:
-{Site name}/{Manufacturer name}/{Device role name}
-
-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.
-
-#### layout
-The default hostgroup layout is "site/manufacturer/device_role".
-
-**Variables**
-
-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|
-
-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")
-* Create the host in Zabbix with an enabled status (For now only enabled with the "Active" status)
-
-You can modify this behaviour by changing the following list variables in the script:
- - zabbix_device_removal
- - zabbix_device_disable
 
 ### Zabbix proxy
 You can set the proxy for a device using the 'proxy' key in config context.
@@ -193,7 +255,7 @@ 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.
+Because of the possible 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, set the `full_proxy_sync` variable in the config file.
 
 ### 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:
@@ -256,4 +318,7 @@ 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.
+
+I would recommend using macros for sensitive data such as community strings since the data in Netbox is plain-text.
+
+> **_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.

config.py.example

@@ -1,7 +1,8 @@
-# Template logic.
+## Template logic.
 # Set to true to enable the template source information
 # coming from config context instead of a custom field.
 templates_config_context = False
+
 # Set to true to give config context templates a 
 # higher priority then custom field templates
 templates_config_context_overrule = False
@@ -11,18 +12,76 @@ templates_config_context_overrule = False
 template_cf = "zabbix_template"
 device_cf = "zabbix_hostid"
 
-# Netbox to Zabbix device state convertion
+## Enable clustering of devices with virtual chassis setup
+clustering = False
+
+## Enable hostgroup generation. Requires permissions in Zabbix
+create_hostgroups = True
+
+## Create journal entries
+create_journal = False
+
+## Proxy Sync
+# Set to true to enable removal of proxy's under hosts. Use with caution and make sure that you specified
+# all the required proxy's in the device config context before enabeling this option.
+# With this option disabled proxy's will only be added and modified for Zabbix hosts.
+full_proxy_sync = False
+
+## Netbox to Zabbix device state convertion
 zabbix_device_removal = ["Decommissioning", "Inventory"]
 zabbix_device_disable = ["Offline", "Planned", "Staged", "Failed"]
 
-# Custom filter for device filtering. Variable must be present but can be left empty with no filtering.
+## Hostgroup mapping
-# A couple of examples are as follows:
+# Available choices: dev_location, dev_role, manufacturer, region, site, site_group, tenant, tenant_group
+# You can also use CF (custom field) names under the device. The CF content will be used for the hostgroup generation.
+#
+# When using region in the group name, the default behaviour is to use name of the directly assigned region.
+# By setting traverse_regions to True the full path of all parent regions will be used in the hostgroup, e.g.:
+#
+# 'Global/Europe/Netherlands/Amsterdam' instead of just 'Amsterdam'.
+#
+# traverse_site_groups controls the same behaviour for any assigned site_groups.   
+hostgroup_format = "site/manufacturer/dev_role"
+traverse_regions = False
+traverse_site_groups = False
 
-# nb_device_filter = {} #No filter
+## Filtering
-# nb_device_filter = {"tag": "zabbix"} #Use a tag
+# Custom device filter, variable must be present but can be left empty with no filtering.
-# nb_device_filter = {"site": "HQ-AMS"} #Use a site name
+# A couple of examples:
-# nb_device_filter = {"site": ["HQ-AMS", "HQ-FRA"]} #Device must be in either one of these sites
+#  nb_device_filter = {} #No filter
-# nb_device_filter = {"site": "HQ-AMS", "tag": "zabbix", "role__n": ["PDU", "console-server"]} #Device must be in site HQ-AMS, have the tag zabbix and must not be part of the PDU or console-server role
+#  nb_device_filter = {"tag": "zabbix"} #Use a tag
+#  nb_device_filter = {"site": "HQ-AMS"} #Use a site name
+#  nb_device_filter = {"site": ["HQ-AMS", "HQ-FRA"]} #Device must be in either one of these sites
+#  nb_device_filter = {"site": "HQ-AMS", "tag": "zabbix", "role__n": ["PDU", "console-server"]} #Device must be in site HQ-AMS, have the tag zabbix and must not be part of the PDU or console-server role
 
-# Default device filter, only get devices which have a name in Netbox.
+# Default device filter, only get devices which have a name in Netbox:
-nb_device_filter = {"name__n": "null"}
+nb_device_filter = {"name__n": "null"}
+
+## Inventory
+# To allow syncing of NetBox device properties, set inventory_sync to True
+inventory_sync = False
+
+# Set inventory_automatic to False to use manual inventory, True for automatic
+# See https://www.zabbix.com/documentation/current/en/manual/config/hosts/inventory#building-inventory 
+inventory_automatic = True
+
+# inventory_map is used to map NetBox properties to Zabbix Inventory fields.
+# For nested properties, you can use the '/' seperator.
+# For example, the following map will assign the custom field 'mycustomfield' to the 'alias' Zabbix inventory field:
+#
+# inventory_map = { "custom_fields/mycustomfield/name": "alias"}
+#
+# The following map should provide some nice defaults:
+inventory_map = { "asset_tag": "asset_tag",
+                  "virtual_chassis/name": "chassis",
+                  "status/label": "deployment_status",
+                  "location/name": "location",
+                  "latitude": "location_lat",
+                  "longitude": "location_lon",
+                  "comments": "notes",
+                  "name": "name",
+                  "rack/name": "site_rack",
+                  "serial": "serialno_a",
+                  "device_type/model": "type",
+                  "device_type/manufacturer/name": "vendor",
+                  "oob_ip/address": "oob_ip" }