fix(kerio): korrekte Admin-API gemäß Delivery.idl + Pop3Account-Doku

- Methoden: Delivery.getPop3AccountList / addPop3AccountList /
  setPop3Account (vorher geraten als Pop3Accounts.set/.create →
  Method not found).
- Pop3Account-Felder mit den richtigen Namen: isActive (statt enabled),
  mode (statt sslMode), authentication (statt authType), und
  leaveOnServer.removeAfterPeriod als OptionalLong-Wrapper.
  Falsche Namen wurden von Kerio still ignoriert → Sammler war inaktiv.
- User-Struct: allowPasswordChange=false (statt mayChangePassword,
  das es nicht gibt). emailAddresses weggelassen, Kerio leitet die
  primäre Adresse aus loginName+domain ab.
- Kerio-Step in 2 Sub-Steps aufgeteilt: User (skip wenn vorhanden) +
  POP3 (upsert). Damit wird bei einem zweiten Lauf der Sammler nicht
  übersprungen, nur weil der User schon existiert.
- POP3-Sammler ist jetzt UPSERT: existierende werden via setPop3Account
  überschrieben → Selbstreparatur kaputter Einträge + Passwort-
  Änderungen aus der CSV ziehen sich von selbst nach.

GUI: 👁/🙈-Toggle pro Passwort-Feld (Klartext temporär einsehbar).

Filenames der Sammel-PDFs + Admin-Report ohne Zeitstempel –
erneuter Lauf überschreibt statt anzuhäufen.

README: Ablauf-Sektion + Idempotenz-Tabelle aktualisiert; Kerio-
Caveat ersetzt durch konkrete Methoden-/Feld-Liste mit Doku-Link.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-12 14:09:06 +02:00
parent 4711c55d89
commit 06d7e00e49
4 changed files with 235 additions and 86 deletions
+52 -33
View File
@@ -157,8 +157,10 @@ python deploy.py
Das Fenster startet maximiert. Jeder Account ist eine **Karte** mit zwei
Zeilen: oben die Person (Vorname, Name, Email) + Lösch-Button, unten drei
Service-Gruppen (Plesk / Kerio / Nextcloud) mit Host + Passwort. Passwort-
Felder sind maskiert. Die Karten sind mit `#1, #2, …` durchnummeriert,
Fehlermeldungen referenzieren diese Nummern.
Felder sind per Default maskiert (`•`); ein **👁-Toggle** neben jedem
Passwort schaltet temporär auf Klartext (🙈) und wieder zurück. Die Karten
sind mit `#1, #2, …` durchnummeriert, Fehlermeldungen referenzieren diese
Nummern.
Buttons in der Toolbar:
@@ -186,52 +188,66 @@ mit dem Pfad zur Sammel-PDF.
```
Plesk: Mailpostfach anlegen
- PLESK_BACKEND=manual → übersprungen (manuell in Plesk-GUI anlegen)
- PLESK_BACKEND=api/ssh → automatisch
- PLESK_BACKEND=api/ssh → automatisch via `plesk bin mail`
Kerio: User anlegen + POP3-Sammler eintragen, der vom Plesk-Host abholt
(Port aus POP3_PORT=995, SSL, 14 Tage auf Server belassen).
Kennwort-ändern ist für den User gesperrt (mayChangePassword=False).
Kerio User: anlegen oder überspringen wenn schon vorhanden.
Beim Anlegen wird `allowPasswordChange=false` gesetzt
(User darf sein Passwort nicht selbst ändern).
Kerio POP3-Sammler: UPSERT existierender wird via Delivery.setPop3Account
mit aktuellen Werten überschrieben, sonst neu via
Delivery.addPop3AccountList. So werden alte/kaputte Sammler
automatisch repariert und Passwort-Änderungen aus der CSV
ziehen sich beim nächsten Lauf von selbst nach.
(Port aus POP3_PORT=995, SSL Auto-Erkennung,
14 Tage auf Plesk belassen.)
Nextcloud: User vorname.nachname mit Gruppe + Quota anlegen
(übersprungen wenn vorhanden).
PDF (einzeln) schreiben
PDFs schreiben (Einzel + Sammel, voll + minimal) und Admin-Report.
```
Am Ende werden pro Lauf vier Dokument-Sorten geschrieben (alle in `output/`):
Am Ende werden pro Lauf folgende Dateien geschrieben (alle in `output/`,
**keine Zeitstempel** im Namen → erneuter Lauf überschreibt):
| Datei | Inhalt |
| ---------------------------------------------- | --------------------------------------------------------------------- |
| `zugangsdaten_<email>.pdf` | **Voll** pro Benutzer: Plesk-Mailpostfach + Kerio + Nextcloud |
| `zugangsdaten_minimal_<email>.pdf` | **Minimal** pro Benutzer: nur Email (Kerio) + Cloud (Nextcloud) |
| `zugangsdaten_gesamt_<ts>.pdf` | Sammel-PDF aller voller Datensätze |
| `zugangsdaten_gesamt_minimal_<ts>.pdf` | Sammel-PDF aller minimalen Datensätze |
| `_admin_report_<ts>.txt` | Status pro Konto (✓/·/⚠/✗). **NICHT für den Kunden** Admin-Doku. |
| Datei | Inhalt |
| -------------------------------------- | --------------------------------------------------------------------- |
| `zugangsdaten_<email>.pdf` | **Voll** pro Benutzer: Plesk-Mailpostfach + Kerio + Nextcloud |
| `zugangsdaten_minimal_<email>.pdf` | **Minimal** pro Benutzer: nur Email (Kerio) + Cloud (Nextcloud) |
| `zugangsdaten_gesamt.pdf` | Sammel-PDF aller voller Datensätze |
| `zugangsdaten_gesamt_minimal.pdf` | Sammel-PDF aller minimalen Datensätze |
| `_admin_report.txt` | Status pro Konto (✓/·/⚠/✗) inkl. Zeitstempel im Header. **NICHT für den Kunden** Admin-Doku. |
Die **Minimal-PDF** enthält genau das, was der Endkunde fürs Mailprogramm
und die Cloud-Anmeldung braucht (Mailadresse, Kennwort, SMTP, IMAP, Cloud-URL,
Cloud-Username, Cloud-Kennwort) ohne Backend-Details wie POP3-Sammler oder
Plesk-Mailserver.
### Idempotenz bestehende Konten werden übersprungen
### Idempotenz bestehende Konten werden übersprungen oder aktualisiert
Jeder Dienst wird **einzeln** geprüft, bevor angelegt wird:
Jeder Sub-Schritt wird **einzeln** geprüft. Im Admin-Report stehen die
Schritte separat (z.B. `Kerio User` und `Kerio POP3` als zwei Zeilen):
| Dienst | Prüfung | Wenn vorhanden |
| --------- | -------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Plesk | `mail --info` (api/ssh) bzw. ohnehin Manual-Modus | übersprungen |
| Kerio | `Users.get` mit `loginName` + `domainId` | übersprungen, **kein neuer POP3-Sammler** (sonst doppelt!) |
| Nextcloud | `GET /ocs/v2.php/cloud/users/<vorname.nachname>` | übersprungen, **keine Quota-/Gruppen-Änderung** |
| Sub-Schritt | Prüfung | Wenn vorhanden |
| ------------- | ------------------------------------------------------------- | ----------------------------------------------- |
| Plesk | `mail --info` (api/ssh) bzw. ohnehin Manual-Modus | übersprungen |
| Kerio User | `Users.get` mit `loginName` + `domainId` | übersprungen |
| Kerio POP3 | `Delivery.getPop3AccountList`, Match auf (deliveryAddress, server, userName) | **aktualisiert** via `Delivery.setPop3Account` (kein Skip! repariert kaputte Einträge + zieht CSV-Änderungen mit) |
| Nextcloud | `GET /ocs/v2.php/cloud/users/<vorname.nachname>` | übersprungen (keine Quota-/Gruppen-Änderung) |
→ Eine CSV kann gefahrlos zwei- oder dreimal durchgejagt werden, z.B. wenn
beim ersten Lauf nur Plesk geklappt hat und du Kerio + Nextcloud nachziehen
willst. Status pro Konto und Dienst steht im Admin-Report als
`✓ angelegt` / `· übersprungen` / `⚠ manuell` / `✗ Fehler`.
→ Eine CSV kann gefahrlos mehrfach laufen. Statuswerte:
`✓ angelegt` / `✓ aktualisiert` / `· übersprungen` / `⚠ manuell` / `✗ Fehler`.
**Caveats**:
- Kerio prüft `loginName` *in der zur Mailadresse passenden Domain* Aliase
auf einer anderen Domain werden nicht erkannt.
- Kerio-User-Prüfung matcht `loginName` *in der zur Mailadresse passenden
Domain* Aliase auf einer anderen Domain werden nicht erkannt.
- Nextcloud prüft den abgeleiteten Username `vorname.nachname` existiert
derselbe Mensch dort unter abweichendem Username, wird das nicht gefunden.
- Kerio-POP3 wird absichtlich aktualisiert statt übersprungen: ohne diese
Selbstreparatur bliebe ein einmal kaputt angelegter Sammler dauerhaft
defekt. Nebeneffekt: ein in der Kerio-Webadmin manuell verstellter
Sammler wird beim nächsten Tool-Lauf wieder auf die CSV-Werte gezogen.
## Workflow bei `PLESK_BACKEND=manual` (Shared Host)
@@ -248,11 +264,14 @@ willst. Status pro Konto und Dienst steht im Admin-Report als
## Hinweise / Caveats
- **Kerio API-Methoden**: die JSON-RPC-Methodennamen für POP3-Sammler
(`Pop3Accounts.create`) entsprechen Kerio Connect 9.x. Falls deine
Version andere Methoden nutzt, ist die Originalmeldung von Kerio in
der Fehlerausgabe (mit Methodenname) sichtbar dann in
[`clients/kerio.py`](clients/kerio.py) anpassen.
- **Kerio API-Methoden** entsprechen der offiziellen Kerio-Connect-Doku
(Delivery.idl + User-Struct, siehe [Kerio Admin API Reference](https://manuals.gfi.com/en/kerio/api/connect/admin/reference/jsonrpc_specification.html)).
Konkret verwendet: `Session.login`, `Domains.get`, `Users.get`,
`Users.create`, `Delivery.getPop3AccountList`,
`Delivery.addPop3AccountList`, `Delivery.setPop3Account`. Pop3Account-
Felder: `isActive`, `server`, `port`, `mode` (NoSsl/SpecialPort/StlsCommand),
`authentication` (PlainPop3/Apop), `userName`, `password`,
`deliveryAddress`, `leaveOnServer{enabled, removeAfterPeriod{enabled,value}}`.
- **Plesk REST-CLI-Wrapper**: nutzt `/api/v2/cli/mail/call` (entspricht
`plesk bin mail`). Verfügbar ab Plesk Obsidian.
- **Nextcloud OCS**: die Admin-Credentials brauchen das Recht „Benutzer