zabbix-templates/docs/conventions.md

Conventions

Directory Layout

templates/<category>/<product>/
├── README.md
├── CHANGELOG.md
├── manifest.yaml
├── <zabbix-version>/
│   └── template_....yaml
└── assets/                 # optional

• One directory is one import unit (a package).
• Place linked and dependent templates in the same package and version directory.
• Use a third level such as network/cisco/ios/ only when vendor grouping is necessary.

Categories

Category	Purpose	Example class tag
app	Applications	application
db	Databases	database
network	Network devices	network
os	Operating systems	os
hardware	Server hardware	hardware
san	SAN and storage arrays	storage
cloud	Cloud services	cloud
container	Containers and orchestration	container
web	Web servers and web monitoring	web
virtualization	Virtualization platforms	virtualization
power	UPS and PDU devices	power
printer	Printers	printer
custom	Custom monitoring that fits no other category	custom

Naming

• Template technical name: <Vendor/Product> by <Method>
  • Examples: Dell PowerVault ME by SNMP, Huawei OceanStor Dorado by SNMP
  • Follow the naming used by official Zabbix templates. Do not add a Template prefix.
• Directory: lowercase snake_case, without the template_ prefix.
  • Examples: templates/app/apache/, templates/network/cisco_ios/
• Export file: keep the default filename produced by Zabbix.
  • Example: template_app_apache.yaml
• Git tag: <id>-v<semver>, replacing / with -.
  • Example: app-apache-v1.2.0

manifest.yaml

manifest.yaml is the single source of metadata for a package. The top-level template list and distribution zips are generated from it.

Field	Required	Description
id	Yes	category/product. Must match the directory path.
name	Yes	Template technical name. Must match the name in the export.
description	Yes	One-line description shown in the template list.
version	Yes	SemVer (for example, 1.0.0).
category	Yes	One of the categories above.
vendor	No	Vendor name.
method	No	agent, agent2, snmp, http, ipmi, jmx, ssh, telnet, odbc, external, script, calculated, dependent, or other
zabbix.min	Yes	Minimum supported Zabbix version (for example, "7.0").
zabbix.max	No	Maximum supported Zabbix version, or null when unbounded.
zabbix.tested	No	List of tested Zabbix versions.
depends_on	No	IDs of other packages this package depends on.
source	No	original or the upstream URL for derived templates.
maintainer	Yes	Maintainer name.

Example:

id: app/apache
name: Apache by HTTP
description: Monitors Apache availability and performance.
version: 1.0.0
category: app
vendor: Apache
method: http

zabbix:
  min: "7.0"
  max: null
  tested: ["7.0", "8.0"]

depends_on: []
source: original
maintainer: okumura

Version Directories

• Directory names use Zabbix major.minor versions (for example, 7.0 and 8.0).
• Start with the directory for the minimum supported version only.
• Add a newer version directory only when the template uses features specific to that version or the exported content differs.
• If the same export also works on a newer version, keep one directory and add the newer version to zabbix.tested in manifest.yaml.

See versioning.md for details.

Export Procedure

1. Prepare a dedicated Zabbix server for template development. A clean server with no hosts is preferred.
2. Select the templates and export them in YAML format.
3. Include linked templates so that a single import is sufficient.
4. Verify that hosts, local IDs, and secrets are not included.
5. Place the export under templates/<category>/<product>/<version>/.
6. scripts/export.sh can export templates directly through the API.

Tags

Follow the tags used by official Zabbix templates and add at least the following.

Tag	Example values	Description
class	application, database, network, os	High-level category
target	apache, postgresql, cisco_ios	Monitored target

Document the meaning of any additional tags in the package README.md.

Macros

• User macros use uppercase {$SECTION.NAME} names.
  • Examples: {$APACHE.PORT}, {$APACHE.TIMEOUT}
• Do not hardcode thresholds. Expose them as macros with defaults.
• LLD macros use the {#SECTION.NAME} format.
• Store passwords and API tokens in secret user macros and never commit their real values.

Items and Triggers

• Item names use the Component [{#MACRO}]: Metric form. Do not add the template name prefix.
• Trigger names use the <Vendor/Product>: <Component>: <Symptom> form. Include {HOST.NAME} for host-level events.
• Prefix item and trigger descriptions with MIB: <MIB name> and a short explanation, following the official Zabbix templates.
• For SNMP discovery, prefer a master SNMP walk item with dependent LLD rules and SNMP_WALK_TO_JSON / SNMP_WALK_VALUE preprocessing.
• Use user macros for discovery filters, for example {$DELL.POWERVAULT.ME.DISCOVERY.PORT.TYPE.NOT_MATCHES}.
• Use DISCARD_UNCHANGED_HEARTBEAT 6h for static or health items and 1h for discovery rules.
• Use vendor-prefixed macro names, for example {$DELL.POWERVAULT.ME.UPTIME.WARN}.
• Expose thresholds as macros and document their defaults and meanings in README.md.
• Always define recovery conditions.
• When dependencies become complex, prefer tags and event correlation over trigger dependencies.
• Filter unnecessary entities in LLD rules to avoid excessive item counts.

README

Each package README.md must cover the following.

1. Overview and what is monitored
2. Supported and tested Zabbix versions
3. Requirements such as agents, SNMP, external scripts, and open ports
4. Import procedure
5. Macro reference
6. Item, LLD, and trigger overview
7. Known limitations and troubleshooting
8. Link to the changelog

The scaffold is available at template-README.md.

Security

• Never commit SNMP communities, API tokens, passwords, or private keys.
• Before exporting, check for host-specific values and internal IP addresses.
• For external scripts, review execution permissions and input handling.

Source and Licensing

• When a template is derived from an official or community template, record the upstream URL in manifest.yaml under source.
• Follow the original license and add its full text to LICENSES/ or NOTICE when required.
• This repository does not have a repository-wide license yet. Decide on one before publishing.