Backupninja 1.2.2 配置文件体系详解

目标：把 Backupninja 的三层配置体系（全局主配置 /etc/backupninja.conf、动作配置目录 /etc/backup.d/、各 handler 的段落字段）一次讲透。文中所有文件原文、字段默认值、报错与产物均为 Debian 13 上 Backupninja 1.2.2-1 的实机验证记录（环境见第一节），涉及调度语义的部分以随包手册 backup.d(5)、backupninja.conf(5) 为准。

一、环境信息

安装过程与运行验证见 《Debian 13 安装 Backupninja 1.2.2 指南》，架构与选型背景见 《Backupninja 1.2.2 介绍与选型指南》。

二、配置体系总览

Backupninja 的配置分三层，读取顺序自上而下：

一个动作配置的一生：cron 每小时拉起主脚本 → check_perms 权限校验 → 预解析 when 决定本次是否执行 → 以 /var/lock/backupninja/ 锁文件互斥 → 按 .sh（整文件当脚本执行）或「ini 段 + 后缀」把配置交给 handler → 结果计入汇总日志与邮件报告。

三、全局配置 /etc/backupninja.conf 详解

3.1 实测原文（1.2.2-1 包内默认值）

#
#                          |\_
# B A C K U P N I N J A   /()/
#                         `\|
# main configuration file
#

# how verbose to make the logs
# 5 -- Debugging messages     (and below)
# 4 -- Informational messages (and below)
# 3 -- Warnings               (and below)
# 2 -- Errors                 (and below)
# 1 -- Fatal errors           (only)
loglevel = 4

# Produce prometheus metrics of backup status (default = no).
# Requires `prometheus-node-exporter` to be installed
reportprom = false

# send a summary of the backup status to
# this email address:
reportemail = root

# if set to 'yes', a report email will be generated
# even if all modules reported success. (default = yes)
reportsuccess = yes

# if set to 'yes', info messages from handlers will be
# sent into the email (default = no)
reportinfo = no

# if set to 'yes', a report email will be generated
# even if there was no error. (default = yes)
reportwarning = yes

# if set to 'yes', disk space usage will be included in
# the backup email report
reportspace = no

# where to rsync the backupninja.log to be aggregated in
# a ninjareport
reporthost =

# what user to connect to reporthost to sync the
# backupninja.log
reportuser = ninja

# where on the reporthost should the report go
reportdirectory = /var/lib/backupninja/reports

# number of columns the report email body should wrap to
#reportwrap = 80

# set to the administration group that is allowed to
# read/write configuration files in /etc/backup.d
admingroup = root

# where to log:
logfile = /var/log/backupninja.log

# directory where all the backup configuration files live
configdirectory = /etc/backup.d

# where backupninja helper scripts are found
scriptdirectory = /usr/share/backupninja

# where backupninja libs are found
libdirectory = /usr/lib/backupninja

# whether to use colors in the log file
usecolors = yes

# default value for 'when'
when = everyday at 01:00

# programs paths（可覆盖各后端工具路径，默认全部注释）
# RDIFFBACKUP=/usr/bin/rdiff-backup
# MYSQL=/usr/bin/mysql
# MYSQLDUMP=/usr/bin/mysqldump
# PSQL=/usr/bin/psql
# RSYNC=/usr/bin/rsync
# ...（SLAPCAT、LDAPSEARCH、CSTREAM、MYSQLHOTCOPY、
#     PGSQLDUMP、PGSQLDUMPALL、GZIP、GZIP_OPTS 等同段）

（原文为完整注释文件，上方为保留全部生效键与关键注释的节选；lockdirectory 缺省即 /var/lock/backupninja，实测锁文件名形如 /var/lock/backupninja/_etc_backup.d_10.tar。）

3.2 字段逐项解读

四、动作配置文件（/etc/backup.d/）

4.1 命名规则与执行顺序

• 命名模板：[0-9][0-9]<名称>.<后缀>，如 10-etc.tar、20-var.rsync、40-dpkg.sh。后缀决定 handler，双数字序决定同类内顺序；
• 主脚本按文件名排序执行（实测顺序：10-etc.tar → 20-var.rsync → 30-sys.sys → 40-dpkg.sh → 50-etc.rdiff）；
• 官方手册建议：数据库 dump 类小编号在前，文件系统增量类大编号在后，使导出的 SQL 落入后续的文件备份中；
• 临时停用：把文件改名为 *.disabled（ninjahelper 的 disable/enable 菜单就是做这个改名）；
• ninjahelper 向导生成的文件采用 10.tar 这种「数字.后缀」形式（实测生成 /etc/backup.d/10.tar），与手工命名 10-etc.tar 同属合法形态。

4.2 权限纪律（硬性）

每个动作文件必须属主 root 且组/其他无读写权限（实测合法形态 -rw------- root root）；/etc/backup.d/ 目录本身为 drwxrws---（带 setgid）。权限不符时主脚本在 check_perms 阶段拒绝，日志会出现 Debug: check_perms ... 流。新建后统一 chmod 600 是必备动作。

4.3 when 调度语法

when 写在动作文件内（或全局 conf），支持多行并存：

语法红线（backup.d(5) 原文归纳）：at 之后必须是两位小时（可附 :分钟）；at 5:00、tuesday at 2am 属于非法写法；合法星期/日与时刻组合共 7 种官方示例（sundays、30th、30、everyday、Tuesday、hourly、manual）。

4.4 格式约定

• .sh 动作是纯 shell 脚本（第一行 when = ... 被主脚本预解析，其余行原样执行）；实测确认 test 模式下 .sh 不真正执行——handler 内部逻辑为 [ $test ] || ( . $1 )，即只有正式运行才加载脚本体；
• 其余后缀为 ini 风格 [section] + key = value，# 注释；同一键重复出现（如多个 include =）即多值累积，是 include/exclude 类字段的标准用法；
• 段名与键名因 handler 而异，见第五节分型详解。

五、handler 配置分型详解（五类实测）

5.1 .tar 全量归档

# /etc/backup.d/10-etc.tar（实测配置原文）
when = manual
backupname = backup-server
backupdir = /srv/backup/tar
compress = bzip
includes = /etc
excludes = /tmp /proc /sys /dev

实测产物三件套（ls 原文）：

-rw------- 1 root root    111 Oct 24 06:46 backup-server-2026.10.24-0646.err
-rw------- 1 root root  20931 Oct 24 06:46 backup-server-2026.10.24-0646.list
-rw------- 1 root root 309662 Oct 24 06:46 backup-server-2026.10.24-0646.tar.bz2

.err 内容为 tar 提示（如 Removing leading '/' from member names）。另一实测细节：日志中 handler returned exit code 1 与 SUCCESS 并存——tar handler 末行的 [ $? -ne 0 ] 判定式本身返回 1（tar 实际成功、无 fatal 触发），属于框架的「正常噪音」，不必按字面理解为失败。

5.2 .rsync 目录镜像（含轮转）

# /etc/backup.d/20-var.rsync（实测配置原文）
[general]
mountpoint = /srv/backup
backupdir = rsync/var
format = short
days = 7
[source]
from = local
include = /var/log
[dest]
dest = local

三段结构：[general] 管目标与轮转——mountpoint 是备份主目录（不必是真实挂载点）、backupdir 是相对 mountpoint 的子目录、format 有 short（backup.0、backup.1…按 days 个增量轮转，取自 rsync_snapshots 增量法）/long（daily.1、weekly.1、monthly.1，由 keepdaily/keepweekly/keepmonthly 控制）/mirror（不轮转）三种；[source] 的 from = local|remote 与 include/exclude 决定备份什么；[dest] 的 dest = local|remote（remote 时补 host/user/sshoptions）决定推到哪里。

实测第一跑直接 Fatal: Backupdir /srv/backup/rsync/var does not exist——rsync handler 不自动建目标目录，mkdir -p 该组合路径后重跑成功。成功后的落盘结构（find 原文节选）：

/srv/backup/rsync/var/var/log/log.0/          # 本次镜像（log.0）
/srv/backup/rsync/var/var/log/metadata/       # 轮转元数据（备份时间戳等）

注意路径出现 var/var：backupdir 段 + include 路径原样拼接所致，规划 backupdir 命名时要预估最终目录形态。

5.3 .rdiff 增量备份

# /etc/backup.d/50-etc.rdiff（实测配置原文，修正后可跑通版本）
[source]
label = backup-server
type = local
include = /etc
include = /root
exclude = /etc/systemd/system
[dest]
type = local
directory = /srv/backup/rdiff/backup-server
keep = 60

兼容性实测：Debian trixie 的 rdiff-backup 2.2.6 走 legacy CLI 兼容模式可正常备份（会话统计正常输出），但每次打印 deprecated 告警，导致动作以 WARNING 收尾——用 2.x 引擎时需知晓；引擎侧原理与用法见 《rdiff-backup 介绍与选型指南》。

5.4 .sys 系统信息收集

# /etc/backup.d/30-sys.sys（实测配置原文）
packages = yes
partitions = yes
hardware = yes
dohwinfo = yes

实测产物（/var/backups/，即全局 backupdir）：

-rw-r--r-- 1 root root  6114 Oct 24 06:47 debconfsel.txt      # debconf 应答
-rw-r--r-- 1 root root  1874 Oct 24 06:47 dpkg-selections.txt # 包清单
-rw-r--r-- 1 root root 152K  Oct 24 06:47 hardware.txt        # hwinfo 输出
-rw-r--r-- 1 root root 10.1M Oct 24 06:47 sysreport.txt       # 系统报告汇总

依赖实测：未装 fdisk 时报 Warning: can't find sfdisk, skipping sfdisk report，apt-get install fdisk kmod 后该告警消失；残留 Info: executing of /sbin/modinfo failed 为 Info 级、不影响 SUCCESS。选型上这类「系统画像」文件适合纳入每天的文件备份——sys 用小编号、文件备份用大编号。

5.5 .sh 自定义脚本

# /etc/backup.d/40-dpkg.sh（实测配置原文）
when = hourly
dpkg --get-selections > /srv/backup/dpkg-selections.txt

首行 when 被主脚本预解析，其余内容在正式运行时由 sh 加载执行（脚本体内可直接调用框架 fatal/error 函数做结果上报）。实测：--test 模式不执行脚本体（无产物生成）；正式 --run 与 cron 触发均真实落盘。它是打通「安装→验证→定时」全链路的最短路径，也是自定义前后钩子（如备份前冻结数据库、备份后清理临时区）的扩展点。

5.6 其余 handler 速览（以包内 example.* 为准）

六、校验与试运行方法

排查配置的标准动作（全部实测有效）：

1. backupninja --test：全量 dry-run，逐文件输出 check_perms 与 when 匹配结果，不真正执行 handler（.sh 也不执行）；
2. backupninja --test --run /etc/backup.d/10.tar：单文件试运行，输出 handler 将要执行的完整命令行（实测可见 tar 的 --exclude/-f 全序列）；
3. backupninja --run 文件：单文件正式执行，日志标 because of --now；
4. backupninja -n：本次全量执行但不发邮件报告；
5. 临时把全局 loglevel 调到 5，看 handler 的每步 Debug；
6. TUI 侧的 ninjahelper 每条动作菜单里也有 test 项，等价于第 2 条（详见本专栏命令详解篇）。

七、参考链接

1. 本站专栏：《Debian 13 安装 Backupninja 1.2.2 指南》（安装与运行验证）
2. 本站专栏：《Backupninja 1.2.2 介绍与选型指南》（架构与选型）
3. 本站专栏：《rdiff-backup 介绍与选型指南》（.rdiff 引擎）
4. 本站专栏：《rsnapshot 配置文件详解》（同为配置文件驱动，含 rsync 轮转语义对照）
5. 本站专栏：《Duplicity 介绍与选型指南》（.dup 引擎）
6. 随包手册：backup.d(5)、backupninja.conf(5)；示例：/usr/share/doc/backupninja/examples/（backupninja 1.2.2-1，实测环境 Debian 13）