Solución de problemas del nodo

Cada ✗ y cada paso fallido imprime su propia solución, y el mismo comando, ejecutado de nuevo, sigue desde donde se detuvo la instalación. Empieza por la línea que imprimió. Aquí abajo están los fallos con los que más se topan los administradores.

Una comprobación dice que el disco no está vacío

El disco tiene particiones, una tabla de particiones, un sistema de archivos o una firma, y el instalador nunca limpia un disco por ti. Si nada de lo que contiene importa, ejecuta sudo wipefs -a /dev/sdb con tu disco. Cuando el disco pertenece a un pool de ZFS, la línea nombra el pool: destrúyelo primero con sudo zpool destroy <pool>, que destruye todos sus archivos. Un disco con LVM aparece como tal. Quita primero su LVM: pvs /dev/sdb nombra su grupo de volúmenes, vgremove <group> destruye sus volúmenes, y después ejecuta pvremove /dev/sdb.

Una comprobación encuentra otro software en el servidor

El nodo ocupa todo el servidor, así que Docker, LXD, un Incus o un cloudflared que no puso el instalador, u otro pool de ZFS, detienen la instalación. La línea lista cada uno con el comando que lo quita, como apt-get purge docker-ce docker.io o snap remove --purge lxd. Quítalos, o usa un servidor limpio.

Fallan Secure Boot o las cabeceras del kernel

El nodo compila su propio módulo ZFS. Desactiva Secure Boot en el firmware, o registra la clave de DKMS: apt-get install dkms, después mokutil --import /var/lib/dkms/mok.pub, y confírmalo en el siguiente arranque. Para las cabeceras: apt-get update && apt-get install linux-headers-$(uname -r); si apt sigue sin tenerlas, apt-get full-upgrade y reinicia con el kernel más nuevo.

Fallan la salida, TLS o el reloj

• La comprobación de salida nombra cada destino que no respondió. Permite TCP saliente hacia ellos, y UDP 7844 hacia el túnel de Cloudflare. Lo que necesita el servidor tiene la lista completa.
• TLS nombra la autoridad que firmó lo que recibió. Deja pasar api.detachbox.com y *.argotunnel.com sin inspección TLS.
• Reloj: timedatectl set-ntp true, y deja que el servidor llegue a sus servidores NTP por UDP 123.

El disco guarda un pool conservado

Un nodo anterior de este servidor se desinstaló conservando su pool, y la nueva instalación rechaza ese disco: un nodo nuevo nunca se queda con los archivos del nodo anterior. Dale al nodo nuevo otro disco (lsblk -d -o NAME,SIZE,MODEL,SERIAL los lista) o, si nada del pool conservado importa, ejecuta el comando que imprime la línea: su uninstall --confirm --destroy-pool destruye el pool con todo lo que contiene y quita ZFS y detachbox-node-host. Si vuelves a importar el pool conservado para leer sus archivos, aparece en la comprobación de otro software: sudo zpool export boxes lo devuelve a su disco, y el comando de desinstalación que imprime la línea lo quita.

Se rechaza el token

Un servidor tiene 7 días para registrarse con un token, y una vez registrado, el token admite repeticiones de esa instalación durante 7 días más.

• «The server does not know this token, or it expired»: pide un token nuevo a tu contacto en detachbox.
• This token was already used by another machine: la línea indica el nombre de host, la dirección y la hora de ese servidor. Un token pertenece al primer servidor que se registró con él. Si ese servidor no es tuyo, no uses el nodo y avisa al soporte de detachbox de inmediato; para otro servidor tuyo, pide un token nuevo.
• «The server has not finished setting up this node's tunnel and certificate»: pide un token nuevo a tu contacto en detachbox y ejecuta el comando con él.
• «This token's node is live already»: el token ya se gastó en un nodo activo. En el servidor que se registró con él, el nodo está en marcha; abre https://my.detachbox.com. Para otro servidor, pide un token nuevo: cada servidor necesita el suyo.
• El servidor se registró con otro token: ejecuta el comando con ese.

El comando se detiene antes de sus comprobaciones

• no answer from https://api.detachbox.com: el servidor necesita HTTPS saliente (puerto 443). Vuelve a ejecutar el mismo comando cuando lo tenga.
• this token downloaded node-host several times lately: espera los minutos que indica y vuelve a ejecutar el mismo comando.
• the server asks this machine to slow down (429): vuelve a ejecutar el mismo comando dentro de un minuto.
• El servidor no es Ubuntu 26.04 en x86_64, o el comando no se ejecutó como root: la línea dice cuál de las dos cosas pasa.

El historial de la instalación no se puede leer

/var/lib/detachbox-node/install/state.json es el historial de lo que la instalación hizo en el servidor. Si el servidor se quedó sin corriente mientras se escribía, la instalación y la desinstalación se detienen con does not read: sin el historial, ninguna de las dos sabe qué es del nodo, y ninguna adivina. Envía esa línea a tu contacto en detachbox. Para empezar de cero, quita el nodo a mano como indica «Quítalo a mano» en Quita el nodo, después ejecuta sudo rm /var/lib/detachbox-node/install/state.json y vuelve a ejecutar el comando de instalación.

--destroy-pool deja el disco como está

--destroy-pool solo limpia el disco cuando todo lo que hay en él es de la instalación. Estos son los dos rechazos más habituales:

• El disco is not the disk the pool boxes was made on: el nombre del disco cambió desde la instalación, por ejemplo /dev/sdb pasó a ser /dev/sdc. lsblk -o NAME,WWN,SERIAL encuentra el disco registrado con el nombre que tiene ahora. O ejecuta uninstall --confirm sin --destroy-pool, que deja el disco y quita todo lo demás.
• El disco o una partición «holds …, which this install did not put there», o lleva la etiqueta ZFS de otro pool. Si nada de lo que contiene importa, límpialo tú con sudo wipefs -a /dev/sdb; uninstall --confirm sin --destroy-pool quita el resto.

Otra ejecución está trabajando

Solo corre una instalación o desinstalación a la vez. El mensaje indica el inicio y el proceso de esa ejecución. Síguela con sudo tail -f /var/lib/detachbox-node/install/install.log. Si de verdad está atascada, sudo kill <pid> la detiene en segundos; después vuelve a ejecutar el mismo comando.

Falla un paso

Antes del paso 6, detachbox-node-host aún no está en el PATH: las comprobaciones se ejecutan con el mismo comando de instalación añadiendo --check, que no cambia nada ni gasta el token.

• Paquetes: apt no pudo llegar a pkgs.zabbly.com, pkg.cloudflare.com o a tu mirror de apt; el comando con --check comprueba el camino hasta ellos.
• OpenZFS: apt no pudo instalar lo que necesita la compilación, o la versión no llegó de github.com y release-assets.githubusercontent.com; el comando con --check comprueba el camino hasta allí. Una compilación interrumpida vuelve a empezar desde un árbol limpio. Cuando falla DKMS, dkms status y /var/lib/dkms/zfs/2.4.4/build/make.log dicen por qué.
• Incus: sudo journalctl -u incus -n 50 muestra lo que dijo Incus.
• La imagen base: sus últimas líneas nombran la parte de la construcción que falló; descarga de los hosts que comprueba el comando con --check.
• cloudflared y node-host: sudo journalctl -u detachbox-node-host -u cloudflared-detachbox -n 50 dice por qué.
• La puesta en marcha: tras 10 minutos sin llegar a node-host, el comando apunta al túnel, que necesita TCP y UDP 7844 salientes. Cuando el servidor detiene la puesta en marcha, la línea dice por qué y tu contacto en detachbox también lo ve. Tras 45 minutos sin que el nodo esté activo, ejecuta sudo detachbox-node-host doctor, y después el mismo comando otra vez para seguirla.

Los logs

Qué enviar al soporte

Un paso fallido de la instalación llega solo a detachbox, con tu token. Para todo lo demás:

1. Cuando el nodo ya se haya registrado, ejecuta sudo detachbox-node-host doctor --report. Envía el resultado de doctor y los datos del servidor a detachbox. Antes de eso, un paso fallido ya ha llegado a detachbox.
2. Escribe a support@detachbox.com, o abre Soporte en el panel, con la línea que falló y las últimas líneas del log: sudo tail -n 100 /var/lib/detachbox-node/install/install.log.