kerio-connect-rename-user/README.md

# kerio-connect-rename-user

Werkzeuge für Kerio Connect auf der Kommandozeile.

| Datei | Zweck |
| --- | --- |
| [`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 |

Beide Scripts laufen **lokal auf dem Kerio-Server als root**, brauchen nur die
Python-Standardbibliothek und bieten `--dry-run`.

---

# Benutzer umbenennen

## Warum

Kerio Connect legt die Mailbox eines Benutzers unter

```
<store>/mail/<domain>/<loginname>/
```

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.

Dieses Script erledigt beide Hälften in der richtigen Reihenfolge.

## Voraussetzungen

- 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/`)

## 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?
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.

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.

## Benutzung

```bash
# Erst ansehen, was passieren würde (braucht kein root):
./kerio_rename_user.py \
    --admin admin \
    --domain firma.de \
    --old-login anna.mueller \
    --new-login anna.schmidt \
    --full-name "Anna Schmidt" \
    --dry-run

# Dann wirklich:
sudo -E ./kerio_rename_user.py \
    --admin admin \
    --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 \
    --old-login anna.mueller --full-name "Anna Schmidt"
```

## Optionen

| Option | Bedeutung |
| --- | --- |
| `--server`, `--port` | Admin-API, Standard `localhost:4040` |
| `--admin`, `--password` | Admin-Zugang; besser `KERIO_ADMIN_PASSWORD` |
| `--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` |
| `--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) |

`--service-manager none` fasst den Dienst nicht an — dafür muss Kerio dann
selbst gestoppt sein, bevor das Script läuft.

## 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.

---

# Erstkonfigurationsassistent überspringen

## Warum

Der Assistent verlangt im Schritt „Registrierte Testaktivierung" eine
Testlizenznummer samt CAPTCHA. Der dokumentierte Link „Im unregistrierten Modus
aktivieren" fehlt je nach Version oder ist im Fenster abgeschnitten, und die
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.

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.

## Benutzung

```bash
./kerio_trial_setup.py --status              # Zustand anzeigen (kein root nötig)
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.

---

## API- und Doku-Referenz

- [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)
- [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)