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.

746 lines
34 KiB

  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.
  7. See https://borgbackup.readthedocs.io/en/stable/quickstart.html and
  8. https://borgbackup.readthedocs.io/en/stable/usage/create.html
  9. for details.
  10. required: true
  11. map:
  12. source_directories:
  13. required: true
  14. seq:
  15. - type: str
  16. desc: |
  17. List of source directories to backup (required). Globs and
  18. tildes are expanded.
  19. example:
  20. - /home
  21. - /etc
  22. - /var/log/syslog*
  23. repositories:
  24. required: true
  25. seq:
  26. - type: str
  27. desc: |
  28. Paths to local or remote repositories (required). Tildes are
  29. expanded. Multiple repositories are backed up to in
  30. sequence. See ssh_command for SSH options like identity file
  31. or port.
  32. If systemd service is used, then add local repository paths
  33. in the systemd service file to the ReadWritePaths list.
  34. example:
  35. - user@backupserver:sourcehostname.borg
  36. one_file_system:
  37. type: bool
  38. desc: |
  39. Stay in same file system (do not cross mount points).
  40. Defaults to false. But when a database hook is used, the
  41. setting here is ignored and one_file_system is considered
  42. true.
  43. example: true
  44. numeric_owner:
  45. type: bool
  46. desc: |
  47. Only store/extract numeric user and group identifiers.
  48. Defaults to false.
  49. example: true
  50. atime:
  51. type: bool
  52. desc: Store atime into archive. Defaults to true.
  53. example: false
  54. ctime:
  55. type: bool
  56. desc: Store ctime into archive. Defaults to true.
  57. example: false
  58. birthtime:
  59. type: bool
  60. desc: |
  61. Store birthtime (creation date) into archive. Defaults to
  62. true.
  63. example: false
  64. read_special:
  65. type: bool
  66. desc: |
  67. Use Borg's --read-special flag to allow backup of block and
  68. other special devices. Use with caution, as it will lead to
  69. problems if used when backing up special devices such as
  70. /dev/zero. Defaults to false. But when a database hook is
  71. used, the setting here is ignored and read_special is
  72. considered true.
  73. example: false
  74. bsd_flags:
  75. type: bool
  76. desc: |
  77. Record bsdflags (e.g. NODUMP, IMMUTABLE) in archive.
  78. Defaults to true.
  79. example: true
  80. files_cache:
  81. type: str
  82. desc: |
  83. Mode in which to operate the files cache. See
  84. http://borgbackup.readthedocs.io/en/stable/usage/create.html
  85. for details. Defaults to "ctime,size,inode".
  86. example: ctime,size,inode
  87. local_path:
  88. type: str
  89. desc: Alternate Borg local executable. Defaults to "borg".
  90. example: borg1
  91. remote_path:
  92. type: str
  93. desc: Alternate Borg remote executable. Defaults to "borg".
  94. example: borg1
  95. patterns:
  96. seq:
  97. - type: str
  98. desc: |
  99. Any paths matching these patterns are included/excluded from
  100. backups. Globs are expanded. (Tildes are not.) Note that
  101. Borg considers this option experimental. See the output of
  102. "borg help patterns" for more details. Quote any value if it
  103. contains leading punctuation, so it parses correctly.
  104. example:
  105. - 'R /'
  106. - '- /home/*/.cache'
  107. - '+ /home/susan'
  108. - '- /home/*'
  109. patterns_from:
  110. seq:
  111. - type: str
  112. desc: |
  113. Read include/exclude patterns from one or more separate
  114. named files, one pattern per line. Note that Borg considers
  115. this option experimental. See the output of "borg help
  116. patterns" for more details.
  117. example:
  118. - /etc/borgmatic/patterns
  119. exclude_patterns:
  120. seq:
  121. - type: str
  122. desc: |
  123. Any paths matching these patterns are excluded from backups.
  124. Globs and tildes are expanded. See the output of "borg help
  125. patterns" for more details.
  126. example:
  127. - '*.pyc'
  128. - /home/*/.cache
  129. - /etc/ssl
  130. exclude_from:
  131. seq:
  132. - type: str
  133. desc: |
  134. Read exclude patterns from one or more separate named files,
  135. one pattern per line. See the output of "borg help patterns"
  136. for more details.
  137. example:
  138. - /etc/borgmatic/excludes
  139. exclude_caches:
  140. type: bool
  141. desc: |
  142. Exclude directories that contain a CACHEDIR.TAG file. See
  143. http://www.brynosaurus.com/cachedir/spec.html for details.
  144. Defaults to false.
  145. example: true
  146. exclude_if_present:
  147. seq:
  148. - type: str
  149. desc: |
  150. Exclude directories that contain a file with the given
  151. filenames. Defaults to not set.
  152. example:
  153. - .nobackup
  154. keep_exclude_tags:
  155. type: bool
  156. desc: |
  157. If true, the exclude_if_present filename is included in
  158. backups. Defaults to false, meaning that the
  159. exclude_if_present filename is omitted from backups.
  160. example: true
  161. exclude_nodump:
  162. type: bool
  163. desc: |
  164. Exclude files with the NODUMP flag. Defaults to false.
  165. example: true
  166. borgmatic_source_directory:
  167. type: str
  168. desc: |
  169. Path for additional source files used for temporary internal
  170. state like borgmatic database dumps. Note that changing this
  171. path prevents "borgmatic restore" from finding any database
  172. dumps created before the change. Defaults to ~/.borgmatic
  173. example: /tmp/borgmatic
  174. storage:
  175. desc: |
  176. Repository storage options. See
  177. https://borgbackup.readthedocs.io/en/stable/usage/create.html and
  178. https://borgbackup.readthedocs.io/en/stable/usage/general.html for
  179. details.
  180. map:
  181. encryption_passcommand:
  182. type: str
  183. desc: |
  184. The standard output of this command is used to unlock the
  185. encryption key. Only use on repositories that were
  186. initialized with passcommand/repokey encryption. Note that
  187. if both encryption_passcommand and encryption_passphrase are
  188. set, then encryption_passphrase takes precedence. Defaults
  189. to not set.
  190. example: "secret-tool lookup borg-repository repo-name"
  191. encryption_passphrase:
  192. type: str
  193. desc: |
  194. Passphrase to unlock the encryption key with. Only use on
  195. repositories that were initialized with passphrase/repokey
  196. encryption. Quote the value if it contains punctuation, so
  197. it parses correctly. And backslash any quote or backslash
  198. literals as well. Defaults to not set.
  199. example: "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"
  200. checkpoint_interval:
  201. type: int
  202. desc: |
  203. Number of seconds between each checkpoint during a
  204. long-running backup. See
  205. https://borgbackup.readthedocs.io/en/stable/faq.html
  206. for details. Defaults to checkpoints every 1800 seconds (30
  207. minutes).
  208. example: 1800
  209. chunker_params:
  210. type: str
  211. desc: |
  212. Specify the parameters passed to then chunker
  213. (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS,
  214. HASH_WINDOW_SIZE). See
  215. https://borgbackup.readthedocs.io/en/stable/internals.html
  216. for details. Defaults to "19,23,21,4095".
  217. example: 19,23,21,4095
  218. compression:
  219. type: str
  220. desc: |
  221. Type of compression to use when creating archives. See
  222. http://borgbackup.readthedocs.io/en/stable/usage/create.html
  223. for details. Defaults to "lz4".
  224. example: lz4
  225. remote_rate_limit:
  226. type: int
  227. desc: |
  228. Remote network upload rate limit in kiBytes/second. Defaults
  229. to unlimited.
  230. example: 100
  231. temporary_directory:
  232. type: str
  233. desc: |
  234. Directory where temporary files are stored. Defaults to
  235. $TMPDIR
  236. example: /path/to/tmpdir
  237. ssh_command:
  238. type: str
  239. desc: |
  240. Command to use instead of "ssh". This can be used to specify
  241. ssh options. Defaults to not set.
  242. example: ssh -i /path/to/private/key
  243. borg_base_directory:
  244. type: str
  245. desc: |
  246. Base path used for various Borg directories. Defaults to
  247. $HOME, ~$USER, or ~.
  248. example: /path/to/base
  249. borg_config_directory:
  250. type: str
  251. desc: |
  252. Path for Borg configuration files. Defaults to
  253. $borg_base_directory/.config/borg
  254. example: /path/to/base/config
  255. borg_cache_directory:
  256. type: str
  257. desc: |
  258. Path for Borg cache files. Defaults to
  259. $borg_base_directory/.cache/borg
  260. example: /path/to/base/cache
  261. borg_security_directory:
  262. type: str
  263. desc: |
  264. Path for Borg security and encryption nonce files. Defaults
  265. to $borg_base_directory/.config/borg/security
  266. example: /path/to/base/config/security
  267. borg_keys_directory:
  268. type: str
  269. desc: |
  270. Path for Borg encryption key files. Defaults to
  271. $borg_base_directory/.config/borg/keys
  272. example: /path/to/base/config/keys
  273. umask:
  274. type: scalar
  275. desc: Umask to be used for borg create. Defaults to 0077.
  276. example: 0077
  277. lock_wait:
  278. type: int
  279. desc: |
  280. Maximum seconds to wait for acquiring a repository/cache
  281. lock. Defaults to 1.
  282. example: 5
  283. archive_name_format:
  284. type: str
  285. desc: |
  286. Name of the archive. Borg placeholders can be used. See the
  287. output of "borg help placeholders" for details. Defaults to
  288. "{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}". If you specify this
  289. option, you must also specify a prefix in the retention
  290. section to avoid accidental pruning of archives with a
  291. different archive name format. And you should also specify a
  292. prefix in the consistency section as well.
  293. example: "{hostname}-documents-{now}"
  294. relocated_repo_access_is_ok:
  295. type: bool
  296. desc: |
  297. Bypass Borg error about a repository that has been moved.
  298. Defaults to false.
  299. example: true
  300. unknown_unencrypted_repo_access_is_ok:
  301. type: bool
  302. desc: |
  303. Bypass Borg error about a previously unknown unencrypted
  304. repository. Defaults to false.
  305. example: true
  306. extra_borg_options:
  307. map:
  308. init:
  309. type: str
  310. desc: |
  311. Extra command-line options to pass to "borg init".
  312. example: "--make-parent-dirs"
  313. prune:
  314. type: str
  315. desc: |
  316. Extra command-line options to pass to "borg prune".
  317. example: "--save-space"
  318. create:
  319. type: str
  320. desc: |
  321. Extra command-line options to pass to "borg create".
  322. example: "--no-files-cache"
  323. check:
  324. type: str
  325. desc: |
  326. Extra command-line options to pass to "borg check".
  327. example: "--save-space"
  328. desc: |
  329. Additional options to pass directly to particular Borg
  330. commands, handy for Borg options that borgmatic does not yet
  331. support natively. Note that borgmatic does not perform any
  332. validation on these options. Running borgmatic with
  333. "--verbosity 2" shows the exact Borg command-line
  334. invocation.
  335. retention:
  336. desc: |
  337. Retention policy for how many backups to keep in each category. See
  338. https://borgbackup.readthedocs.io/en/stable/usage/prune.html for
  339. details. At least one of the "keep" options is required for pruning
  340. to work. To skip pruning entirely, run "borgmatic create" or "check"
  341. without the "prune" action. See borgmatic documentation for details.
  342. map:
  343. keep_within:
  344. type: str
  345. desc: Keep all archives within this time interval.
  346. example: 3H
  347. keep_secondly:
  348. type: int
  349. desc: Number of secondly archives to keep.
  350. example: 60
  351. keep_minutely:
  352. type: int
  353. desc: Number of minutely archives to keep.
  354. example: 60
  355. keep_hourly:
  356. type: int
  357. desc: Number of hourly archives to keep.
  358. example: 24
  359. keep_daily:
  360. type: int
  361. desc: Number of daily archives to keep.
  362. example: 7
  363. keep_weekly:
  364. type: int
  365. desc: Number of weekly archives to keep.
  366. example: 4
  367. keep_monthly:
  368. type: int
  369. desc: Number of monthly archives to keep.
  370. example: 6
  371. keep_yearly:
  372. type: int
  373. desc: Number of yearly archives to keep.
  374. example: 1
  375. prefix:
  376. type: str
  377. desc: |
  378. When pruning, only consider archive names starting with this
  379. prefix. Borg placeholders can be used. See the output of
  380. "borg help placeholders" for details. Defaults to
  381. "{hostname}-". Use an empty value to disable the default.
  382. example: sourcehostname
  383. consistency:
  384. desc: |
  385. Consistency checks to run after backups. See
  386. https://borgbackup.readthedocs.io/en/stable/usage/check.html and
  387. https://borgbackup.readthedocs.io/en/stable/usage/extract.html for
  388. details.
  389. map:
  390. checks:
  391. seq:
  392. - type: str
  393. enum: [
  394. 'repository',
  395. 'archives',
  396. 'data',
  397. 'extract',
  398. 'disabled'
  399. ]
  400. unique: true
  401. desc: |
  402. List of one or more consistency checks to run: "repository",
  403. "archives", "data", and/or "extract". Defaults to
  404. "repository" and "archives". Set to "disabled" to disable
  405. all consistency checks. "repository" checks the consistency
  406. of the repository, "archives" checks all of the archives,
  407. "data" verifies the integrity of the data within the
  408. archives, and "extract" does an extraction dry-run of the
  409. most recent archive. Note that "data" implies "archives".
  410. example:
  411. - repository
  412. - archives
  413. check_repositories:
  414. seq:
  415. - type: str
  416. desc: |
  417. Paths to a subset of the repositories in the location
  418. section on which to run consistency checks. Handy in case
  419. some of your repositories are very large, and so running
  420. consistency checks on them would take too long. Defaults to
  421. running consistency checks on all repositories configured in
  422. the location section.
  423. example:
  424. - user@backupserver:sourcehostname.borg
  425. check_last:
  426. type: int
  427. desc: |
  428. Restrict the number of checked archives to the last n.
  429. Applies only to the "archives" check. Defaults to checking
  430. all archives.
  431. example: 3
  432. prefix:
  433. type: str
  434. desc: |
  435. When performing the "archives" check, only consider archive
  436. names starting with this prefix. Borg placeholders can be
  437. used. See the output of "borg help placeholders" for
  438. details. Defaults to "{hostname}-". Use an empty value to
  439. disable the default.
  440. example: sourcehostname
  441. output:
  442. desc: |
  443. Options for customizing borgmatic's own output and logging.
  444. map:
  445. color:
  446. type: bool
  447. desc: |
  448. Apply color to console output. Can be overridden with
  449. --no-color command-line flag. Defaults to true.
  450. example: false
  451. hooks:
  452. desc: |
  453. Shell commands, scripts, or integrations to execute at various
  454. points during a borgmatic run. IMPORTANT: All provided commands and
  455. scripts are executed with user permissions of borgmatic. Do not
  456. forget to set secure permissions on this configuration file (chmod
  457. 0600) as well as on any script called from a hook (chmod 0700) to
  458. prevent potential shell injection or privilege escalation.
  459. map:
  460. before_backup:
  461. seq:
  462. - type: str
  463. desc: |
  464. List of one or more shell commands or scripts to execute
  465. before creating a backup, run once per configuration file.
  466. example:
  467. - echo "Starting a backup."
  468. before_prune:
  469. seq:
  470. - type: str
  471. desc: |
  472. List of one or more shell commands or scripts to execute
  473. before pruning, run once per configuration file.
  474. example:
  475. - echo "Starting pruning."
  476. before_check:
  477. seq:
  478. - type: str
  479. desc: |
  480. List of one or more shell commands or scripts to execute
  481. before consistency checks, run once per configuration file.
  482. example:
  483. - echo "Starting checks."
  484. before_extract:
  485. seq:
  486. - type: str
  487. desc: |
  488. List of one or more shell commands or scripts to execute
  489. before extracting a backup, run once per configuration file.
  490. example:
  491. - echo "Starting extracting."
  492. after_backup:
  493. seq:
  494. - type: str
  495. desc: |
  496. List of one or more shell commands or scripts to execute
  497. after creating a backup, run once per configuration file.
  498. example:
  499. - echo "Finished a backup."
  500. after_prune:
  501. seq:
  502. - type: str
  503. desc: |
  504. List of one or more shell commands or scripts to execute
  505. after pruning, run once per configuration file.
  506. example:
  507. - echo "Finished pruning."
  508. after_check:
  509. seq:
  510. - type: str
  511. desc: |
  512. List of one or more shell commands or scripts to execute
  513. after consistency checks, run once per configuration file.
  514. example:
  515. - echo "Finished checks."
  516. after_extract:
  517. seq:
  518. - type: str
  519. desc: |
  520. List of one or more shell commands or scripts to execute
  521. after extracting a backup, run once per configuration file.
  522. example:
  523. - echo "Finished extracting."
  524. on_error:
  525. seq:
  526. - type: str
  527. desc: |
  528. List of one or more shell commands or scripts to execute
  529. when an exception occurs during a "prune", "create", or
  530. "check" action or an associated before/after hook.
  531. example:
  532. - echo "Error during prune/create/check."
  533. before_everything:
  534. seq:
  535. - type: str
  536. desc: |
  537. List of one or more shell commands or scripts to execute
  538. before running all actions (if one of them is "create").
  539. These are collected from all configuration files and then
  540. run once before all of them (prior to all actions).
  541. example:
  542. - echo "Starting actions."
  543. after_everything:
  544. seq:
  545. - type: str
  546. desc: |
  547. List of one or more shell commands or scripts to execute
  548. after running all actions (if one of them is "create").
  549. These are collected from all configuration files and then
  550. run once after all of them (after any action).
  551. example:
  552. - echo "Completed actions."
  553. postgresql_databases:
  554. seq:
  555. - map:
  556. name:
  557. required: true
  558. type: str
  559. desc: |
  560. Database name (required if using this hook). Or
  561. "all" to dump all databases on the host. Note
  562. that using this database hook implicitly enables
  563. both read_special and one_file_system (see
  564. above) to support dump and restore streaming.
  565. example: users
  566. hostname:
  567. type: str
  568. desc: |
  569. Database hostname to connect to. Defaults to
  570. connecting via local Unix socket.
  571. example: database.example.org
  572. port:
  573. type: int
  574. desc: Port to connect to. Defaults to 5432.
  575. example: 5433
  576. username:
  577. type: str
  578. desc: |
  579. Username with which to connect to the database.
  580. Defaults to the username of the current user.
  581. You probably want to specify the "postgres"
  582. superuser here when the database name is "all".
  583. example: dbuser
  584. password:
  585. type: str
  586. desc: |
  587. Password with which to connect to the database.
  588. Omitting a password will only work if PostgreSQL
  589. is configured to trust the configured username
  590. without a password, or you create a ~/.pgpass
  591. file.
  592. example: trustsome1
  593. format:
  594. type: str
  595. enum: ['plain', 'custom', 'directory', 'tar']
  596. desc: |
  597. Database dump output format. One of "plain",
  598. "custom", "directory", or "tar". Defaults to
  599. "custom" (unlike raw pg_dump). See pg_dump
  600. documentation for details. Note that format is
  601. ignored when the database name is "all".
  602. example: directory
  603. ssl_mode:
  604. type: str
  605. enum: ['disable', 'allow', 'prefer',
  606. 'require', 'verify-ca', 'verify-full']
  607. desc: |
  608. SSL mode to use to connect to the database
  609. server. One of "disable", "allow", "prefer",
  610. "require", "verify-ca" or "verify-full".
  611. Defaults to "disable".
  612. example: require
  613. ssl_cert:
  614. type: str
  615. desc: |
  616. Path to a client certificate.
  617. example: "/root/.postgresql/postgresql.crt"
  618. ssl_key:
  619. type: str
  620. desc: |
  621. Path to a private client key.
  622. example: "/root/.postgresql/postgresql.key"
  623. ssl_root_cert:
  624. type: str
  625. desc: |
  626. Path to a root certificate containing a list of
  627. trusted certificate authorities.
  628. example: "/root/.postgresql/root.crt"
  629. ssl_crl:
  630. type: str
  631. desc: |
  632. Path to a certificate revocation list.
  633. example: "/root/.postgresql/root.crl"
  634. options:
  635. type: str
  636. desc: |
  637. Additional pg_dump/pg_dumpall options to pass
  638. directly to the dump command, without performing
  639. any validation on them. See pg_dump
  640. documentation for details.
  641. example: --role=someone
  642. desc: |
  643. List of one or more PostgreSQL databases to dump before
  644. creating a backup, run once per configuration file. The
  645. database dumps are added to your source directories at
  646. runtime, backed up, and removed afterwards. Requires
  647. pg_dump/pg_dumpall/pg_restore commands. See
  648. https://www.postgresql.org/docs/current/app-pgdump.html and
  649. https://www.postgresql.org/docs/current/libpq-ssl.html for
  650. details.
  651. mysql_databases:
  652. seq:
  653. - map:
  654. name:
  655. required: true
  656. type: str
  657. desc: |
  658. Database name (required if using this hook). Or
  659. "all" to dump all databases on the host. Note
  660. that using this database hook implicitly enables
  661. both read_special and one_file_system (see
  662. above) to support dump and restore streaming.
  663. example: users
  664. hostname:
  665. type: str
  666. desc: |
  667. Database hostname to connect to. Defaults to
  668. connecting via local Unix socket.
  669. example: database.example.org
  670. port:
  671. type: int
  672. desc: Port to connect to. Defaults to 3306.
  673. example: 3307
  674. username:
  675. type: str
  676. desc: |
  677. Username with which to connect to the database.
  678. Defaults to the username of the current user.
  679. example: dbuser
  680. password:
  681. type: str
  682. desc: |
  683. Password with which to connect to the database.
  684. Omitting a password will only work if MySQL is
  685. configured to trust the configured username
  686. without a password.
  687. example: trustsome1
  688. options:
  689. type: str
  690. desc: |
  691. Additional mysqldump options to pass directly to
  692. the dump command, without performing any
  693. validation on them. See mysqldump documentation
  694. for details.
  695. example: --skip-comments
  696. desc: |
  697. List of one or more MySQL/MariaDB databases to dump before
  698. creating a backup, run once per configuration file. The
  699. database dumps are added to your source directories at
  700. runtime, backed up, and removed afterwards. Requires
  701. mysqldump/mysql commands (from either MySQL or MariaDB). See
  702. https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html or
  703. https://mariadb.com/kb/en/library/mysqldump/ for details.
  704. healthchecks:
  705. type: str
  706. desc: |
  707. Healthchecks ping URL or UUID to notify when a backup
  708. begins, ends, or errors. Create an account at
  709. https://healthchecks.io if you'd like to use this service.
  710. See borgmatic monitoring documentation for details.
  711. example:
  712. https://hc-ping.com/your-uuid-here
  713. cronitor:
  714. type: str
  715. desc: |
  716. Cronitor ping URL to notify when a backup begins, ends, or
  717. errors. Create an account at https://cronitor.io if you'd
  718. like to use this service. See borgmatic monitoring
  719. documentation for details.
  720. example:
  721. https://cronitor.link/d3x0c1
  722. pagerduty:
  723. type: str
  724. desc: |
  725. PagerDuty integration key used to notify PagerDuty when a
  726. backup errors. Create an account at
  727. https://www.pagerduty.com/ if you'd like to use this
  728. service. See borgmatic monitoring documentation for details.
  729. example:
  730. a177cad45bd374409f78906a810a3074
  731. cronhub:
  732. type: str
  733. desc: |
  734. Cronhub ping URL to notify when a backup begins, ends, or
  735. errors. Create an account at https://cronhub.io if you'd
  736. like to use this service. See borgmatic monitoring
  737. documentation for details.
  738. example:
  739. https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d01
  740. umask:
  741. type: scalar
  742. desc: |
  743. Umask used when executing hooks. Defaults to the umask that
  744. borgmatic is run with.
  745. example: 0077