Umbenennung ueber users.cfg statt Administration API
Der Test gegen einen echten Server (Kerio Connect 10.0.9 patch 2) hat gezeigt, dass Users.set das Feld loginName stillschweigend ignoriert - kein Fehler, keine Wirkung, waehrend fullName im selben Aufruf sauber uebernommen wird. Vier Varianten geprueft (nur loginName, mit domainId, mit leeren emailAddresses, vollstaendiges User-Objekt): alle wirkungslos. Der bisherige Ansatz konnte also gar nicht funktionieren. Der Login-Name steht in users.cfg, und zwar in zwei Listen: User und UserAdditionalData. Beide verweisen ueber Name+Domain statt ueber die Guid, beide muessen mit, sonst verliert der Benutzer seine Passworthistorie. Geaendert wird der Rohtext, damit Formatierung und unbekannte Felder unangetastet bleiben. users.cfg und Store-Verzeichnis wandern jetzt in EINEM Stopp-Fenster. Laeuft Kerio zwischendurch mit nur einer Haelfte, legt es die vermeintlich fehlende Mailbox sofort neu an - beim Entwickeln genau so passiert. Damit entfaellt auch der Admin-Zugang: das Script braucht keine Zugangsdaten mehr, --list zeigt die Benutzer aus der Datei. Ausserdem gefunden: itemSource heisst 'DSInternalSource', nicht 'Internal' wie angenommen - die alte Pruefung haette bei jedem lokalen Benutzer faelschlich abgebrochen. Die Erkennung laeuft jetzt ueber InternalDb in users.cfg. Tests fuer beide Haelften unter tests/. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
duffyduck
co-authored by
Claude Opus 5
Claude Opus 5
parent
b12041fc81
commit
5011491067
@@ -6,62 +6,75 @@ Werkzeuge für Kerio Connect auf der Kommandozeile.
|
||||
| --- | --- |
|
||||
| [`kerio_rename_user.py`](kerio_rename_user.py) | Benutzer umbenennen — Login-Name **und** Mailbox-Verzeichnis im Store |
|
||||
| [`kerio_trial_setup.py`](kerio_trial_setup.py) | Am Erstkonfigurationsassistenten vorbei, wenn dessen Lizenzschritt klemmt |
|
||||
| [`kerio_common.py`](kerio_common.py) | Gemeinsame Bausteine: API-Client, Dienststeuerung |
|
||||
| [`kerio_users_config.py`](kerio_users_config.py) | Lesen und Ändern von `users.cfg` |
|
||||
| [`kerio_common.py`](kerio_common.py) | Gemeinsame Bausteine: Admin-API-Client, Dienststeuerung |
|
||||
|
||||
Beide Scripts laufen **lokal auf dem Kerio-Server als root**, brauchen nur die
|
||||
Python-Standardbibliothek und bieten `--dry-run`.
|
||||
|
||||
Getestet gegen **Kerio Connect 10.0.9 patch 2** auf Debian 12.
|
||||
|
||||
---
|
||||
|
||||
# Benutzer umbenennen
|
||||
|
||||
## Warum
|
||||
## Warum das nicht trivial ist
|
||||
|
||||
Kerio Connect legt die Mailbox eines Benutzers unter
|
||||
Kerio hält den Benutzernamen an zwei Stellen, die nichts voneinander wissen:
|
||||
|
||||
```
|
||||
<store>/mail/<domain>/<loginname>/
|
||||
```
|
||||
| Wo | Was |
|
||||
| --- | --- |
|
||||
| `users.cfg` | Der Login-Name, in **zwei** Listen: `User` und `UserAdditionalData` |
|
||||
| Dateisystem | `<store>/mail/<domain>/<loginname>/` — die eigentliche Mailbox |
|
||||
|
||||
ab. Ändert man den Login-Namen über die Administration API oder die
|
||||
Admin-Konsole, zieht dieses Verzeichnis nicht mit — der Benutzer findet danach
|
||||
eine leere Mailbox vor, während die alten Daten unter dem alten Verzeichnisnamen
|
||||
liegenbleiben. Typischer Anlass: Heirat oder ein anderer Namenswechsel.
|
||||
Ändert man nur den Login-Namen, sucht Kerio ab sofort im Verzeichnis mit dem
|
||||
*neuen* Namen, findet keins, legt ein leeres an — und die alten Mails liegen
|
||||
weiter unter dem alten Verzeichnisnamen. Typischer Anlass für eine Umbenennung:
|
||||
Heirat oder ein anderer Namenswechsel.
|
||||
|
||||
Dieses Script erledigt beide Hälften in der richtigen Reihenfolge.
|
||||
## Warum nicht über die Administration API
|
||||
|
||||
## Voraussetzungen
|
||||
**Die API kann das nicht.** `Users.set` nimmt ein Feld `loginName` entgegen und
|
||||
ignoriert es stillschweigend — kein Fehler, keine Wirkung. Nachgeprüft gegen
|
||||
Kerio Connect 10.0.9 mit vier Varianten (nur `loginName`, mit `domainId`, mit
|
||||
leeren `emailAddresses`, vollständiges User-Objekt): alle wirkungslos, während
|
||||
`fullName` im selben Aufruf sauber übernommen wird.
|
||||
|
||||
- Python 3.9 oder neuer, nur Standardbibliothek — keine Pakete zu installieren
|
||||
- Läuft **lokal auf dem Kerio-Server als root** (Dateisystemzugriff + Dienstkontrolle)
|
||||
- Administration API erreichbar (Standard: `https://localhost:4040/admin/api/jsonrpc/`)
|
||||
Deshalb arbeitet das Script direkt auf `users.cfg` — und braucht dadurch
|
||||
**keine Admin-Zugangsdaten**.
|
||||
|
||||
## Ablauf
|
||||
|
||||
1. **Vorprüfungen**, bevor irgendetwas geschrieben wird:
|
||||
- Domain und Benutzer über die API auflösen
|
||||
- Benutzer aus einem Verzeichnisdienst (LDAP/AD)? → Abbruch, denn der Name
|
||||
gehört dann dem Verzeichnisdienst
|
||||
- neuer Login-Name noch frei?
|
||||
- Mailbox-Verzeichnis vorhanden, Zielname noch nicht belegt,
|
||||
Quelle und Ziel auf demselben Dateisystem?
|
||||
- ist der Dienst überhaupt steuerbar?
|
||||
- Domain und Benutzer in `users.cfg` vorhanden?
|
||||
- Benutzer aus einem Verzeichnisdienst (`InternalDb=0`)? → Abbruch, denn
|
||||
dann gehört der Name dem Verzeichnisdienst
|
||||
- neuer Login-Name frei und zeichenmäßig zulässig?
|
||||
- Zielverzeichnis unbelegt, Quelle und Ziel auf demselben Dateisystem?
|
||||
- Dienst steuerbar?
|
||||
2. Plan ausgeben. `--dry-run` endet hier, sonst Rückfrage (`--yes` überspringt).
|
||||
3. `Users.set` setzt `loginName` und optional `fullName`.
|
||||
4. Kerio-Dienst stoppen und warten, bis er wirklich unten ist.
|
||||
5. Verzeichnisse per `os.rename` verschieben (`mail/`, und `archive/` falls vorhanden).
|
||||
6. Dienst wieder starten.
|
||||
3. Dienst stoppen.
|
||||
4. `users.cfg` **neu einlesen**, Name in `User` und `UserAdditionalData` setzen,
|
||||
atomar über eine temporäre Datei speichern.
|
||||
5. Verzeichnisse verschieben (`mail/`, und `archive/` falls vorhanden).
|
||||
6. Dienst starten und gegenlesen.
|
||||
|
||||
Schlägt Schritt 5 fehl, werden bereits verschobene Verzeichnisse zurückgenommen
|
||||
und der Login-Name in Kerio auf den alten Wert zurückgesetzt — Konfiguration und
|
||||
Platte bleiben konsistent.
|
||||
**Schritte 4 und 5 liegen bewusst in einem einzigen Stopp-Fenster.** Das ist
|
||||
keine Bequemlichkeit: Läuft Kerio zwischendurch mit nur einer der beiden
|
||||
Hälften, legt es die vermeintlich fehlende Mailbox sofort neu an, und man hat
|
||||
ein verwaistes Verzeichnis mehr. Genau das ist beim Entwickeln passiert.
|
||||
|
||||
Schlägt etwas fehl, werden verschobene Verzeichnisse zurückgenommen und
|
||||
`users.cfg` aus dem Backup wiederhergestellt.
|
||||
|
||||
## Benutzung
|
||||
|
||||
```bash
|
||||
# Erst ansehen, was passieren würde (braucht kein root):
|
||||
# Wer ist da? (kein root nötig)
|
||||
./kerio_rename_user.py --list
|
||||
|
||||
# Erst ansehen:
|
||||
./kerio_rename_user.py \
|
||||
--admin admin \
|
||||
--domain firma.de \
|
||||
--old-login anna.mueller \
|
||||
--new-login anna.schmidt \
|
||||
@@ -69,22 +82,17 @@ Platte bleiben konsistent.
|
||||
--dry-run
|
||||
|
||||
# Dann wirklich:
|
||||
sudo -E ./kerio_rename_user.py \
|
||||
--admin admin \
|
||||
sudo ./kerio_rename_user.py \
|
||||
--domain firma.de \
|
||||
--old-login anna.mueller \
|
||||
--new-login anna.schmidt \
|
||||
--full-name "Anna Schmidt"
|
||||
```
|
||||
|
||||
Das Passwort kommt aus der Umgebungsvariablen `KERIO_ADMIN_PASSWORD` oder wird
|
||||
interaktiv abgefragt — nicht über die Kommandozeile, sonst landet es in der
|
||||
Shell-History. (`sudo -E` reicht die Variable durch.)
|
||||
|
||||
Nur den angezeigten Namen ändern, ohne Login und Verzeichnis anzufassen:
|
||||
|
||||
```bash
|
||||
./kerio_rename_user.py --admin admin --domain firma.de \
|
||||
sudo ./kerio_rename_user.py --domain firma.de \
|
||||
--old-login anna.mueller --full-name "Anna Schmidt"
|
||||
```
|
||||
|
||||
@@ -92,35 +100,50 @@ Nur den angezeigten Namen ändern, ohne Login und Verzeichnis anzufassen:
|
||||
|
||||
| Option | Bedeutung |
|
||||
| --- | --- |
|
||||
| `--server`, `--port` | Admin-API, Standard `localhost:4040` |
|
||||
| `--admin`, `--password` | Admin-Zugang; besser `KERIO_ADMIN_PASSWORD` |
|
||||
| `--list` | Benutzer aus `users.cfg` auflisten |
|
||||
| `--domain` | Mail-Domain, z. B. `firma.de` |
|
||||
| `--old-login`, `--new-login` | Login-Namen ohne `@domain` |
|
||||
| `--full-name` | Neuer angezeigter Name |
|
||||
| `--store-dir` | Store-Pfad, Standard `/opt/kerio/mailserver/store` |
|
||||
| `--install-dir` | Standard `/opt/kerio/mailserver` |
|
||||
| `--store-dir` | Standard `/opt/kerio/mailserver/store` |
|
||||
| `--service-name` | Dienstname, Standard `kerio-connect` |
|
||||
| `--service-manager` | `auto`, `systemd`, `initd` oder `none` |
|
||||
| `--service-wait` | Sekunden Wartezeit aufs Stoppen, Standard 90 |
|
||||
| `--dry-run` | Nur anzeigen |
|
||||
| `--yes` | Rückfrage überspringen |
|
||||
| `--force` | Auch bei LDAP-/AD-Benutzern versuchen |
|
||||
| `--insecure` | TLS-Zertifikat nicht prüfen (selbstsigniert) |
|
||||
| `--force` | Auch bei Benutzern aus einem Verzeichnisdienst |
|
||||
|
||||
`--service-manager none` fasst den Dienst nicht an — dafür muss Kerio dann
|
||||
selbst gestoppt sein, bevor das Script läuft.
|
||||
|
||||
## Was das Script bewusst nicht anfasst
|
||||
|
||||
Nach der Umbenennung steht der alte Name noch an ein paar Stellen, die reine
|
||||
Anzeige betreffen und den Mailbetrieb nicht stören:
|
||||
|
||||
- `.personal` — die vCard des Benutzers, enthält noch die alte Adresse
|
||||
- `#public/Contacts/` — der Eintrag in der globalen Adressliste
|
||||
- `.caldav.db` / `.carddav.db` — die DAV-Datenbanken
|
||||
|
||||
Kerio schreibt `.personal` beim Start teilweise selbst neu. Wer die Adresse dort
|
||||
sofort korrekt haben will, korrigiert den Kontakt in der Administrationskonsole.
|
||||
|
||||
Kommt der alte Name in `users.cfg` außerhalb der Benutzerlisten vor (etwa in
|
||||
einem Alias), meldet das Script das im Plan und ändert es **nicht** automatisch —
|
||||
lieber ein Hinweis als eine kaputte Konfiguration.
|
||||
|
||||
Die alte Adresse nimmt nach der Umbenennung keine Mail mehr an. Wer das braucht,
|
||||
legt anschließend in der Administrationskonsole einen Alias an.
|
||||
|
||||
## Hinweise
|
||||
|
||||
- **Vorher ein Backup des Stores anlegen.** Das Script verschiebt Verzeichnisse.
|
||||
- Erst an einem Testbenutzer ausprobieren.
|
||||
- Der Benutzer sollte während des Laufs nicht angemeldet sein.
|
||||
- Nach der Umbenennung müssen sich alle Mail-Clients des Benutzers mit dem neuen
|
||||
Login neu anmelden.
|
||||
- Die alte Adresse wird bewusst **nicht** als Alias angelegt. Wer möchte, dass
|
||||
Mail an die alte Adresse weiterhin ankommt, legt den Alias anschließend in der
|
||||
Admin-Konsole an.
|
||||
- Weitere Adressen am Benutzer (`emailAddresses`) bleiben unverändert und werden
|
||||
im Plan zur Kontrolle mit angezeigt.
|
||||
- Nach der Umbenennung müssen sich alle Mail-Clients mit dem neuen Login neu
|
||||
anmelden.
|
||||
- Gruppenmitgliedschaften bleiben erhalten: Kerio referenziert Gruppen über
|
||||
GUIDs, nicht über Namen.
|
||||
|
||||
---
|
||||
|
||||
@@ -135,13 +158,22 @@ verlinkte Registrierungsseite ist seit der Übernahme durch GFI teilweise tot
|
||||
man kommt im Assistenten nicht weiter.
|
||||
|
||||
Kerio kennt dafür den Schalter `ConfigWizardDone` in `mailserver.cfg`. Steht er
|
||||
auf `1`, öffnet die Administrationskonsole den Assistenten nicht mehr und der
|
||||
Server läuft 30 Tage ab Installation im unregistrierten Modus.
|
||||
auf `1`, öffnet die Administrationskonsole den Assistenten nicht mehr.
|
||||
|
||||
Im unregistrierten Modus fehlen Antivirus-Updates, ActiveSync, Greylisting und
|
||||
Hersteller-Support; nach 30 Tagen stoppt die Engine. **Benutzerverwaltung,
|
||||
Administrationskonsole und Admin-API sind nicht eingeschränkt** — für einen
|
||||
Testserver also unproblematisch.
|
||||
## Was das bringt — und was nicht
|
||||
|
||||
Danach sind **Administrationskonsole und Admin-API voll nutzbar**, und dieses
|
||||
Repo lässt sich damit testen.
|
||||
|
||||
**Der Mailbetrieb bleibt aber gesperrt.** Ohne Lizenzschlüssel weisen IMAP, POP3
|
||||
und Webmail jede Verbindung ab (`Server license expired` beim Client,
|
||||
`Product name does not match` im Log), und `error.log` meldet beim Start
|
||||
`No license key found`. Der Schalter überspringt nur den Dialog — er aktiviert
|
||||
keinen Testzeitraum.
|
||||
|
||||
Für echten Mailbetrieb führt kein Weg an einer Trial-Lizenznummer vorbei:
|
||||
**Dashboard → „Become a registered trial user"**, oder auf der GFI-Downloadseite
|
||||
„Try free for 30 days". Braucht ausgehendes HTTPS auf Port 443.
|
||||
|
||||
## Benutzung
|
||||
|
||||
@@ -151,33 +183,19 @@ sudo ./kerio_trial_setup.py --skip-wizard # Assistenten überspringen
|
||||
sudo ./kerio_trial_setup.py --restore # Backup zurückspielen
|
||||
```
|
||||
|
||||
`--status` zeigt Dienstzustand, `ConfigWizardDone`, `TrialID`, vorhandene
|
||||
Lizenzdateien und eine Schätzung, wann der Testzeitraum abläuft.
|
||||
|
||||
## Der springende Punkt
|
||||
|
||||
`mailserver.cfg` darf **nur bei gestopptem Dienst** bearbeitet werden. Kerio
|
||||
schreibt seine Konfiguration beim Beenden aus dem Speicher zurück und würde eine
|
||||
Änderung am laufenden Dienst wieder überschreiben. Das Script stoppt deshalb den
|
||||
Dienst, liest die Datei **danach neu ein** (die Version von vorher ist zu diesem
|
||||
Zeitpunkt bereits veraltet), schreibt atomar über eine temporäre Datei im selben
|
||||
Verzeichnis, startet den Dienst und liest den Wert zur Kontrolle noch einmal.
|
||||
|
||||
Vor jeder Änderung wird ein Backup als `mailserver.cfg.bak-trial-setup` angelegt.
|
||||
|
||||
## Falls du doch eine registrierte Trial willst
|
||||
|
||||
Geht aus der laufenden Instanz heraus, ohne Installer: **Dashboard → „Become a
|
||||
registered trial user"**. Braucht ausgehendes HTTPS auf Port 443 zum
|
||||
GFI-Registrierungsserver.
|
||||
Änderung am laufenden Dienst wieder überschreiben. Das gilt für `users.cfg`
|
||||
genauso — beide Scripts halten sich daran.
|
||||
|
||||
---
|
||||
|
||||
## API- und Doku-Referenz
|
||||
## Referenzen
|
||||
|
||||
- [Administration API for Kerio Connect — Users](https://manuals.gfi.com/en/kerio/api/connect/admin/reference/interfacekerio_1_1jsonapi_1_1admin_1_1_users.html)
|
||||
- [Administration API — Users](https://manuals.gfi.com/en/kerio/api/connect/admin/reference/interfacekerio_1_1jsonapi_1_1admin_1_1_users.html)
|
||||
- [Sample communication (Session.login, X-Token)](https://manuals.gfi.com/en/kerio/api/connect/admin/reference/sample_communication.html)
|
||||
- [User struct](https://manuals.gfi.com/en/kerio/api/connect/admin/reference/structkerio_1_1jsonapi_1_1admin_1_1_user.html)
|
||||
- [Registering Kerio Connect (unregistered mode)](https://manuals.gfi.com/en/kerio/connect/content/registration-and-licenses/registering-kerio-connect-1134.html)
|
||||
- [Initial Wizard Settings Are Not Saving (ConfigWizardDone)](https://support.kerioconnect.gfi.com/article/114858-initial-wizard-settings-are-not-saving-in-kerio-connect)
|
||||
- [Modifying the mailserver.cfg](https://support.kerioconnect.gfi.com/en-us/article/114788-modifying-the-mailserver-cfg)
|
||||
|
||||
Reference in New Issue
Block a user