# Backups on a QNAP NAS

What to copy, where a copy may go, and how Bucket & Code Server IDE backs up its own data. The NAS facts come from
QNAP Club Poland's knowledge base; the package's from its user guide (`bvs guide`, section "Backups"). The first two
sections hold with or without Bucket & Code Server IDE. The last one covers only the data that package keeps.

## What a backup of a NAS covers

- **Data** lives on the data volumes (`/share/CACHEDEV<N>_DATA` on QTS, `/share/ZFS<N>_DATA` on QuTS hero) and in
  the shared folders on them. That is what a backup copies.
- **Settings** live in `/etc/config`, which persists on md9 (QTS) or `/mnt/sync` (QuTS hero). The NAS keeps
  earlier copies of its settings on the data volume in `<volume>/.@backup_config`; the forum's FAQ shows how to
  copy them out.
- **An installed package** keeps its files in `<volume>/.qpkg/<name>` and its settings in `/etc/config/qpkg.conf`.
  A package with a database or a repository in it is copied by its own export or dump, or with its service
  stopped (`qpkg_cli --stop <name>`); files copied while the program writes them may not open again.
- **Snapshots** are made by the storage layer (LVM thin snapshots on QTS, ZFS snapshots on QuTS hero) and live in
  the same pool as the data. They undo a deletion or a change; they do not survive the loss of that pool. A copy
  on another device does.
- QNAP's own backup app is Hybrid Backup Sync (HBS 3), installed from App Center; the forum has its manual in
  Polish.

## Writing a backup script

- Write the copy to a data volume, a mounted USB disk or another machine, never to `/tmp`, `/root` or anything on
  the RAM disk: a full `/tmp` takes the NAS down, and the RAM disk forgets everything at the next boot.
- Before a script writes to a USB disk, check that the disk is mounted (the snippet in
  [storage-and-paths.md](storage-and-paths.md)). With the disk unplugged, the copy lands in RAM.
- `rsync` is `/usr/bin/rsync` on QTS 6.1; the forum's QuTS hero 6.0 capture records no path for it, so check for
  it there first. On a FAT, exFAT or NTFS disk use `rsync -rt`: those file systems keep no Unix owners.
- Schedule it in `/etc/config/crontab`, then `crontab /etc/config/crontab`; call every program by its full path.
  Report the result with `/sbin/log_tool -t 0|1|2 -a "…"`, so it shows in the NAS's System Logs.
- Keep a time limit on network copies with the program's own option (`rsync --timeout=<seconds>`,
  `curl -m <seconds>`); `timeout` does not exist on the NAS ([never-recommend.md](never-recommend.md)).
- Test a restore: a backup that was never read back is a guess.

## Bucket & Code Server IDE's own backups

The Backups page (admin) of the package backs up its own data root. It runs daily as the built-in job `backup` and
on **Back up now**, and keeps the newest run of each of the last 7 days, 4 weeks and 6 months.

- A run is a folder `<data>/backups/<id>/` with a `manifest.json` that lists every file with its sha256: the
  settings (accounts, TOTP secrets, the TLS key), Forgejo's dump, every SVN repository and bucket, each account's
  VS Code settings, and optionally the environments.
- Two runs on one day count as one: **Back up now** in the afternoon replaces that morning's scheduled run. Copy a
  run elsewhere first when that morning's state matters.
- Targets: a local folder on the NAS (on the same disks as the data, so it guards against mistakes, not against a
  failed volume), rsync over SSH with the package's backup key, and rclone. A copy that leaves the NAS must be
  encrypted with the package's age key, whose secret half is shown once and not kept: without it no NAS can
  restore that copy.
- **Verify** reads a run back completely; **Restore** checks every archive before it replaces anything and keeps
  what it replaced in `<data>/trash` for 7 days.
- The package repository (the published QPKGs) is not part of a backup: after a restore, publish the packages
  again.

## Sources

QNAP Club Poland (forum.qnap.net.pl): [guidelines.md](https://forum.qnap.net.pl/llms/guidelines.md),
[storage-layout.md](https://forum.qnap.net.pl/llms/storage-layout.md), and the FAQ and manual index in
[forum-wiki.md](https://forum.qnap.net.pl/llms/forum-wiki.md) (the settings copies in `.@backup_config`, the HBS 3
manual). The package's backups: its user guide, `bvs guide`.
