Registro de nós (enrollment)

Fazer o onboarding de um novo nó no NGBackup precisa apenas de duas coisas: o endereço do Director e um nome para este nó. O daemon registra a si mesmo sobre TLS: ele apresenta apenas o nome, o Director cria o recurso Client ou Storage, gera a senha compartilhada, os dois lados a selam em seus cofres de segredos, e o canal normal assume. Sem senha carregada à mão, sem SSH, sem editar arquivos de configuração, e sem token para gerar ou colar. Isso é o enrollment aberto, e é o padrão.

Fazer o onboarding de um Storage (SD) e de um Cliente (FD) é o procedimento idêntico. Eles diferem apenas no nome do daemon e nas flags opcionais de dispositivo do Storage.

O endpoint de enrollment do Director é sua porta de console já existente 9101. O nó conecta para fora, então funciona atrás de NAT.

Registrar um cliente (File Daemon)

Após instalar o backup-fd, aponte-o para o Director e dê um nome a ele:

backup-fd --enroll --director dir.example.com:9101 --name web-01

Depois inicie-o - o modo daemon é o padrão, então nenhuma flag é necessária:

backup-fd

É isso. O Director cria o Client chamado web-01, sela uma senha compartilhada nos dois lados, e daqui em diante o cliente é gerenciado inteiramente pela rede (.reconfigure client=web-01, .restart client=web-01, configuração versionada) via o plano de gerenciamento.

Registrar um storage (Storage Daemon)

Idêntico na forma - troque o binário e o nome. Um nó de storage também pode definir o layout dos seus dispositivos de disco no enrollment:

backup-sd --enroll --director dir.example.com:9101 --name store-01 \
  --archive-device /opt/backup/storage --rw-devices 10 --ro-devices 2

Depois inicie-o:

backup-sd

O Director cria o Storage chamado store-01. As flags de dispositivo são opcionais:

Flag	Significado
`--archive-device DIR`	Diretório onde o storage em disco registrado grava os volumes. Padrão `/opt/backup/storage`.
`--rw-devices N`	Dispositivos virtuais de leitura/escrita no autochanger em disco gerado. Padrão 10 (escritas de jobs concorrentes).
`--ro-devices M`	Dispositivos virtuais somente leitura para restauração / Instant Recovery. Padrão 2.

Flags comuns

Ambos os daemons compartilham as mesmas flags de enrollment:

--config assume por padrão /opt/backup/etc/backup-fd.conf (FD) ou /opt/backup/etc/backup-sd.conf (SD); passe-o apenas para um caminho não padrão.
--director-fingerprint SHA256 é opcional - omita-o para trust-on-first-use (um aviso é impresso), ou passe-o para fixar o certificado do Director contra um man-in-the-middle.
Re-executar --enroll contra uma configuração existente é recusado a menos que você passe --force.

Os instaladores fazem isso por você

Os instaladores da plataforma pedem exatamente essas duas coisas - o endereço do Director e um nome - e executam o enrollment, registram o serviço e abrem o firewall.

Linux - sudo bash install.sh (papel client ou storage) pergunta o endereço do Director e um nome. Não interativo: --director dir.example.com:9101 --name web-01. Os wizards por daemon install-ngbackup-fd.sh / install-ngbackup-sd.sh recebem os mesmos --director + --name.
Windows - a página Connect do NGBackup-fd-Setup.exe gráfico tem dois campos: Director enrollment endpoint (host:port) e Name for this client. Ele instala o serviço, abre o firewall e faz o enroll. Silencioso: /S /DIRECTOR=dir.example.com:9101 /NAME=web-01.

O que o enrollment cria

Sobre uma única conexão TLS ao :9101:

O nó verifica o certificado TLS do Director. Passe --director-fingerprint para fixá-lo; sem a flag, ele recorre ao trust-on-first-use e imprime um aviso alto - fixe em produção, ou sobre redes não confiáveis.
Com AllowOpenEnrollment = yes (o padrão), o Director aceita o nome escolhido pelo nó e cria o recurso Client ou Storage via config-as-data - uma revisão commitada, ativada e auditável.
O Director gera uma senha compartilhada de alta entropia, a sela em seu próprio cofre de segredos, e a entrega ao nó.
O nó sela a senha localmente (fazendo o bootstrap de uma master.key no primeiro uso) e escreve um backup-fd.conf / backup-sd.conf pronto cujo Password é uma referência @secret: - sem texto plano em disco.

Controle no lado do Director: AllowOpenEnrollment

O enrollment aberto é governado por uma diretiva no recurso Director:

AllowOpenEnrollment = yes    # padrão

Deixe em yes (o padrão) e qualquer nó que tenha o endereço do Director pode se registrar sozinho com um nome. Defina como no para exigir um token pré-gerado (veja Avançado abaixo); tentativas sem token são então recusadas.

Avançado: enrollment por token (sites restritos)

Para sites que definem AllowOpenEnrollment = no, um nó precisa apresentar um token bearer de uso único gerado no Director. Esse caminho é opcional - use-o apenas quando quiser controlar exatamente quais nós podem entrar.

Gere um token sobre uma sessão de console segura (TLS / TLS-PSK - o build padrão backup-console):

*.enroll-token client=web-01 ttl=1800 cidr=10.0.0.0/24 profile=default

Argumento	Significado
`client=NAME`	(obrigatório) o único nó que este token pode registrar (`[A-Za-z0-9._-]`, ≤128 caracteres).
`ttl=SECONDS`	Tempo de vida do token. Padrão 1800 (30 min), limitado a 86400 (1 dia).
`cidr=A.B.C.D/N`	Opcionalmente restringe o endereço de origem de onde o token pode ser resgatado (IPv4 ou IPv6).
`profile=NAME`	Aplica um template embutido de Job + Content - `default`, `home` ou `system`.

A resposta traz o token completo uma única vez (apenas um hash é armazenado no catálogo) mais a director_fingerprint. Faça o enroll com --token em vez de --name:

backup-fd --enroll --director dir.example.com:9101 --token ab12.cd34

Gerencie os tokens pendentes com .enroll-token-list client=NAME (estado: live/used/expired/revoked) e .enroll-token-revoke token=ID. Tokens terminais com mais de um dia são varridos automaticamente.

Propriedades de segurança do token

Token de alta entropia e uso único - o segredo tem 256 bits; o catálogo armazena apenas seu hash SHA-256, e o resgate o consome atomicamente.
TTL curto - 30 minutos por padrão, limitado a no máximo um dia.
Fixação opcional de CIDR - o token só é resgatável a partir da rede de origem declarada.
Limite de taxa por IP - no máximo 10 tentativas de enrollment por IP de origem por janela deslizante de 60 segundos, com mensagens de erro uniformes.
Emissão e resgate auditados - a geração exige uma sessão segura + CommandACL, e todo desfecho (aceito / rejeitado, com IP de origem) é anexado ao enroll-audit.log ao lado da configuração do Director.

Solução de problemas

Sintoma	Causa / correção
Reset do handshake TLS / conexão recusada no `--enroll`	O Director não tem certificado TLS configurado - defina `TlsCertificate` + `TlsKey` no seu recurso `Director` (veja a nota de pré-requisito acima) e reinicie-o.
Enrollment recusado com um nome (sem token)	`AllowOpenEnrollment` está em `no` no Director - defina-o como `yes`, ou gere um token e faça o enroll com `--token` (veja Avançado acima).
Erro de fingerprint incompatível no nó	O `--director-fingerprint` não corresponde ao certificado do Director - copie-o de novo, ou descarte um man-in-the-middle. A flag é opcional; remova-a para trust-on-first-use.
Tentativas repetidas subitamente recusadas	Limite de taxa por IP (10 tentativas / 60 s) - espere um minuto e tente de novo.
`--enroll` se recusa a rodar	Já existe uma configuração no caminho de destino - passe `--force` para refazer o enroll.