Secrets & encrypted config

Backup daemons authenticate to each other with CRAM-MD5 shared secrets — passwords that the protocol needs in plaintext at both ends, so they cannot be hashed. Historically they sat in the clear in every .conf. NGBackup replaces them with @secret: references backed by an encrypted store, so the only thing you must protect carefully is one master key per host.

How it works

• A .conf directive holds a reference instead of a value:

  Director {
    Name = backup-dir
    Password = "@secret:dir-console-password"
  }

• The real values live AEAD-encrypted (ChaCha20-Poly1305) in a sealed file, secrets.enc, unlocked by a 32-byte master.key.

• Each daemon resolves the references in memory at boot — the plaintext never touches disk in the config.

• A config with no @secret: reference is untouched (plaintext configs keep working), and an unresolvable reference makes the daemon fail closed with a clear error rather than authenticate with a wrong or empty password.

The backup-secrets tool

Run it as the daemon’s user so the key and store are owned correctly (e.g. sudo -u backup …):

SEC="backup-secrets --key-file /opt/backup/etc/master.key --secrets /opt/backup/etc/secrets.enc"

$SEC init                              # mint a master key (0600; refuses to overwrite)
printf '%s' "$VALUE" | $SEC set NAME   # seal a secret (value via stdin — never in argv/ps)
$SEC list                              # secret names only (never values)
$SEC resolve -c CONFIG                 # preview a config with references resolved
$SEC seal-config -c CONFIG             # migrate a config's plaintext passwords → @secret in one pass
$SEC rotate-key                        # re-encrypt the whole store under a fresh master key

seal-config is the easy path for existing configs: point it at a .conf and it seals every plaintext Password / DbPassword, rewrites them as @secret: references (named after the resource), and backs up the original to *.conf.pre-seal. Use --dry-run to preview.

Secret-free by default

Generating a host’s default configuration is secret-free out of the box — no plaintext passwords are ever written:

backup-config install --confdir /opt/backup/etc

This mints the per-edge passwords, seals them into secrets.enc, creates the host’s master.key (if absent), emits @secret: references in the generated .conf files, and reminds you to back up the master.key out of band. Pass --no-seal-secrets only if you specifically need legacy plaintext passwords.

First thing after install: back up the master key

A default install creates master.key in the config directory. Copy it somewhere safe and separate before you do anything else — without it the daemons can’t start. See Disaster recovery.

Key rotation

After a suspected key exposure, backup-secrets rotate-key re-encrypts the whole store under a new key. It writes the new key and store to temporary files and verifies they open together before swapping, so a crash mid-rotation can never leave a store the daemons can’t open. The old key and store are kept at *.bak. Restart the daemons (they re-read the key at boot), back up the new key out of band, then destroy the *.bak files.

Back up the master key out of band

The master.key is the one irreducible secret per host — keep a copy somewhere safe and separate (password manager, printed in a safe, an HSM). Lose it and that host’s daemons cannot resolve their passwords and will not start (by design — fail closed). The encrypted secrets.enc is useless without it, so it’s safe to keep secrets.enc in your regular backup set. See Disaster recovery.

Related

• The catalog database password is eliminated entirely on platforms that support peer / socket authentication — there is no DB password to store. See the Catalog reference.
• Setting a secret remotely goes through .reconfigure over a secure console session; the read verbs always redact existing values.