Simple, configuration-driven backup software for servers and workstations https://torsion.org/borgmatic/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

schema.yaml 22KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452
  1. name: Borgmatic configuration file schema
  2. version: 1
  3. map:
  4. location:
  5. desc: |
  6. Where to look for files to backup, and where to store those backups. See
  7. https://borgbackup.readthedocs.io/en/stable/quickstart.html and
  8. https://borgbackup.readthedocs.io/en/stable/usage.html#borg-create for details.
  9. required: true
  10. map:
  11. source_directories:
  12. required: true
  13. seq:
  14. - type: str
  15. desc: |
  16. List of source directories to backup (required). Globs and tildes are expanded.
  17. example:
  18. - /home
  19. - /etc
  20. - /var/log/syslog*
  21. repositories:
  22. required: true
  23. seq:
  24. - type: str
  25. desc: |
  26. Paths to local or remote repositories (required). Tildes are expanded. Multiple
  27. repositories are backed up to in sequence. See ssh_command for SSH options like
  28. identity file or port.
  29. example:
  30. - user@backupserver:sourcehostname.borg
  31. one_file_system:
  32. type: bool
  33. desc: Stay in same file system (do not cross mount points). Defaults to false.
  34. example: true
  35. numeric_owner:
  36. type: bool
  37. desc: Only store/extract numeric user and group identifiers. Defaults to false.
  38. example: true
  39. atime:
  40. type: bool
  41. desc: Store atime into archive. Defaults to true.
  42. example: false
  43. ctime:
  44. type: bool
  45. desc: Store ctime into archive. Defaults to true.
  46. example: false
  47. birthtime:
  48. type: bool
  49. desc: Store birthtime (creation date) into archive. Defaults to true.
  50. example: false
  51. read_special:
  52. type: bool
  53. desc: |
  54. Use Borg's --read-special flag to allow backup of block and other special
  55. devices. Use with caution, as it will lead to problems if used when
  56. backing up special devices such as /dev/zero. Defaults to false.
  57. example: false
  58. bsd_flags:
  59. type: bool
  60. desc: Record bsdflags (e.g. NODUMP, IMMUTABLE) in archive. Defaults to true.
  61. example: true
  62. files_cache:
  63. type: str
  64. desc: |
  65. Mode in which to operate the files cache. See
  66. https://borgbackup.readthedocs.io/en/stable/usage/create.html#description for
  67. details. Defaults to "ctime,size,inode".
  68. example: ctime,size,inode
  69. local_path:
  70. type: str
  71. desc: Alternate Borg local executable. Defaults to "borg".
  72. example: borg1
  73. remote_path:
  74. type: str
  75. desc: Alternate Borg remote executable. Defaults to "borg".
  76. example: borg1
  77. patterns:
  78. seq:
  79. - type: str
  80. desc: |
  81. Any paths matching these patterns are included/excluded from backups. Globs are
  82. expanded. (Tildes are not.) Note that Borg considers this option experimental.
  83. See the output of "borg help patterns" for more details. Quote any value if it
  84. contains leading punctuation, so it parses correctly.
  85. example:
  86. - 'R /'
  87. - '- /home/*/.cache'
  88. - '+ /home/susan'
  89. - '- /home/*'
  90. patterns_from:
  91. seq:
  92. - type: str
  93. desc: |
  94. Read include/exclude patterns from one or more separate named files, one pattern
  95. per line. Note that Borg considers this option experimental. See the output of
  96. "borg help patterns" for more details.
  97. example:
  98. - /etc/borgmatic/patterns
  99. exclude_patterns:
  100. seq:
  101. - type: str
  102. desc: |
  103. Any paths matching these patterns are excluded from backups. Globs and tildes
  104. are expanded. See the output of "borg help patterns" for more details.
  105. example:
  106. - '*.pyc'
  107. - ~/*/.cache
  108. - /etc/ssl
  109. exclude_from:
  110. seq:
  111. - type: str
  112. desc: |
  113. Read exclude patterns from one or more separate named files, one pattern per
  114. line. See the output of "borg help patterns" for more details.
  115. example:
  116. - /etc/borgmatic/excludes
  117. exclude_caches:
  118. type: bool
  119. desc: |
  120. Exclude directories that contain a CACHEDIR.TAG file. See
  121. http://www.brynosaurus.com/cachedir/spec.html for details. Defaults to false.
  122. example: true
  123. exclude_if_present:
  124. type: str
  125. desc: |
  126. Exclude directories that contain a file with the given filename. Defaults to not
  127. set.
  128. example: .nobackup
  129. storage:
  130. desc: |
  131. Repository storage options. See
  132. https://borgbackup.readthedocs.io/en/stable/usage.html#borg-create and
  133. https://borgbackup.readthedocs.io/en/stable/usage/general.html#environment-variables for
  134. details.
  135. map:
  136. encryption_passcommand:
  137. type: str
  138. desc: |
  139. The standard output of this command is used to unlock the encryption key. Only
  140. use on repositories that were initialized with passcommand/repokey encryption.
  141. Note that if both encryption_passcommand and encryption_passphrase are set,
  142. then encryption_passphrase takes precedence. Defaults to not set.
  143. example: "secret-tool lookup borg-repository repo-name"
  144. encryption_passphrase:
  145. type: str
  146. desc: |
  147. Passphrase to unlock the encryption key with. Only use on repositories that were
  148. initialized with passphrase/repokey encryption. Quote the value if it contains
  149. punctuation, so it parses correctly. And backslash any quote or backslash
  150. literals as well. Defaults to not set.
  151. example: "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"
  152. checkpoint_interval:
  153. type: int
  154. desc: |
  155. Number of seconds between each checkpoint during a long-running backup. See
  156. https://borgbackup.readthedocs.io/en/stable/faq.html#if-a-backup-stops-mid-way-does-the-already-backed-up-data-stay-there
  157. for details. Defaults to checkpoints every 1800 seconds (30 minutes).
  158. example: 1800
  159. chunker_params:
  160. type: str
  161. desc: |
  162. Specify the parameters passed to then chunker (CHUNK_MIN_EXP, CHUNK_MAX_EXP,
  163. HASH_MASK_BITS, HASH_WINDOW_SIZE). See https://borgbackup.readthedocs.io/en/stable/internals.html
  164. for details. Defaults to "19,23,21,4095".
  165. example: 19,23,21,4095
  166. compression:
  167. type: str
  168. desc: |
  169. Type of compression to use when creating archives. See
  170. https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create for details.
  171. Defaults to "lz4".
  172. example: lz4
  173. remote_rate_limit:
  174. type: int
  175. desc: Remote network upload rate limit in kiBytes/second. Defaults to unlimited.
  176. example: 100
  177. ssh_command:
  178. type: str
  179. desc: |
  180. Command to use instead of "ssh". This can be used to specify ssh options.
  181. Defaults to not set.
  182. example: ssh -i /path/to/private/key
  183. borg_base_directory:
  184. type: str
  185. desc: |
  186. Base path used for various Borg directories. Defaults to $HOME, ~$USER, or ~.
  187. See https://borgbackup.readthedocs.io/en/stable/usage/general.html#environment-variables for details.
  188. example: /path/to/base
  189. borg_config_directory:
  190. type: str
  191. desc: |
  192. Path for Borg configuration files. Defaults to $borg_base_directory/.config/borg
  193. example: /path/to/base/config
  194. borg_cache_directory:
  195. type: str
  196. desc: |
  197. Path for Borg cache files. Defaults to $borg_base_directory/.cache/borg
  198. example: /path/to/base/cache
  199. borg_security_directory:
  200. type: str
  201. desc: |
  202. Path for Borg security and encryption nonce files. Defaults to $borg_base_directory/.config/borg/security
  203. example: /path/to/base/config/security
  204. borg_keys_directory:
  205. type: str
  206. desc: |
  207. Path for Borg encryption key files. Defaults to $borg_base_directory/.config/borg/keys
  208. example: /path/to/base/config/keys
  209. umask:
  210. type: scalar
  211. desc: Umask to be used for borg create. Defaults to 0077.
  212. example: 0077
  213. lock_wait:
  214. type: int
  215. desc: Maximum seconds to wait for acquiring a repository/cache lock. Defaults to 1.
  216. example: 5
  217. archive_name_format:
  218. type: str
  219. desc: |
  220. Name of the archive. Borg placeholders can be used. See the output of
  221. "borg help placeholders" for details. Defaults to
  222. "{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}". If you specify this option, you must
  223. also specify a prefix in the retention section to avoid accidental pruning of
  224. archives with a different archive name format. And you should also specify a
  225. prefix in the consistency section as well.
  226. example: "{hostname}-documents-{now}"
  227. relocated_repo_access_is_ok:
  228. type: bool
  229. desc: Bypass Borg error about a repository that has been moved. Defaults to false.
  230. example: true
  231. unknown_unencrypted_repo_access_is_ok:
  232. type: bool
  233. desc: |
  234. Bypass Borg error about a previously unknown unencrypted repository. Defaults to
  235. false.
  236. example: true
  237. retention:
  238. desc: |
  239. Retention policy for how many backups to keep in each category. See
  240. https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for details.
  241. At least one of the "keep" options is required for pruning to work. See
  242. https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups/
  243. if you'd like to skip pruning entirely.
  244. map:
  245. keep_within:
  246. type: str
  247. desc: Keep all archives within this time interval.
  248. example: 3H
  249. keep_secondly:
  250. type: int
  251. desc: Number of secondly archives to keep.
  252. example: 60
  253. keep_minutely:
  254. type: int
  255. desc: Number of minutely archives to keep.
  256. example: 60
  257. keep_hourly:
  258. type: int
  259. desc: Number of hourly archives to keep.
  260. example: 24
  261. keep_daily:
  262. type: int
  263. desc: Number of daily archives to keep.
  264. example: 7
  265. keep_weekly:
  266. type: int
  267. desc: Number of weekly archives to keep.
  268. example: 4
  269. keep_monthly:
  270. type: int
  271. desc: Number of monthly archives to keep.
  272. example: 6
  273. keep_yearly:
  274. type: int
  275. desc: Number of yearly archives to keep.
  276. example: 1
  277. prefix:
  278. type: str
  279. desc: |
  280. When pruning, only consider archive names starting with this prefix.
  281. Borg placeholders can be used. See the output of "borg help placeholders" for
  282. details. Defaults to "{hostname}-". Use an empty value to disable the default.
  283. example: sourcehostname
  284. consistency:
  285. desc: |
  286. Consistency checks to run after backups. See
  287. https://borgbackup.readthedocs.org/en/stable/usage.html#borg-check and
  288. https://borgbackup.readthedocs.org/en/stable/usage.html#borg-extract for details.
  289. map:
  290. checks:
  291. seq:
  292. - type: str
  293. enum: ['repository', 'archives', 'data', 'extract', 'disabled']
  294. unique: true
  295. desc: |
  296. List of one or more consistency checks to run: "repository", "archives", "data",
  297. and/or "extract". Defaults to "repository" and "archives". Set to "disabled" to
  298. disable all consistency checks. "repository" checks the consistency of the
  299. repository, "archives" checks all of the archives, "data" verifies the integrity
  300. of the data within the archives, and "extract" does an extraction dry-run of the
  301. most recent archive. Note that "data" implies "archives".
  302. example:
  303. - repository
  304. - archives
  305. check_repositories:
  306. seq:
  307. - type: str
  308. desc: |
  309. Paths to a subset of the repositories in the location section on which to run
  310. consistency checks. Handy in case some of your repositories are very large, and
  311. so running consistency checks on them would take too long. Defaults to running
  312. consistency checks on all repositories configured in the location section.
  313. example:
  314. - user@backupserver:sourcehostname.borg
  315. check_last:
  316. type: int
  317. desc: Restrict the number of checked archives to the last n. Applies only to the
  318. "archives" check. Defaults to checking all archives.
  319. example: 3
  320. prefix:
  321. type: str
  322. desc: |
  323. When performing the "archives" check, only consider archive names starting with
  324. this prefix. Borg placeholders can be used. See the output of
  325. "borg help placeholders" for details. Defaults to "{hostname}-". Use an empty
  326. value to disable the default.
  327. example: sourcehostname
  328. output:
  329. desc: |
  330. Options for customizing borgmatic's own output and logging.
  331. map:
  332. color:
  333. type: bool
  334. desc: |
  335. Apply color to console output. Can be overridden with --no-color command-line
  336. flag. Defaults to true.
  337. example: false
  338. hooks:
  339. desc: |
  340. Shell commands, scripts, or integrations to execute at various points during a borgmatic
  341. run. IMPORTANT: All provided commands and scripts are executed with user permissions of
  342. borgmatic. Do not forget to set secure permissions on this configuration file (chmod
  343. 0600) as well as on any script called from a hook (chmod 0700) to prevent potential
  344. shell injection or privilege escalation.
  345. map:
  346. before_backup:
  347. seq:
  348. - type: str
  349. desc: |
  350. List of one or more shell commands or scripts to execute before creating a
  351. backup, run once per configuration file.
  352. example:
  353. - echo "Starting a backup."
  354. after_backup:
  355. seq:
  356. - type: str
  357. desc: |
  358. List of one or more shell commands or scripts to execute after creating a
  359. backup, run once per configuration file.
  360. example:
  361. - echo "Created a backup."
  362. on_error:
  363. seq:
  364. - type: str
  365. desc: |
  366. List of one or more shell commands or scripts to execute when an exception
  367. occurs during a backup or when running a before_backup or after_backup hook.
  368. example:
  369. - echo "Error while creating a backup or running a backup hook."
  370. postgresql_databases:
  371. seq:
  372. - map:
  373. name:
  374. required: true
  375. type: str
  376. desc: |
  377. Database name (required if using this hook). Or "all" to dump all
  378. databases on the host.
  379. example: users
  380. hostname:
  381. type: str
  382. desc: |
  383. Database hostname to connect to. Defaults to connecting via local
  384. Unix socket.
  385. example: database.example.org
  386. port:
  387. type: int
  388. desc: Port to connect to. Defaults to 5432.
  389. example: 5433
  390. username:
  391. type: str
  392. desc: |
  393. Username with which to connect to the database. Defaults to the
  394. username of the current user. You probably want to specify the
  395. "postgres" superuser here when the database name is "all".
  396. example: dbuser
  397. password:
  398. type: str
  399. desc: |
  400. Password with which to connect to the database. Omitting a password
  401. will only work if PostgreSQL is configured to trust the configured
  402. username without a password, or you create a ~/.pgpass file.
  403. example: trustsome1
  404. format:
  405. type: str
  406. enum: ['plain', 'custom', 'directory', 'tar']
  407. desc: |
  408. Database dump output format. One of "plain", "custom", "directory",
  409. or "tar". Defaults to "custom" (unlike raw pg_dump). See
  410. https://www.postgresql.org/docs/current/app-pgdump.html for details.
  411. Note that format is ignored when the database name is "all".
  412. example: directory
  413. options:
  414. type: str
  415. desc: |
  416. Additional pg_dump/pg_dumpall options to pass directly to the dump
  417. command, without performing any validation on them. See
  418. https://www.postgresql.org/docs/current/app-pgdump.html for details.
  419. example: --role=someone
  420. desc: |
  421. List of one or more PostgreSQL databases to dump before creating a backup,
  422. run once per configuration file. The database dumps are added to your source
  423. directories at runtime, backed up, and then removed afterwards. Requires
  424. pg_dump/pg_dumpall/pg_restore commands. See
  425. https://www.postgresql.org/docs/current/app-pgdump.html for details.
  426. healthchecks:
  427. type: str
  428. desc: |
  429. Healthchecks ping URL or UUID to notify when a backup begins, ends, or errors.
  430. Create an account at https://healthchecks.io if you'd like to use this service.
  431. example:
  432. https://hc-ping.com/your-uuid-here
  433. before_everything:
  434. seq:
  435. - type: str
  436. desc: |
  437. List of one or more shell commands or scripts to execute before running all
  438. actions (if one of them is "create"), run once before all configuration files.
  439. example:
  440. - echo "Starting actions."
  441. after_everything:
  442. seq:
  443. - type: str
  444. desc: |
  445. List of one or more shell commands or scripts to execute after running all
  446. actions (if one of them is "create"), run once after all configuration files.
  447. example:
  448. - echo "Completed actions."
  449. umask:
  450. type: scalar
  451. desc: Umask used when executing hooks. Defaults to the umask that borgmatic is run with.
  452. example: 0077