SOP Managing Zabbix macros / variables

Overview

This SOP documents the information and steps to manage Zabbix macros, both from the UI and from Ansible.

Contact Information

Owner

Fedora Infrastructure Team

Contact

#fedora-admin, sysadmin-main, sysadmin-noc

Purpose

Ensure monitoring config is stored in configuration management for later (re)use.

Overview

Zabbix can reference variables (it calls them macros) when determining if a trigger needs to be fired, or what device/file/port/etc needs to be checked for an item. See Zabbix Macro Docs [1] for for details.

Macros are defined either at the template level (most common), or at the host level (usually as an override to a template macro, but sometimes standalone). This is similar to group_vars and host_vars in Ansible, in that a host inherits the template defaults for a macro if a host macro is not defined.

This page details how to set them, both in the UI and via Ansible.

Setting a macro in the UI

  1. Open the Configuration page for the host you wish to update.

    • There are many paths to this, generally clicking the host name in any UI pane will do (e.g from the frontpage dashboard).

  2. Click the Macros tab.

  3. If overriding a template macro (likely), click the "Inherited and host macros" button.

    1. Search for the macro name to override (there is no search field, use your browser’s page search).

    2. Click "Change" and edit the value.

  4. If editing an existing override, look under "Host macros" and edit it.

  5. If creating a new host-level macro, click "Add" under "Host macros", name it, add the value.

  6. Save the host changes.

This is good for testing changes, however it is not guaranteed to be permanent. Ansible does not run any kind of "state:absent" on unmanaged macros, so new entries will likely persist - but to be sure, add them them to Ansible as detailed below.

Setting a macro in Ansible

Macros can be set at the group_vars or host_vars level - in Zabbix it will always be at the host level. Decide whether you want to set:

  • a group-level override (e.g. SMTP hosts can have a higher number of stuck mails), or

  • a host-level override (e.g. a host has a slow disk and needs a higher read/write threshold)

Then follow these steps:

  1. Open the inventory/group_vars or inventory/host_vars file (as appropriate)

  2. Find (or add) the zabbix_macros dict

  3. Add a key of the macro name (without the {$ …​ } parts, just the name), and the value

    • e.g. 'SWAP.PFREE.MIN.WARN': 0 would set the allowed free swap before alerting to 0

  4. Save and git-commit the change as usual

If the item is part of low-level discovery (LLD), for example a disk or ethernet device, then you’ll need to specify the target item, otherwise your macro will apply to all the discovered entries for this host:

  • Put the discovered name in double-quotes, and single-quote the whole key:

    • e.g. 'VFS.FS.PUSED.MAX.WARN:"/srv/nfs/copr-be"': 95 would set a 95% full warning level for the volume on /srv/nfs/copr-be, but not touch any other mountpounts

To roll out the change (if needed, you may have tested the entry in the UI already), run any playbook for the host(s) with -t zabbix_api as the required task is in the base role.

Resources

Want to help? Learn how to contribute to Fedora Docs ›