# Mail-Server-Verwaltung (Mailcow)

## Übersicht

Diese Kategorie umfasst 13 spezialisierte Playbooks zur Verwaltung von Mailcow-basierten Mail-Servern. Mailcow ist eine containerisierte, Docker-basierte Mail-Server-Lösung.

**Anwendungsfälle**:
- Mailcow-Updates und -Upgrades
- Start/Stop von Mail-Services
- Konfigurationsänderungen (SNI, Garbage Collector, Watchdog)
- Migration zu zentralen Services (ClamAV, Syslog)
- Health-Checks und Monitoring
- Docker-Proxy-Konfiguration
- Roundcube-Installation-Verwaltung
- Mailbox-Zählung

**Standard-Installationspfad**: `/opt/mailcow-dockerized`

---

## Playbooks

### update-mailcow.yaml

Umfassende Mailcow-Update mit Snapshots, Versionsvergleich, Health-Checks und automatischem Cleanup.

**Datei**: `playbooks/managed-mailcow/update-mailcow.yaml`

**Zweck**: Vollautomatisches Mailcow-Update mit Pre-Checks, Snapshot-Erstellung, Versions-Management und Post-Update-Cleanup.

**Ziel-Hosts**: `all`

**Benutzer**: `tincadmin` (mit sudo-Rechten)

**Verwendete Rollen**:
- `managed-mailcow` (find-mailcow-composedir, check-mailcow-install-status, get-mailcow-current-version, update-mailcow)
- `system` (check-disk-utilization)
- `proxmox-automation` (get-vmid, create-snapshots) - optional
- `docker` (cleanup-all)

**Wichtige Variablen**:

| Variable | Default | Beschreibung |
|----------|---------|-------------|
| `github_mailcow_ver` | `"2026-03b"` | Ziel-Mailcow-Version |
| `do_snapshots` | `true` | Erstellt Proxmox-Snapshots |
| `debug` | `true` | Debug-Ausgaben aktivieren |
| `load_vault` | `true` | Vault-Datei laden |
| `snapshot_name` | `"pre-mailcow-update-{{ github_mailcow_ver }}"` | Snapshot-Name |

**Verwendungsbeispiel**:

```bash
# Vollständiges Update mit Snapshots
ansible-playbook playbooks/managed-mailcow/update-mailcow.yaml \
  -i inventories/extern.yml \
  -e "github_mailcow_ver=2026-04" \
  -K --ask-vault-pass

# Ohne Snapshots (nicht empfohlen)
ansible-playbook playbooks/managed-mailcow/update-mailcow.yaml \
  -i inventories/extern.yml \
  -e "do_snapshots=false" \
  -K

# Einzelner Mail-Server
ansible-playbook playbooks/managed-mailcow/update-mailcow.yaml \
  -i inventories/extern.yml \
  --limit mail.example.com \
  -e "github_mailcow_ver=2026-04" \
  -K --ask-vault-pass
```

**Abhängigkeiten**:
- Vault-Datei (`vault.yml`) für Proxmox-Integration
- Ausreichend Festplattenspeicher (mindestens 4 GB frei)
- Proxmox-Umgebung (optional, für Snapshots)
- Mailcow-Installation

**Besonderheiten**:
- **Komplexeste Logik** aller Playbooks:
  - Vergleicht GitHub-Version mit lokaler Version
  - Erstellt Snapshot nur bei signifikanter Versions-Differenz
  - Disk-Space-Check vor Update (mindestens 4 GB erforderlich)
  - Automatisches Cleanup nach erfolgreichem Update
  - Pre-Tasks für Vault-Laden
- **Intelligente Version-Prüfung**: Überspringt Update wenn bereits aktuell
- **Rollback-fähig**: Durch Proxmox-Snapshots

**Workflow**:
1. Pre-Task: Lädt Vault-Datei (wenn `load_vault=true`)
2. Findet Mailcow-Compose-Directory
3. Prüft Mailcow-Installationsstatus
4. Prüft Festplattenspeicher (mindestens 4 GB)
5. Ermittelt aktuelle Mailcow-Version
6. Vergleicht mit Ziel-Version
7. Überspringt Update wenn bereits aktuell
8. Abruft Proxmox VM-ID (wenn Snapshots aktiviert)
9. Erstellt Pre-Update-Snapshot
10. Führt Mailcow-Update durch (Git-Pull + Update-Script)
11. Wartet auf Abschluss
12. Führt Docker-Cleanup durch
13. Verifiziert neue Version

**⚠️ Wichtig**: Dieses Playbook kann lange laufen (10-30 Minuten je nach System). Planen Sie Wartungsfenster.

---

### start-stop-mailcow.yaml

Start/Stop der kompletten Mailcow-Docker-Compose-Stack.

**Datei**: `playbooks/managed-mailcow/start-stop-mailcow.yaml`

**Zweck**: Kontrolliertes Herunterfahren und Hochfahren der gesamten Mailcow-Umgebung.

**Ziel-Hosts**: `all`

**Benutzer**: `tincadmin` (mit sudo-Rechten)

**Verwendete Rollen**:
- `managed-mailcow` (find-mailcow-composedir, stop-mailcow, start-mailcow)

**Wichtige Variablen**:

| Variable | Default | Beschreibung |
|----------|---------|-------------|
| `verbose` | `true` | Zeigt Docker-Compose-Output |

**Verwendungsbeispiel**:

```bash
# Stop und Start aller Mailcow-Services
ansible-playbook playbooks/managed-mailcow/start-stop-mailcow.yaml \
  -i inventories/extern.yml \
  -K

# Ohne Debug-Output
ansible-playbook playbooks/managed-mailcow/start-stop-mailcow.yaml \
  -i inventories/extern.yml \
  -e "verbose=false" \
  -K

# Nur ein Server
ansible-playbook playbooks/managed-mailcow/start-stop-mailcow.yaml \
  -i inventories/extern.yml \
  --limit mail-01.example.com \
  -K
```

**Abhängigkeiten**:
- Mailcow-Installation
- Docker und Docker-Compose

**Besonderheiten**:
- **Sequenzielle Ausführung**: Stop → Start
- **Sauberes Herunterfahren**: Verwendet `docker-compose down` (nicht `kill`)
- **Wartezeit**: Zwischen Stop und Start für vollständiges Shutdown
- **Verbose-Output**: Zeigt alle Docker-Logs wenn aktiviert

**Workflow**:
1. Findet Mailcow-Directory
2. Stoppt alle Container mit `docker-compose down`
3. Wartet auf vollständiges Shutdown
4. Startet alle Container mit `docker-compose up -d`
5. Wartet auf Verfügbarkeit der Services

**Anwendungsfälle**:
- Wartungsarbeiten
- Konfigurationsänderungen die Neustart erfordern
- Problembehebung
- Host-Neustarts vorbereiten

---

### check-mailcow-health.yml

Health-Checks von Mailcow-Instanzen (UI, SMTP, IMAP, Submission).

**Datei**: `playbooks/managed-mailcow/check-mailcow-health.yml`

**Zweck**: Überwachung der Erreichbarkeit und Funktionalität von Mailcow-Services von extern.

**Ziel-Hosts**: `localhost`

**Benutzer**: Lokal (keine Remote-Ausführung)

**Verwendete Rollen**: Keine (direkte Tasks)

**Wichtige Variablen**:

| Variable | Beispielwert | Beschreibung |
|----------|--------------|-------------|
| `hosts` | `["mail.ps.develcow.de", "mail.np.develcow.de"]` | Liste zu testender Mail-Server |

**Verwendungsbeispiel**:

```bash
# Health-Check auf definierten Hosts
ansible-playbook playbooks/managed-mailcow/check-mailcow-health.yml

# Mit custom Hosts
ansible-playbook playbooks/managed-mailcow/check-mailcow-health.yml \
  -e '{"hosts": ["mail.example.com", "mail2.example.com"]}'

# Mit Verbose-Output
ansible-playbook playbooks/managed-mailcow/check-mailcow-health.yml -v
```

**Abhängigkeiten**:
- Externe Erreichbarkeit der Mail-Server
- Ports: 25, 587, 143, 993, 443

**Besonderheiten**:
- **Testet Weboberfläche**: Sucht nach "showVersionModal" im HTML
- **Testet Mail-Ports**:
  - SMTP (Port 25)
  - Submission (Port 587)
  - IMAP (Port 143)
  - IMAPS (Port 993)
- **`ignore_errors: yes`** auf allen Tests - keine Unterbrechung bei Fehlern
- **Keine Timeouts als Fehler** gewertet

**Workflow**:
1. Iteriert über Host-Liste
2. Für jeden Host:
   - HTTP-Request zur Weboberfläche (Port 443)
   - TCP-Verbindungstest zu SMTP (25)
   - TCP-Verbindungstest zu Submission (587)
   - TCP-Verbindungstest zu IMAP (143)
   - TCP-Verbindungstest zu IMAPS (993)
3. Sammelt Ergebnisse
4. Zeigt Zusammenfassung

**Ausgabe-Beispiel**:
```
TASK [Test Webinterface] ****
ok: [localhost] => (item=mail.example.com)

TASK [Test SMTP Port] ****
ok: [localhost] => (item=mail.example.com)
```

---

### count-mailboxes.yml

Zählung aktiver Mailboxen über die Mailcow-Datenbank.

**Datei**: `playbooks/managed-mailcow/count-mailboxes.yml`

**Zweck**: Ermittelt die Anzahl aktiver Mailboxen auf allen Mailcow-Servern zur Lizenzierung oder Reporting.

**Ziel-Hosts**: `all` (mit Aggregation)

**Benutzer**: `tincadmin` (mit sudo-Rechten)

**Verwendete Rollen**:
- `managed-mailcow` (find-mailcow-composedir)

**Wichtige Variablen**:
- `DBROOT` - Wird automatisch aus `mailcow.conf` extrahiert

**Verwendungsbeispiel**:

```bash
# Zähle Mailboxen auf allen Servern
ansible-playbook playbooks/managed-mailcow/count-mailboxes.yml \
  -i inventories/extern.yml \
  -K

# Nur ein Server
ansible-playbook playbooks/managed-mailcow/count-mailboxes.yml \
  -i inventories/extern.yml \
  --limit mail-01.example.com \
  -K
```

**Abhängigkeiten**:
- Mailcow-Installation
- MySQL-Container muss laufen
- Zugriff auf `mailcow.conf` für DB-Root-Passwort

**Besonderheiten**:
- **Liest DBROOT-Passwort** aus `mailcow.conf`
- **Nutzt `docker compose exec`** für DB-Abfrage
- **Aggregiert Ergebnisse** über alle Hosts (verwendet `run_once: true`)
- **SQL-Query**: `SELECT COUNT(*) FROM mailbox WHERE active = 1`

**Workflow**:
1. Findet Mailcow-Directory auf jedem Host
2. Extrahiert DB-Root-Passwort aus `mailcow.conf`
3. Führt SQL-Query in MySQL-Container aus
4. Sammelt Mailbox-Counts von allen Hosts
5. Zeigt Aggregierte Summe

**Ausgabe-Beispiel**:
```
TASK [Show mailbox counts] ****
ok: [mail-01.example.com] => {
    "msg": "mail-01.example.com: 245 active mailboxes"
}
ok: [mail-02.example.com] => {
    "msg": "mail-02.example.com: 189 active mailboxes"
}

Total: 434 active mailboxes
```

---

### enable-sni-globally.yml

Globale Aktivierung von SNI (Server Name Indication) in Mailcow.

**Datei**: `playbooks/managed-mailcow/enable-sni-globally.yml`

**Zweck**: Aktiviert SNI-Support für Multi-Domain-SSL-Zertifikate in Mailcow.

**Ziel-Hosts**: `all`

**Benutzer**: `tincadmin` (mit sudo-Rechten)

**Verwendete Rollen**:
- `managed-mailcow` (find-mailcow-composedir, start-mailcow)

**Wichtige Variablen**:

| Variable | Default | Beschreibung |
|----------|---------|-------------|
| `debug` | `false` | Debug-Output aktivieren |

**Verwendungsbeispiel**:

```bash
# SNI global aktivieren
ansible-playbook playbooks/managed-mailcow/enable-sni-globally.yml \
  -i inventories/extern.yml \
  -K

# Mit Debug-Output
ansible-playbook playbooks/managed-mailcow/enable-sni-globally.yml \
  -i inventories/extern.yml \
  -e "debug=true" \
  -K
```

**Abhängigkeiten**:
- Mailcow-Installation

**Besonderheiten**:
- **Konfigurationsänderung**: Setzt `ENABLE_SSL_SNI=y` in `mailcow.conf`
- **Bedingter Neustart**: Nur wenn Änderung vorgenommen wurde
- **Idempotent**: Mehrfache Ausführung sicher

**Workflow**:
1. Findet Mailcow-Directory
2. Prüft aktuellen SNI-Status in `mailcow.conf`
3. Ändert `ENABLE_SSL_SNI=y` (falls noch nicht gesetzt)
4. Startet Mailcow neu (nur bei Änderung)
5. Wartet auf Service-Verfügbarkeit

**Wann verwenden**:
- Multi-Domain-Setups
- Verschiedene SSL-Zertifikate pro Domain
- Wildcard-Zertifikate für Subdomains

---

### remove-watchdog-mail.yaml

Deaktivierung von Watchdog-E-Mail-Benachrichtigungen.

**Datei**: `playbooks/managed-mailcow/remove-watchdog-mail.yaml`

**Zweck**: Entfernt oder kommentiert die Watchdog-Benachrichtigungs-E-Mail-Adresse in Mailcow.

**Ziel-Hosts**: `all`

**Benutzer**: `tincadmin` (mit sudo-Rechten)

**Verwendete Rollen**:
- `managed-mailcow` (find-mailcow-composedir, start-mailcow)

**Wichtige Variablen**:

| Variable | Default | Beschreibung |
|----------|---------|-------------|
| `debug` | `false` | Debug-Ausgaben |

**Verwendungsbeispiel**:

```bash
# Watchdog-Benachrichtigungen deaktivieren
ansible-playbook playbooks/managed-mailcow/remove-watchdog-mail.yaml \
  -i inventories/extern.yml \
  -K

# Auf einzelnem Server
ansible-playbook playbooks/managed-mailcow/remove-watchdog-mail.yaml \
  -i inventories/extern.yml \
  --limit mail.example.com \
  -K
```

**Abhängigkeiten**:
- Mailcow-Installation

**Besonderheiten**:
- **Kommentiert** oder **entfernt** `WATCHDOG_NOTIFY_EMAIL` in `mailcow.conf`
- **Restart nach Änderung** 
- **Idempotent**

**Workflow**:
1. Findet Mailcow-Directory
2. Sucht `WATCHDOG_NOTIFY_EMAIL` in `mailcow.conf`
3. Kommentiert Zeile aus oder entfernt sie
4. Startet Mailcow neu (bei Änderung)

**Wann verwenden**:
- Zu viele Watchdog-Benachrichtigungen
- Externes Monitoring bevorzugt (z.B. CheckMK)
- Benachrichtigungen an andere Destination

---

### change-garbagecleaner.yaml

Änderung des Mailcow-Garbage-Cleaner-Intervalls.

**Datei**: `playbooks/managed-mailcow/change-garbagecleaner.yaml`

**Zweck**: Setzt das Garbage-Collector-Intervall für Maildir-Bereinigung auf 7 Tage (10080 Minuten).

**Ziel-Hosts**: `all`

**Benutzer**: `tincadmin` (mit sudo-Rechten)

**Verwendete Rollen**: Keine (direkte Tasks)

**Wichtige Variablen**:
- Regex-Ersetzung: `MAILDIR_GC_TIME=10080`

**Verwendungsbeispiel**:

```bash
# Garbage-Cleaner-Intervall ändern
ansible-playbook playbooks/managed-mailcow/change-garbagecleaner.yaml \
  -i inventories/extern.yml \
  -K

# Mit custom Intervall (z.B. 14 Tage = 20160 Minuten)
ansible-playbook playbooks/managed-mailcow/change-garbagecleaner.yaml \
  -i inventories/extern.yml \
  -e "gc_time=20160" \
  -K
```

**Abhängigkeiten**:
- Mailcow-Installation unter `/opt/mailcow-dockerized`

**Besonderheiten**:
- **Backup des Config-Files** vor Änderung
- **Bedingte Docker-Compose Neustart** (nur bei Änderung)
- **Hardcoded Pfad**: `/opt/mailcow-dockerized/mailcow.conf`

**Workflow**:
1. Erstellt Backup von `mailcow.conf`
2. Ersetzt `MAILDIR_GC_TIME` mit neuem Wert (10080)
3. Prüft ob Änderung erfolgte
4. Restart Mailcow (bei Änderung)

**Wann verwenden**:
- Speicherplatz-Optimierung
- Compliance-Anforderungen (längere Aufbewahrung)
- Performance-Tuning

---

### migrate-clamd.yaml

Migration zu zentralem ClamAV-Server, Deaktivieren lokaler ClamAV.

**Datei**: `playbooks/managed-mailcow/migrate-clamd.yaml`

**Zweck**: Umstellung von lokalem ClamAV auf zentralen ClamAV-Server für Antivirus-Scanning.

**Ziel-Hosts**: `all`

**Benutzer**: `tincadmin` (mit sudo-Rechten)

**Verwendete Rollen**: Keine (direkte Tasks)

**Wichtige Variablen**:

| Variable | Wert | Beschreibung |
|----------|------|-------------|
| Neuer ClamAV-Server | `[2a07:6fc0:c:2809::23]:3310` | Zentrale ClamAV-Instanz (IPv6) |

**Verwendungsbeispiel**:

```bash
# Migration auf zentralen ClamAV
ansible-playbook playbooks/managed-mailcow/migrate-clamd.yaml \
  -i inventories/extern.yml \
  -K

# Mit custom ClamAV-Server
ansible-playbook playbooks/managed-mailcow/migrate-clamd.yaml \
  -i inventories/extern.yml \
  -e "clamd_server=[2a07:6fc0:c:2809::99]:3310" \
  -K
```

**Abhängigkeiten**:
- Mailcow-Installation unter `/opt/mailcow-dockerized`
- Erreichbarkeit des zentralen ClamAV-Servers

**Besonderheiten**:
- **Ändert Rspamd-Config**: `antivirus.conf` 
- **Ändert Mailcow-Config**: `SKIP_CLAMD=y` (deaktiviert lokalen ClamAV)
- **Neustart** von Mailcow und Rspamd-Container
- **Ressourcen-Einsparung**: Kein lokaler ClamAV mehr nötig

**Workflow**:
1. Backup von `antivirus.conf`
2. Ändert Rspamd-Antivirus-Konfiguration auf zentralen Server
3. Setzt `SKIP_CLAMD=y` in `mailcow.conf`
4. Restart Mailcow-Stack
5. Restart Rspamd-Container spezifisch

**Vorteile**:
- **Ressourcen-Einsparung**: ClamAV benötigt 1-2 GB RAM pro Instanz
- **Zentrale Updates**: Virus-Signaturen nur einmal aktualisieren
- **Konsistenz**: Gleiche Scan-Engine für alle Server

**Siehe auch**: [Basis-System → deploy-clamav-server.yml](07-Basis-System.md#deploy-clamav-serveryml)

---

### use-syslog-server.yaml

Umleitung von Docker-Container-Logs auf zentralen Syslog-Server.

**Datei**: `playbooks/managed-mailcow/use-syslog-server.yaml`

**Zweck**: Konfiguration des Docker-Logging-Treibers für zentrale Syslog-Aggregation.

**Ziel-Hosts**: `all`

**Benutzer**: `tincadmin` (mit sudo-Rechten)

**Verwendete Rollen**:
- `managed-mailcow` (find-mailcow-composedir, stop-mailcow, start-mailcow)

**Wichtige Variablen**:

| Variable | Wert | Beschreibung |
|----------|------|-------------|
| Syslog-Server | `udp://[2a0e:b680:80::91]:5514` | Zentrale Syslog-Instanz (IPv6, UDP) |
| Format | `rfc5424` | Syslog-Message-Format |
| Tag | `{{ '{{.Name}}' }}` | Container-Name als Log-Tag |

**Verwendungsbeispiel**:

```bash
# Syslog-Logging aktivieren
ansible-playbook playbooks/managed-mailcow/use-syslog-server.yaml \
  -i inventories/extern.yml \
  -K

# Mit custom Syslog-Server
ansible-playbook playbooks/managed-mailcow/use-syslog-server.yaml \
  -i inventories/extern.yml \
  -e "syslog_server=udp://syslog.example.com:514" \
  -K
```

**Abhängigkeiten**:
- Mailcow-Installation
- Erreichbarkeit des Syslog-Servers
- Docker installiert

**Besonderheiten**:
- **Ändert log-driver** zu "syslog" in `docker-compose.override.yml`
- **Bedingte Anwendung**: Nur wenn aktueller Driver "local" ist
- **Mailcow-Neustart** nach Änderung für Aktivierung
- **RFC5424-Format**: Strukturierte Syslog-Messages

**Workflow**:
1. Findet Mailcow-Directory
2. Prüft aktuellen Log-Driver in docker-compose.yml
3. Erstellt docker-compose.override.yml (falls nicht vorhanden)
4. Konfiguriert Syslog-Logging für alle Services
5. Stoppt Mailcow
6. Startet Mailcow (neue Log-Konfiguration aktiv)

**Vorteile**:
- **Zentrale Log-Aggregation**
- **Log-Retention-Management** zentralisiert
- **Bessere Analyse-Möglichkeiten** (z.B. mit ELK-Stack)
- **Reduzierter lokaler Speicherverbrauch**

---

### use-docker-image-proxy.yaml

Konfiguration von Docker-Daemon zur Nutzung von Docker-Image-Proxy.

**Datei**: `playbooks/managed-mailcow/use-docker-image-proxy.yaml`

**Zweck**: Konfiguration des Docker-Daemons zur Verwendung eines HTTP-Proxys für Docker-Image-Downloads.

**Ziel-Hosts**: `all`

**Benutzer**: `tincadmin` (mit sudo-Rechten)

**Verwendete Rollen**: Keine (direkte Tasks)

**Wichtige Variablen**:

| Variable | Wert | Beschreibung |
|----------|------|-------------|
| Proxy-Server | `dim.servercow.com:3128` | Docker-Image-Mirror-Proxy |
| CA-Certificate URL | `http://[2a07:6fc0:c:2809::20]:3128/ca.crt` | Proxy-CA-Zertifikat |

**Verwendungsbeispiel**:

```bash
# Docker-Proxy konfigurieren
ansible-playbook playbooks/managed-mailcow/use-docker-image-proxy.yaml \
  -i inventories/extern.yml \
  -K

# Mit custom Proxy
ansible-playbook playbooks/managed-mailcow/use-docker-image-proxy.yaml \
  -i inventories/extern.yml \
  -e "docker_proxy=proxy.example.com:3128" \
  -K
```

**Abhängigkeiten**:
- Docker installiert
- Erreichbarkeit des Proxy-Servers

**Besonderheiten**:
- **Entfernt existing registry-mirrors** (saubere Neukonfiguration)
- **Installiert CA-Zertifikat** für HTTPS-Proxying
- **Konfiguriert systemd-override** für Docker-Proxy-Environment
- **Reload und Restart** von Docker-Daemon

**Workflow**:
1. Entfernt alte Registry-Mirrors aus `/etc/docker/daemon.json`
2. Lädt CA-Zertifikat vom Proxy herunter
3. Installiert CA-Zertifikat systemweit
4. Erstellt systemd-Override für Docker (`/etc/systemd/system/docker.service.d/http-proxy.conf`)
5. Setzt Environment-Variablen:
   - `HTTP_PROXY`
   - `HTTPS_PROXY`
   - `NO_PROXY`
6. Reload systemd
7. Restart Docker-Service

**Vorteile**:
- **Schnellere Image-Downloads** (Caching)
- **Bandbreiten-Einsparung**
- **Rate-Limit-Vermeidung** bei Docker Hub
- **Offline-Capability** (gecachte Images)

**Siehe auch**: [Container-Management → Docker-Image-Proxy/Mirror](03-Container-Management.md#docker-image-proxymirror)

---

### find-roundcube-installations.yaml

Suche nach Roundcube-Webmail-Installationen in Mailcow.

**Datei**: `playbooks/managed-mailcow/find-roundcube-installations.yaml`

**Zweck**: Automatisches Auffinden von Roundcube-Webmail-Installationen auf Mail-Servern.

**Ziel-Hosts**: `all`

**Benutzer**: `tincadmin` (mit sudo-Rechten)

**Verwendete Rollen**: Keine (direkte Tasks)

**Wichtige Variablen**:

| Variable | Default | Beschreibung |
|----------|---------|-------------|
| `mailcow_search_paths` | `[/opt, /data, /root, /storage]` | Suchverzeichnisse |
| `rc_dirs` | `[rc, roundcube, roundcubemail]` | Roundcube-Verzeichnisnamen |

**Verwendungsbeispiel**:

```bash
# Suche nach Roundcube-Installationen
ansible-playbook playbooks/managed-mailcow/find-roundcube-installations.yaml \
  -i inventories/extern.yml \
  -K

# Mit custom Suchpfaden
ansible-playbook playbooks/managed-mailcow/find-roundcube-installations.yaml \
  -i inventories/extern.yml \
  -e "mailcow_search_paths=[/var/www, /srv]" \
  -K
```

**Abhängigkeiten**:
- Keine (nur Dateisystem-Zugriff)

**Besonderheiten**:
- **Recursive Find** über mehrere Verzeichnisse
- **Pattern-Matching**: Sucht nach typischen Roundcube-Verzeichnissen
- **Report nur für Hosts** mit gefundenen Installationen
- **Keine Änderungen** - nur Information

**Workflow**:
1. Durchsucht definierte Pfade rekursiv
2. Sucht nach Verzeichnissen mit Namen: `rc`, `roundcube`, `roundcubemail`
3. Sammelt gefundene Pfade
4. Zeigt Report für jeden Host mit Installationen

**Ausgabe-Beispiel**:
```
TASK [Show Roundcube installations] ****
ok: [mail-01.example.com] => {
    "msg": "Found Roundcube at: /opt/mailcow-dockerized/data/web/rc"
}
skipping: [mail-02.example.com]  # Keine Installation gefunden
```

**Wann verwenden**:
- Inventarisierung von Roundcube-Installationen
- Vor Roundcube-Updates
- Security-Audits
- Bereinigung alter Installationen

---

### install-register-cmk-agent.yaml

Installation und Registrierung von CheckMK-Agent für verwaltete Mailcow-Systeme.

**Datei**: `playbooks/managed-mailcow/install-register-cmk-agent.yaml`

**Zweck**: Spezialisierte CheckMK-Agent-Installation für Mailcow-Hosts mit spezifischen Konfigurationen.

**Ziel-Hosts**: `all`

**Benutzer**: `tincadmin` (mit sudo-Rechten)

**Verwendete Rollen**:
- `checkmk.general.agent` (externe Collection)

**Wichtige Variablen**:

| Variable | Default | Beschreibung |
|----------|---------|-------------|
| `checkmk_agent_version` | `"2.3.0p14"` | Agent-Version (älter als Standard!) |
| `checkmk_agent_user` | `"automation"` | CheckMK-Automation-User |
| `checkmk_agent_server` | `servercow.observer` | CheckMK-Server |
| `checkmk_agent_folder` | `"/managed_mailcows"` | Ziel-Ordner im CheckMK |
| Discovery | `max_parallel_tasks: 2` | Parallelisierung der Discovery |

**Verwendungsbeispiel**:

```bash
# CheckMK-Agent für Mailcow-Hosts installieren
ansible-playbook playbooks/managed-mailcow/install-register-cmk-agent.yaml \
  -i inventories/extern.yml \
  -K --ask-vault-pass

# Mit neuerer Agent-Version
ansible-playbook playbooks/managed-mailcow/install-register-cmk-agent.yaml \
  -i inventories/extern.yml \
  -e "checkmk_agent_version=2.4.0p17" \
  -K --ask-vault-pass
```

**Abhängigkeiten**:
- CheckMK-Server erreichbar
- Vault-Authentifizierung

**Besonderheiten**:
- **Strategie: linear** - Sequential processing
- **Unterschiedliche Versionen** je nach Use-Case (2.3.0p14 vs. 2.4.0p17)
- **IPv4-Adresse** wird automatisch aus `ansible_default_ipv4.address` extrahiert
- **Spezifischer Folder**: `/managed_mailcows` für Organisierung

**Workflow**:
1. Lädt Vault-Daten
2. Installiert CheckMK-Agent (Version 2.3.0p14)
3. Registriert Agent beim Server
4. Führt Service-Discovery durch (max 2 parallel)
5. Aktiviert Host in CheckMK

**⚠️ Hinweis**: Dieses Playbook verwendet eine ältere Agent-Version (2.3.0p14) als das generische Playbook. Prüfen Sie ob dies beabsichtigt ist.

**Siehe auch**: [Monitoring → reinstall-cmk-agent.yml](02-Monitoring.md#reinstall-cmk-agentyml)

---

### add-haveged.yaml

Installation von Haveged (Entropy-Generator).

**Datei**: `playbooks/managed-mailcow/add-haveged.yaml`

**Zweck**: Installation des Haveged-Daemons für bessere Zufallszahlen-Generierung (Entropie).

**Ziel-Hosts**: `all`

**Benutzer**: `tincadmin` (mit sudo-Rechten)

**Verwendete Rollen**: Keine (direkte apt-Installation)

**Verwendungsbeispiel**:

```bash
# Haveged installieren
ansible-playbook playbooks/managed-mailcow/add-haveged.yaml \
  -i inventories/extern.yml \
  -K
```

**Abhängigkeiten**:
- Debian APT

**Besonderheiten**:
- **Sehr einfaches Playbook**
- **Direkte apt-Installation** ohne Rolle
- **Startet automatisch** nach Installation

**Workflow**:
1. Aktualisiert APT-Cache
2. Installiert Paket `haveged`
3. Startet und aktiviert Service

**Wann verwenden**:
- Virtuelle Maschinen mit niedriger Entropie
- Kryptographie-intensive Anwendungen (Mail-Server, TLS)
- Nach `/dev/random` Blockierungen

**Warum für Mail-Server**:
- Mail-Verschlüsselung benötigt gute Zufallszahlen
- TLS-Verbindungen nutzen Entropie
- DKIM-Signing profitiert von guter Entropie

---

## Rollen

### Rolle: managed-mailcow

**Zweck**: Verwaltung von Mailcow-E-Mail-Servern (Docker-basiert).

**Pfad**: `roles/managed-mailcow/`

**Hauptaufgaben**:

#### 1. check-mailcow-install-status.yml
Prüft ob Mailcow installiert ist.

- Überprüft Existenz von `mailcow.conf`
- Setzt `mailcow_installed` Fact
- Verwendet in Pre-Checks

#### 2. find-mailcow-composedir.yml
Sucht und ermittelt Mailcow-Installationsverzeichnis.

- Sucht nach `docker-compose.yml` mit Mailcow-spezifischem Content
- Setzt `mailcow_dir_result` Variable
- Standardpfad: `/opt/mailcow-dockerized`

#### 3. get-mailcow-current-version.yml
Ermittelt aktuell installierte Mailcow-Version.

- Liest Git-Tag oder Branch
- Parses Versions-Information
- Setzt `mailcow_current_version` Fact

#### 4. start-mailcow.yml
Startet Mailcow-Docker-Compose-Stack.

- Verwendet `docker-compose up -d`
- Wartet auf Service-Verfügbarkeit
- Optionale Verbose-Ausgabe

#### 5. stop-mailcow.yml
Stoppt Mailcow-Stack sauber.

- Verwendet `docker-compose down`
- Graceful shutdown
- Wartet auf vollständiges Stoppen

#### 6. update-mailcow.yml
Führt Mailcow-Update durch.

- Git-Pull von Mailcow-Repository
- Führt `update.sh` Script aus
- Throttled execution (verhindert Overload)
- Wartet auf Abschluss

#### 7. install-mailcow-components.yml
Installiert fehlende Mailcow-Komponenten.

- Installiert optionale Features
- Konfiguriert Zusatzmodule

**Standardvariablen**:

Die Rolle hat keine `defaults/main.yml` - Variablen werden per Playbook übergeben.

**Typische Variablen**:
```yaml
mailcow_dir: /opt/mailcow-dockerized
github_mailcow_ver: "2026-03b"
verbose: true
debug: false
```

**Verwendung in Playbooks**:

```yaml
# Find Mailcow directory
- include_role:
    name: managed-mailcow
    tasks_from: find-mailcow-composedir

# Check installation status
- include_role:
    name: managed-mailcow
    tasks_from: check-mailcow-install-status

# Update Mailcow
- include_role:
    name: managed-mailcow
    tasks_from: update-mailcow
  vars:
    github_mailcow_ver: "2026-04"
```

---

## Best Practices

### 1. Updates planen

Mailcow-Updates in Wartungsfenstern durchführen:
```bash
# Außerhalb der Geschäftszeiten
ansible-playbook playbooks/managed-mailcow/update-mailcow.yaml \
  -i inventories/extern.yml \
  -e "github_mailcow_ver=2026-04" \
  -K --ask-vault-pass
```

### 2. Snapshots aktivieren

**Immer** Snapshots bei Updates aktivieren:
```bash
-e "do_snapshots=true"
```

### 3. Health-Checks vor und nach Änderungen

```bash
# Vor Änderung
ansible-playbook playbooks/managed-mailcow/check-mailcow-health.yml

# Änderung durchführen

# Nach Änderung
ansible-playbook playbooks/managed-mailcow/check-mailcow-health.yml
```

### 4. Zentrale Services nutzen

Verwenden Sie zentrale Services für Ressourcen-Einsparung:
- ClamAV: `migrate-clamd.yaml`
- Syslog: `use-syslog-server.yaml`
- Docker-Proxy: `use-docker-image-proxy.yaml`

### 5. Regelmäßige Bereinigung

Wöchentliche Docker-Cleanups nach Updates:
```bash
# Nach jedem Update
ansible-playbook playbooks/docker/cleanup-images.yml \
  -i inventories/extern.yml \
  -K
```

---

## Fehlerbehebung

### Problem: Mailcow-Update hängt

**Symptome**: Update-Script läuft endlos

**Lösung**:
1. Überprüfen Sie Logs auf dem Host:
   ```bash
   tail -f /opt/mailcow-dockerized/logs/update.log
   ```
2. Überprüfen Sie Docker-Container-Status:
   ```bash
   docker-compose ps
   ```
3. Manuelle Intervention:
   ```bash
   cd /opt/mailcow-dockerized
   ./update.sh --skip-start
   ```

### Problem: Container starten nach Update nicht

**Symptome**: Services bleiben down nach Update

**Lösung**:
1. Überprüfen Sie Logs:
   ```bash
   docker-compose logs -f
   ```
2. Neustart einzelner Container:
   ```bash
   docker-compose restart <container-name>
   ```
3. Vollständiger Neustart:
   ```bash
   ansible-playbook playbooks/managed-mailcow/start-stop-mailcow.yaml
   ```

### Problem: Disk-Space-Check schlägt fehl

**Symptome**: Update abbricht wegen Speicherplatz

**Lösung**:
1. Bereinigen Sie Docker-Ressourcen:
   ```bash
   ansible-playbook playbooks/docker/cleanup-all.yml
   ```
2. Überprüfen Sie Speichernutzung:
   ```bash
   df -h /var/lib/docker
   ```
3. Erweitern Sie Partition oder löschen Sie alte Backups

### Problem: Syslog-Logging funktioniert nicht

**Symptome**: Keine Logs auf Syslog-Server

**Lösung**:
1. Testen Sie Syslog-Server-Erreichbarkeit:
   ```bash
   nc -vuz [2a0e:b680:80::91] 5514
   ```
2. Überprüfen Sie Docker-Logging-Konfiguration:
   ```bash
   docker inspect <container> | grep -A 10 LogConfig
   ```
3. Restart Container nach Logging-Änderung

---

**Navigation**: [← Zurück: Container-Management](03-Container-Management.md) | [Nächstes: Security & Hardening →](05-Security-Hardening.md)