A wrapper script for Borg backup software that creates and prunes backups 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 13KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292
  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: scalar
  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: scalar
  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).
  34. example: true
  35. read_special:
  36. type: bool
  37. desc: |
  38. Use Borg's --read-special flag to allow backup of block and other special
  39. devices. Use with caution, as it will lead to problems if used when
  40. backing up special devices such as /dev/zero.
  41. example: false
  42. bsd_flags:
  43. type: bool
  44. desc: Record bsdflags (e.g. NODUMP, IMMUTABLE) in archive. Defaults to true.
  45. example: true
  46. files_cache:
  47. type: scalar
  48. desc: |
  49. Mode in which to operate the files cache. See
  50. https://borgbackup.readthedocs.io/en/stable/usage/create.html#description for
  51. details.
  52. example: ctime,size,inode
  53. local_path:
  54. type: scalar
  55. desc: Alternate Borg local executable. Defaults to "borg".
  56. example: borg1
  57. remote_path:
  58. type: scalar
  59. desc: Alternate Borg remote executable. Defaults to "borg".
  60. example: borg1
  61. patterns:
  62. seq:
  63. - type: scalar
  64. desc: |
  65. Any paths matching these patterns are included/excluded from backups. Globs are
  66. expanded. (Tildes are not.) Note that Borg considers this option experimental.
  67. See the output of "borg help patterns" for more details. Quote any value if it
  68. contains leading punctuation, so it parses correctly.
  69. example:
  70. - 'R /'
  71. - '- /home/*/.cache'
  72. - '+ /home/susan'
  73. - '- /home/*'
  74. patterns_from:
  75. seq:
  76. - type: scalar
  77. desc: |
  78. Read include/exclude patterns from one or more separate named files, one pattern
  79. per line. Note that Borg considers this option experimental. See the output of
  80. "borg help patterns" for more details.
  81. example:
  82. - /etc/borgmatic/patterns
  83. exclude_patterns:
  84. seq:
  85. - type: scalar
  86. desc: |
  87. Any paths matching these patterns are excluded from backups. Globs and tildes
  88. are expanded. See the output of "borg help patterns" for more details.
  89. example:
  90. - '*.pyc'
  91. - ~/*/.cache
  92. - /etc/ssl
  93. exclude_from:
  94. seq:
  95. - type: scalar
  96. desc: |
  97. Read exclude patterns from one or more separate named files, one pattern per
  98. line. See the output of "borg help patterns" for more details.
  99. example:
  100. - /etc/borgmatic/excludes
  101. exclude_caches:
  102. type: bool
  103. desc: |
  104. Exclude directories that contain a CACHEDIR.TAG file. See
  105. http://www.brynosaurus.com/cachedir/spec.html for details.
  106. example: true
  107. exclude_if_present:
  108. type: scalar
  109. desc: Exclude directories that contain a file with the given filename.
  110. example: .nobackup
  111. storage:
  112. desc: |
  113. Repository storage options. See
  114. https://borgbackup.readthedocs.io/en/stable/usage.html#borg-create and
  115. https://borgbackup.readthedocs.io/en/stable/usage/general.html#environment-variables for
  116. details.
  117. map:
  118. encryption_passcommand:
  119. type: scalar
  120. desc: |
  121. The standard output of this command is used to unlock the encryption key. Only
  122. use on repositories that were initialized with passcommand/repokey encryption.
  123. Note that if both encryption_passcommand and encryption_passphrase are set,
  124. then encryption_passphrase takes precedence.
  125. example: "secret-tool lookup borg-repository repo-name"
  126. encryption_passphrase:
  127. type: scalar
  128. desc: |
  129. Passphrase to unlock the encryption key with. Only use on repositories that were
  130. initialized with passphrase/repokey encryption. Quote the value if it contains
  131. punctuation, so it parses correctly. And backslash any quote or backslash
  132. literals as well.
  133. example: "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"
  134. checkpoint_interval:
  135. type: int
  136. desc: |
  137. Number of seconds between each checkpoint during a long-running backup. See
  138. https://borgbackup.readthedocs.io/en/stable/faq.html#if-a-backup-stops-mid-way-does-the-already-backed-up-data-stay-there
  139. for details. Defaults to checkpoints every 1800 seconds (30 minutes).
  140. example: 1800
  141. chunker_params:
  142. type: scalar
  143. desc: |
  144. Specify the parameters passed to then chunker (CHUNK_MIN_EXP, CHUNK_MAX_EXP,
  145. HASH_MASK_BITS, HASH_WINDOW_SIZE). See https://borgbackup.readthedocs.io/en/stable/internals.html
  146. for details.
  147. example: 19,23,21,4095
  148. compression:
  149. type: scalar
  150. desc: |
  151. Type of compression to use when creating archives. See
  152. https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create for details.
  153. Defaults to no compression.
  154. example: lz4
  155. remote_rate_limit:
  156. type: int
  157. desc: Remote network upload rate limit in kiBytes/second.
  158. example: 100
  159. ssh_command:
  160. type: scalar
  161. desc: Command to use instead of just "ssh". This can be used to specify ssh options.
  162. example: ssh -i /path/to/private/key
  163. umask:
  164. type: scalar
  165. desc: Umask to be used for borg create.
  166. example: 0077
  167. lock_wait:
  168. type: int
  169. desc: Maximum seconds to wait for acquiring a repository/cache lock.
  170. example: 5
  171. archive_name_format:
  172. type: scalar
  173. desc: |
  174. Name of the archive. Borg placeholders can be used. See the output of
  175. "borg help placeholders" for details. Default is
  176. "{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}". If you specify this option, you must
  177. also specify a prefix in the retention section to avoid accidental pruning of
  178. archives with a different archive name format. And you should also specify a
  179. prefix in the consistency section as well.
  180. example: "{hostname}-documents-{now}"
  181. retention:
  182. desc: |
  183. Retention policy for how many backups to keep in each category. See
  184. https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for details.
  185. At least one of the "keep" options is required for pruning to work.
  186. map:
  187. keep_within:
  188. type: scalar
  189. desc: Keep all archives within this time interval.
  190. example: 3H
  191. keep_secondly:
  192. type: int
  193. desc: Number of secondly archives to keep.
  194. example: 60
  195. keep_minutely:
  196. type: int
  197. desc: Number of minutely archives to keep.
  198. example: 60
  199. keep_hourly:
  200. type: int
  201. desc: Number of hourly archives to keep.
  202. example: 24
  203. keep_daily:
  204. type: int
  205. desc: Number of daily archives to keep.
  206. example: 7
  207. keep_weekly:
  208. type: int
  209. desc: Number of weekly archives to keep.
  210. example: 4
  211. keep_monthly:
  212. type: int
  213. desc: Number of monthly archives to keep.
  214. example: 6
  215. keep_yearly:
  216. type: int
  217. desc: Number of yearly archives to keep.
  218. example: 1
  219. prefix:
  220. type: scalar
  221. desc: |
  222. When pruning, only consider archive names starting with this prefix.
  223. Borg placeholders can be used. See the output of "borg help placeholders" for
  224. details. Default is "{hostname}-".
  225. example: sourcehostname
  226. consistency:
  227. desc: |
  228. Consistency checks to run after backups. See
  229. https://borgbackup.readthedocs.org/en/stable/usage.html#borg-check and
  230. https://borgbackup.readthedocs.org/en/stable/usage.html#borg-extract for details.
  231. map:
  232. checks:
  233. seq:
  234. - type: str
  235. enum: ['repository', 'archives', 'extract', 'disabled']
  236. unique: true
  237. desc: |
  238. List of one or more consistency checks to run: "repository", "archives", and/or
  239. "extract". Defaults to "repository" and "archives". Set to "disabled" to disable
  240. all consistency checks. "repository" checks the consistency of the repository,
  241. "archive" checks all of the archives, and "extract" does an extraction dry-run
  242. of just the most recent archive.
  243. example:
  244. - repository
  245. - archives
  246. check_repositories:
  247. seq:
  248. - type: scalar
  249. desc: |
  250. Paths to a subset of the repositories in the location section on which to run
  251. consistency checks. Handy in case some of your repositories are very large, and
  252. so running consistency checks on them would take too long. Defaults to running
  253. consistency checks on all repositories configured in the location section.
  254. example:
  255. - user@backupserver:sourcehostname.borg
  256. check_last:
  257. type: int
  258. desc: Restrict the number of checked archives to the last n. Applies only to the
  259. "archives" check.
  260. example: 3
  261. prefix:
  262. type: scalar
  263. desc: |
  264. When performing the "archives" check, only consider archive names starting with
  265. this prefix. Borg placeholders can be used. See the output of
  266. "borg help placeholders" for details. Default is "{hostname}-".
  267. example: sourcehostname
  268. hooks:
  269. desc: |
  270. Shell commands or scripts to execute before and after a backup or if an error has occurred.
  271. IMPORTANT: All provided commands and scripts are executed with user permissions of borgmatic.
  272. Do not forget to set secure permissions on this file as well as on any script listed (chmod 0700) to
  273. prevent potential shell injection or privilege escalation.
  274. map:
  275. before_backup:
  276. seq:
  277. - type: scalar
  278. desc: List of one or more shell commands or scripts to execute before creating a backup.
  279. example:
  280. - echo "`date` - Starting a backup job."
  281. after_backup:
  282. seq:
  283. - type: scalar
  284. desc: List of one or more shell commands or scripts to execute after creating a backup.
  285. example:
  286. - echo "`date` - Backup created."
  287. on_error:
  288. seq:
  289. - type: scalar
  290. desc: List of one or more shell commands or scripts to execute in case an exception has occurred.
  291. example:
  292. - echo "`date` - Error while creating a backup."