# Runbook: Wenn die Host-Übernahme stehenbleibt

Der Bootstrap läuft in neun Abschnitten. Bleibt einer davon aus, zeigt die
Konsole **welcher** — nicht „irgendetwas ging schief". Dieses Runbook sagt je
Abschnitt: woran man es merkt, wo man nachsieht, und was der übliche Grund ist.

---

## Die eine Regel, die über allen steht

**Eine halb installierte Maschine wird neu aufgesetzt, nicht nachgebessert.**

Nicht aus Bequemlichkeit. Der Bootstrap ist so gebaut, dass ein zweiter Lauf auf
einer frisch aufgesetzten Maschine immer gleich ausgeht — ein Lauf auf einer
Maschine, an der jemand von Hand etwas gerade gerückt hat, ist das nicht mehr.
Wer nachbessert, tauscht ein wiederholbares Ergebnis gegen ein einmaliges, und
merkt den Unterschied erst beim nächsten Host.

Der Weg zurück ist immer derselbe:

1. Im Adminbereich einen **neuen** Host anlegen. Der Einmal-Code ist verbraucht;
   die Seite zeigt ihn nicht wieder her, und das ist Absicht.
2. Beim Anbieter das **Rettungssystem** starten.
3. Die neue Zeile einfügen.

Der alte Host-Eintrag wird im Adminbereich entfernt. Solange er steht, hält er
seine Tunneladresse belegt.

**Ausnahme:** Bleibt der Lauf in `rescue_checked` stehen, ist noch **nichts**
geschrieben worden. Dort ist Nachbessern richtig — es ist der einzige Abschnitt,
der die Platte nicht angefasst hat.

---

## Wo alles steht

| Was | Wo |
|---|---|
| Fortschritt, Zeile je Abschnitt | `/var/lib/clupilot/progress.jsonl` |
| Was schon gesendet wurde (Zeilenzahl) | `/var/lib/clupilot/progress.sent` |
| Laufprotokoll des Skripts | `/var/lib/clupilot/bootstrap.log` |
| Aufrufargumente (nur root) | `/var/lib/clupilot/arguments` |
| Arbeitsverzeichnis: ISO, Protokolle | `/var/tmp/clupilot-work/` |
| Installer-Protokoll | `/var/tmp/clupilot-work/qemu.log` |
| Antwortdatei des Installers | `/var/tmp/clupilot-work/answer.toml` |
| Traefik | `/var/log/traefik.log`, `/etc/traefik/traefik.yml` |

Die Fortschrittsdatei **ist** der Zustand. Ein Abschnitt, der dort `done`
gemeldet hat, läuft bei einem Wiederanlauf nicht erneut.

---

## Vor dem Neustart oder danach?

Das ist die erste Frage, und sie ist leicht zu beantworten:

```sh
findmnt -no FSTYPE /
```

`tmpfs`, `overlay` oder `ramfs` heißt: noch im Rettungssystem, der Neustart
steht bevor. `zfs` heißt: die Maschine läuft schon auf dem installierten System,
und der `first-boot`-Hook hat den Lauf wieder aufgenommen.

---

## Abschnitt für Abschnitt

### `rescue_checked` — die Eingangsprüfung

**Woran man es merkt:** Das Skript endet sofort mit einer Liste von Befunden.
In der Konsole steht nichts, weil es vor dem Tunnel keinen Weg dorthin gibt.

**Übliche Gründe:**

- *„Das Wurzelverzeichnis liegt auf /dev/… also auf einer echten Partition."*
  Die Maschine läuft nicht im Rettungssystem. Beim Anbieter das Rettungssystem
  einschalten und **neu starten** — das Einschalten allein genügt nicht.
- *„Die CPU meldet weder vmx noch svm."* Ein Cloud-Produkt ohne verschachtelte
  Virtualisierung (Hetzner CPX/CX, teils netcup). Nicht abstellbar; es braucht
  eine dedizierte Maschine.
- *„/dev/kvm gibt es nicht."* Virtualisierung im BIOS aus, oder das
  Rettungssystem hat das Modul nicht geladen: `modprobe kvm_intel` bzw.
  `modprobe kvm_amd`, dann die Zeile noch einmal.
- *„Es sind Partitionen echter Platten eingehängt."* Jemand hat nachgesehen.
  `umount` und noch einmal.
- *„Die Uhr geht … Sekunden falsch."* Die Meldung enthält den fertigen Befehl
  zum Stellen. Ohne ihn scheitert später jede TLS-Prüfung mit einer Meldung über
  Zertifikate statt über die Uhrzeit.

**Hier ist Nachbessern richtig.** Es wurde noch nichts geschrieben.

---

### `debian_installed` — das Grundsystem

Heißt „Grundsystem geschrieben". Es entsteht **kein** Debian, das nachher jemand
umbaut: die offizielle Proxmox-ISO wird mit einer Antwortdatei versehen und
unter QEMU gegen die echten Platten gestartet.

**Woran man es merkt:** Der Lauf steht lange ohne Meldung; im Rettungssystem
läuft ein `qemu-system-x86_64`.

**Wo man nachsieht:** `/var/tmp/clupilot-work/qemu.log`, und die Antwortdatei
daneben. Läuft QEMU noch, kann man dem Installer zusehen — er hört auf
`127.0.0.1:5900`:

```bash
ssh -L 5900:127.0.0.1:5900 root@<öffentliche-ip>
```

Dann mit einem VNC-Betrachter auf `localhost:5900`. Sieht man dort eine
**Eingabemaske**, ist die Antwortdatei nicht angenommen worden — der Installer
ist in den interaktiven Modus gefallen und wartet, bis die Stunde abläuft.

**Übliche Gründe:**

- `answer.toml` abgelehnt. Steht in `/var/tmp/clupilot-work/assistant.log`. Das
  Skript prüft sie mit `validate-answer`, bevor es die ISO backt, also ist das
  selten — und wenn, dann liegt es an einem Wert aus der Umgebung (Adresse,
  Gateway, MAC), den das Rettungssystem anders meldet als erwartet.
- Prüfsumme der ISO stimmt nicht. Abgebrochene Übertragung. Zeile noch einmal.
- Keine passende PVE-9-ISO gefunden. Die Liste unter
  `https://enterprise.proxmox.com/iso/` war nicht erreichbar.

---

### `rebooted` — die einzige unumkehrbare Stelle

**Woran man es merkt:** Die Maschine antwortet nach dem Neustart nicht mehr,
oder sie antwortet, meldet aber nichts weiter.

**Übliche Gründe:**

- Die Maschine bootet noch vom Rettungssystem statt von der Platte. Beim
  Anbieter das Rettungssystem **abschalten** und neu starten.
- Der `first-boot`-Hook lief nicht. Nachsehen mit
  `journalctl -u proxmox-first-boot` und `ls /var/lib/clupilot/`. Fehlt das
  Verzeichnis ganz, ist der Hook nicht in die ISO gekommen — dann neu aufsetzen.

**Kommt die Maschine gar nicht zurück:** Anbieterkonsole. Neu aufsetzen ist
schneller als jede Suche.

---

### `proxmox_installed` — abnehmen und Quellen richten

**Woran man es merkt:** Meldung mit `failed` und einem der folgenden Sätze.

**Übliche Gründe:**

- *„pveversion gibt es nicht"* — die ISO hat kein Proxmox installiert. Neu
  aufsetzen.
- *„läuft auf …, das ist kein PVE-Kernel"* — die Maschine ist in den
  Debian-Kernel gebootet. `uname -r` muss `-pve` enthalten.
- *„erwartet wäre PVE 9"* — Abbild und Unterbau passen nicht zusammen. Mit dem
  richtigen Abbild neu aufsetzen; Paketquellen heilen das nicht.
- *„apt-get update schlägt fehl"* — siehe `/var/tmp/clupilot-work/apt.log`. Fast
  immer eine Abonnement-Quelle, die wieder aufgetaucht ist:
  `ls /etc/apt/sources.list.d/`.

---

### `network_bridged` — der gefährlichste Abschnitt

**Woran man es merkt:** Entweder eine `failed`-Meldung, oder die Maschine ist
für ein paar Minuten weg und kommt dann von selbst zurück.

**Kommt sie zurück, war das die Selbstrücknahme.** Das ist kein Fehler des
Zeitgebers, sondern sein Zweck: die Brücke hätte den Host vom Netz genommen.
Nachsehen mit `journalctl -t clupilot`.

**Übliche Gründe:**

- Falsche Anbieterform erkannt. Bei einer gerouteten Einzeladresse muss
  `pointopoint` in `/etc/network/interfaces` stehen; fehlt sie, findet der
  Kernel das Gateway nicht.
- *„die Datacenter-Firewall ließ sich nicht einschalten"* — ohne sie sind die
  „nur 80/443"-Regeln **jeder** Kunden-VM wirkungslos. Prüfen mit
  `pvesh get /cluster/firewall/options`.

**Kommt die Maschine nicht zurück:** Anbieterkonsole, dort
`tar xzf /var/lib/clupilot/interfaces.vor-der-bruecke.tar.gz -C /` und
`ifreload -a`. Danach neu aufsetzen.

---

### `wireguard_joined` — ab hier ist CluPilot erreichbar

**Woran man es merkt:** Bis hierher stand in der Konsole „wartet auf den
Tunnel". Bleibt es dabei, ist dieser Abschnitt der offene.

**Wo man nachsieht:** `wg show` auf dem Host. Steht dort ein Peer ohne
`latest handshake`, steht die Datei und der Tunnel nicht.

**Übliche Gründe:**

- Der Hub kennt den Peer nicht. Sollte nicht vorkommen — CluPilot legt ihn beim
  Anlegen des Hosts an —, aber ein gelöschter Host-Eintrag nimmt ihn mit.
- Der Hub-Endpunkt ist von dieser Maschine aus nicht erreichbar. UDP auf dem
  Port des Hubs prüfen.
- *„konnte wg-quick@wg0 nicht freigeben"* — der Tunnel überlebte den nächsten
  Neustart nicht. Das ist ein harter Fehler, kein Schönheitsfehler.

---

### `traefik_running`

**Woran man es merkt:** `failed` mit einem der Sätze unten. Der Host ist
erreichbar, also lässt sich alles direkt nachsehen.

**Übliche Gründe:**

- *„antwortet nicht am Ping-Endpunkt"* — `/var/log/traefik.log` und
  `systemctl status traefik`.
- *„80 und 443 sind nicht belegt"* — Traefik läuft, ein Entrypoint fehlt.
  `ss -ltnp | grep -E ':80|:443'`. Belegt sie etwas anderes, gehört das nicht auf
  diese Maschine.
- Prüfsumme des Binaries stimmt nicht. Zeile noch einmal.

Dass Traefik hier **noch keine Routentabelle** holt, ist richtig so: den Token
dafür gibt es erst mit der Registrierung.

---

### `template_built` — die goldene Vorlage

**Woran man es merkt:** `failed`, meist mit einem Hinweis auf eine der drei
Fallen.

**Wo man nachsieht:** `/var/tmp/clupilot-work/virt-customize.log` und
`qm.log`.

**Übliche Gründe:**

- *„erfüllt Falle 2 nicht"* — das Cloud-Abbild hat LVM oder die Wurzel ist nicht
  die letzte Partition. Dann stimmt etwas am Abbild nicht, das dort liegt.
- *„qemu-guest-agent ist NICHT im Abbild"* — `virt-customize` hat Erfolg
  gemeldet und apt hat das Paket still nicht installiert. Fast immer ein
  Netzproblem im Abbild-Umbau.
- *„kein `user: www-data`"* — die Compose-Datei im Abbild ist nicht die aus
  `assets/`. Ohne diese Zeile schlagen **alle** `occ`-Aufrufe fehl.
- *„meldet nicht template: 1"* — die VM existiert, ist aber keine Vorlage.
  `qm template 9000` von Hand und dann **trotzdem neu aufsetzen**: wenn dieser
  Schritt schiefging, ist unklar, was sonst noch.

---

### `registered` — die Übergabe

**Woran man es merkt:** Der Host bleibt in der Konsole auf `onboarding`.

**Übliche Gründe:**

- *„die Proxmox-Rolle ließ sich nicht angleichen"* — ohne `Sys.Modify` stirbt
  später **jede** Kundenbereitstellung am Backup-Schritt. Prüfen mit
  `pveum role list`.
- *„hat nicht geantwortet"* — CluPilot ist über den Tunnel nicht erreichbar,
  obwohl der Handshake stand. Auf der CluPilot-Seite nachsehen, ob die
  Tunneladresse in `TRUSTED_RANGES` steht.
- *„kam ohne host_token zurück"* — die Registrierung ist durchgelaufen, die
  Antwort war unvollständig. Auf der CluPilot-Seite nachsehen.
- *„der Schlüsseltausch hat keinen Handshake ergeben"* — das Skript hat auf den
  alten Schlüssel zurückgestellt, der Host ist also **noch erreichbar**. Der Hub
  hat den neuen Peer möglicherweise schon aufgenommen und den alten entfernt;
  dann ist der Host beim nächsten Versuch weg. Neu aufsetzen.
- *„die Routentabelle ist nicht abrufbar"* — der Token stimmt nicht oder
  `/host/routes` antwortet nicht. Direkt prüfen:
  ```bash
  curl -H "Authorization: Bearer $(cat /etc/traefik/host-token)" http://<tunnel-ip>/host/routes
  ```

---

## Der Host ist nicht mehr erreichbar

Erst die Frage: **war die Firewall schon dran?** Sie wird als **allerletztes**
angewendet. Steht in der Konsole `registered` noch nicht auf `done`, war sie es
nicht — dann liegt es am Netz, nicht an den Regeln.

War sie dran, gibt es von der Anbieterkonsole aus genau einen Griff:

```bash
/usr/local/sbin/clupilot-emergency-open-firewall.sh
```

Der Host nimmt danach auf jedem Port wieder an. **Es gibt bewusst keine
automatische Wiederöffnung** — kein Zeitgeber, kein „nach N Minuten ohne
Handshake wieder auf". Eine Firewall, die sich unter Störung selbst öffnet, ist
keine Firewall.

Zurück kommen die Regeln mit:

```bash
nft -f /etc/nftables.conf && systemctl enable --now nftables
```

---

## Was dieses Runbook nicht sagt

Alles, was noch nicht auf echter Hardware gelaufen ist. Die Abschnitte oben sind
aus dem Skript und aus den Fundstellen geschrieben, die ihm zugrunde liegen —
nicht aus Vorfällen. Was beim ersten Durchlauf tatsächlich stehenbleibt, gehört
hier ergänzt, mit dem Satz, der in der Konsole stand.
