Solução de problemas do nó

Cada ✗ e cada passo com falha mostram a própria correção, e o mesmo comando rodado de novo continua de onde a instalação parou. Comece pela linha que ela imprimiu. Abaixo estão os casos que os administradores mais encontram.

Uma verificação diz que o disco não está vazio

O disco tem partições, uma tabela de partições, um sistema de arquivos ou uma assinatura, e o instalador nunca limpa um disco por você. Se nada nele importa, rode sudo wipefs -a /dev/sdb com o seu disco. Quando o disco pertence a um pool ZFS, a linha mostra o nome do pool: destrua o pool antes com sudo zpool destroy <pool>, o que destrói todos os arquivos nele. Um disco com LVM aparece como tal. Tire o LVM dele primeiro: pvs /dev/sdb mostra o grupo de volumes, vgremove <group> destrói os volumes dele, e depois rode pvremove /dev/sdb.

Uma verificação encontra outro software no servidor

O nó ocupa o servidor inteiro, então Docker, LXD, um Incus ou cloudflared que o instalador não colocou ali, ou outro pool ZFS, impedem a instalação. A linha lista cada um com o comando que o remove, como apt-get purge docker-ce docker.io ou snap remove --purge lxd. Remova-os, ou use um servidor limpo.

O Secure Boot ou os headers do kernel falham

O nó compila o próprio módulo ZFS. Desligue o Secure Boot no firmware, ou registre a chave DKMS: apt-get install dkms, depois mokutil --import /var/lib/dkms/mok.pub, e confirme no próximo boot. Para os headers: apt-get update && apt-get install linux-headers-$(uname -r); se o apt continuar sem eles, apt-get full-upgrade e reinicie no kernel mais novo.

Saída, TLS ou relógio falham

• A verificação de saída mostra cada destino que não respondeu. Libere TCP de saída para eles, e UDP 7844 para o túnel da Cloudflare. Do que o servidor precisa tem a lista completa.
• TLS mostra a autoridade que assinou o que recebeu. Libere api.detachbox.com e *.argotunnel.com sem inspeção de TLS.
• Relógio: timedatectl set-ntp true, e deixe o servidor alcançar os servidores NTP dele pela UDP 123.

O disco guarda um pool mantido

Um nó anterior neste servidor foi desinstalado mantendo o pool, e a nova instalação recusa esse disco: um nó novo nunca assume os arquivos do nó antigo. Dê outro disco ao nó novo (lsblk -d -o NAME,SIZE,MODEL,SERIAL lista os discos) ou, se nada no pool mantido importa, rode o comando que a linha mostra: o uninstall --confirm --destroy-pool dele destrói o pool com tudo o que tem dentro e remove o ZFS e o detachbox-node-host. Se você importar o pool mantido de novo para ler os arquivos, ele aparece na verificação de outro software: sudo zpool export boxes devolve o pool ao disco dele, e o comando de desinstalação que a linha mostra o remove.

O token é recusado

Um servidor tem 7 dias para se registrar com um token, e depois do registro o token aceita novas execuções dessa instalação por mais 7 dias.

• "The server does not know this token, or it expired": peça um token novo ao seu contato no detachbox.
• This token was already used by another machine: a linha mostra o nome de host, o endereço e o horário desse servidor. Um token pertence ao primeiro servidor que se registrou com ele. Se esse servidor não for seu, não use o nó e avise o suporte do detachbox na hora; para outro servidor seu, peça um token novo.
• "The server has not finished setting up this node's tunnel and certificate": peça um token novo ao seu contato no detachbox e rode o comando com ele.
• "This token's node is live already": o token já foi usado num nó ativo. No servidor que se registrou com ele, o nó está no ar; abra https://my.detachbox.com. Para outro servidor, peça um token novo: cada servidor precisa do seu.
• O servidor se registrou com outro token: rode o comando com aquele.

O comando para antes das verificações

• no answer from https://api.detachbox.com: o servidor precisa de HTTPS de saída (porta 443). Rode o mesmo comando de novo quando ele tiver.
• this token downloaded node-host several times lately: espere os minutos indicados e rode o mesmo comando de novo.
• the server asks this machine to slow down (429): rode o mesmo comando de novo daqui a um minuto.
• O servidor não é Ubuntu 26.04 em x86_64, ou o comando não rodou como root: a linha diz qual dos dois.

O histórico da instalação não pode ser lido

/var/lib/detachbox-node/install/state.json é o histórico do que a instalação fez no servidor. Se o servidor perdeu energia enquanto ele era gravado, a instalação e a desinstalação param com does not read: sem o histórico, nenhuma das duas sabe o que é do nó, e nenhuma tenta adivinhar. Mande essa linha para o seu contato no detachbox. Para recomeçar, tire o nó à mão como lista "Remova à mão" em Remova o nó, depois rode sudo rm /var/lib/detachbox-node/install/state.json e rode o comando de instalação de novo.

--destroy-pool deixa o disco como está

O --destroy-pool só limpa o disco quando tudo nele é da instalação. Estas são as duas recusas mais comuns:

• O disco is not the disk the pool boxes was made on: o nome do disco mudou desde a instalação, por exemplo /dev/sdb virou /dev/sdc. lsblk -o NAME,WWN,SERIAL encontra o disco registrado pelo nome que ele tem agora. Ou rode uninstall --confirm sem --destroy-pool, que deixa o disco e remove o resto.
• O disco ou uma partição "holds …, which this install did not put there", ou tem o rótulo ZFS de outro pool. Se nada nele importa, limpe você mesmo com sudo wipefs -a /dev/sdb; uninstall --confirm sem --destroy-pool remove o resto.

Outra execução está trabalhando

Só uma instalação ou desinstalação roda por vez. A mensagem mostra o início e o processo dessa execução. Acompanhe com sudo tail -f /var/lib/detachbox-node/install/install.log. Se ela estiver mesmo travada, sudo kill <pid> para a execução em segundos; depois rode o mesmo comando de novo.

Um passo falha

Antes do passo 6, o detachbox-node-host ainda não está no PATH: as verificações rodam pelo mesmo comando de instalação com --check no fim, que não muda nada e não gasta o token.

• Pacotes: o apt não conseguiu alcançar pkgs.zabbly.com, pkg.cloudflare.com ou o seu mirror do apt; o comando com --check confere o caminho até eles.
• OpenZFS: o apt não conseguiu instalar o que o build precisa, ou a versão não veio de github.com e release-assets.githubusercontent.com; o comando com --check confere o caminho até lá. Um build interrompido recomeça de uma árvore limpa. Quando o DKMS falha, dkms status e /var/lib/dkms/zfs/2.4.4/build/make.log dizem por quê.
• Incus: sudo journalctl -u incus -n 50 mostra o que o Incus disse.
• A imagem base: as últimas linhas dela mostram a parte do build que falhou; ela baixa dos hosts que o comando com --check confere.
• cloudflared e node-host: sudo journalctl -u detachbox-node-host -u cloudflared-detachbox -n 50 diz por quê.
• A ativação: depois de 10 minutos sem alcançar o node-host, o comando aponta para o túnel, que precisa de TCP e UDP 7844 de saída. Quando o servidor interrompe a ativação, a linha diz por quê, e o seu contato no detachbox também vê. Depois de 45 minutos sem o nó no ar, rode sudo detachbox-node-host doctor e depois o mesmo comando de novo para continuar acompanhando.

Os logs

O que mandar ao suporte

Um passo da instalação que falhou chega sozinho ao detachbox, com o seu token. Para todo o resto:

1. Depois que o nó se registrar, rode sudo detachbox-node-host doctor --report. Ele envia o resultado do doctor e os dados do servidor ao detachbox. Antes disso, um passo que falhou já chegou ao detachbox.
2. Escreva para support@detachbox.com, ou abra Suporte no painel, com a linha que falhou e as últimas linhas do log: sudo tail -n 100 /var/lib/detachbox-node/install/install.log.