Zabbix Integration

Zabbix

Zabbix sees a disk filling up on a server. An incident appears on the service desk board, linked to that server in the CMDB, at the priority you chose for that severity. When Zabbix says the problem has cleared, the ticket is resolved. Nobody had to watch the monitoring screen.

Set up under System → Integrations → Zabbix. Contributed by Carl Steynvaard of Open Resilience, who built and ran it in production before offering it to the project.

Developers: how it works, the file map and the traps are in the Zabbix — Developer Guide.

---

What you get

• A problem opens an incident. Titled [Zabbix] web01: Disk space is low, with the host, the severity, Zabbix's own message and a link back to the problem in Zabbix.
• The priority follows the severity. You map each Zabbix severity — Not classified, Information, Warning, Average, High, Disaster — to one of your priorities.
• The server is linked. If a CMDB item has the same name as the Zabbix host (or its short name, web01 for web01.example.com), the incident is linked to it — so the outage shows on the server's record.
• It lands in the right company. On a multi-company install, an incident goes to the company its server belongs to in the CMDB; one for a server the CMDB does not know goes to the company you choose.
• A repeat is not a second ticket. An update to the same problem in Zabbix — an acknowledgement, a comment — is added to the ticket's thread.
• A recovery resolves it. A "recovered" message is added and the ticket moves to Resolved, or to whichever status you choose — or nowhere, if you would rather a person decided.
• You can see what arrived. The bottom of the Zabbix page lists the last 25 alerts received and what was done with each.

After that it is an ordinary incident: assignment, SLAs, notifications and reporting all work as they do for any other ticket.

---

🔑 Zabbix calls FreeITSM, not the other way round

FreeITSM never logs in to Zabbix and holds no Zabbix password. Zabbix sends each alert to an address on your FreeITSM, with a token — a long secret that proves the alert came from your Zabbix. Anything without it is refused. No token, no integration: until you make one, every alert is turned away.

If Zabbix runs on the same server or network as FreeITSM, its way to FreeITSM may not be the public address — change FreeITSM's address on the page (the parameters and the download follow it). For a Zabbix in Docker on the same machine, that is http://host.docker.internal/….

FreeITSM never connects to Zabbix — it needs neither Zabbix's address nor a Zabbix password. The address the page shows is FreeITSM's own, for you to give to Zabbix. The one Zabbix-side setting worth making is the macro {$ZABBIX.URL} (Administration → Macros in Zabbix), which gives each ticket a link back to the problem.

So Zabbix must be able to reach your FreeITSM. On the same network that is easy; if FreeITSM is only reachable inside your network and Zabbix is somewhere else, it is the first thing to sort out.

---

Setting it up

The in-app guide (System → Integrations → Zabbix → How to set up Zabbix) walks through it step by step. In short:

1. Make the token on the Zabbix page, and check the Address is one Zabbix can reach.
2. Import the media type into Zabbix. Click Download for Zabbix import on the FreeITSM page, then in Zabbix: Alerts → Media types → Import. It arrives complete — address, token, script, the three message templates, switched on. (It can also be set up by hand: the page gives the parameters and script, and the in-app guide the steps — including the Message templates tab, without which nothing is sent.) The file holds the token: keep it to yourself.
3. Give it to a Zabbix user (Users → the user → Media) and create an action (Alerts → Actions → Trigger actions) that sends to that user through FreeITSM — under Operations, Recovery operations and, if you want updates, Update operations.
4. Choose what the incidents look like on the FreeITSM page: who they are raised as, the company, a team, the severity → priority map, and what a recovery does.

Things worth knowing

• Who the tickets are "from". The default requester, zabbix@monitoring.invalid, is an address that can never receive mail — so an auto-acknowledgement workflow emails nobody. Use a real monitoring mailbox if you would rather it did.
• Updates and the user who made them. Zabbix never notifies the user who made an update. If the alerts go to the same Zabbix user who acknowledges problems, their acknowledgements never reach the ticket — send the alerts to a user of their own.
• Two servers with one name. If two companies each have a CMDB item matching the host, none is linked, rather than risk putting one company's alert on another's server.
• A recovery that cannot close the ticket. If a closure rule stops the status changing — a mandatory field, a checklist — the ticket stays open, the recovered message is still added, and the alert list says why.
• A new token stops the old one working at once. Download and import the media type again (or paste the new token into it) straight away.
• Setting it up by hand instead of importing? A new webhook in Zabbix comes with five parameters of its own — URL, HTTPProxy, To, Subject, Message. Delete them first: they belong to Zabbix's example script. Names are case-sensitive, so its Message is not FreeITSM's message. And add the three message templates, or nothing is ever sent.
• Behind a proxy? If your Zabbix server can only reach FreeITSM through a web proxy, put the proxy's address in the media type's http_proxy parameter. Leave it empty otherwise.

Testing it

• Send a test alert on the Zabbix page tests FreeITSM's half: a test problem goes through exactly what a real alert does, raising an incident titled [Zabbix] freeitsm-test: Test alert from FreeITSM with your settings, and Send the recovery resolves it. The test incident stays, so you can see what a real one looks like.
• Test on the media type in Zabbix tests the other half: that your Zabbix server can reach FreeITSM at all.

You need both: the first cannot prove the network, and the second cannot show you the incident your settings make.

If something is wrong

Start in Zabbix: Reports → Action log shows every attempt to send, with the error. Then the Recent alerts list on the FreeITSM page shows what arrived and what was done. The in-app guide's last section lists the common causes — a disabled media type, a stale token, a missing recovery operation.

---

Related: Zabbix — Developer Guide · CMDB · Multi-Tenancy · Workflows · Issue trackers