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_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 das nicht trivial ist

Kerio hält den Benutzernamen an zwei Stellen, die nichts voneinander wissen:

| Wo | Was |
| --- | --- |
| `users.cfg` | Der Login-Name, in **zwei** Listen: `User` und `UserAdditionalData` |
| Dateisystem | `<store>/mail/<domain>/<loginname>/` — die eigentliche Mailbox |

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

## Warum nicht über die Administration API

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

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

**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
# Wer ist da? (kein root nötig)
./kerio_rename_user.py --list

# Erst ansehen:
./kerio_rename_user.py \
    --domain firma.de \
    --old-login anna.mueller \
    --new-login anna.schmidt \
    --full-name "Anna Schmidt" \
    --dry-run

# Dann wirklich:
sudo ./kerio_rename_user.py \
    --domain firma.de \
    --old-login anna.mueller \
    --new-login anna.schmidt \
    --full-name "Anna Schmidt"
```

Nur den angezeigten Namen ändern, ohne Login und Verzeichnis anzufassen:

```bash
sudo ./kerio_rename_user.py --domain firma.de \
    --old-login anna.mueller --full-name "Anna Schmidt"
```

## Optionen

| Option | Bedeutung |
| --- | --- |
| `--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 |
| `--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 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 mit dem neuen Login neu
  anmelden.
- Gruppenmitgliedschaften bleiben erhalten: Kerio referenziert Gruppen über
  GUIDs, nicht über Namen.

---

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

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

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

## 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 gilt für `users.cfg`
genauso — beide Scripts halten sich daran.

---

## Referenzen

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