Zabbix mailGraph installieren - Trigger Alerts Emails mit Grafiken
Aus znilwiki
Changelog:
- 18. bis 20.11.2024 erste Version
Vorwort
Ein Kunde wünschte sich bei Emailbenachrichtigungen von Zabbix das in dieser Email auch gleich die Grafik des letzten Tages und der letzten 7 Tage enthalten sind.
Grafiken für Items abrufen habe ich vor ein paar Jahren schon mal gemacht (z.B. WinZabbixREPORTER.exe), auch mit dem alten Telegram-Skript habe ich mir schon Grafiken zuschicken lassen. Grundsätzlich ist das also möglich und ich habe zugesagt das zu realisieren.
Bei meinen Recherchen für die Lösung bin ich auf dieses Projekt von Mark Oudsen gestoßen: https://github.com/moudsen/mailGraph
Dieses erfüllt eigentlich schon alle Ansprüche und ich habe mich zunächst dagegen entschieden etwas selbst zu programmieren.
Dieser Artikel ist nun im Zuge der Testinstallation von mailGraph entstanden um eine reproduzierbare Anleitung zu erhalten.
Ich muss mailGraph in 3 verschiedenen Konstellationen zum laufen bekommen:
- Zabbix 6 auf Ubuntu 20.04 und PHP 7.4.3
- Zabbix 7 auf Ubuntu 22.04 und PHP 8.1.2
- Zabbix 7 auf Ubuntu 24.04 und PHP 8.3.6
von der Wichtigkeit in dieser Reihenfolge - also fange ich mit Zabbix 6 auf Ubuntu 20.04 an.
Im Moment scheint es so das mailGraph nicht mit Zabbix 7 funktioniert. Grund ist das bei API-Zugriffen nun zwingend ein API-Schlüssel statt eines Passwortes verwendet werden muss und der Übergabeparameter deswegen anders heißt. Die Änderung ist nicht so schwierig und habe ich bereits in anderen Skripten vorgenommen. Ich werden sehen wie ich das handhabe, eventuell lässt sich Zabbix 7 auch zum alten verhalten überreden.
Ich installiere hier mailGraph auf den gleichen Server auf dem auch Zabbix läuft, das muss aber nicht so sein, Zabbix muss per URL die mailGraph.php erreichen können und umgekehrt muss mailGraph das Zabbix-Frontend / die Weboberfläche per URL erreichen können. Man kann das ganze also auch trennen.
Hinweis zu den Zabbix-Grafiken
mailGraph bekommt von Zabbix die Event-Id des ausgelösten Triggers mitgeteilt. Über die Zabbix-API ermittelt mailGraph dann alle benötigten Informationen, unter anderem welche Items beteiligt sind. Es sucht dann vorhandene(!!!) Grafiken in welchen die Items vorkommen und erstellt diese über das Zabbix-Webinterface (die chart2.php).
Das bedeutet das keine ad hoc Grafiken erstellt werden sondern das die gewünschten Grafiken beim Host in Zabbix hinterlegt sein müssen. Da man Grafiken auch in den Templates definieren kann ist das weniger umständlich als es klingt. Zudem kann man die Grafiken so informativer Gestalten.
Es gibt eine CPU-Warnung für einen Cluster-Knoten? Man kann in die Grafik gleich die CPU-Auslastung aller Knoten einbauen.
Es ist eine "freier Speicherplatz auf Laufwerk D:" Warnung? In die Grafik könnte Ihr auch gleich den gesamten und belegten Speicherplatz einbauen.
Es gibt wohl die Möglichkeit die Grafiken zu filtern so das man über die Bezeichnung nur bestimmte Grafiken senden könnte. Das habe ich zu diesem Zeitpunkt aber noch nicht getestet und werde es ggf. später in dieser Anleitung hinterlegen.
Werden keine Grafiken gefunden, so wird immer noch die Meldung selbst über mailGraph gesendet, dann halt nur ohne Grafiken. Sorgt also dafür das im Template auch genügend Informativer Text dabei ist.
Hinweis zu dieser Anleitung
Ich arbeite hier in den SSH-Sitzungen als root um mir ständige sudo Eingaben zu ersparen.
Dazu wechsle ich per
sudo -i
dauerhaft in einer SSH-Sitzung zum Benutzer root.
Bei Bedarf wird in der Anleitung in den Kontext eines anderen Benutzers geweschselt, z.B. www-data
mailGraph mit Zabbix 6.0 LTS und Ubuntu 20.04 LTS mit PHP 7.4.3
Postfix installieren und konfigurieren
Den eigentlichen Mailtransport übernimmt Postfix, welchen wir dann so konfigurieren das dieser alle Emails an einen Smarthost (z.B. ein Exchange-Server) weiterleitet. Mailutils brauchen wir zum testen.
apt install postfix mailutils -y
In den nachfolgenden Optionen wählt Ihr dann folgendes (Namen und IP-Adressen ggf. anpassen):
- Satellitensystem
- E-Mail-Name des Systems: testzabbix6.znil.local
- SMTP-Relay-Host: 192.168.128.83
Die IP-Adresse muss dann euer SMTP-Relay bzw. euer Mailserver sein.
Natürlich testen wir einmal ob der Versand funktioniert:
echo "Test Email Body" | mail -s "Testnachricht von testzabbix6" "admin@znil.org"
Wen die Email nicht ankommt, schaut als erstes in den Junk-E-Mail Ordner von Outlook.
Ansonsten könnte ihr mit dem Befehl
mailq
sehen ob Postfix die Email überhaupt losgeworden ist. Ist der Empfänger innerhalb euerer Organisation sollte das eigentlich immer Klappen (vom Jun-E-Mail Ordner mal angesehen).
PHP benötigte Pakete installieren
Der Composer wird benötigt um später verschiedene PHP-Module zu installieren, php-curl für den Zugriff auf das Zabbix-Server Webinterface:
apt install composer php-curl -y
mailGraph herunterladen und installieren
cd /var/www/html git clone https://github.com/moudsen/mailGraph mailGraph chown -R www-data:www-data /var/www sudo -u www-data /usr/bin/bash cd mailGraph mkdir log tmp composer require phpmailer/phpmailer composer require twig/twig cp config/config.json.template.multigraph config/config.json exit
Ihr solltet jetzt wieder den Eingabeprompt des root haben.
mailGraph per http erreichbar machen
mailGraph wird später per Webhook aufgerufen, also per URL-Aufruf.
In meinen Installationen habe ich die Standardwebseite durch die der Zabbix-Webseite ersetzt.
Wenn ich also die IP-Adresse des Zabbix-Servers im Webbrowser eingebe erscheint die Zabbix-Weboberfläche, auch ohne den Zusatz /zabbix.
Wenn bei euch nur die Standardwebseite des Apache Webservers erscheint, sollte der Zugriff über /mailGraph bereits funktionieren.
Wenn nicht erstellen wir eine Konfiguration (schadet auch nicht das zu tun):
nano /etc/apache2/conf-available/mailGraph.conf
und folgenden Inhalt einfügen:
<IfModule mod_alias.c>
Alias /mailGraph /var/www/html/mailGraph
</IfModule>
<Directory "/var/www/html/mailGraph">
Options FollowSymLinks
AllowOverride None
Order allow,deny
Allow from all
<IfModule mod_php7.c>
php_value max_execution_time 300
php_value memory_limit 128M
php_value post_max_size 16M
php_value upload_max_filesize 2M
php_value max_input_time 300
php_value max_input_vars 10000
php_value always_populate_raw_post_data -1
php_value date.timezone Europe/Berlin
</IfModule>
</Directory>
Im Anschluss:
a2enconf mailGraph systemctl reload apache2
Kleiner Test:
http://192.168.0.6/mailGraph/mailGraph.php
aufrufen (IP-Adresse an euren Zabbix-Server anpassen) sollte eine Meldung wie
Missing EVENT ID?
ergeben.
Nun können wir auch gleich die benötigte Konfigurationsdatei für Zabbix herunterladen, da der Webbrowser die Datei aber direkt öffnen würde, nutzen wir einen kleinen Trick:
sudo -u www-data /usr/bin/nano /var/www/html/mailGraph/downloadxml.html
und fügen folgende Zeile ein:
<a href="mailGraph.xml?dummy=dummy" download>Download mailGraph.xml</a>
Nun können wir über folgenden Link die XML herunterladen und auf unserem Rechner speichern:
http://192.168.0.6/mailGraph/downloadxml.html
Da erscheint dann ein Link, auf den drücken wir dann drauf :-)
Zabbix Benutzer mit API-Zugriff erstellen
Wir brauchen einen Zabbix Super Admin Benutzer mit Passwort und einen API-Schlüssel für diesen Benutzer.
mailGraph meldet sich über die API an um die notwendigen Daten und IDs zu ermitteln, der Download der Grafiken erfolgt aber über die Web-Schnittstelle, deshalb wird beides benötigt.
Auf der Weboberfläche von Zabbix:
Administration => Users => Create user
Bitte keine Sonderzeichen im Benutzernamen oder im Passwort. Es darf lang sein, Groß und Klein und Zahlen.
Die Sprache stellt auf English (en_GB) damit er auch brav die europäische Schreibweise bei Datum und Uhrzeit nutzt.
Dann auf den Reiter Permissions wechseln:
und die Super admin role setzen.
Meldet euch bei Zabbix ab und mit dem neu erstellen Benutzer gleich wieder an.
Geht dann unten links auf
User settings => API tokens => Create API token
Danach erscheint das Auth token was Ihr euch wegkopiert - Ihr könnt es danach nicht wieder anzeigen lassen sondern müsstet ein neues generieren!
mailGraph konfigurieren
wieder in der SSH-Sitzung, wir wechseln wieder zum www-data Benutzer weil wir die Konfiguration dann testen können:
sudo -u www-data /usr/bin/bash cd /var/www/html/mailGraph nano config/config.json
und den Inhalt wie folgt (Erklärungen kommen darunter):
{
"script_baseurl": "http:\/\/192.168.0.6\/mailGraph\/",
"cli_eventId": 0,
"cli_duration": 0,
"cli_recipient": "admin@znil.org",
"cli_subject": "[TEST] {{ HOST_NAME|raw }}: ({{ EVENT_SEVERITY }}) {{ EVENT_NAME|raw }}",
"cli_baseURL": "http:\/\/192.168.0.6\/",
"cli_periods": "10m,4h,2d,7d",
"cli_periods_headers": "Last 10 minutes,Last 4 hours,Last 2 days,Last 7 days",
"cli_debug": 1,
"cli_proxy": "",
"zabbix_user": "mailgraphuser",
"zabbix_user_pwd": "test123456",
"zabbix_api_user": "mailgraphuser",
"zabbix_api_pwd": "test123456",
"subject": "{{ HOST_NAME|raw }}: ({{ EVENT_SEVERITY }}) {{ EVENT_NAME|raw }}",
"smtp_server": "localhost",
"smtp_port": 25,
"smtp_transport": "none",
"smtp_strict": "yes",
"smtp_from_address": "mailgraph@testzabbix6.znil.local",
"smtp_from_name": "mailGraph TestZabbix6",
"smtp_reply_address": "admin@znil.org",
"smtp_reply_name": "mailGraph response mailbox",
"graph_match": "any",
"periods": "10m,4h,2d,7d",
"periods_headers": "Last 10 minutes,Last 4 hours,Last 2 days,Last 7 days",
"retention_logs": 14,
"retention_images": 14,
"debug": 0
}
Erläuterung der Optionen im Detail:
"script_baseurl": "http:\/\/192.168.0.6\/mailGraph\/"
Die URL über welche mailGraph aufgerufen wird, hier also das virtuelle Verzeichnis welches wir zuvor angelegt haben.
Wichtig ist das alle / Escaped werden müssen mit einem \ davor.
Und das es am Ende auch noch ein / kommt.
"cli_eventId": 0, "cli_duration": 0,
wird für die Kommandozeilen-Testoptionen benötigt und müssen in der aktuellen Version beide auf 0 stehen. Der Test wählt dann zufällig bzw. den neuesten ausgelösten Trigger aus.
"cli_recipient": "admin@znil.org",
wird für die Kommandozeilen-Testoptionen benötigt und gibt den Empfänger der Test-E-Mails an
"cli_subject": "[TEST] {{ HOST_NAME|raw }}: ({{ EVENT_SEVERITY }}) {{ EVENT_NAME|raw }}",
wird für die Kommandozeilen-Testoptionen benötigt und definiert die Betreffzeile der Email
"cli_baseURL": "http:\/\/192.168.0.6\/",
wird für die Kommandozeilen-Testoptionen benötigt und gibt den Ziel-Zabbix-Server an, also die URL über welche die Weboberfläche und API erreichbar ist.
"cli_periods": "10m,4h,2d,7d",
wird für die Kommandozeilen-Testoptionen benötigt und gibt die Zeiträume der Grafiken an, hier die letzten 10 Minuten, die letzten 4 Stunden, die letzten 2 Tage und die letzten 7 Tage
"cli_periods_headers": "Last 10 minutes,Last 4 hours,Last 2 days,Last 7 days",
wird für die Kommandozeilen-Testoptionen benötigt und legt die Überschriften über den Grafiken der zuvor definierten Zeiträume fest. Über der Grafik mit den letzten 2 Tagen steht also die Überschrift "Last 2 days"
"cli_debug": 1,
wird für die Kommandozeilen-Testoptionen benötigt und sorgt für umfangreiche Debuggingmeldung welche auch an die Email angehängt werden (als .log Datei)
"cli_proxy": "",
wird für die Kommandozeilen-Testoptionen benötigt und legt ggf. einen zu verwendenden Proxy-Server fest
"zabbix_user": "mailgraphuser", "zabbix_user_pwd": "test123456",
Der Benutzer für den Zugriff auf die Weboberfläche mit Passwort
"zabbix_api_user": "mailgraphuser", "zabbix_api_pwd": "test123456"
Der Benutzer für den Zugriff auf die API von Zabbix. ACHTUNG! Der Zugriff per API-Schlüssel wird aktuell noch nicht unterstützt! Deshalb auch hier das Passwort.
"subject": "{{ HOST_NAME|raw }}: ({{ EVENT_SEVERITY }}) {{ EVENT_NAME|raw }}",
Wie die Betreffzeile bei normalen Emails aussehen soll. Es Können die Zabbix-Makronamen verwendet werden, jedoch den . durch einen _ ersetzen und siehe die Schreibweise mit den doppelten Klammern + Leerzeichen
"smtp_server": "localhost", "smtp_port": 25, "smtp_transport": "none", "smtp_strict": "yes",
Die Angaben zum Ziel-Mailserver. Wir haben zuvor Postfix konfiguriert so das wir diese einfach dem eigenem System in die Hand drücken können. Dafür sollten die Einstellungen passen
"smtp_from_address": "mailgraph@testzabbix6.znil.local", "smtp_from_name": "mailGraph TestZabbix6",
Absender Email-Adresse und Anzeigename unter dem die Nachrichten versendet werden
"smtp_reply_address": "admin@znil.org", "smtp_reply_name": "mailGraph response mailbox",
Antwortadresse, also wohin gesendet wird wenn jemand bei der Mail auf Antworten drückt
"graph_match": "any",
Filter für die gefundenen Grafiken. any liefert jede zurück, weitere mögliche Werte sind Exact und Other, die Bedeutung bzw. Funktionsweise habe ich noch nicht herausgefunden
"periods": "10m,4h,2d,7d", "periods_headers": "Last 10 minutes,Last 4 hours,Last 2 days,Last 7 days",
gibt die Zeiträume der Grafiken an, hier die letzten 10 Minuten, die letzten 4 Stunden, die letzten 2 Tage und die letzten 7 Tage,
sowie deren Überschriften. Über der Grafik mit den letzten 4 Stunden steht also die Überschrift "Last 4 hours"
"retention_logs": 14, "retention_images": 14,
Wie lange sollen die Logs und die Grafiken auf Festplatte gespeichert bleiben bevor diese gelöscht werden. Achtung, die Bilder können bei vielen Emails auch viel Platz einnehmen!
"debug": 0
Kein ausführliches Debbugging bei normalen Nachrichten.
Template in Zabbix importieren
Als wir den http:// Zugriff auf mailGraph eingerichtet haben, haben wir auch gleich die mailGraph.xml heruntergeladen.
Diese Datei ist ein Media type Template, mir war vorher gar nicht aufgefallen das es so etwas gibt.
Auf dem Webinterface des Zabbix-Servers gehen wir auf
Administration => Media types => Import
und importieren diese Datei:
Oben links sollte ein
und in der Liste sollte es auch auftauchen:
Media Types deaktivieren
Damit es später leichter in den anderen Dialogen wird, würde ich euch empfehlen alle Media types zu deaktivieren die Ihr nicht nutzt.
Jeder aktive Media type erscheint später nämlich in den Auswahllisten. Ihr könnt vorne per Kontrollkästchen mehre markieren und unten dann auf Disable klicken, alternativ klickt Ihr auf das grüne Wort Enabled hinter dem Namen und Typ des um den Media types um dessen Status umzuschalten.
mailGraph in Zabbix konfigurieren
Wir klicken in der Liste der Media types auf mailGraph um diesen zu konfigurieren:
Die Parameter im Detail:
baseURL http://192.168.0.6/
Die URL zum Webinterface eures Zabbix-Servers mit einem abschließenden /. Endet oft auch auf /zabbix/ je nach dem wir Ihr installiert habt.
Wenn Ihr oben in die Adresszeiles des Browser schaut, sollte da die richtige Adresse stehen (alles vor zabbix.php)
duration {EVENT.DURATION}
Wie lange der Trigger schon ausgelöst hat bzw. hatte, Wert wird dem Makro {EVENT.DURATION} entnommen, Wert in Sekunden.
Zeit bei einer Recovery-Meldung an wie lange der Trigger ausgelöst hatte.
Siehe auch https://www.zabbix.com/documentation/current/en/manual/appendix/macros/supported_by_location
eventId {EVENT.ID}
Die Id des Ereignisses / Problems welches der Trigger ausgelöst hat. Die wichtigste Information überhaupt für mailGraph, anhand dieses Wertes werden alle Daten ermittelt.
graphHeight 300 graphWidth 600
Höhe und Breite der eingebetteten Grafiken in Pixeln. Ich habe die Werte etwas erhöht, die Augen werden auch nicht besser.
HTTPProxy
Hier könnte man einen Proxy angeben falls der für den Zugriff auf mailGraph notwendig wäre.
infoTest Test
Ein Beispiel für die Übergabe weiterer Daten an mailGraph. infoText könnte man auch mit dem Wert eines Makros füllen, der Wert kann im verwendeten Template (abgelegt unter /var/www/html/mailGraph/templates über TWIG verwendet werden. Um infoText dort zu verwenden würde man Vorlage:InfoText verwenden.
Bevor Ihr hier anfangt etwas zu übergeben, schaut unter https://github.com/moudsen/mailGraph/wiki/5--Templates nach ob es den Wert nicht schon gibt.
periods 7d,183d
Für welche Zeiträume sollen die Grafiken eingebettet werden? Ich habe hier die letzten 7 Tage und das letzte halbe Jahr, jeweils in Tagen.
Man könnte auch nur einen Zeitraum angeben oder auch mehr.
periods_headers Letzten 7 Tage,Letzten 6 Monate
Überschriften über die zuvor definierten Zeiträume, die 183 Tage würden also mit Letzten 6 Monate überschrieben werden.
recipient {ALERT.SENDTO}
Die Emailadresse des Empfängers, muss beim Benutzer für den Medientyp mailGraph hinterlegt sein. Es wird nicht automatisch die ggf. schon hinterlegte Emailadresse für andere Media types wie Email oder Email (HTML) genommen.
showLegend 1
Ob unter den Grafiken die Legende, also die Erklärung welche Farbe welcher Linie wofür steht. Sinnvoll falls mehr als ein Item in der Grafik dargestellt wird.
subject Vorlage:HOST NAME - Vorlage:EVENT STATUS (Vorlage:EVENT SEVERITY): Vorlage:EVENT NAME
Die Betreffzeile der gesendeten Email, hier anpasst an meine persönlichen Vorlieben. Sollte etwa so aussehen:
DCNEW.znil.local - PROBLEM (Average): Service stopped: Druckwarteschlange
Siehe auch https://github.com/moudsen/mailGraph/wiki/5--Templates
URL http://192.168.0.6/mailGraph/mailGraph.php
Die komplette URL zur mailGraph.php, testet den Aufruf vorher im Browser, sollte die Missing EVENT ID? Meldung bringen.
Email-Adresse bei einem Benutzer für mailGraph hinterlegen
Ein Zabbix Super Admin kann den Benutzern unter
Administration => Users => Username anklicken => Media
die Email-Adresse hinterlegen. Alternativ kann der Benutzer wenn er an Zabbix angemeldet ist diese selbst unter
User Settings => Profile => Media
hinzufügen:
Wichtig ist das Ihr bei Type unbedingt mailGraph auswählt. Alle nicht aktiven Medientypen werden in der Auswahlliste rot dargestellt.
Und den Klick auf Update nicht vergessen!
Trigger Action - Vorwort
Zuerst ein Hinweis: In den Trigger actions für Benachrichtigungen kann man festlegen über welche Medien die jeweilige Action senden soll.
In der Default Action Report problems to Zabbix administrators die es nach einer frischen Installation gibt ist das aber so definiert:
- All - bedeutet das die Personen oder Gruppen über alle hinterlegten Medien informiert werden.
Nutzt Ihr z.B. Email (HTML), Telegram und nun noch mailGraph würde der Benutzer also gleich 3 Meldungen erhalten.
Ist das so gewollt - Ok.
Ich persönlich erstelle für jeden Medientyp eine eigene Trigger action, ich finde das übersichtlicher und kann z.B. auch Trigger auf bestimmten Medien ausfiltern bzw. die Trigger überhaupt nach Medien filtern.
Ich rate euch also dringend, eure bestehenden Trigger actions einmal zu kontrollieren und nach Möglichkeit immer den gewünschten Medientyp fest einzustellen.
Eine schnelle Übersicht dafür bietet die
Administration => Media types
Ansicht, hinter jedem Media type ist in der Spalte Used in actions aufgeführt für welche diese greift:
Ein Fehler im System: Wenn man sich in einer Trigger action unter "Recovery operations" per Notify all involved sendet lässt, taucht diese Trigger action zumindest im Moment bei Zabbix Version ab 7.x immer bei jeden Media type auf.
Trigger Action für mailGraph einrichten
Zum Testen erstelle ich nun eine Trigger action die bei einem Problem sofort eine Mail versendet, ggf. solltet Ihr in einer Produktivumgebung diese auf Hostgruppen oder einzelne Hosts einschränken.
Configuration => Actions => Trigger actions => Create action
Bei den Conditions setzte ich einen Filter das die Trigger severity mindestens Warning oder höher sein muss.
Hier könntet Ihr auch noch nach Hosts / Hostgruppen filtern.
Weiter geht es auf dem Reiter Operations:
Die Defaul operation step duration setzte ich immer auf 1m, also 1 Minute. Das ist der zeitliche Abstand zwischen 2 Schritten. Im Normalfall lasse ich mir Meldungen z.B. erst nach 10 Minuten senden, wenn ich die Operation dann also auf den Schritt 11 setze, so führt er diese erst nach 10 Minuten aus.
Wir klicken bei Operations auf Add:
Steps lasse ich auf 1, so wird sofort gesendet (zum Testen), bei Send only to stelle ich auf mailGraph.
Custom message ist in Zusammenhang mit mailGraph übrigens sinnlos da der Text aus diesem Feld nicht ausgewertet wird.
Für den Test ist das schon alles.
Testen!