Was dieses Modul tut #

Eine Instanz hat viel zu erzählen: fail2ban hat eine IP gesperrt, aide hat eine geänderte Systemdatei gesehen, das Backup von heute Nacht ist fehlgeschlagen, die Root-Platte liegt bei 95 %. Wenn jedes Modul auf seine Weise meldet —eine Mail hier, eine Logzeile dort— bekommt niemand etwas mit, und bei zehn Instanzen wird das Problem zehnmal so groß.

Das Modul global-alerts ist der zentrale Alert-Bus von imaxe: ein einziger Befehl, durch den all diese Meldungen laufen, und ein einziges Ziel, an dem sie ankommen, ein Amazon-SNS-Topic, das deine ganze Flotte teilt. Von dort verteilt SNS, wie du willst: Mail, SMS, eine Lambda-Funktion, eine SQS-Queue, deine Rufbereitschaft. Veröffentlicht wird mit der IAM-Rolle der Instanz (Berechtigung sns:Publish), es gibt also keine Zugangsdaten zu speichern. Und der Lärm wird vor dem Senden gefiltert: eine Schweregrad-Schwelle verwirft alles unterhalb des Niveaus, das dich interessiert, und ein Deduplizierungsfenster verhindert, dass derselbe Alert dich vierzigmal weckt.

Ist SNS nicht erreichbar —Netz weg, Rolle noch ohne Berechtigungen, Region nicht erreichbar— geht der Alert nicht verloren: er wird auf Platte in die Warteschlange gelegt und ein systemd-Timer versucht es alle 5 Minuten erneut.

Bevor du anfängst

Du brauchst den ARN eines SNS-Topics (arn:aws:sns:region:konto:topic) und dass die Instanz darin veröffentlichen darf. Hast du die AMI über den Launcher gestartet, legt das CloudFormation-Template das Topic bereits an, abonniert deine Mail, erstellt die IAM-Rolle mit sns:Publish und übergibt den ARN als Tag an die Instanz: das Modul konfiguriert sich selbst und hier ist nichts zu tun.

SchnellstartAufgaben Schritt für Schritt

Häufige Aufgaben #

Such dir aus, was du tun willst. Jedes Rezept bringt den Befehl schon fertig mit — tausch ARN und Text gegen deine und klick auf Kopieren.

SNS-Topic festlegen Test-Alert senden Alert aus einem Skript senden Status des Bus ansehen Lärm reduzieren Warteschlange ansehen und erneut senden Modul stummschalten

1

SNS-Topic festlegen

Sag der Instanz, wo sie ihre Meldungen veröffentlichen soll.

Verbinde dich per SSH mit deinem Server als Benutzer ubuntu.

Richte das Modul auf den ARN deines Topics aus. Die Region wird aus dem ARN selbst abgeleitet, du musst sie also normalerweise nicht angeben:

Terminal

$ sudo imaxe global-alerts configure \
    --topic-arn arn:aws:sns:eu-west-1:123456789012:imaxe-alerts

Mehrere Instanzen, die in dasselbe Topic veröffentlichen? Gib jeder mit --source eine erkennbare Quellkennung (standardmäßig wird der Hostname verwendet):

Terminal

$ sudo imaxe global-alerts configure --source web-produktion-1

Die Konfiguration landet in /etc/imaxe/global-alerts.yml und der Versand ist aktiviert. Weiter mit dem Rezept Test-Alert senden.

2

Test-Alert senden

Prüf, dass die IAM-Rolle wirklich veröffentlicht, bevor du dem Kanal vertraust.

Veröffentliche einen Test-Alert im konfigurierten Topic:

Terminal

$ sudo imaxe global-alerts test

Der Test überspringt Schwelle und Deduplizierung —er geht immer raus— und gibt dir, wenn etwas schiefgeht, den echten AWS-Fehler zurück, statt still in die Warteschlange zu legen. Sieh im Postfach der auf das Topic abonnierten Adresse nach (auch im Spam-Ordner).

Siehst du die MessageId und kommt die Meldung an, funktioniert der Kanal. Kommt AuthorizationError, fehlt der Instanz die Berechtigung sns:Publish auf diesem Topic.

3

Alert aus einem Skript senden

Derselbe Kanal, den die Module nutzen, verfügbar für deine eigenen Sachen.

Ein Alert mit Schweregrad und Quelle:

Terminal

$ sudo imaxe global-alerts send --severity critical \
    --source backup --subject "Backup fehlgeschlagen" \
    "das nächtliche Datenbank-Backup endete mit einem Fehler"

Wird der Text von einem anderen Befehl erzeugt, gib ihn über stdin weiter und nutze - als Nachricht:

Terminal

$ df -h / | sudo imaxe global-alerts send --severity warning -

Bei etwas, das alle paar Minuten läuft, gib ihm einen stabilen Deduplizierungsschlüssel: innerhalb des konfigurierten Fensters geht nur der erste raus:

Terminal

$ sudo imaxe global-alerts send --severity warning \
    --dedup-key root-platte-voll "Root-Platte bei 95%"

Der Alert reist als JSON zum Topic, mit Instanz, Region und Zeitstempel bereits enthalten. Ohne --dedup-key leitet das Modul einen aus Quelle + Schweregrad + Betreff ab.

4

Status des Bus ansehen

Topic, Region, AWS-CLI und ausstehende Alerts auf einen Blick.

Zusammenfassung des aktuellen Zustands:

Terminal

$ sudo imaxe global-alerts status

Um zu prüfen, welche Konfiguration wirklich gilt —einschließlich der, die über Instanz-Tags kommt und Vorrang vor der Datei hat—:

Terminal

$ sudo imaxe global-alerts show
$ sudo imaxe global-alerts status --json

Du weißt, ob ein Topic konfiguriert ist, in welcher Region veröffentlicht wird und wie viele Alerts in der Warteschlange warten. Mit --json fertig für ein Dashboard oder ein Skript.

5

Lärm reduzieren

Heb die Schweregrad-Schwelle an und vergrößere das Deduplizierungsfenster.

Willst du nur mitbekommen, was zählt, verwirf alles unterhalb von warning:

Terminal

$ sudo imaxe global-alerts configure --min-severity warning

Das Deduplizierungsfenster hat kein Flag: es wird in der Konfigurationsdatei gesetzt. Erhöh es, wenn sich ein und derselbe Alert oft wiederholt:

/etc/imaxe/global-alerts.yml

dedup_window: 1h   # 30s, 5m, 1h… (Standard 5m)

Alerts unterhalb der Schwelle werden verworfen, bevor sie rausgehen (sie landen nicht in der Warteschlange), und Wiederholungen innerhalb des Fensters werden unterdrückt. test veröffentlicht weiterhin immer, du verlierst also nie die Möglichkeit, den Kanal zu prüfen.

6

Warteschlange ansehen und erneut senden

Was liegen blieb, als SNS nicht antwortete, und wie du den Versand erzwingst.

Sieh dir an, was aussteht, und die zuletzt gesendeten Schlüssel:

Terminal

$ sudo imaxe global-alerts history

Den Retry macht schon ein systemd-Timer alle 5 Minuten, aber du kannst ihn erzwingen, nachdem du Berechtigung oder Netz repariert hast:

Terminal

$ sudo imaxe global-alerts flush
$ systemctl status imaxe-global-alerts-flush.timer

Du siehst, wie viele rausgingen und wie viele noch warten. Schlägt der erste wieder fehl, hört der Durchlauf dort auf und lässt den Rest für den nächsten Versuch: nichts wird weggeworfen.

7

Modul stummschalten

Hör auf zu veröffentlichen, ohne die Konfiguration zu verlieren.

Deaktiviere den Alert-Versand und entferne den Retry-Timer:

Terminal

$ sudo imaxe global-alerts remove

Topic, Region und die übrigen Einstellungen bleiben in der Datei: zum Wiedereinschalten genügt ein configure, das das Modul reaktiviert.

Die Instanz veröffentlicht nicht mehr. Spätere send-Aufrufe schlagen nicht fehl: sie melden über stderr, dass das Modul deaktiviert ist, und enden mit Code 0.

Ohne IAM-Rolle keine Alerts

Das Modul veröffentlicht mit den Anmeldedaten der Instanzrolle, nicht mit gespeicherten Schlüsseln. Erlaubt die Rolle kein sns:Publish auf diesem Topic, stapeln sich die Alerts einer nach dem anderen in der Warteschlange, ohne je anzukommen. Ein imaxe global-alerts test sagt es dir sofort, mit dem Fehler genau so, wie AWS ihn zurückgibt.

CLI-ReferenzBefehle, Flags und Dateien

Synopsis #

Verwendung

imaxe global-alerts <Unterbefehl> [--topic-arn ARN] [--severity STUFE] [Flags]

Alle Unterbefehle brauchen root-Rechte (nutz sudo), weil sie nach /etc/imaxe/ schreiben, den Zustand in /var/lib/imaxe/ halten und eine systemd-Unit verwalten. Es gibt keine Geheimnisse zu verwalten: veröffentlicht wird über die IAM-Rolle der Instanz. Häng --json an status, show, history oder flush, um maschinenlesbare Ausgabe zu erhalten.

Unterbefehle #

Unterbefehl	Was er tut	Relevante Flags
status	Zustand: konfiguriertes Topic, effektive Region, AWS-CLI verfügbar und Alerts in der Warteschlange.	--json
configure	Legt SNS-Topic und Versandoptionen fest. Reaktiviert das Modul, falls es deaktiviert war.	--topic-arn, --region, --source, --min-severity
send	Veröffentlicht einen Alert. Das ist der Kanal, den Betreiber und die übrigen Module nutzen.	--severity, --source, --subject, --dedup-key
test	Veröffentlicht einen Test-Alert unter Umgehung von Schwelle und Deduplizierung und meldet den echten Fehler, wenn es scheitert.	--severity
show	Zeigt die effektive Konfiguration (Datei + bereits angewandte Instanz-Tags).	--json
history	Ausstehende Alerts in der Warteschlange und zuletzt gesendete Deduplizierungsschlüssel.	--json
flush	Wiederholt die eingereihten Alerts. Der systemd-Timer führt das ebenfalls aus.	--json
remove	Deaktiviert den Versand und entfernt den Timer. Behält die Konfiguration.	—

Argumente und Flags #

Flag	Typ	Standard	Beschreibung
--topic-arn erf.	string	—	ARN des Ziel-SNS-Topics (`arn:aws:sns:region:konto:topic`). Ohne ihn kann das Modul nicht veröffentlichen.
--region	string	aus dem ARN	AWS-Region. Fehlt sie, wird sie aus dem Topic-ARN abgeleitet; sonst aus IMDS oder `AWS_REGION`.
--source	string	hostname	Quellkennung. In `configure` die der Instanz; in `send` die dieses konkreten Alerts (z. B. das Modul, das ihn auslöst).
--min-severity	string	info	Schwelle: verwirft Alerts unterhalb dieser Stufe. Werte: `info`, `warning`, `critical`.
--severity	string	info	In `send`/`test`: die Stufe dieses Alerts. Die Kurzformen `warn` und `crit` werden akzeptiert.
--subject	string	aus der Nachricht	Kurzer Betreff. Fehlt er, wird er aus der Nachricht selbst abgeleitet.
--dedup-key	string	abgeleitet	Deduplizierungsschlüssel: unterdrückt Wiederholungen innerhalb von `dedup_window`. Standardmäßig aus Quelle + Schweregrad + Betreff berechnet.
<Nachricht> erf.	positional	—	In `send`: der Text des Alerts, oder `-`, um ihn von `stdin` zu lesen.
--json	bool	false	In `status`, `show`, `history` und `flush` gibt das Ergebnis als JSON auf `stdout` aus.

Verwerfen ist kein Fehlschlag

Wird ein Alert verworfen —Modul deaktiviert, Schweregrad unter der Schwelle oder Duplikat innerhalb des Fensters— erklärt send das über stderr und endet mit Code 0. So geht das Skript, das ihn ausgelöst hat, nicht an einem Filter kaputt, den du selbst konfiguriert hast.

Konfiguration über Instanz-Tags #

Jedes Deployment muss auf sein Topic zeigen, und dafür die AMI neu zu bauen ergäbe keinen Sinn. Deshalb liest das Modul neben der Datei auch die Tags der Instanz mit dem Präfix imaxe.global-alerts. über IMDSv2: existieren sie, gewinnen sie gegen das YAML. Genau das macht das CloudFormation-Template des Launchers, das außerdem MetadataOptions.InstanceMetadataTags: enabled verlangt, damit sie gelesen werden können.

Tag	Entspricht	Werte
imaxe.global-alerts.topic_arn	topic_arn	ARN des Ziel-SNS-Topics.
imaxe.global-alerts.region	region	AWS-Region; leer = aus dem ARN oder aus IMDS abgeleitet.
imaxe.global-alerts.source	source	Quellkennung; leer = Hostname.
imaxe.global-alerts.min_severity	min_severity	`info` · `warning` · `critical`
imaxe.global-alerts.dedup_window	dedup_window	Dauer: `30s`, `5m`, `1h`…
imaxe.global-alerts.enabled	enabled	`true`/`false` (auch `1`/`0`, `yes`/`no`, `on`/`off`).

Außerhalb von AWS oder mit blockiertem IMDS scheitert das Lesen in Millisekunden und das Modul macht mit dem weiter, was die Datei sagt. Um zu sehen, was wirklich aktiv geworden ist: imaxe global-alerts show.

Dateien und Pfade #

Pfad	Inhalt
/etc/imaxe/global-alerts.yml	Konfiguration des Moduls: Topic, Region, Quelle, Schwelle und Deduplizierungsfenster.
/var/lib/imaxe/state/global-alerts/spool/	Warteschlange ausstehender Alerts, einer pro `.json`-Datei, in chronologischer Reihenfolge.
/var/lib/imaxe/state/global-alerts/sent.json	Register der Deduplizierungsschlüssel mit der Uhrzeit des letzten Versands.
/etc/systemd/system/imaxe-global-alerts-flush.timer	Retry-Timer: startet 2 Min nach dem Boot und wiederholt alle 5 Min.

Beispiel für global-alerts.yml:

/etc/imaxe/global-alerts.yml

enabled: true
topic_arn: arn:aws:sns:eu-west-1:123456789012:imaxe-alerts
region: ""            # leer = aus dem ARN oder aus IMDS abgeleitet
source: ""            # leer = Hostname der Instanz
min_severity: info
dedup_window: 5m

Der Zustand (Warteschlange und Deduplizierungsregister) liegt absichtlich in /var/lib/imaxe/ und nicht in /etc/: es ist Zustand, keine Konfiguration. Beide Pfade lassen sich mit den Umgebungsvariablen IMAXE_CONFIG_DIR und IMAXE_STATE_DIR verschieben.

Format des Alerts #

Der Body der SNS-Nachricht ist versioniertes JSON (schema: 1), damit der Abonnent es außer per Mail auch mit einer Lambda oder einer Queue verarbeiten kann:

Nachrichten-Body

{
  "schema": 1,
  "severity": "critical",
  "source": "backup",
  "subject": "Backup fehlgeschlagen",
  "message": "das nächtliche Datenbank-Backup endete mit einem Fehler",
  "host": "web-produktion-1",
  "instance_id": "i-0abc123def4567890",
  "region": "eu-west-1",
  "ts": "2026-07-25T03:14:07Z",
  "dedup_key": "9f2c1b7e44a0d513"
}

Der Betreff der SNS-Nachricht wird als [imaxe][Schweregrad] host: Betreff zusammengesetzt, auf druckbares ASCII bereinigt und auf 100 Zeichen gekürzt, was das Limit von SNS ist.

Exit-Codes und Logs #

Jeder Lauf gibt einen Code zurück, den du mit echo $? prüfen kannst — praktisch zum Verketten in Skripten:

0OKVorgang abgeschlossen. Auch wenn der Alert absichtlich verworfen oder eingereiht wird.

1ERRAllgemeiner Fehler: der Test konnte nicht veröffentlicht werden, oder er konnte weder veröffentlicht noch eingereiht werden.

2USAGEUngültige Argumente: unbekanntes Flag, fehlende Nachricht oder ungültiger Schweregrad.

64NO TOPICKein SNS-Topic konfiguriert, weder per Datei noch per Tag.

Das Modul antwortet auch auf den Health-Check von imaxe: ist es aktiviert, aber ohne Topic, schlägt der Health fehl, sodass ein imaxe health es verrät, bevor der erste Alert überhaupt gebraucht wird.

Terminal

$ sudo imaxe global-alerts test; echo "Exit: $?"
$ journalctl -u imaxe-global-alerts-flush.service -n 50

Fehlersuche #

Symptom	Wahrscheinliche Ursache	Lösung
Es kommt NO TOPIC (Code 64)	Weder Datei noch Tags liefern einen Topic-ARN.	Führ `configure --topic-arn …` aus, oder prüf, dass die Instanz den Tag `imaxe.global-alerts.topic_arn` hat und Tags in den Metadaten aktiviert sind.
„SNS nicht verfügbar; Alert eingereiht“ immer wieder	Der Instanzrolle fehlt `sns:Publish` auf diesem Topic, oder der ARN gehört zu einem anderen Konto oder einer anderen Region.	Führ `test` aus, um den genauen AWS-Fehler zu sehen, korrigier die Policy der Rolle und dann `flush`.
„aws-CLI verfügbar: false“ im status	Auf der Instanz ist die AWS-CLI nicht installiert; das Modul veröffentlicht darüber.	Installier die AWS-CLI. Die AMIs von imaxe bringen sie mit; auf einem eigenen Host muss man sie nachrüsten.
Du konfigurierst etwas und show zeigt weiter einen anderen Wert	Ein Tag `imaxe.global-alerts.*` überschreibt die Datei: er hat konstruktionsbedingt Vorrang.	Änder den Tag der Instanz (oder den Parameter des CloudFormation-Stacks) statt des YAML.
Von mehreren gleichen Alerts kommt nur der erste an	Das Deduplizierungsfenster unterdrückt sie.	Das ist so gewollt. Senk `dedup_window`, oder nutz unterschiedliche `--dedup-key`, wenn es wirklich verschiedene Ereignisse sind.
Es kommt nichts an und es gibt keine Fehler	Das Modul ist deaktiviert, oder der Schweregrad liegt unter `min_severity`.	`show` zeigt dir `enabled` und die Schwelle; `configure` reaktiviert den Versand.
Alerts werden veröffentlicht, kommen aber nicht per Mail an	Das Abonnement des SNS-Topics ist nicht bestätigt.	Such die Bestätigungsmail von AWS (sieh im Spam nach) und akzeptier das Abonnement in der SNS-Konsole.

Steckst du beim Modul Alerts fest?

Schreib uns mit der Ausgabe von «imaxe <module> status --json» und wir antworten dir schnell.

Support kontaktieren

Ein einziger Ort, an dem du deine ganze Flotte hörst

Was dieses Modul tut #

Häufige Aufgaben #

SNS-Topic festlegen

Test-Alert senden

Alert aus einem Skript senden

Status des Bus ansehen

Lärm reduzieren

Warteschlange ansehen und erneut senden

Modul stummschalten

Synopsis #

Unterbefehle #

Argumente und Flags #

Konfiguration über Instanz-Tags #

Dateien und Pfade #

Format des Alerts #

Exit-Codes und Logs #

Fehlersuche #

Steckst du beim Modul Alerts fest?