restic-manager/docs/book/src/operations/backups-and-restores.md

Backups and restores

Running a backup

Three ways to trigger one:

1. Scheduled — the agent's local cron fires at the time set on the schedule.
2. Run-now — operator clicks Run now for a specific source group. This uses POST /hosts/{id}/source-groups/{gid}/run.
3. API — use POST /api/hosts/{id}/source-groups/{gid}/run for a configured source group. The lower-level POST /api/hosts/{id}/jobs backup form requires explicit paths in args; an empty backup is rejected instead of dispatching a job that restic cannot run.

In every case the server creates a jobs row, broadcasts a command.run to the host, and lands the operator on the live job log page (HTMX HX-Redirect).

Cancelling a job

Any running job — backup, forget, prune, restore, anything — exposes a Cancel button on its detail page. The server broadcasts command.cancel, and the agent kills the running restic subprocess via context cancel: SIGTERM first, SIGKILL after a 5s grace (cmd.Cancel + cmd.WaitDelay). On Windows the SIGTERM step is replaced with os.Kill because Windows can't deliver SIGTERM. Result: a cancelled job lands as cancelled within a couple of hundred milliseconds.

Restore wizard

Restoring a file or path goes through a four-step wizard at /hosts/{id}/restore:

1. Pick a snapshot. Search by id or by date; the page is pre-populated when you launched the wizard from a snapshot row.
2. Browse the snapshot tree. Lazy-loaded children via the MsgTreeList synchronous WS RPC; results are cached per-wizard-session for 30 minutes. Pick the absolute paths you want.
3. Choose a target. Either In place (overwrites the live filesystem; requires you to type the hostname to confirm) or New directory (default $HOME/rm-restore/<job-id>/; agent expands $HOME / ${HOME} / ~/ and creates the directory chain).
4. Review and submit. Server mints a job, dispatches command.run with a RestorePayload, and HX-Redirects to the live job log.

--no-ownership is gated on restic ≥ 0.17 (the flag was added in that release). Hosts running 0.16 don't get the flag and restore as the running user instead.

Snapshot diff

Two snapshot ids in the Diff form on the host detail page → a JobDiff job that runs restic diff <a> <b>. Output streams to the standard live job log. Useful when investigating a suspiciously-sized backup.

Job log artefacts

Every job's log is persisted in job_logs (one row per line), not just streamed in-memory. That gives you:

• A live view at /jobs/{id} while the job runs.
• Two download formats from the same page header dropdown:
  • txt — one line per row, HH:MM:SS.mmm TAG payload.
  • ndjson — one self-contained JSON object per line ({seq, ts, stream, payload}), perfect for jq.

Downloads work whether the job is running or finished — the source is the DB, not the live socket.