Aktionen

Zabbix mailGraph installieren - Trigger Alerts Emails mit Grafiken

Aus znilwiki

ACHTUNG-BAUSTELLE.png

Dieses Thema ist noch nicht vollständig! Es wird noch daran gearbeitet!



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
ClipCapIt-241118-132815.PNG

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:

ClipCapIt-241118-133041.PNG

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
ClipCapIt-241118-133353.PNG

Danach erscheint das Auth token was Ihr euch wegkopiert - Ihr könnt es danach nicht wieder anzeigen lassen sondern müsstet ein neues generieren!

ClipCapIt-241118-133607.PNG



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:

ClipCapIt-241119-093219.PNG

Oben links sollte ein

ClipCapIt-241119-093305.PNG

und in der Liste sollte es auch auftauchen:

ClipCapIt-241119-093427.PNG



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:

ClipCapIt-241119-101132.PNG

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:

ClipCapIt-241119-110839.PNG
ClipCapIt-241119-110932.PNG

Wichtig ist das Ihr bei Type unbedingt mailGraph auswählt. Alle nicht aktiven Medientypen werden in der Auswahlliste rot dargestellt.

ClipCapIt-241119-111919.PNG

Und den Klick auf Update nicht vergessen!


Trigger Action für mailGraph einrichten



Testen!