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
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user