Dépannage du nœud

Chaque ✗ et chaque étape en échec affiche sa propre correction, et la même commande, relancée, reprend là où l’installation s’est arrêtée. Partez de la ligne qu’elle a affichée. Voici les cas que les administrateurs rencontrent le plus souvent.

Une vérification dit que le disque n’est pas vide

Le disque porte des partitions, une table de partitions, un système de fichiers ou une signature, et l’installateur n’efface jamais un disque à votre place. Si rien dessus ne compte, lancez sudo wipefs -a /dev/sdb pour votre disque. Quand le disque appartient à un pool ZFS, la ligne nomme le pool : détruisez-le d’abord avec sudo zpool destroy <pool>, ce qui efface chaque fichier qu’il contient. Un disque LVM est désigné comme tel. Retirez d’abord son LVM : pvs /dev/sdb nomme son groupe de volumes, vgremove <group> détruit ses volumes, puis lancez pvremove /dev/sdb.

Une vérification trouve d’autres logiciels sur le serveur

Le nœud prend tout le serveur : Docker, LXD, un Incus ou un cloudflared que l’installateur n’a pas mis là, ou un autre pool ZFS bloquent l’installation. La ligne liste chacun avec la commande qui le retire, comme apt-get purge docker-ce docker.io ou snap remove --purge lxd. Retirez-les, ou prenez un serveur propre.

Secure Boot ou les en-têtes du noyau échouent

Le nœud compile son propre module ZFS. Désactivez Secure Boot dans le firmware, ou enrôlez la clé DKMS : apt-get install dkms, puis mokutil --import /var/lib/dkms/mok.pub, et confirmez-la au démarrage suivant. Pour les en-têtes : apt-get update && apt-get install linux-headers-$(uname -r) ; si apt n’en a toujours pas, apt-get full-upgrade puis redémarrez sur le noyau le plus récent.

La sortie réseau, TLS ou l’horloge échouent

• La vérification de sortie nomme chaque destination qui n’a pas répondu. Autorisez le TCP sortant vers ces destinations, et l’UDP 7844 vers le tunnel de Cloudflare. Ce qu’il faut au serveur donne la liste complète.
• TLS nomme l’autorité qui a signé ce qui est arrivé. Laissez passer api.detachbox.com et *.argotunnel.com sans inspection TLS.
• Horloge : timedatectl set-ntp true, et laissez le serveur joindre ses serveurs NTP en UDP 123.

Le disque porte un pool gardé

Un nœud précédent sur ce serveur a été désinstallé en gardant son pool, et la nouvelle installation refuse ce disque : un nouveau nœud ne reprend jamais les fichiers de l’ancien. Donnez au nouveau nœud un autre disque (lsblk -d -o NAME,SIZE,MODEL,SERIAL les liste), ou, si rien sur le pool gardé ne compte, lancez la commande qu’affiche la ligne : son uninstall --confirm --destroy-pool détruit le pool avec tout ce qu’il contient et retire ZFS et detachbox-node-host. Si vous avez de nouveau importé le pool gardé pour lire ses fichiers, il apparaît dans la vérification des autres logiciels : sudo zpool export boxes le remet sur son disque, et la commande de désinstallation affichée sur la ligne le retire.

Le jeton est refusé

Un serveur a 7 jours pour s’enregistrer avec un jeton, et une fois l’enregistrement fait, le jeton accepte les relances de cette installation pendant 7 jours de plus.

• « The server does not know this token, or it expired » : demandez-en un nouveau à votre contact chez detachbox.
• This token was already used by another machine : la ligne donne le nom d’hôte, l’adresse et l’heure de ce serveur. Un jeton appartient au premier serveur qui s’est enregistré avec lui. Si ce serveur n’est pas le vôtre, n’utilisez pas le nœud et prévenez tout de suite le support detachbox ; pour un autre de vos serveurs, demandez un nouveau jeton.
• « The server has not finished setting up this node's tunnel and certificate » : demandez un nouveau jeton à votre contact chez detachbox, puis lancez la commande avec ce jeton.
• « This token's node is live already » : le jeton a déjà servi pour un nœud en service. Sur le serveur qui s’est enregistré avec lui, le nœud tourne ; ouvrez https://my.detachbox.com. Pour un autre serveur, demandez un nouveau jeton : chaque serveur a besoin du sien.
• Le serveur s’est enregistré avec un autre jeton : lancez la commande avec celui-là.

La commande s’arrête avant ses vérifications

• no answer from https://api.detachbox.com : le serveur a besoin du HTTPS sortant (port 443). Relancez la même commande une fois qu’il l’a.
• this token downloaded node-host several times lately : attendez les minutes indiquées, puis relancez la même commande.
• the server asks this machine to slow down (429) : relancez la même commande dans une minute.
• Le serveur n’est pas un Ubuntu 26.04 sur x86_64, ou la commande n’a pas tourné en root : la ligne dit lequel des deux.

Le registre de l’installation est illisible

/var/lib/detachbox-node/install/state.json est le registre de ce que l’installation a fait sur le serveur. Si le serveur a perdu l’alimentation pendant son écriture, l’installation et la désinstallation s’arrêtent toutes deux sur does not read : sans le registre, aucune ne sait ce qui appartient au nœud, et aucune ne devine. Envoyez cette ligne à votre contact chez detachbox. Pour repartir de zéro, retirez le nœud à la main comme le détaille « Le retirer à la main » sur Retirer le nœud, puis lancez sudo rm /var/lib/detachbox-node/install/state.json et relancez la commande d’installation.

--destroy-pool laisse le disque tel quel

--destroy-pool n’efface le disque que si tout ce qu’il contient vient de l’installation. Deux refus reviennent le plus souvent :

• Le disque is not the disk the pool boxes was made on : son nom a changé depuis l’installation, par exemple /dev/sdb devenu /dev/sdc. lsblk -o NAME,WWN,SERIAL retrouve le disque enregistré sous son nom actuel. Ou lancez uninstall --confirm sans --destroy-pool, qui laisse le disque et retire le reste.
• Le disque ou une partition « holds …, which this install did not put there », ou porte l’étiquette ZFS d’un autre pool. Si rien dessus ne compte, effacez-le vous-même avec sudo wipefs -a /dev/sdb ; uninstall --confirm sans --destroy-pool retire le reste.

Une autre exécution est en cours

Une seule installation ou désinstallation tourne à la fois. Le message indique le début et le processus de cette exécution. Suivez-la avec sudo tail -f /var/lib/detachbox-node/install/install.log. Si elle est vraiment bloquée, sudo kill <pid> l’arrête en quelques secondes ; relancez ensuite la même commande.

Une étape échoue

Avant l’étape 6, detachbox-node-host n’est pas encore dans le PATH : les vérifications passent alors par la même commande d’installation, avec --check en plus, qui ne change rien et ne consomme aucun jeton.

• Paquets : apt n’a pas pu joindre pkgs.zabbly.com, pkg.cloudflare.com ou votre miroir apt ; la commande avec --check vérifie le chemin vers eux.
• OpenZFS : apt n’a pas pu installer ce dont la compilation a besoin, ou la version publiée n’est pas venue de github.com et release-assets.githubusercontent.com ; la commande avec --check vérifie le chemin jusque-là. Une compilation interrompue repart d’un arbre propre. Quand DKMS échoue, dkms status et /var/lib/dkms/zfs/2.4.4/build/make.log disent pourquoi.
• Incus : sudo journalctl -u incus -n 50 montre ce qu’Incus a répondu.
• L’image de base : ses dernières lignes nomment la partie de la construction qui a échoué ; elle se télécharge depuis les hôtes que vérifie la commande avec --check.
• cloudflared et node-host : sudo journalctl -u detachbox-node-host -u cloudflared-detachbox -n 50 dit pourquoi.
• La mise en service : après 10 minutes sans que node-host soit joint, la commande désigne le tunnel, qui a besoin du TCP et de l’UDP 7844 sortants. Quand le serveur arrête la mise en service, la ligne dit pourquoi, et votre contact chez detachbox le voit aussi. Si le nœud n’est pas en service au bout de 45 minutes, lancez sudo detachbox-node-host doctor, puis relancez la même commande pour continuer à suivre.

Les journaux

Quoi envoyer au support

Une étape d’installation en échec parvient d’elle-même à detachbox, avec votre jeton. Pour tout le reste :

1. Une fois le nœud enregistré, lancez sudo detachbox-node-host doctor --report. La commande envoie le résultat de doctor et les caractéristiques du serveur à detachbox. Avant cela, une étape en échec a déjà atteint detachbox.
2. Écrivez à support@detachbox.com, ou ouvrez Support dans le tableau de bord, avec la ligne qui a échoué et les dernières lignes du journal : sudo tail -n 100 /var/lib/detachbox-node/install/install.log.