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