Node enrollment

Onboarding a new node in NGBackup needs only two things: the Director address and a name for this node. The daemon enrolls itself over TLS: it presents just the name, the Director creates the Client or Storage resource, generates the shared password, both sides seal it into their secret stores, and the normal channel takes over. No hand-carried password, no SSH, no editing config files, and no token to mint or paste. This is open enrollment, and it is on by default.

Onboarding a Storage (SD) and a Client (FD) is the identical procedure. They differ only in the daemon name and a Storage’s optional device flags.

The Director’s enrollment endpoint is its existing console port 9101. The node connects out, so it works behind NAT.

Director prerequisite: a TLS certificate

Enrollment runs over TLS, so the Director needs a certificate configured - TlsCertificate + TlsKey in its Director resource (a self-signed cert is fine). Without one, the enrollment handshake is refused. This is a one-time Director setup, not a per-node step.

Enroll a client (File Daemon)

After installing backup-fd, point it at the Director and give it a name:

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

Then start it - daemon mode is the default, so no flags are needed:

backup-fd

That’s it. The Director creates the Client named web-01, seals a shared password on both sides, and from here the client is managed entirely over the wire (.reconfigure client=web-01, .restart client=web-01, versioned config) via the management plane.

Enroll a storage (Storage Daemon)

Identical in shape - swap the binary and the name. A storage node may also set its disk device layout at enrollment:

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

Then start it:

backup-sd

The Director creates the Storage named store-01. The device flags are optional:

Flag	Meaning
--archive-device DIR	Directory the enrolled disk storage writes volumes to. Default /opt/backup/storage.
--rw-devices N	Read/write virtual devices in the generated disk autochanger. Default 10 (concurrent job writes).
--ro-devices M	Read-only virtual devices for restore / Instant Recovery reads. Default 2.

Common flags

Both daemons share the same enrollment flags:

• --config defaults to /opt/backup/etc/backup-fd.conf (FD) or /opt/backup/etc/backup-sd.conf (SD); pass it only for a non-default path.
• --director-fingerprint SHA256 is optional - omit it for trust-on-first-use (a warning is printed), or pass it to pin the Director’s certificate against a man-in-the-middle.
• Re-running --enroll against an existing config is refused unless you pass --force.

The installers do this for you

The platform installers ask for exactly those two things - the Director address and a name - and run the enrollment, register the service, and open the firewall.

• Linux - sudo bash install.sh (role client or storage) prompts for the Director address and a name. Non-interactive: --director dir.example.com:9101 --name web-01. The per-daemon wizards install-ngbackup-fd.sh / install-ngbackup-sd.sh take the same --director + --name.
• Windows - the graphical NGBackup-fd-Setup.exe Connect page has two fields: Director enrollment endpoint (host:port) and Name for this client. It installs the service, opens the firewall, and enrolls. Silent: /S /DIRECTOR=dir.example.com:9101 /NAME=web-01.

What enrollment creates

Over a single TLS connection to :9101:

1. The node verifies the Director’s TLS certificate. Pass --director-fingerprint to pin it; without the flag it falls back to trust-on-first-use and prints a loud warning - pin in production, or over untrusted networks.
2. With AllowOpenEnrollment = yes (the default), the Director accepts the node’s chosen name and creates the Client or Storage resource through config-as-data - a committed, activated, auditable revision.
3. The Director generates a high-entropy shared password, seals it into its own secret store, and hands it to the node.
4. The node seals the password locally (bootstrapping a master.key on first use) and writes a ready backup-fd.conf / backup-sd.conf whose Password is an @secret: reference - no plaintext on disk.

Director-side control: AllowOpenEnrollment

Open enrollment is governed by one directive in the Director resource:

AllowOpenEnrollment = yes    # default

Leave it yes (the default) and any node holding the Director address can self-enroll with a name. Set it to no to require a pre-minted token instead (see Advanced below); tokenless attempts are then refused.

Advanced: token enrollment (locked-down sites)

For sites that set AllowOpenEnrollment = no, a node must present a single-use bearer token minted on the Director. This path is optional - use it only when you want to gate exactly which nodes may join.

Mint a token over a secure console session (TLS / TLS-PSK - the default backup-console build):

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

Argument	Meaning
client=NAME	(required) the one node this token may enroll ([A-Za-z0-9._-], ≤128 chars).
ttl=SECONDS	Token lifetime. Default 1800 (30 min), capped at 86400 (1 day).
cidr=A.B.C.D/N	Optionally restrict the source address the token may be redeemed from (IPv4 or IPv6).
profile=NAME	Apply a built-in Job + Content template - default, home or system.

The reply carries the full token once (only a hash is stored in the catalog) plus the director_fingerprint. Enroll with --token instead of --name:

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

Manage outstanding tokens with .enroll-token-list client=NAME (state: live/used/expired/revoked) and .enroll-token-revoke token=ID. Terminal tokens older than a day are swept automatically.

Token security properties

• High-entropy, single-use token - the secret is 256 bits; the catalog stores only its SHA-256 hash, and redemption consumes it atomically.
• Short TTL - 30 minutes by default, hard-capped at one day.
• Optional CIDR pinning - the token is only redeemable from the declared source network.
• Per-IP rate limit - at most 10 enrollment attempts per source IP per 60-second sliding window, with uniform error messages.
• Audited issuance and redemption - minting requires a secure session + CommandACL, and every outcome (accepted / rejected, with source IP) is appended to enroll-audit.log beside the Director config.

Troubleshooting

Symptom	Cause / fix
TLS handshake reset / connection refused on --enroll	The Director has no TLS certificate configured - set TlsCertificate + TlsKey in its Director resource (see the prerequisite note above) and restart it.
Enrollment refused with a name (no token)	AllowOpenEnrollment is no on the Director - either set it to yes, or mint a token and enroll with --token (see Advanced above).
Fingerprint mismatch error on the node	The --director-fingerprint doesn’t match the Director’s certificate - re-copy it, or rule out a man-in-the-middle. The flag is optional; drop it for trust-on-first-use.
Repeated attempts suddenly refused	Per-IP rate limit (10 attempts / 60 s) - wait a minute and retry.
--enroll refuses to run	A config already exists at the target path - pass --force to re-enroll.