Burp 3.2.0 配置参数详解

目标：逐项解析 burp 3.2.0（grke/burp，开源 C/S 架构网络备份恢复工具，注意与 PortSwigger 的 Burp Suite 同名异物）服务端 burp-server.conf 与客户端 burp.conf/clientconfdir 的核心配置参数，覆盖监听端口、存储目录、keep 保留策略、timer 定时调度、CA 证书双向认证链与备份范围控制，每个改动项均以实测回显证明生效。全部命令与输出均为 2026-10-24 在两台 Ubuntu 22.04 服务器（备份服务器 10.89.68.2、客户端服务器 10.89.68.3，burp 3.2.0 源码编译安装）上实测所得，逐行照抄。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS，两台：备份服务器 10.89.68.2（burp 服务端 + 内置 CA）、客户端服务器 10.89.68.3（burp 客户端 client1）
软件版本：burp 3.2.0（官方 Stable 推荐版，burp -V 输出 burp-3.2.0；版本选型依据见《Burp 3.2.0 介绍与选型指南》）
配置文件布局（服务端）：
- /etc/burp/burp-server.conf：服务端主配置
- /etc/burp/clientconfdir/：每个客户端一个同名接入文件（client1、client2、testclient）
- /etc/burp/CA.cnf：内置 CA 的 openssl 配置；/etc/burp/CA/：CA 数据库与证书
配置文件布局（客户端）：
- /etc/burp/burp.conf：客户端主配置
- /etc/burp/CA-client/：客户端证书签名请求（CSR）存放目录
数据目录：/var/spool/burp/（按客户端名分目录存放备份数据）
端口：4971（数据）、4972（状态监控）
实测日期：2026-10-24；安装过程见《Burp 3.2.0 安装与运行实测指南》，本篇在其安装完成、服务端守护进程运行、client1 已有备份的基础上展开

二、前置条件

2.1 两侧服务就绪

本篇所有参数改动都在"已安装、已互信"的环境上验证：服务端 burp 守护进程运行中，客户端 client1 已完成证书签发并成功备份过。先确认基线状态：

burp -V
ss -lntp | grep -E '4971|4972'

服务端实测回显：

burp-3.2.0
LISTEN 0      5            0.0.0.0:4972       0.0.0.0:*    users:(("burp",pid=9308,fd=4))
LISTEN 0      5            0.0.0.0:4971       0.0.0.0:*    users:(("burp",pid=9308,fd=2))

客户端确认与服务端连通且已认证：

burp -a l

实测回显（节选握手行）：

2026-10-24 10:16:41 +0000: burp[3402] Connecting to 10.89.68.2:4971
2026-10-24 10:16:41 +0000: burp[3402] auth ok
2026-10-24 10:16:41 +0000: burp[3402] Server version: 3.2.0
2026-10-24 10:16:41 +0000: burp[3402] nocsr ok
Backup: 0000005 2026-10-24 08:16:54 +0000 (deletable)
Backup: 0000006 2026-10-24 08:19:17 +0000
2026-10-24 10:16:42 +0000: burp[3402] main socket 3: Peer closed SSL session
2026-10-24 10:16:42 +0000: burp[3402] List finished ok

nocsr ok 表示客户端证书已就位、无需再走 CSR 签发；此时 client1 在服务端已有编号 0000005、0000006 两个备份，作为后续保留策略实测的初始状态。

2.2 burp 的配置文件模型

burp 没有独立的命令行参数体系，所有行为都由配置文件驱动，一个二进制靠 mode 决定角色：

文件	位置	角色	关键内容
`burp-server.conf`	服务端 `/etc/burp/`	服务端全局	监听、存储、保留策略、CA、timer
`clientconfdir/<客户端名>`	服务端 `/etc/burp/clientconfdir/`	单客户端接入	口令、可覆盖的备份范围、单客户端限额
`burp.conf`	客户端 `/etc/burp/`	客户端全局	服务器地址、口令、证书路径、备份范围

💡 技术拓展：服务端配置存在"全局 → 单客户端"两级覆盖模型，同类备份软件对比：

软件配置分层备份范围定义方
burp 全局 conf + clientconfdir 单客户端文件，客户端文件可覆盖全局默认客户端定，服务端可强制接管
UrBackup Web 界面全局设置 + 每客户端设置管理员在服务端定
BorgBackup/Restic 无服务端，纯客户端命令行参数客户端定

burp 实际采用"服务端两级配置 + 客户端配置"三层模型，且默认 server_can_override_includes = 1 允许服务端强制接管客户端的备份范围（见 6.3 节实测说明）。

软件	配置分层	备份范围定义方
burp	全局 conf + clientconfdir 单客户端文件，客户端文件可覆盖全局	默认客户端定，服务端可强制接管
UrBackup	Web 界面全局设置 + 每客户端设置	管理员在服务端定
BorgBackup/Restic	无服务端，纯客户端命令行参数	客户端定

配置文件语法规则（全部实测确认）：

键 = 值，等号两侧空格可有可无（实测文件中 cross_filesystem=/home 与 include = /home 两种写法均生效）；
# 开头为注释；可重复的键（timer_arg、keep、include、exclude_fs 等）每行一条、多次出现累积生效；
. 开头一行引入其他配置文件，如 clientconfdir/client1 中的 . incexc/* 会读取 clientconfdir/incexc/ 下所有文件。

三、参数查看与修改方式

3.1 `-t` 试跑：一次看全所有生效参数值

burp 自带"配置试跑"模式：burp -c <配置> -t 只解析配置、打印全部参数的最终生效值，不启动服务。这是排查"我改的参数到底生效没有"的第一工具。

burp -c /etc/burp/burp-server.conf -t

实测回显（节选前 26 行，完整输出约 190 行）：

                        conffile: /etc/burp/burp-server.conf
                            mode: server
                        lockfile: 
                         pidfile: /var/run/burp.server.pid
                          syslog: 1
                          stdout: 1
                progress_counter: 0
                     ssl_cert_ca: /etc/burp/ssl_cert_ca.pem
                        ssl_cert: /etc/burp/ssl_cert-server.pem
                         ssl_key: /etc/burp/ssl_cert-server.key
                ssl_key_password: 
                     ssl_peer_cn:

客户端侧同理（在客户端服务器执行）：

burp -c /etc/burp/burp.conf -t | head -6

实测回显：

                        conffile: /etc/burp/burp.conf
                            mode: client
                        lockfile: 
                         pidfile: /var/run/burp.client.pid
                          syslog: 0

-t 同时承担语法校验职责：配置写错时直接报错退出。实测给服务端喂一个非法 mode：

burp -c /etc/burp/burp-server.conf -o mode=bogus -t

实测回显：

2026-10-24 08:17:49 +0000: burp[9266] Unknown mode setting: bogus
2026-10-24 08:17:49 +0000: burp[9266] /etc/burp/burp-server.conf: mode unset - need 'server' or 'client'

验证要点：看到完整参数清单且无报错行，配置即为可启动状态；改完配置先 -t 再重启，能拦下绝大多数手误。

3.2 `-o` 命令行覆写：不改文件的临时参数

-o 键=值 可在命令行临时覆写配置项，可叠多个。实测覆写 keep 与压缩级别（只试跑不启动）：

burp -c /etc/burp/burp-server.conf -o keep=3 -o compression=zlib5 -t | grep -E 'keep:|compression:|listen:'

实测回显：

                          listen: 0.0.0.0:4971
                       directory: /var/spool/burp
                            keep: 7
                            keep: 3
                     compression: 5

解读：keep 是可重复键，-o keep=3 是追加而非替换，所以出现 keep: 7 与 keep: 3 两行（保留策略语义见 5.3 节）；compression 是单值键，配置文件中被注释（默认 zlib9），-o compression=zlib5 覆写后生效为 5。单值键 -o 才是"替换"，多值键是"追加"——这个差异在临时调参时容易踩坑。

3.3 配置生效时机：哪些改动要重启

burp 服务端为每个客户端连接 fork 子进程并重新读取配置，所以绝大多数改动（口令、clientconfdir、timer 规则、keep、备份范围）无需重启即时生效；只有 listen/listen_status 这类监听参数必须重启进程。本篇 5.1 节对端口改动做了重启实测，5.3/5.4 节的 keep 与 timer 改动均为不重启即时生效实测。

四、参数总览

以下两张表汇总 -t 试跑输出的关键生效值（burp 3.2.0，未改动项为编译/模板默认值，改动项以实测为准）。

服务端（burp-server.conf）关键参数：

参数	实测生效值	说明
`mode`	server	服务端角色
`listen`	0.0.0.0:4971	数据监听地址与端口
`listen_status`	0.0.0.0:4972	状态监控监听（可浏览备份数据，慎对外）
`max_children` / `max_status_children`	5 / 5	数据/状态连接的最大子进程数
`directory`	/var/spool/burp	备份数据根目录
`clientconfdir`	/etc/burp/clientconfdir	客户端接入文件目录
`dedup_group`	global	去重组（跨客户端去重的分组名）
`keep`	7	保留策略（可多行）
`timer_script` / `timer_arg`	（默认脚本）/ 0h + always	定时备份裁决脚本与规则
`ca_conf` / `ca_name` / `ca_server_name`	/etc/burp/CA.cnf / burpCA / burpserver	内置 CA 配置
`ca_burp_ca`	/usr/sbin/burp_ca	证书操作脚本
`ca_crl_check`	1	校验证书吊销列表
`ssl_cert_ca` / `ssl_cert` / `ssl_key`	/etc/burp/ssl_cert_ca.pem / ssl_cert-server.pem / ssl_cert-server.key	CA 根证书、服务端证书、私钥
`ssl_dhfile`	/etc/burp/dhfile.pem	Diffie-Hellman 参数文件
`ssl_compression`	5	SSL 压缩级别
`compression`	9	备份数据压缩级别（zlib9）
`librsync` / `librsync_max_size`	1 / 0	差量传输开关/大小上限（0 不限）
`client_can_delete` 等能力项	1	客户端可删/可比对/可列/可恢复/可校验
`password_check`	1	口令校验开关
`working_dir_recovery_method`	delete	中断备份工作目录的处理
`max_hardlinks` / `max_storage_subdirs`	10000 / 30000	硬链接与存储子目录上限
`network_timeout`	7200	网络超时（秒）
`ratelimit`	0（不限）	发送限速（Mb/s）
`version_warn`	1	客户端版本不一致时告警
`hard_quota` / `soft_quota`	0（不限）	客户端存储配额（字节）
`timestamp_format`	%Y-%m-%d %H:%M:%S %z	备份时间戳格式

客户端（burp.conf）关键参数：

参数	实测生效值	说明
`mode`	client	客户端角色
`server`	10.89.68.2:4971	服务端地址与数据端口
`status_port`	4972	服务端状态端口（监控连接用）
`cname`	client1	客户端名（服务端据此找 clientconfdir 同名文件）
`password`	q1w2e3r4	接入口令（与服务端同名文件一致）
`ca_burp_ca` / `ca_csr_dir`	/usr/sbin/burp_ca / /etc/burp/CA-client	自动 CSR 的脚本与存放目录
`ssl_cert_ca`	/etc/burp/ssl_cert_ca.pem	CA 根证书（两侧同一文件）
`ssl_cert` / `ssl_key`	/etc/burp/ssl_cert-client.pem / .key	客户端证书与私钥
`ssl_peer_cn`	burpserver	校验服务端证书的 CN
`include`	/home	备份范围
`exclude_fs`	sysfs、tmpfs	按文件系统类型排除
`exclude_comp`	bz2、gz	不再压缩的扩展名
`nobackup`	.nobackup	目录内标记文件命中即跳过该目录内容
`cross_filesystem`	/home	允许跨文件系统边界（限 /home）
`cross_all_filesystems`	0	不跨全部文件系统
`server_can_restore`	1	允许服务端发起恢复
`restoreprefix`	/root/server_restore	服务端发起恢复的落点前缀
`progress_counter`	1	进度计数行输出
`encryption_password`	（未设）	客户端侧加密（设置后无法差量传输）
`randomise`	0（未设）	定时备份随机延迟秒数

关键差异解读：服务端参数围绕"存储、保留、调度、准入"，客户端参数围绕"连谁、用什么证书、备什么"；两侧唯一的强一致点是 ssl_cert_ca 必须是同一份 CA 根证书，password 必须与 clientconfdir 同名文件一致。

五、服务端 burp-server.conf 核心参数分类详解

5.1 监听与并发：listen / listen_status / max_children

3.2.0 的服务端配置模板用 listen = 地址:端口 与 listen_status = 地址:端口 定义双端口（旧版 port/status_port 写法在服务端已由 listen 系列取代；客户端配置中的 status_port 仍保留，含义是"服务端状态端口在哪"）。实测配置文件相关行为：

mode = server

listen = 0.0.0.0:4971
max_children = 5
# Optionally configure additional addresses and ports.
# listen = :::5971
# max_children = 6

# Think carefully before changing the status port address, as it can be used
# to view the contents of backups.
# If you do not wish to run a status server at all, leave it commented out.
listen_status = 0.0.0.0:4972
max_status_children = 5

逐项说明：

listen：备份数据通道监听地址与端口，客户端 server 参数指向它；可写多行同时监听多个地址（如 IPv6 :::5971），max_children 是数据通道的最大并发子进程数（即同时服务的客户端连接数）；
listen_status：状态监控端口，burp -a s/-a S/-a m 都连它；模板注释特意提醒"改状态端口地址前想清楚，因为它可以用来浏览备份内容"——生产上不要把 4972 暴露给不可信网络，或用 network_allow_status 限制来源（-t 输出中可见 network_allow_status: 默认为空即不限）；
若完全不想要状态服务，注释掉 listen_status 即可。

端口改动生效实测：把 listen 从 4971 改为 4981，重启服务端进程：

sed -i 's|^listen = 0.0.0.0:4971|listen = 0.0.0.0:4981|' /etc/burp/burp-server.conf
kill 9308
burp -c /etc/burp/burp-server.conf
sleep 2
ss -lntp | grep burp

实测回显：

5:listen = 0.0.0.0:4981
LISTEN 0      5            0.0.0.0:4981       0.0.0.0:*    users:(("burp",pid=9645,fd=2))
LISTEN 0      5            0.0.0.0:4972       0.0.0.0:*    users:(("burp",pid=9645,fd=4))

4971 监听消失、4981 生效。此时客户端仍按 server = 10.89.68.2:4971 连接，实测报错：

2026-10-24 10:18:47 +0000: burp[3478] Connecting to 10.89.68.2:4971
2026-10-24 10:18:47 +0000: burp[3478] Could not connect to 10.89.68.2:4971
EXITCODE=4

退出码 4 即"无法连接服务端"（与源码自带 systemd 单元注释的退出码表一致：0 成功、1 出错、2 恢复有告警、3 timer 不允许、4 连不上、5 并发备份满）。把配置改回 4971 并重启后，监听恢复、客户端 -a l 重新 auth ok（实测回显 1 行 auth ok）。这组对照证明：listen 类参数改动必须重启服务端，且改端口时两侧要同步。

5.2 存储目录与数据布局：directory / dedup_group / clientconfdir

directory = /var/spool/burp
dedup_group = global
clientconfdir = /etc/burp/clientconfdir
pidfile = /var/run/burp.server.pid
hardlinked_archive = 0
working_dir_recovery_method = delete
umask = 0022

逐项说明：

directory：备份数据根目录，服务端在其下按客户端名建目录。实测布局（每个备份一个以"编号时间戳"命名的子目录，current 符号链接指向最新备份）：

ls -la /var/spool/burp/

实测回显：

total 16
drwxr-xr-x 4 root root 4096 Oct 24 07:02 .
drwxr-xr-x 1 root root 4096 Oct 24 06:48 ..
drwxr-xr-x 4 root root 4096 Oct 24 08:41 client1
drwxr-xr-x 3 root root 4096 Oct 24 07:02 client2

ls -la "/var/spool/burp/client1/"

实测回显：

total 24
drwxr-xr-x 4 root root 4096 Oct 24 08:41 .
drwxr-xr-x 4 root root 4096 Oct 24 07:02 ..
-rw-r--r-- 1 root root 3039 Oct 24 08:42 .command
-rw-r--r-- 1 root root   26 Oct 24 06:51 .created
drwxr-xr-x 2 root root 4096 Oct 24 08:19 0000005 2026-10-24 08:16:54 +0000
drwxr-xr-x 3 root root 4096 Oct 24 08:41 0000006 2026-10-24 08:19:17 +0000
lrwxrwxrwx 1 root root   33 Oct 24 08:19 current -> 0000006 2026-10-24 08:19:17 +0000

单个备份目录内的文件（实测 ls /var/spool/burp/client1/current/）：

backup_stats
data
incexc
log.gz
manifest.gz
restore_stats
restorelog.gz
timestamp
verify_stats
verifylog.gz

解读：data/ 存文件数据、manifest.gz 是清单、log.gz 是本次备份日志、backup_stats/restore_stats/verify_stats 是统计、.command 记录服务端视角的客户端操作流水（内容样例见 5.4 节）。迁移存储盘时改 directory 需要把旧目录整体搬走并保持属主；working_dir_recovery_method = delete 表示备份中断时直接删除残留工作目录（可改 resume 尝试续传）。

dedup_group：去重组名，默认 global——同一组内不同客户端的相同文件块可跨客户端去重；把不相关的客户隔离到不同组可避免数据混杂；
clientconfdir：接入文件目录，文件名必须与客户端 cname 完全一致，缺文件或口令不符都会被拒（见 6.2 节反向实测）；
umask = 0022：服务端写文件的权限掩码。

5.3 保留策略：keep（含多行语义与自动清理实测）

# You can have as many 'keep' lines as you like.
# For example, if running backups daily, setting keep 7, keep 4, keep 6 will keep
# 7 daily backups, 4 weekly, and 6 four-weekly backups.
keep = 7
# keep = 4
# keep = 6

keep 语义（官方模板注释原文翻译 + 实测）：

只有一行 keep = N：保留最近 N 个备份，第 N+1 个备份完成时最旧的自动删除；
多行 keep：实现"GFS 祖孙三代"保留（如 7 个每日 + 4 个每周 + 6 个每四周），多行之间按时间桶分层，新备份完成时服务端按规则清理不满足任何一层的旧备份；
特殊值 keep = 0 表示不自动清理（全靠手动删除）。

keep=2 自动清理实测：初始状态 client1 有备份 0000005（deletable）与 0000006。把服务端 keep = 7 改为 keep = 2（不重启，burp 每次连接重读配置），客户端造一个新文件后做一次备份：

# 服务端
sed -i 's|^keep = 7|keep = 2|' /etc/burp/burp-server.conf
grep -n '^keep' /etc/burp/burp-server.conf
# 客户端
date > /home/client1/keep_test.txt
burp -a b

实测回显（备份统计尾节选）：

       Bytes received:           468
           Bytes sent:          1780 (1.74 KB)
--------------------------------------------------------------------------------
2026-10-24 10:17:54 +0000: burp[3412] Phase 2 end (send file data)
2026-10-24 10:17:54 +0000: burp[3412] backup finished ok

备份 0000007 完成后立即列清单：

burp -a l

实测回显：

Backup: 0000006 2026-10-24 08:19:17 +0000 (deletable)
Backup: 0000007 2026-10-24 10:17:54 +0000

对比改前状态（5、6 两个备份），编号 0000005 已被服务端按 keep=2 自动删除，无需任何手动操作。服务端数据目录同步确认（ls /var/spool/burp/client1/）：

0000006 2026-10-24 08:19:17 +0000
0000007 2026-10-24 10:17:54 +0000
current

验证完毕后把 keep 改回 7。要点：保留策略的清理动作发生在"新备份完成时"，因此改小 keep 不会立刻删历史，要等下一次备份；(deletable) 标记表示该备份当前允许被清理/手动删除。

5.4 定时调度：timer_script 与 timer_arg

burp 的定时模型是"客户端定时来问，服务端裁决"：客户端 cron/systemd 定时执行 burp -a t，服务端运行 timer_script 传入一组 timer_arg 规则，裁决"现在允许备份吗"——允许则当场执行备份，不允许则客户端拿到退出码 3。

# The default timer_script treats the first timer_arg as the minimum interval
# Ensure that 20 hours elapse between backups
# Available units:
# s (seconds), m (minutes), h (hours), d (days), w (weeks), n (months)
# Allow backups to start in the evenings and nights during weekdays
# Allow more hours at the weekend.
# Allow backups to start any time.
timer_arg = 0h
timer_arg = always
#timer_arg = always
# Note that, if you specify no timebands, the timer will never allow backups.

默认 timer 脚本的 timer_arg 规则（自上而下逐条尝试满足）：

timer_arg 写法	含义
`20h`	第一条通常是最小间隔：距上次备份不足 20 小时则拒绝
`mon,tue,wed,thu,fri,22:00,23:59` 这类"天,起,止"时间带	工作日某时段允许
`sat,sun,00:00,23:59`	周末全天允许
`always`	任何时间允许（兜底规则）
`0h`	最小间隔为 0（不限制频率）

timer 裁决实测（一）：服务端规则 timer_arg = 0h + timer_arg = always，客户端 -a T（只裁决不备份）：

2026-10-24 10:18:20 +0000: burp[3452] Timer conditions on the server were met
EXITCODE=0

timer 裁决实测（二）：服务端改为 timer_arg = 20h + timer_arg = always（距上次备份仅 1 分钟，必触发最小间隔），客户端 -a T：

2026-10-24 10:18:19 +0000: burp[3444] Timer conditions on the server were not met
EXITCODE=3

退出码 3 正是 systemd 客户端单元里 SuccessExitStatus=3 要兼容的"裁决不允许"（见《Burp 3.2.0 安装与运行实测指南》第四章），两次实测均为改完即生效、无需重启。

服务端侧留痕：每次裁决与备份都会写进 /var/spool/burp/client1/.command（实测节选）：

2026-10-24 06:52:54 +0000 10.89.68.3 client1 c:0016:backupphase1timedcheck
2026-10-24 06:52:54 +0000 10.89.68.3 client1 c:0011:backupphase1timed

backupphase1timedcheck 即 -a T 的裁决查询、backupphase1timed 是 -a t 的正式定时备份。要点：timer_script 可替换为自定义脚本（源码包自带 /usr/share/burp/scripts/timer_script），只要脚本退出码 0/非 0 表达允许/拒绝即可；timer_repeat_interval 可让服务端在裁决通过后持续重试窗口。注意官方模板的警告：只配最小间隔、不配任何时间带（或 always），timer 将永远不允许备份。

5.5 CA 与证书链参数：ca_conf / ca_name / ca_server_name / ca_burp_ca

服务端兼做证书签发机构（CA）的参数组：

ca_conf = /etc/burp/CA.cnf
ca_name = burpCA
ca_server_name = burpserver
ca_burp_ca = /usr/sbin/burp_ca

# Check for revoked certificates in the certificate revocation list.
ca_crl_check = 1

# SSL certificate authority - same file on both server and client
ssl_cert_ca = /etc/burp/ssl_cert_ca.pem

# Server SSL certificate
ssl_cert = /etc/burp/ssl_cert-server.pem

# Server SSL key
ssl_key = /etc/burp/ssl_cert-server.key

# Server DH file.
ssl_dhfile = /etc/burp/dhfile.pem

逐项说明（启动顺序依据官方 burp_ca 文档 + 实测文件布局）：

ca_conf 指向 openssl 风格的 CA 配置，其中 CA_DIR = /etc/burp/CA。服务端启动时读取它：若 CA_DIR 已存在则跳过初始化，不存在则走 burp -c /etc/burp/burp-server.conf -g 同款初始化流程（生成 CA 根密钥/证书、DH 参数文件、服务端密钥与证书，并把 ssl_cert_ca/ssl_cert/ssl_key 指向的路径覆写为符号链接）。实测链接关系：

ls -l /etc/burp/ssl_cert-server.pem /etc/burp/ssl_cert-server.key
openssl x509 -in /etc/burp/ssl_cert-server.pem -noout -subject

实测回显：

lrwxrwxrwx 1 root root 27 Oct 24 06:49 /etc/burp/ssl_cert-server.key -> /etc/burp/CA/burpserver.key
lrwxrwxrwx 1 root root 27 Oct 24 06:49 /etc/burp/ssl_cert-server.pem -> /etc/burp/CA/burpserver.crt
subject=CN = burpserver

ca_name = burpCA：CA 名，决定根证书文件名 CA_burpCA.crt/.key/.crl；ca_server_name = burpserver：服务端自身证书的 CN（客户端的 ssl_peer_cn 必须与它一致，见 6.2 节反向实测）；
ca_burp_ca：证书操作脚本路径，客户端 CSR 签发、吊销都靠它；
ca_crl_check = 1：服务端握手时校验证书是否在吊销列表（CRL）中；证书签发与吊销由 burp_ca 脚本完成（实测命令流程见本专栏命令篇）；
不想要内置 CA 自动签发，不设 ca_conf 即可（证书全部手工管理）。

CA.cnf 关键项实测（cat /etc/burp/CA.cnf 节选）：

CA_DIR                  = /etc/burp/CA
default_md              = sha256
default_days            = 7300
default_crl_days        = 7300
x509_extensions         = usr_cert
[ usr_cert ]
basicConstraints        = CA:FALSE
[ policy_anything ]
commonName              = supplied

default_days = 7300 即客户端证书默认有效期约 20 年（与实测签发证书 notAfter 距 notBefore 7300 天一致）。CA 数据库 /etc/burp/CA/index.txt 实测样例：

V       461019064930Z           00      unknown /CN=burpserver
V       461019065132Z           01      unknown /CN=client1
R       461019070240Z   261024070932Z   02      unknown /CN=client2

V 为有效、R 为已吊销（client2 在实测中被吊销过，CRL 已含其序列号 02）。

5.6 客户端能力与准入：client_can_* / password_check / super_client

# The following options can restrict what the client can do.
client_can_delete = 1
client_can_diff = 1
client_can_force_backup = 1
client_can_list = 1
client_can_monitor = 1
client_can_restore = 1
client_can_verify = 1

逐项说明：这一组开关限制客户端能在服务端做的操作——删除备份（client_can_delete）、差量比对（client_can_diff）、不经 timer 强制备份（client_can_force_backup = 0 时只允许定时备份）、列清单、看监控、发起恢复、发起校验。置 0 后客户端执行对应 -a 动作会被服务端拒绝。安全上建议生产环境关闭 client_can_delete（防误删全部备份）。

配套参数：

password_check = 1：校验 clientconfdir 中的口令；置 0 完全跳过口令校验（SSL 证书校验不受影响，官方文档明确此行为）；
hard_quota / soft_quota：按客户端在 clientconfdir 文件里设置存储配额（字节），超硬配额备份失败、超软配额告警；
super_client：在全局或单客户端文件中指定"可列出/恢复其他客户端备份"的特权客户端（跨客户端恢复用 -a r -C <其他客户端> 执行，命令用法见本专栏命令篇）；
manual_delete：把删除动作改为"写删除指令文件、由外部定时任务执行"的托管模式；
server_can_restore（单客户端文件/客户端 conf 侧）：置 0 禁止服务端单方面发起恢复。

5.7 传输与压缩：compression / librsync / ratelimit / network_timeout

# Server storage compression. Default is zlib9. Set to zlib0 to turn it off.
#compression = zlib9
# Ratelimit throttles the send speed. Specified in Megabits per second (Mb/s).
# ratelimit = 1.5
# Network timeout defaults to 7200 seconds (2 hours).
# network_timeout = 7200
# When the client version does not match the server version, log a warning.
version_warn = 1

逐项说明：

compression：服务端存储压缩级别，zlib0～zlib9，默认 9（实测 -t 输出 compression: 9，备份日志中客户端同步确认 Compression level: 9）。值越大越省盘越耗 CPU；
librsync = 1 + librsync_max_size = 0：差量传输开关与适用文件大小上限（0 为全部文件都做差量；实测握手日志 Using librsync hash blake2，差量效果量化见 B1 篇 7.4 节：150KB 文件改动后仅传 8.49KB）；
ratelimit：服务端发送限速（Mb/s，恢复时生效），0 不限；
network_timeout = 7200：单次网络操作超时（秒），跨慢速链路备份可调大；
version_warn = 1：客户端与服务端版本不一致时在日志告警（3.x 与 2.x 混连时这是第一线索）；
hardlinked_archive = 0：备份间用硬链接共享未变文件（1 = 归档内硬链接，省空间但恢复略慢）。

六、客户端 burp.conf 与服务端 clientconfdir 详解

6.1 接入四要素：mode / server / cname / password

客户端实测配置关键行：

mode = client
server = 10.89.68.2:4971
status_port = 4972
password = q1w2e3r4
cname = client1

逐项说明：

mode = client：客户端角色（服务端文件里对应 mode = server）；
server：服务端数据端口地址，改动必须与服务端 listen 联动（5.1 节实测了不同步时的退出码 4）；
status_port：服务端状态端口，-a s/-a S/-a m 监控动作连它（实测 -a m 首行日志 Connecting to 10.89.68.2:4972.）；
cname：客户端名，服务端用它匹配 clientconfdir/client1 文件；一台机器跑多个客户端身份时，用 -c 指向不同 conf（实测环境同机第二身份 burp-client2.conf 设 cname = client2、独立 ca_csr_dir 与证书路径）；
password：接入口令，必须与服务端 clientconfdir/client1 中的 password 一致。服务端同名文件实测内容：

cat /etc/burp/clientconfdir/client1

实测回显：

password = q1w2e3r4

# More configuration files can be read, using syntax like the following.
. incexc/*

. incexc/* 引入同目录 incexc 下的附加规则（服务端可在此覆盖客户端的备份范围，见 6.3 节）。clientconfdir 中还默认有模板示例 testclient（password = abcdefgh）。

6.2 双向认证链逐项展开：ssl_cert_ca / ssl_cert / ssl_key / ssl_peer_cn / ca_burp_ca / ca_csr_dir

burp 的准入是"口令 + TLS 双向证书"双保险，客户端侧证书相关实测配置：

ca_burp_ca = /usr/sbin/burp_ca
ca_csr_dir = /etc/burp/CA-client

# SSL certificate authority - same file on both server and client
ssl_cert_ca = /etc/burp/ssl_cert_ca.pem

# Client SSL certificate
ssl_cert = /etc/burp/ssl_cert-client.pem

# Client SSL key
ssl_key = /etc/burp/ssl_cert-client.key

# Common name in the certificate that the server gives us
ssl_peer_cn = burpserver

整条认证链的六个环节（每个环节都标注了实测证据）：

环节	参数/文件	校验内容	实测证据
1 口令	客户端 `password` ↔ 服务端 `clientconfdir/<cname>` 的 `password`	相等	改错口令实测：`unable to authorise on server`，退出码 1（见下）
2 客户端证书自动签发	`ca_burp_ca` + `ca_csr_dir`	首连无证书时自动生成密钥/CSR 并由服务端签发	B1 篇 7.2 节完整 CSR 流程回显
3 客户端出示证书	客户端 `ssl_cert`/`ssl_key`	服务端校验证书由本 CA 签发且未吊销	`ca_crl_check = 1` + CA index.txt
4 服务端出示证书	服务端 `ssl_cert`（CN=ca_server_name）	客户端校验 CA 签名与 CN	证书实测 `subject=CN = burpserver`
5 CN 比对	客户端 `ssl_peer_cn`	必须等于服务端证书 CN	改错实测：`cert common name doesn't match configured ssl_peer_cn`（见下）
6 加密信道	两侧 `ssl_cert_ca` 同一份根证书 + `ssl_dhfile`	TLS 握手协商	实测 `SSL is using cipher: TLS_AES_256_GCM_SHA384 TLSv1.3`

反向实测一：口令改错。 客户端 password 改为 badpw123 后执行 burp -a l：

2026-10-24 10:18:30 +0000: burp[3461] Connecting to 10.89.68.2:4971
2026-10-24 10:18:32 +0000: burp[3461] unexpected command in authorise_client(): e:001D:unable to authorise on server
EXITCODE=1

反向实测二：ssl_peer_cn 改错。 客户端 ssl_peer_cn 改为 notburpserver 后执行 burp -a l：

2026-10-24 10:18:32 +0000: burp[3467] cert common name doesn't match configured ssl_peer_cn
2026-10-24 10:18:32 +0000: burp[3467] 'burpserver'!='notburpserver'
2026-10-24 10:18:32 +0000: burp[3467] check cert failed
EXITCODE=1

两种失败均还原后，burp -a l 立即恢复 auth ok（实测 grep 计数 1）。两类错误消息的区分度很好：口令错误停在 authorise_client()，证书 CN 错误停在 check cert failed——排障时按报错行定位参数。

证书落地后的本机核验（客户端）：

openssl x509 -in /etc/burp/ssl_cert-client.pem -noout -subject -serial -dates

实测回显：

subject=CN = client1
serial=01
notBefore=Oct 24 07:02:40 2026 GMT
notAfter=Oct 19 07:02:40 2046 GMT

CN 即 cname、序列号登记在服务端 CA 数据库、有效期 7300 天（CA.cnf 的 default_days）。ssl_key_password 仅在私钥文件本身加密时需要；ssl_ciphers 可强制套件白名单（默认协商 TLS 1.3 强套件，一般不动）。

6.3 备份范围：include / exclude 族与 server_can_override_includes

客户端实测配置的备份范围段：

include = /home
exclude_fs = sysfs
exclude_fs = tmpfs
nobackup = .nobackup
exclude_comp=bz2
exclude_comp=gz
cross_filesystem=/home
cross_all_filesystems=0

逐项说明：

include：备份范围根，可多行；exclude：范围內再排除的路径，可多行；
exclude_regex = \.cache：按正则排除路径（include_regex 在 3.2.0 官方注释标注尚未实现）；exclude_ext = vdi：按扩展名排除；exclude_comp：这些扩展名的文件存但不再压缩（已压缩文件二次压缩无收益）；
exclude_fs：按文件系统类型整类排除（tmpfs/sysfs/proc 等伪文件系统的标配）；cross_filesystem：允许进入该挂点跨文件系统；cross_all_filesystems = 0 不跨全部边界（默认行为：include 路径内遇到其他文件系统不进入，除非 cross_filesystem 点名放行）；
nobackup = .nobackup：目录里存在名为 .nobackup 的条目则跳过该目录内容；min_file_size/max_file_size：按大小过滤（默认 0 不限）；
atime = 0（默认）：读文件时启用 O_NOATIME 不改动访问时间。

服务端覆盖机制：客户端配置模板注释明示"The server will override them if there is at least one 'include=' line on the server side and 'server_can_override_includes=1'"——服务端在 clientconfdir/<cname>（或其 . incexc/* 引入的文件）里写至少一行 include=，且 server_can_override_includes = 1（-t 实测默认值即 1），客户端本地 include/exclude 即被服务端整体接管。incexc/example 模板实测内容（服务端）：

# If you add at least one 'include=' line, the server will override the
# rest of the client options below, which define exactly what to backup.
# (This file needs to be included in the clientconfdir file for the client,
# using the '. path/to/this/file' syntax. Alternatively, these options can
# be added to the clientconfdir file directly).

# include=/home
# exclude=/home/dontwant
# exclude_ext=vdi
# exclude_regex=/\.cache/
# exclude_fs=tmpfs
# exclude_comp=gz
# min_file_size=0
# max_file_size=0
# cross_filesystem=/some/path
# cross_all_filesystems=0
# nobackup=.nobackup
# read_fifo=/some/path/to/a/fifo
# read_all_fifos=0
# split_vss=1
# strip_vss=0
# atime=0
# scan_problem_raises_error=0

这个机制让"备份什么"最终由服务端统一治理（客户端改了也算数不了），是 burp 相对纯客户端型备份工具（BorgBackup/Restic）的一个管控差异点。

6.4 服务端发起恢复与加密：server_can_restore / restoreprefix / encryption_password

# Set server_can_restore to 0 if you do not want the server to be able to
# initiate a restore (setting it to 1 also requires 'restoreprefix').
server_can_restore = 1
# This option is prefixed to the path of all restores, and is overridden by
# '-d' on the command line.
# restoreprefix = /my/restore/directory

server_can_restore = 1 时必须配 restoreprefix：服务端发起的恢复只能落到该前缀目录内（实测环境 restoreprefix = /root/server_restore，服务端写 /var/spool/burp/<客户端>/restore 指令文件、客户端下次连接时自动执行的触发机制见本专栏命令篇）；
encryption_password：客户端侧对称加密口令。设置后数据在客户端加密、服务端存密文；官方注释明示代价：无法再做差量传输，文件每次变更都整文件重传。信任服务端存储时不启用，以保留 librsync 差量能力；
randomise = 1200：定时备份前随机延迟 0～N 秒，避免大批客户端同时来问（默认不启用）；
progress_counter = 1：备份/恢复时输出进度计数行（实测备份日志中的 dmdff 5、ff 2 行即此开关产物）。

七、生产配置模板

适用场景：2 台～数百台 Linux 服务器的集中文件备份；备份服务器 8GB 内存、NVMe SSD 或大容量 SATA 阵列、磁盘容量 ≥ 全体客户端活跃数据 ×(保留代数 ÷ 去重率)；千兆内网。

服务端 /etc/burp/burp-server.conf 生产模板（在默认模板基础上修改，#>>> 标注改动点）：

mode = server

#>>> 内网监听；跨网段时把状态口限制到管理网或干脆注释掉 listen_status
listen = 0.0.0.0:4971
max_children = 8
listen_status = 10.89.68.2:4972
max_status_children = 5

#>>> 数据盘独立挂载点（如 /data），勿与系统盘混用
directory = /data/burp/spool
dedup_group = global
clientconfdir = /etc/burp/clientconfdir
pidfile = /var/run/burp.server.pid
hardlinked_archive = 1
working_dir_recovery_method = resume
umask = 0022
syslog = 1
stdout = 0

#>>> 收敛客户端能力：禁删、禁强制备份，只走 timer 裁决
client_can_delete = 0
client_can_diff = 1
client_can_force_backup = 0
client_can_list = 1
client_can_monitor = 1
client_can_restore = 1
client_can_verify = 1

#>>> 压缩按 CPU 富余度选 zlib4～zlib9；慢链路可加 ratelimit
compression = zlib4
librsync = 1
librsync_max_size = 0
# ratelimit = 50
network_timeout = 7200

#>>> GFS 保留：7 个每日 + 4 个每周 + 6 个每四周（配合每日 -a t）
keep = 7
keep = 4
keep = 6

#>>> 定时：最小间隔 20h + 工作日晚间/周末/always 时间带（生产标准写法）
timer_script = /usr/share/burp/scripts/timer_script
timer_arg = 20h
timer_arg = mon,tue,wed,thu,fri,22:00,23:59
timer_arg = sat,sun,00:00,23:59
timer_arg = always

ca_conf = /etc/burp/CA.cnf
ca_name = burpCA
ca_server_name = burpserver
ca_burp_ca = /usr/sbin/burp_ca
ca_crl_check = 1
ssl_cert_ca = /etc/burp/ssl_cert_ca.pem
ssl_cert = /etc/burp/ssl_cert-server.pem
ssl_key = /etc/burp/ssl_cert-server.key
ssl_dhfile = /etc/burp/dhfile.pem

version_warn = 1

客户端 /etc/burp/burp.conf 生产模板：

mode = client
server = 10.89.68.2:4971
status_port = 4972
password = q1w2e3r4
cname = client1
pidfile = /var/run/burp.client.pid
syslog = 0
stdout = 0
progress_counter = 0

#>>> 定时备份随机延迟 20 分钟内打散并发
randomise = 1200

ca_burp_ca = /usr/sbin/burp_ca
ca_csr_dir = /etc/burp/CA-client
ssl_cert_ca = /etc/burp/ssl_cert_ca.pem
ssl_cert = /etc/burp/ssl_cert-client.pem
ssl_key = /etc/burp/ssl_cert-client.key
ssl_peer_cn = burpserver

#>>> 备份范围按需列 include；排除伪文件系统与压缩类文件
include = /etc
include = /home
include = /root
exclude_fs = sysfs
exclude_fs = tmpfs
exclude_fs = proc
exclude_comp = bz2
exclude_comp = gz
exclude_comp = zst
nobackup = .nobackup
cross_all_filesystems = 0

server_can_restore = 1
restoreprefix = /root/server_restore

模板要点：

保留策略三层 keep 依赖"每日固定跑一次 -a t"的节奏（cron 7,27,47 * * * * 或 systemd timer，见 B1 篇 7.6 节），层间才有日/周语义；
compression = zlib4 与 hardlinked_archive = 1 是"CPU 换磁盘"的常见组合；CPU 紧张的备份机退回 zlib0～zlib2；
每个客户端在 clientconfdir/<cname> 里单独设口令与配额（hard_quota/soft_quota），不共用一把口令；
改完任何文件先 burp -c <配置> -t 试跑，再处理重启问题（只有 listen 类需要）。

八、常见问题（FAQ）

Q1：改了 keep/timer_arg/clientconfdir 没生效？ 这三类都无需重启，但生效时机不同：keep 在"下一次备份完成时"执行清理（5.3 节实测改小 keep 后旧备份并未立即消失）；timer_arg 在下一次客户端 -a t/-a T 连接时裁决（5.4 节实测即时生效）。先用 burp -c /etc/burp/burp-server.conf -t 确认配置解析值，再看触发时机。

Q2：改了 listen 端口，客户端全部报 Could not connect。 listen/listen_status 必须重启服务端进程才生效，且客户端 server= 要同步改（5.1 节实测：服务端改 4981 后客户端仍连 4971 得到退出码 4）。两侧一致后恢复。

Q3：客户端报 unable to authorise on server 或 check cert failed 怎么区分？ 前者是口令链失败：客户端 password 与服务端 clientconfdir/<cname> 文件中的 password 不一致（或 cname 拼错找不到同名文件）；后者是证书 CN 校验失败：客户端 ssl_peer_cn 与服务端证书 CN（ca_server_name，默认 burpserver）不一致（6.2 节两种失败均有实测回显与退出码 1）。

Q4：burp -a t 总是退出码 3，是不是坏了？ 不是。退出码 3 = 服务端 timer 裁决"当前不允许备份"（最小间隔未到或不在时间带内，5.4 节实测）。生产上这正是打散备份时机的正常机制；若想立即备份用 burp -a b（需服务端 client_can_force_backup = 1）。注意：timer 只配了间隔类规则、没有任何时间带或 always 时，将永远不允许备份——保持 timer_arg = always 作为兜底行。

Q5：-o keep=3 试跑时输出里 keep 出现了两行？ -o 对可重复键是追加不是替换（3.2 节实测 keep: 7 + keep: 3 并存），对单值键才是替换。临时压参数时留意这个语义差。

Q6：服务端 clientconfdir 里的文件名有什么讲究？ 必须与客户端 cname 完全一致（区分大小写），文件内 password 必须与客户端一致；. incexc/* 引入的文件里只要出现一行 include= 且 server_can_override_includes = 1，客户端本地的备份范围就被服务端接管（6.3 节）。

Q7：想给某客户端限磁盘用量？ 在该客户端的 clientconfdir 文件里设 hard_quota（超限备份失败）与 soft_quota（超限告警），单位字节；-t 试跑可见默认 0 即不限。

九、参考链接

Burp 官网与文档：https://burp.grke.org/
官方服务器配置文档（server basics）：https://burp.grke.org/docs/server-basics.html
官方保留策略文档：https://burp.grke.org/docs/retention.html
官方定时脚本文档：https://burp.grke.org/docs/timer_script.html
官方 CA 与证书文档：https://burp.grke.org/docs/burp_ca.html
本专栏选型篇：《Burp 3.2.0 介绍与选型指南》
本专栏安装篇：《Burp 3.2.0 安装与运行实测指南》
本站同类组件配置篇：《Restic 配置参数详解》、《BorgBackup 配置参数详解》、《Proxmox Backup Server 4.2 配置参数详解》

Burp 3.2.0 配置参数详解

Burp 3.2.0 配置参数详解

一、环境信息

二、前置条件

2.1 两侧服务就绪

2.2 burp 的配置文件模型

三、参数查看与修改方式

3.1 -t 试跑：一次看全所有生效参数值

3.2 -o 命令行覆写：不改文件的临时参数

3.3 配置生效时机：哪些改动要重启

四、参数总览

五、服务端 burp-server.conf 核心参数分类详解

5.1 监听与并发：listen / listen_status / max_children

5.2 存储目录与数据布局：directory / dedup_group / clientconfdir

5.3 保留策略：keep（含多行语义与自动清理实测）

5.4 定时调度：timer_script 与 timer_arg

5.5 CA 与证书链参数：ca_conf / ca_name / ca_server_name / ca_burp_ca

5.6 客户端能力与准入：client_can_* / password_check / super_client

5.7 传输与压缩：compression / librsync / ratelimit / network_timeout

六、客户端 burp.conf 与服务端 clientconfdir 详解

6.1 接入四要素：mode / server / cname / password

6.2 双向认证链逐项展开：ssl_cert_ca / ssl_cert / ssl_key / ssl_peer_cn / ca_burp_ca / ca_csr_dir

6.3 备份范围：include / exclude 族与 server_can_override_includes

6.4 服务端发起恢复与加密：server_can_restore / restoreprefix / encryption_password

七、生产配置模板

八、常见问题（FAQ）

九、参考链接

3.1 `-t` 试跑：一次看全所有生效参数值

3.2 `-o` 命令行覆写：不改文件的临时参数