windows-updater/docs/notifications.md

Benachrichtigungen einrichten

Das Script unterstützt drei unabhängige Benachrichtigungskanäle, die einzeln oder gleichzeitig genutzt werden können.

ntfy

ntfy ist ein einfacher Push-Notification-Dienst. Es kann die öffentliche Instanz (ntfy.sh) oder ein selbst gehosteter Server verwendet werden.

Einrichtung

1. Topic wählen - Ein Topic-Name ist wie ein Kanal, auf den man Nachrichten sendet (z.B. windows-updates-meinserver)

2. App installieren (optional) - ntfy-App für Android, iOS oder Web öffnen und das Topic abonnieren

3. Token erstellen (optional) - Wenn der ntfy-Server Authentifizierung erfordert, einen Access Token erstellen

4. Config anpassen:

[Notification]
NtfyEnabled = true
NtfyUrl = https://ntfy.sh
NtfyTopic = windows-updates-meinserver
NtfyToken =
NtfyPriority = default

Prioritäten

Wert	Bedeutung
min	Keine Vibration, kein Sound
low	Keine Vibration
default	Standard-Verhalten
high	Hohe Priorität mit Sound
urgent	Höchste Priorität, durchbricht "Nicht stören"

Das Script verwendet automatisch high für Fehler und Reboot-Benachrichtigungen.

Selbst gehosteter ntfy-Server

Bei einem eigenen ntfy-Server die URL entsprechend anpassen:

NtfyUrl = https://ntfy.mein-server.de
NtfyToken = tk_mein_zugangstoken

E-Mail

Einrichtung

1. SMTP-Zugangsdaten beschaffen - Diese bekommt man vom E-Mail-Provider oder dem eigenen Mailserver

2. Config anpassen:

[Notification]
EmailEnabled = true
SmtpServer = smtp.example.com
SmtpPort = 587
SmtpUseSsl = true
SmtpUsername = user@example.com
SmtpPassword = mein-passwort
EmailFrom = updater@example.com
EmailTo = admin@example.com
EmailHtmlReport = true

Mehrere Empfänger

Kommagetrennt in EmailTo:

EmailTo = admin@example.com,ops@example.com,chef@example.com

HTML-Report

Wenn EmailHtmlReport = true gesetzt ist, enthält die E-Mail nach der Update-Installation eine formatierte HTML-Tabelle mit:

• Hostname und Betriebssystem
• Datum und Uhrzeit
• Anzahl erfolgreicher und fehlgeschlagener Updates
• Tabelle mit allen Updates (KB, Titel, Größe, Ergebnis)
• Farbcodierung: Grün für Erfolg, Rot für Fehler

Bei EmailHtmlReport = false wird stattdessen eine einfache Text-E-Mail gesendet.

Häufige SMTP-Einstellungen

Provider	Server	Port	SSL
Microsoft 365	smtp.office365.com	587	true
Gmail	smtp.gmail.com	587	true
Eigener Server	mail.example.com	587 oder 465	true
Lokaler Relay	localhost	25	false

Hinweis: Bei Gmail wird ein App-spezifisches Passwort benötigt, kein normales Kontopasswort.

E-Mail ohne Authentifizierung

Bei einem lokalen SMTP-Relay ohne Authentifizierung:

SmtpServer = mailrelay.local
SmtpPort = 25
SmtpUseSsl = false
SmtpUsername =
SmtpPassword =

Microsoft Teams

Einrichtung

Benachrichtigungen werden über einen Webhook an einen Teams-Kanal gesendet. Es werden Adaptive Cards verwendet, die eine übersichtliche Darstellung mit Update-Details bieten.

Webhook erstellen (Workflows / Power Automate)

Microsoft hat den klassischen Incoming Webhook-Connector in Teams abgekündigt. Neue Webhooks werden über Workflows erstellt:

1. Im gewünschten Teams-Kanal auf ⋯ → Workflows klicken
2. Die Vorlage "Post to a channel when a webhook request is received" auswählen
3. Dem Flow einen Namen geben und bestätigen
4. Die generierte Webhook-URL kopieren

Webhook erstellen (klassischer Incoming Webhook-Connector)

Falls der klassische Connector in der Organisation noch verfügbar ist:

1. Im gewünschten Teams-Kanal auf ⋯ → Connectors klicken
2. Incoming Webhook suchen und Konfigurieren klicken
3. Namen vergeben (z.B. "Windows Updater") und optional ein Icon hochladen
4. Erstellen klicken und die generierte Webhook-URL kopieren

Config anpassen

[Notification]
TeamsEnabled = true
TeamsWebhookUrl = https://xxxxx.webhook.office.com/webhookb2/...

Darstellung

Die Teams-Benachrichtigung wird als Adaptive Card dargestellt und enthält:

• Titel der Benachrichtigung (farblich hervorgehoben)
• Hostname und Zeitstempel
• Nachrichtentext
• Bei Update-Berichten: Detailliste aller Updates mit Status-Icons (✅ Erfolg / ❌ Fehler)

Benachrichtigungs-Ereignisse

Das Script sendet Benachrichtigungen bei folgenden Ereignissen. Jedes Ereignis kann einzeln in der Sektion [NotificationEvents] der config.ini ein- oder ausgeschaltet werden. Standardmäßig sind alle Ereignisse aktiviert.

Übersicht

Ereignis	Config-Schlüssel	Priorität	Subject-Muster
Scan-Fehler	NotifyOnScanError	high	Scan Error - <Hostname>
Modul-Fehler	NotifyOnModuleError	high	Windows Update FAILED - <Hostname>
Pre-Hook fehlgeschlagen	NotifyOnHookFailure	high	Windows Update ABORTED - <Hostname>
Keine Updates	NotifyOnNoUpdates	default	No Updates - <Hostname>
Dry-Run Report	NotifyOnDryRun	default	Dry-Run Report - <Hostname>
Update-Zusammenfassung	NotifyOnUpdateComplete	default/high	Updates OK - <Hostname> oder Updates (with errors) - <Hostname>
Neustart wird ausgeführt	NotifyOnReboot	high	Reboot - <Hostname> / Reboot in X min - <Hostname> / Reboot scheduled at HH:MM - <Hostname>
Neustart erforderlich	NotifyOnRebootRequired	high	Reboot Required - <Hostname>
Dienst-Neustart fehlgeschlagen	NotifyOnServiceRestartFailure	high	Service Restart FAILED - <Hostname>

Details zu jedem Ereignis

Scan-Fehler (NotifyOnScanError)

Der Windows-Update-Scan ist fehlgeschlagen (Get-AvailableUpdates hat $null zurückgegeben). Das Script bricht ab, es werden keine Updates installiert.

• Priorität: high
• Subject: Scan Error - <Hostname>
• Inhalt: Hinweis, dass der Update-Scan fehlgeschlagen ist

Modul-Fehler (NotifyOnModuleError)

Das PSWindowsUpdate-Modul konnte weder online (PSGallery) noch offline (lokaler Modules-Ordner) geladen werden. Das Script bricht ab, es werden keine Updates installiert.

• Priorität: high
• Subject: Windows Update FAILED - <Hostname>
• Inhalt: Fehlermeldung, dass das Modul nicht geladen werden konnte

Pre-Hook fehlgeschlagen (NotifyOnHookFailure)

Das in [Hooks] PreUpdateScript konfigurierte Script hat einen Exit-Code ≠ 0 zurückgegeben und AbortOnPreHookFailure = true ist gesetzt. Der Update-Prozess wird abgebrochen.

• Priorität: high
• Subject: Windows Update ABORTED - <Hostname>
• Inhalt: Exit-Code und Pfad des fehlgeschlagenen Hook-Scripts

Keine Updates (NotifyOnNoUpdates)

Der Update-Scan hat keine verfügbaren Windows-Updates gefunden. Das Script beendet sich regulär.

• Priorität: default
• Subject: No Updates - <Hostname>
• Inhalt: Hinweis, dass keine Updates verfügbar sind

Dry-Run Report (NotifyOnDryRun)

Im Dry-Run-Modus (DryRun = true) werden verfügbare Updates nur gemeldet, aber nicht installiert.

• Priorität: default
• Subject: Dry-Run Report - <Hostname>
• Inhalt: Liste aller verfügbaren Updates mit KB-Nummer, Titel und Größe

Update-Zusammenfassung (NotifyOnUpdateComplete)

Nach Abschluss der Update-Installation wird eine Zusammenfassung aller Ergebnisse gesendet. Die Priorität richtet sich danach, ob Fehler aufgetreten sind.

• Priorität: default (alle erfolgreich) oder high (mindestens ein Fehler)
• Subject: Updates OK - <Hostname> oder Updates (with errors) - <Hostname>
• Inhalt: Hostname, Betriebssystem, Anzahl erfolgreicher/fehlgeschlagener Updates, Detail-Liste aller Updates. Per E-Mail optional als HTML-Report mit farbcodierter Tabelle (EmailHtmlReport = true). Per Teams als Adaptive Card mit Status-Icons.

Neustart wird ausgeführt (NotifyOnReboot)

Nach der Update-Installation ist ein Neustart erforderlich und [Reboot] Enabled = true. Je nach konfiguriertem Modus wird der Neustart sofort, verzögert oder zu einer festen Uhrzeit eingeleitet.

• Priorität: high
• Subject: Reboot - <Hostname> (immediate) / Reboot in X min - <Hostname> (delayed) / Reboot scheduled at HH:MM - <Hostname> (scheduled)
• Inhalt: Information über den Neustart-Zeitpunkt, inklusive Update-Details

Neustart erforderlich (NotifyOnRebootRequired)

Ein Neustart ist nach der Update-Installation nötig, aber der automatische Neustart ist deaktiviert ([Reboot] Enabled = false). Ein manueller Neustart ist erforderlich.

• Priorität: high
• Subject: Reboot Required - <Hostname>
• Inhalt: Hinweis, dass ein manueller Neustart durchgeführt werden muss

Dienst-Neustart fehlgeschlagen (NotifyOnServiceRestartFailure)

Der Service-Watchdog konnte einen oder mehrere konfigurierte Dienste nach den Updates nicht starten. Der Watchdog wird nur ausgeführt, wenn kein Neustart erforderlich ist ([ServiceWatchdog] Enabled = true).

• Priorität: high
• Subject: Service Restart FAILED - <Hostname>
• Inhalt: Liste der betroffenen Dienste mit Fehlerbeschreibung (Dienst nicht gefunden, alle Versuche fehlgeschlagen)

Einzelne Ereignisse deaktivieren

In der Sektion [NotificationEvents] der config.ini kann jedes Ereignis individuell gesteuert werden. Beispiel — nur bei Fehlern und Reboot-Bedarf benachrichtigen:

[NotificationEvents]
NotifyOnModuleError = true
NotifyOnHookFailure = true
NotifyOnNoUpdates = false
NotifyOnDryRun = false
NotifyOnUpdateComplete = true
NotifyOnReboot = true
NotifyOnRebootRequired = true
NotifyOnServiceRestartFailure = true

Wird die Sektion [NotificationEvents] nicht angegeben oder ein Schlüssel weggelassen, ist das jeweilige Ereignis standardmäßig aktiviert (true).

Sicherheitshinweis

Die config.ini enthält möglicherweise Zugangsdaten (SMTP-Passwort, ntfy-Token). Stelle sicher, dass:

• Die Datei config.ini in .gitignore eingetragen ist (ist standardmäßig der Fall)
• Die Dateiberechtigungen auf dem Server eingeschränkt sind (nur Administratoren)
• Das SMTP-Passwort idealerweise ein App-spezifisches Passwort ist, nicht das Hauptpasswort