Skip to main content

Zabbix smart home integration, free and open source

Zabbix integration for Gladys Assistant

Your Zabbix hosts and problems in Gladys, and scenes when a problem starts or ends.

View on GitHubAll integrations

Bring your Zabbix monitoring into Gladys: each host becomes a device (available, active problems, highest severity, maintenance), a "Zabbix server" device counts the problems by severity, and your scenes react when a problem starts or is resolved — a red light for a disaster, a message for a failing disk. A scene can also acknowledge the problems of a host, and a dashboard widget lists the problems in progress.

The integration reads the Zabbix API on your local network, with an API token. Nothing goes through a cloud.

Tested against a real Zabbix 7.0 LTS and 6.0 LTS (official Docker images, agent 2 and trapper items); Zabbix 5.4 and 6.4 only through their documented API differences. Feedback welcome: github.com/guim31/gladys-zabbix/issues.

What you need​

  • Gladys Assistant 5.1.0 or later.
  • Zabbix 5.4 or later (API tokens), 6.0 LTS and 7.0 LTS included, reachable from the Gladys machine (the address of its web frontend).
  • A Zabbix user for Gladys. A read-only role on the host groups to follow is enough; add the right to acknowledge problems for the scene action.

Getting started​

1. Create an API token​

In Zabbix, open Users → API tokens (6.4 and later; Administration → General → API tokens from 5.4 to 6.2), click Create API token, choose the user, untick "Set expiration date" or choose a far date, and copy the token: Zabbix shows it only once.

2. Configure the integration​

In Gladys, open the configuration of the integration:

  • Zabbix address: the address you open the Zabbix frontend with, e.g. http://192.168.1.2/zabbix or https://zabbix.example.com. The URL of a frontend page copied from the browser works too.
  • API token: the token of step 1.
  • Host groups (optional): names separated by commas, exactly as in Zabbix (case included). Empty: every monitored host the token can see.
  • Item keys (optional): up to 5 numeric item keys, e.g. system.cpu.util, vm.memory.utilization, vfs.fs.size[/,pused]. Each host that has one of these items gets a feature with its last value.
  • Refresh interval: 15 seconds to 5 minutes (30 seconds by default).
  • Allow acknowledging from scenes: untick to turn the acknowledgement action off.
  • Accept self-signed certificates: for an https:// address whose certificate your browser does not trust either.
  • Language of the names: language of the feature names and of the scene results.

Save, then click Test the connection: it shows the Zabbix version, the number of hosts and of active problems.

3. Add the devices​

Open the Discover tab of the integration and add the hosts to follow, and the "Zabbix server" device if you want the counts by severity. The scene triggers work for every host, added to Gladys or not.

The devices​

Each host (monitored hosts only; disabled ones are left out):

FeatureValue
Available1 available, 0 unavailable (an interface, or the active agent on 7.0+)
Active problemsnumber of active problems (suppressed ones left out)
Highest severity0 Not classified, 1 Information, 2 Warning, 3 Average, 4 High, 5 Disaster, -1 no problem
In maintenance1 while the host is in a Zabbix maintenance
Itemsone feature per configured item key found on the host, named after it

"Available" stays empty for a host without interface (trapper items only), whose availability Zabbix does not know.

The Zabbix server device:

  • Active problems
  • Not classified problems
  • Information problems
  • Warning problems
  • Average problems
  • High problems
  • Disaster problems

Values are sent to Gladys only when they change, and every 6 hours otherwise.

Dashboard​

The Zabbix problems widget shows three tiles — the active problems, the ones not acknowledged yet, the hosts unavailable — and the problems, the most severe first: the problem, its host (✓ once acknowledged), and an icon and colour for its severity. Ten rows at most. Refresh reads Zabbix again. In its settings, choose hosts to show only theirs (empty: every host).

Scenes​

Triggers​

  • A problem starts: a new problem on a host. Filters: hosts (empty: any), severities (empty: any; for "High or above", choose High and Disaster). Variables: host name, problem, severity, severity level (0 to 5), Zabbix event id.
  • A problem is resolved: a problem is resolved or closed, with the same filters and variables, plus its duration in minutes.
  • Zabbix no longer answers: the API fails to answer twice in a row (variables: Zabbix address, error).

The problems already there when the integration starts are not announced. A problem that starts or ends while Gladys or the integration restarts is announced once at the next read. Problems suppressed by a maintenance are left out, as in the Zabbix dashboards: neither counted nor announced while suppressed, and not taken for resolved; one that started during the maintenance is announced when it ends.

Actions​

  • Acknowledge the problems of a host: acknowledges the active problems of the host in Zabbix, with a message in their history (empty: "Acknowledged from Gladys"). Returns the number acknowledged. Turn it off with "Allow acknowledging from scenes".
  • Read the problems: counts and lists the active problems of one host, or of all, for the next actions: number, not acknowledged, highest severity (in words and as a level), and the list "host: problem".

Scene ideas​

  • A red light for serious problems: trigger "A problem starts", severities High and Disaster → turn the living-room lamp red and send {{triggerEvent.data.host}}: {{triggerEvent.data.problem}}.
  • Back to normal: trigger "A problem is resolved", same filters → message "Resolved after {{triggerEvent.data.duration_minutes}} min".
  • Morning report: every day at 8:00, "Read the problems" → send the count and the list when the count is above 0.
  • Seen from the couch: a dashboard button or a Zigbee remote runs "Acknowledge the problems of a host" on the NAS.

Troubleshooting​

  • "API token refused or expired": check the token in Users → API tokens (enabled, not expired), and that its user is enabled.
  • "Zabbix does not answer": check the address from the Gladys machine. localhost is the integration container itself: use the IP address of the Zabbix machine.
  • "No Zabbix API at this address": the address does not lead to the frontend; api_jsonrpc.php must be next to its pages.
  • "Certificate refused": tick "Accept self-signed certificates", or use the http:// address on the local network.
  • "No host group with these names": the names must match Zabbix exactly. The report of "Test the connection" lists the unknown ones.
  • A host is missing: it is disabled, outside the host groups, or the user of the token has no read permission on it.
  • The acknowledgement is refused: the role of the user needs "Acknowledge problems", and write or read permission on the host group.

Limits​

  • One Zabbix server per integration.
  • Problems of triggers only (no internal events, no services). Suppressed problems are left out.
  • "A problem is resolved" also fires when a problem leaves the scope: a host removed from the host groups, a trigger disabled.
  • At most 30 problem events per read: a network outage can raise dozens at once; the rest follows at the next reads.
  • Item features hold numbers only; a percentage shows as a level from 0 to 100, other units without unit.
  • No quota on the Zabbix API: each read sends two to six requests.

Not affiliated with Zabbix SIA. Zabbix is a trademark of Zabbix SIA.

Configuration settings​

These are the settings Zabbix asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Your Zabbix serversectionNoIn Zabbix (5.4+), open Users → API tokens (Administration → General before 6.4), create a token and paste it below with the address of Zabbix. Then add the hosts to follow from the Discover tab: the scene triggers work for every host, added or not.
Zabbix addressstringYesThe address you open the Zabbix frontend with; the API is found next to it.
API tokensecretYesA read-only user is enough, plus the right to acknowledge problems for the scene action.
Host groups (optional)stringNoNames separated by commas. Empty: every monitored host the token can see.
Item keys (optional)stringNoUp to 5 numeric item keys, separated by commas, added to each host that has them.
OptionssectionNo
Refresh intervalselectNoHow often Zabbix is read: a handful of API requests each time.
Allow acknowledging from scenesbooleanNoUntick to turn off the "Acknowledge the problems of a host" scene action.
Accept self-signed certificatesbooleanNoOnly for an https:// address whose certificate your browser does not trust either.
Language of the namesselectNoLanguage of the feature names (set when a device is added) and of the scene results.

How to install Zabbix in Gladys​

  1. In Gladys, open Integrations: Zabbix appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/guim31/gladys-zabbix:1.0.0), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/guim31/gladys-zabbix.

Zabbix requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

Zabbix is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by guim31, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on