Skip to content

Onboarding a new machine

Bringing any new device into the backup estate is self-service and takes about fifteen minutes. The heavy lifting is one script on ops (add-backup-endpoint.sh); everything else is typing what it prints into KopiaUI and proving the result works.

Where things live

The Kopia repo sits on the NAS but endpoints never mount it — they talk HTTPS to the Kopia repository server on the ops LXC (https://192.168.1.190:51515). One server user exists per machine (backup@<name>); passwords live in /etc/backup-stack/kopia-users.env on ops. Central knobs (server URL, upload cap, minimum-source count) live in /etc/backup-stack/backup-targets.env on ops.

The six-step recipe

1. Network first

  • Give the machine a DHCP reservation in the UniFi console.
  • If it should back up away from home, install Tailscale and sign in. macOS / iOS / Windows accept subnet routes by default; Linux machines need sudo tailscale set --accept-routes to see the home LAN remotely (ops advertises 192.168.1.0/24 — see Tailscale).

2. Create its backup identity — one command on ops

Pick a short name (e.g. pc3) and run:

ssh root@192.168.1.190 add-backup-endpoint.sh pc3

It creates the server user, stores the password in kopia-users.env, restarts the Kopia server, and prints everything step 3 asks for (server URL, cert fingerprint, username, hostname, password). Safe to re-run — it just reprints.

3. Connect the machine (KopiaUI)

Install KopiaUI (winget install Kopia.KopiaUI on Windows, brew install kopia or the KopiaUI app on macOS), then Connect to Repository Server and enter exactly what step 2 printed:

KopiaUI field Value
Server address https://192.168.1.190:51515
Trusted server certificate fingerprint c35cdeb5ccea0b2de0610cff4aaf0da977fe649f169f0956f7bf3676d3806756
Username override backup
Hostname override the machine's short name (pc3, tablet, …)
Password printed by add-backup-endpoint.sh (stored in kopia-users.env on ops)

Then add the machine's folders as snapshot sources — the global policy (hourly snapshots, retention, compression) applies automatically. Bandwidth needs no per-machine setup: a 10 MB/s cap is enforced repo-wide on ops.

Fingerprint changed?

Re-derive it on ops anytime: openssl x509 -in /etc/backup-stack/kopia.cert -noout -fingerprint -sha256 (strip colons, lowercase).

For a pure-CLI box (Linux/VPS) the equivalent is:

kopia repository connect server \
  --url "https://192.168.1.190:51515" \
  --server-cert-fingerprint "c35cdeb5ccea0b2de0610cff4aaf0da977fe649f169f0956f7bf3676d3806756" \
  --override-username backup --override-hostname <name>

plus a systemd timer / launchd job running kopia snapshot create on its source list.

4. Tell the monitor to expect it

After its first snapshot completes, bump KOPIA_MIN_SOURCES by one in /etc/backup-stack/backup-targets.env on ops. From then on the machine going missing shows up in the daily digest. (First-backups-not-yet-finished are digest-only by design — they never page.)

5. Windows extras (Veeam + WoL)

  • Configure a Veeam Agent image job per the Veeam checklist pattern — entire computer, SMB share on the NAS, game-directory exclusions, job encryption ON (password in the password manager, not the NAS password), and create the recovery-media USB after the first run.
  • Record the machine's MAC on ops and add a wol-*.timer for its backup window.

WoL timers are gated OFF

Scheduled nightly wakes stay disabled (WOL_ENABLED=0 in the config) until Veeam is actually configured — there is nothing to wake for yet. Manual wake works today: ssh root@192.168.1.190 wol-wake.sh pc1|pc2. The tablet is WiFi-only, which WoL cannot reliably reach — its Veeam job should use Windows' own wake-from-sleep instead.

6. Prove it before trusting it

Take a snapshot, then restore one file to the Desktop and open it. The next morning's digest should list the new source. This step is mandatory — unproven backups are the house-rule violation; this estate ran a system that reported green for 62 nights while backing up nothing (see Security history).

Rotating a machine's Kopia password

Do this if a laptop is lost/stolen (lost device) or on general hygiene:

  1. On ops, set a new password for the server user (let it prompt rather than putting the value in shell history):

    kopia server users set backup@pc3 --ask-user-password

  2. Update that machine's line in /etc/backup-stack/kopia-users.env on ops so the file stays the source of truth.

  3. systemctl restart kopia-server on ops so the server picks up the change. The old credential is now dead — the machine's snapshots start failing soft.
  4. On the endpoint, reconnect with the new password (KopiaUI → repository → disconnect → Connect to Repository Server again, same fields as step 3 above).
  5. Verify: take a snapshot, confirm it completes.

Note

Rotating a user password does not touch the repository master password (vaulted in the password manager) — endpoints never see that.

Related: backups overview · restores · off-site · current status