Fehlerbehebung am Node

Jedes ✗ und jeder gescheiterte Schritt gibt seine eigene Lösung aus, und derselbe Befehl, noch einmal ausgeführt, macht dort weiter, wo die Installation stehen blieb. Fang mit der Zeile an, die sie ausgegeben hat. Unten stehen die Fälle, auf die Admins am häufigsten treffen.

Eine Prüfung meldet, die Disk sei nicht leer

Die Disk hat Partitionen, eine Partitionstabelle, ein Dateisystem oder eine Signatur, und der Installer löscht nie eine Disk für dich. Brauchst du nichts davon, führ sudo wipefs -a /dev/sdb für deine Disk aus. Gehört die Disk zu einem ZFS-Pool, nennt die Zeile den Pool: Lösch ihn zuerst mit sudo zpool destroy <pool>; damit ist jede Datei darauf weg. Eine LVM-Disk nennt die Zeile als solche. Nimm zuerst ihr LVM herunter: pvs /dev/sdb nennt ihre Volume Group, vgremove <group> zerstört ihre Volumes, danach führ pvremove /dev/sdb aus.

Eine Prüfung findet andere Software auf dem Server

Der Node beansprucht den ganzen Server, also stoppen Docker, LXD, ein Incus oder cloudflared, das nicht der Installer dorthin gebracht hat, oder ein anderer ZFS-Pool die Installation. Die Zeile listet jedes davon mit dem Befehl, der es entfernt, etwa apt-get purge docker-ce docker.io oder snap remove --purge lxd. Entfern sie oder nimm einen sauberen Server.

Secure Boot oder die Kernel-Header scheitern

Der Node baut sein eigenes ZFS-Modul. Schalte Secure Boot in der Firmware ab oder trag den DKMS-Schlüssel ein: apt-get install dkms, dann mokutil --import /var/lib/dkms/mok.pub, und bestätige ihn beim nächsten Booten. Für die Header: apt-get update && apt-get install linux-headers-$(uname -r); hat apt dann immer noch keine, apt-get full-upgrade und in den neuesten Kernel neu starten.

Ausgehende Verbindungen, TLS oder die Uhr scheitern

• Die Prüfung der ausgehenden Verbindungen nennt jedes Ziel, das nicht geantwortet hat. Erlaube ausgehendes TCP zu diesen Zielen und UDP 7844 zum Tunnel von Cloudflare. Was der Server braucht hat die vollständige Liste.
• TLS nennt die Stelle, die signiert hat, was ankam. Lass api.detachbox.com und *.argotunnel.com ohne TLS-Inspektion durch.
• Uhr: timedatectl set-ntp true, und lass den Server seine NTP-Server über UDP 123 erreichen.

Die Disk trägt einen behaltenen Pool

Ein früherer Node auf diesem Server wurde deinstalliert und sein Pool behalten, und die neue Installation lehnt diese Disk ab: Ein neuer Node übernimmt nie die Dateien des alten. Gib dem neuen Node eine andere Disk (lsblk -d -o NAME,SIZE,MODEL,SERIAL listet sie auf), oder, wenn nichts auf dem behaltenen Pool wichtig ist, führ den Befehl aus, den die Zeile ausgibt: Sein uninstall --confirm --destroy-pool zerstört den Pool mit allem darauf und entfernt ZFS und detachbox-node-host. Hast du den behaltenen Pool wieder importiert, um seine Dateien zu lesen, taucht er in der Prüfung auf andere Software auf: sudo zpool export boxes legt ihn wieder auf seiner Disk ab, und der Deinstallationsbefehl aus der Zeile entfernt ihn.

Der Token wird abgelehnt

Ein Server hat 7 Tage, um sich mit einem Token zu registrieren; danach nimmt der Token 7 weitere Tage lang neue Läufe dieser Installation an.

• „The server does not know this token, or it expired“: Bitte deinen Ansprechpartner bei detachbox um einen neuen.
• This token was already used by another machine: Die Zeile nennt Hostnamen, Adresse und Uhrzeit dieses Servers. Ein Token gehört dem ersten Server, der sich damit registriert hat. Ist das nicht dein Server, nutz den Node nicht und sag sofort dem detachbox-Support Bescheid; für einen anderen deiner Server bitte um einen neuen Token.
• „The server has not finished setting up this node's tunnel and certificate“: Bitte deinen Ansprechpartner bei detachbox um einen neuen Token und führ den Befehl dann damit aus.
• „This token's node is live already“: Der Token ist für einen laufenden Node verbraucht. Auf dem Server, der sich damit registriert hat, läuft der Node; öffne https://my.detachbox.com. Für einen anderen Server bitte um einen neuen Token: Jeder Server braucht seinen eigenen.
• Der Server hat sich mit einem anderen Token registriert: Führ den Befehl mit diesem aus.

Der Befehl stoppt vor seinen Prüfungen

• no answer from https://api.detachbox.com: Der Server braucht ausgehendes HTTPS (Port 443). Führ denselben Befehl noch einmal aus, sobald er es hat.
• this token downloaded node-host several times lately: Warte die genannten Minuten ab und führ dann denselben Befehl noch einmal aus.
• the server asks this machine to slow down (429): Führ denselben Befehl in einer Minute noch einmal aus.
• Der Server ist kein Ubuntu 26.04 auf x86_64, oder der Befehl lief nicht als root: Die Zeile sagt, was davon zutrifft.

Die Aufzeichnung der Installation ist nicht lesbar

/var/lib/detachbox-node/install/state.json ist die Aufzeichnung der Installation darüber, was sie auf dem Server getan hat. Fiel der Strom aus, während sie geschrieben wurde, stoppen Installation und Deinstallation beide mit does not read: Ohne die Aufzeichnung weiß keine von beiden, was zum Node gehört, und keine rät. Schick diese Zeile an deinen Ansprechpartner bei detachbox. Um neu anzufangen, nimm den Node von Hand vom Server, wie es „Von Hand entfernen“ auf Den Node entfernen auflistet, lösch dann mit sudo rm /var/lib/detachbox-node/install/state.json die Aufzeichnung und führ den Installationsbefehl noch einmal aus.

--destroy-pool lässt die Disk, wie sie ist

--destroy-pool löscht die Disk nur, wenn alles darauf von der Installation stammt. Zwei Ablehnungen kommen am häufigsten vor:

• Die Disk is not the disk the pool boxes was made on: Ihr Name hat sich seit der Installation geändert, etwa von /dev/sdb zu /dev/sdc. lsblk -o NAME,WWN,SERIAL findet die gespeicherte Disk unter ihrem heutigen Namen. Oder führ uninstall --confirm ohne --destroy-pool aus: Das lässt die Disk, wie sie ist, und entfernt den Rest.
• Die Disk oder eine Partition „holds …, which this install did not put there“ oder trägt das ZFS-Label eines anderen Pools. Ist nichts darauf wichtig, lösch sie selbst mit sudo wipefs -a /dev/sdb; uninstall --confirm ohne --destroy-pool entfernt den Rest.

Ein anderer Lauf ist am Werk

Es läuft immer nur eine Installation oder Deinstallation. Die Meldung nennt Beginn und Prozess dieses Laufs. Verfolge ihn mit sudo tail -f /var/lib/detachbox-node/install/install.log. Hängt er wirklich fest, stoppt sudo kill <pid> ihn innerhalb von Sekunden; führ dann denselben Befehl noch einmal aus.

Ein Schritt scheitert

Vor Schritt 6 liegt detachbox-node-host noch nicht im PATH: Die Prüfungen laufen dann über denselben Installationsbefehl mit angehängtem --check, der nichts ändert und keinen Token verbraucht.

• Pakete: apt konnte pkgs.zabbly.com, pkg.cloudflare.com oder deinen apt-Mirror nicht erreichen; der Befehl mit --check prüft den Weg dorthin.
• OpenZFS: apt konnte nicht installieren, was der Build braucht, oder das Release kam nicht von github.com und release-assets.githubusercontent.com; der Befehl mit --check prüft den Weg dorthin. Ein abgebrochener Build beginnt wieder in einem sauberen Verzeichnis. Scheitert DKMS, sagen dkms status und /var/lib/dkms/zfs/2.4.4/build/make.log, warum.
• Incus: sudo journalctl -u incus -n 50 zeigt, was Incus gemeldet hat.
• Das Basis-Image: Seine letzten Zeilen nennen den Teil des Builds, der gescheitert ist; es lädt von den Hosts, die der Befehl mit --check prüft.
• cloudflared und node-host: sudo journalctl -u detachbox-node-host -u cloudflared-detachbox -n 50 sagt, warum.
• Die Inbetriebnahme: Nach 10 Minuten, in denen node-host nicht erreichbar war, verweist der Befehl auf den Tunnel, der ausgehendes TCP und UDP 7844 braucht. Stoppt der Server die Inbetriebnahme, sagt die Zeile, warum, und dein Ansprechpartner bei detachbox sieht es auch. Ist der Node nach 45 Minuten nicht live, führ sudo detachbox-node-host doctor aus und dann denselben Befehl noch einmal, um weiter mitzulesen.

Die Logs

Was an den Support geht

Ein gescheiterter Installationsschritt erreicht detachbox von selbst, mit deinem Token. Für alles andere:

1. Sobald der Node registriert ist, führ sudo detachbox-node-host doctor --report aus. Es schickt das Ergebnis von doctor und die Eckdaten des Servers an detachbox. Davor hat ein gescheiterter Schritt detachbox schon erreicht.
2. Schreib an support@detachbox.com oder öffne Support im Dashboard, mit der gescheiterten Zeile und den letzten Zeilen des Logs: sudo tail -n 100 /var/lib/detachbox-node/install/install.log.