diff --git a/docs/00-Übersicht.md b/docs/00-Übersicht.md new file mode 100644 index 0000000..c24ab56 --- /dev/null +++ b/docs/00-Übersicht.md @@ -0,0 +1,216 @@ +# Operating Automation - Ansible-Projekt Dokumentation + +## Übersicht + +Dieses Ansible-Projekt dient der Automatisierung von Systemadministrations-Aufgaben für eine Debian-basierte Infrastruktur. Es umfasst 26 Playbooks und 10 Rollen zur Verwaltung von Betriebssystem-Updates, Container-Verwaltung, Mail-Server-Betrieb (Mailcow), Monitoring (CheckMK), Virtualisierung (Proxmox) und Sicherheits-Härtung. + +## Projektzweck + +Das Projekt automatisiert folgende Hauptbereiche: +- **Betriebssystem-Verwaltung**: Updates, Major-Upgrades, Mirror-Konfiguration +- **Container-Infrastruktur**: Docker-Installation und -Wartung +- **Mail-Server-Betrieb**: Umfassende Mailcow-Verwaltung mit 13 spezialisierten Playbooks +- **Monitoring**: CheckMK-Agent-Installation und -Verwaltung +- **Virtualisierung**: Proxmox-Snapshot-Verwaltung +- **Sicherheit**: SSH-Schlüssel-Verwaltung und System-Härtung +- **Wartung**: Cleanup-Routinen für Snapshots, Container und Agenten-Plugins + +## Projektstruktur + +``` +operating-automation/ +├── ansible.cfg # Ansible-Hauptkonfiguration +├── vault.yml # Verschlüsselte Zugangsdaten (Ansible Vault) +├── inventories/ # Host-Inventories +│ ├── extern.yml # Externe Mail-Server +│ ├── icp-fra-pve1.yml # Proxmox-Cluster (6 Hosts, IPv6 TincVPN) +│ ├── icp-frav-packer01.yml # Packer-Build-Host +│ └── group_vars/ # Gruppenvariablen +│ ├── all.yml # Globale Variablen für alle Hosts +│ └── all.example.yml # Template für Umgebungsanpassungen +├── playbooks/ # Ansible-Playbooks +│ ├── *.yml # Root-Level Playbooks (OS, Monitoring, etc.) +│ ├── cleanups/ # Wartungs- und Bereinigungsaufgaben +│ ├── docker/ # Docker-Verwaltung +│ ├── hardening/ # Sicherheits-Härtung +│ └── managed-mailcow/ # Mailcow-spezifische Automatisierung +├── roles/ # Ansible-Rollen +│ ├── checkmk-monitoring/ # CheckMK-Integration +│ ├── deploy-clamd/ # ClamAV-Antivirus-Bereitstellung +│ ├── docker/ # Docker-Verwaltung +│ ├── manage-ssh-keys/ # SSH-Schlüssel-Administration +│ ├── managed-mailcow/ # Mailcow-Operationen +│ ├── os-updates/ # Betriebssystem-Updates +│ ├── proxmox-automation/ # Proxmox-Snapshot-Verwaltung +│ ├── ssh/ # SSH-Konfiguration (in Entwicklung) +│ ├── system/ # Basis-Systemkonfiguration +│ └── updates/ # Generische Update-Mechanismen +└── collections/ # Externe Collections (via ansible-galaxy) +``` + +## Ansible-Konfiguration + +Die Datei `ansible.cfg` definiert folgende wichtige Einstellungen: + +| Einstellung | Wert | Bedeutung | +|-------------|------|-----------| +| `host_key_checking` | `False` | Deaktiviert SSH-Host-Key-Überprüfung | +| `roles_path` | `./roles:/etc/ansible/roles` | Priorisiert lokale Rollen | +| `interpreter_python` | `/usr/bin/python3` | Erzwingt Python 3 auf allen Zielhosts | + +## Inventory-Struktur + +Das Projekt nutzt drei separate Inventory-Dateien für unterschiedliche Deployment-Kontexte: + +### icp-fra-pve1.yml +- **Zweck**: Proxmox-Cluster-Verwaltung +- **Hosts**: 6 Systeme +- **Adressierung**: IPv6 TincVPN-Adressen +- **Ziel-OS**: Debian Bookworm/Trixie + +### extern.yml +- **Zweck**: Externe Mail-Server +- **Adressierung**: IPv4 mit custom SSH-Ports +- **Besonderheit**: Root-SSH-Zugang + +### icp-frav-packer01.yml +- **Zweck**: Einzelner Packer-Build-Host +- **Zugriff**: Root via SSH + +## Gruppenvariablen (group_vars) + +Die Konfiguration erfolgt über eine dreistufige Hierarchie: + +1. **all.yml** - Globale Defaults für alle Hosts: + - OS-Update-Konfiguration (Mirror, Upgrade-Modi, Ziel-Versionen) + - CheckMK-Agent-Version (2.3.0p34 CEE) und Server-URLs + - Docker-Mirror und Proxy-Konfiguration + - CrowdSec LAPI-Einstellungen + - BackupCow Git-Repository + +2. **Gruppen-spezifische Variablen** - Z.B. für Proxmox-Cluster + +3. **Host-spezifische Variablen** - Inline in Inventory-Dateien + +## Externe Abhängigkeiten + +Das Projekt benötigt folgende Ansible-Collections (Installation via `ansible-galaxy`): + +| Collection | Version | Verwendung | +|------------|---------|------------| +| `community.docker` | 3.11.0 | Docker-Operationen (cleanup, image mgmt) | +| `community.proxmox` | 1.4.0 | Proxmox API (Snapshots, VM-Management) | +| `checkmk.general` | - | CheckMK-Agent-Deployment & Registrierung | + +## Vault-Verwendung + +Die Datei `vault.yml` enthält verschlüsselte Zugangsdaten für: +- Proxmox API-Tokens +- CheckMK Automation-User und Passwörter +- Weitere sensible Konfigurationsdaten + +**Verwendung**: Playbooks mit Vault-Zugriff müssen mit `--ask-vault-pass` ausgeführt werden. + +## Voraussetzungen + +- **Ansible**: Version 2.14 oder höher +- **Python**: Version 3.x auf allen Zielhosts +- **SSH-Zugriff**: Schlüsselbasierte Authentifizierung als `tincadmin` mit Sudo-Rechten +- **Betriebssystem**: Debian Bookworm oder Trixie auf Zielhosts + +## Dokumentationsnavigation + +Die Dokumentation ist nach funktionalen Kategorien gegliedert: + +1. **[OS-Management](01-OS-Management.md)** - Betriebssystem-Updates, Major-Upgrades, Mirror-Verwaltung +2. **[Monitoring](02-Monitoring.md)** - CheckMK-Agent-Installation und -Verwaltung +3. **[Container-Management](03-Container-Management.md)** - Docker-Installation und -Wartung +4. **[Mail-Server-Verwaltung](04-Mail-Server-Verwaltung.md)** - Mailcow-Automatisierung (13 Playbooks) +5. **[Security & Hardening](05-Security-Hardening.md)** - SSH-Schlüssel-Verwaltung +6. **[Virtualisierung](06-Virtualisierung.md)** - Proxmox-Snapshot-Automatisierung +7. **[Basis-System](07-Basis-System.md)** - Grundlegende Systemkonfiguration, ClamAV, Chrony +8. **[Cleanup-Aufgaben](08-Cleanup-Aufgaben.md)** - Wartungs- und Bereinigungsroutinen + +## Quick Start + +Grundlegendes Kommando-Muster: + +```bash +# Einfaches Playbook ohne Vault +ansible-playbook playbooks/setup-chronyd.yml -i inventories/icp-fra-pve1.yml -K + +# Playbook mit Vault-Zugriff +ansible-playbook playbooks/os-update.yml -i inventories/icp-fra-pve1.yml -K --ask-vault-pass + +# Mit spezifischen Variablen +ansible-playbook playbooks/os-major-upgrade.yml \ + -i inventories/icp-fra-pve1.yml \ + -e "os_update_version_codename=trixie" \ + -e "do_snapshots=true" \ + -K --ask-vault-pass +``` + +**Parameter-Erklärung**: +- `-i`: Inventory-Datei +- `-K`: Fragt nach Sudo-Passwort +- `--ask-vault-pass`: Fragt nach Vault-Passwort +- `-e`: Externe Variable (überschreibt Defaults) + +## Best Practices + +1. **Snapshots**: Aktivieren Sie Snapshots bei riskanten Operationen (Major-Upgrades, Mailcow-Updates) +2. **Dry-Run**: Nutzen Sie `--check` für Trockenläufe (wo unterstützt) +3. **Limitierung**: Verwenden Sie `--limit hostname` für Tests auf einzelnen Hosts +4. **Vault-Sicherheit**: Bewahren Sie das Vault-Passwort sicher auf +5. **Inventories**: Pflegen Sie getrennte Inventories für Produktion und Test-Umgebungen + +## Projekt-Architektur + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Ansible Control Node │ +│ │ +│ ┌─────────────┐ ┌──────────────┐ ┌─────────────┐ │ +│ │ Playbooks │──▶│ Roles │──▶│ Inventories │ │ +│ └─────────────┘ └──────────────┘ └─────────────┘ │ +│ │ │ │ │ +│ │ │ │ │ +│ └──────────────────┴───────────────────┘ │ +│ │ │ +└────────────────────────────┼─────────────────────────────────┘ + │ + ▼ + ┌───────────────────────────────────────┐ + │ Target Infrastructure │ + │ │ + │ ┌──────────┐ ┌──────────────┐ │ + │ │ Proxmox │ │ Mailcow │ │ + │ │ Cluster │ │ Servers │ │ + │ └──────────┘ └──────────────┘ │ + │ │ + │ ┌──────────┐ ┌──────────────┐ │ + │ │ CheckMK │ │ Docker │ │ + │ │ Agent │ │ Container │ │ + │ └──────────┘ └──────────────┘ │ + └───────────────────────────────────────┘ +``` + +## Häufig verwendete Playbooks + +| Playbook | Häufigkeit | Zweck | +|----------|------------|-------| +| `os-update.yml` | Wöchentlich | Regelmäßige Sicherheitsupdates | +| `managed-mailcow/update-mailcow.yaml` | Monatlich | Mailcow-Updates | +| `docker/cleanup-images.yml` | Wöchentlich | Speicherplatz freigeben | +| `setup-checkmk-monitoring.yml` | Bei neuen Hosts | Monitoring einrichten | +| `os-major-upgrade.yml` | Bei Releases | Debian-Versionssprung | + +## Kontakt und Support + +Diese Dokumentation wurde erstellt am: **14. April 2026** + +Bei Änderungen an Playbooks oder Rollen sollte diese Dokumentation entsprechend aktualisiert werden. + +--- + +**Navigation**: [Nächstes: OS-Management →](01-OS-Management.md) diff --git a/docs/01-OS-Management.md b/docs/01-OS-Management.md new file mode 100644 index 0000000..e53c7e2 --- /dev/null +++ b/docs/01-OS-Management.md @@ -0,0 +1,346 @@ +# OS-Management + +## Übersicht + +Diese Kategorie umfasst alle Playbooks und Rollen zur Verwaltung des Debian-Betriebssystems, einschließlich regulärer Updates, Major-Version-Upgrades und Paketquellen-Konfiguration. + +**Anwendungsfälle**: +- Regelmäßige Sicherheits- und Paket-Updates +- Debian-Versionssprünge (z.B. Bookworm → Trixie) +- Umstellung auf alternative Mirror-Server +- Automatisierte Wartungsfenster + +--- + +## Playbooks + +### os-update.yml + +Führt reguläre Betriebssystem-Updates (Minor-Updates) für Debian-Systeme durch. + +**Datei**: `playbooks/os-update.yml` + +**Zweck**: Regelmäßige Installation von Sicherheits- und Paket-Updates auf allen Debian-Systemen mit optionaler Snapshot-Erstellung vor dem Update. + +**Ziel-Hosts**: `all` (gefiltert auf Debian-Systeme) + +**Benutzer**: `tincadmin` (mit sudo-Rechten) + +**Verwendete Rollen**: +- [`proxmox-automation`](06-Virtualisierung.md#rolle-proxmox-automation) (optional, für Snapshots) +- `os-updates` (siehe unten) + +**Wichtige Variablen**: + +| Variable | Default | Beschreibung | +|----------|---------|-------------| +| `os_also_update_mirror` | `false` | Aktualisiert auch die Mirror-Konfiguration | +| `os_update_version_codename` | `"trixie"` | Ziel-Codename für Paketquellen | +| `do_snapshots` | `true` | Erstellt Proxmox-Snapshots vor Updates | +| `snapshot_name` | `"AUTO_before_os_update_{{ ansible_date_time.date }}"` | Name des Snapshots | + +**Verwendungsbeispiel**: + +```bash +# Einfaches Update ohne Snapshots +ansible-playbook playbooks/os-update.yml \ + -i inventories/icp-fra-pve1.yml \ + -e "do_snapshots=false" \ + -K --ask-vault-pass + +# Update mit Mirror-Aktualisierung +ansible-playbook playbooks/os-update.yml \ + -i inventories/icp-fra-pve1.yml \ + -e "os_also_update_mirror=true" \ + -K --ask-vault-pass + +# Update auf einzelnem Host +ansible-playbook playbooks/os-update.yml \ + -i inventories/icp-fra-pve1.yml \ + --limit hostname.example.com \ + -K --ask-vault-pass +``` + +**Abhängigkeiten**: +- Vault-Datei (`vault.yml`) für Proxmox API-Zugriff +- Proxmox-Umgebung (wenn `do_snapshots=true`) +- Verfügbare Updates auf den Zielsystemen + +**Besonderheiten**: +- Prüft mit `apt list --upgradable`, ob Updates verfügbar sind +- Erstellt Snapshots nur wenn tatsächlich Updates vorhanden sind +- Überspringt Snapshot-Erstellung automatisch, wenn `do_snapshots=false` +- Bedingte Proxmox-Integration je nach Konfiguration + +**Workflow**: +1. Lädt Vault-Datei (falls Snapshots aktiviert) +2. Prüft auf verfügbare Updates +3. Erstellt Snapshot (optional, nur bei verfügbaren Updates) +4. Aktualisiert APT-Cache +5. Führt Paket-Upgrade durch +6. Neustart bei Kernel-Updates (optional) + +--- + +### os-major-upgrade.yml + +Führt ein Debian-Major-Version-Upgrade durch (z.B. Bookworm → Trixie). + +**Datei**: `playbooks/os-major-upgrade.yml` + +**Zweck**: Upgrade des Debian-Betriebssystems auf die nächste Hauptversion mit automatischer Snapshot-Erstellung und Neustart-Verwaltung. + +**Ziel-Hosts**: `all` (gefiltert auf Debian-Systeme) + +**Benutzer**: `tincadmin` (mit sudo-Rechten) + +**Verwendete Rollen**: +- [`proxmox-automation`](06-Virtualisierung.md#rolle-proxmox-automation) (für Snapshots) +- `os-updates` (für Version-Upgrade-Logik) + +**Wichtige Variablen**: + +| Variable | Default | Beschreibung | +|----------|---------|-------------| +| `os_update_major_version` | `true` | Aktiviert Major-Version-Upgrade | +| `os_update_version_codename` | `"trixie"` | Ziel-Debian-Version | +| `do_snapshots` | `true` | Erstellt Snapshots vor Upgrade | +| `snapshot_name` | `"AUTO_before_major_{{ ansible_date_time.date }}"` | Snapshot-Name | + +**Verwendungsbeispiel**: + +```bash +# Major-Upgrade auf Trixie mit Snapshots +ansible-playbook playbooks/os-major-upgrade.yml \ + -i inventories/icp-fra-pve1.yml \ + -e "os_update_version_codename=trixie" \ + -K --ask-vault-pass + +# Ohne Snapshots (nicht empfohlen!) +ansible-playbook playbooks/os-major-upgrade.yml \ + -i inventories/icp-fra-pve1.yml \ + -e "do_snapshots=false" \ + -K --ask-vault-pass + +# Test auf einzelnem Host +ansible-playbook playbooks/os-major-upgrade.yml \ + -i inventories/icp-fra-pve1.yml \ + --limit test-host.example.com \ + -K --ask-vault-pass +``` + +**Abhängigkeiten**: +- Vault-Datei für Proxmox API-Tokens +- Proxmox-Integration (stark empfohlen für Snapshots) +- Ausreichend Festplattenspeicher für Upgrade +- Stabile Netzwerkverbindung + +**Besonderheiten**: +- **Liest `/etc/os-release`** um aktuelle Debian-Version zu ermitteln +- **Vergleicht** aktuelle und Ziel-Version vor Upgrade +- **Erstellt Snapshots** vor dem Upgrade (Rollback-Möglichkeit) +- **Wartet auf Verbindung** nach Neustart (Timeout: 300 Sekunden) +- **Überspringt** Upgrade automatisch, wenn bereits auf Ziel-Version + +**Workflow**: +1. Lädt Vault-Datei +2. Liest aktuelle OS-Version aus `/etc/os-release` +3. Abruft Proxmox VM-ID +4. Erstellt Pre-Upgrade Snapshot +5. Aktualisiert Paketquellen auf neue Version +6. Aktualisiert APT-Cache +7. Führt `apt dist-upgrade` durch +8. Startet System neu +9. Wartet auf Verfügbarkeit des Systems + +**⚠️ Warnung**: Major-Upgrades sind kritische Operationen. Immer Snapshots aktivieren und auf Test-Systemen validieren! + +--- + +### os-change-mirror.yml + +Ändert die Debian-Paketquellen (APT-Mirror) auf allen Systemen. + +**Datei**: `playbooks/os-change-mirror.yml` + +**Zweck**: Umstellung der APT-Paketquellen auf alternative Mirror-Server (z.B. auf interne tinc.gmbh Mirrors). + +**Ziel-Hosts**: `all` (gefiltert auf Debian-Systeme) + +**Benutzer**: `tincadmin` (mit sudo-Rechten) + +**Verwendete Rollen**: +- `os-updates` (Task: `update_mirrors`) + +**Wichtige Variablen**: +- Verwendet Variablen aus `group_vars/all.yml` (`os_update_mirrors`) + +**Verwendungsbeispiel**: + +```bash +# Mirror-Änderung auf allen Hosts +ansible-playbook playbooks/os-change-mirror.yml \ + -i inventories/icp-fra-pve1.yml \ + -K + +# Auf spezifischer Host-Gruppe +ansible-playbook playbooks/os-change-mirror.yml \ + -i inventories/extern.yml \ + -K + +# Mit custom Mirror (überschreibt Defaults) +ansible-playbook playbooks/os-change-mirror.yml \ + -i inventories/icp-fra-pve1.yml \ + -e "os_update_mirrors=['http://deb.debian.org/debian']" \ + -K +``` + +**Abhängigkeiten**: +- Debian-Betriebssystem (`ansible_os_family == "Debian"`) +- Keine Vault-Datei erforderlich + +**Besonderheiten**: +- **Überprüfung des Betriebssystems** mit Fehler-Abbruch bei Nicht-Debian +- **Backup** der alten `/etc/apt/sources.list` wird automatisch erstellt +- **Aktualisiert** APT-Cache nach Mirror-Änderung +- **Einfaches Playbook** ohne komplexe Logik + +**Workflow**: +1. Prüft OS-Familie (nur Debian erlaubt) +2. Erstellt Backup der aktuellen sources.list +3. Schreibt neue Mirror-Konfiguration +4. Aktualisiert APT-Cache (`apt update`) + +--- + +## Rollen + +### Rolle: os-updates + +**Zweck**: Zentrale Rolle für alle OS-Update-Operationen auf Debian-Systemen. + +**Pfad**: `roles/os-updates/` + +**Hauptaufgaben**: + +#### 1. main.yml +Steuert den Update-Workflow und koordiniert Mirror-Updates und Paket-Upgrades. + +#### 2. update_mirrors.yaml +Aktualisiert die APT-Mirror-Konfiguration in `/etc/apt/sources.list`. + +- Verwendet Jinja2-Template `sources.list.j2` +- Setzt Mirror-URLs aus `os_update_mirrors` Variable +- Erstellt Backup der Original-Konfiguration + +#### 3. upgrade_packages.yaml +Führt das eigentliche Paket-Upgrade durch. + +- Aktualisiert APT-Cache +- Führt `apt upgrade` oder `apt dist-upgrade` durch +- Prüft auf Kernel-Updates +- Triggert Neustart bei Kernel-Update (über Handler) + +#### 4. update_major_version.yaml +Wechselt Debian auf eine neue Hauptversion. + +- Ändert Codename in `/etc/apt/sources.list` +- Führt `apt update` und `apt dist-upgrade` durch +- Verwaltet Neustart-Logik + +**Standardvariablen** (`defaults/main.yml`): + +| Variable | Default | Beschreibung | +|----------|---------|-------------| +| `os_update_auto_upgrade` | `true` | Automatisches Upgrade aktivieren | +| `os_also_update_mirror` | `true` | Mirror auch aktualisieren | +| `os_update_mirrors` | tinc.gmbh Mirrors | Liste der APT-Mirror-URLs | +| `os_update_major_version` | `false` | Major-Version-Upgrade aktivieren | +| `os_update_version_codename` | `"bookworm"` | Ziel-Debian-Codename | + +**Handler**: +- `apt cleanup` - Führt `apt autoremove` und `apt clean` aus +- `Reboot system` - Startet System neu und wartet auf Verfügbarkeit + +**Templates**: +- `sources.list.j2` - Erzeugt `/etc/apt/sources.list` mit konfigurierten Mirrors + +**Verwendung in Playbooks**: + +```yaml +- name: OS Updates durchführen + hosts: all + become: true + roles: + - role: os-updates +``` + +**Verwendung einzelner Tasks**: + +```yaml +- name: Nur Mirrors aktualisieren + include_role: + name: os-updates + tasks_from: update_mirrors +``` + +--- + +## Best Practices + +### 1. Snapshot-Verwaltung +Aktivieren Sie **immer** Snapshots bei Major-Upgrades: +```bash +-e "do_snapshots=true" +``` + +### 2. Test-First-Ansatz +Testen Sie Updates zuerst auf einem einzelnen Host: +```bash +--limit test-host.example.com +``` + +### 3. Wartungsfenster +Planen Sie OS-Updates in Wartungsfenstern, besonders wenn Neustarts erforderlich sind. + +### 4. Mirror-Auswahl +Verwenden Sie geografisch nahe oder interne Mirrors für schnellere Updates: +```yaml +os_update_mirrors: + - "http://tinc.gmbh/debian" + - "http://tinc.gmbh/debian-security" +``` + +### 5. Monitoring nach Updates +Überprüfen Sie nach Major-Upgrades: +- System-Services: `systemctl --failed` +- Kernel-Version: `uname -r` +- Verfügbare Updates: `apt list --upgradable` +- Logs: `/var/log/apt/history.log` + +--- + +## Fehlerbehebung + +### Problem: Snapshot schlägt fehl +**Lösung**: Überprüfen Sie Proxmox API-Zugangsdaten in `vault.yml` und Speicherplatz auf dem Storage. + +### Problem: APT-Lock während Update +**Lösung**: Stellen Sie sicher, dass keine anderen APT-Prozesse laufen: +```bash +sudo lsof /var/lib/dpkg/lock-frontend +sudo killall apt apt-get +``` + +### Problem: Neustart nach Kernel-Update hängt +**Lösung**: Überprüfen Sie Console-Zugriff über Proxmox und prüfen Sie auf Boot-Probleme. + +### Problem: Mirror nicht erreichbar +**Lösung**: Testen Sie Mirror-Erreichbarkeit manuell: +```bash +curl -I http://tinc.gmbh/debian/ +``` + +--- + +**Navigation**: [← Zurück zur Übersicht](00-Übersicht.md) | [Nächstes: Monitoring →](02-Monitoring.md) diff --git a/docs/02-Monitoring.md b/docs/02-Monitoring.md new file mode 100644 index 0000000..5e67cc6 --- /dev/null +++ b/docs/02-Monitoring.md @@ -0,0 +1,454 @@ +# Monitoring + +## Übersicht + +Diese Kategorie umfasst alle Playbooks und Rollen zur CheckMK-Monitoring-Integration. CheckMK wird für die zentrale Überwachung aller verwalteten Systeme eingesetzt. + +**Anwendungsfälle**: +- Installation und Registrierung des CheckMK-Agenten auf neuen Hosts +- Neuinstallation von CheckMK-Agenten nach Problemen +- Automatische Service-Discovery auf überwachten Hosts +- Bereinigung von Agent-Plugins +- Verwaltung von Hosts im CheckMK-Server + +**CheckMK-Server**: `servercow.observer` (Site: `scowmon`) + +--- + +## Playbooks + +### setup-checkmk-monitoring.yml + +Umfassende CheckMK-Monitoring-Einrichtung mit Host-Erstellung, Agent-Installation und Service-Discovery. + +**Datei**: `playbooks/setup-checkmk-monitoring.yml` + +**Zweck**: Vollständige Integration eines neuen Hosts in das CheckMK-Monitoring-System, einschließlich Host-Registrierung, Agent-Installation, Zertifikat-Signierung und automatischer Service-Erkennung. + +**Ziel-Hosts**: `all` + +**Benutzer**: `tincadmin` (mit sudo-Rechten) + +**Verwendete Rollen**: +- `checkmk-monitoring` (eigene Rolle) + - Tasks: `create-host`, `sign-bake-agents`, `discover-host` +- `checkmk.general.agent` (externe Collection) + +**Wichtige Variablen**: + +Alle Variablen werden aus der Vault-Datei geladen. Wichtige Konfigurationsparameter: + +| Variable | Beispielwert | Beschreibung | +|----------|--------------|-------------| +| `checkmk_server` | `servercow.observer` | CheckMK-Server-URL | +| `checkmk_site` | `scowmon` | CheckMK-Site-Name | +| `checkmk_folder` | `/managed_mailcows` | Ziel-Ordner im CheckMK | +| `checkmk_automation_user` | Aus Vault | Automation-Benutzer | +| `checkmk_automation_secret` | Aus Vault | Automation-Passwort | + +**Verwendungsbeispiel**: + +```bash +# Vollständiges Monitoring-Setup für alle Hosts +ansible-playbook playbooks/setup-checkmk-monitoring.yml \ + -i inventories/icp-fra-pve1.yml \ + -K --ask-vault-pass + +# Nur für bestimmte Host-Gruppe +ansible-playbook playbooks/setup-checkmk-monitoring.yml \ + -i inventories/extern.yml \ + -K --ask-vault-pass + +# Einzelner Host +ansible-playbook playbooks/setup-checkmk-monitoring.yml \ + -i inventories/icp-fra-pve1.yml \ + --limit newhost.example.com \ + -K --ask-vault-pass +``` + +**Abhängigkeiten**: +- Vault-Datei (`vault.yml`) mit CheckMK-Zugangsdaten +- Externe Collection: `checkmk.general` +- Erreichbarkeit des CheckMK-Servers +- DNS-Auflösung für überwachte Hosts + +**Besonderheiten**: +- **Mehrere sequenzielle Schritte**: + 1. Host im CheckMK registrieren + 2. Agent-Zertifikate signieren und backen + 3. CheckMK-Agent auf Host installieren + 4. Service-Discovery durchführen +- **2-Minuten-Pause** vor Discovery für Agent-Bereitschaft +- **`ignore_errors: true`** für Agent-Zertifikat-Handling (Fehlertoleranz) +- **Delegation zu localhost** für CheckMK-API-Aufrufe + +**Workflow**: +1. Lädt Vault-Datei mit Zugangsdaten +2. Erstellt Host im CheckMK-Server (Task: `create-host`) +3. Signiert und bäckt ausstehende Agent-Jobs (Task: `sign-bake-agents`) +4. Installiert CheckMK-Agent auf Zielhost (externe Rolle) +5. Wartet 2 Minuten auf Agent-Bereitschaft +6. Führt Service-Discovery durch (Task: `discover-host`) +7. Aktiviert Änderungen im CheckMK + +--- + +### reinstall-cmk-agent.yml + +Neuinstallation und Neuregistrierung des CheckMK-Monitoring-Agenten. + +**Datei**: `playbooks/reinstall-cmk-agent.yml` + +**Zweck**: Neuinstallation des CheckMK-Agenten, z.B. nach Agenten-Problemen oder Version-Upgrades. + +**Ziel-Hosts**: `all` + +**Benutzer**: `tincadmin` (mit sudo-Rechten) + +**Verwendete Rollen**: +- `checkmk.general.agent` (externe Collection) + +**Wichtige Variablen**: + +| Variable | Default | Beschreibung | +|----------|---------|-------------| +| `checkmk_agent_version` | `"2.4.0p17"` | Agent-Version | +| `checkmk_agent_edition` | `"cee"` | Edition (CEE = Commercial Enterprise Edition) | +| `checkmk_agent_server` | `servercow.observer` | CheckMK-Server | +| `checkmk_agent_site` | `"scowmon"` | Site-Name | +| `checkmk_agent_folder` | `"/managed_mailcows"` | Ziel-Ordner | +| `checkmk_agent_auto_activate` | `true` | Automatische Aktivierung | +| `checkmk_agent_tls` | `true` | TLS-Verschlüsselung aktivieren | +| `checkmk_agent_discover` | `true` | Automatische Service-Discovery | + +**Verwendungsbeispiel**: + +```bash +# Neuinstallation des Agenten auf allen Hosts +ansible-playbook playbooks/reinstall-cmk-agent.yml \ + -i inventories/icp-fra-pve1.yml \ + -K --ask-vault-pass + +# Mit spezifischer Agent-Version +ansible-playbook playbooks/reinstall-cmk-agent.yml \ + -i inventories/icp-fra-pve1.yml \ + -e "checkmk_agent_version=2.4.0p20" \ + -K --ask-vault-pass + +# Nur auf problematischen Hosts +ansible-playbook playbooks/reinstall-cmk-agent.yml \ + -i inventories/extern.yml \ + --limit mail-server-01.example.com \ + -K --ask-vault-pass +``` + +**Abhängigkeiten**: +- Vault-Datei mit CheckMK-Zugangsdaten (`checkmk_agent_user`, `checkmk_agent_pass`) +- Externe Collection `checkmk.general` +- CheckMK-Server muss erreichbar sein +- Host muss bereits im CheckMK registriert sein + +**Besonderheiten**: +- **Strategie: linear** - Hosts werden nacheinander bearbeitet +- **Host-Auto-Discovery** aktiviert (`checkmk_agent_discover: true`) +- **Automatische API-Aktivierung** nach Host-Hinzufügen +- **IP-Adresse** wird automatisch aus `ansible_default_ipv4.address` extrahiert +- **Discovery mit Parallelisierung**: `max_parallel_tasks: 2` + +**Workflow**: +1. Lädt Vault-Datei +2. Deinstalliert alten Agent (falls vorhanden) +3. Lädt neue Agent-Version herunter +4. Installiert neuen Agenten +5. Registriert Agent beim CheckMK-Server +6. Führt Service-Discovery durch +7. Aktiviert Änderungen + +**⚠️ Hinweis**: Dieses Playbook verwendet eine ältere Agent-Version (2.4.0p17) als das Standard-Setup (2.3.0p34 in `group_vars/all.yml`). Passen Sie die Version bei Bedarf an. + +--- + +## Rollen + +### Rolle: checkmk-monitoring + +**Zweck**: Integriert Hosts mit dem CheckMK-Überwachungsserver und verwaltet Monitoring-Agenten. + +**Pfad**: `roles/checkmk-monitoring/` + +**Hauptaufgaben**: + +#### 1. create-host.yaml +Registriert neue Hosts auf dem CheckMK-Server. + +- Verwendet CheckMK REST-API +- Erstellt Host-Eintrag mit IPv6-Adressen +- Setzt Host-Attribute (Ordner, Tags, IP-Adresse) +- Delegiert zu localhost (API-Aufruf) + +**Beispiel-Verwendung**: +```yaml +- import_role: + name: checkmk-monitoring + tasks_from: create-host.yaml +``` + +#### 2. sign-bake-agents.yaml +Signiert und bäckt ausstehende Agent-Jobs im CheckMK. + +- Signiert TLS-Agent-Zertifikate +- Bäckt Agent-Pakete +- Wartet auf Abschluss des Baking-Prozesses +- **Retry-Logik**: Versucht mehrfach bei Fehlern + +**Beispiel-Verwendung**: +```yaml +- import_role: + name: checkmk-monitoring + tasks_from: sign-bake-agents.yaml +``` + +#### 3. discover-host.yaml +Führt automatische Service-Discovery auf Hosts durch. + +- Scannt Host nach verfügbaren Services +- Fügt erkannte Services zum Monitoring hinzu +- Aktiviert Änderungen automatisch +- Delegiert zu localhost (API-Aufruf) + +**Beispiel-Verwendung**: +```yaml +- import_role: + name: checkmk-monitoring + tasks_from: discover-host.yaml +``` + +#### 4. delete-host.yaml +Löscht Hosts vom CheckMK-Server. + +- Entfernt Host aus Monitoring +- Bereinigt alle assoziierten Services +- Nützlich für Dekommissionierung + +**Beispiel-Verwendung**: +```yaml +- import_role: + name: checkmk-monitoring + tasks_from: delete-host.yaml +``` + +#### 5. cleanup-agent-plugins.yaml +Bereinigt nicht benötigte Agent-Plugins auf überwachten Hosts. + +- Entfernt veraltete oder unerwünschte Plugins +- Reduziert Overhead auf Agenten +- Verwendet Variable `checkmk_agent_plugins_to_remove` + +**Beispiel-Verwendung**: +```yaml +- import_role: + name: checkmk-monitoring + tasks_from: cleanup-agent-plugins.yaml +``` + +**Standardvariablen** (`defaults/main.yaml`): + +| Variable | Default | Beschreibung | +|----------|---------|-------------| +| `checkmk_agent_plugins_to_remove` | `["docker-mailq-monitoring"]` | Liste zu entfernender Plugins | + +**Handler**: + +| Handler | Funktion | +|---------|----------| +| `Activate Changes` | Aktiviert Konfigurationsänderungen auf CheckMK | +| `Sign and bake pending agent jobs` | Signiert Agent-Zertifikate mit Retry-Logik | + +**Abhängigkeiten**: +- Keine lokalen Abhängigkeiten +- Externe Collection: `checkmk.general` erforderlich + +**Verwendung in Playbooks**: + +Das Playbook `setup-checkmk-monitoring.yml` zeigt die typische Verwendung: + +```yaml +- name: Create host in CheckMK + import_role: + name: checkmk-monitoring + tasks_from: create-host.yaml + +- name: Sign and bake pending agent jobs + import_role: + name: checkmk-monitoring + tasks_from: sign-bake-agents.yaml + +- name: Install CheckMK agent + include_role: + name: checkmk.general.agent + +- name: Wait for agent to be ready + pause: + minutes: 2 + +- name: Discover host + import_role: + name: checkmk-monitoring + tasks_from: discover-host.yaml +``` + +--- + +## CheckMK-Konfiguration + +### Global Variables (aus group_vars/all.yml) + +```yaml +# CheckMK Agent Configuration +checkmk_agent_version: "2.3.0p34" +checkmk_agent_edition: "cee" +checkmk_agent_server: "servercow.observer" +checkmk_agent_site: "scowmon" +checkmk_agent_folder: "/managed_mailcows" +checkmk_agent_auto_activate: true +checkmk_agent_tls: true +checkmk_agent_discover: true +checkmk_agent_registration_mode: "automatic" +``` + +### Vault-Variablen (vault.yml) + +```yaml +# Nicht sichtbar - verschlüsselt +checkmk_automation_user: "automation" +checkmk_automation_secret: "" +checkmk_agent_user: "automation" +checkmk_agent_pass: "" +``` + +--- + +## Best Practices + +### 1. Monitoring neuer Hosts + +Verwenden Sie `setup-checkmk-monitoring.yml` für neue Hosts. Es führt alle notwendigen Schritte automatisch durch. + +### 2. Agent-Updates + +Für bestehende Hosts mit alten Agent-Versionen: +```bash +ansible-playbook playbooks/reinstall-cmk-agent.yml \ + -i inventories/icp-fra-pve1.yml \ + -e "checkmk_agent_version=2.4.0p20" \ + -K --ask-vault-pass +``` + +### 3. Service-Discovery + +CheckMK führt automatisch Discovery durch. Für manuelle Discovery nur bei Änderungen: +```bash +# Führen Sie setup-checkmk-monitoring.yml mit --limit aus +ansible-playbook playbooks/setup-checkmk-monitoring.yml \ + -i inventories/icp-fra-pve1.yml \ + --limit changed-host.example.com \ + -K --ask-vault-pass +``` + +### 4. Plugin-Bereinigung + +Entfernen Sie regelmäßig nicht benötigte Plugins: +```bash +ansible-playbook playbooks/cleanups/cleanup-cmk-agent-plugins.yml \ + -i inventories/icp-fra-pve1.yml \ + -K +``` + +### 5. TLS-Verschlüsselung + +Halten Sie `checkmk_agent_tls: true` für sichere Agent-Verbindungen. + +--- + +## Fehlerbehebung + +### Problem: Agent-Registrierung schlägt fehl + +**Symptome**: Agent kann sich nicht beim Server registrieren + +**Lösung**: +1. Überprüfen Sie Vault-Zugangsdaten +2. Testen Sie Erreichbarkeit des CheckMK-Servers: + ```bash + curl https://servercow.observer/scowmon + ``` +3. Überprüfen Sie Firewall-Regeln (Port 6556 für Agent-Communication) + +### Problem: Service-Discovery findet keine Services + +**Symptome**: Nach Installation werden keine Services erkannt + +**Lösung**: +1. Warten Sie 2-3 Minuten nach Agent-Installation +2. Überprüfen Sie Agent-Status auf Host: + ```bash + systemctl status check-mk-agent.socket + cmk-agent-ctl status + ``` +3. Manuelle Discovery im CheckMK-Web-Interface durchführen + +### Problem: TLS-Zertifikat-Fehler + +**Symptome**: Agent-Verbindung schlägt mit TLS-Fehler fehl + +**Lösung**: +1. Regenerieren Sie Agent-Zertifikate: + ```bash + ansible-playbook playbooks/setup-checkmk-monitoring.yml \ + --tags sign-bake \ + -i inventories/... \ + -K --ask-vault-pass + ``` +2. Deinstallieren und neu installieren Sie den Agenten + +### Problem: Alte Plugins stören Monitoring + +**Symptome**: Fehler in Service-Checks oder hohe Agent-Last + +**Lösung**: +```bash +# Bereinigen Sie Plugins +ansible-playbook playbooks/cleanups/cleanup-cmk-agent-plugins.yml \ + -i inventories/icp-fra-pve1.yml \ + -K + +# Passen Sie checkmk_agent_plugins_to_remove in defaults/main.yaml an +``` + +--- + +## Externe Abhängigkeiten + +### CheckMK Collection Installation + +Installieren Sie die erforderliche Collection: + +```bash +ansible-galaxy collection install checkmk.general +``` + +Oder mit spezifischer Version: + +```bash +ansible-galaxy collection install checkmk.general:5.0.0 +``` + +### Dokumentation + +Offizielle CheckMK Collection Dokumentation: +- https://docs.checkmk.com/stable/en/agent_linux.html +- https://galaxy.ansible.com/checkmk/general + +--- + +**Navigation**: [← Zurück: OS-Management](01-OS-Management.md) | [Nächstes: Container-Management →](03-Container-Management.md) diff --git a/docs/03-Container-Management.md b/docs/03-Container-Management.md new file mode 100644 index 0000000..4e5bd7d --- /dev/null +++ b/docs/03-Container-Management.md @@ -0,0 +1,547 @@ +# Container-Management + +## Übersicht + +Diese Kategorie umfasst alle Playbooks und Rollen zur Docker-Container-Verwaltung, einschließlich Installation, Konfiguration, Bereinigung und Wartung. + +**Anwendungsfälle**: +- Docker-Installation auf neuen Hosts +- Bereinigung ungenutzter Container und Images +- Verwaltung von Docker-Daemons +- Konfiguration von Image-Proxy/Mirror für schnellere Pulls +- Status-Überprüfung von Docker-Compose-Stacks + +--- + +## Playbooks + +### docker/install-docker.yml + +Installation und Konfiguration von Docker aus offizieller Quelle. + +**Datei**: `playbooks/docker/install-docker.yml` + +**Zweck**: Installiert Docker Engine von der offiziellen Docker-Repository auf Debian-basierten Systemen. + +**Ziel-Hosts**: `all` + +**Benutzer**: `tincadmin` (mit sudo-Rechten) + +**Verwendete Rollen**: +- `system` (Task: `install-docker.yaml`) + +**Wichtige Variablen**: + +| Variable | Default | Beschreibung | +|----------|---------|-------------| +| `docker_install_source` | `"official"` | Installationsquelle (official/tinc) | + +**Verwendungsbeispiel**: + +```bash +# Docker von offizieller Quelle installieren +ansible-playbook playbooks/docker/install-docker.yml \ + -i inventories/icp-fra-pve1.yml \ + -K + +# Mit tinc-Mirror (schneller in internem Netzwerk) +ansible-playbook playbooks/docker/install-docker.yml \ + -i inventories/icp-fra-pve1.yml \ + -e "docker_install_source=tinc" \ + -K + +# Auf einzelnem Host +ansible-playbook playbooks/docker/install-docker.yml \ + -i inventories/icp-fra-pve1.yml \ + --limit newhost.example.com \ + -K +``` + +**Abhängigkeiten**: +- `system` Rolle +- Internet-Zugriff oder tinc-Mirror-Zugriff +- APT-Paketmanager + +**Besonderheiten**: +- Verwendet offizielle Docker-Registry standardmäßig +- Installiert Docker CE (Community Edition) +- Konfiguriert Docker-Daemon automatisch +- Aktiviert Docker-Service beim Systemstart + +**Workflow**: +1. Fügt Docker GPG-Key hinzu +2. Konfiguriert Docker APT-Repository +3. Aktualisiert APT-Cache +4. Installiert Docker CE +5. Startet und aktiviert Docker-Service + +--- + +### docker/cleanup-images.yml + +Bereinigung ungenutzter Docker-Images. + +**Datei**: `playbooks/docker/cleanup-images.yml` + +**Zweck**: Entfernt ungenutzte Docker-Images um Festplattenspeicher freizugeben. + +**Ziel-Hosts**: `all` + +**Benutzer**: `tincadmin` (mit sudo-Rechten) + +**Verwendete Rollen**: +- `docker` (Tasks: `get-containerstatus`, `cleanup-images`) + +**Wichtige Variablen**: + +| Variable | Default | Beschreibung | +|----------|---------|-------------| +| `docker_compose_path` | `/opt/mailcow-dockerized` | Pfad zum Docker-Compose-Projekt | + +**Verwendungsbeispiel**: + +```bash +# Cleanup für alle Hosts +ansible-playbook playbooks/docker/cleanup-images.yml \ + -i inventories/icp-fra-pve1.yml \ + -K + +# Mit custom Compose-Pfad +ansible-playbook playbooks/docker/cleanup-images.yml \ + -i inventories/extern.yml \ + -e "docker_compose_path=/opt/my-app" \ + -K + +# Nur auf spezifischem Host +ansible-playbook playbooks/docker/cleanup-images.yml \ + -i inventories/icp-fra-pve1.yml \ + --limit mail-server-01.example.com \ + -K +``` + +**Abhängigkeiten**: +- Docker-Installation +- Docker-Compose (falls Compose-Projekt) + +**Besonderheiten**: +- **Statischer Mailcow-Pfad** - Standard ist `/opt/mailcow-dockerized` +- Entfernt nur ungenutzte Images (keine aktiven Container betroffen) +- Prüft Container-Status vor Cleanup + +**Workflow**: +1. Überprüft Status aller Container im Compose-Projekt +2. Identifiziert ungenutzte Images +3. Entfernt ungenutzte Images +4. Gibt Speicherplatz frei + +**⚠️ Hinweis**: Stopped Container und deren Images werden nicht entfernt. Nur vollständig ungenutzte Images. + +--- + +### docker/cleanup-all.yml + +Vollständige Docker-Bereinigung (Container, Images, Volumes, Networks). + +**Datei**: `playbooks/docker/cleanup-all.yml` + +**Zweck**: Umfassende Bereinigung von Docker-Ressourcen auf Mailcow-Hosts, nur wenn alle Container laufen. + +**Ziel-Hosts**: `all` (mit Mailcow) + +**Benutzer**: `tincadmin` (mit sudo-Rechten) + +**Verwendete Rollen**: +- `managed-mailcow` (Task: `find-mailcow-composedir`) +- `docker` (Tasks: `get-containerstatus`, `cleanup-all`) + +**Wichtige Variablen**: + +| Variable | Beschreibung | +|----------|-------------| +| `docker_compose_path` | Wird dynamisch aus Mailcow-Directory ermittelt | + +**Verwendungsbeispiel**: + +```bash +# Vollständiges Cleanup auf Mailcow-Hosts +ansible-playbook playbooks/docker/cleanup-all.yml \ + -i inventories/extern.yml \ + -K + +# Mit Debug-Ausgabe +ansible-playbook playbooks/docker/cleanup-all.yml \ + -i inventories/icp-fra-pve1.yml \ + -v \ + -K +``` + +**Abhängigkeiten**: +- Vorhandene Mailcow-Installation +- Alle Container müssen laufen (Sicherheitsbedingung) + +**Besonderheiten**: +- **Conditional Cleanup**: Nur wenn alle Container aktiv sind +- **Bedingung**: `not 'false' in container_status.values()` +- Dynamische Pfaderkennung über `managed-mailcow` Rolle +- Entfernt: + - Stopped Container + - Ungenutzte Images + - Ungenutzte Volumes + - Ungenutzte Networks + +**Workflow**: +1. Findet Mailcow-Compose-Directory +2. Prüft Status aller Container +3. **Abbruch** wenn Container nicht laufen +4. Führt vollständiges Cleanup durch: + - `docker system prune -a` + - `docker volume prune` + - `docker network prune` + +**⚠️ Warnung**: Dieses Playbook ist aggressiv und entfernt alle ungenutzten Ressourcen. Verwenden Sie es nur, wenn Sie sicher sind, dass alle gewünschten Container laufen. + +--- + +## Rollen + +### Rolle: docker + +**Zweck**: Verwaltung von Docker-Containern, Images und Daemon-Konfiguration. + +**Pfad**: `roles/docker/` + +**Hauptaufgaben**: + +#### 1. install-docker.yml +Installiert Docker von offiziellem Repo oder tinc-Mirror. + +**Funktionen**: +- Fügt Docker GPG-Signatur-Key hinzu +- Konfiguriert Docker APT-Repository +- Installiert Docker CE, CLI und containerd +- Konfiguriert Docker-Daemon mit Proxy (optional) + +**Variablen**: +```yaml +docker_install_source: "official" # oder "tinc" +``` + +#### 2. cleanup-images.yml +Entfernt ungenutzte Docker-Images. + +**Funktionen**: +- Verwendet `docker image prune -a` +- Bereinigt dangling Images +- Gibt Speicherplatz frei + +**Verwendung**: +```yaml +- include_role: + name: docker + tasks_from: cleanup-images.yml +``` + +#### 3. cleanup-all.yml +Vollständige Bereinigung aller Docker-Ressourcen. + +**Funktionen**: +- Entfernt stopped Container +- Löscht ungenutzte Images +- Bereinigt Volumes +- Entfernt ungenutzte Networks + +**Verwendung**: +```yaml +- include_role: + name: docker + tasks_from: cleanup-all.yml +``` + +#### 4. get-containerstatus.yml +Prüft Status von Docker-Compose-Containern. + +**Funktionen**: +- Liest `docker-compose ps` +- Erstellt Status-Dictionary +- Prüft ob Container running sind + +**Ausgabe**: +```yaml +container_status: + nginx-mailcow: true + mysql-mailcow: true + postfix-mailcow: false # nicht laufend +``` + +**Verwendung**: +```yaml +- include_role: + name: docker + tasks_from: get-containerstatus.yml + vars: + docker_compose_path: /opt/mailcow-dockerized +``` + +#### 5. restart-daemon.yml +Startet Docker-Daemon neu. + +**Funktionen**: +- Reload systemd +- Restart Docker-Service +- Wartet auf Verfügbarkeit + +**Verwendung**: +```yaml +- include_role: + name: docker + tasks_from: restart-daemon.yml +``` + +**Standard-Variablen**: + +Die Rolle selbst hat keine `defaults/main.yml`, aber verwendet Variablen aus `group_vars/all.yml`: + +```yaml +use_docker_image_mirror: true +docker_mirror_location: "SC" # oder "tinc" +docker_install_source: "official" +``` + +**Abhängigkeiten** (`requirements.yml`): + +```yaml +collections: + - name: community.docker + version: "3.11.0" +``` + +**Installation**: +```bash +ansible-galaxy collection install -r roles/docker/requirements.yml +``` + +--- + +## Docker-Image-Proxy/Mirror + +### Konfiguration + +Für schnellere Docker-Pulls in internen Netzwerken kann ein Image-Proxy konfiguriert werden. + +**Siehe auch**: [Mail-Server-Verwaltung → use-docker-image-proxy.yaml](04-Mail-Server-Verwaltung.md#use-docker-image-proxyyaml) + +**Vorteile**: +- Reduzierte Bandbreitennutzung +- Schnellere Image-Downloads +- Caching häufig genutzter Images +- Rate-Limit-Vermeidung bei Docker Hub + +**Konfiguration in group_vars/all.yml**: + +```yaml +# Docker Mirror Configuration +use_docker_image_mirror: true +docker_mirror_location: "SC" # ServerCow Mirror + +# Proxy Settings +docker_proxy_host: "dim.servercow.com" +docker_proxy_port: 3128 +``` + +--- + +## Best Practices + +### 1. Regelmäßiges Cleanup + +Führen Sie wöchentliches Image-Cleanup durch: +```bash +# Jeden Sonntag via Cron +0 2 * * 0 ansible-playbook /path/to/playbooks/docker/cleanup-images.yml \ + -i /path/to/inventories/all.yml +``` + +### 2. Vor Major-Updates + +Cleanup vor großen Updates für Speicherplatz: +```bash +ansible-playbook playbooks/docker/cleanup-all.yml \ + -i inventories/icp-fra-pve1.yml \ + -K +``` + +### 3. Image-Mirror verwenden + +Nutzen Sie interne Mirrors für schnellere Pulls: +```yaml +# In group_vars/all.yml +use_docker_image_mirror: true +docker_mirror_location: "tinc" +``` + +### 4. Container-Status überwachen + +Vor Cleanup immer Container-Status prüfen: +```bash +# Manuell auf Host +docker ps -a +docker-compose ps + +# Via Ansible +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "docker ps --format '{{.Names}}: {{.Status}}'" +``` + +### 5. Speicherplatz-Monitoring + +Überwachen Sie Docker-Speicherverbrauch: +```bash +# Auf Host +docker system df + +# Via Ansible +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "docker system df" +``` + +--- + +## Fehlerbehebung + +### Problem: Docker-Installation schlägt fehl + +**Symptome**: APT kann Docker-Repository nicht erreichen + +**Lösung**: +1. Überprüfen Sie Internet-Verbindung +2. Testen Sie Repository-Erreichbarkeit: + ```bash + curl -fsSL https://download.docker.com/linux/debian/gpg + ``` +3. Verwenden Sie tinc-Mirror als Alternative: + ```bash + -e "docker_install_source=tinc" + ``` + +### Problem: Cleanup entfernt benötigte Images + +**Symptome**: Nach Cleanup fehlen Images für laufende Container + +**Lösung**: +- Dies sollte nicht passieren, da `cleanup-all.yml` nur bei laufenden Containern ausgeführt wird +- Restore aus Backup oder re-pull Images: + ```bash + cd /opt/mailcow-dockerized + docker-compose pull + docker-compose up -d + ``` + +### Problem: Kein Speicherplatz freigegeben + +**Symptome**: `docker system df` zeigt immer noch hohe Nutzung + +**Lösung**: +1. Überprüfen Sie Volumes: + ```bash + docker volume ls + docker volume prune + ``` +2. Überprüfen Sie Build-Cache: + ```bash + docker builder prune -a + ``` +3. Manuelle vollständige Bereinigung: + ```bash + docker system prune -a --volumes + ``` + +### Problem: Docker-Daemon startet nicht + +**Symptome**: `systemctl status docker` zeigt Failed + +**Lösung**: +1. Überprüfen Sie Logs: + ```bash + journalctl -u docker.service -n 50 + ``` +2. Überprüfen Sie Daemon-Konfiguration: + ```bash + cat /etc/docker/daemon.json + ``` +3. Starten Sie Daemon neu: + ```bash + systemctl restart docker + ``` + +### Problem: Container-Status-Prüfung fehlgeschlagen + +**Symptome**: `get-containerstatus` Task schlägt fehl + +**Lösung**: +1. Überprüfen Sie docker-compose.yml: + ```bash + cd /opt/mailcow-dockerized + docker-compose config + ``` +2. Überprüfen Sie ob Docker-Compose installiert ist: + ```bash + docker-compose --version + ``` + +--- + +## Externe Abhängigkeiten + +### Community Docker Collection + +**Installation**: +```bash +ansible-galaxy collection install community.docker:3.11.0 +``` + +**Dokumentation**: +- https://docs.ansible.com/ansible/latest/collections/community/docker/ +- https://galaxy.ansible.com/community/docker + +**Verwendete Module**: +- `community.docker.docker_image` +- `community.docker.docker_container` +- `community.docker.docker_prune` +- `community.docker.docker_compose` + +--- + +## Nützliche Kommandos + +### Docker-Informationen abrufen + +```bash +# Speichernutzung +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "docker system df -v" \ + -b + +# Laufende Container +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Image}}'" \ + -b + +# Docker-Version +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "docker version --format '{{.Server.Version}}'" \ + -b +``` + +### Manuelle Bereinigung + +```bash +# Auf spezifischem Host +ssh tincadmin@host.example.com +sudo docker system prune -a --volumes +sudo docker image ls +sudo docker volume ls +``` + +--- + +**Navigation**: [← Zurück: Monitoring](02-Monitoring.md) | [Nächstes: Mail-Server-Verwaltung →](04-Mail-Server-Verwaltung.md) diff --git a/docs/04-Mail-Server-Verwaltung.md b/docs/04-Mail-Server-Verwaltung.md new file mode 100644 index 0000000..2598f44 --- /dev/null +++ b/docs/04-Mail-Server-Verwaltung.md @@ -0,0 +1,1069 @@ +# 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 + ``` +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 | 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) diff --git a/docs/05-Security-Hardening.md b/docs/05-Security-Hardening.md new file mode 100644 index 0000000..71fcc18 --- /dev/null +++ b/docs/05-Security-Hardening.md @@ -0,0 +1,532 @@ +# Security & Hardening + +## Übersicht + +Diese Kategorie umfasst Playbooks und Rollen zur Verbesserung der Systemsicherheit, insbesondere SSH-Zugriffsverwaltung und Härtung. + +**Anwendungsfälle**: +- Verwaltung autorisierter SSH-Schlüssel +- Entfernung kompromittierter oder veralteter Schlüssel +- SSH-Zugriffskontrolle über Whitelisting und Blacklisting +- Zentrale SSH-Schlüssel-Verwaltung über mehrere Hosts + +--- + +## Playbooks + +### hardening/manage-ssh-keys.yaml + +Verwaltung von SSH-Schlüsseln für Systemzugriff (Hinzufügen/Entfernen). + +**Datei**: `playbooks/hardening/manage-ssh-keys.yaml` + +**Zweck**: Zentrale Verwaltung von SSH-Public-Keys mit Whitelisting (erlaubte Schlüssel) und Blacklisting (zu entfernende Schlüssel) auf allen verwalteten Hosts. + +**Ziel-Hosts**: `all` + +**Benutzer**: `tincadmin` (mit sudo-Rechten) + +**Verwendete Rollen**: +- `manage-ssh-keys` + +**Wichtige Variablen**: + +| Variable | Typ | Beschreibung | +|----------|-----|-------------| +| `good_keys` | Liste | Autorisierte SSH-Public-Keys (werden hinzugefügt) | +| `bad_keys` | Liste | Zu entfernende SSH-Public-Keys (Blacklist) | +| `ssh_user` | String | Zielbenutzer für SSH-Schlüssel (Default: `root`) | + +**Verwendungsbeispiel**: + +```bash +# Mit Variablen aus Rolle (defaults/main.yml) +ansible-playbook playbooks/hardening/manage-ssh-keys.yaml \ + -i inventories/icp-fra-pve1.yml \ + -K + +# Mit externen Variablen (JSON-Format) +ansible-playbook playbooks/hardening/manage-ssh-keys.yaml \ + -i inventories/icp-fra-pve1.yml \ + -e '{"good_keys": ["ssh-ed25519 AAAA... user@host"]}' \ + -e '{"bad_keys": ["ssh-rsa AAAA... old-key"]}' \ + -K + +# Nur auf einzelnem Host +ansible-playbook playbooks/hardening/manage-ssh-keys.yaml \ + -i inventories/icp-fra-pve1.yml \ + --limit critical-server.example.com \ + -K + +# Für spezifischen User (nicht root) +ansible-playbook playbooks/hardening/manage-ssh-keys.yaml \ + -i inventories/icp-fra-pve1.yml \ + -e "ssh_user=tincadmin" \ + -K +``` + +**Abhängigkeiten**: +- `manage-ssh-keys` Rolle +- Sudo-Rechte auf Zielhosts +- SSH-Zugriff zu Hosts + +**Besonderheiten**: +- **Kommentierte Variablen** für externe Übergabe im Playbook +- **Validierung** von Schlüsseln vor Anwendung +- **Idempotent**: Mehrfache Ausführung sicher +- **Atomare Operationen**: Erst Validierung, dann Änderung +- **Automatisches Backup**: Vor jeder Änderung + +**Workflow**: +1. Validiert SSH-Schlüssel-Format (good_keys und bad_keys) +2. Überprüft `.ssh`-Verzeichnis-Existenz (erstellt falls nötig) +3. Entfernt Schlüssel aus Blacklist (`bad_keys`) +4. Fügt Schlüssel aus Whitelist (`good_keys`) hinzu +5. Bereinigt Kommentare in authorized_keys +6. Fügt Änderungs-Timestamp hinzu + +**Sicherheitsaspekte**: +- ✅ Whitelisting-Ansatz (explizite Erlaubnis) +- ✅ Blacklisting für Revokation kompromittierter Schlüssel +- ✅ Automatische Bereinigung alter Einträge +- ✅ Audit-Trail durch Timestamps +- ✅ Validierung verhindert fehlerhafte Schlüssel + +--- + +## Rollen + +### Rolle: manage-ssh-keys + +**Zweck**: Verwaltet SSH-Schlüssel mit Whitelisting und Blacklisting-Mechanismen für sicheren Systemzugriff. + +**Pfad**: `roles/manage-ssh-keys/` + +**Hauptaufgaben**: + +#### 1. validate-keys.yml +Stellt sicher, dass `.ssh`-Verzeichnis existiert und korrekte Berechtigungen hat. + +**Funktionen**: +- Erstellt `.ssh`-Verzeichnis (falls nicht vorhanden) +- Setzt Berechtigungen: `0700` (nur Owner kann lesen/schreiben/ausführen) +- Erstellt `authorized_keys`-Datei (falls nicht vorhanden) +- Setzt Berechtigungen für `authorized_keys`: `0600` + +**Ausgeführt für User**: +```yaml +ssh_user: "root" # Standard, kann überschrieben werden +``` + +#### 2. add-goodkeys.yml +Fügt autorisierte SSH-Public-Keys hinzu. + +**Funktionen**: +- Iteriert über `good_keys`-Liste +- Fügt jeden Schlüssel zu `authorized_keys` hinzu +- Verhindert Duplikate (idempotent) +- Verwendet `authorized_key`-Modul von Ansible + +**Beispiel good_keys**: +```yaml +good_keys: + - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleKey1 admin@workstation" + - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC... admin@laptop" +``` + +#### 3. remove-badkeys.yml +Entfernt nicht autorisierte oder kompromittierte Schlüssel. + +**Funktionen**: +- Iteriert über `bad_keys`-Liste +- Entfernt jeden Schlüssel aus `authorized_keys` +- Verwendet `absent`-State in `authorized_key`-Modul +- Sicher bei nicht vorhandenen Schlüsseln (idempotent) + +**Beispiel bad_keys**: +```yaml +bad_keys: + - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC... old-compromised-key" + - "ssh-dss AAAAB3NzaC1kc3MAAACBAP... deprecated-dsa-key" +``` + +**Standardvariablen** (`defaults/main.yml`): + +```yaml +# User für SSH-Schlüsselverwaltung +ssh_user: "root" + +# Pfad zu authorized_keys +authorized_keys_file: "/{{ ssh_user }}/.ssh/authorized_keys" + +# Whitelist: Autorisierte SSH-Schlüssel (ca. 20+ Schlüssel) +good_keys: + - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleKey1" + - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExampleKey2" + - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQC..." + # ... weitere autorisierte Schlüssel + +# Blacklist: Zu entfernende Schlüssel (6+ revozierte Schlüssel) +bad_keys: + - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC... old-key-1" + - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQD... compromised-key" + # ... weitere zu entfernende Schlüssel +``` + +**Handler**: + +| Handler | Funktion | +|---------|----------| +| `Cleanup Comments` | Entfernt alte Kommentare aus authorized_keys | +| `Add Comment` | Fügt Änderungs-Timestamp hinzu | + +**Verwendung in Playbooks**: + +```yaml +# Vollständige Rolle +- name: Manage SSH Keys + hosts: all + become: true + roles: + - manage-ssh-keys + +# Mit custom Variablen +- name: Manage SSH Keys for tincadmin user + hosts: all + become: true + roles: + - role: manage-ssh-keys + vars: + ssh_user: tincadmin + good_keys: + - "ssh-ed25519 AAAAC3... new-admin-key" + bad_keys: + - "ssh-rsa AAAAB3... old-admin-key" + +# Einzelne Tasks +- name: Add authorized keys only + include_role: + name: manage-ssh-keys + tasks_from: add-goodkeys.yml +``` + +--- + +## SSH-Schlüssel-Typen + +### Empfohlene Schlüsseltypen (2026) + +| Typ | Sicherheit | Empfehlung | Verwendung in Projekt | +|-----|------------|------------|----------------------| +| **Ed25519** | ⭐⭐⭐⭐⭐ Höchste | ✅ Bevorzugt | Ja (~15+ Schlüssel) | +| **RSA 4096** | ⭐⭐⭐⭐ Hoch | ✅ Akzeptabel | Ja (~5+ Schlüssel) | +| **ECDSA** | ⭐⭐⭐ Mittel | ⚠️ Mäßig | Nicht im Projekt | +| **RSA 2048** | ⭐⭐ Niedrig | ⚠️ Veraltet | Einige Legacy-Keys | +| **DSA** | ⭐ Sehr niedrig | ❌ Deprecated | Sollte entfernt werden | + +### Schlüssel-Generierung + +**Ed25519 (empfohlen)**: +```bash +ssh-keygen -t ed25519 -C "admin@workstation-$(date +%Y%m%d)" +``` + +**RSA 4096**: +```bash +ssh-keygen -t rsa -b 4096 -C "admin@workstation-$(date +%Y%m%d)" +``` + +--- + +## Best Practices + +### 1. Regelmäßiges Key-Rotation + +Erneuern Sie SSH-Schlüssel regelmäßig: +```bash +# Quartalsweise +ansible-playbook playbooks/hardening/manage-ssh-keys.yaml \ + -i inventories/icp-fra-pve1.yml \ + -e '{"good_keys": [...neue Schlüssel...]}' \ + -e '{"bad_keys": [...alte Schlüssel...]}' \ + -K +``` + +### 2. Zentrale Schlüsselverwaltung + +Pflegen Sie `good_keys` und `bad_keys` in: +- `roles/manage-ssh-keys/defaults/main.yml` (Standard) +- Externe Variablendateien für verschiedene Umgebungen +- Vault-Datei für sensible Schlüssel + +### 3. Audit-Trail + +Dokumentieren Sie Schlüssel-Änderungen: +```bash +# Vor Änderung: Backup erstellen +ansible all -i inventories/icp-fra-pve1.yml \ + -m fetch \ + -a "src=/root/.ssh/authorized_keys dest=/backup/ssh-keys/{{ inventory_hostname }}-{{ ansible_date_time.date }}" \ + -b + +# Änderung durchführen +ansible-playbook playbooks/hardening/manage-ssh-keys.yaml ... + +# Verifizierung +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "wc -l /root/.ssh/authorized_keys" \ + -b +``` + +### 4. Kompromittierte Schlüssel sofort entfernen + +Bei Sicherheitsvorfällen: +```bash +# Notfall-Entfernung kompromittierter Schlüssel +ansible-playbook playbooks/hardening/manage-ssh-keys.yaml \ + -i inventories/all.yml \ + -e '{"bad_keys": ["ssh-rsa AAAA... KOMPROMITTIERT"]}' \ + -K +``` + +### 5. Test auf Non-Production zuerst + +```bash +# Test auf einzelnem Host +ansible-playbook playbooks/hardening/manage-ssh-keys.yaml \ + -i inventories/icp-fra-pve1.yml \ + --limit test-host.example.com \ + -e '{"good_keys": [...]}' \ + -K + +# Nach Verifizierung: Rollout +ansible-playbook playbooks/hardening/manage-ssh-keys.yaml \ + -i inventories/icp-fra-pve1.yml \ + -K +``` + +### 6. Mehrfache Admin-Keys + +Verwenden Sie mehrere Admin-Schlüssel für Redundanz: +```yaml +good_keys: + - "ssh-ed25519 ... primary-admin@workstation" + - "ssh-ed25519 ... secondary-admin@laptop" + - "ssh-ed25519 ... emergency-admin@spare" +``` + +--- + +## SSH-Daemon-Härtung + +Während dieses Playbook die Schlüssel verwaltet, sollten Sie auch SSH-Daemon-Konfiguration härten. + +### Empfohlene sshd_config-Einstellungen + +```ini +# /etc/ssh/sshd_config + +# Nur Public-Key-Authentifizierung +PubkeyAuthentication yes +PasswordAuthentication no +ChallengeResponseAuthentication no + +# Kein Root-Login mit Passwort +PermitRootLogin prohibit-password + +# Moderne Krypto-Algorithmen +KexAlgorithms curve25519-sha256,curve25519-sha256@libssh.org +Ciphers chacha20-poly1305@openssh.com,aes256-gcm@openssh.com,aes128-gcm@openssh.com +MACs hmac-sha2-512-etm@openssh.com,hmac-sha2-256-etm@openssh.com + +# Weitere Härtungen +PermitEmptyPasswords no +X11Forwarding no +MaxAuthTries 3 +LoginGraceTime 20 +``` + +### Anwendung mit Ansible + +**Siehe**: [`system` Rolle → ssh-hardening.yaml](07-Basis-System.md#rolle-system) + +```bash +# SSH-Daemon härten (falls implementiert in system Rolle) +ansible-playbook playbooks/hardening/harden-sshd.yml \ + -i inventories/icp-fra-pve1.yml \ + -K +``` + +--- + +## Fehlerbehebung + +### Problem: Aussperrung nach Schlüssel-Entfernung + +**Symptome**: Kein SSH-Zugriff mehr nach Ausführung + +**Prävention**: +1. **Immer** mindestens einen funktionierenden Schlüssel in `good_keys` behalten +2. Testen Sie auf einzelnem Host zuerst (`--limit`) +3. Halten Sie Console-Zugriff bereit (z.B. Proxmox VNC) + +**Lösung bei Aussperrung**: +1. Zugriff über Console (Proxmox, IPMI, etc.) +2. Manuelle Wiederherstellung: + ```bash + # Via Console + echo "ssh-ed25519 AAAA... emergency-key" >> /root/.ssh/authorized_keys + ``` +3. Führen Sie Playbook erneut aus mit korrekten Schlüsseln + +### Problem: Schlüssel werden nicht hinzugefügt + +**Symptome**: `good_keys` werden nicht in authorized_keys eingetragen + +**Lösung**: +1. Überprüfen Sie Schlüssel-Format: + ```bash + ssh-keygen -l -f /path/to/public_key.pub + ``` +2. Überprüfen Sie Berechtigungen: + ```bash + ansible all -i inventories/... \ + -m shell -a "ls -la /root/.ssh/" \ + -b + ``` +3. Führen Sie validate-keys Task manuell aus: + ```yaml + - include_role: + name: manage-ssh-keys + tasks_from: validate-keys.yml + ``` + +### Problem: Handler werden nicht ausgeführt + +**Symptome**: Timestamps oder Kommentare fehlen + +**Lösung**: +- Handler laufen erst am Ende des Plays +- Erzwingen Sie Handler-Ausführung: + ```yaml + - meta: flush_handlers + ``` +- Oder führen Sie Playbook mit `--force-handlers` aus + +### Problem: Unterschiedliche Schlüssel pro Umgebung + +**Symptome**: Dev/Prod benötigen verschiedene Schlüssel-Sets + +**Lösung**: +Verwenden Sie separate Variablendateien: + +```bash +# Development +ansible-playbook playbooks/hardening/manage-ssh-keys.yaml \ + -i inventories/dev.yml \ + -e "@vars/ssh-keys-dev.yml" \ + -K + +# Production +ansible-playbook playbooks/hardening/manage-ssh-keys.yaml \ + -i inventories/prod.yml \ + -e "@vars/ssh-keys-prod.yml" \ + -K +``` + +**vars/ssh-keys-prod.yml**: +```yaml +good_keys: + - "ssh-ed25519 ... prod-admin-1" + - "ssh-ed25519 ... prod-admin-2" +bad_keys: + - "ssh-rsa ... old-dev-key" +``` + +--- + +## Compliance und Audit + +### DSGVO / Datenschutz + +SSH-Schlüssel-Management unterstützt Compliance durch: +- ✅ **Access Control**: Nur autorisierte Personen +- ✅ **Audit Trail**: Timestamps in authorized_keys +- ✅ **Revocation**: Schnelle Entfernung kompromittierter Keys +- ✅ **Least Privilege**: Spezifische User-Zuordnung + +### Audit-Kommandos + +```bash +# Liste aller autorisierten Schlüssel +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "cat /root/.ssh/authorized_keys" \ + -b + +# Zähle Schlüssel pro Host +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "wc -l /root/.ssh/authorized_keys" \ + -b + +# Prüfe auf DSA-Schlüssel (veraltet) +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "grep 'ssh-dss' /root/.ssh/authorized_keys || echo 'None found'" \ + -b + +# Letzte Änderung +ansible all -i inventories/icp-fra-pve1.yml \ + -m stat -a "path=/root/.ssh/authorized_keys" \ + -b +``` + +--- + +## Weitere Sicherheits-Maßnahmen + +Neben SSH-Schlüssel-Verwaltung gibt es weitere Härtungs-Maßnahmen im Projekt: + +### 1. Fail2Ban (nicht implementiert) +Schutz vor Brute-Force-Attacken + +### 2. UFW/Firewall (nicht implementiert) +Netzwerk-Level-Zugriffsschutz + +### 3. Sudo-Beschränkungen +Siehe `system` Rolle für zukünftige Implementierung + +### 4. SELinux/AppArmor +OS-Level Mandatory Access Control + +--- + +## Nützliche Kommandos + +### SSH-Schlüssel-Informationen abrufen + +```bash +# Alle Schlüssel auf Hosts anzeigen +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell \ + -a "cat /root/.ssh/authorized_keys | grep -v '^#' | while read line; do echo \$line | ssh-keygen -l -f - 2>/dev/null || echo 'Invalid: '\$line; done" \ + -b + +# Schlüssel-Typen zählen +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell \ + -a "cat /root/.ssh/authorized_keys | grep -v '^#' | awk '{print \$1}' | sort | uniq -c" \ + -b +``` + +### Backup erstellen + +```bash +# Backup aller authorized_keys Dateien +ansible all -i inventories/icp-fra-pve1.yml \ + -m fetch \ + -a "src=/root/.ssh/authorized_keys dest=/backup/ssh-keys/{{ inventory_hostname }}-{{ ansible_date_time.date }}/" \ + -b +``` + +--- + +**Navigation**: [← Zurück: Mail-Server-Verwaltung](04-Mail-Server-Verwaltung.md) | [Nächstes: Virtualisierung →](06-Virtualisierung.md) diff --git a/docs/06-Virtualisierung.md b/docs/06-Virtualisierung.md new file mode 100644 index 0000000..212e758 --- /dev/null +++ b/docs/06-Virtualisierung.md @@ -0,0 +1,553 @@ +# Virtualisierung (Proxmox) + +## Übersicht + +Diese Kategorie umfasst die Rolle zur Proxmox VE-Automatisierung, insbesondere für VM-Snapshot-Verwaltung. Die Proxmox-Integration wird von vielen anderen Playbooks genutzt, um Snapshots vor kritischen Operationen zu erstellen. + +**Anwendungsfälle**: +- Automatische Snapshot-Erstellung vor OS-Updates +- Automatische Snapshot-Erstellung vor Mailcow-Updates +- Snapshot-Bereinigung nach erfolgreichen Updates +- Rollback-Möglichkeit bei fehlgeschlagenen Operationen +- VM-ID-Ermittlung für API-Operationen + +**Proxmox-Cluster**: `icp-fra-pve1` (6 Hosts) + +--- + +## Verwendung in anderen Playbooks + +Die Proxmox-Automation-Rolle wird nicht direkt über dedizierte Playbooks aufgerufen, sondern als **integraler Bestandteil** anderer Playbooks verwendet: + +### Playbooks mit Proxmox-Integration + +| Playbook | Verwendung | Snapshot-Name-Muster | +|----------|------------|----------------------| +| [`os-update.yml`](01-OS-Management.md#os-updateyml) | Snapshot vor OS-Updates | `AUTO_before_os_update_{{ date }}` | +| [`os-major-upgrade.yml`](01-OS-Management.md#os-major-upgradeyml) | Snapshot vor Major-Upgrade | `AUTO_before_major_{{ date }}` | +| [`update-mailcow.yaml`](04-Mail-Server-Verwaltung.md#update-mailcowyaml) | Snapshot vor Mailcow-Update | `pre-mailcow-update-{{ version }}` | +| `cleanups/clean-pve-snapshots.yml` | Snapshot-Löschung | Alle außer "current" | + +### Beispiel-Integration in Playbook + +```yaml +- name: OS-Update mit Snapshot + hosts: all + become: true + + pre_tasks: + - name: Load vault + include_vars: ../vault.yml + when: do_snapshots | bool + + tasks: + - name: Get Proxmox VM ID + include_role: + name: proxmox-automation + tasks_from: get-vmid + when: do_snapshots | bool + + - name: Create pre-update snapshot + include_role: + name: proxmox-automation + tasks_from: create-snapshots + vars: + snapshot_name: "AUTO_before_update_{{ ansible_date_time.date }}" + when: do_snapshots | bool + + # ... Update-Tasks ... +``` + +--- + +## Rollen + +### Rolle: proxmox-automation + +**Zweck**: Automatisiert Proxmox VE VM-Verwaltung, primär für Snapshot-Operationen. + +**Pfad**: `roles/proxmox-automation/` + +**Hauptaufgaben**: + +#### 1. get-vmid.yaml + +Ermittelt die Proxmox VM-ID für den aktuellen Host. + +**Funktionen**: +- Verwendet Proxmox API zur VM-ID-Ermittlung +- Sucht nach VM mit passendem Hostname +- Setzt `proxmox_vmid` Fact für weitere Operationen +- Delegiert zu localhost (API-Aufruf) + +**Benötigte Variablen**: +```yaml +proxmox_host: "pve-cluster.example.com" +proxmox_user: "automation@pve" +proxmox_token_id: "ansible" +proxmox_token_secret: "" +``` + +**Verwendung**: +```yaml +- include_role: + name: proxmox-automation + tasks_from: get-vmid +``` + +**Output**: +```yaml +proxmox_vmid: 100 # VM-ID des aktuellen Hosts +``` + +**API-Endpunkt**: `GET /api2/json/cluster/resources?type=vm` + +--- + +#### 2. create-snapshots.yaml + +Erstellt VM-Snapshots mit automatischer Retention (behält letzten 2). + +**Funktionen**: +- Erstellt benannten Snapshot der VM +- Löscht alte Snapshots automatisch +- **Retention**: Behält nur die letzten 2 Snapshots +- Wartet auf Snapshot-Completion +- Delegiert zu localhost (API-Aufruf) + +**Benötigte Variablen**: +```yaml +snapshot_name: "pre-update-2026-04-14" +proxmox_vmid: 100 # Aus get-vmid Task +proxmox_host: "pve-cluster.example.com" +proxmox_user: "automation@pve" +proxmox_token_id: "ansible" +proxmox_token_secret: "" +``` + +**Verwendung**: +```yaml +- include_role: + name: proxmox-automation + tasks_from: create-snapshots + vars: + snapshot_name: "my-snapshot-{{ ansible_date_time.date }}" +``` + +**Snapshot-Retention-Logik**: +1. Listet alle existierenden Snapshots auf +2. Sortiert nach Erstellungsdatum +3. Löscht alle außer den letzten 2 +4. Erstellt neuen Snapshot +5. Wartet auf Completion + +**API-Endpunkte**: +- `GET /api2/json/nodes/{node}/qemu/{vmid}/snapshot` +- `POST /api2/json/nodes/{node}/qemu/{vmid}/snapshot` +- `DELETE /api2/json/nodes/{node}/qemu/{vmid}/snapshot/{snapname}` + +**⚠️ Wichtig**: Die Retention von 2 Snapshots ist hardcoded. Ältere Snapshots werden **automatisch gelöscht**. + +--- + +#### 3. delete-snapshots.yaml + +Löscht alle Snapshots außer "current" (aktiver Zustand). + +**Funktionen**: +- Listet alle Snapshots einer VM auf +- Löscht alle Snapshots außer "current" +- Useful für Cleanup nach erfolgreichen Updates +- Delegiert zu localhost (API-Aufruf) + +**Benötigte Variablen**: +```yaml +proxmox_vmid: 100 +proxmox_host: "pve-cluster.example.com" +proxmox_user: "automation@pve" +proxmox_token_id: "ansible" +proxmox_token_secret: "" +``` + +**Verwendung**: +```yaml +- include_role: + name: proxmox-automation + tasks_from: delete-snapshots +``` + +**Workflow**: +1. Abruft alle Snapshots der VM +2. Filtert "current" aus (wird nicht gelöscht) +3. Iteriert über verbleibende Snapshots +4. Löscht jeden Snapshot +5. Wartet auf Completion + +**API-Endpunkte**: +- `GET /api2/json/nodes/{node}/qemu/{vmid}/snapshot` +- `DELETE /api2/json/nodes/{node}/qemu/{vmid}/snapshot/{snapname}` + +**Verwendung**: Siehe [Cleanup-Aufgaben → clean-pve-snapshots.yml](08-Cleanup-Aufgaben.md#clean-pve-snapshotsyml) + +--- + +## Vault-Konfiguration + +### Erforderliche Variablen in vault.yml + +```yaml +# Proxmox API Credentials +proxmox_host: "pve-cluster.example.com" +proxmox_user: "automation@pve" +proxmox_token_id: "ansible" +proxmox_token_secret: "" +``` + +### Proxmox API-Token erstellen + +1. **Login to Proxmox Web Interface** +2. **Datacenter → Permissions → API Tokens** +3. **Add API Token**: + - User: `automation@pve` (erstellen falls nicht vorhanden) + - Token ID: `ansible` + - Privilege Separation: **Unchecked** (Token hat alle User-Rechte) + - Expire: Nie oder lang genug +4. **Kopieren Sie den Secret** (nur einmal sichtbar!) +5. **Speichern Sie in vault.yml** + +### Benötigte Proxmox-Berechtigungen + +Der Automation-User benötigt folgende Berechtigungen: + +| Pfad | Berechtigung | Zweck | +|------|--------------|-------| +| `/vms` | `VM.Snapshot` | Snapshots erstellen/löschen | +| `/vms` | `VM.Audit` | VM-Informationen lesen | +| `/` | `Sys.Audit` | Cluster-Ressourcen lesen | + +**Minimale Berechtigung**: +```bash +# Via Proxmox CLI +pveum role add AutomationRole -privs "VM.Snapshot,VM.Audit,Sys.Audit" +pveum aclmod / -user automation@pve -role AutomationRole +``` + +--- + +## Externe Abhängigkeiten + +### Community Proxmox Collection + +**Installation**: +```bash +ansible-galaxy collection install community.proxmox:1.5.0 +``` + +**In requirements.yml**: +```yaml +collections: + - name: community.proxmox + version: "1.5.0" +``` + +**Installation via requirements**: +```bash +ansible-galaxy collection install -r roles/proxmox-automation/requirements.yml +``` + +### Verwendete Module + +- `community.general.proxmox_snap`: Snapshot-Verwaltung +- `community.general.proxmox`: VM-Informationen +- `ansible.builtin.uri`: Für direkte API-Aufrufe + +**Dokumentation**: +- https://docs.ansible.com/ansible/latest/collections/community/general/proxmox_snap_module.html +- https://pve.proxmox.com/wiki/Proxmox_VE_API + +--- + +## Best Practices + +### 1. Snapshots nur bei kritischen Operationen + +Aktivieren Sie Snapshots für: +- ✅ OS Major-Upgrades +- ✅ Mailcow-Updates (große Versionssprünge) +- ✅ Konfigurationsänderungen an kritischen Services +- ❌ Nicht für tägliche OS-Updates (außer bei kritischen Systemen) + +```bash +# Mit Snapshots +ansible-playbook playbooks/os-major-upgrade.yml \ + -e "do_snapshots=true" \ + ... + +# Ohne Snapshots (schneller, aber riskanter) +ansible-playbook playbooks/os-update.yml \ + -e "do_snapshots=false" \ + ... +``` + +### 2. Aussagekräftige Snapshot-Namen + +Verwenden Sie beschreibende Namen: +```yaml +# Gut +snapshot_name: "pre-mailcow-update-2026-03b" +snapshot_name: "before-debian-trixie-upgrade" +snapshot_name: "AUTO_before_major_2026-04-14" + +# Schlecht +snapshot_name: "snapshot1" +snapshot_name: "backup" +``` + +### 3. Regelmäßiges Snapshot-Cleanup + +Bereinigen Sie alte Snapshots nach erfolgreichen Updates: +```bash +# Nach erfolgreichem Update +ansible-playbook playbooks/cleanups/clean-pve-snapshots.yml \ + -i inventories/icp-fra-pve1.yml \ + -K --ask-vault-pass +``` + +### 4. Snapshot-Retention beachten + +Die Rolle behält automatisch nur die **letzten 2 Snapshots**. Planen Sie entsprechend: +- Tag 1: Snapshot A (vor Update 1) +- Tag 2: Snapshot B (vor Update 2) → Snapshot A bleibt +- Tag 3: Snapshot C (vor Update 3) → Snapshot A wird gelöscht, B bleibt + +### 5. Storage-Kapazität überwachen + +Snapshots benötigen Speicherplatz: +```bash +# Proxmox Storage-Nutzung prüfen +pvesm status + +# Pro VM Snapshot-Größe +qm listsnapshot +``` + +### 6. Snapshot-Limits beachten + +Proxmox hat keine harte Snapshot-Anzahl-Begrenzung, aber: +- ⚠️ Zu viele Snapshots degradieren Performance +- ⚠️ Snapshots sind keine Backups (auf gleichem Storage) +- ✅ Maximale Empfehlung: 5-10 Snapshots pro VM + +--- + +## Snapshot-Rollback + +### Manuelle Rollback über Proxmox Web-Interface + +1. **VM auswählen** in Proxmox +2. **Snapshots** Tab öffnen +3. **Gewünschten Snapshot auswählen** +4. **Rollback** klicken +5. **Bestätigen** + +**⚠️ Warnung**: Rollback überschreibt aktuellen Zustand! + +### Rollback via CLI (auf Proxmox-Host) + +```bash +# Liste Snapshots +qm listsnapshot + +# Rollback zu Snapshot +qm rollback + +# Beispiel +qm rollback 100 pre-update-2026-04-14 +``` + +### Rollback via Ansible (manuell) + +```yaml +- name: Rollback to snapshot + hosts: localhost + tasks: + - name: Proxmox Snapshot Rollback + community.general.proxmox_snap: + api_host: "{{ proxmox_host }}" + api_user: "{{ proxmox_user }}" + api_token_id: "{{ proxmox_token_id }}" + api_token_secret: "{{ proxmox_token_secret }}" + vmid: 100 + snapname: "pre-update-2026-04-14" + state: rollback +``` + +**⚠️ Wichtig**: Nach Rollback ist die VM im Zustand des Snapshots. Alle Änderungen danach gehen verloren! + +--- + +## Fehlerbehebung + +### Problem: API-Authentifizierung schlägt fehl + +**Symptome**: `401 Unauthorized` oder `403 Forbidden` + +**Lösung**: +1. Überprüfen Sie API-Token in vault.yml: + ```bash + ansible-vault view vault.yml | grep proxmox + ``` +2. Testen Sie API-Zugriff manuell: + ```bash + curl -k "https://pve-cluster.example.com:8006/api2/json/cluster/resources" \ + -H "Authorization: PVEAPIToken=automation@pve!ansible=" + ``` +3. Überprüfen Sie Benutzerberechtigungen in Proxmox + +### Problem: VM-ID kann nicht gefunden werden + +**Symptome**: `get-vmid` Task schlägt fehl + +**Lösung**: +1. Überprüfen Sie Hostname-Übereinstimmung: + ```bash + # Auf Ansible-Host + ansible -m setup -a "filter=ansible_hostname" + + # In Proxmox + # VM-Name muss mit Hostname übereinstimmen + ``` +2. Manuelle VM-ID-Ermittlung: + ```bash + pvesh get /cluster/resources --type vm + ``` +3. Setzen Sie VM-ID manuell: + ```yaml + -e "proxmox_vmid=100" + ``` + +### Problem: Snapshot-Erstellung timeout + +**Symptome**: Task hängt oder timeout nach langer Zeit + +**Lösung**: +1. Überprüfen Sie Proxmox-Storage-Performance +2. Überprüfen Sie Storage-Kapazität: + ```bash + pvesm status + ``` +3. Reduzieren Sie VM-RAM (weniger Snapshot-Größe): + - Snapshots mit RAM benötigen mehr Zeit + - Erwägen Sie `snapshots ohne RAM` (in Proxmox-Config) +4. Erhöhen Sie Ansible-Timeout: + ```yaml + async: 3600 # 1 Stunde + poll: 10 + ``` + +### Problem: Alte Snapshots werden nicht gelöscht + +**Symptome**: Mehr als 2 Snapshots vorhanden + +**Lösung**: +1. Manuelle Bereinigung: + ```bash + ansible-playbook playbooks/cleanups/clean-pve-snapshots.yml \ + -i inventories/... \ + -K --ask-vault-pass + ``` +2. Überprüfen Sie Snapshot-Liste: + ```bash + qm listsnapshot + ``` +3. Manuell löschen via CLI: + ```bash + qm delsnapshot + ``` + +### Problem: Nicht genug Speicherplatz für Snapshot + +**Symptome**: `no space left on device` + +**Lösung**: +1. Überprüfen Sie Storage-Nutzung: + ```bash + pvesm status + df -h + ``` +2. Bereinigen Sie alte Snapshots: + ```bash + # Alle VMs, alle Snapshots + for vmid in $(qm list | awk 'NR>1 {print $1}'); do + qm delsnapshot $vmid + done + ``` +3. Erweitern Sie Storage oder verschieben Sie VMs + +--- + +## Monitoring und Reporting + +### Snapshot-Übersicht abrufen + +```bash +# Via Ansible ad-hoc +ansible localhost \ + -m uri \ + -a "url=https://{{ proxmox_host }}:8006/api2/json/nodes/{{ proxmox_node }}/qemu/{{ vmid }}/snapshot headers={'Authorization':'PVEAPIToken={{ proxmox_user }}!{{ proxmox_token_id }}={{ proxmox_token_secret }}'} validate_certs=no" \ + -e @vault.yml \ + --ask-vault-pass + +# Direkt auf Proxmox-Host +pvesh get /nodes//qemu//snapshot +``` + +### Alle Snapshots im Cluster + +```bash +# Auf Proxmox-Host +for node in $(pvesh get /nodes --output-format json | jq -r '.[].node'); do + echo "=== Node: $node ===" + for vmid in $(qm list | awk 'NR>1 {print $1}'); do + echo "VM $vmid:" + qm listsnapshot $vmid + done +done +``` + +--- + +## Integration mit anderen Systemen + +### Backup-Integration + +Snapshots sind **keine Backups**! Kombinieren Sie mit echten Backups: + +1. **Proxmox Backup Server (PBS)**: Native Integration +2. **Borg/Rsync**: File-Level Backups +3. **3-2-1 Regel**: 3 Kopien, 2 Medien, 1 Offsite + +### Monitoring-Integration + +Überwachen Sie Snapshots mit CheckMK oder Prometheus: +- Anzahl Snapshots pro VM +- Alter des letzten Snapshots +- Snapshot-Größe +- Failed Snapshot-Operationen + +--- + +## Weiterführende Ressourcen + +### Proxmox-Dokumentation +- [Proxmox VE API](https://pve.proxmox.com/wiki/Proxmox_VE_API) +- [Snapshots and Backups](https://pve.proxmox.com/wiki/Storage:_Directory#_snapshots_and_backups) +- [Qemu/KVM Virtual Machines](https://pve.proxmox.com/wiki/Qemu/KVM_Virtual_Machines) + +### Ansible Collections +- [community.general.proxmox_snap](https://docs.ansible.com/ansible/latest/collections/community/general/proxmox_snap_module.html) +- [community.general Collections](https://galaxy.ansible.com/community/general) + +--- + +**Navigation**: [← Zurück: Security & Hardening](05-Security-Hardening.md) | [Nächstes: Basis-System →](07-Basis-System.md) diff --git a/docs/07-Basis-System.md b/docs/07-Basis-System.md new file mode 100644 index 0000000..50bd253 --- /dev/null +++ b/docs/07-Basis-System.md @@ -0,0 +1,779 @@ +# Basis-System + +## Übersicht + +Diese Kategorie umfasst Playbooks und Rollen für grundlegende Systemkonfiguration und Infrastruktur-Services wie ClamAV-Antivirus, Zeitsynchronisation (Chrony) und allgemeine System-Setup-Aufgaben. + +**Anwendungsfälle**: +- Installation von ClamAV-Antivirus-Server +- NTP-Zeitserver-Konfiguration (Chrony) +- Docker-Installation und -Konfiguration +- Basis-Tools-Installation +- System-Härtung +- MOTD-Konfiguration +- Admin-Benutzer-Erstellung + +--- + +## Playbooks + +### deploy-clamav-server.yml + +Bereitstellung eines dedizierten ClamAV-Antivirus-Servers. + +**Datei**: `playbooks/deploy-clamav-server.yml` + +**Zweck**: Installation und Konfiguration eines zentralen ClamAV-Servers für Antivirus-Scanning. Dieser Server wird von Mailcow-Instanzen für Malware-Scanning verwendet. + +**Ziel-Hosts**: `clamav-servers` (Inventory-Gruppe) + +**Benutzer**: `tincadmin` (mit sudo-Rechten) + +**Verwendete Rollen**: +- `deploy-clamd` + +**Verwendungsbeispiel**: + +```bash +# ClamAV-Server bereitstellen +ansible-playbook playbooks/deploy-clamav-server.yml \ + -i inventories/icp-fra-pve1.yml \ + -K + +# Mit spezifischer ClamAV-Version +ansible-playbook playbooks/deploy-clamav-server.yml \ + -i inventories/icp-fra-pve1.yml \ + -e "clamd_version=1.4.3" \ + -K +``` + +**Abhängigkeiten**: +- `deploy-clamd` Rolle +- Build-Tools (gcc, cmake, Rust) +- Internet-Zugriff für ClamAV-Source-Download + +**Besonderheiten**: +- **Kompiliert ClamAV von Source** (Version 1.4.2) +- Installiert FreshClam für Signatur-Updates +- Konfiguriert systemd-Services +- Erstellt dedizierte clamav-User/Group + +**Workflow**: +1. Installiert Build-Dependencies +2. Erstellt clamav-Benutzer und -Gruppe +3. Lädt ClamAV-Source herunter +4. Kompiliert mit CMake +5. Installiert Binärdateien +6. Konfiguriert ClamAV-Daemon +7. Konfiguriert FreshClam (Signatur-Updates) +8. Erstellt und startet systemd-Services + +**Integration**: Siehe [Mail-Server → migrate-clamd.yaml](04-Mail-Server-Verwaltung.md#migrate-clamdyaml) + +**⚠️ Hinweis**: Kompilation kann 10-20 Minuten dauern je nach System-Performance. + +--- + +### setup-chronyd.yml + +Setup des Chronyd-NTP-Zeitservers. + +**Datei**: `playbooks/setup-chronyd.yml` + +**Zweck**: Installation und Konfiguration von Chrony für präzise Zeitsynchronisation auf Debian/Ubuntu-Systemen. + +**Ziel-Hosts**: `all` (gefiltert auf Debian/Ubuntu) + +**Benutzer**: `tincadmin` (mit sudo-Rechten) + +**Verwendete Rollen**: +- `system` (Task: `setup-timeserver`) + +**Verwendungsbeispiel**: + +```bash +# Chrony auf allen Hosts installieren +ansible-playbook playbooks/setup-chronyd.yml \ + -i inventories/icp-fra-pve1.yml \ + -K + +# Auf einzelnem Host +ansible-playbook playbooks/setup-chronyd.yml \ + -i inventories/icp-fra-pve1.yml \ + --limit timeserver.example.com \ + -K +``` + +**Abhängigkeiten**: +- `system` Rolle +- Debian/Ubuntu Betriebssystem + +**Besonderheiten**: +- **Einfaches Playbook** ohne komplexe Logik +- **Deinstalliert NTPd** (falls vorhanden, Konflikt mit Chrony) +- Installiert Chrony +- Konfiguriert NTP-Pools +- Startet und aktiviert chronyd-Service + +**Workflow**: +1. Entfernt ntpd (falls installiert) +2. Installiert chrony-Paket +3. Konfiguriert NTP-Server-Pools +4. Startet chronyd-Service +5. Aktiviert Service beim Boot + +**Warum Chrony statt NTP**: +- ✅ Bessere Performance bei instabilen Verbindungen +- ✅ Schnellere Synchronisation nach Boot +- ✅ Geringerer Ressourcenverbrauch +- ✅ Moderne Alternative zu ntpd + +--- + +## Rollen + +### Rolle: deploy-clamd + +**Zweck**: Kompiliert, konfiguriert und stellt ClamAV-Antivirensoftware bereit. + +**Pfad**: `roles/deploy-clamd/` + +**Hauptaufgaben**: + +#### 1. install-dependencies.yml +Installiert Build-Tools und Abhängigkeiten. + +**Installierte Pakete**: +- Build-Essentials: `gcc`, `g++`, `make`, `cmake` +- Rust-Toolchain (für ClamAV 1.4.x) +- Python3 und pip +- Entwicklungsbibliotheken: `libssl-dev`, `libjson-c-dev`, `libpcre2-dev` +- Zusatztools: `wget`, `curl`, `pkg-config` + +**Besonderheit**: Installiert Rust über rustup (erforderlich ab ClamAV 1.4.x) + +#### 2. setup-clamav-user-group.yml +Erstellt System-Benutzer und -Gruppe für ClamAV. + +**Funktionen**: +- Erstellt Gruppe `clamav` +- Erstellt System-User `clamav` (no-login) +- Erstellt Verzeichnisse: + - `/var/lib/clamav` (Datenbank) + - `/var/log/clamav` (Logs) + - `/var/run/clamav` (PID-Files) +- Setzt korrekte Berechtigungen + +#### 3. compile-clamav.yml +Lädt ClamAV-Source herunter und kompiliert. + +**Funktionen**: +- Download von GitHub (Version 1.4.2) +- Entpackt Source +- Konfiguriert mit CMake: + ```bash + cmake . \ + -DCMAKE_INSTALL_PREFIX=/usr/local \ + -DENABLE_SYSTEMD=ON \ + -DENABLE_JSON_SHARED=ON + ``` +- Kompiliert mit `make -j$(nproc)` +- Installiert mit `make install` + +**Dauer**: 10-20 Minuten je nach CPU + +#### 4. configure-clamav.yml +Konfiguriert ClamAV-Daemon und FreshClam, erstellt systemd-Services. + +**Funktionen**: +- Generiert `clamd.conf` aus Template +- Generiert `freshclam.conf` aus Template +- Erstellt systemd-Service-Files: + - `clamav-daemon.service` + - `clamav-freshclam.service` +- Reload systemd +- Startet Services + +**Standardvariablen** (`defaults/main.yml`): + +| Variable | Default | Beschreibung | +|----------|---------|-------------| +| `clamd_version` | `1.4.2` | ClamAV-Version zum Kompilieren | + +**Templates**: + +#### clamav-config.j2 +ClamAV-Daemon-Konfiguration. + +**Wichtige Einstellungen**: +```ini +LogFile /var/log/clamav/clamd.log +LogFileMaxSize 10M +LogTime yes +LogSyslog yes + +# Scanning-Parameter +MaxThreads 4 +MaxDirectoryRecursion 15 +MaxFileSize 100M + +# Network +TCPSocket 3310 +TCPAddr 0.0.0.0 # Lauscht auf allen Interfaces +``` + +#### freshclam-config.j2 +FreshClam-Konfiguration (Virus-Signatur-Updates). + +**Wichtige Einstellungen**: +```ini +DatabaseDirectory /var/lib/clamav +LogFile /var/log/clamav/freshclam.log + +# Update-Häufigkeit +Checks 24 # 24x pro Tag (jede Stunde) + +# Update-Quellen +DatabaseMirror database.clamav.net +DatabaseMirror db.local.clamav.net + +# SecureInfo URLs für Premium-Signaturen +# (optional, falls lizenziert) +``` + +#### systemd-clamav-service.j2 +Systemd-Service für ClamAV-Daemon. + +```ini +[Unit] +Description=ClamAV Antivirus Daemon +After=network.target + +[Service] +Type=forking +ExecStart=/usr/local/sbin/clamd +Restart=on-failure +User=clamav +Group=clamav + +[Install] +WantedBy=multi-user.target +``` + +#### systemd-freshclam-service.j2 +Systemd-Service für FreshClam. + +```ini +[Unit] +Description=ClamAV Virus Database Updater +After=network.target + +[Service] +Type=simple +ExecStart=/usr/local/bin/freshclam -d +Restart=on-failure +User=clamav +Group=clamav + +[Install] +WantedBy=multi-user.target +``` + +**Handler**: + +| Handler | Funktion | +|---------|----------| +| `Reload Systemd Daemon` | Lädt systemd-Konfiguration neu | +| `Start Clamd Service` | Startet ClamAV-Daemon | +| `Start Freshclam Service` | Startet FreshClam-Service | + +**Verwendung**: + +```yaml +- name: Deploy ClamAV Server + hosts: clamav-servers + become: true + roles: + - deploy-clamd +``` + +**Weiterführende Informationen**: +- Scanning-Performance: 50-200 MB/s je nach Hardware +- RAM-Bedarf: ~1-2 GB (für Signatur-Datenbank) +- Signatur-Updates: Automatisch jede Stunde +- Network-Port: 3310 (TCP) + +--- + +### Rolle: system + +**Zweck**: Grundlegende Systemkonfiguration und Administration. + +**Pfad**: `roles/system/` + +**Hauptaufgaben**: + +#### 1. install-basic-tools.yaml +Installiert essenzielle System-Tools. + +**Installierte Pakete**: +- `git` - Versionskontrolle +- `curl`, `wget` - Download-Tools +- `vim` - Editor +- `htop` - Prozess-Monitor +- `net-tools` - Netzwerk-Tools (ifconfig, netstat) +- `tcpdump` - Netzwerk-Paket-Analyse +- `bind9-dnsutils` - DNS-Tools (dig, nslookup) +- `gnupg` - GPG-Verschlüsselung +- `sudo` - Privilege Escalation + +**Verwendung**: +```yaml +- include_role: + name: system + tasks_from: install-basic-tools +``` + +#### 2. install-docker.yaml +Installiert Docker von offiziellem Repo oder tinc-Mirror. + +**Funktionen**: +- Fügt Docker GPG-Key hinzu +- Konfiguriert Docker APT-Repository +- Installiert Docker CE, CLI, containerd +- Konfiguriert Docker-Daemon +- Startet und aktiviert Service + +**Variablen**: +```yaml +docker_install_source: "official" # oder "tinc" +``` + +**Verwendung**: +```yaml +- include_role: + name: system + tasks_from: install-docker +``` + +**Siehe auch**: [Container-Management → install-docker.yml](03-Container-Management.md#dockerinstall-dockeryml) + +#### 3. install-docker-image-mirror.yaml +Konfiguriert Docker HTTP-Proxy für Image-Mirror. + +**Funktionen**: +- Installiert CA-Zertifikat für Proxy +- Konfiguriert systemd-Override für Docker +- Setzt HTTP_PROXY, HTTPS_PROXY Environment-Variablen +- Restart Docker-Daemon + +**Variablen**: +```yaml +use_docker_image_mirror: true +docker_mirror_location: "SC" # oder "tinc" +``` + +**Proxy-Server**: +- SC (ServerCow): `dim.servercow.com:3128` +- tinc: `[2a07:6fc0:c:2809::20]:3128` + +**Verwendung**: +```yaml +- include_role: + name: system + tasks_from: install-docker-image-mirror +``` + +#### 4. setup-timeserver.yaml +Installiert und konfiguriert Chrony für NTP. + +**Funktionen**: +- Deinstalliert ntpd (Konflikt-Vermeidung) +- Installiert chrony +- Konfiguriert NTP-Pools: + - `0.debian.pool.ntp.org` + - `1.debian.pool.ntp.org` + - `2.debian.pool.ntp.org` + - `3.debian.pool.ntp.org` +- Startet und aktiviert chronyd + +**Verwendung**: +```yaml +- include_role: + name: system + tasks_from: setup-timeserver +``` + +#### 5. ssh-hardening.yaml +Ruft SSH-Schlüssel von URL ab und härtet sshd_config. + +**Funktionen**: +- Download autorisierter SSH-Keys von URL +- Konfiguriert sshd_config mit Härtung: + - `PermitRootLogin without-password` + - `PasswordAuthentication no` + - `PubkeyAuthentication yes` + - Moderne Krypto-Algorithmen +- Restart SSH-Service + +**Template**: `templates/sshd_config.j2` + +**Verwendung**: +```yaml +- include_role: + name: system + tasks_from: ssh-hardening +``` + +**⚠️ Vorsicht**: Testen Sie auf einem Host zuerst, um Aussperrung zu vermeiden! + +#### 6. check-disk-utilization.yaml +Prüft mindestens 4 GB verfügbaren Speicherplatz. + +**Funktionen**: +- Ermittelt verfügbaren Speicher auf `/` +- Schlägt fehl wenn weniger als 4 GB frei +- Nützlich vor großen Updates + +**Verwendung**: +```yaml +- include_role: + name: system + tasks_from: check-disk-utilization +``` + +**Verwendung in**: [Mail-Server → update-mailcow.yaml](04-Mail-Server-Verwaltung.md#update-mailcowyaml) + +#### 7. special-admin-create.yaml +Erstellt Admin-Benutzer mit Sudo ohne Passwort. + +**Funktionen**: +- Erstellt Benutzer `specialadmin` (konfigurierbarer Name) +- Fügt zu `sudo`-Gruppe hinzu +- Konfiguriert passwordless sudo +- Kopiert SSH-Keys + +**Verwendung**: +```yaml +- include_role: + name: system + tasks_from: special-admin-create + vars: + admin_username: myadmin +``` + +#### 8. install-motd.yaml +Installiert custom Message of the Day (MOTD). + +**Funktionen**: +- Kopiert MOTD-File von `files/motd` +- Zeigt bei jedem SSH-Login +- Kann Branding, Warnungen, Informationen enthalten + +**File**: `roles/system/files/motd` + +**Verwendung**: +```yaml +- include_role: + name: system + tasks_from: install-motd +``` + +**Standardvariablen**: + +```yaml +# Docker-Konfiguration +use_docker_image_mirror: true +docker_mirror_location: "SC" # oder "tinc" +docker_install_source: "official" + +# NTP-Server +ntp_servers: + - 0.debian.pool.ntp.org + - 1.debian.pool.ntp.org + - 2.debian.pool.ntp.org + - 3.debian.pool.ntp.org +``` + +**Handler**: + +| Handler | Funktion | +|---------|----------| +| `Reload systemd` | Lädt systemd-Konfiguration neu | +| `Restart SSH` | Startet SSH-Daemon neu | +| `Restart Docker` | Startet Docker-Service neu | +| `Restart chronyd` | Startet Chrony-Service neu | +| `Enable Docker` | Aktiviert Docker beim Boot | +| `Start Docker` | Startet Docker-Service | + +**Templates**: + +#### sshd_config.j2 +SSH-Daemon-Konfiguration mit Härtung. + +**Wichtige Einstellungen**: +```ini +# Authentifizierung +PermitRootLogin without-password +PasswordAuthentication no +PubkeyAuthentication yes +ChallengeResponseAuthentication no + +# Krypto +Ciphers chacha20-poly1305@openssh.com,aes256-gcm@openssh.com +MACs hmac-sha2-512-etm@openssh.com,hmac-sha2-256-etm@openssh.com +KexAlgorithms curve25519-sha256,curve25519-sha256@libssh.org + +# Sicherheit +PermitEmptyPasswords no +X11Forwarding no +MaxAuthTries 3 +LoginGraceTime 20 +``` + +**Files**: + +#### files/motd +Custom Message of the Day. + +Kann enthalten: +- Systemidentifikation +- Sicherheitshinweise +- Kontaktinformationen +- Maintenance-Ankündigungen + +**Verwendung der Rolle**: + +```yaml +# Vollständige System-Setup +- name: System Base Configuration + hosts: all + become: true + roles: + - system +``` + +--- + +### Rolle: updates + +**Zweck**: Verschiedene Update-Mechanismen für unterschiedliche Distributionen. + +**Pfad**: `roles/updates/` + +**Hauptaufgaben**: + +#### 1. apk-based-update.yaml +Für Alpine Linux Updates. + +**Funktionen**: +- `apk update` +- `apk upgrade` + +#### 2. apt-based-update.yaml +Für Debian/Ubuntu Updates. + +**Funktionen**: +- `apt update` +- `apt dist-upgrade` +- Kernel-Update-Prüfung + +#### 3. apt-cleaning.yaml +APT-Cache-Bereinigung. + +**Funktionen**: +- `apt clean` +- `apt autoclean` +- `apt autoremove` + +#### 4. debian-major-upgrade-apt.yaml +Upgrade auf neue Debian-Hauptversion. + +**Funktionen**: +- Ändert Paketquellen +- `apt update` +- `apt dist-upgrade` + +**Verwendung**: + +Diese Rolle wird als **Fallback** verwendet, wenn spezifischere Rollen nicht passen. + +**Siehe bevorzugt**: [`os-updates` Rolle](01-OS-Management.md#rolle-os-updates) + +--- + +## Best Practices + +### 1. ClamAV-Server-Dimensionierung + +**Empfohlene Hardware**: +- CPU: 2+ Cores +- RAM: 4 GB (2 GB für ClamAV, 2 GB für System) +- Disk: 20 GB (10 GB für Signaturen und Logs) +- Network: Gbit-Ethernet empfohlen + +### 2. Chrony-Konfiguration + +Verwenden Sie mehrere NTP-Server für Redundanz: +```yaml +ntp_servers: + - 0.de.pool.ntp.org + - 1.de.pool.ntp.org + - ptbtime1.ptb.de # Deutsche Physikalisch-Technische Bundesanstalt + - ptbtime2.ptb.de +``` + +### 3. Docker-Mirror nutzen + +Für schnellere Image-Downloads in internen Netzwerken: +```yaml +use_docker_image_mirror: true +docker_mirror_location: "tinc" +``` + +### 4. Basis-Tools konsistent installieren + +Installieren Sie Basis-Tools auf allen Hosts: +```bash +ansible all -i inventories/icp-fra-pve1.yml \ + -m include_role \ + -a "name=system tasks_from=install-basic-tools" \ + -b +``` + +### 5. Regelmäßige ClamAV-Signatur-Updates + +FreshClam aktualisiert automatisch. Überprüfen Sie regelmäßig: +```bash +# Auf ClamAV-Server +freshclam --version +journalctl -u clamav-freshclam -n 50 +``` + +--- + +## Fehlerbehebung + +### Problem: ClamAV-Kompilation schlägt fehl + +**Symptome**: Build-Fehler während `compile-clamav.yml` + +**Lösung**: +1. Überprüfen Sie Rust-Installation: + ```bash + rustc --version + cargo --version + ``` +2. Installieren Sie fehlende Dependencies manuell +3. Überprüfen Sie Internet-Verbindung für Source-Download +4. Erhöhen Sie RAM (ClamAV-Build benötigt ~2 GB) + +### Problem: Chrony synchronisiert nicht + +**Symptome**: Uhrzeit ist falsch oder driftet + +**Lösung**: +1. Überprüfen Sie Chrony-Status: + ```bash + chronyc tracking + chronyc sources -v + ``` +2. Testen Sie NTP-Server-Erreichbarkeit: + ```bash + chronyc -n sources + ping 0.debian.pool.ntp.org + ``` +3. Restart Chrony: + ```bash + systemctl restart chronyd + ``` + +### Problem: Docker-Mirror funktioniert nicht + +**Symptome**: Image-Pulls schlagen fehl oder sind langsam + +**Lösung**: +1. Testen Sie Proxy-Erreichbarkeit: + ```bash + curl -I http://dim.servercow.com:3128 + ``` +2. Überprüfen Sie Docker-Daemon-Config: + ```bash + cat /etc/systemd/system/docker.service.d/http-proxy.conf + ``` +3. Restart Docker: + ```bash + systemctl restart docker + ``` + +### Problem: SSH-Härtung sperrt aus + +**Symptome**: Kein SSH-Zugriff nach Härtung + +**Prävention**: +- Testen Sie zuerst auf einem Non-Production-Host +- Halten Sie Console-Zugriff bereit (Proxmox, IPMI) +- Behalten Sie eine offene SSH-Session während Änderungen + +**Lösung**: +1. Zugriff über Console +2. Revert sshd_config: + ```bash + cp /etc/ssh/sshd_config.backup /etc/ssh/sshd_config + systemctl restart sshd + ``` + +--- + +## Nützliche Kommandos + +### ClamAV-Operationen + +```bash +# Signatur-Version prüfen +clamdscan --version + +# Manueller Scan +clamdscan /path/to/directory + +# Signatur-Update manuell +freshclam + +# ClamAV-Status +systemctl status clamav-daemon +journalctl -u clamav-daemon -f +``` + +### Chrony-Operationen + +```bash +# Zeitquellen anzeigen +chronyc sources -v + +# Synchronisations-Status +chronyc tracking + +# Force-Sync (bei großer Drift) +chronyc makestep + +# Statistiken +chronyc sourcestats -v +``` + +### System-Tools + +```bash +# Installierte Basis-Tools prüfen +dpkg -l | grep -E 'git|curl|wget|vim|htop' + +# Docker-Version +docker --version +docker compose version + +# Verfügbarer Speicher +df -h +``` + +--- + +**Navigation**: [← Zurück: Virtualisierung](06-Virtualisierung.md) | [Nächstes: Cleanup-Aufgaben →](08-Cleanup-Aufgaben.md) diff --git a/docs/08-Cleanup-Aufgaben.md b/docs/08-Cleanup-Aufgaben.md new file mode 100644 index 0000000..3c2d80d --- /dev/null +++ b/docs/08-Cleanup-Aufgaben.md @@ -0,0 +1,508 @@ +# Cleanup-Aufgaben + +## Übersicht + +Diese Kategorie umfasst Wartungs- und Bereinigungsroutinen für verschiedene Systemkomponenten. Regelmäßige Cleanup-Aufgaben sind wichtig für Speicherplatz-Management, Performance-Optimierung und System-Hygiene. + +**Anwendungsfälle**: +- Löschen alter Proxmox-Snapshots +- Bereinigung ungenutzter CheckMK-Agent-Plugins +- Entfernung veralteter Docker-Images und -Container +- Speicherplatz-Freigabe + +--- + +## Playbooks + +### cleanups/clean-pve-snapshots.yml + +Löschen von Proxmox VE Snapshots auf VM-Hosts. + +**Datei**: `playbooks/cleanups/clean-pve-snapshots.yml` + +**Zweck**: Bereinigung aller Proxmox-VM-Snapshots (außer "current") zur Freigabe von Speicherplatz nach erfolgreichen Updates oder Wartungsarbeiten. + +**Ziel-Hosts**: `all` + +**Benutzer**: `tincadmin` (mit sudo-Rechten) + +**Verwendete Rollen**: +- `proxmox-automation` (get-vmid, delete-snapshots) + +**Wichtige Variablen**: +- Keine (verwendet Vault-Variablen) + +**Verwendungsbeispiel**: + +```bash +# Alle Snapshots auf allen VMs entfernen +ansible-playbook playbooks/cleanups/clean-pve-snapshots.yml \ + -i inventories/icp-fra-pve1.yml \ + -K --ask-vault-pass + +# Nur für spezifische Hosts +ansible-playbook playbooks/cleanups/clean-pve-snapshots.yml \ + -i inventories/icp-fra-pve1.yml \ + --limit mail-server-01.example.com \ + -K --ask-vault-pass + +# Mit Verbose-Output +ansible-playbook playbooks/cleanups/clean-pve-snapshots.yml \ + -i inventories/icp-fra-pve1.yml \ + -v \ + -K --ask-vault-pass +``` + +**Abhängigkeiten**: +- Vault-Datei (`vault.yml`) für Proxmox API-Tokens +- Hosts müssen Proxmox-VMs sein +- Proxmox API-Zugriff + +**Besonderheiten**: +- **`gather_facts: false`** - Keine Fact-Sammlung für Performance +- **Löscht ALLE Snapshots** außer "current" (aktiver VM-Zustand) +- **Snapshot-ID-Abruf** vor Löschung +- **API-basiert** - Delegiert zu localhost + +**Workflow**: +1. Lädt Vault-Datei mit Proxmox-Zugangsdaten +2. Für jeden Host: + - Ermittelt Proxmox VM-ID + - Listet alle Snapshots auf + - Filtert "current" aus + - Löscht alle verbleibenden Snapshots +3. Gibt Speicherplatz frei + +**⚠️ Warnung**: Dieses Playbook löscht **ALLE** Snapshots! Stellen Sie sicher, dass keine wichtigen Snapshots mehr benötigt werden. + +**Wann verwenden**: +- Nach erfolgreichen OS-Major-Upgrades +- Nach erfolgreichen Mailcow-Updates +- Monatliche Speicherplatz-Bereinigung +- Vor großen Updates (alte Snapshots entfernen, neue erstellen) + +**Siehe auch**: [Virtualisierung → delete-snapshots.yaml](06-Virtualisierung.md#3-delete-snapshotsyaml) + +--- + +### cleanups/cleanup-cmk-agent-plugins.yml + +Bereinigung von CheckMK-Agent-Plugins auf überwachten Hosts. + +**Datei**: `playbooks/cleanups/cleanup-cmk-agent-plugins.yml` + +**Zweck**: Entfernung nicht benötigter oder veralteter CheckMK-Agent-Plugins zur Reduzierung des Monitoring-Overheads. + +**Ziel-Hosts**: `all` + +**Benutzer**: `tincadmin` (mit sudo-Rechten) + +**Verwendete Rollen**: +- `checkmk-monitoring` (Task: `cleanup-agent-plugins`) + +**Wichtige Variablen**: +- `checkmk_agent_plugins_to_remove` (aus Rolle) + +**Verwendungsbeispiel**: + +```bash +# Standard-Cleanup (entfernt Plugins aus defaults/main.yaml) +ansible-playbook playbooks/cleanups/cleanup-cmk-agent-plugins.yml \ + -i inventories/icp-fra-pve1.yml \ + -K + +# Mit custom Plugin-Liste +ansible-playbook playbooks/cleanups/cleanup-cmk-agent-plugins.yml \ + -i inventories/icp-fra-pve1.yml \ + -e '{"checkmk_agent_plugins_to_remove": ["docker-mailq-monitoring", "old-plugin"]}' \ + -K + +# Nur auf Mail-Servern +ansible-playbook playbooks/cleanups/cleanup-cmk-agent-plugins.yml \ + -i inventories/extern.yml \ + -K +``` + +**Abhängigkeiten**: +- `checkmk-monitoring` Rolle +- CheckMK-Agent muss installiert sein + +**Besonderheiten**: +- **Minimales Playbook** - Nur Rollen-Aufruf +- **`gather_facts: false`** - Performance-Optimierung +- **Idempotent** - Mehrfache Ausführung sicher + +**Workflow**: +1. Liest Plugin-Liste aus `checkmk_agent_plugins_to_remove` +2. Für jeden Host: + - Lokalisiert CheckMK-Agent-Plugin-Verzeichnis + - Löscht spezifizierte Plugins + - Bereinigt zugehörige Konfigurationsdateien +3. CheckMK-Agent wird automatisch neu geladen + +**Standard-Plugins zur Entfernung** (aus `roles/checkmk-monitoring/defaults/main.yaml`): +```yaml +checkmk_agent_plugins_to_remove: + - "docker-mailq-monitoring" +``` + +**Wann verwenden**: +- Nach Migration zu alternativen Monitoring-Lösungen +- Nach Dekommissionierung von Services +- Bei Performance-Problemen durch zu viele Plugins +- Regelmäßige Bereinigung (quartalsweise) + +**Plugin-Verzeichnisse** (typisch): +- `/usr/lib/check_mk_agent/plugins/` +- `/usr/lib/check_mk_agent/local/` +- `/etc/check_mk/` + +**Siehe auch**: [Monitoring → Rolle checkmk-monitoring](02-Monitoring.md#5-cleanup-agent-pluginsyaml) + +--- + +## Docker-Cleanup-Playbooks + +Die Docker-Cleanup-Playbooks sind in der [Container-Management](03-Container-Management.md)-Kategorie dokumentiert: + +- **[docker/cleanup-images.yml](03-Container-Management.md#dockercleanup-imagesyml)** - Bereinigung ungenutzter Docker-Images +- **[docker/cleanup-all.yml](03-Container-Management.md#dockercleanup-allyml)** - Vollständige Docker-Bereinigung + +Diese Playbooks sind ebenfalls Teil der Cleanup-Strategie und sollten regelmäßig ausgeführt werden. + +--- + +## Cleanup-Strategie und Best Practices + +### 1. Regelmäßige Ausführung + +Empfohlener Cleanup-Zeitplan: + +| Aufgabe | Häufigkeit | Playbook | Begründung | +|---------|------------|----------|------------| +| Docker-Images | Wöchentlich | `docker/cleanup-images.yml` | Speicherplatz-Management | +| Proxmox-Snapshots | Monatlich | `cleanups/clean-pve-snapshots.yml` | Nach erfolgreichen Updates | +| CMK-Agent-Plugins | Quartalsweise | `cleanups/cleanup-cmk-agent-plugins.yml` | Nach Plugin-Änderungen | +| Docker-Full-Cleanup | Monatlich | `docker/cleanup-all.yml` | Vollständige Bereinigung | + +### 2. Automatisierung mit Cron/Systemd-Timer + +**Beispiel Cron-Job** (auf Ansible-Control-Node): + +```bash +# /etc/cron.d/ansible-cleanup + +# Wöchentliches Docker-Image-Cleanup (Sonntag 02:00 Uhr) +0 2 * * 0 ansible-user /usr/local/bin/cleanup-docker-images.sh + +# Monatliches Snapshot-Cleanup (1. des Monats, 03:00 Uhr) +0 3 1 * * ansible-user /usr/local/bin/cleanup-snapshots.sh +``` + +**Wrapper-Script** (`/usr/local/bin/cleanup-docker-images.sh`): + +```bash +#!/bin/bash +cd /opt/operating-automation +ansible-playbook playbooks/docker/cleanup-images.yml \ + -i inventories/icp-fra-pve1.yml \ + >> /var/log/ansible-cleanup.log 2>&1 +``` + +### 3. Pre-Cleanup-Checks + +Vor größeren Cleanups: + +```bash +# 1. Überprüfen Sie aktuelle Snapshot-Liste +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "qm listsnapshot \$(qm list | grep $(hostname) | awk '{print \$1}')" \ + -b + +# 2. Überprüfen Sie Docker-Speichernutzung +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "docker system df" \ + -b + +# 3. Überprüfen Sie CheckMK-Plugins +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "ls -la /usr/lib/check_mk_agent/plugins/" \ + -b +``` + +### 4. Post-Cleanup-Verifizierung + +Nach Cleanup-Operationen: + +```bash +# 1. Verifizieren Sie freigegebenen Speicherplatz +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "df -h /" \ + -b + +# 2. Überprüfen Sie Service-Status +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "systemctl status docker check-mk-agent" \ + -b + +# 3. Überprüfen Sie ob kritische Snapshots gelöscht wurden +# (manuell im Proxmox Web-Interface) +``` + +### 5. Backup vor Cleanup + +Für sicherheitskritische Cleanups: + +```bash +# 1. Erstellen Sie neue Snapshots BEVOR Sie alte löschen +ansible-playbook playbooks/os-update.yml \ + -e "do_snapshots=true" \ + -e "snapshot_name=pre-cleanup-$(date +%Y%m%d)" \ + -i inventories/... \ + -K --ask-vault-pass + +# 2. Dann Cleanup durchführen +ansible-playbook playbooks/cleanups/clean-pve-snapshots.yml \ + -i inventories/... \ + -K --ask-vault-pass +``` + +--- + +## Speicherplatz-Monitoring + +### Speichernutzung überwachen + +```bash +# Gesamte Festplattennutzung +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "df -h | grep -E 'Filesystem|/$'" \ + -b + +# Docker-Speichernutzung detailliert +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "docker system df -v" \ + -b + +# Proxmox-Storage-Status +pvesm status +``` + +### Top-Speicherverbraucher identifizieren + +```bash +# Größte Verzeichnisse finden +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "du -h / --max-depth=2 2>/dev/null | sort -rh | head -20" \ + -b + +# Docker-Volume-Größen +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "docker system df -v | grep VOLUME -A 100" \ + -b +``` + +--- + +## Fehlerbehebung + +### Problem: Snapshot-Cleanup schlägt fehl + +**Symptome**: delete-snapshots Task meldet Fehler + +**Lösung**: +1. Überprüfen Sie Proxmox-API-Zugangsdaten in Vault +2. Überprüfen Sie ob Snapshots tatsächlich existieren: + ```bash + qm listsnapshot + ``` +3. Versuchen Sie manuelles Löschen: + ```bash + qm delsnapshot + ``` +4. Überprüfen Sie Proxmox-Logs: + ```bash + journalctl -u pveproxy -n 100 + ``` + +### Problem: Plugin-Cleanup entfernt benötigte Plugins + +**Symptome**: CheckMK-Services fehlen nach Cleanup + +**Prävention**: +- Überprüfen Sie `checkmk_agent_plugins_to_remove` Liste vor Ausführung +- Testen Sie auf einzelnem Host zuerst + +**Lösung**: +1. Re-installation des CheckMK-Agents: + ```bash + ansible-playbook playbooks/reinstall-cmk-agent.yml + ``` +2. Service-Discovery neu ausführen: + ```bash + ansible-playbook playbooks/setup-checkmk-monitoring.yml \ + --limit affected-host + ``` + +### Problem: Docker-Cleanup löscht benötigte Images + +**Symptome**: Container können nicht starten nach Cleanup + +**Prävention**: +- Verwenden Sie `cleanup-images.yml` statt `cleanup-all.yml` für konservatives Cleanup +- Stellen Sie sicher alle Container laufen vor `cleanup-all.yml` + +**Lösung**: +1. Re-pull Images: + ```bash + cd /opt/mailcow-dockerized + docker-compose pull + docker-compose up -d + ``` + +### Problem: Zu wenig Speicherplatz freigegeben + +**Symptome**: Nach Cleanup immer noch hohe Speichernutzung + +**Lösung**: +1. Identifizieren Sie Top-Verbraucher: + ```bash + du -h / --max-depth=2 | sort -rh | head -20 + ``` +2. Überprüfen Sie Log-Dateien: + ```bash + journalctl --vacuum-size=100M + find /var/log -type f -name "*.log" -size +100M + ``` +3. Bereinigen Sie alte Kernels: + ```bash + apt autoremove --purge + ``` +4. Überprüfen Sie Mailcow-Logs: + ```bash + cd /opt/mailcow-dockerized + du -sh data/logs/* + # Bereinigen Sie alte Logs manuell + ``` + +--- + +## Erweiterte Cleanup-Operationen + +### APT-Cache-Bereinigung + +```bash +# Auf allen Hosts +ansible all -i inventories/icp-fra-pve1.yml \ + -m apt -a "autoclean=yes" \ + -b + +ansible all -i inventories/icp-fra-pve1.yml \ + -m apt -a "autoremove=yes purge=yes" \ + -b +``` + +### Journalctl-Log-Rotation + +```bash +# Logs älter als 30 Tage löschen +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "journalctl --vacuum-time=30d" \ + -b + +# Logs auf max 500MB begrenzen +ansible all -i inventories/icp-fra-pve1.yml \ + -m shell -a "journalctl --vacuum-size=500M" \ + -b +``` + +### Alte Kernel-Versionen entfernen + +```bash +# Automatische Entfernung alter Kernels (Debian) +ansible all -i inventories/icp-fra-pve1.yml \ + -m apt -a "autoremove=yes purge=yes" \ + -b +``` + +### Mailcow-Log-Bereinigung + +```bash +# Alte Mailcow-Logs löschen (älter als 30 Tage) +ansible all -i inventories/extern.yml \ + -m shell -a "find /opt/mailcow-dockerized/data/logs -type f -mtime +30 -delete" \ + -b +``` + +--- + +## Cleanup-Checkliste + +Verwenden Sie diese Checkliste für monatliche Wartung: + +- [ ] **Pre-Check**: Speichernutzung dokumentieren +- [ ] **Backup**: Wichtige Snapshots oder Backups erstellen +- [ ] **Docker-Images**: `playbooks/docker/cleanup-images.yml` ausführen +- [ ] **Proxmox-Snapshots**: `playbooks/cleanups/clean-pve-snapshots.yml` ausführen (nach erfolgreichen Updates) +- [ ] **CMK-Plugins**: `playbooks/cleanups/cleanup-cmk-agent-plugins.yml` ausführen (quartalsweise) +- [ ] **APT-Cache**: `apt autoclean` und `apt autoremove` auf allen Hosts +- [ ] **Logs**: Journalctl und Application-Logs rotieren +- [ ] **Post-Check**: Speicherplatz-Freigabe verifizieren +- [ ] **Monitoring**: Services und Container-Status prüfen +- [ ] **Dokumentation**: Cleanup-Ergebnisse dokumentieren + +--- + +## Nützliche Kommandos + +### Speicherplatz-Analyse + +```bash +# Top 10 größte Verzeichnisse +ansible all -i inventories/... \ + -m shell -a "du -h / --max-depth=2 2>/dev/null | sort -rh | head -10" \ + -b + +# Inode-Nutzung +ansible all -i inventories/... \ + -m shell -a "df -i" \ + -b +``` + +### Cleanup-Status + +```bash +# Anzahl Docker-Images +ansible all -i inventories/... \ + -m shell -a "docker images | wc -l" \ + -b + +# Anzahl Snapshots pro VM +pvesh get /nodes//qemu//snapshot + +# CheckMK-Plugin-Liste +ansible all -i inventories/... \ + -m shell -a "ls /usr/lib/check_mk_agent/plugins/ | wc -l" \ + -b +``` + +--- + +## Zusammenfassung + +Cleanup-Aufgaben sind essentiell für: +- ✅ **Speicherplatz-Management**: Verhindert Disk-Full-Situationen +- ✅ **Performance**: Reduziert Overhead durch alte Snapshots/Images +- ✅ **Sicherheit**: Entfernt veraltete Software-Komponenten +- ✅ **Compliance**: Erfüllt Datenaufbewahrungsrichtlinien +- ✅ **Wartungsfreundlichkeit**: Übersichtlichere Systeme + +**Empfohlene Cleanup-Routine**: +1. Wöchentlich: Docker-Image-Cleanup +2. Monatlich: Vollständiges Docker-Cleanup, APT-Cache +3. Nach Updates: Proxmox-Snapshot-Cleanup +4. Quartalsweise: CheckMK-Plugin-Cleanup, Log-Rotation + +--- + +**Navigation**: [← Zurück: Basis-System](07-Basis-System.md) | [Zurück zur Übersicht](00-Übersicht.md)