backup-server/backup/README.md

# Restic backup → TrueNAS REST server

Generic backup setup for any Linux machine (server, laptop, VM).
Backs up over WireGuard to a restic REST server running on TrueNAS.

## File overview

| File | Purpose | Edit per machine? |
|---|---|---|
| `backup.sh` | Backup script | ❌ Never |
| `restic-backup.service` | Systemd service | ❌ Never |
| `restic-backup.timer` | Daily timer (02:00) | ❌ Never |
| `restic-backup-boot.timer` | Boot timer — personal machines only | ❌ Never |
| `env.example` | Machine config template | ✅ Yes — copy & fill in |
| `excludes.txt` | Exclude patterns template | ✅ Yes — copy & customize |
| `recovery.txt` | Emergency credentials | ✅ Yes — fill in, store on TrueNAS |

`backup.sh`, the service, and the timers are **identical on every machine**.
Only the env and excludes files are machine-specific.

### Which timers to install

| Machine type | `restic-backup.timer` | `restic-backup-boot.timer` |
|---|---|---|
| **Server** (always on) | ✅ | ❌ |
| **Personal** (laptop, desktop) | ✅ | ✅ |

For personal machines the daily timer covers the case where the machine
happens to be on at 02:00 (e.g. left overnight), while the boot timer
ensures a backup runs whenever you start the machine during the day.

> **Note for personal machines:** `Persistent=true` in the daily timer
> means systemd will catch up a missed 02:00 run at next boot — which
> would fire at the same time as the boot timer. Disable it on personal
> machines:
> ```bash
> sudo systemctl edit restic-backup.timer
> # Add:
> # [Timer]
> # Persistent=false
> ```

---

## Prerequisites

- TrueNAS REST server reachable (confirmed ✅ at `nas.box:30248`)
- WireGuard tunnel active
- `restic` installed

```bash
# Debian / Ubuntu
apt install restic

# Arch
pacman -S restic

# Any distro — latest binary from GitHub
# https://github.com/restic/restic/releases
```

---

## Setup (repeat for each machine)

### 1. Create the config directory

```bash
sudo mkdir -p /etc/restic
```

### 2. Install and fill in the env file

```bash
sudo cp env.example /etc/restic/env
sudo nano /etc/restic/env
sudo chmod 600 /etc/restic/env
```

Set these values:
- `MACHINE_NAME` — unique name for this machine (e.g. `netcup`, `laptop`, `homeserver`)
- `RESTIC_PASSWORD` — generate with `openssl rand -base64 32`
- `BACKUP_PATHS` — space-separated list of paths to back up

### 3. Install the excludes file

```bash
sudo cp excludes.txt /etc/restic/excludes.txt
# Edit to add any machine-specific paths to skip
sudo nano /etc/restic/excludes.txt
```

### 4. Initialize the repository on the REST server

```bash
sudo bash -c 'set -a && source /etc/restic/env && restic init'
```

### 5. Install the backup script

```bash
sudo cp backup.sh /usr/local/bin/restic-backup.sh
sudo chmod +x /usr/local/bin/restic-backup.sh
```

### 6. Install the systemd units

**Server:**
```bash
sudo cp restic-backup.service  /etc/systemd/system/
sudo cp restic-backup.timer    /etc/systemd/system/

sudo systemctl daemon-reload
sudo systemctl enable --now restic-backup.timer
```

**Personal machine (laptop / desktop):**
```bash
sudo cp restic-backup.service      /etc/systemd/system/
sudo cp restic-backup.timer        /etc/systemd/system/
sudo cp restic-backup-boot.timer   /etc/systemd/system/

sudo systemctl daemon-reload
sudo systemctl enable --now restic-backup.timer
sudo systemctl enable --now restic-backup-boot.timer

# Disable catch-up on the daily timer to avoid double backup at boot
sudo systemctl edit restic-backup.timer
# Add these lines, save and close:
# [Timer]
# Persistent=false
```

### 7. Run a first backup to verify

```bash
sudo systemctl start restic-backup.service
sudo journalctl -u restic-backup.service -f
```

---

## Useful commands

```bash
# Check timer status and next run time
systemctl status restic-backup.timer restic-backup-boot.timer

# List all snapshots
sudo bash -c 'set -a && source /etc/restic/env && restic snapshots'

# Browse a snapshot interactively
sudo bash -c 'set -a && source /etc/restic/env && restic mount /mnt/restic'

# Restore a single file or directory
sudo bash -c 'set -a && source /etc/restic/env && restic restore latest --target /tmp/restore --include /etc/wireguard'

# Check repo integrity
sudo bash -c 'set -a && source /etc/restic/env && restic check'
```

---

## Password recovery — avoid the bootstrap trap

If your password manager runs on the machine being backed up, losing that
machine means losing access to the password — and the repo is unrecoverable.

**Solution:** store `recovery.txt` on TrueNAS, outside the restic repo.

```bash
# On TrueNAS — one file per machine
cp recovery.txt /mnt/pool/backups/recovery-netcup.txt
chmod 600 /mnt/pool/backups/recovery-netcup.txt
```

```
/mnt/pool/backups/
├── netcup/                  ← restic repo (encrypted)
├── laptop/                  ← restic repo (encrypted)
├── recovery-netcup.txt      ← credentials + restore steps
└── recovery-laptop.txt      ← credentials + restore steps
```

**Recommended redundancy:**

| Copy | Survives |
|---|---|
| TrueNAS `recovery-<machine>.txt` | Machine loss |
| Personal device password manager | TrueNAS loss |
| Printed in a safe | Everything digital |

---

## Server reconstruction

On a fresh machine:

```bash
# 1. Install restic
apt install restic

# 2. Restore all files
RESTIC_PASSWORD=<from recovery.txt> \
restic -r rest:http://oliver:oli1oli1@nas.box:30248/<MACHINE_NAME> \
restore latest --target /

# 3. Reinstall packages (Debian/Ubuntu)
dpkg --set-selections < /etc/backup-package-list.txt
apt-get dselect-upgrade

# 4. Reload systemd
systemctl daemon-reload
```