Dateien nach "/" hochladen
This commit is contained in:
@@ -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
|
## Installation
|
||||||
SMTPGraphRelay-v1.5.0\
|
|
||||||
├── Setup-SMTPGraphRelay.ps1
|
|
||||||
├── SMTPGraphRelay.ps1
|
|
||||||
├── Test-SMTPGraphRelay.ps1
|
|
||||||
├── Renew-SMTPGraphRelayCertificate.ps1
|
|
||||||
└── version.json
|
|
||||||
```
|
|
||||||
|
|
||||||
## Warum
|
### Einfachste Variante
|
||||||
|
|
||||||
Der Manager kopiert bei Neuinstallation, Repair und Update immer die Dateien,
|
**Windows PowerShell 5.1 als Administrator** öffnen und diesen Befehl ausführen:
|
||||||
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:
|
|
||||||
|
|
||||||
```powershell
|
```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
|
```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
|
```text
|
||||||
Paketversion: 1.6.0
|
[1] Neuinstallation aus Gitea
|
||||||
Installierte Version: 1.5.0
|
[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
|
## Was die Neuinstallation automatisch erledigt
|
||||||
gesichert. `config.json`, Queue, Logs, Zertifikat, Entra-App und Exchange-RBAC
|
|
||||||
bleiben erhalten.
|
|
||||||
|
|
||||||
## 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:
|
Beispiel:
|
||||||
|
|
||||||
```json
|
```text
|
||||||
{
|
SMTPGraphRelay App
|
||||||
"Version": "1.5.0",
|
|
|
||||||
"Product": "SMTPGraphRelay",
|
| Application Mail.Send
|
||||||
"MinimumPowerShell": "5.1",
|
v
|
||||||
"ReleaseDate": "2026-08-13"
|
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
|
||||||
|
|||||||
Reference in New Issue
Block a user