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