diff --git a/README.md b/README.md index e06e8b1..e851795 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,324 @@ -# SMTPGraphRelay 1.5.0 +# SMTPGraphRelay -Ab dieser Version gibt es **keinen `payload`-Ordner mehr**. +Lokaler SMTP Store-and-Forward Relay für Windows mit Versand über Microsoft 365 / Microsoft Graph. -Alle Release-Dateien liegen genau einmal nebeneinander: +SMTPGraphRelay nimmt klassische lokale SMTP-Mails von Druckern, Scannern, NAS, +Servern, Monitoring-Systemen usw. entgegen und leitet sie per OAuth / Microsoft Graph +an Microsoft 365 weiter. -```text -SMTPGraphRelay-v1.5.0\ -├── Setup-SMTPGraphRelay.ps1 -├── SMTPGraphRelay.ps1 -├── Test-SMTPGraphRelay.ps1 -├── Renew-SMTPGraphRelayCertificate.ps1 -└── version.json -``` +## Installation -## Warum +### Einfachste Variante -Der Manager kopiert bei Neuinstallation, Repair und Update immer die Dateien, -die direkt neben `Setup-SMTPGraphRelay.ps1` liegen. - -Dadurch gibt es keine zweite Kopie von `SMTPGraphRelay.ps1`, die bei neuen -Versionen versehentlich veraltet bleiben könnte. - -## Update - -Ein neues Release wird künftig einfach als neuer Ordner/ZIP gebaut: - -```text -SMTPGraphRelay-v1.6.0.zip -``` - -Darin liegen jeweils genau die aktuellen Dateien. - -Dann: +**Windows PowerShell 5.1 als Administrator** öffnen und diesen Befehl ausführen: ```powershell -.\Setup-SMTPGraphRelay.ps1 +$u='https://me-gitea.maieredv.cloud/MAIEREDV/SMTPGraphRelay/raw/branch/main/Setup-SMTPGraphRelay.ps1';$f="$env:TEMP\Setup-SMTPGraphRelay.ps1";Invoke-WebRequest $u -UseBasicParsing -OutFile $f;& $f ``` -und Menüpunkt: +Danach erscheint das SMTPGraphRelay-Verwaltungsmenü. + +Der Installer lädt automatisch den aktuellen Stand aus dem Gitea-Repository und +installiert SMTPGraphRelay nach: ```text -[3] Relay aktualisieren +C:\Program Files\SMTPGraphRelay ``` -Der Manager liest `version.json` und zeigt: +Es muss kein ZIP manuell heruntergeladen oder entpackt werden. + +## Installer / Manager ```text -Paketversion: 1.6.0 -Installierte Version: 1.5.0 +[1] Neuinstallation aus Gitea +[2] Installation aus Gitea reparieren +[3] Nach Online-Updates suchen +[4] Entra / Exchange RBAC prüfen +[5] Zertifikat erneuern +[6] Health Check ausführen +[7] Deinstallieren +[8] Status anzeigen +[0] Beenden ``` -Beim Update wird die vorhandene `SMTPGraphRelay.ps1` weiterhin mit Zeitstempel -gesichert. `config.json`, Queue, Logs, Zertifikat, Entra-App und Exchange-RBAC -bleiben erhalten. +## Was die Neuinstallation automatisch erledigt -## version.json +- prüft Windows PowerShell 5.1 +- installiert benötigte PowerShell-Module systemweit +- lädt die aktuellen Programmdateien aus Gitea +- installiert nach `C:\Program Files\SMTPGraphRelay` +- erzeugt ein nicht exportierbares Zertifikat in `LocalMachine\My` +- erstellt die Entra ID App Registration +- erstellt den Entra Service Principal +- vergibt **keine globale Graph `Mail.Send` Application Permission** +- richtet Exchange Online Application RBAC ein +- begrenzt `Application Mail.Send` auf das konfigurierte Absenderpostfach +- erzeugt `config.json` +- legt Queue-, Failed- und Log-Verzeichnisse an +- erstellt die Windows-Firewallregel +- erstellt den Scheduled Task unter `SYSTEM` +- startet SMTPGraphRelay +- führt abschließend den Health Check aus + +## Architektur + +```text +Drucker / Scanner / NAS / Server / Monitoring + | + | SMTP + v + SMTPGraphRelay + | + | Queue / Retry + v + Microsoft Graph + | + | OAuth2 App-only + v + Microsoft 365 +``` + +## SMTP-Funktionen + +- `EHLO` / `HELO` +- `MAIL FROM` +- mehrere `RCPT TO` +- `DATA` +- `RSET` +- `NOOP` +- `QUIT` +- IPv4-Netzwerk-Allowlist +- maximale Nachrichtengröße +- bis zu 20 parallele SMTP-Verbindungen standardmäßig +- konfigurierbares Parallel-Limit +- `421 Service busy` bei erreichtem Parallel-Limit + +## Store-and-Forward Queue + +```text +queue\ +├── incoming\ +├── pending\ +└── processing\ + +failed\ +``` + +- Nachrichten werden zunächst atomar unter `incoming` geschrieben. +- Erst vollständig geschriebene Nachrichten werden unter `pending` sichtbar. +- Während des Graph-Versands liegen Nachrichten unter `processing`. +- Nach einem Absturz werden verbliebene Processing-Nachrichten wieder nach Pending gestellt. +- Permanent fehlgeschlagene Nachrichten landen unter `failed`. + +## Retry-Verhalten + +- HTTP `429`: Microsoft `Retry-After` wird berücksichtigt +- ohne `Retry-After`: exponentielles Backoff +- HTTP `408` und `5xx`: Retry +- DNS-, TLS-, Timeout- und Netzwerkfehler: Retry +- typische permanente `4xx`: direkt nach `failed` +- nach `MaxRetries`: nach `failed` + +## Microsoft 365 / Security + +Der Relay verwendet: + +```text +Microsoft Graph +Application Mail.Send +``` + +über **Exchange Online Application RBAC**. + +Die Berechtigung wird auf das beim Setup angegebene Absenderpostfach beschränkt. Beispiel: -```json -{ - "Version": "1.5.0", - "Product": "SMTPGraphRelay", - "MinimumPowerShell": "5.1", - "ReleaseDate": "2026-08-13" -} +```text +SMTPGraphRelay App + | + | Application Mail.Send + v +info@example.com ``` -Die Datei wird mit installiert und dient dem Manager als Versionsmarker. +Die App erhält bewusst **keine zusätzliche tenantweite Graph `Mail.Send` +Application Permission**, da diese das Exchange-RBAC-Scoping umgehen würde. + +Der lokale Relay erzwingt außerdem standardmäßig: + +```json +"ForceSender": true +``` + +und verwendet ausschließlich `Graph.SenderMailbox` als Graph-Absender. + +## Zertifikatsauthentifizierung + +SMTPGraphRelay verwendet kein Client Secret. + +Das Setup erzeugt ein RSA-Zertifikat unter: + +```text +Cert:\LocalMachine\My +``` + +Der private Schlüssel ist nicht exportierbar. + +Das Relay prüft regelmäßig die Restlaufzeit des Zertifikats. + +Standard: + +```text +Warnung: 60 Tage +Kritisch: 14 Tage +Prüfung: alle 12 Stunden +``` + +Zur Rotation: + +```powershell +.\Renew-SMTPGraphRelayCertificate.ps1 +``` + +Die Rotation erfolgt mit Überlappung: + +```text +OLD + ↓ +NEW erzeugen + ↓ +OLD + NEW in Entra + ↓ +NEW testen + ↓ +Config auf NEW + ↓ +Relay neu starten + ↓ +OLD optional entfernen +``` + +## Log-Rotation + +Standard: + +```text +MaxFileSizeMB = 10 +RetentionDays = 30 +CleanupHours = 12 +``` + +Aktives Log: + +```text +logs\SMTPGraphRelay.log +``` + +Archiv: + +```text +logs\SMTPGraphRelay-YYYYMMDD-HHMMSS.log +``` + +## Health Check + +```powershell +.\Test-SMTPGraphRelay.ps1 +``` + +Optional mit echter SMTP-Testmail: + +```powershell +.\Test-SMTPGraphRelay.ps1 ` + -SendTestMail ` + -TestRecipient "user@example.com" +``` + +Der Health Check prüft unter anderem: + +- PowerShell-Version +- Administratorstatus +- Config +- Graph-Modul +- Zertifikat und Private Key +- Zertifikatslaufzeit +- Queue und Schreibrechte +- Failed Queue +- Scheduled Task +- SMTP Listener +- Graph App-only Authentication + +Exitcodes: + +```text +0 = OK +1 = Warnung +2 = Fehler +``` + +## Online Update + +Im Manager: + +```text +[3] Nach Online-Updates suchen +``` + +Der Manager prüft: + +```text +https://me-gitea.maieredv.cloud/MAIEREDV/SMTPGraphRelay/raw/branch/main/version.json +``` + +und lädt bei Bedarf: + +```text +https://me-gitea.maieredv.cloud/MAIEREDV/SMTPGraphRelay/archive/main.zip +``` + +Vor dem Update wird ein Backup der verwalteten Programmdateien erstellt. + +Bei einem fehlgeschlagenen Health Check erfolgt automatisch ein Rollback. + +### Von Updates niemals überschrieben + +- `config.json` +- `queue\` +- `failed\` +- `logs\` +- `backup\` +- lokales Zertifikat +- Entra App Registration +- Exchange Application RBAC + +## Repair + +```text +[2] Installation aus Gitea reparieren +``` + +Repair lädt den aktuellen Programmstand neu aus dem Repository und repariert: + +- Programmdateien +- PowerShell-Module +- Verzeichnisstruktur +- Firewallregel +- Scheduled Task + +Cloud-Konfiguration, Zertifikat, Config, Queue und Logs bleiben erhalten. + +## Repository + +```text +https://me-gitea.maieredv.cloud/MAIEREDV/SMTPGraphRelay +``` + +## Systemvoraussetzungen + +- Windows 10 / 11 oder Windows Server +- Windows PowerShell 5.1 +- lokale Administratorrechte für Installation +- Internetzugang zu Microsoft Entra, Microsoft Graph, Exchange Online und dem Gitea-Repository +- Entra-/Exchange-Administratorkonto für die Ersteinrichtung +- Microsoft-365-/Exchange-Online-Postfach für den Relay-Absender