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 14KB

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