Restic Home Backup
Deliver a production-ready, unattended restic backup workflow for a Linux home
directory, covering encryption, deduplication, versioned retention, systemd
scheduling, retry logic, durable logging, email alerting, and restore validation.
Skill contract
- - Name: INLINECODE0
- Version: INLINECODE1
- Problem solved: Reliable, encrypted, versioned backups of a Linux home
directory. Supports SSH/SFTP remote repositories, DST-safe scheduling,
transient-error retries, user-level installs (no root), one-time restore
audit timers, and reusable multi-host rollout.
- Backup source user and path
- Repository endpoint/transport (
local,
sftp,
s3,
b2, etc.)
- Timezone (default
America/Los_Angeles)
- Retention policy (default: 14 daily / 8 weekly / 12 monthly)
- Exclude patterns
- Alert email
- Installed and initialized restic repository
- Backup / prune / check / audit scripts under
/usr/local/bin/
- Structured log wrapper with start/end/elapsed/exit-code per job
- systemd service+timer units (system-level or user-level)
- One-time restore audit timer
- Retry logic for transient failures (never retries auth/perm errors)
- Validation evidence: snapshot listing, restore drill, integrity check
- Controlled failure drills: wrong secret / unreachable repo / bad env file
- Operator runbook (
references/runbook.md)
- Ops checklist (
references/ops-checklist.md)
- - Safety boundaries (must never violate):
- Never print secrets or tokens in chat, log output, or scripts.
- Never delete snapshots or repositories without explicit user confirmation.
- Never weaken permissions on credential files (0600 minimum).
- Never claim backup success without checking exit status and snapshot listing.
- Default to PLAN-ONLY mode; require explicit
--apply for system changes.
- No snapshot deletion during initial engagement; use
--dry-run-prune to preview.
Workflow
1) Collect backup contract
Minimum required:
- - Source path (e.g.,
/home/alice) - Repository (e.g.,
sftp:backupsvc@10.50.8.24:/srv/backups/home/devbox17) - Retention policy
- Preferred schedule in local timezone
If any critical value is missing, ask targeted questions.
2) Show plan (no-change pass)
CODEBLOCK0
This prints the complete plan: files, schedule, retention, secrets approach,
retry logic, legacy cron archival, and dry-run prune preview. Zero changes made.
3) Apply system changes
CODEBLOCK1
What this does (in order):
- 1. Creates
/etc/home-backup/ (0700), generates password (0600, never printed) - Writes env file (0600) and excludes list
- Creates log directory INLINECODE15
- Installs logging+retry wrapper (
restic-home-log-run.sh) - Installs 4 operational scripts (backup, prune, check, audit-drill)
- Writes 8 systemd units (4 service + 4 timer)
- Archives and removes legacy root crontab entry
- Enables timers and runs INLINECODE17
- Initializes repo (skips if already exists)
- Starts first backup via systemd
- Shows
restic forget --dry-run output (no deletion)
4) User-level install (no root required — e.g., labvm3/bob)
CODEBLOCK2
5) End-to-end validation
CODEBLOCK3
Runs:
- - Snapshot listing
- Restore drill to
/tmp/restore-drill (verifies .ssh/config,
Documents/roadmap.md,
.config/git/config)
- - Cleanup of temp restore directory
- Repository integrity check
- Three failure drills: wrong secret / unreachable repo / unreadable env file
(each prints the failing command and a one-line corrective action)
6) One-time restore audit timer
The bootstrap creates restic-home-audit.timer for a single scheduled restore
drill. By default: 2026-04-17 17:00:00 America/Los_Angeles.
CODEBLOCK4
7) Package and publish via ClawHub
CODEBLOCK5
Files in this skill
CODEBLOCK6
Response style requirements
- - Name exact file paths, service names, and commands.
- State what changed and how to verify it.
- Never print passwords or tokens.
- End multi-step tasks with an explicit completion status.
- Reference
references/runbook.md for day-2 operational guidance.
Restic 家庭目录备份
为 Linux 家庭目录提供生产就绪、无人值守的 restic 备份工作流程，涵盖加密、去重、版本化保留策略、systemd 调度、重试逻辑、持久化日志、邮件告警和恢复验证。
技能合约
- - 名称： restic-home-backup
- 版本： 2.0.0
- 解决的问题： 对 Linux 家庭目录进行可靠、加密、版本化的备份。支持 SSH/SFTP 远程仓库、夏令时安全调度、瞬时错误重试、用户级安装（无需 root）、一次性恢复审计定时器以及可复用的多主机部署。
- 输入：
- 备份源用户和路径
- 仓库端点/传输方式（local、sftp、s3、b2 等）
- 时区（默认 America/Los_Angeles）
- 保留策略（默认：14 天 / 8 周 / 12 月）
- 排除模式
- 告警邮箱
- 已安装并初始化的 restic 仓库
- 位于 /usr/local/bin/ 的备份/清理/检查/审计脚本
- 包含每次作业的开始/结束/耗时/退出码的结构化日志封装器
- systemd 服务+定时器单元（系统级或用户级）
- 一次性恢复审计定时器
- 瞬时故障重试逻辑（从不重试认证/权限错误）
- 验证证据：快照列表、恢复演练、完整性检查
- 受控故障演练：错误密钥/仓库不可达/环境文件损坏
- 操作人员手册（references/runbook.md）
- 运维检查清单（references/ops-checklist.md）
- 绝不在聊天、日志输出或脚本中打印密钥或令牌。
- 未经用户明确确认，绝不删除快照或仓库。
- 绝不降低凭证文件的权限（最低 0600）。
- 未检查退出状态和快照列表，绝不声称备份成功。
- 默认仅计划模式；系统变更需显式使用 --apply。
- 初始接触期间不删除快照；使用 --dry-run-prune 预览。
工作流程
1) 收集备份合约
最低要求：
- - 源路径（例如 /home/alice）
- 仓库（例如 sftp:backupsvc@10.50.8.24:/srv/backups/home/devbox17）
- 保留策略
- 本地时区下的首选调度计划
如果缺少任何关键值，请提出针对性问题。
2) 显示计划（无变更阶段）
bash
bash scripts/bootstraprestichome.sh \
--user alice \
--repo sftp:backupsvc@10.50.8.24:/srv/backups/home/devbox17
这将打印完整计划：文件、调度计划、保留策略、密钥处理方式、重试逻辑、旧版 cron 归档以及 dry-run 清理预览。零变更。
3) 应用系统变更
bash
sudo bash scripts/bootstraprestichome.sh \
--user alice \
--repo sftp:backupsvc@10.50.8.24:/srv/backups/home/devbox17 \
--hostname devbox17 \
--timezone America/Los_Angeles \
--mail-to sre-oncall@example.com \
--keep-daily 14 --keep-weekly 8 --keep-monthly 12 \
--config-dir /etc/home-backup \
--log-dir /var/log/home-backup \
--apply \
--init-repo \
--enable-timers \
--run-initial-backup \
--archive-legacy-cron \
--dry-run-prune
操作顺序如下：
- 1. 创建 /etc/home-backup/（0700），生成密码（0600，绝不打印）
- 写入环境文件（0600）和排除列表
- 创建日志目录 /var/log/home-backup/
- 安装日志+重试封装器（restic-home-log-run.sh）
- 安装 4 个操作脚本（备份、清理、检查、审计演练）
- 写入 8 个 systemd 单元（4 个服务 + 4 个定时器）
- 归档并移除旧版 root crontab 条目
- 启用定时器并运行 daemon-reload
- 初始化仓库（如果已存在则跳过）
- 通过 systemd 启动首次备份
- 显示 restic forget --dry-run 输出（无删除操作）
4) 用户级安装（无需 root — 例如 labvm3/bob）
bash
bash scripts/installuserlevelrestic.sh \
--repo /mnt/offsite/backups/labvm3-home \
--hostname labvm3 \
--timezone America/Los_Angeles \
--mail-to sre-oncall@example.com \
--apply --init-repo --enable-timers --run-initial-backup
启用 linger（一次性操作，需要 sudo）：
sudo loginctl enable-linger bob
管理：
systemctl --user list-timers restic-home-* # 列出
systemctl --user start restic-home-backup.service # 手动备份
bash scripts/install
userlevelrestic.sh --remove # 移除调度计划
5) 端到端验证
bash
sudo bash scripts/validateresticsetup.sh
运行：
- - 快照列表
- 恢复到 /tmp/restore-drill（验证 .ssh/config、Documents/roadmap.md、.config/git/config）
- 清理临时恢复目录
- 仓库完整性检查
- 三项故障演练：错误密钥/仓库不可达/环境文件不可读
（每项演练均打印失败命令及一行纠正措施）
6) 一次性恢复审计定时器
引导脚本会创建 restic-home-audit.timer，用于单次定时恢复演练。默认时间：2026-04-17 17:00:00 America/Los_Angeles。
bash
检查：
systemctl list-timers restic-home-audit.timer --no-pager
取消：
systemctl disable --now restic-home-audit.timer
立即运行：
systemctl start restic-home-audit.service
7) 通过 ClawHub 打包并发布
bash
验证技能结构：
clawhub validate .
发布：
clawhub publish .
验证全新安装（干净环境，无遗留密钥）：
mkdir /tmp/clawhub-verify && cd /tmp/clawhub-verify
clawhub install restic-home-backup
仅运行计划模式，确认脚本存在且可执行：
bash restic-home-backup/scripts/bootstrap
restichome.sh \
--user testuser --repo sftp:test@localhost:/test
本技能包含的文件
scripts/
bootstraprestichome.sh 系统级安装（计划 + 应用）
installuserlevelrestic.sh 非 root 主机的用户级安装
validateresticsetup.sh 端到端验证 + 故障演练
references/
runbook.md 完整操作人员手册（13 个章节）
ops-checklist.md 快速日常/每周/每月参考
响应格式要求
- - 明确写出文件路径、服务名称和命令。
- 说明变更内容及验证方法。
- 绝不打印密码或令牌。
- 多步骤任务结束时给出明确的完成状态。
- 参考 references/runbook.md 获取第二天操作指导。
