147 lines
4.4 KiB
Markdown
147 lines
4.4 KiB
Markdown
# Kopia Backup Setup
|
|
|
|
> Last updated: 2026-04-20
|
|
|
|
## Architecture
|
|
|
|
- **Hypervisor:** Proxmox (MacBook Pro 2017 Intel)
|
|
- **Backup server runtime:** Debian VM on Proxmox
|
|
- **Repository storage:** Synology NAS via NFS (`192.168.1.34:/volume1/kopia-repository`)
|
|
- **Service:** Kopia Repository Server
|
|
- **Access:** Tailscale / LAN
|
|
- **TLS:** self-signed cert at `/etc/kopia/server.cert` + `/etc/kopia/server.key`
|
|
- **First client:** MacBook (claudio@macbook-main)
|
|
|
|
## Repository model
|
|
|
|
The repository blobs live on Synology NFS. The Kopia Repository Server acts as the HTTP/S layer in front of it. Clients connect to the server, not directly to the NAS share.
|
|
|
|
## Important paths (VM)
|
|
|
|
| Purpose | Path |
|
|
|---------|------|
|
|
| NFS mountpoint | `/srv/kopia-repo` |
|
|
| Repository blobs | `/srv/kopia-repo/repository` |
|
|
| TLS cert | `/etc/kopia/server.cert` |
|
|
| TLS key | `/etc/kopia/server.key` |
|
|
| Env vars | `/etc/kopia-server.env` |
|
|
| Systemd service | `/etc/systemd/system/kopia-server.service` |
|
|
|
|
## Users
|
|
|
|
| User | Identity | Machine |
|
|
|------|----------|---------|
|
|
| `claudio` | `claudio@macbook-main` | MacBook |
|
|
|
|
## Passwords (stored in pass)
|
|
|
|
All three passwords are stored in `pass`:
|
|
- `KOPIA_REPO_PW` — repository encryption password
|
|
- `KOPIA_SRV_CTRL_PW` — server control plane password
|
|
- `KOPIA_SRV_PW` — web UI login password
|
|
|
|
## How to get the cert fingerprint
|
|
|
|
```bash
|
|
openssl x509 -in /etc/kopia/server.cert -noout -fingerprint -sha256 | sed 's/://g' | cut -f 2 -d =
|
|
```
|
|
|
|
## Server commands
|
|
|
|
```bash
|
|
# Status
|
|
sudo systemctl status kopia-server --no-pager
|
|
|
|
# Logs
|
|
sudo journalctl -u kopia-server -n 100 --no-pager
|
|
|
|
# Check listening
|
|
ss -ltnp | grep 51515
|
|
|
|
# Refresh credentials (after adding users, etc.)
|
|
kopia server refresh \
|
|
--address=https://127.0.0.1:51515 \
|
|
--server-control-username=control \
|
|
--server-control-password="$KOPIA_SRV_CTRL_PW" \
|
|
--server-cert-fingerprint=YOUR_FINGERPRINT
|
|
```
|
|
|
|
## MacBook client commands
|
|
|
|
```bash
|
|
# Repository status
|
|
kopia repository status
|
|
|
|
# List snapshots
|
|
kopia snapshot list
|
|
|
|
# Manual snapshot
|
|
kopia snapshot create --all
|
|
|
|
# Test restore
|
|
mkdir -p ~/kopia-restore-test
|
|
kopia restore latest ~/kopia-restore-test
|
|
```
|
|
|
|
## Automatic backups (launchd)
|
|
|
|
A launchd job at `~/Library/LaunchAgents/com.claudio.kopia-backup.plist` runs `kopia snapshot create --all` every 6 hours.
|
|
|
|
To reload after editing:
|
|
```bash
|
|
launchctl unload ~/Library/LaunchAgents/com.claudio.kopia-backup.plist 2>/dev/null || true
|
|
launchctl load ~/Library/LaunchAgents/com.claudio.kopia-backup.plist
|
|
launchctl list | grep kopia
|
|
```
|
|
|
|
## Known failure modes
|
|
|
|
1. **"not connected to a direct repository"** on Mac — server is running but not connected to repo. Fix: make sure systemd service runs as the same user (`cef`) that created the repository.
|
|
|
|
2. **`400 Bad Request: not connected`** on refresh — same root cause as above. Check `kopia repository status` as the service user.
|
|
|
|
3. **Browser works but Mac client fails** — usually cert fingerprint mismatch or HTTPS listener issue. Check fingerprint on client matches server.
|
|
|
|
4. **Shell quoting bug** — always use `"$VAR"` not `'$VAR'` in kopia commands.
|
|
|
|
## Maintenance
|
|
|
|
- `kopia repository status` — verify repo integrity
|
|
- `kopia snapshot verify --verify-files-percent=100 --file-parallelism=10 --parallel=10` — full consistency check (runs weekly via cron)
|
|
- Weekly restore test via cron job (see HEARTBEAT/backup task)
|
|
- Certificate fingerprint must be re-entered after cert rotation
|
|
|
|
## Adding a new user
|
|
|
|
On the VM:
|
|
```bash
|
|
kopia server user add partner@hostname
|
|
# set password when prompted
|
|
kopia server refresh \
|
|
--address=https://127.0.0.1:51515 \
|
|
--server-control-username=control \
|
|
--server-control-password="$KOPIA_SRV_CTRL_PW" \
|
|
--server-cert-fingerprint=YOUR_FINGERPRINT
|
|
```
|
|
|
|
From the new client machine:
|
|
```bash
|
|
kopia repository connect server \
|
|
--url=https://YOUR_VM_IP:51515 \
|
|
--server-cert-fingerprint=YOUR_FINGERPRINT \
|
|
--override-username=partner \
|
|
--override-hostname=hostname
|
|
```
|
|
|
|
## Next steps
|
|
|
|
- [ ] Finalize Mac backup roots (Documents, Desktop, project folders — avoid full ~/Library initially)
|
|
- [ ] Set retention policies on real backup roots
|
|
- [ ] Test automatic backups from the Mac
|
|
- [ ] Add spouse's machine as second user
|
|
- [ ] Test restore from spouse's machine
|
|
- [ ] Weekly `kopia snapshot verify --verify-files-percent=100` cron job with failure alert
|
|
- [ ] Weekly full restore test cron job
|
|
- [ ] Off-site replication of the Kopia repository (parents' NAS?)
|
|
- [ ] Keep Time Machine in parallel for full-machine restore
|