slantsh/borgmatic
1
0
Fork 0
forked from borgmatic-collective/borgmatic
Code Pull requests Activity

added --files_changed flag

Browse source
This commit is contained in:
slantsh 2026-02-22 12:15:56 +05:30
commit e3779c90ad
141 changed files with 9 additions and 8702 deletions
Download patch file Download diff file Expand all files Collapse all files

9
borgmatic/config/schema.yaml
View file

@ -98,6 +98,15 @@ properties:
label: backupserver
- path: /mnt/backup
label: local
files_changed:
type: string
description: |
Threshold for considering a file as changed. See
https://borgbackup.readthedocs.io/en/stable/usage/create.html for
details. Defaults to "mtime" (i.e., a file is considered
changed if either its mtime has changed since the last
backup).
example: size
working_directory:
type: string
description: |

37
docs/Dockerfile
View file

@ -1,37 +0,0 @@
FROM docker.io/alpine:3.20.1 AS borgmatic
COPY . /app
RUN apk add --no-cache py3-pip py3-ruamel.yaml py3-ruamel.yaml.clib
RUN pip install --break-system-packages --no-cache /app && borgmatic config generate && borgmatic config generate --destination /etc/borgmatic --split && chmod +r /etc/borgmatic/*.yaml
RUN mkdir /command-line \
&& borgmatic --help > /command-line/global.txt \
&& for action in repo-create transfer create prune compact check delete extract config "config bootstrap" "config generate" "config validate" "config show" export-tar mount umount repo-delete restore repo-list list repo-info info break-lock "key export" "key import" "key change-passphrase" recreate borg; do \
borgmatic $action --help > /command-line/${action/ /-}.txt; done
RUN /app/docs/fetch-contributors >> /contributors.html
FROM docker.io/node:22.4.0-alpine AS html
ARG ENVIRONMENT=production
WORKDIR /source
RUN npm install @11ty/eleventy \
@11ty/eleventy-plugin-syntaxhighlight \
@11ty/eleventy-plugin-inclusive-language \
@11ty/eleventy-navigation \
eleventy-plugin-code-clipboard \
markdown-it \
markdown-it-anchor \
markdown-it-replace-link
COPY --from=borgmatic /etc/borgmatic/* /source/docs/_includes/borgmatic/
COPY --from=borgmatic /etc/borgmatic/options.json /source/docs/reference/configuration/index.json
COPY --from=borgmatic /command-line/* /source/docs/_includes/borgmatic/command-line/
COPY --from=borgmatic /contributors.html /source/docs/_includes/borgmatic/contributors.html
COPY . /source
RUN NODE_ENV=${ENVIRONMENT} npx eleventy --input=/source/docs --output=/output
RUN npx -y pagefind --site /output
FROM docker.io/nginx:1.26.1-alpine
COPY --from=html /output /usr/share/nginx/html
COPY --from=borgmatic /etc/borgmatic/config.yaml /usr/share/nginx/html/reference/config.yaml

1
docs/README.md
View file

@ -1 +0,0 @@
../README.md

19
docs/SECURITY.md
View file

@ -1,19 +0,0 @@
---
title: Security policy
permalink: security-policy/index.html
---
## Supported versions
While we want to hear about security vulnerabilities in all versions of
borgmatic, security fixes will only be made to the most recently released
version. It's not practical for our small volunteer effort to maintain
multiple different release branches and put out separate security patches for
each.
## Reporting a vulnerability
If you find a security vulnerability, please [file a
ticket](https://torsion.org/borgmatic/#issues) or [send email
directly](mailto:witten@torsion.org) as appropriate. You should expect to hear
back within a few days at most and generally sooner.

5
docs/_data/borgmatic.js
View file

@ -1,5 +0,0 @@
module.exports = function() {
return {
environment: process.env.NODE_ENV || "development"
};
};

1
docs/_data/layout.json
View file

@ -1 +0,0 @@
"layouts/main.njk"

12
docs/_includes/components/external-links.css
View file

@ -1,12 +0,0 @@
/* External links */
a[href^="http://"]:not(.minilink):not(.elv-externalexempt),
a[href^="https://"]:not(.minilink):not(.elv-externalexempt),
a[href^="//"]:not(.minilink):not(.elv-externalexempt) {
text-decoration-color: inherit;
}
/* External link hovers */
a[href^="http://"]:not(.minilink):not(.elv-externalexempt):hover,
a[href^="https://"]:not(.minilink):not(.elv-externalexempt):hover,
a[href^="//"]:not(.minilink):not(.elv-externalexempt):hover {
text-decoration-color: #00bcd4;
}

34
docs/_includes/components/info-blocks.css
View file

@ -1,34 +0,0 @@
/* Warning */
.elv-info {
line-height: 1.5;
padding: 0.8125em 1em 0.75em; /* 13px 16px 12px /16 */
margin-left: -1rem;
margin-right: -1rem;
margin-bottom: 2em;
background-color: #dff7ff;
}
.elv-info:before {
content: "ℹ️ ";
}
.elv-info-warn {
background-color: #ffa;
}
.elv-info-warn:before {
content: "⚠️ ";
}
.elv-info:first-child {
margin-top: 0;
}
body > .elv-info {
margin-left: 0;
margin-right: 0;
padding: .5rem 1rem;
}
@media (min-width: 37.5em) and (min-height: 25em) { /* 600px / 400px */
body > .elv-info-sticky {
position: sticky;
top: 0;
z-index: 2;
box-shadow: 0 3px 0 0 rgba(0,0,0,.08);
}
}

245
docs/_includes/components/lists.css
View file

@ -1,245 +0,0 @@
/* Buzzwords */
@keyframes rainbow {
0% { background-position: 0% 50%; }
100% { background-position: 100% 50%; }
}
.buzzword-list,
.inlinelist {
padding: 0;
}
.inlinelist:first-child:last-child {
margin: 0;
}
.buzzword,
.buzzword-list li,
.inlinelist .inlinelist-item {
display: inline;
-webkit-box-decoration-break: clone;
box-decoration-break: clone;
font-family: Georgia, serif;
font-size: 116%;
white-space: normal;
line-height: 1.85;
padding: .2em .5em;
margin: 4px 4px 4px 0;
transition: .15s linear outline;
}
.inlinelist .inlinelist-item.active {
background-color: #222;
color: #fff;
font-weight: inherit;
}
.inlinelist .inlinelist-item.active :link,
.inlinelist .inlinelist-item.active :visited {
color: #fff;
}
.inlinelist .inlinelist-item code {
background-color: transparent;
font-size: 80%;
margin-left: 6px;
padding-left: 6px;
display: inline-block;
position: relative;
}
@media (max-width: 26.8125em) { /* 429px */
.inlinelist .inlinelist-item {
overflow: hidden;
}
.inlinelist .inlinelist-item code {
float: right;
line-height: 1.75;
}
}
@media (min-width: 26.875em) { /* 430px */
.inlinelist .inlinelist-item code {
float: none;
}
.inlinelist .inlinelist-item code:before {
content: " ";
border-left: 1px solid rgba(255,255,255,.8);
position: absolute;
left: -2px;
top: -2px;
bottom: 2px;
}
}
a.buzzword {
text-decoration: underline;
}
.buzzword-list a,
.inlinelist a {
text-decoration: none;
}
.inlinelist .inlinelist-item {
font-size: 100%;
line-height: 2;
}
@supports not(-webkit-box-decoration-break: clone) {
.buzzword,
.buzzword-list li,
.inlinelist .inlinelist-item {
display: inline-block;
}
}
.buzzword-list li,
.buzzword {
background-color: #f7f7f7;
}
.inlinelist .inlinelist-item {
background-color: #e9e9e9;
}
.inlinelist .inlinelist-item:hover,
.inlinelist .inlinelist-item:focus,
.buzzword-list li:hover,
.buzzword-list li:focus,
.buzzword:hover,
.buzzword:focus,
.rainbow-active:hover,
.rainbow-active:focus {
position: relative;
background-image: linear-gradient(238deg, #ff0000, #ff8000, #ffff00, #80ff00, #00ff00, #00ff80, #00ffff, #0080ff, #0000ff, #8000ff, #ff0080);
background-size: 1200% 1200%;
background-position: 2% 80%;
color: #fff;
text-shadow: 0 0 2px rgba(0,0,0,.9);
animation: rainbow 4s ease-out alternate infinite;
}
.rainbow-active-noanim {
animation: none !important;
}
.inlinelist .inlinelist-item:hover a,
.inlinelist .inlinelist-item:focus a,
.buzzword-list li:hover a,
.buzzword-list li:focus a,
a.buzzword:hover,
a.buzzword:focus,
a.rainbow-active:hover,
a.rainbow-active:focus {
color: #fff;
text-decoration: none;
}
@media (prefers-reduced-motion: reduce) {
.inlinelist .inlinelist-item:hover,
.inlinelist .inlinelist-item:focus,
.buzzword-list li:hover,
.buzzword-list li:focus,
.buzzword:hover,
.buzzword:focus,
.rainbow-active:hover,
.rainbow-active:focus {
animation: none;
}
}
.buzzword-list li:hover:after,
.buzzword-list li:focus:after,
.buzzword:hover:after,
.buzzword:focus:after {
font-family: system-ui, -apple-system, sans-serif;
content: "Buzzword alert!!!";
position: absolute;
left: 0;
top: 0;
max-width: 8em;
color: #f00;
font-weight: 700;
text-transform: uppercase;
transform: rotate(-10deg) translate(-25%, -125%);
text-shadow: 1px 1px 5px rgba(0,0,0,.6);
line-height: 1.2;
pointer-events: none;
}
main h2 .buzzword,
main h3 .buzzword,
main p .buzzword {
padding: 0px 7px;
font-size: 1em; /* 18px /18 */
margin: 0;
line-height: 1.444444444444; /* 26px /18 */
font-family: inherit;
}
main h2 a.buzzword,
main h3 a.buzzword,
main p a.buzzword {
text-decoration: underline;
}
/* Small viewport */
@media (max-width: 26.8125em) { /* 429px */
.inlinelist .inlinelist-item {
display: block;
width: auto;
padding: 0;
line-height: 1.4;
}
.inlinelist .inlinelist-item > a {
display: block;
padding: .2em .5em;
}
}
@media (min-width: 26.875em) { /* 430px */
.inlinelist .inlinelist-item > a {
display: inline-block;
white-space: nowrap;
}
}
.numberflag {
display: inline-flex;
align-items: center;
justify-content: center;
background-color: #dff7ff;
border-radius: 50%;
width: 1.75em;
height: 1.75em;
font-weight: 600;
}
h1 .numberflag,
h2 .numberflag,
h3 .numberflag,
h4 .numberflag,
h5 .numberflag {
width: 1.25em;
height: 1.25em;
}
h2 .numberflag {
position: relative;
margin-right: 0.25em; /* 10px /40 */
}
h2 .numberflag:after {
content: " ";
position: absolute;
bottom: -1px;
left: 0;
height: 1px;
background-color: #fff;
width: calc(100% + 0.4em); /* 16px /40 */
}
/* Super featured list on home page */
.list-superfeatured .avatar {
width: calc(30px + 5vw);
height: calc(30px + 5vw);
max-width: 60px;
max-height: 60px;
margin-left: 0;
}
@media (max-width: 26.8125em) { /* 429px */
.list-superfeatured .inlinelist-item > a {
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
}
@media (min-width: 26.875em) { /* 430px */
.list-superfeatured .inlinelist-item {
font-size: 110%;
}
}
/* Only top level */
.inlinelist-no-nest ul,
.inlinelist-no-nest ol {
display: none;
}

86
docs/_includes/components/minilink.css
View file

@ -1,86 +0,0 @@
/* Mini link */
.minilink {
display: inline-block;
padding: .125em .375em;
text-transform: uppercase;
font-size: 0.875rem; /* 14px /16 */
text-decoration: none;
background-color: #ddd;
border-radius: 0.1875em; /* 3px /16 */
font-weight: 500;
margin: 0 0.4285714285714em 0.07142857142857em 0; /* 0 6px 1px 0 /14 */
line-height: 1.285714285714; /* 18px /14 */
font-family: system-ui, -apple-system, sans-serif;
}
table .minilink {
margin-top: 6px;
}
.minilink[href] {
box-shadow: 0 1px 1px 0 rgba(0,0,0,.5);
}
.minilink[href]:hover,
.minilink[href]:focus {
background-color: #bbb;
}
pre + .minilink {
color: #fff;
border-radius: 0 0 0.2857142857143em 0.2857142857143em; /* 4px /14 */
float: right;
background-color: #444;
color: #fff;
}
pre[class*=language-] + .minilink {
position: relative;
top: -0.7142857142857em; /* -10px /14 */
}
p.minilink {
float: right;
margin-left: 2em;
margin-bottom: 2em;
}
h1 .minilink,
h2 .minilink,
h3 .minilink,
h4 .minilink {
font-size: 0.9375rem; /* 15px /16 */
vertical-align: middle;
margin-left: 1em;
}
h3 .minilink,
h4 .minilink {
font-size: 0.8125rem; /* 13px /16 */
}
.minilink + pre[class*=language-] {
clear: both;
}
.minilink-addedin {
text-transform: none;
box-shadow: 0 0 0 1px rgba(0,0,0,0.3);
}
.minilink-addedin:not(:first-child) {
margin-left: .5em;
}
.minilink-addedin.minilink-inline {
margin: 0 4px;
background-color: #fff;
}
.minilink-lower {
text-transform: none;
background-color: transparent;
}
.minilink-lower[href] {
box-shadow: 0 0 0 1px rgba(0,0,0,0.5);
}
.minilink-lower[href]:hover,
.minilink-lower[href]:focus {
background-color: #eee;
}
.minilink > .minilink {
margin: -.125em .375em -.125em -.375em;
box-shadow: none;
border-top-right-radius: 0;
border-bottom-right-radius: 0;
}

5
docs/_includes/components/suggestion-link.html
View file

@ -1,5 +0,0 @@
<h2>Improve this documentation</h2>
<p>Have an idea on how to make this documentation even better? Use our <a
href="https://torsion.org/borgmatic/#support-and-contributing">issue
tracker</a> to send your feedback!</p>

137
docs/_includes/components/toc.css
View file

@ -1,137 +0,0 @@
.elv-toc {
font-size: 1rem; /* Reset */
}
.elv-toc details {
--details-force-closed: (max-width: 79.9375em); /* 1023px */
}
.elv-toc details > summary {
font-size: 1.375rem; /* 22px /16 */
margin-bottom: .5em;
}
@media (min-width: 80em) {
.elv-toc {
position: absolute;
left: 3rem;
width: 16rem;
z-index: 1;
}
.elv-toc details > summary {
margin-top: 0;
}
.js .elv-toc details > summary {
display: none;
}
}
.elv-toc-list {
display: flex;
flex-wrap: wrap;
justify-content: space-between;
padding-left: 0;
padding-right: 0;
margin: 0 0 2.5em;
list-style: none;
}
.elv-toc-list li {
font-size: 0.9375em; /* 15px /16 */
line-height: 1.466666666667; /* 22px /15 */
}
/* Nested lists */
.elv-toc-list ul {
padding: 0 0 .75em 0;
margin: 0;
list-style: none;
}
/* Menus nested 2 or more deep */
.elv-toc-list ul ul {
padding-bottom: 0;
padding-left: 0.625rem; /* 10px /16 */
}
/* Display inline menus 4 or more deep */
.elv-toc-list ul ul ul > li {
display: inline-block;
}
.elv-toc-list ul ul ul > li::before {
content: "•";
margin-left: 0.4em;
margin-right: -0.2em;
}
.elv-toc-list ul ul ul > li > a {
display: inline-block;
}
/* List items */
.elv-toc summary,
.elv-toc-list a {
padding: .15em .25em;
}
.elv-toc-list a {
display: block;
}
.elv-toc-list a:not(:hover) {
text-decoration: none;
}
.elv-toc-list li {
margin: 0;
padding: 0;
}
.elv-toc-list > li {
flex-grow: 1;
flex-basis: 14.375rem; /* 230px /16 */
}
/* Top level links */
.elv-toc-list > li > a {
color: #222;
font-weight: 600;
border-bottom: 1px solid #ddd;
margin-bottom: 0.25em; /* 4px /16 */
}
/* Active links */
.elv-toc-list li.elv-toc-active > a {
background-color: #dff7ff;
}
.elv-toc-list ul .elv-toc-active > a:after {
content: "";
}
/* Show only active nested lists */
.elv-toc-list ul.elv-toc-active,
.elv-toc-list li.elv-toc-active > ul {
display: block;
}
/* Footer category navigation */
.elv-cat-list-active {
font-weight: 600;
}
.breadcrumb-item.active {
color: var(--primary-color);
}
#breadcrumb ol,
#breadcrumb ul {
margin: 0;
padding: 0 0 1em;
}
#breadcrumb li {
display: inline;
}
#breadcrumb li:not(:last-child)::after {
content: " ˃"
}
#breadcrumb a:not(:hover) {
text-decoration: none;
}
#breadcrumb a {
text-decoration-color: #00bcd4;
}

13
docs/_includes/header.njk
View file

@ -1,13 +0,0 @@
<header class="elv-layout elv-layout-full elv-header{% if headerClass %} {{ headerClass }}{% endif %}">
{% if page.url != '/' %}<h3><a href="https://torsion.org/borgmatic/">borgmatic</a></h3>{% endif %}
<div class="container" id="breadcrumb">
{% set breadcrumb = collections.all | eleventyNavigationBreadcrumb(eleventyNavigation.key, {allowMissing: true}) %}
{# The replace() is a work-around for https://github.com/11ty/eleventy-navigation/issues/56 #}
{{ breadcrumb | eleventyNavigationToHtml | replace('href="/reference/', 'href="/borgmatic/reference/') | safe }}
<div data-pagefind-meta="title" aria-hidden="true" style="display: none">
{% for entry in breadcrumb %}{{ entry.title }} > {% endfor %}{{ title | safe }}
</div>
</div>
<h1 class="elv-hed">{{ title | safe }}</h1>
{% if page.url == '/' %}<h3>It's your data. Keep it that way.</h3>{% endif %}
</header>

562
docs/_includes/index.css
View file

File diff suppressed because one or more lines are too long

32
docs/_includes/layouts/base.njk
View file

@ -1,32 +0,0 @@
<!doctype html>
<html lang="en"{% if templateClass %} class="{{ templateClass }}"{% endif %}>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="{{ eleventy.generator }}">
<link rel="icon" href="https://torsion.org/borgmatic/static/borgmatic.png" type="image/x-icon">
{% if page.url == '/' %}
<title>borgmatic</title>
{% else %}
<title>borgmatic{% if subtitle or title %} - {% endif %}{{ subtitle + ' - ' if subtitle}}{{ title }}</title>
{% endif %}
{%- set css %}
{% include 'index.css' %}
{% include 'components/lists.css' %}
{% include 'components/external-links.css' %}
{% include 'components/minilink.css' %}
{% include 'components/toc.css' %}
{% include 'components/info-blocks.css' %}
{% include 'prism-theme.css' %}
{% endset %}
<style>{{ css | safe }}</style>
{% if feedTitle and feedUrl %}
<link rel="alternate" href="{{ feedUrl }}" title="{{ feedTitle }}" type="application/atom+xml">
{% endif %}
</head>
<body>
{{ content | safe }}
{% initClipboardJS %}
</body>
</html>

44
docs/_includes/layouts/main.njk
View file

@ -1,44 +0,0 @@
---
layout: layouts/base.njk
templateClass: elv-default
headerClass: elv-header-default
---
{% include "header.njk" %}
<main class="elv-layout{% if layoutClass %} {{ layoutClass }}{% endif %}">
<div id="documentation" class="elv-toc">
{% if page.url != '/search/' %}
<div id="search-entrance">
🔍
<form action="/borgmatic/search/">
<label>
<input type="search" name="query" placeholder="Search">
</label>
</form>
</div>
{% endif %}
<div>
{% set navPages = collections.all | eleventyNavigation %}
{% macro renderNavListItem(entry) -%}
<li{% if entry.url == page.url %} class="elv-toc-active"{% endif %}>
<a {% if entry.url %}href="{% if borgmatic.environment == "production" %}https://torsion.org/borgmatic{% else %}http://localhost:8080/borgmatic{% endif %}{{ entry.url | url }}"{% endif %}>{{ entry.title }}</a>
{%- if entry.children.length -%}
<ul>
{%- for child in entry.children %}{{ renderNavListItem(child) }}{% endfor -%}
</ul>
{%- endif -%}
</li>
{%- endmacro %}
<ul class="elv-toc-list">
{%- for entry in navPages %}{{ renderNavListItem(entry) }}{%- endfor -%}
</ul>
</div>
</div>
<div data-pagefind-body>
{{ content | safe }}
</div>
{% include 'components/suggestion-link.html' %}
</main>

177
docs/_includes/prism-theme.css
View file

@ -1,177 +0,0 @@
/**
* prism.js default theme for JavaScript, CSS and HTML
* Based on dabblet (http://dabblet.com)
* @author Lea Verou
*/
/*
* Modified with an approximation of the One Light syntax highlighting theme.
*/
code[class*="language-"],
pre[class*="language-"] {
color: #494b53;
background: none;
font-family: Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace;
text-align: left;
white-space: pre;
word-spacing: normal;
word-break: normal;
word-wrap: normal;
line-height: 1.5;
-moz-tab-size: 4;
-o-tab-size: 4;
tab-size: 4;
-webkit-hyphens: none;
-moz-hyphens: none;
-ms-hyphens: none;
hyphens: none;
}
pre[class*="language-"]::-moz-selection, pre[class*="language-"] ::-moz-selection,
code[class*="language-"]::-moz-selection, code[class*="language-"] ::-moz-selection {
text-shadow: none;
color: #232324;
background: #dbdbdc;
}
pre[class*="language-"]::selection, pre[class*="language-"] ::selection,
code[class*="language-"]::selection, code[class*="language-"] ::selection {
text-shadow: none;
color: #232324;
background: #dbdbdc;
}
@media print {
code[class*="language-"],
pre[class*="language-"] {
text-shadow: none;
}
}
/* Code blocks */
pre[class*="language-"] {
padding: 1em;
margin: .5em 0;
overflow: auto;
}
:not(pre) > code[class*="language-"],
pre[class*="language-"] {
background: #fafafa;
}
/* Inline code */
:not(pre) > code[class*="language-"] {
padding: .1em;
border-radius: .3em;
white-space: normal;
}
.token.comment,
.token.prolog,
.token.doctype,
.token.cdata {
color: #505157;
}
.token.punctuation {
color: #526fff;
}
.token.selector,
.token.tag {
color: none;
}
.token.property,
.token.boolean,
.token.number,
.token.constant,
.token.symbol,
.token.attr-name,
.token.deleted {
color: #986801;
}
.token.string,
.token.char,
.token.attr-value,
.token.builtin,
.token.inserted {
color: #50a14f;
}
.token.operator,
.token.entity,
.token.url,
.language-css .token.string,
.style .token.string {
color: #526fff;
}
.token.atrule,
.token.keyword {
color: #e45649;
}
.token.function {
color: #4078f2;
}
.token.regex,
.token.important,
.token.variable {
color: #e45649;
}
.token.important,
.token.bold {
font-weight: bold;
}
.token.italic {
font-style: italic;
}
.token.entity {
cursor: help;
}
pre.line-numbers {
position: relative;
padding-left: 3.8em;
counter-reset: linenumber;
}
pre.line-numbers > code {
position: relative;
}
.line-numbers .line-numbers-rows {
position: absolute;
pointer-events: none;
top: 0;
font-size: 100%;
left: -3.8em;
width: 3em; /* works for line-numbers below 1000 lines */
letter-spacing: -1px;
border-right: 0;
-webkit-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
}
.line-numbers-rows > span {
pointer-events: none;
display: block;
counter-increment: linenumber;
}
.line-numbers-rows > span:before {
content: counter(linenumber);
color: #5C6370;
display: block;
padding-right: 0.8em;
text-align: right;
}

5
docs/_includes/snippet/command-line/sample.md
View file

@ -1,5 +0,0 @@
Here's the command-line help for this action in the [most recent version of
borgmatic](https://projects.torsion.org/borgmatic-collective/borgmatic/releases).
If you're using an older version, some of these flags may not work, and you
should instead run the action with `--help` to see the flags specific to your
borgmatic version.

6
docs/_includes/snippet/configuration/sample.md
View file

@ -1,6 +0,0 @@
Here's an example configuration with all of the available options for this
feature in the [most recent version of
borgmatic](https://projects.torsion.org/borgmatic-collective/borgmatic/releases).
If you're using an older version, some of these options may not work, and you
should instead [generate a sample configuration file specific to your borgmatic
version](https://torsion.org/borgmatic/how-to/set-up-backups/#configuration).

49
docs/docker-compose.yaml
View file

@ -1,49 +0,0 @@
services:
traefik:
image: public.ecr.aws/docker/library/traefik:3.5.3
container_name: borgmatic-docs-traefik
command:
- "--global.checkNewVersion=false"
- "--global.sendAnonymousUsage=false"
- "--entrypoints.web.address=:8080"
- "--accesslog"
- "--accesslog.fields.headers.defaultmode=keep"
- "--providers.docker"
- "--providers.docker.exposedbydefault=false"
- "--api.insecure=false"
- "--api.dashboard=false"
- "--log.level=WARN"
ports:
- "127.0.0.1:8080:8080"
volumes:
- ${CONTAINER_SOCKET_PATH:-/run/user/docker.sock}:/var/run/docker.sock:ro
docs:
image: borgmatic-docs
container_name: borgmatic-docs
labels:
- "traefik.enable=true"
- "traefik.http.routers.borgmatic-docs.rule=PathPrefix(`/borgmatic`)"
- "traefik.http.routers.borgmatic-docs.middlewares=borgmatic-trailing-slash-redirectregex,borgmatic-docs-redirectregex,borgmatic-stripprefix"
- "traefik.http.middlewares.borgmatic-trailing-slash-redirectregex.redirectregex.regex=^(.*)/borgmatic$$"
- "traefik.http.middlewares.borgmatic-trailing-slash-redirectregex.redirectregex.replacement=$${1}/borgmatic/"
- "traefik.http.middlewares.borgmatic-trailing-slash-redirectregex.redirectregex.permanent=true"
- "traefik.http.middlewares.borgmatic-docs-redirectregex.redirectregex.regex=^(.*)/borgmatic/docs/(.*)$$"
- "traefik.http.middlewares.borgmatic-docs-redirectregex.redirectregex.replacement=$${1}/borgmatic/$${2}"
- "traefik.http.middlewares.borgmatic-docs-redirectregex.redirectregex.permanent=true"
- "traefik.http.middlewares.borgmatic-stripprefix.stripprefix.prefixes=/borgmatic"
- "traefik.http.routers.borgmatic-docs.entrypoints=web"
build:
dockerfile: docs/Dockerfile
context: ..
args:
ENVIRONMENT: development
message:
image: alpine
container_name: borgmatic-docs-message
command:
- sh
- -c
- |
echo; echo "You can view dev docs at http://localhost:8080/borgmatic/"; echo
depends_on:
- docs

82
docs/fetch-contributors
View file

@ -1,82 +0,0 @@
#!/usr/bin/python
'''
A script to fetch recent contributors to borgmatic, used during documentation generation.
'''
import datetime
import itertools
import operator
import subprocess
import requests
def list_merged_pulls(url):
'''
Given a Gitea or GitHub API endpoint URL for pull requests, fetch and return the corresponding
JSON for all such merged pull requests.
'''
response = requests.get(f'{url}?state=closed', headers={'Accept': 'application/json', 'Content-Type': 'application/json'})
if not response.ok:
response.raise_for_status()
return tuple(pull for pull in response.json() if pull.get('merged_at'))
def list_contributing_issues(url):
response = requests.get(url, headers={'Accept': 'application/json', 'Content-Type': 'application/json'})
if not response.ok:
response.raise_for_status()
return tuple(response.json())
PULLS_API_ENDPOINT_URLS = (
'https://projects.torsion.org/api/v1/repos/borgmatic-collective/borgmatic/pulls',
)
ISSUES_API_ENDPOINT_URL = 'https://projects.torsion.org/api/v1/repos/borgmatic-collective/borgmatic/issues?state=all'
RECENT_CONTRIBUTORS_CUTOFF_DAYS = 365
def get_item_timestamp(item):
return item.get('merged_at') or item.get('created_at')
def print_contributors():
'''
Display the recent contributors as a row of avatars in an HTML fragment.
'''
pulls = tuple(itertools.chain.from_iterable(list_merged_pulls(url) for url in PULLS_API_ENDPOINT_URLS))
issues = list_contributing_issues(ISSUES_API_ENDPOINT_URL)
seen_user_ids = set()
print('<p>')
for item in sorted(pulls + issues, key=get_item_timestamp, reverse=True):
timestamp = get_item_timestamp(item)
user = item.get('user')
if not timestamp or not user:
continue
user_id = user.get('id')
if not user_id or user_id in seen_user_ids:
continue
if datetime.datetime.fromisoformat(timestamp) < datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=RECENT_CONTRIBUTORS_CUTOFF_DAYS):
continue
seen_user_ids.add(user_id)
print(
f'''<a href="{user.get('html_url')}?tab=activity"><img src="{user.get('avatar_url')}" width="50" height="50" title="{user.get('full_name') or user.get('login')}" /></a>'''
)
print('</p>')
if __name__ == '__main__':
print_contributors()

202
docs/how-to/add-preparation-and-cleanup-steps-to-backups.md
View file

@ -1,202 +0,0 @@
---
title: 🧹 How to add preparation and cleanup steps to backups
eleventyNavigation:
key: 🧹 Add preparation and cleanup steps
parent: How-to guides
order: 10
---
If you find yourself performing preparation tasks before your backup runs or
doing cleanup work afterwards, borgmatic command hooks may be of interest. These
are custom shell commands you can configure borgmatic to execute at various
points as it runs.
(But if you're looking to backup a database, it's probably easier to use the
[database backup
feature](https://torsion.org/borgmatic/how-to/backup-your-databases/)
instead.)
<span class="minilink minilink-addedin">New in version 2.0.0</span> Command
hooks are now configured via a list of `commands:` in your borgmatic
configuration file. For example:
```yaml
commands:
- before: action
when: [create]
run:
- echo "Before create!"
- after: action
when:
- create
- prune
run:
- echo "After create or prune!"
- after: error
run:
- echo "Something went wrong!"
```
If you're coming from an older version of borgmatic, there is tooling to help
you [upgrade your
configuration](https://torsion.org/borgmatic/how-to/upgrade/#upgrading-your-configuration)
to this new command hook format.
Note that if a `run:` command contains a special YAML character such as a colon,
you may need to quote the entire string (or use a [multiline
string](https://yaml-multiline.info/)) to avoid an error:
```yaml
commands:
- before: action
when: [create]
run:
- "echo Backup: start"
```
By default, an `after` command hook runs even if an error occurs in the
corresponding `before` hook or between those two hooks. This allows you to
perform cleanup steps that correspond to `before` preparation commands—even when
something goes wrong. You may notice that this is a departure from the way that
the deprecated `after_*` hooks worked in borgmatic prior to version 2.0.0.
<span class="minilink minilink-addedin">New in version 2.0.3</span> You can
customize this behavior with the `states` option. For instance, here's an
example of an `after` hook that only triggers on success and not on error:
```yaml
commands:
- after: action
when: [create]
states: [finish]
run:
- echo "After successful create!"
```
See the [command hooks
documentation](https://torsion.org/borgmatic/reference/configuration/command-hooks/)
for additional details about how to configure command hooks.
### Deprecated command hooks
<span class="minilink minilink-addedin">Prior to version 2.0.0</span> The
command hooks worked a little differently. In these older versions of borgmatic,
you can specify `before_backup` hooks to perform preparation steps before
running backups and specify `after_backup` hooks to perform cleanup steps
afterwards. These deprecated command hooks still work in version 2.0.0+,
although see below about a few semantic differences starting in that version.
Here's an example of these deprecated hooks:
```yaml
before_backup:
- mount /some/filesystem
after_backup:
- umount /some/filesystem
```
If your command contains a special YAML character such as a colon, you may
need to quote the entire string (or use a [multiline
string](https://yaml-multiline.info/)) to avoid an error:
```yaml
before_backup:
- "echo Backup: start"
```
There are additional hooks that run before/after other actions as well. For
instance, `before_prune` runs before a `prune` action for a repository, while
`after_prune` runs after it.
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
these options in the `hooks:` section of your configuration.
<span class="minilink minilink-addedin">New in version 2.0.0</span> An `after_*`
command hook runs even if an error occurs in the corresponding `before_*` hook
or between those two hooks. This allows you to perform cleanup steps that
correspond to `before_*` preparation commands—even when something goes wrong.
<span class="minilink minilink-addedin">New in version 2.0.0</span> When command
hooks run, they respect the `working_directory` option if it is configured,
meaning that the hook commands are run in that directory.
<span class="minilink minilink-addedin">New in version 1.7.0</span> The
`before_actions` and `after_actions` hooks run before/after all the actions
(like `create`, `prune`, etc.) for each repository. These hooks are a good
place to run per-repository steps like mounting/unmounting a remote
filesystem.
<span class="minilink minilink-addedin">New in version 1.6.0</span> The
`before_backup` and `after_backup` hooks each run once per repository in a
configuration file. `before_backup` hooks runs right before the `create`
action for a particular repository, and `after_backup` hooks run afterwards,
but not if an error occurs in a previous hook or in the backups themselves.
(Prior to borgmatic 1.6.0, these hooks instead ran once per configuration file
rather than once per repository.)
You can also use `before_everything` and `after_everything` hooks to perform
global setup or cleanup:
```yaml
before_everything:
- set-up-stuff-globally
after_everything:
- clean-up-stuff-globally
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
these options in the `hooks:` section of your configuration.
`before_everything` hooks collected from all borgmatic configuration files run
once before all configuration files (prior to all actions), but only if there
is a `create` action. An error encountered during a `before_everything` hook
causes borgmatic to exit without creating backups.
`after_everything` hooks run once after all configuration files and actions,
but only if there is a `create` action. It runs even if an error occurs during
a backup or a backup hook, but not if an error occurs during a
`before_everything` hook.
`on_error` hooks run when an error occurs, but only if there is a `create`,
`prune`, `compact`, or `check` action. For instance, borgmatic can run
configurable shell commands to fire off custom error notifications or take other
actions, so you can get alerted as soon as something goes wrong. Here's a
not-so-useful example:
```yaml
on_error:
- echo "Error while creating a backup or running a backup hook."
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
this option in the `hooks:` section of your configuration.
The `on_error` hook supports interpolating particular runtime variables into
the hook command. Here's an example that assumes you provide a separate shell
script to handle the alerting:
```yaml
on_error:
- send-text-message.sh
```
borgmatic does not run `on_error` hooks if an error occurs within a
`before_everything` or `after_everything` hook.
## Hook output
Any output produced by your hooks shows up both at the console and in syslog
(when enabled). For more information, see the <a
href="https://torsion.org/borgmatic/reference/command-line/logging/">logging
documentation</a>.
## Security
An important security note about hooks: borgmatic executes all hook commands
with the user permissions of borgmatic itself. So to prevent potential shell
injection or privilege escalation, do not forget to set secure permissions
on borgmatic configuration files (`chmod 0600`) and scripts (`chmod 0700`)
invoked by hooks.

122
docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md
View file

@ -1,122 +0,0 @@
---
title: 💾 How to backup to a removable drive or an intermittent server
eleventyNavigation:
key: 💾 Backup to a removable drive/server
parent: How-to guides
order: 11
---
A common situation is backing up to a repository that's only sometimes online.
For instance, you might send most of your backups to the cloud, but
occasionally you want to plug in an external hard drive or backup to your
buddy's sometimes-online server for that extra level of redundancy.
But if you run borgmatic and your hard drive isn't plugged in, or your buddy's
server is offline, then you'll get an annoying error message and the overall
borgmatic run will fail (even if individual repositories still complete).
Another variant is when the source machine is only sometimes available for
backups, e.g. a laptop where you want to skip backups when the battery falls
below a certain level.
So what if you want borgmatic to swallow the error of a missing drive
or an offline server or a low battery—and exit gracefully? That's where the
concept of "soft failure" come in.
<a id="caveats-and-details"></a>
## Soft failure command hooks
This feature leverages [borgmatic command
hooks](https://torsion.org/borgmatic/how-to/add-preparation-and-cleanup-steps-to-backups/),
so familiarize yourself with them first. The idea is that you write a simple
test in the form of a borgmatic command hook to see if backups should proceed or
not.
The way the test works is that if any of your hook commands return a special
exit status of 75, that indicates to borgmatic that it's a temporary failure
and borgmatic should skip all subsequent actions for the current repository.
If you return any status besides 75, then it's a standard success or error.
(Zero is success; anything else other than 75 is an error).
So for instance, if you have an external drive that's only sometimes mounted,
declare its repository in its own [separate configuration
file](https://torsion.org/borgmatic/how-to/make-per-application-backups/),
say at `/etc/borgmatic.d/removable.yaml`:
```yaml
source_directories:
- /home
repositories:
- path: /mnt/removable/backup.borg
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
these options in the `location:` section of your configuration.
<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
the `path:` portion of the `repositories` list.
Then, make a command hook in that same configuration file that uses the external
`findmnt` utility to see whether the drive is mounted before proceeding.
```yaml
commands:
- before: repository
run:
- findmnt /mnt/removable > /dev/null || exit 75
```
<span class="minilink minilink-addedin">Prior to version 2.0.0</span> Use the
deprecated `before_actions` hook instead:
```yaml
before_actions:
- findmnt /mnt/removable > /dev/null || exit 75
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put this
option in the `hooks:` section of your configuration.
<span class="minilink minilink-addedin">Prior to version 1.7.0</span> Use
`before_backup` or similar instead of `before_actions`, which was introduced in
borgmatic 1.7.0.
What this does is check if the `findmnt` command errors when probing for a
particular mount point. If it does error, then it returns exit code 75 to
borgmatic. borgmatic logs the soft failure, skips all further actions for the
current repository, and proceeds onward to any other repositories and/or
configuration files you may have.
You can imagine a similar check for the sometimes-online server case:
```yaml
source_directories:
- /home
repositories:
- path: ssh://me@buddys-server.org/./backup.borg
commands:
- before: repository
run:
- ping -q -c 1 buddys-server.org > /dev/null || exit 75
```
Or to only run backups if the battery level is high enough:
```yaml
commands:
- before: repository
run:
- is_battery_percent_at_least.sh 25
```
Writing the battery script is left as an exercise to the reader.
See the [soft failure
documentation](https://torsion.org/borgmatic/reference/configuration/command-hooks/#soft-failure)
for additional details.

683
docs/how-to/backup-your-databases.md
View file

@ -1,683 +0,0 @@
---
title: 🗄️ How to backup your databases
eleventyNavigation:
key: 🗄️ Backup your databases
parent: How-to guides
order: 8
---
If you want to backup a database, it's best practice with most database
systems to backup an exported database dump, rather than backing up your
database's internal file storage. That's because the internal storage can
change while you're reading from it. In contrast, a database dump creates a
consistent snapshot that is more suited for backups.
Fortunately, borgmatic includes built-in support for creating database dumps
prior to running backups. For example, here is everything you need to dump and
backup a couple of local PostgreSQL databases and a MySQL database.
```yaml
postgresql_databases:
- name: users
- name: orders
mysql_databases:
- name: posts
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
these and other database options in the `hooks:` section of your
configuration.
As part of each backup, borgmatic streams a database dump for each configured
database directly to Borg, so it's included in the backup without consuming
additional disk space. (The exceptions are the PostgreSQL/MongoDB `directory`
dump formats, which can't stream and therefore do consume temporary disk
space. Additionally, prior to borgmatic 1.5.3, all database dumps consumed
temporary disk space.)
Also note that using a database hook implicitly enables the `read_special`
configuration option (even if it's disabled in your configuration) to support
this dump and restore streaming. See Limitations below for more on this.
Here's a more involved example that connects to remote databases:
```yaml
postgresql_databases:
- name: users
label: database_server1
hostname: database1.example.org
- name: orders
label: database_server2
hostname: database2.example.org
port: 5433
username: postgres
password: trustsome1
format: tar
options: "--role=someone"
mariadb_databases:
- name: photos
hostname: database3.example.org
port: 3307
username: root
password: trustsome1
options: "--skip-comments"
mysql_databases:
- name: posts
hostname: database4.example.org
port: 3307
username: root
password: trustsome1
options: "--skip-comments"
mongodb_databases:
- name: messages
hostname: database5.example.org
port: 27018
username: dbuser
password: trustsome1
authentication_database: mongousers
options: "--ssl"
sqlite_databases:
- name: mydb
path: /var/lib/sqlite3/mydb.sqlite
```
See the [data sources
documentation](https://torsion.org/borgmatic/reference/configuration/data-sources/)
for details on additional options, including customizing the flags passed to
database commands when listing databases, restoring databases, etc.
<a id="runtime-directory"></a>
To support streaming database dumps to Borg, borgmatic uses a runtime directory
for temporary file storage. See the [runtime directory
documentation](https://torsion.org/borgmatic/reference/configuration/runtime-directory/)
for details.
### All databases
If you want to dump all databases on a host, use `all` for the database name:
```yaml
postgresql_databases:
- name: all
mariadb_databases:
- name: all
mysql_databases:
- name: all
mongodb_databases:
- name: all
```
Note that you may need to use a `username` of the `postgres` superuser for
this to work with PostgreSQL.
The SQLite hook in particular does not consider "all" a special database name.
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
these options in the `hooks:` section of your configuration.
<span class="minilink minilink-addedin">New in version 1.7.6</span> With
PostgreSQL, MariaDB, and MySQL, you can optionally dump "all" databases to
separate files instead of one combined dump file, allowing more convenient
restores of individual databases. Enable this by specifying your desired
database dump `format`:
```yaml
postgresql_databases:
- name: all
format: custom
mariadb_databases:
- name: all
format: sql
mysql_databases:
- name: all
format: sql
```
### Database containers
If your database server is running within a container and borgmatic is too, no
problem—configure borgmatic to connect to the container's name on its exposed
port. For instance:
```yaml
postgresql_databases:
- name: users
hostname: your-database-server-container-name
port: 5433
username: postgres
password: trustsome1
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
these options in the `hooks:` section of your configuration.
#### Database client on the host
But what if borgmatic is running on the host?
<span class="minilink minilink-addedin">New in version 2.0.8</span> You can
connect to the database container by specifying its container name or ID:
```yaml
postgresql_databases:
- name: users
container: your-database-server-container-name
port: 5433
username: postgres
password: trustsome1
```
borgmatic uses the `docker` or `podman` command to figure out the container IP
to connect to. But `container:` doesn't work when borgmatic itself is running in
a container—unless the `docker` or `podman` command works inside that container.
But you can always use `hostname:` as described above.
<span class="minilink minilink-addedin">Prior to version 2.0.8</span> If you're
running an older version of borgmatic on the host, you can publish your database
container ports to the host (e.g. via `docker run --publish` or Compose's
`ports`)—and then configure borgmatic to connect to `localhost` and the
published port.
#### Database client in a running container
Normally, borgmatic dumps a database by running a database dump command (e.g.
`pg_dump`) on the host or wherever borgmatic is running, and this command
connects to your containerized database via the given `hostname` and `port`. But
if you don't have any database dump commands installed on your host and you'd
rather use the commands inside your running database container itself, borgmatic
supports that too. For that, configure borgmatic to `exec` into your container
to run the dump command.
For instance, if using Docker and PostgreSQL, something like this might work:
```yaml
postgresql_databases:
- name: users
hostname: 127.0.0.1
port: 5433
username: postgres
password: trustsome1
pg_dump_command: docker exec my_pg_container pg_dump
```
... where `my_pg_container` is the name of your running database container.
Running `pg_dump` this way takes advantage of the localhost "trust"
authentication within that container. In this example, you'd also need to set
the `pg_restore_command` and `psql_command` options.
If you choose to use the `pg_dump` command within the container, and you're
using the `directory` format in particular, you'll also need to mount the
[runtime
directory](https://torsion.org/borgmatic/reference/configuration/runtime-directory/)
from your host into the container at the same path. Otherwise, the `directory`
format dump will remain locked away inside the database container where Borg
can't read it.
For example, with Docker Compose and a runtime directory located at
`/run/user/1000`:
```yaml
services:
db:
image: postgres
volumes:
- /run/user/1000:/run/user/1000
```
And here's an example of using a MariaDB database client within a running Docker
container:
```yaml
mariadb_databases:
- name: users
hostname: 127.0.0.1
username: example
password: trustsome1
password_transport: environment
mariadb_dump_command: docker exec --env MYSQL_PWD my_mariadb_container mariadb-dump
```
The `password_transport: environment` option tells borgmatic to transmit the
password via environment variable instead of the default behavior of using an
anonymous pipe. The environment variable transport is potentially less secure
than the pipe, but it's necessary when the database client is running in a
container separate from borgmatic.
A similar approach can work with MySQL, using `mysql_dump_command` instead of
`mariadb_dump_command` to run `mysqldump` in a container.
Note: With MariaDB and MySQL, use `options`, `list_options`, and/or
`restore_options` to override command-line flags rather than putting flags into
`mariadb_dump_command`, `mysql_dump_command`, etc.
#### Database client in a temporary container
Another variation: If you're running borgmatic on the host but want to spin up a
temporary `pg_dump` container whenever borgmatic dumps a database, for
instance to make use of a `pg_dump` version not present on the host, try
something like this:
```yaml
postgresql_databases:
- name: users
hostname: your-database-hostname
username: postgres
password: trustsome1
pg_dump_command: docker run --rm --env PGPASSWORD postgres:17-alpine pg_dump
```
The `--env PGPASSWORD` is necessary here for borgmatic to provide your database
password to the temporary `pg_dump` container.
Similar command override options are available for (some of) the other
supported database types as well. See the [configuration
reference](https://torsion.org/borgmatic/reference/configuration/) for
details.
### No source directories
<span class="minilink minilink-addedin">New in version 1.7.1</span> If you
would like to backup databases only and not source directories, you can omit
`source_directories` entirely.
<span class="minilink minilink-addedin">Prior to version 1.7.1</span> In older
versions of borgmatic, instead specify an empty `source_directories` value, as
it is a mandatory option there:
```yaml
location:
source_directories: []
hooks:
mysql_databases:
- name: all
```
### External passwords
If you don't want to keep your database passwords in your borgmatic
configuration file, you can instead pass them in from [external credential
sources](https://torsion.org/borgmatic/reference/configuration/credentials/) or
[environment
variables](https://torsion.org/borgmatic/reference/configuration/environment-variables/).
### Configuration backups
An important note about this database configuration: You'll need the
configuration to be present in order for borgmatic to restore a database. So
to prepare for this situation, it's a good idea to include borgmatic's own
configuration files as part of your regular backups. That way, you can always
bring back any missing configuration files in order to restore a database.
<span class="minilink minilink-addedin">New in version 1.7.15</span> borgmatic
automatically includes configuration files in your backup. See [the
documentation on the `config bootstrap`
action](https://torsion.org/borgmatic/how-to/extract-a-backup/#extract-the-configuration-files-used-to-create-an-archive)
for more information.
## Supported databases
borgmatic directly supports [several database
systems](https://torsion.org/borgmatic/reference/configuration/data-sources/).
But if you're looking to backup an unsupported databases system, you can use
general-purpose [preparation and cleanup
hooks](https://torsion.org/borgmatic/how-to/add-preparation-and-cleanup-steps-to-backups/)
as a work-around. These hooks allows you to trigger arbitrary commands or
scripts before and after backups to create and cleanup database dumps for any
database system.
Also, please [file a ticket](https://torsion.org/borgmatic/#issues) for
additional database systems that you'd like borgmatic to officially support.
## Database restoration
When you want to replace an existing database with its backed-up contents, you
can restore it with borgmatic. Note that the database must already exist;
borgmatic does not currently create a database upon restore.
To restore a database dump from an archive, use the `borgmatic restore`
action. But the first step is to figure out which archive to restore from. A
good way to do that is to use the `repo-list` action:
```bash
borgmatic repo-list
```
(No borgmatic `repo-list` action? Try `rlist` or `list` instead or upgrade
borgmatic!)
That should yield output looking something like:
```text
host-2023-01-01T04:05:06.070809 Tue, 2023-01-01 04:05:06 [...]
host-2023-01-02T04:06:07.080910 Wed, 2023-01-02 04:06:07 [...]
```
Assuming that you want to restore all database dumps from the archive with the
most up-to-date files and therefore the latest timestamp, run a command like:
```bash
borgmatic restore --archive host-2023-01-02T04:06:07.080910
```
Or you can simplify this to:
```bash
borgmatic restore --archive latest
```
The `--archive` value is the name of the archive or archive hash to restore
from. This restores all databases dumps that borgmatic originally backed up to
that archive.
This is a destructive action! `borgmatic restore` replaces live databases by
restoring dumps from the selected archive. So be very careful when and where
you run it.
### Configuration file selection
If you have a multi-configuration-file setup and you want to restore a database
from a single configuration file, use the `--config` flag with the path of the
configuration file to use for the restore. For example:
```bash
borgmatic restore --config /path/to/config.yaml --archive latest
```
Without `--config`, borgmatic tries to run the `restore` action once for each
configuration file it finds.
### Repository selection
If you have a single repository in your borgmatic configuration file(s), no
problem: the `restore` action figures out which repository to use.
But if you have multiple repositories configured, then you'll need to specify
the repository to use via the `--repository` flag. This can be done either
with the repository's path or its label as configured in your borgmatic
configuration file.
```bash
borgmatic restore --repository repo.borg --archive latest
```
### Restore particular databases
If you've backed up multiple databases into an archive, and you'd only like to
restore one of them, use the `--database` flag to select one or more
databases. For instance:
```bash
borgmatic restore --archive latest --database users --database orders
```
<span class="minilink minilink-addedin">New in version 1.7.6</span> You can
also restore individual databases even if you dumped them as "all"—as long as
you dumped them into separate files via use of the "format" option. See above
for more information.
### Restore databases sharing a name
<span class="minilink minilink-addedin">New in version 1.9.5</span> If you've
backed up multiple databases that happen to share the same name but different
hostnames, ports, or hooks, you can include additional flags to disambiguate
which database you'd like to restore. For instance, let's say you've backed up
the following configured databases:
```yaml
postgresql_databases:
- name: users
hostname: host1.example.org
- name: users
hostname: host2.example.org
```
... then you can run the following command to restore only one of them:
```bash
borgmatic restore --archive latest --database users --original-hostname host1.example.org
```
This selects a `users` database to restore, but only if it originally came
from the host `host1.example.org`. This command won't restore `users`
databases from any other hosts.
Here's another example configuration:
```yaml
postgresql_databases:
- name: users
hostname: example.org
port: 5433
- name: users
hostname: example.org
port: 5434
```
And a command to restore just one of the databases:
```bash
borgmatic restore --archive latest --database users --original-port 5433
```
That restores a `users` database only if it originally came from port `5433`
*and* if that port is in borgmatic's configuration, e.g. `port: 5433`.
Finally, check out this configuration:
```yaml
postgresql_databases:
- name: users
hostname: example.org
mariadb_databases:
- name: users
hostname: example.org
```
And to select just one of the databases to restore:
```bash
borgmatic restore --archive latest --database users --hook postgresql
```
That restores a `users` database only if it was dumped using the
`postgresql_databases:` data source hook. This command won't restore `users`
databases that were dumped using other hooks.
Note that these flags don't change the hostname or port to which the database
is actually restored. For that, see below about restoring to an alternate
host.
### Restore all databases
To restore all databases:
```bash
borgmatic restore --archive latest --database all
```
Or omit the `--database` flag entirely:
```bash
borgmatic restore --archive latest
```
<span class="minilink minilink-addedin">New in version 1.7.6</span> Restoring
"all" databases restores each database found in the selected archive. That
includes any combined dump file named "all" and any other individual database
dumps found in the archive. Prior to borgmatic version 1.7.6, restoring "all"
only restored a combined "all" database dump from the archive.
### Restore particular schemas
<span class="minilink minilink-addedin">New in version 1.7.13</span> With
PostgreSQL and MongoDB, you can limit the restore to a single schema found
within the database dump:
```bash
borgmatic restore --archive latest --database users --schema tentant1
```
### Restore to an alternate host
<span class="minilink minilink-addedin">New in version 1.7.15</span>
A database dump can be restored to a host other than the one from which it was
originally dumped. The connection parameters like the username, password, and
port can also be changed. This can be done from the command line:
```bash
borgmatic restore --archive latest --database users --hostname database2.example.org --port 5433 --username postgres --password trustsome1
```
Or from the configuration file:
```yaml
postgresql_databases:
- name: users
hostname: database1.example.org
restore_hostname: database2.example.org
restore_port: 5433
restore_username: postgres
restore_password: trustsome1
```
### Manual restoration
If you prefer to restore a database without the help of borgmatic, first
[extract](https://torsion.org/borgmatic/how-to/extract-a-backup/) an
archive containing a database dump.
borgmatic extracts the dump file into the `borgmatic/` directory within the
extraction destination path. For example, if you're extracting to `/tmp`, then
the dump will be in `/tmp/borgmatic/`.
<span class="minilink minilink-addedin">Prior to version 1.9.0</span> borgmatic
extracted the dump file into the *`username`*`/.borgmatic/` directory within the
extraction destination path, where *`username`* is the user that created the
backup. For example, if you created the backup with the `root` user and you're
extracting to `/tmp`, then the dump will be in `/tmp/root/.borgmatic`.
After extraction, you can manually restore the dump file using native database
commands like `pg_restore`, `mysql`, `mongorestore`, `sqlite`, or similar.
Also see the documentation on [listing database
dumps](https://torsion.org/borgmatic/how-to/inspect-your-backups/#listing-database-dumps).
## Limitations
There are a few important limitations with borgmatic's current database
hooks that you should know about:
1. When database hooks are enabled, borgmatic instructs Borg to consume
special files (via `--read-special`) to support database dump
streaming—regardless of the value of your `read_special` configuration option.
And because this can cause Borg to hang, borgmatic also automatically excludes
special files (and symlinks to them) that Borg may get stuck on. Even so,
there are still potential edge cases in which applications on your system
create new special files *after* borgmatic constructs its exclude list,
resulting in Borg hangs. If that occurs, you can resort to manually excluding
those files. And if you explicitly set the `read_special` option to `true`,
borgmatic will opt you out of the auto-exclude feature entirely, but will
still instruct Borg to consume special files—and you will be on your own to
exclude them. <span class="minilink minilink-addedin">Prior to version
1.7.3</span>Special files were not auto-excluded, and you were responsible for
excluding them yourself. Common directories to exclude are `/dev` and `/run`,
but that may not be exhaustive.
2. <span class="minilink minilink-addedin">Prior to version 1.9.5</span>
borgmatic did not support backing up or restoring multiple databases that
shared the exact same name on different hosts or with different ports.
3. <span class="minilink minilink-addedin">Prior to version 1.9.0</span>
Database hooks also implicitly enabled the `one_file_system` option, which
meant Borg wouldn't cross filesystem boundaries when looking for files to
backup. When borgmatic was running in a container, this often required a
work-around to explicitly add each mounted backup volume to
`source_directories` instead of relying on Borg to include them implicitly via
a parent directory. But as of borgmatic 1.9.0, `one_file_system` is no longer
auto-enabled and such work-arounds aren't necessary.
4. <span class="minilink minilink-addedin">Prior to version 1.9.0</span> You
must restore as the same Unix user that created the archive containing the
database dump. That's because the user's home directory path is encoded into
the path of the database dump within the archive.
5. <span class="minilink minilink-addedin">Prior to version 1.7.15</span> As
mentioned above, borgmatic can only restore a database that's defined in
borgmatic's own configuration file. So include your configuration files in
backups to avoid getting caught without a way to restore a database. But
starting from version 1.7.15, borgmatic includes your configuration files
automatically.
## Troubleshooting
### Authentication errors
With PostgreSQL, MariaDB, and MySQL, if you're getting authentication errors
when borgmatic tries to connect to your database, a natural reaction is to
increase your borgmatic verbosity with `--verbosity 2` and go looking in the
logs. You'll notice though that your database password does not show up in the
logs. But this is likely not the cause of the authentication problem unless you
mistyped your password; borgmatic passes your password to the database via an
environment variable or anonymous pipe, so the password does not appear in the
logs.
The cause of an authentication error is often on the database side—in the
configuration of which users are allowed to connect and how they are
authenticated. For instance, with PostgreSQL, check your
[pg_hba.conf](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html)
file for that configuration.
Additionally, MariaDB or MySQL may be picking up some of your credentials from
a defaults file like `~/mariadb.cnf` or `~/.my.cnf`. If that's the case, then
it's possible MariaDB or MySQL end up using, say, a username from borgmatic's
configuration and a password from `~/mariadb.cnf` or `~/.my.cnf`. This may
result in authentication errors if this combination of credentials is not what
you intend.
### MariaDB or MySQL table lock errors
If you encounter table lock errors during a database dump with MariaDB or
MySQL, you may need to [use a
transaction](https://mariadb.com/docs/skysql-dbaas/ref/mdb/cli/mariadb-dump/single-transaction/).
You can add any additional flags to the `options:` in your database
configuration. Here's an example with MariaDB:
```yaml
mariadb_databases:
- name: posts
options: "--single-transaction"
```
<span class="minilink minilink-addedin">New in version 2.0.13</span> borgmatic
passes `--single-transaction` to MariaDB/MySQL by default, and you no longer
need to set that in `options:`.
### borgmatic hangs during backup
See Limitations above about `read_special`. You may need to exclude certain
paths with named pipes, block devices, character devices, or sockets on which
borgmatic is hanging.
Alternatively, if excluding special files is too onerous, you can create two
separate borgmatic configuration files—one for your source files and a
separate one for backing up databases. That way, the database `read_special`
option will not be active when backing up special files.
<span class="minilink minilink-addedin">New in version 1.7.3</span> See
Limitations above about borgmatic's automatic exclusion of special files to
prevent Borg hangs.

74
docs/how-to/customize-warnings-and-errors.md
View file

@ -1,74 +0,0 @@
---
title: 💥 How to customize warnings and errors
eleventyNavigation:
key: 💥 Customize warnings/errors
parent: How-to guides
order: 13
---
After Borg runs, it indicates whether it succeeded via its exit code, a numeric
ID indicating success, warning, or error. borgmatic consumes this exit code to
decide how to respond. By default, Borg errors (and some warnings) result
in a borgmatic error, while Borg successes don't.
<span class="minilink minilink-addedin">New in borgmatic version 2.1.0</span>
borgmatic elevates most Borg warnings to errors by default. For instance, if a
source directory is missing during backup, Borg indicates that with a warning
exit code (`107`). And starting in borgmatic 2.1.0, that exit code is considered
an error, so you'll actually find out about missing files.
<span class="minilink minilink-addedin">With Borg version 1.4+</span> If the
default behavior isn't sufficient for your needs, you can customize how
borgmatic interprets [Borg's exit
codes](https://borgbackup.readthedocs.io/en/stable/internals/frontends.html#message-ids).
For instance, this borgmatic configuration elevates a Borg warning about source files
changes during backup (exit code `100`)—and only those warnings—to
errors:
```yaml
borg_exit_codes:
- code: 100
treat_as: error
```
The following configuration does that *and* treats Borg's backup file not found
(exit code `107`) as a warning:
```yaml
borg_exit_codes:
- code: 100
treat_as: error
- code: 107
treat_as: warning
```
If you don't know the exit code for a particular Borg error or warning you're
experiencing, you can usually find it in your borgmatic output when `--verbosity
2` is enabled. For instance, here's a snippet of that output when a backup file
is not found:
```
/noexist: stat: [Errno 2] No such file or directory: '/noexist'
...
terminating with warning status, rc 107
```
So if you want to configure borgmatic to treat this as an warning instead of an
error, the exit status to use is `107`.
<span class="minilink minilink-addedin">With Borg version 1.2 and earlier</span>
Older versions of Borg didn't support granular exit codes, but still
distinguished between Borg errors and warnings. For instance, to elevate Borg
warnings to errors, thereby causing borgmatic to error on them, use the
following borgmatic configuration with Borg 1.2 or below:
```yaml
borg_exit_codes:
- code: 1
treat_as: error
```
Be aware though that Borg exits with a warning code for a variety of benign
situations such as files changing while they're being read, so this example
may not meet your needs. Upgrading to Borg 1.4+ is recommended.

89
docs/how-to/deal-with-very-large-backups.md
View file

@ -1,89 +0,0 @@
---
title: 📏 How to deal with very large backups
eleventyNavigation:
key: 📏 Deal with very large backups
parent: How-to guides
order: 4
---
<a id="a-la-carte-actions"></a>
Borg itself is great for efficiently de-duplicating data across successive
backup archives, even when dealing with very large repositories. But you may
find that while borgmatic's default actions of `create`, `prune`, `compact`,
and `check` works well on small repositories, it's not so great on larger
ones. That's because running the default pruning, compact, and consistency
checks take a long time on large repositories.
See the [actions
documentation](https://torsion.org/borgmatic/reference/command-line/actions/)
for details on customizing the actions that borgmatic runs.
<a id="spot-check"></a>
<a id="check-frequency"></a>
<a id="check-days"></a>
<a id="running-only-checks"></a>
<a id="disabling-checks"></a>
### Consistency check configuration
Another way of dealing with large backups is to customize your consistency
checks. By default, if you omit consistency checks from configuration, borgmatic
runs full-repository checks and per-archive checks within each repository on a
monthly basis.
But if you find that archive checks are too slow and/or you'd like to customize
the check frequency, see the [consistency checks
documentation](https://torsion.org/borgmatic/reference/configuration/consistency-checks/)
for details.
### Pre-backup safety validation
Before running a backup during the `create` action, borgmatic automatically runs
through some pre-backup safety validation to ensure that:
1. You haven't accidentally excluded borgmatic's [runtime
directory](https://torsion.org/borgmatic/reference/configuration/runtime-directory/)
from the backup, which would break things like database dumps, filesystem
snapshots, etc.
2. Special files are auto-excluded to prevent Borg from hanging.
This validation does have a cost: performance. On a large filesystem, it can
take a while to run. So if you are absolutely sure that you aren't excluding
borgmatic's runtime directory, and you also aren't including any special files
that might cause Borg to hang, you can disable the pre-backup validation as
follows:
```yaml
unsafe_skip_path_validation_before_create: true
```
However, this is indeed unsafe and could lead to hangs or data being left out
of backups. Use this option at your own risk.
## Troubleshooting
### Broken pipe with remote repository
When running borgmatic on a large remote repository, you may receive errors
like the following, particularly while "borg check" is validating backups for
consistency:
```text
Write failed: Broken pipe
borg: Error: Connection closed by remote host
```
This error can be caused by an ssh timeout, which you can rectify by adding
the following to the `~/.ssh/config` file on the client:
```text
Host *
ServerAliveInterval 120
```
This should make the client keep the connection alive while validating
backups.

211
docs/how-to/develop-on-borgmatic.md
View file

@ -1,211 +0,0 @@
---
title: 🏗️ How to develop on borgmatic
eleventyNavigation:
key: 🏗️ Develop on borgmatic
parent: How-to guides
order: 15
---
<span data-pagefind-weight="0.25">
To get set up to develop on borgmatic, first [`install
uv`](https://docs.astral.sh/uv/) to make managing your borgmatic environment
easier without impacting other Python applications on your system.
Then, clone borgmatic via HTTPS or SSH:
```bash
git clone https://projects.torsion.org/borgmatic-collective/borgmatic.git
```
Or:
```bash
git clone ssh://git@projects.torsion.org:3022/borgmatic-collective/borgmatic.git
```
Finally, install borgmatic
"[editable](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs)"
so that you can run borgmatic actions during development to make sure your
changes work:
```bash
cd borgmatic
uv tool update-shell
uv tool install --editable .
```
Or to work on the [Apprise
hook](https://torsion.org/borgmatic/reference/configuration/monitoring/apprise/),
change that last line to:
```bash
uv tool install --editable .[Apprise]
```
To get oriented with the borgmatic source code, have a look at the [source
code reference](https://torsion.org/borgmatic/reference/source-code/).
### Source packages
Each [borgmatic
release](https://projects.torsion.org/borgmatic-collective/borgmatic/releases)
also has source packages available. These include automated tests and serve as
a good starting point for creating third-party borgmatic packages.
## Automated tests
Assuming you've cloned the borgmatic source code as described above and you're
in the `borgmatic/` working copy, install [tox](https://tox.wiki/) and
[tox-uv](https://github.com/tox-dev/tox-uv) using uv, which are used for setting
up testing environments:
```bash
uv tool install tox --with tox-uv
```
Also install [Ruff](https://docs.astral.sh/ruff/), which borgmatic uses for code
linting and formatting:
```bash
uv tool install ruff
```
Finally, to actually run tests, run tox from inside the borgmatic source
directory:
```bash
tox
```
That runs tests against all supported versions of Python, which takes a while.
So if you'd only like to run tests against a single version of Python, e.g.
Python 3.13:
```bash
tox -e py313
```
### Code style
If when running tests, you get an error from Ruff's linter about files that
don't meet linting requirements, you can ask Ruff to attempt to fix them for you
via the following:
```bash
tox -e lint-fix
```
And if you get an error from the Ruff's code formatter about files that would be
reformatted, you can ask Ruff to format them for you:
```bash
tox -e format
```
Similarly, if you get errors about spelling mistakes in source code, you can
ask [codespell](https://github.com/codespell-project/codespell) to correct
them:
```bash
tox -e spell
```
See the [code style
documentation](https://torsion.org/borgmatic/reference/source-code/#code-style)
for more specifics about borgmatic's own code style.
### End-to-end tests
borgmatic additionally includes some end-to-end tests that integration test
with Borg and supported databases for a few representative scenarios. These
tests don't run by default when running `tox`, because they're relatively slow
and depend on containers for runtime dependencies. These tests do run on the
continuous integration (CI) server, and running them on your developer machine
is the closest thing to dev-CI parity.
If you would like to run the end-to-end tests, first install Docker (or
Podman; see below) and [Docker
Compose](https://docs.docker.com/compose/install/). Then run:
```bash
scripts/run-end-to-end-tests
```
This script assumes you have permission to run `docker`. If you don't, then
you may need to run with `sudo`.
#### Podman
borgmatic's end-to-end tests optionally support using
[rootless](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md)
[Podman](https://podman.io/) instead of Docker.
Setting up Podman is outside the scope of this documentation, but here are
some key points to double-check:
* Install Podman and your desired networking support.
* Configure `/etc/subuid` and `/etc/subgid` to map users/groups for the
non-root user who will run tests.
* Create a non-root Podman socket for that user:
```bash
systemctl --user enable --now podman.socket
systemctl --user start --now podman.socket
```
Then you'll be able to run end-to-end tests as per normal, and the test script
will automatically use your non-root Podman socket instead of a Docker socket.
## Continuous integration
Each commit to
[main](https://projects.torsion.org/borgmatic-collective/borgmatic/branches)
triggers [a continuous integration
build](https://projects.torsion.org/borgmatic-collective/borgmatic/actions)
which runs the test suite and updates
[documentation](https://torsion.org/borgmatic/). These builds are also linked
from the [commits for the main
branch](https://projects.torsion.org/borgmatic-collective/borgmatic/commits/branch/main).
## Documentation development
Updates to borgmatic's documentation are welcome. It's formatted in Markdown
and located in the `docs/` directory in borgmatic's source, plus the
`README.md` file at the root.
To build and view a copy of the documentation with your local changes, run the
following from the root of borgmatic's source code:
```bash
scripts/dev-docs
```
This requires Docker (or Podman; see below) to be installed on your system.
This script assumes you have permission to run `docker`. If you don't, then
you may need to run with `sudo`.
After you run the script, you can point your web browser at
http://localhost:8080/borgmatic/ to view the documentation with your changes.
To close the documentation server, ctrl-C the script. Note that it does not
currently auto-reload, so you'll need to stop it and re-run it for any
additional documentation changes to take effect.
#### Podman
borgmatic's developer build for documentation optionally supports using
[rootless](https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md)
[Podman](https://podman.io/) instead of Docker.
Setting up Podman is outside the scope of this documentation. But once you
install and configure Podman, then `scripts/dev-docs` should automatically use
Podman instead of Docker.
</span>

223
docs/how-to/extract-a-backup.md
View file

@ -1,223 +0,0 @@
---
title: 📤 How to extract a backup
eleventyNavigation:
key: 📤 Extract a backup
parent: How-to guides
order: 7
---
When the worst happens—or you want to test your backups—the first step is
to figure out which archive to extract. A good way to do that is to use the
`repo-list` action:
```bash
borgmatic repo-list
```
(No borgmatic `repo-list` action? Try `rlist` or `list` instead or upgrade
borgmatic!)
That should yield output looking something like:
```text
host-2023-01-01T04:05:06.070809 Tue, 2023-01-01 04:05:06 [...]
host-2023-01-02T04:06:07.080910 Wed, 2023-01-02 04:06:07 [...]
```
Assuming that you want to extract the archive with the most up-to-date files
and therefore the latest timestamp, run a command like:
```bash
borgmatic extract --archive host-2023-01-02T04:06:07.080910
```
Or simplify this to:
```bash
borgmatic extract --archive latest
```
The `--archive` value is the name of the archive or archive hash to extract.
This extracts the entire contents of the archive to the current directory, so
make sure you're in the right place before running the command—or see below
about the `--destination` flag.
## Repository selection
If you have a single repository in your borgmatic configuration file(s), no
problem: the `extract` action figures out which repository to use.
But if you have multiple repositories configured, then you'll need to specify
the repository to use via the `--repository` flag. This can be done either
with the repository's path or its label as configured in your borgmatic configuration file.
```bash
borgmatic extract --repository repo.borg --archive host-2023-...
```
## Extract particular files
Sometimes, you want to extract a single deleted file, rather than extracting
everything from an archive. To do that, tack on one or more `--path` values.
For instance:
```bash
borgmatic extract --archive latest --path path/1 --path path/2
```
Note that the specified restore paths should not have a leading slash. Like a
whole-archive extract, this also extracts into the current directory by
default. So for example, if you happen to be in the directory `/var` and you
run the `extract` command above, borgmatic will extract `/var/path/1` and
`/var/path/2`.
### Searching for files
If you're not sure which archive contains the files you're looking for, you
can [search across
archives](https://torsion.org/borgmatic/how-to/inspect-your-backups/#searching-for-a-file).
## Extract to a particular destination
By default, borgmatic extracts files into the current directory. To instead
extract files to a particular destination directory, use the `--destination`
flag:
```bash
borgmatic extract --archive latest --destination /tmp
```
When using the `--destination` flag, be careful not to overwrite your system's
files with extracted files unless that is your intent.
## Database restoration
The `borgmatic extract` command only extracts files. To restore a database,
please see the [documentation on database backups and
restores](https://torsion.org/borgmatic/how-to/backup-your-databases/).
borgmatic does not perform database restoration as part of `borgmatic extract`
so that you can extract files from your archive without impacting your live
databases.
## Mount a filesystem
If instead of extracting files, you'd like to explore the files from an
archive as a [FUSE](https://en.wikipedia.org/wiki/Filesystem_in_Userspace)
filesystem, you can use the `borgmatic mount` action. Here's an example:
```bash
borgmatic mount --archive latest --mount-point /mnt
```
This mounts the entire archive on the given mount point `/mnt`, so that you
can look in there for your files.
Omit the `--archive` flag to mount all archives (lazy-loaded):
```bash
borgmatic mount --mount-point /mnt
```
Or use the "latest" value for the archive to mount the latest archive:
```bash
borgmatic mount --archive latest --mount-point /mnt
```
<span class="minilink minilink-addedin">New in borgmatic version 1.9.0 with
Borg version 2.x</span>You can provide a series name for the `--archive` value
to mount multiple archives in that series:
```bash
borgmatic mount --archive seriesname --mount-point /mnt
```
If you'd like to restrict the mounted filesystem to only particular paths from
your archive, use the `--path` flag, similar to the `extract` action above.
For instance:
```bash
borgmatic mount --archive latest --mount-point /mnt --path var/lib
```
When you're all done exploring your files, unmount your mount point. No
`--archive` flag is needed:
```bash
borgmatic umount --mount-point /mnt
```
## Extract the configuration files used to create an archive
<span class="minilink minilink-addedin">New in version 1.7.15</span> As part
of creating a backup archive, borgmatic automatically includes all of the
configuration files used when creating it, storing them inside the archive
itself with their full paths from the machine being backed up. This is useful
in cases where you've lost a configuration file or you want to see what
configurations were used to create a particular archive.
To support this, borgmatic creates a manifest file that records the paths of
all the borgmatic configuration files stored within an archive. The file gets
written to borgmatic's runtime directory on disk and then stored within the
archive. See the [runtime directory
documentation](https://torsion.org/borgmatic/reference/configuration/runtime-directory/)
for how and where that happens.
To extract the configuration files from an archive, use the `config bootstrap`
action. For example:
```bash
borgmatic config bootstrap --repository repo.borg --destination /tmp
```
This extracts the configuration file from the latest archive in the repository
`repo.borg` to `/tmp/etc/borgmatic/config.yaml`, assuming that the only
configuration file used to create this archive was located at
`/etc/borgmatic/config.yaml` when the archive was created.
Note that to run the `config bootstrap` action, you don't need to have a
borgmatic configuration file. You only need to specify the repository to use
via the `--repository` flag; borgmatic will figure out the rest.
If a destination directory is not specified, the configuration files will be
extracted to their original locations, silently *overwriting* any configuration
files that may already exist. For example, if a configuration file was located
at `/etc/borgmatic/config.yaml` when the archive was created, it will be
extracted to `/etc/borgmatic/config.yaml` too.
If you want to extract the configuration file from a specific archive, use the
`--archive` flag:
```bash
borgmatic config bootstrap --repository repo.borg --archive host-2023-01-02T04:06:07.080910 --destination /tmp
```
See the [config bootstrap action
documentation](https://torsion.org/borgmatic/reference/command-line/actions/config-bootstrap/)
for additional flags you may need for bootstrapping.
<span class="minilink minilink-addedin">New in version 1.9.3</span>
If your borgmatic configuration files contain sensitive information you don't
want to store even inside your encrypted backups, you can disable the
automatic backup of the configuration files. To do this, set the
`store_config_files` option under the `bootstrap` hook to `false`. For
instance:
```yaml
bootstrap:
store_config_files: false
```
If you do this though, the `config bootstrap` action will no longer work.
<span class="minilink minilink-addedin">In version 1.8.1 through 1.9.2</span>
The `store_config_files` option was at the global scope instead of under the
`bootstrap` hook.
<span class="minilink minilink-addedin">New in version 1.8.7</span>
Configuration file includes are stored in each backup archive. This means that
the `config bootstrap` action not only extracts the top-level configuration
files but also the includes they depend upon.

6
docs/how-to/index.md
View file

@ -1,6 +0,0 @@
---
eleventyNavigation:
key: How-to guides
order: 1
permalink: false
---

118
docs/how-to/inspect-your-backups.md
View file

@ -1,118 +0,0 @@
---
title: 🔎 How to inspect your backups
eleventyNavigation:
key: 🔎 Inspect your backups
parent: How-to guides
order: 5
---
By default, borgmatic runs proceed silently except in the case of warnings or
errors. But if you'd like to to get additional information about the progress of
the backup as it proceeds, see the [logging
documentation](https://torsion.org/borgmatic/reference/command-line/logging/)
for details.
## Backup summary
If you're less concerned with progress during a backup, and you only want to see
the summary of archive statistics at the end, use the stats option when
performing a backup:
```bash
borgmatic --stats
```
## Existing backups
borgmatic provides convenient actions for Borg's
[`list`](https://borgbackup.readthedocs.io/en/stable/usage/list.html) and
[`info`](https://borgbackup.readthedocs.io/en/stable/usage/info.html)
functionality:
```bash
borgmatic list
borgmatic info
```
You can change the output format of `borgmatic list` by specifying your own
with `--format`. Refer to the [borg list --format
documentation](https://borgbackup.readthedocs.io/en/stable/usage/list.html#the-format-specifier-syntax)
for available values.
<span class="minilink minilink-addedin">New in version 1.9.0</span> There are
also `repo-list` and `repo-info` actions for displaying repository information
with Borg 2.x:
```bash
borgmatic repo-list
borgmatic repo-info
```
See the [borgmatic command-line
reference](https://torsion.org/borgmatic/reference/command-line/) for
more information.
### Searching for a file
<span class="minilink minilink-addedin">New in version 1.6.3</span> Let's say
you've accidentally deleted a file and want to find the backup archive(s)
containing it. `borgmatic list` provides a `--find` flag for exactly this
purpose. For instance, if you're looking for a `foo.txt`:
```bash
borgmatic list --find foo.txt
```
This lists your archives and indicate those with files matching `*foo.txt*`
anywhere in the archive. The `--find` parameter can alternatively be a [Borg
pattern](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-patterns).
To limit the archives searched, use the standard `list` parameters for
filtering archives such as `--last`, `--archive`, `--match-archives`, etc. For
example, to search only the last five archives:
```bash
borgmatic list --find foo.txt --last 5
```
## Listing database dumps
If you've enabled borgmatic's [database
hooks](https://torsion.org/borgmatic/how-to/backup-your-databases/), you
can list backed up database dumps via borgmatic. For example:
```bash
borgmatic list --archive latest --find *borgmatic/*_databases
```
This gives you a listing of all database dump files contained in the latest
archive, complete with file sizes.
<span class="minilink minilink-addedin">New in borgmatic version
1.9.0</span>Database dump files are stored at `/borgmatic` within a backup
archive, regardless of the user who performs the backup. (Note that Borg
doesn't store the leading `/`.)
<span class="minilink minilink-addedin">With Borg version 1.2 and
earlier</span>Database dump files are stored at a path dependent on the [runtime
directory](https://torsion.org/borgmatic/reference/configuration/runtime-directory/)
in use at the time the archive was created, as Borg 1.2 and earlier do not
support path rewriting.
<span class="minilink minilink-addedin">Prior to borgmatic version
1.9.0</span>Database dump files were instead stored at `~/.borgmatic` within
the backup archive (where `~` was expanded to the home directory of the user
who performed the backup). This applied with all versions of Borg.
<a id="rate-limiting"></a>
<a id="logging-to-file"></a>
## Logging
By default, borgmatic only logs to the console. But to enable simultaneous
syslog or file logging, see the [logging
documentation](https://torsion.org/borgmatic/reference/command-line/logging/)
for details.

56
docs/how-to/make-backups-redundant.md
View file

@ -1,56 +0,0 @@
---
title: ☁️ How to make backups redundant
eleventyNavigation:
key: ☁️ Make backups redundant
parent: How-to guides
order: 3
---
If you really care about your data, you probably want more than one backup of
it. borgmatic supports this in its configuration by specifying multiple backup
repositories. Here's an example:
```yaml
# List of source directories to backup.
source_directories:
- /home
- /etc
# Paths of local or remote repositories to backup to.
repositories:
- path: ssh://k8pDxu32@k8pDxu32.repo.borgbase.com/./repo
- path: /var/lib/backups/local.borg
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
these options in the `location:` section of your configuration.
<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
the `path:` portion of the `repositories` list.
When you run borgmatic with this configuration, it invokes Borg once for each
configured repository in sequence. (So, not in parallel.) That means—in each
repository—borgmatic creates a single new backup archive containing all of
your source directories.
Here's a way of visualizing what borgmatic does with the above configuration:
1. Backup `/home` and `/etc` to `k8pDxu32@k8pDxu32.repo.borgbase.com:repo`
2. Backup `/home` and `/etc` to `/var/lib/backups/local.borg`
This gives you redundancy of your data across repositories and even
potentially across providers.
See [repositories
documentation](https://torsion.org/borgmatic/reference/configuration/repositories/)
for more information on how to specify local and remote repository paths.
### Different options per repository
What if you want borgmatic to backup to multiple repositories—while also
setting different options for each one? In that case, you'll need to use
[a separate borgmatic configuration file for each
repository](https://torsion.org/borgmatic/how-to/make-per-application-backups/)
instead of the multiple repositories in one configuration file as described
above. That's because all of the repositories in a particular configuration
file get the same options applied.

96
docs/how-to/make-per-application-backups.md
View file

@ -1,96 +0,0 @@
---
title: 🗂️ How to make per-application backups
eleventyNavigation:
key: 🗂️ Make per-application backups
parent: How-to guides
order: 1
---
You may find yourself wanting to create different backup policies for
different applications on your system or even for different backup
repositories. For instance, you might want one backup configuration for your
database data directory and a different configuration for your user home
directories. Or one backup configuration for your local backups with a
different configuration for your remote repository.
The way to accomplish that is pretty simple: Create multiple separate
configuration files and place each one in a `/etc/borgmatic.d/` directory. For
instance, for applications:
```bash
sudo mkdir /etc/borgmatic.d
sudo borgmatic config generate --destination /etc/borgmatic.d/app1.yaml
sudo borgmatic config generate --destination /etc/borgmatic.d/app2.yaml
```
Or, for repositories:
```bash
sudo mkdir /etc/borgmatic.d
sudo borgmatic config generate --destination /etc/borgmatic.d/repo1.yaml
sudo borgmatic config generate --destination /etc/borgmatic.d/repo2.yaml
```
<span class="minilink minilink-addedin">Prior to version 1.7.15</span> The
command to generate configuration files was `generate-borgmatic-config`
instead of `borgmatic config generate`.
When you set up multiple configuration files like this, borgmatic will run
each one in turn from a single borgmatic invocation. This includes, by
default, the traditional `/etc/borgmatic/config.yaml` as well.
Each configuration file is interpreted independently, as if you ran borgmatic
for each configuration file one at a time. In other words, borgmatic does not
perform any merging of configuration files by default. If you'd like borgmatic
to merge your configuration files, for instance to avoid duplication of
settings, see below about configuration includes.
Additionally, the `~/.config/borgmatic.d/` directory works the same way as
`/etc/borgmatic.d`.
If you need even more customizability, you can specify alternate configuration
paths on the command-line with borgmatic's `--config` flag. (See the
[command-line
documentation](https://torsion.org/borgmatic/reference/command-line/) for more
information.) For instance, if you want to schedule your various borgmatic
backups to run at different times, you'll need multiple entries in your
[scheduling software of
choice](https://torsion.org/borgmatic/how-to/set-up-backups/#autopilot), each
entry using borgmatic's `--config` flag instead of relying on
`/etc/borgmatic.d`.
## Limitations
borgmatic does not currently support its own parallelism—being run multiple
times on the same machine simultaneously. In particular, many of the [data
source
hooks](https://torsion.org/borgmatic/reference/configuration/data-sources/) rely
on global borgmatic runtime files which can't be shared across processes, and
therefore multiple borgmatic instances on the same machine would interfere with
each other.
A single borgmatic instance also doesn't currently support running multiple Borg
instances in parallel on the same machine.
<a id="archive-naming"></a>
<a id="configuration-includes"></a>
<a id="configuration-overrides"></a>
<a id="constant-interpolation"></a>
## Related features
Once you've got multiple configuration files, there are a few other borgmatic
features that you might find handy:
* Use different archive naming schemes in each configuration file with the
[archive name
format](https://torsion.org/borgmatic/reference/configuration/archive-name-format/)
feature.
* Share common options across configuration files with
[includes](https://torsion.org/borgmatic/reference/configuration/includes/).
* Override configuration file options from the command-line with
[overrides](https://torsion.org/borgmatic/reference/command-line/overrides/).
* Also check out the
[constants](https://torsion.org/borgmatic/reference/configuration/constants/)
feature for defining custom per-configuration-file constants.

97
docs/how-to/monitor-your-backups.md
View file

@ -1,97 +0,0 @@
---
title: 🚨 How to monitor your backups
eleventyNavigation:
key: 🚨 Monitor your backups
parent: How-to guides
order: 6
---
Having backups is great, but they won't do you a lot of good unless you have
confidence that they're running on a regular basis. That's where monitoring
and alerting comes in.
There are several different ways you can monitor your backups and find out
whether they're succeeding. Which of these you choose to do is up to you and
your particular infrastructure:
* **Job runner alerts**: The easiest place to start is with failure alerts from
the [scheduled job
runner](https://torsion.org/borgmatic/how-to/set-up-backups/#autopilot)
(cron, systemd, etc.) that's running borgmatic. But note that if the job
doesn't even get scheduled (e.g. due to the job runner not running), you
probably won't get an alert at all! Still, this is a decent first line of
defense, especially when combined with some of the other approaches below.
* **Third-party monitoring services:** borgmatic integrates with these monitoring
services and libraries, pinging them as backups happen. The idea is that
you'll receive an alert when something goes wrong or when the service doesn't
hear from borgmatic for a configured interval (if supported). While these
services and libraries offer different features, you probably only need to
use one of them at most. See the [monitoring configuration
documentation](https://torsion.org/borgmatic/reference/configuration/monitoring/)
for details.
* **Third-party monitoring software:** You can use traditional monitoring
software to consume borgmatic JSON output and track when the last successful
backup occurred. See [scripting
borgmatic](https://torsion.org/borgmatic/how-to/monitor-your-backups/#scripting-borgmatic)
below for how to configure this.
* **Borg hosting providers:** Some [Borg hosting
providers](https://torsion.org/borgmatic/#hosting-providers) include
monitoring and alerting as part of their offering. This gives you a dashboard
to check on all of your backups, and can alert you if the service doesn't
hear from borgmatic for a configured interval.
* **Consistency checks:** While not strictly part of monitoring, if you want
confidence that your backups are not only running but are restorable as well,
you can configure particular [consistency
checks](https://torsion.org/borgmatic/reference/configuration/consistency-checks/)
or even script full [extract
tests](https://torsion.org/borgmatic/how-to/extract-a-backup/).
* **Commands run on error:** borgmatic's command hooks support running
arbitrary commands or scripts when borgmatic itself encounters an error
running your backups. So for instance, you can run a script to send yourself
a text message alert. But note that if borgmatic doesn't actually run, this
alert won't fire. See the [documentation on preparation and cleanup
steps](https://torsion.org/borgmatic/how-to/add-preparation-and-cleanup-steps-to-backups/)
for details.
## Scripting borgmatic
To consume the output of borgmatic in other software, you can include an
optional `--json` flag with `create`, `repo-list`, `repo-info`, or `info` to
get the output formatted as JSON.
Note that when you specify the `--json` flag, Borg's other non-JSON output is
suppressed so as not to interfere with the captured JSON. Also note that JSON
output only shows up at the console and not in syslog.
### Getting configuration
<span class="minilink minilink-addedin">New in version 2.1.3</span> If you want
to consume borgmatic's computed configuration in your scripts, use the [`config
show`
action](https://torsion.org/borgmatic/reference/command-line/actions/config-show/).
Here's an example:
```bash
borgmatic config show --json
```
That outputs borgmatic's entire configuration as JSON with one array element per
configuration file.
Or you can ask for the value of a particular option:
```bash
borgmatic config show --option repositories --json
```
### Latest backups
All borgmatic actions that accept an `--archive` flag allow you to specify an
archive name of `latest`. This lets you get the latest archive without having
to first run `borgmatic repo-list` manually, which can be handy in automated
scripts. Here's an example:
```bash
borgmatic info --archive latest
```

64
docs/how-to/provide-your-passwords.md
View file

@ -1,64 +0,0 @@
---
title: 🔒 How to provide your passwords
eleventyNavigation:
key: 🔒 Provide your passwords
parent: How-to guides
order: 2
---
If you want to use a Borg repository passphrase or database passwords with
borgmatic, you can set them directly in your borgmatic configuration file,
treating those secrets like any other option value. For instance, you can
specify your Borg passhprase with:
```yaml
encryption_passphrase: yourpassphrase
```
But if you'd rather store them outside of borgmatic, whether for convenience
or security reasons, read on.
### Delegating to another application
borgmatic supports calling another application such as a password manager to
obtain the Borg passphrase to a repository.
For example, to ask the [Pass](https://www.passwordstore.org/) password manager
to provide the passphrase:
```yaml
encryption_passcommand: pass path/to/borg-passphrase
```
<span class="minilink minilink-addedin">New in version 1.9.9</span> Instead of
letting Borg run the passcommand—potentially multiple times since borgmatic runs
Borg multiple times—borgmatic now runs the passcommand itself and passes the
resulting passphrase securely to Borg via an anonymous pipe. This means you
should only ever get prompted for your password manager's passphrase at most
once per borgmatic run.
<a id="systemd-service-credentials"></a>
<a id="container-secrets"></a>
<a id="keepassxc-passwords"></a>
<a id="file-based-credentials"></a>
### Using external credentials
<span class="minilink minilink-addedin">New in version 1.9.10</span> Several
borgmatic options support reading their values directly from an external
credential store or service. See the [credentials
documentation](https://torsion.org/borgmatic/reference/configuration/credentials/)
for details.
<a id="environment-variable-interpolation"></a>
### Using environment variables
Another way to get passwords into your configuration file is by [interpolating
arbitrary environment
variables](https://torsion.org/borgmatic/reference/configuration/environment-variables/)
directly into option values.

3
docs/how-to/restore-a-backup.md
View file

@ -1,3 +0,0 @@
<head>
<meta http-equiv='refresh' content='0; URL=https://torsion.org/borgmatic/how-to/extract-a-backup/'>
</head>

154
docs/how-to/run-arbitrary-borg-commands.md
View file

@ -1,154 +0,0 @@
---
title: 🔧 How to run arbitrary Borg commands
eleventyNavigation:
key: 🔧 Run arbitrary Borg commands
parent: How-to guides
order: 12
---
Borg has several commands and options that borgmatic does not currently
support. Sometimes though, as a borgmatic user, you may find yourself wanting
to take advantage of these off-the-beaten-path Borg features. You could of
course drop down to running Borg directly. But then you'd give up all the
niceties of your borgmatic configuration. You could file a [borgmatic
ticket](https://torsion.org/borgmatic/#issues) or even a [pull
request](https://torsion.org/borgmatic/#contributing) to add the feature. But
what if you need it *now*?
That's where borgmatic's support for running "arbitrary" Borg commands comes
in. Running these Borg commands with borgmatic can take advantage of the
following, all based on your borgmatic configuration files or command-line
arguments:
* configured repositories, running your Borg command once for each one
* local and remote Borg executable paths
* SSH settings and Borg environment variables
* lock wait settings
* verbosity
## borg action
<span class="minilink minilink-addedin">New in version 1.5.15</span> The way
you run Borg with borgmatic is via the `borg` action. Here's a simple example:
```bash
borgmatic borg break-lock
```
This runs Borg's `break-lock` command once with each configured borgmatic
repository, passing the repository path in as a Borg-supported environment
variable named `BORG_REPO`. (The native `borgmatic break-lock` action should
be preferred though for most uses.)
You can also specify Borg options for relevant commands. For instance:
```bash
borgmatic borg list --short
```
This runs Borg's `list` command once on each configured borgmatic
repository.
What if you only want to run Borg on a single configured borgmatic repository
when you've got several configured? Not a problem. The `--repository` argument
lets you specify the repository to use, either by its path or its label:
```bash
borgmatic borg --repository repo.borg break-lock
```
And if you need to specify where the repository goes in the command because
there are positional arguments after it:
```bash
borgmatic borg debug dump-manifest :: root
```
The `::` is a Borg placeholder that means: Substitute the repository passed in
by environment variable here.
<span class="minilink minilink-addedin">Prior to version 1.8.0</span>borgmatic
attempted to inject the repository name directly into your Borg arguments in
the right place (which didn't always work). So your command-line in these
older versions didn't support the `::`
## Specifying an archive
For borg commands that expect an archive name, you have a few approaches.
Here's one:
```bash
borgmatic borg --archive latest list '::$ARCHIVE'
```
The single quotes are necessary in order to pass in a literal `$ARCHIVE`
string instead of trying to resolve it from borgmatic's shell where it's not
yet set.
Or if you don't need borgmatic to resolve an archive name like `latest`, you
can do:
```bash
borgmatic borg list ::your-actual-archive-name
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span>borgmatic
provided the archive name implicitly along with the repository, attempting to
inject it into your Borg arguments in the right place (which didn't always
work). So your command-line in these older versions of borgmatic looked more
like:
```bash
borgmatic borg --archive latest list
```
<span class="minilink minilink-addedin">With Borg version 2.x</span> Either of
these will list an archive:
```bash
borgmatic borg --archive latest list '$ARCHIVE'
```
```bash
borgmatic borg list your-actual-archive-name
```
## Limitations
borgmatic's `borg` action is not without limitations:
* The Borg command you want to run (`create`, `list`, etc.) *must* come first
after the `borg` action (and any borgmatic-specific arguments). If you have
other Borg options to specify, provide them after. For instance,
`borgmatic borg list --progress ...` will work, but
`borgmatic borg --progress list ...` will not.
* Do not specify any global borgmatic arguments to the right of the `borg`
action. (They will be passed to Borg instead of borgmatic.) If you have
global borgmatic arguments, specify them *before* the `borg` action.
* Unlike other borgmatic actions, you cannot combine the `borg` action with
other borgmatic actions. This is to prevent ambiguity in commands like
`borgmatic borg list`, in which `list` is both a valid Borg command and a
borgmatic action. In this case, only the Borg command is run.
* Unlike normal borgmatic actions that support JSON, the `borg` action will
not disable certain borgmatic logs to avoid interfering with JSON output.
* The `borg` action bypasses most of borgmatic's machinery, so for instance
monitoring hooks will not get triggered when running `borgmatic borg create`.
* The `borg` action does not use `extra_borg_options`.
* <span class="minilink minilink-addedin">Prior to version 1.8.0</span>
borgmatic implicitly injected the repository/archive arguments on the Borg
command-line for you (based on your borgmatic configuration or the
`borgmatic borg --repository`/`--archive` arguments)—which meant you
couldn't specify the repository/archive directly in the Borg command. Also,
in these older versions of borgmatic, the `borg` action didn't work for any
Borg commands like `borg serve` that do not accept a repository/archive
name.
* <span class="minilink minilink-addedin">Prior to version 1.7.13</span> Unlike
other borgmatic actions, the `borg` action captured (and logged) all output,
so interactive prompts and flags like `--progress` dit not work as expected.
In new versions, borgmatic runs the `borg` action without capturing output,
so interactive prompts work.
In general, this `borgmatic borg` feature should be considered an escape
valve—a feature of second resort. In the long run, it's preferable to wrap
Borg commands with borgmatic actions that can support them fully.

3
docs/how-to/run-preparation-steps-before-backups.md
View file

@ -1,3 +0,0 @@
<head>
<meta http-equiv='refresh' content='0; URL=https://torsion.org/borgmatic/how-to/add-preparation-and-cleanup-steps-to-backups/'>
</head>

407
docs/how-to/set-up-backups.md
View file

@ -1,407 +0,0 @@
---
title: 📥 How to set up backups
eleventyNavigation:
key: 📥 Set up backups
parent: How-to guides
order: 0
---
To install borgmatic, first [install
Borg](https://borgbackup.readthedocs.io/en/stable/installation.html), at least
version 1.1. (borgmatic does not install Borg automatically so as to avoid
conflicts with existing Borg installations.)
Then, [install pipx](https://pypa.github.io/pipx/installation/) as the root
user (with `sudo`) to make installing borgmatic easier without impacting other
Python applications on your system. If you have trouble installing pipx with
pip, then you can install a system package instead. E.g. on Ubuntu or Debian,
run:
```bash
sudo apt update
sudo apt install pipx
```
### Root install
If you want to run borgmatic on a schedule with privileged access to your
files, then you should install borgmatic as the root user by running the
following commands:
```bash
sudo pipx ensurepath
sudo pipx install borgmatic
```
Check whether this worked with:
```bash
sudo su -
borgmatic --version
```
If borgmatic is properly installed, that should output your borgmatic version.
And if you'd also like `sudo borgmatic` to work, keep reading!
### Non-root install
If you only want to run borgmatic as a non-root user (without privileged file
access) *or* you want to make `sudo borgmatic` work so borgmatic runs as root,
then install borgmatic as a non-root user by running the following commands as
that user:
```bash
pipx ensurepath
pipx install borgmatic
```
This should work even if you've also installed borgmatic as the root user.
Check whether this worked with:
```bash
borgmatic --version
```
If borgmatic is properly installed, that should output your borgmatic version.
You can also try `sudo borgmatic --version` if you intend to run borgmatic
with `sudo`. If that doesn't work, you may need to update your [sudoers
`secure_path` option](https://wiki.archlinux.org/title/Sudo).
### Other ways to install
Besides the approaches described above, there are several other options for
installing borgmatic:
#### <span data-pagefind-weight="7.0">Docker / Podman</span>
* [container image with scheduled backups](https://github.com/borgmatic-collective/docker-borgmatic) (+ Docker Compose files)
* [container image with multi-arch and Docker CLI support](https://github.com/modem7/docker-borgmatic)
#### Operating system packages
* [Debian](https://tracker.debian.org/pkg/borgmatic)
* [Ubuntu](https://launchpad.net/ubuntu/+source/borgmatic)
* [Fedora](https://bodhi.fedoraproject.org/updates/?search=borgmatic)
* [Gentoo](https://packages.gentoo.org/packages/app-backup/borgmatic)
* [Arch Linux](https://archlinux.org/packages/extra/any/borgmatic/)
* [Alpine Linux](https://pkgs.alpinelinux.org/packages?name=borgmatic)
* [OpenBSD](https://openports.pl/path/sysutils/borgmatic)
* [openSUSE](https://software.opensuse.org/package/borgmatic)
* [macOS (via Homebrew)](https://formulae.brew.sh/formula/borgmatic)
* [macOS (via MacPorts)](https://ports.macports.org/port/borgmatic/)
* [NixOS](https://search.nixos.org/packages?channel=unstable&show=borgmatic&query=borgmatic)
#### Etc.
* [Ansible role](https://github.com/borgbase/ansible-role-borgbackup)
* [uv tool install](https://docs.astral.sh/uv/)
## Hosting providers
Need somewhere to store your encrypted off-site backups? The following hosting
providers include specific support for Borg/borgmatic—and fund borgmatic
development and hosting when you use these referral links to sign up:
<ul>
<li class="referral"><a href="https://www.borgbase.com/?utm_source=borgmatic">BorgBase</a>: Borg hosting service with support for monitoring, 2FA, and append-only repos</li>
<li class="referral"><a href="https://hetzner.cloud/?ref=v9dOJ98Ic9I8">Hetzner</a>: A "storage box" that includes support for Borg</li>
</ul>
Additionally, rsync.net has a compatible storage offering, but does not fund
borgmatic development or hosting.
## Configuration
After you install borgmatic, generate a sample configuration file:
```bash
sudo borgmatic config generate
```
<span class="minilink minilink-addedin">Prior to version 1.7.15</span>
Generate a configuration file with this command instead:
```bash
sudo generate-borgmatic-config
```
If neither command is found, then borgmatic may be installed in a location
that's not in your system `PATH` (see above). Try looking in `~/.local/bin/`.
The command generates a sample configuration file at
`/etc/borgmatic/config.yaml` by default. If you'd like to use another path,
use the `--destination` flag, for instance: `--destination
~/.config/borgmatic/config.yaml`.
You should edit the configuration file to suit your needs, as the generated
values are only representative. All options are optional except where
indicated, so feel free to ignore anything you don't need. Be sure to use
spaces rather than tabs for indentation; YAML does not allow tabs.
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> The
configuration file was organized into distinct sections, each with a section
name like `location:` or `storage:`. So in older versions of borgmatic, take
care that if you uncomment a particular option, also uncomment its containing
section name—or else borgmatic won't recognize the option.
You can get the same sample configuration file from the [configuration
reference](https://torsion.org/borgmatic/reference/configuration/), the
authoritative set of all configuration options. This is handy if borgmatic has
added new options since you originally created your configuration file. Also
check out how to [upgrade your
configuration](https://torsion.org/borgmatic/how-to/upgrade/#upgrading-your-configuration).
And see the documentation on [patterns and
excludes](https://torsion.org/borgmatic/reference/configuration/patterns-and-excludes/).
### Encryption
If you encrypt your Borg repository with a passphrase or a key file, you'll
either need to set the borgmatic `encryption_passphrase` configuration
variable or set the `BORG_PASSPHRASE` environment variable. See the
[repository encryption
section](https://borgbackup.readthedocs.io/en/stable/quickstart.html#repository-encryption)
of the Borg Quick Start for more info.
Alternatively, you can specify the passphrase programmatically by setting
either the borgmatic `encryption_passcommand` configuration variable or the
`BORG_PASSCOMMAND` environment variable. See the [Borg Security
FAQ](http://borgbackup.readthedocs.io/en/stable/faq.html#how-can-i-specify-the-encryption-passphrase-programmatically)
for more info.
### Redundancy
If you'd like to configure your backups to go to multiple different
repositories, see the documentation on how to [make backups
redundant](https://torsion.org/borgmatic/how-to/make-backups-redundant/).
### Validation
If you'd like to validate that your borgmatic configuration is valid, the
following command is available for that:
```bash
sudo borgmatic config validate
```
<span class="minilink minilink-addedin">Prior to version 1.7.15</span>
Validate a configuration file with this command instead:
```bash
sudo validate-borgmatic-config
```
You'll need to specify your configuration file with `--config` if it's not in
a default location.
This command's exit status (`$?` in Bash) is zero when configuration is valid
and non-zero otherwise.
Validating configuration can be useful if you generate your configuration
files via configuration management, or you want to double check that your hand
edits are valid.
## Repository creation
Before you can create backups with borgmatic, you first need to create a Borg
repository so you have a destination for your backup archives. (But skip this
step if you already have a Borg repository.) To create a repository, assuming
it's already [specified in borgmatic's
configuration](https://torsion.org/borgmatic/reference/configuration/repositories/),
run a command like the following with Borg 1.x:
```bash
sudo borgmatic repo-create --encryption repokey
```
<span class="minilink minilink-addedin">Prior to borgmatic version 1.9.0</span>
The `repo-create` action was called `init`.
<span class="minilink minilink-addedin">With Borg version 2.x</span> Borg 2.x
uses more specific encryption modes like `repokey-aes-ocb`. For example:
```bash
sudo borgmatic repo-create --encryption repokey-aes-ocb
```
(Note that `repokey-chacha20-poly1305` may be faster than `repokey-aes-ocb` on
certain platforms like ARM64.)
This uses the borgmatic configuration file you created above to determine
which local or remote repository to create and encrypts it with the
encryption passphrase specified there if one is provided. Read about [Borg
encryption
modes](https://borgbackup.readthedocs.io/en/stable/usage/init.html#encryption-mode-tldr)
for the menu of available encryption modes.
Also, optionally check out the [Borg Quick
Start](https://borgbackup.readthedocs.org/en/stable/quickstart.html) for more
background about repository creation.
Note that borgmatic skips repository creation if the repository already
exists. This supports use cases like ensuring a repository exists prior to
performing a backup.
If the repository is on a remote host, make sure that your local user has
key-based SSH access to the desired user account on the remote host.
## Backups
Now that you've configured borgmatic and created a repository, it's a good
idea to test that borgmatic is working. So to run borgmatic and start a
backup, you can invoke it like this:
```bash
sudo borgmatic create --verbosity 1 --list --stats
```
(No borgmatic `--list` flag? Try `--files` instead, leave it out, or upgrade
borgmatic!)
The `--verbosity` flag makes borgmatic show the steps it's performing. The
`--list` flag lists each file that's new or changed since the last backup. And
`--stats` shows summary information about the created archive. All of these
flags are optional.
As the command runs, you should eyeball the output to see if it matches your
expectations based on your configuration.
If you'd like to specify an alternate configuration file path, use the
`--config` flag.
See [command-line
documentation](https://torsion.org/borgmatic/reference/command-line/) and the
[create action
documentation](https://torsion.org/borgmatic/reference/command-line/actions/create/)
for more information.
<a id="default-actions"></a>
<a id="skipping-actions"></a>
<a id="disabling-default-actions"></a>
And check out the [actions
documentation](https://torsion.org/borgmatic/reference/command-line/actions/)
for details on customizing the actions that borgmatic runs.
## Autopilot
Running backups manually is good for validating your configuration, but I'm
guessing that you want to run borgmatic automatically, say once a day. To do
that, you can configure a separate job runner to invoke it periodically.
### cron
If you're using cron, download the [sample cron
file](https://projects.torsion.org/borgmatic-collective/borgmatic/src/main/sample/cron/borgmatic).
Then, from the directory where you downloaded it:
```bash
sudo mv borgmatic /etc/cron.d/borgmatic
```
If borgmatic is installed at a different location than
`/root/.local/bin/borgmatic`, edit the cron file with the correct path. You
can also modify the cron file if you'd like to run borgmatic more or less
frequently.
### systemd
If you're using systemd instead of cron to run jobs, you can still configure
borgmatic to run automatically.
(If you installed borgmatic from [Other ways to
install](https://torsion.org/borgmatic/how-to/set-up-backups/#other-ways-to-install),
you may already have borgmatic systemd service and timer files. If so, you may
be able to skip some of the steps below.)
First, download the [sample systemd service
file](https://projects.torsion.org/borgmatic-collective/borgmatic/raw/branch/main/sample/systemd/borgmatic.service)
and the [sample systemd timer
file](https://projects.torsion.org/borgmatic-collective/borgmatic/raw/branch/main/sample/systemd/borgmatic.timer).
Then, from the directory where you downloaded them:
```bash
sudo mv borgmatic.service borgmatic.timer /etc/systemd/system/
sudo systemctl enable --now borgmatic.timer
```
Review the security settings in the service file and update them as needed.
If `ProtectSystem=strict` is enabled and local repositories are used, then
the repository path must be added to the `ReadWritePaths` list.
Feel free to modify the timer file based on how frequently you'd like
borgmatic to run.
### launchd in macOS
If you run borgmatic in macOS with launchd, you may encounter permissions
issues when reading files to backup. If that happens to you, you may be
interested in an [unofficial work-around for Full Disk
Access](https://projects.torsion.org/borgmatic-collective/borgmatic/issues/293).
## Niceties
<a id="shell-completion"></a>
<a id="bash"></a>
<a id="fish"></a>
### Command-line autocompletion
borgmatic includes autocompletion scripts for various command-line shells to
support tab-completing command-line actions and flags. See the [autocompletion
documentation](https://torsion.org/borgmatic/reference/command-line/autocompletion/)
for details.
### Colored output
borgmatic produces colored terminal output by default. It is disabled when a
non-interactive terminal is detected (like a cron job), or when you use the
`--json` flag. Otherwise, you can disable it by passing the `--no-color` flag,
setting the environment variables `PY_COLORS=False` or `NO_COLOR=True`, or
setting the `color` option to `false` in the `output` section of
configuration.
## Troubleshooting
### "found character that cannot start any token" error
If you run borgmatic and see an error looking something like this, it probably
means you've used tabs instead of spaces:
```
test.yaml: Error parsing configuration file
An error occurred while parsing a configuration file at config.yaml:
while scanning for the next token
found character that cannot start any token
in "config.yaml", line 230, column 1
```
YAML does not allow tabs. So to fix this, replace any tabs in your
configuration file with the requisite number of spaces.
### libyaml compilation errors
borgmatic depends on a Python YAML library (ruamel.yaml) that will optionally
use a C YAML library (libyaml) if present. But if it's not installed, then
when installing or upgrading borgmatic, you may see errors about compiling the
YAML library. If so, not to worry. borgmatic should install and function
correctly even without the C YAML library. And borgmatic won't be any faster
with the C library present, so you don't need to go out of your way to install
it.

147
docs/how-to/snapshot-your-filesystems.md
View file

@ -1,147 +0,0 @@
---
title: 📸 How to snapshot your filesystems
eleventyNavigation:
key: 📸 Snapshot your filesystems
parent: How-to guides
order: 9
---
Many filesystems support taking snapshots—point-in-time, read-only "copies" of
your data, ideal for backing up files that may change during the backup. These
snapshots initially don't use any additional storage space and can be made
almost instantly.
To help automate backup of these filesystems, borgmatic can use them to take
snapshots.
<a id="dataset-discovery"></a>
<a id="zfs-performance"></a>
### ZFS
<span class="minilink minilink-addedin">New in version 1.9.3</span> borgmatic
supports taking snapshots with the [ZFS filesystem](https://openzfs.org/) and
sending those snapshots to Borg for backup.
To use this feature, add one or more ZFS dataset paths to your
`source_directories`. Then, enable borgmatic's ZFS snapshotting of those
datasets by adding the following line to your configuration file:
```yaml
zfs:
```
No other options are necessary to enable ZFS support. But if you're using
systemd to run borgmatic, you'll likely need to modify the [sample systemd
service
file](https://projects.torsion.org/borgmatic-collective/borgmatic/raw/branch/main/sample/systemd/borgmatic.service)
to work with ZFS. See the comments in that file for details.
As long as the ZFS hook is in beta, it may be subject to breaking changes
and/or may not work well for your use cases. But feel free to use it in
production if you're okay with these caveats, and please [provide any
feedback](https://torsion.org/borgmatic/#issues) you have on this feature.
For additional details about ZFS support, see [borgmatic's ZFS
documentation](https://torsion.org/borgmatic/reference/configuration/data-sources/zfs/).
#### Extract a dataset
Filesystem snapshots are stored in a Borg archive as normal files, so
you can use the standard
[extract action](https://torsion.org/borgmatic/how-to/extract-a-backup/) to
extract them.
<a id="subvolume-discovery"></a>
<a id="btrfs-performance"></a>
### Btrfs
<span class="minilink minilink-addedin">New in version 1.9.4</span> borgmatic
supports taking snapshots with the [Btrfs
filesystem](https://btrfs.readthedocs.io/) and sending those snapshots to Borg
for backup.
To use this feature, add one or more subvolume paths to your
`source_directories`. Then, enable Btrfs within borgmatic by adding the
following line to your configuration file:
```yaml
btrfs:
```
No other options are necessary to enable Btrfs support. But if you're using
systemd to run borgmatic, you may need to modify the [sample systemd service
file](https://projects.torsion.org/borgmatic-collective/borgmatic/raw/branch/main/sample/systemd/borgmatic.service)
to work with Btrfs. See the comments in that file for details.
As long as the Btrfs hook is in beta, it may be subject to breaking changes
and/or may not work well for your use cases. But feel free to use it in
production if you're okay with these caveats, and please [provide any
feedback](https://torsion.org/borgmatic/#issues) you have on this feature.
For additional details about Btrfs support, see [borgmatic's Btrfs
documentation](https://torsion.org/borgmatic/reference/configuration/data-sources/btrfs/).
#### Extract a subvolume
Subvolume snapshots are stored in a Borg archive as normal files, so you can use
the standard [extract
action](https://torsion.org/borgmatic/how-to/extract-a-backup/) to extract
them.
<a id="snapshot-size"></a>
<a id="logical-volume-discovery"></a>
<a id="lvm-performance"></a>
### LVM
<span class="minilink minilink-addedin">New in version 1.9.4</span> borgmatic
supports taking snapshots with [LVM](https://sourceware.org/lvm2/) (Linux
Logical Volume Manager) and sending those snapshots to Borg for backup. LVM
isn't itself a filesystem, but it can take snapshots at the layer right below
your filesystem.
Note that, due to Borg being a file-level backup, this feature is really only
suitable for filesystems, not whole disk or raw images containing multiple
filesystems (for example, if you're using a LVM volume to run a Windows
KVM that contains an MBR, partitions, etc.).
In those cases, you can omit the `lvm:` option and use Borg's own support for
[image backup](https://borgbackup.readthedocs.io/en/stable/deployment/image-backup.html).
To use the LVM snapshot feature, add one or more mounted LVM logical volumes to
your `source_directories`. Then, enable LVM within borgmatic by adding the
following line to your configuration file:
```yaml
lvm:
```
No other options are necessary to enable LVM support. But if you're using
systemd to run borgmatic, you may need to modify the [sample systemd service
file](https://projects.torsion.org/borgmatic-collective/borgmatic/raw/branch/main/sample/systemd/borgmatic.service)
to work with LVM. See the comments in that file for details.
As long as the LVM hook is in beta, it may be subject to breaking changes
and/or may not work well for your use cases. But feel free to use it in
production if you're okay with these caveats, and please [provide any
feedback](https://torsion.org/borgmatic/#issues) you have on this feature.
For additional details about LVM support, see [borgmatic's LVM
documentation](https://torsion.org/borgmatic/reference/configuration/data-sources/lvm/).
#### Extract a logical volume
Logical volume snapshots are stored in a Borg archive as normal files, so
you can use the standard
[extract action](https://torsion.org/borgmatic/how-to/extract-a-backup/) to
extract them.

198
docs/how-to/upgrade.md
View file

@ -1,198 +0,0 @@
---
title: 📦 How to upgrade borgmatic and Borg
eleventyNavigation:
key: 📦 Upgrade borgmatic/Borg
parent: How-to guides
order: 14
---
In general, all you should need to do to upgrade borgmatic if you've
[installed it with
pipx](https://torsion.org/borgmatic/how-to/set-up-backups/#installation)
is to run the following:
```bash
sudo pipx upgrade borgmatic
```
Omit `sudo` if you installed borgmatic as a non-root user. And if you
installed borgmatic *both* as root and as a non-root user, you'll need to
upgrade each installation independently.
If you originally installed borgmatic with `sudo pip3 install --user`, you can
uninstall it first with `sudo pip3 uninstall borgmatic` and then [install it
again with
pipx](https://torsion.org/borgmatic/how-to/set-up-backups/#installation),
which should better isolate borgmatic from your other Python applications.
But if you [installed borgmatic without pipx or
pip3](https://torsion.org/borgmatic/how-to/set-up-backups/#other-ways-to-install),
then your upgrade method may be different.
### Upgrading your configuration
The borgmatic configuration file format is usually backwards-compatible from
release to release without any changes, but you may still want to update your
configuration file when you upgrade to take advantage of new configuration
options or avoid old configuration from eventually becoming unsupported. If
you prefer, you can add new configuration options manually.
If you do want to upgrade your configuration file to include new options, use
the `borgmatic config generate` action with its optional `--source` flag that
takes the path to your original configuration file. If provided with this
path, `borgmatic config generate` merges your original configuration into the
generated configuration file, so you get all the newest options and comments.
Here's an example:
```bash
borgmatic config generate --source config.yaml --destination config-new.yaml
```
<span class="minilink minilink-addedin">Prior to version 1.7.15</span> The
command to generate configuration files was `generate-borgmatic-config`
instead of `borgmatic config generate`.
New options start as commented out, so you can edit the file and decide
whether you want to use each one.
There are a few caveats to this process. First, when generating the new
configuration file, `borgmatic config generate` replaces any comments you've
written in your original configuration file with the newest generated
comments. Second, the script adds back any options you had originally deleted,
although it does so with the options commented out. And finally, any YAML
includes you've used in the source configuration get flattened out into a
single generated file.
As a safety measure, `borgmatic config generate` refuses to modify
configuration files in-place. So it's up to you to review the generated file
and, if desired, replace your original configuration file with it.
### Upgrading from borgmatic 1.0.x
borgmatic changed its configuration file format in version 1.1.0 from
INI-style to YAML. This better supports validation and has a more natural way
to express lists of values. Modern versions of borgmatic no longer include
support for upgrading configuration files this old, but feel free to [file a
ticket](https://torsion.org/borgmatic/#issues) for help with upgrading any old
INI-style configuration files you may have.
### Versioning and breaking changes
To avoid version number bloat, borgmatic doesn't follow traditional semantic
versioning. But here's how borgmatic versioning generally works:
* Major version bumps (e.g., 1 to 2): Major breaking changes. Configuration
file formats might change, deprecated features may be removed entirely, etc.
* Minor version bumps (e.g., 1.8 to 1.9): Medium breaking changes. Depending
on the features you use, this may be a drop-in replacement. But read the
release notes to make sure.
* Patch version bumps (e.g., 1.8.13 to 1.8.14): Minor breaking changes. These
include, for instance, bug fixes that are technically breaking but may only
affect a small subset of users.
Each breaking change is prefixed with "BREAKING:" in [borgmatic's release
notes](https://projects.torsion.org/borgmatic-collective/borgmatic/releases),
so there should hopefully be no surprises.
## Upgrading Borg
To upgrade to a new version of Borg, you can generally install a new version
the same way you installed the previous version, paying attention to any
instructions included with each Borg release changelog linked from the
[releases page](https://github.com/borgbackup/borg/releases). Some more major
Borg releases require additional steps that borgmatic can help with.
### Borg 1.2 to 2.0
<span class="minilink minilink-addedin">New in borgmatic version 1.9.0</span>
Upgrading Borg from 1.2 to 2.0 requires manually upgrading your existing Borg
1 repositories before use with Borg or borgmatic. Here's how you can
accomplish that.
Start by upgrading borgmatic as described above to at least version 1.7.0 and
Borg to 2.0. Then, rename your repository in borgmatic's configuration file to
a new repository path. The repository upgrade process does not occur
in-place; you'll create a new repository with a copy of your old repository's
data.
Let's say your original borgmatic repository configuration file looks something
like this:
```yaml
repositories:
- path: original.borg
```
Change it to a new (not yet created) repository path:
```yaml
repositories:
- path: upgraded.borg
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> This
option was found in the `location:` section of your configuration.
<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
the `path:` portion of the `repositories` list.
Then, run the `repo-create` action (formerly `init`) to create that new Borg 2
repository:
```bash
borgmatic repo-create --verbosity 1 --encryption repokey-blake2-aes-ocb \
--source-repository original.borg --repository upgraded.borg
```
This creates an empty repository and doesn't actually transfer any data yet.
The `--source-repository` flag is necessary to reuse key material from your
Borg 1 repository so that the subsequent data transfer can work.
The `--encryption` value above selects the same chunk ID algorithm (`blake2`)
commonly used in Borg 1, thereby making deduplication work across transferred
archives and new archives.
If you get an error about "You must keep the same ID hash" from Borg, that
means the encryption value you specified doesn't correspond to your source
repository's chunk ID algorithm. In that case, try not using `blake2`:
```bash
borgmatic repo-create --verbosity 1 --encryption repokey-aes-ocb \
--source-repository original.borg --repository upgraded.borg
```
Read about [Borg encryption
modes](https://borgbackup.readthedocs.io/en/latest/usage/repo-create.html)
for more details.
To transfer data from your original Borg 1 repository to your newly created
Borg 2 repository:
```bash
borgmatic transfer --verbosity 1 --upgrader From12To20 --source-repository \
original.borg --repository upgraded.borg --dry-run
borgmatic transfer --verbosity 1 --upgrader From12To20 --source-repository \
original.borg --repository upgraded.borg
borgmatic transfer --verbosity 1 --upgrader From12To20 --source-repository \
original.borg --repository upgraded.borg --dry-run
```
The first command with `--dry-run` tells you what Borg is going to do during
the transfer, the second command actually performs the transfer/upgrade (this
might take a while), and the final command with `--dry-run` again provides
confirmation of success—or tells you if something hasn't been transferred yet.
Note that by omitting the `--upgrader` flag, you can also do archive transfers
between related Borg 2 repositories without upgrading, even down to individual
archives. For more on that functionality, see the [Borg transfer
documentation](https://borgbackup.readthedocs.io/en/2.0.0b16/usage/transfer.html).
That's it! Now you can use your new Borg 2 repository as normal with
borgmatic. If you've got multiple repositories, repeat the above process for
each.

17
docs/reference/command-line/actions/borg.md
View file

@ -1,17 +0,0 @@
---
title: borg
eleventyNavigation:
key: borg
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/borg.txt %}
```
## Related documentation
* [How to run arbitrary Borg commands](https://torsion.org/borgmatic/how-to/run-arbitrary-borg-commands/)

12
docs/reference/command-line/actions/break-lock.md
View file

@ -1,12 +0,0 @@
---
title: break-lock
eleventyNavigation:
key: break-lock
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/break-lock.txt %}
```

16
docs/reference/command-line/actions/check.md
View file

@ -1,16 +0,0 @@
---
title: check
eleventyNavigation:
key: check
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/check.txt %}
```
## Related documentation
* [Consistency checks](https://torsion.org/borgmatic/reference/configuration/consistency-checks/)

12
docs/reference/command-line/actions/compact.md
View file

@ -1,12 +0,0 @@
---
title: compact
eleventyNavigation:
key: compact
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/compact.txt %}
```

17
docs/reference/command-line/actions/config-bootstrap.md
View file

@ -1,17 +0,0 @@
---
title: config bootstrap
eleventyNavigation:
key: config bootstrap
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/config-bootstrap.txt %}
```
## Related documentation
* [Extract the configuration files used to create an archive](https://torsion.org/borgmatic/how-to/extract-a-backup/#extract-the-configuration-files-used-to-create-an-archive)

17
docs/reference/command-line/actions/config-generate.md
View file

@ -1,17 +0,0 @@
---
title: config generate
eleventyNavigation:
key: config generate
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/config-generate.txt %}
```
## Related documentation
* [Configuration](https://torsion.org/borgmatic/how-to/set-up-backups/#configuration)

17
docs/reference/command-line/actions/config-show.md
View file

@ -1,17 +0,0 @@
---
title: config show
eleventyNavigation:
key: config show
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/config-show.txt %}
```
## Related documentation
* [Scripting borgmatic](https://torsion.org/borgmatic/how-to/monitor-your-backups/#scripting-borgmatic)

17
docs/reference/command-line/actions/config-validate.md
View file

@ -1,17 +0,0 @@
---
title: config validate
eleventyNavigation:
key: config validate
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/config-validate.txt %}
```
## Related documentation
* [Validation](https://torsion.org/borgmatic/how-to/set-up-backups/#validation)

12
docs/reference/command-line/actions/config.md
View file

@ -1,12 +0,0 @@
---
title: config
eleventyNavigation:
key: config
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/config.txt %}
```

17
docs/reference/command-line/actions/create.md
View file

@ -1,17 +0,0 @@
---
title: create
eleventyNavigation:
key: create
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/create.txt %}
```
## Related documentation
* [Backups](https://torsion.org/borgmatic/how-to/set-up-backups/#backups)

12
docs/reference/command-line/actions/delete.md
View file

@ -1,12 +0,0 @@
---
title: delete
eleventyNavigation:
key: delete
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/delete.txt %}
```

12
docs/reference/command-line/actions/export-tar.md
View file

@ -1,12 +0,0 @@
---
title: export-tar
eleventyNavigation:
key: export-tar
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/export-tar.txt %}
```

17
docs/reference/command-line/actions/extract.md
View file

@ -1,17 +0,0 @@
---
title: extract
eleventyNavigation:
key: extract
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/extract.txt %}
```
## Related documentation
* [How to extract a backup](https://torsion.org/borgmatic/how-to/extract-a-backup/)

95
docs/reference/command-line/actions/index.md
View file

@ -1,95 +0,0 @@
---
title: 🎬 Actions
eleventyNavigation:
key: 🎬 Actions
parent: 💻 Command-line
---
An action in borgmatic is like a subcommand in Borg. The `create` action creates
a backup, the `list` action shows the files in an archive, and so on.
## Available actions
{{ collections.all | eleventyNavigation: "🎬 Actions" | eleventyNavigationToHtml | replace: 'href="/reference/', 'href="/borgmatic/reference/' }}
## Default actions
If you omit `create` and other actions from the command-line, borgmatic runs
through a set of default actions:
1. `prune` any old backups as per the configured retention policy
2. `compact` segments to free up space (with Borg 1.2+ and borgmatic 1.5.23+)
3. `create` a backup
4. `check` backups for consistency problems due to things like file damage
<span class="minilink minilink-addedin">Prior to version 1.7.9</span> The
default action ordering was `prune`, `compact`, `create`, and `check`.
### Disabling default actions
If you want to disable this default action behavior and require explicit actions
to be specified, add the following to your configuration:
```yaml
default_actions: false
```
With this setting, running `borgmatic` without arguments will show the help
message instead of performing any actions.
## A la carte actions
If you find yourself wanting to customize the actions, you have some options.
First, you can run borgmatic's `create`, `prune`, `compact`, or `check`
actions separately. For instance, the following optional actions are
available (among others):
```bash
borgmatic create
borgmatic prune
borgmatic compact
borgmatic check
```
You can run borgmatic with only one of these actions provided, or you can mix
and match any number of them in a single borgmatic run. This supports
approaches like skipping certain actions while running others. For instance,
this skips `prune` and `compact` and only runs `create` and `check`:
```bash
borgmatic create check
```
<span class="minilink minilink-addedin">New in version 1.7.9</span> borgmatic
now respects your specified command-line action order, running actions in the
order you specify. In previous versions, borgmatic ran your specified actions
in a fixed ordering regardless of the order they appeared on the command-line.
But instead of running actions together, another option is to run backups with
`create` on a frequent schedule (e.g. with `borgmatic create` called from one
cron job), while only running expensive consistency checks with `check` on a
much less frequent basis (e.g. with `borgmatic check` called from a separate
cron job).
<span class="minilink minilink-addedin">New in version 1.8.5</span> Instead of
(or in addition to) specifying actions on the command-line, you can configure
borgmatic to [skip particular
actions](https://torsion.org/borgmatic/reference/command-line/actions/#skipping-actions).
### Skipping actions
<span class="minilink minilink-addedin">New in version 1.8.5</span> You can
configure borgmatic to skip running certain actions (default or otherwise).
For instance, to always skip the `compact` action (e.g., when using [Borg's
append-only
mode](https://borgbackup.readthedocs.io/en/stable/usage/notes.html#append-only-mode-forbid-compaction)),
set the `skip_actions` option in your configuration:
```yaml
skip_actions:
- compact
```

17
docs/reference/command-line/actions/info.md
View file

@ -1,17 +0,0 @@
---
title: info
eleventyNavigation:
key: info
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/info.txt %}
```
## Related documentation
* [How to inspect your backups](https://torsion.org/borgmatic/how-to/inspect-your-backups/)

12
docs/reference/command-line/actions/key-change-passphrase.md
View file

@ -1,12 +0,0 @@
---
title: key change-passphrase
eleventyNavigation:
key: key change-passphrase
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/key-change-passphrase.txt %}
```

12
docs/reference/command-line/actions/key-export.md
View file

@ -1,12 +0,0 @@
---
title: key export
eleventyNavigation:
key: key export
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/key-export.txt %}
```

12
docs/reference/command-line/actions/key-import.md
View file

@ -1,12 +0,0 @@
---
title: key import
eleventyNavigation:
key: key import
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/key-import.txt %}
```

17
docs/reference/command-line/actions/list.md
View file

@ -1,17 +0,0 @@
---
title: list
eleventyNavigation:
key: list
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/list.txt %}
```
## Related documentation
* [How to inspect your backups](https://torsion.org/borgmatic/how-to/inspect-your-backups/)

17
docs/reference/command-line/actions/mount.md
View file

@ -1,17 +0,0 @@
---
title: mount
eleventyNavigation:
key: mount
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/mount.txt %}
```
## Related documentation
* [Mount a filesystem](https://torsion.org/borgmatic/how-to/extract-a-backup/#mount-a-filesystem)

12
docs/reference/command-line/actions/prune.md
View file

@ -1,12 +0,0 @@
---
title: prune
eleventyNavigation:
key: prune
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/prune.txt %}
```

12
docs/reference/command-line/actions/recreate.md
View file

@ -1,12 +0,0 @@
---
title: recreate
eleventyNavigation:
key: recreate
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/recreate.txt %}
```

17
docs/reference/command-line/actions/repo-create.md
View file

@ -1,17 +0,0 @@
---
title: repo-create
eleventyNavigation:
key: repo-create
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/repo-create.txt %}
```
## Related documentation
* [Repository creation](https://torsion.org/borgmatic/how-to/set-up-backups/#repository-creation)

12
docs/reference/command-line/actions/repo-delete.md
View file

@ -1,12 +0,0 @@
---
title: repo-delete
eleventyNavigation:
key: repo-delete
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/repo-delete.txt %}
```

17
docs/reference/command-line/actions/repo-info.md
View file

@ -1,17 +0,0 @@
---
title: repo-info
eleventyNavigation:
key: repo-info
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/repo-info.txt %}
```
## Related documentation
* [How to inspect your backups](https://torsion.org/borgmatic/how-to/inspect-your-backups/)

17
docs/reference/command-line/actions/repo-list.md
View file

@ -1,17 +0,0 @@
---
title: repo-list
eleventyNavigation:
key: repo-list
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/repo-list.txt %}
```
## Related documentation
* [How to inspect your backups](https://torsion.org/borgmatic/how-to/inspect-your-backups/)

17
docs/reference/command-line/actions/restore.md
View file

@ -1,17 +0,0 @@
---
title: restore
eleventyNavigation:
key: restore
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/restore.txt %}
```
## Related documentation
* [Database restoration](https://torsion.org/borgmatic/how-to/backup-your-databases/#database-restoration)

16
docs/reference/command-line/actions/transfer.md
View file

@ -1,16 +0,0 @@
---
title: transfer
eleventyNavigation:
key: transfer
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/transfer.txt %}
```
## Related documentation
* [Upgrade Borg 1.2 to 2.0](https://torsion.org/borgmatic/how-to/upgrade/#borg-1.2-to-2.0)

17
docs/reference/command-line/actions/umount.md
View file

@ -1,17 +0,0 @@
---
title: umount
eleventyNavigation:
key: umount
parent: 🎬 Actions
---
{% include snippet/command-line/sample.md %}
```
{% include borgmatic/command-line/umount.txt %}
```
## Related documentation
* [Mount a filesystem](https://torsion.org/borgmatic/how-to/extract-a-backup/#mount-a-filesystem)

36
docs/reference/command-line/autocompletion/bash.md
View file

@ -1,36 +0,0 @@
---
title: bash
eleventyNavigation:
key: bash
parent: ➡️ Autocompletion
---
borgmatic includes an autocompletion script for
[Bash](https://www.gnu.org/software/bash/) to support tab-completing
command-line actions and flags. Depending on how you installed borgmatic, this
may be enabled by default.
If completions aren't enabled, start by installing the `bash-completion` Linux
package or the
[`bash-completion@2`](https://formulae.brew.sh/formula/bash-completion@2) macOS
Homebrew formula. Then, install the shell completion script globally:
```bash
sudo su -c "borgmatic --bash-completion > $(pkg-config --variable=completionsdir bash-completion)/borgmatic"
```
If you don't have `pkg-config` installed, you can try the following path
instead:
```bash
sudo su -c "borgmatic --bash-completion > /usr/share/bash-completion/completions/borgmatic"
```
Or, if you'd like to install the script for only the current user:
```bash
mkdir --parents ~/.local/share/bash-completion/completions
borgmatic --bash-completion > ~/.local/share/bash-completion/completions/borgmatic
```
Finally, restart your shell (`exit` and open a new shell) so the completions
take effect.

17
docs/reference/command-line/autocompletion/fish.md
View file

@ -1,17 +0,0 @@
---
title: fish
eleventyNavigation:
key: fish
parent: ➡️ Autocompletion
---
borgmatic includes an autocompletion script for [fish
shell](https://fishshell.com/) to support tab-completing command-line actions
and flags. Depending on how you installed borgmatic, this may be enabled by
default.
If completions aren't enabled, install the completions file globally:
```shell
borgmatic --fish-completion | sudo tee /usr/share/fish/vendor_completions.d/borgmatic.fish
source /usr/share/fish/vendor_completions.d/borgmatic.fish
```

13
docs/reference/command-line/autocompletion/index.md
View file

@ -1,13 +0,0 @@
---
title: ➡️ Autocompletion
eleventyNavigation:
key: ➡️ Autocompletion
parent: 💻 Command-line
---
borgmatic includes autocompletion scripts for various command-line shells to
support tab-completing command-line actions and flags. Depending on how you
installed borgmatic, this may be enabled by default. Here are the supported
shells and how to configure borgmatic autocompletion for each:
{{ collections.all | eleventyNavigation: "➡️ Autocompletion" | eleventyNavigationToHtml | replace: 'href="/reference/', 'href="/borgmatic/reference/' }}

26
docs/reference/command-line/index.md
View file

@ -1,26 +0,0 @@
---
title: 💻 Command-line
eleventyNavigation:
key: 💻 Command-line
parent: Reference guides
order: 1
---
Here are all of the available global borgmatic command-line flags for the [most
recent version of
borgmatic](https://projects.torsion.org/borgmatic-collective/borgmatic/releases),
including the separate flags for each action (sub-command). Most of the flags
listed here have equivalents in borgmatic's [configuration
file](https://torsion.org/borgmatic/reference/configuration/).
Also see the [actions
documentation](https://torsion.org/borgmatic/reference/command-line/actions/)
for the command-line flags for individual actions.
If you're using an older version of borgmatic, some of these flags may not be
present in that version and you should instead use `borgmatic --help` or
`borgmatic [action name] --help` (where `[action name]` is the name of an
action like `list`, `create`, etc.).
```
{% include borgmatic/command-line/global.txt %}
```

179
docs/reference/command-line/logging.md
View file

@ -1,179 +0,0 @@
---
title: 🪵 Logging
eleventyNavigation:
key: 🪵 Logging
parent: 💻 Command-line
---
By default, borgmatic runs proceed silently except in the case of warnings or
errors. But if you'd like to to get additional information about the progress of
the backup as it proceeds, use the verbosity option:
```bash
borgmatic --verbosity 1
```
Or, for even more progress and debug spew:
```bash
borgmatic --verbosity 2
```
The full set of verbosity levels are:
* `-2`: disable output entirely <span class="minilink minilink-addedin">New in borgmatic 1.7.14</span>
* `-1`: only show errors
* `0`: default output
* `1`: some additional output (informational level)
* `2`: lots of additional output (debug level)
<span class="minilink minilink-addedin">New in version 2.0.0</span>Set the
verbosity in your borgmatic configuration via the `verbosity` option.
Additionally, for the `create` action in particular, you can include the
`--list` flag to list the files that borgmatic is archiving—those files
that are new or changed since the last backup.
### JSON logging
<span class="minilink minilink-addedin">New in version 2.1.0</span>With the
`--log-json` flag, borgmatic logs both its own logs and Borg's output as JSON.
The `--log-json` flag applies to console output and any log file (see below).
## Logging to syslog
By default, borgmatic only logs its output to the console. You can enable
simultaneous syslog logging and customize its log level with the
`--syslog-verbosity` flag, which is independent from the console logging
`--verbosity` flag described above. For instance, to enable syslog logging,
run:
```bash
borgmatic --syslog-verbosity 1
```
To increase syslog logging further to include debugging information, run:
```bash
borgmatic --syslog-verbosity 2
```
See above for further details about the verbosity levels.
<span class="minilink minilink-addedin">New in version 2.0.0</span>Set the
syslog verbosity in your borgmatic configuration via the `syslog_verbosity`
option.
Where these logs show up depends on your particular system. If you're using
systemd, try running `journalctl -xe`. Otherwise, try viewing
`/var/log/syslog` or similar.
<span class="minilink minilink-addedin">Prior to version 1.8.3</span>borgmatic
logged to syslog by default whenever run at a non-interactive console.
### Systemd journal
<span class="minilink minilink-addedin">New in version 2.1.0</span>If the syslog
verbosity is set and systemd's journal is present, then borgmatic sends
structured logs to the journal instead of plain text. This allows you to query
logs by particular fields. For instance:
```bash
journalctl --catalog --pager-end SYSLOG_IDENTIFIER=borgmatic
```
Or to view just borgmatic warning and error logs:
```bash
journalctl --catalog --pager-end SYSLOG_IDENTIFIER=borgmatic --priority warning..alert
```
The fields borgmatic sends are:
* `MESSAGE`: the log message
* `PRIORITY`: the [numeric priority level](https://wiki.archlinux.org/title/Systemd/Journal#Priority_level) for the log entry
* `SYSLOG_IDENTIFIER`: `borgmatic`
* `SYSLOG_PID`: borgmatic's process ID
You can also output these structured logs as JSON:
```bash
journalctl --output=json SYSLOG_IDENTIFIER=borgmatic
```
Note that systemd's journal adds its own fields to the JSON on top of the fields
that borgmatic logs.
### Rate limiting
If you are using rsyslog or systemd's journal, be aware that by default they
both throttle the rate at which logging occurs. So you may need to change
either [the global rate
limit](https://www.rootusers.com/how-to-change-log-rate-limiting-in-linux/) or
[the per-service rate
limit](https://www.freedesktop.org/software/systemd/man/journald.conf.html#RateLimitIntervalSec=)
if you're finding that borgmatic logs are missing.
Note that the [sample borgmatic systemd service
file](https://torsion.org/borgmatic/how-to/set-up-backups/#systemd)
already has this rate limit disabled for systemd's journal.
## Logging to file
If you don't want to use syslog, and you'd rather borgmatic log to a plain
file, use the `--log-file` flag:
```bash
borgmatic --log-file /path/to/file.log
```
Note that if you use the `--log-file` flag, you are responsible for rotating
the log file so it doesn't grow too large, for example with
[logrotate](https://wiki.archlinux.org/index.php/Logrotate).
You can use the `--log-file-verbosity` flag to customize the log file's log level:
```bash
borgmatic --log-file /path/to/file.log --log-file-verbosity 2
```
<span class="minilink minilink-addedin">New in version 2.0.0</span>Set the log
file verbosity in your borgmatic configuration via the `log_file_verbosity`
option.
<span class="minilink minilink-addedin">New in version 1.7.11</span> Use the
`--log-file-format` flag to override the default log message format. This
format string can contain a series of named placeholders wrapped in curly
brackets. For instance, the default log format is: `[{asctime}] {levelname}:
{message}`. This means each log message is recorded as the log time (in square
brackets), a logging level name, a colon, and the actual log message.
So if you only want each log message to get logged *without* a timestamp or a
logging level name:
```bash
borgmatic --log-file /path/to/file.log --log-file-format "{message}"
```
Here is a list of available placeholders:
* `{asctime}`: time the log message was created
* `{levelname}`: level of the log message (`INFO`, `DEBUG`, etc.)
* `{lineno}`: line number in the source file where the log message originated
* `{message}`: actual log message
* `{pathname}`: path of the source file where the log message originated
See the [Python logging
documentation](https://docs.python.org/3/library/logging.html#logrecord-attributes)
for additional placeholders.
Note that this `--log-file-format` flag only applies to the specified
`--log-file` and not to syslog or other logging.
<span class="minilink minilink-addedin">New in version 2.0.0</span>Set the
defaults for these flags in your borgmatic configuration via the `log_file` and
`log_file_format` options.

145
docs/reference/command-line/overrides.md
View file

@ -1,145 +0,0 @@
---
title: 🔄 Overrides
eleventyNavigation:
key: 🔄 Overrides
parent: 💻 Command-line
---
In more complex multi-application setups, you may want to override particular
borgmatic configuration file options at the time you run borgmatic. For
instance, you could reuse a common configuration file for multiple
applications, but then set the repository for each application at runtime. Or
you might want to try a variant of an option for testing purposes without
actually touching your configuration file.
<span class="minilink minilink-addedin">New in version 2.0.0</span>
Whatever the reason, you can override borgmatic configuration options at the
command-line, as there's a command-line flag corresponding to every
configuration option (with its underscores converted to dashes).
For instance, to override the `compression` configuration option, use the
corresponding `--compression` flag on the command-line:
```bash
borgmatic create --compression zstd
```
What this does is load your given configuration files and for each one, disregard
the configured value for the `compression` option and use the value given on the
command-line instead—but just for the duration of the borgmatic run.
You can override nested configuration options too by separating such option
names with a period. For instance:
```bash
borgmatic create --bootstrap.store-config-files false
```
You can even set complex option data structures by using inline YAML syntax. For
example, set the `repositories` option with a YAML list of key/value pairs:
```bash
borgmatic create --repositories "[{path: /mnt/backup, label: local}]"
```
If your override value contains characters like colons or spaces, then you'll
need to use quotes for it to parse correctly.
You can also set individual nested options within existing list elements:
```bash
borgmatic create --repositories[0].path /mnt/backup
```
This updates the `path` option for the first repository in `repositories`.
Change the `[0]` index as needed to address different list elements. And note
that this only works for elements already set in configuration; you can't append
new list elements from the command-line.
See the [command-line reference
documentation](https://torsion.org/borgmatic/reference/command-line/) for
the full set of available arguments, including examples of each for the complex
values.
There are a handful of configuration options that don't have corresponding
command-line flags at the global scope, but instead have flags within individual
borgmatic actions. For instance, the `list_details` option can be overridden by
the `--list` flag that's only present on particular actions. Similarly with
`progress` and `--progress`, `statistics` and `--stats`, and `match_archives`
and `--match-archives`.
Also note that if you want to pass a command-line flag itself as a value to one
of these override flags, that may not work. For instance, specifying
`--extra-borg-options.create --no-cache-sync` results in an error, because
`--no-cache-sync` gets interpreted as a borgmatic option (which in this case
doesn't exist) rather than a Borg option.
An alternate to command-line overrides is passing in your values via
[environment
variables](https://torsion.org/borgmatic/reference/configuration/environment-variables/).
### Deprecated overrides
<span class="minilink minilink-addedin">Prior to version 2.0.0</span>
Configuration overrides were performed with an `--override` flag. You can still
use `--override` with borgmatic 2.0.0+, but it's deprecated in favor of the new
command-line flags described above.
Here's an example of `--override`:
```bash
borgmatic create --override remote_path=/usr/local/bin/borg1
```
What this does is load your given configuration files and for each one, disregard
the configured value for the `remote_path` option and use the value given on the
command-line instead—but just for the duration of the borgmatic run.
You can even override nested values or multiple values at once. For instance:
```bash
borgmatic create --override parent_option.option1=value1 --override parent_option.option2=value2
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Don't
forget to specify the section that an option is in. That looks like a prefix
on the option name, e.g. `location.repositories`.
Note that each value is parsed as an actual YAML string, so you can set list
values by using brackets. For instance:
```bash
borgmatic create --override repositories=[test1.borg,test2.borg]
```
Or a single list element:
```bash
borgmatic create --override repositories=[/root/test.borg]
```
Or a single list element that is a key/value pair:
```bash
borgmatic create --override repositories="[{path: test.borg, label: test}]"
```
If your override value contains characters like colons or spaces, then you'll
need to use quotes for it to parse correctly.
Another example:
```bash
borgmatic create --override repositories="['user@server:test.borg']"
```
There is not currently a way to override a single element of a list without
replacing the whole list.
Using the `[ ]` list syntax is required when overriding an option of the list
type (like `location.repositories`). See the [configuration
reference](https://torsion.org/borgmatic/reference/configuration/) for
which options are list types. (YAML list values look like `- this` with an
indentation and a leading dash.)

100
docs/reference/configuration/archive-name-format.md
View file

@ -1,100 +0,0 @@
---
title: 📛 Archive name format
eleventyNavigation:
key: 📛 Archive name format
parent: ⚙️ Configuration
---
If you've got multiple borgmatic configuration files, you might want to create
archives with different naming schemes for each one. This is especially handy
if each configuration file is backing up to the same Borg repository but you
still want to be able to distinguish backup archives for one application from
another.
borgmatic supports this use case with an `archive_name_format` option. The
idea is that you define a string format containing a number of [Borg
placeholders](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-placeholders),
and borgmatic uses that format to name any new archive it creates. For
instance:
```yaml
archive_name_format: home-directories-{now}
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
this option in the `storage:` section of your configuration.
This example means that when borgmatic creates an archive, its name will start
with the string `home-directories-` and end with a timestamp for its creation
time. If `archive_name_format` is unspecified, the default with Borg 1 is
`{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}`, meaning your system hostname plus a
timestamp in a particular format.
<span class="minilink minilink-addedin">New in borgmatic version 1.9.0 with
Borg version 2.x</span>The default is just `{hostname}`, as Borg 2 does not
require unique archive names; identical archive names form a common "series"
that can be targeted together.
### Archive filtering
<span class="minilink minilink-addedin">New in version 1.7.11</span> borgmatic
uses the `archive_name_format` option to automatically limit which archives
get used for actions operating on multiple archives. This prevents, for
instance, duplicate archives from showing up in `repo-list` or `info`
results—even if the same repository appears in multiple borgmatic
configuration files. To take advantage of this feature, use a different
`archive_name_format` in each configuration file.
Under the hood, borgmatic accomplishes this by substituting globs for certain
ephemeral data placeholders in your `archive_name_format`—and using the result
to filter archives when running supported actions.
For instance, let's say that you have this in your configuration:
```yaml
archive_name_format: {hostname}-user-data-{now}
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
this option in the `storage:` section of your configuration.
borgmatic considers `{now}` an emphemeral data placeholder that will probably
change per archive, while `{hostname}` won't. So it turns the example value
into `{hostname}-user-data-*` and applies it to filter down the set of
archives used for actions like `repo-list`, `info`, `prune`, `check`, etc.
The end result is that when borgmatic runs the actions for a particular
application-specific configuration file, it only operates on the archives
created for that application. But this doesn't apply to actions like `compact`
that operate on an entire repository.
If this behavior isn't quite smart enough for your needs, you can use the
`match_archives` option to override the pattern that borgmatic uses for
filtering archives. For example:
```yaml
archive_name_format: {hostname}-user-data-{now}
match_archives: sh:myhost-user-data-*
```
<span class="minilink minilink-addedin">With Borg version 1.x</span>Use a shell
pattern for the `match_archives` value and see the [Borg patterns
documentation](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-help-patterns)
for more information.
<span class="minilink minilink-addedin">With Borg version 2.x</span>See the
[match archives
documentation](https://borgbackup.readthedocs.io/en/2.0.0b16/usage/help.html#borg-help-match-archives).
Some borgmatic command-line actions also have a `--match-archives` flag that
overrides both the auto-matching behavior and the `match_archives`
configuration option.
<span class="minilink minilink-addedin">Prior to version 1.7.11</span> The way
to limit the archives used for the `prune` action was a `prefix` option in the
`retention` section for matching against the start of archive names. And the
option for limiting the archives used for the `check` action was a separate
`prefix` in the `consistency` section. Both of these options are deprecated in
favor of the auto-matching behavior (or `match_archives`/`--match-archives`)
in newer versions of borgmatic.

248
docs/reference/configuration/command-hooks.md
View file

@ -1,248 +0,0 @@
---
title: 🪝 Command hooks
eleventyNavigation:
key: 🪝 Command hooks
parent: ⚙️ Configuration
---
<span class="minilink minilink-addedin">New in version 2.0.0</span> Command
hooks allow you to run arbitrary prepration and cleanup commands (or external
scripts) at various points in borgmatic's execution. You configure them via a
list of `commands:` in your borgmatic configuration file. For example:
```yaml
commands:
- before: action
when: [check] # This is an inline YAML sequence.
run:
- echo "Before create!"
- before: action
when: [create, prune] # Also an inline YAML sequence.
run:
- echo "Before create or prune!"
- after: action
when: # Multi-line YAML sequence, equivalent to "[create, prune]".
- create
- prune
run:
- echo "After create or prune!"
- after: error
run:
- echo "Something went wrong!"
```
Each command in the `commands:` list has the following options:
* `before` or `after`: Name for the point in borgmatic's execution that the commands should be run before or after, one of:
* `action` runs before or after each action for each repository. This replaces the deprecated `before_backup`, `after_prune`, etc.
* `repository` runs before or after all actions for each repository. This replaces the deprecated `before_actions` and `after_actions`.
* `configuration` runs before or after all actions and repositories in the current configuration file.
* `everything` runs before or after all configuration files. Errors here do not trigger `error` hooks or the `fail` state in monitoring hooks. This replaces the deprecated `before_everything` and `after_everything`.
* `error` runs after an error occurs—and it's only available for `after`. This replaces the deprecated `on_error` hook.
* `when`: Only trigger the hook when borgmatic is run with particular actions (`create`, `prune`, etc.) listed here. Defaults to running for all actions.
* `states`: <span class="minilink minilink-addedin">New in version 2.0.3</span> Only trigger the hook if borgmatic encounters one of the states (execution results) listed here. This state is evaluated only for the scope of the configured `action`, `repository`, etc., rather than for the entire borgmatic run. Only available for `after` hooks. Defaults to running the hook for all states. One or more of:
* `finish`: No errors occurred.
* `fail`: An error occurred.
* `run`: List of one or more shell commands or scripts to run when this command hook is triggered.
When command hooks run, they respect the `working_directory` option if it is
configured, meaning that the hook commands are run in that directory.
<span class="minilink minilink-addedin">New in version 2.0.4</span>If the exact
same `everything` command hook is present in multiple configuration files,
borgmatic only runs it once.
borgmatic's `--repository` flag does not impact which command hooks get run. But
you can use the `--config` flag to limit the configuration files (and thus
command hooks) used.
## Order of execution
Here's a way of visualizing how all of these command hooks slot into borgmatic's
execution.
Let's say you've got a borgmatic configuration file with a configured
repository. And suppose you configure several command hooks and then run
borgmatic for the `create` and `prune` actions. Here's the order of execution:
* Run `before: everything` hooks (from all configuration files).
* Run `before: configuration` hooks (from the first configuration file).
* Run `before: repository` hooks (for the first repository).
* Run `before: action` hooks for `create`.
* Actually run the `create` action (e.g. `borg create`).
* Run `after: action` hooks for `create`.
* Run `before: action` hooks for `prune`.
* Actually run the `prune` action (e.g. `borg prune`).
* Run `after: action` hooks for `prune`.
* Run `after: repository` hooks (for the first repository).
* Run `after: configuration` hooks (from the first configuration file).
* Run `after: error` hooks (if an error occurs).
* Run `after: everything` hooks (from all configuration files).
This same order of execution extends to multiple repositories and/or
configuration files.
Based on the above, you can see the difference between, say, an `after: action`
hook with `states: [fail]` and an `after: error` hook. The `after: action hook`
runs immediately after the create action fails for a particular repository—so
before any subsequent actions for that repository or other repositories even
have a chance to run. Whereas the `after: error` hook doesn't run until all
actions for—and repositories in—a configuration file have had a chance to
execute.
And if there are multiple hooks defined for a particular step (e.g. `before:
action` for `create`), then those hooks are run in the order they're defined in
configuration.
## Variable interpolation
The command action hooks support interpolating particular runtime variables into
the commands that are run. Here's are a couple examples that assume you provide
separate shell scripts:
```yaml
commands:
- after: action
when: [prune]
run:
- record-prune.sh {configuration_filename} {repository}
- after: error
when: [create]
run:
- send-text-message.sh {configuration_filename} {repository}
```
In this example, when the hook is triggered, borgmatic interpolates runtime
values into each hook command: the borgmatic configuration filename and the
paths of the current Borg repository.
Here's the full set of supported variables you can use here:
* `configuration_filename`: borgmatic configuration filename in which the
hook was defined
* `log_file`
<span class="minilink minilink-addedin">New in version 1.7.12</span>:
path of the borgmatic log file, only set when the `--log-file` flag is used
* `repository`: path of the current repository as configured in the current
borgmatic configuration file, if applicable to the current hook
* `repository_label` <span class="minilink minilink-addedin">New in version
1.8.12</span>: label of the current repository as configured in the current
borgmatic configuration file, if applicable to the current hook
* `error`: the error message itself, only applies to `error` hooks
* `output`: output of the command that failed, only applies to `error` hooks
(may be blank if an error occurred without running a command)
Not all command hooks support all variables. For instance, the `everything` and
`configuration` hooks don't support repository variables because those hooks
don't run in the context of a single repository. But the deprecated command
hooks (`before_backup`, `on_error`, etc.) do generally support variable
interpolation.
Note that you can also interpolate [arbitrary environment
variables](https://torsion.org/borgmatic/reference/configuration/environment-variables/).
### Shell escaping
borgmatic automatically escapes these interpolated values to prevent shell
injection attacks. One implication is that you shouldn't wrap the interpolated
values in your own quotes, as that will interfere with the quoting performed by
borgmatic and result in your command receiving incorrect arguments. For
instance, this won't work:
```yaml
commands:
- after: error
run:
# Don't do this! It won't work, as the {error} value is already quoted.
- send-text-message.sh "Uh oh: {error}"
```
Do this instead:
```yaml
commands:
- after: error
run:
- send-text-message.sh {error}
```
### Disabling variable interpolation
<span class="minilink minilink-addedin">New in version 2.1.0</span> To prevent
borgmatic from attempting variable interpolation on a specific would-be variable
name—or warning about unknown variables—you can backslash its curly brackets.
For instance:
```yaml
commands:
- after: action
when: [prune]
run:
- record-prune.sh \{name\}
```
This tells borgmatic to skip variable interpolation for `{name}` and instead
pass the `{name}` literal to the command. This is handy if you've got a command
containing literal curly brackets around a name that appears to reference a
variable—but actually doesn't.
## Soft failure
If any of your hook commands return a special exit status of 75, that indicates
to borgmatic that it's a temporary failure and borgmatic should skip all
subsequent actions for the current repository.
If you return any status besides 75, then it's a standard success or error.
(Zero is success; anything else other than 75 is an error).
Example of a soft failure command:
```yaml
commands:
- before: repository
run:
- findmnt /mnt/removable > /dev/null || exit 75
```
### Caveats and details
There are some caveats you should be aware of with this feature.
* You'll generally want to put a soft failure command in a `before` command
hook, so as to gate whether the backup action occurs. While a soft failure is
also supported in an `after` command hook, returning a soft failure there
won't prevent any actions from occurring, because they've already occurred!
Similarly, you can return a soft failure from an `error` command hook, but at
that point it's too late to prevent the error.
* Returning a soft failure does prevent further commands in the same hook from
executing. So, like a standard error, it is an "early out." Unlike a standard
error, borgmatic does not display it in angry red text or consider it a
failure.
* <span class="minilink minilink-addedin">New in version 1.9.0</span> Soft
failures in `action` or `before_*` command hooks only skip the current
repository rather than all repositories in a configuration file.
* If you're writing a soft failure script that you want to vary based on the
current repository, for instance so you can have multiple repositories in a
single configuration file, have a look at [variable
interpolation](#variable-interpolation) above.
And there's always still the option of putting anything that you don't want
soft-failed (like always-online cloud backups) in separate configuration
files from your soft-failing repositories.
* The soft failure doesn't have to test anything related to a repository. You
can even perform a test that individual source directories are mounted and
available. Use your imagination!
* Soft failures are not currently implemented for `everything`,
`before_everything`, or `after_everything` command hooks.
## Full configuration
{% include snippet/configuration/sample.md %}
```yaml
{% include borgmatic/commands.yaml %}
```

322
docs/reference/configuration/consistency-checks.md
View file

@ -1,322 +0,0 @@
---
title: ✅ Consistency checks
eleventyNavigation:
key: ✅ Consistency checks
parent: ⚙️ Configuration
---
Consistency checks, run via the `check` action, serve to validate the integrity
of your backups. borgmatic has several different named checks that perform
different levels of this validation.
By default, borgmatic runs full-repository checks (`repository`) and per-archive
checks (`archives`) within each repository on a monthly basis. (See below about
setting your own check frequency.)
To customize the checks that borgmatic run, set the `checks` option in your
configuration. For instance, to make borgmatic only run the `repository` check:
```yaml
checks:
- name: repository
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
this option in the `consistency:` section of your configuration.
<span class="minilink minilink-addedin">Prior to version 1.6.2</span> The
`checks` option was a plain list of strings without the `name:` part, and
borgmatic ran each configured check every time checks were run. For example:
```yaml
checks:
- repository
```
Here are the available checks, roughly from fastest to slowest:
* `archives`: Checks all of the archives' metadata in the repository.
* `repository`: Checks the consistency of the whole repository. The checks run
on the server and do not cause significant network traffic.
* `extract`: Performs an extraction dry-run of the latest archive.
* `data`: Verifies the data integrity of all archives contents, decrypting
and decompressing all data.
* `spot`: Compares file counts and contents between your source files and the
latest archive.
Note that the `data` check is a more thorough version of the `archives` check,
so enabling the `data` check implicitly enables the `archives` check as well.
See [Borg's check
documentation](https://borgbackup.readthedocs.io/en/stable/usage/check.html)
for more information.
## Spot check
The various consistency checks all have trade-offs around speed and
thoroughness, but most of them don't even look at your original source
files—arguably one important way to ensure your backups contain the files
you'll want to restore in the case of catastrophe (or an accidentally deleted
file). Because if something goes wrong with your source files, most
consistency checks will still pass with flying colors and you won't discover
there's a problem until you go to restore.
<span class="minilink minilink-addedin">New in version 1.8.10</span> That's
where the spot check comes in. This check actually compares your source file
counts and data against those in the latest archive, potentially catching
problems like incorrect excludes, inadvertent deletes, files changed by
malware, etc.
But because an exhaustive comparison of all source files against the latest
archive might be too slow, the spot check supports *sampling* a percentage of
your source files for the comparison, ensuring they fall within configured
tolerances.
Here's how it works. Start by installing the `xxhash` OS package if you don't
already have it, so the spot check can run the `xxh64sum` command and
efficiently hash files for comparison. Then add something like the following
to your borgmatic configuration:
```yaml
checks:
- name: spot
count_tolerance_percentage: 10
data_sample_percentage: 1
data_tolerance_percentage: 0.5
```
The `count_tolerance_percentage` is the percentage delta between the source
directories file count and the latest backup archive file count that is
allowed before the entire consistency check fails. For instance, if the spot
check runs and finds 100 source files on disk and 105 files in the latest
archive, that would be within the configured 10% count tolerance and the check
would succeed. But if there were 100 source files and 200 archive files, the
check would fail. (100 source files and only 50 archive files would also
fail.)
The `data_sample_percentage` is the percentage of total files in the source
directories to randomly sample and compare to their corresponding files in the
latest backup archive. A higher value allows a more accurate check—and a
slower one. The comparison is performed by hashing the selected source files
and counting hashes that don't match the latest archive. For instance, if you
have 1,000 source files and your sample percentage is 1%, then only 10 source
files will be compared against the latest archive. These sampled files are
selected randomly each time, so in effect the spot check is probabilistic.
The `data_tolerance_percentage` is the percentage of total files in the source
directories that can fail a spot check data comparison without failing the
entire consistency check. The value must be lower than or equal to the
`data_sample_percentage`, because `data_tolerance_percentage` only looks at
at the sampled files as determined by `data_sample_percentage`.
All three options are required when using the spot check. And because the
check relies on these configured tolerances, it may not be a
set-it-and-forget-it type of consistency check, at least until you get the
tolerances dialed in so there are minimal false positives or negatives. It is
recommended you run `borgmatic check` several times after configuring the spot
check, tweaking your tolerances as needed. For certain workloads where your
source files experience wild swings of file contents or counts, the spot check
may not suitable at all.
What if you add, delete, or change a bunch of your source files and you don't
want the spot check to fail the next time it's run? Run `borgmatic create` to
create a new backup, thereby allowing the next spot check to run against an
archive that contains your recent changes.
Because the spot check only looks at the most recent archive, you may not want
to run it immediately after a `create` action (borgmatic's default behavior).
Instead, it may make more sense to run the spot check on a separate schedule
from `create`.
## Check frequency
<span class="minilink minilink-addedin">New in version 1.6.2</span> You can
optionally configure checks to run on a periodic basis rather than every time
borgmatic runs checks. For instance:
```yaml
checks:
- name: repository
frequency: 2 weeks
- name: archives
frequency: 1 month
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
this option in the `consistency:` section of your configuration.
This tells borgmatic to run the `repository` consistency check at most once
every two weeks for a given repository and the `archives` check at most once a
month. The `frequency` value is a number followed by a unit of time, e.g. `3
days`, `1 week`, `2 months`, etc. The set of possible time units is as
follows (singular or plural):
* `second`
* `minute`
* `hour`
* `day`
* `week` (7 days)
* `month` (30 days)
* `year` (365 days)
The `frequency` defaults to `always` for a check configured without a
`frequency`, which means run this check every time checks run. But if you omit
consistency checks from configuration entirely, borgmatic runs full-repository
checks (`repository`) and per-archive checks (`archives`) within each
repository, at most once a month.
Unlike a real scheduler like cron, borgmatic only makes a best effort to run
checks on the configured frequency. It compares that frequency with how long
it's been since the last check for a given repository If it hasn't been long
enough, the check is skipped. And you still have to run `borgmatic check` (or
`borgmatic` without actions) in order for checks to run, even when a
`frequency` is configured!
This also applies *across* configuration files that have the same repository
configured. Make sure you have the same check frequency configured in each
though—or the most frequently configured check will apply.
<span class="minilink minilink-addedin">New in version 1.9.0</span>To support
this frequency logic, borgmatic records check timestamps within the
`~/.local/state/borgmatic/checks` directory. To override the `~/.local/state`
portion of this path, set the `user_state_directory` configuration option.
Alternatively, set the `XDG_STATE_HOME` environment variable.
<span class="minilink minilink-addedin">New in version 1.9.2</span>The
`STATE_DIRECTORY` environment variable also works for this purpose. It's set
by systemd if `StateDirectory=borgmatic` is added to borgmatic's systemd
service file.
<span class="minilink minilink-addedin">Prior to version 1.9.0</span>
borgmatic recorded check timestamps within the `~/.borgmatic` directory. At
that time, the path was configurable by the `borgmatic_source_directory`
configuration option (now deprecated).
If you want to temporarily ignore your configured frequencies, you can invoke
`borgmatic check --force` to run checks unconditionally.
<span class="minilink minilink-addedin">New in version 1.8.6</span> `borgmatic
check --force` runs `check` even if it's specified in the `skip_actions`
option.
## Check days
<span class="minilink minilink-addedin">New in version 1.8.13</span> You can
optionally configure checks to only run on particular days of the week. For
instance:
```yaml
checks:
- name: repository
only_run_on:
- Saturday
- Sunday
- name: archives
only_run_on:
- weekday
- name: spot
only_run_on:
- Friday
- weekend
```
Each day of the week is specified in the current locale (system
language/country settings). `weekend` and `weekday` are also accepted.
As with `frequency`, borgmatic only makes a best effort to run checks on the
given day of the week. For instance, if you run `borgmatic check` daily, then
every day borgmatic will have an opportunity to determine whether your checks
are configured to run on that day. If they are, then the checks run. If not,
they are skipped.
For instance, with the above configuration, if borgmatic is run on a Saturday,
the `repository` check will run. But on a Monday? The repository check will
get skipped. And if borgmatic is never run on a Saturday or a Sunday, that
check will never get a chance to run.
Also, the day of the week configuration applies *after* any configured
`frequency` for a check. So for instance, imagine the following configuration:
```yaml
checks:
- name: repository
frequency: 2 weeks
only_run_on:
- Monday
```
If you run borgmatic daily with that configuration, then borgmatic will first
wait two weeks after the previous check before running the check again—on the
first Monday after the `frequency` duration elapses.
## Running only checks
<span class="minilink minilink-addedin">New in version 1.7.1</span> If you
would like to only run consistency checks without creating backups (for
instance with the `check` action on the command-line), you can omit
the `source_directories` option entirely.
<span class="minilink minilink-addedin">Prior to version 1.7.1</span> In older
versions of borgmatic, instead specify an empty `source_directories` value, as
it is a mandatory option there:
```yaml
location:
source_directories: []
```
## Disabling checks
If that's still too slow, you can disable consistency checks entirely, either
for a single repository or for all repositories.
<span class="minilink minilink-addedin">New in version 1.8.5</span> Disabling
all consistency checks looks like this:
```yaml
skip_actions:
- check
```
<span class="minilink minilink-addedin">Prior to version 1.8.5</span> Use this
configuration instead:
```yaml
checks:
- name: disabled
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
`checks:` in the `consistency:` section of your configuration.
<span class="minilink minilink-addedin">Prior to version 1.6.2</span>
`checks:` was a plain list of strings without the `name:` part. For instance:
```yaml
checks:
- disabled
```
If you have multiple repositories in your borgmatic configuration file,
you can keep running consistency checks, but only against a subset of the
repositories:
```yaml
check_repositories:
- path/of/repository_to_check.borg
```
Finally, you can override your configuration file's consistency checks and
run particular checks via the command-line. For instance:
```bash
borgmatic check --only data --only extract
```
This is useful for running slow consistency checks on an infrequent basis,
separate from your regular checks. It is still subject to any configured
check frequencies unless the `--force` flag is used.

96
docs/reference/configuration/constants.md
View file

@ -1,96 +0,0 @@
---
title: 🟰 Constants
eleventyNavigation:
key: 🟰 Constants
parent: ⚙️ Configuration
---
<span class="minilink minilink-addedin">New in version 1.7.10</span> borgmatic
supports defining custom configuration constants. This is similar to the
[variable interpolation
feature](https://torsion.org/borgmatic/reference/configuration/command-hooks/#variable-interpolation)
for command hooks, but the constants feature lets you substitute your own custom
values into any option values in the entire configuration file.
Here's an example usage:
```yaml
constants:
user: foo
archive_prefix: bar
source_directories:
- /home/{user}/.config
- /home/{user}/.ssh
...
archive_name_format: '{archive_prefix}-{now}'
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Don't
forget to specify the section (like `location:` or `storage:`) that any option
is in.
In this example, when borgmatic runs, all instances of `{user}` get replaced
with `foo` and all instances of `{archive_prefix}` get replaced with `bar`.
And `{now}` doesn't get replaced with anything, but gets passed directly to
Borg, which has its own
[placeholders](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-help-placeholders)
using the same syntax as borgmatic constants. So borgmatic options like
`archive_name_format` that get passed directly to Borg can use either Borg
placeholders or borgmatic constants or both!
After substitution, the logical result looks something like this:
```yaml
source_directories:
- /home/foo/.config
- /home/foo/.ssh
...
archive_name_format: 'bar-{now}'
```
Note that if you'd like to interpolate a constant into the beginning of a
value, you'll need to quote it. For instance, this won't work:
```yaml
source_directories:
- {my_home_directory}/.config # This will error!
```
Instead, do this:
```yaml
source_directories:
- "{my_home_directory}/.config"
```
<span class="minilink minilink-addedin">New in version 1.8.5</span> Constants
work across
[includes](https://torsion.org/borgmatic/reference/configuration/includes/),
meaning you can define a constant and then include a separate configuration file
that uses that constant.
An alternate to constants is passing in your values via [environment
variables](https://torsion.org/borgmatic/reference/configuration/environment-variables/).
## Disabling constants
<span class="minilink minilink-addedin">New in version 2.1.0</span> To prevent
borgmatic from attempting constant interpolation on a specific would-be
constant name, you can backslash its curly brackets. For instance:
```yaml
constants:
name: foo
source_directories:
- /home/user/\{name\}
```
This tells borgmatic to skip constant interpolation for `{name}` and instead use
the `{name}` literal. This is handy if you've got a filename that has literal
curly brackets around a name that happens to match a constant.

65
docs/reference/configuration/credentials/container.md
View file

@ -1,65 +0,0 @@
---
title: Container secrets
eleventyNavigation:
key: Container
parent: 🔒 Credentials
---
<span class="minilink minilink-addedin">New in version 1.9.11</span> When
running inside a container, borgmatic can read [<span
data-pagefind-weight="0.5">Docker</span>
secrets](https://docs.docker.com/compose/how-tos/use-secrets/) and [<span
data-pagefind-weight="0.5">Podman</span>
secrets](https://www.redhat.com/en/blog/new-podman-secrets-command). Creating
those secrets and passing them into your borgmatic container is outside the
scope of this documentation, but here's a simple example of that with [<span
data-pagefind-weight="0.5">Docker</span>
Compose](https://docs.docker.com/compose/):
```yaml
services:
borgmatic:
# Use the actual image name of your borgmatic container here.
image: borgmatic:latest
secrets:
- borgmatic_passphrase
secrets:
borgmatic_passphrase:
file: /etc/borgmatic/passphrase.txt
```
This assumes there's a file on the host at `/etc/borgmatic/passphrase.txt`
containing your passphrase. <span data-pagefind-weight="0.5">Docker or
Podman</span> mounts the contents of that file into a secret named
`borgmatic_passphrase` in the borgmatic container at `/run/secrets/`.
Once your container secret is in place, you can consume it within your borgmatic
configuration file:
```yaml
encryption_passphrase: "{credential container borgmatic_passphrase}"
```
This reads the secret securely from a file mounted at
`/run/secrets/borgmatic_passphrase` within the borgmatic container.
The `{credential ...}` syntax works for several different options in a borgmatic
configuration file besides just `encryption_passphrase`. For instance, the
username, password, and API token options within database and monitoring hooks
support `{credential ...}`:
```yaml
postgresql_databases:
- name: invoices
username: postgres
password: "{credential container borgmatic_db1}"
```
You can also optionally override the `/run/secrets` directory that borgmatic reads secrets from
inside a container:
```yaml
container:
secrets_directory: /path/to/secrets
```
But you should only need to do this for development or testing purposes.

32
docs/reference/configuration/credentials/file.md
View file

@ -1,32 +0,0 @@
---
title: File-based credentials
eleventyNavigation:
key: File
parent: 🔒 Credentials
---
<span class="minilink minilink-addedin">New in version 1.9.11</span> borgmatic
supports reading credentials from arbitrary file paths. To use this feature,
start by writing your credential into a file that borgmatic has permission to
read. Take care not to include anything in the file other than your credential.
(borgmatic is smart enough to strip off a trailing newline though.)
You can consume that credential file in your borgmatic configuration. For
instance, if your credential file is at `/credentials/borgmatic.txt`, do this:
```yaml
encryption_passphrase: "{credential file /credentials/borgmatic.txt}"
```
With this in place, borgmatic reads the credential from the file path.
The `{credential ...}` syntax works for several different options in a borgmatic
configuration file besides just `encryption_passphrase`. For instance, the
username, password, and API token options within database and monitoring hooks
support `{credential ...}`:
```yaml
postgresql_databases:
- name: invoices
username: postgres
password: "{credential file /credentials/database.txt}"
```

48
docs/reference/configuration/credentials/index.md
View file

@ -1,48 +0,0 @@
---
title: 🔒 Credentials
eleventyNavigation:
key: 🔒 Credentials
parent: ⚙️ Configuration
---
<span class="minilink minilink-addedin">New in version 1.9.10</span> Several
borgmatic options support reading their values directly from an external
credential store or service. To take advantage of this feature, use `{credential
...}` syntax wherever you'd like borgmatic to read in a credential (for
supported options). In borgmatic's configuration, this looks like:
```yaml
option: "{credential type ...}"
```
... where:
* `option` is the name of the configuration option being set
* `type` is the source of the credential, one of:
* `container`: [Container secrets](https://torsion.org/borgmatic/reference/configuration/credentials/container/)
* `file`: [File-based credentials](https://torsion.org/borgmatic/reference/configuration/credentials/file/)
* `keepassxc`: [KeePassXC passwords](https://torsion.org/borgmatic/reference/configuration/credentials/keepassxc/)
* `systemd`: [systemd service credentials](https://torsion.org/borgmatic/reference/configuration/credentials/systemd/)
* "`...`" provides additional arguments specific to the selected credential
type
For example:
```yaml
encryption_passphrase: "{credential systemd borgmatic.pw}"
```
The `{credential ...}` syntax works for several different options in a borgmatic
configuration file besides just `encryption_passphrase`. For instance, the
username, password, and API token options within database and monitoring hooks
support `{credential ...}`:
```yaml
postgresql_databases:
- name: invoices
username: postgres
password: "{credential systemd borgmatic_db1}"
```
For details about which options support the use of `{credential ...}` syntax,
see the [configuration
reference](https://torsion.org/borgmatic/reference/configuration/).

100
docs/reference/configuration/credentials/keepassxc.md
View file

@ -1,100 +0,0 @@
---
title: KeePassXC passwords
eleventyNavigation:
key: KeePassXC
parent: 🔒 Credentials
---
<span class="minilink minilink-addedin">New in version 1.9.11</span> borgmatic
supports reading passwords from the [KeePassXC](https://keepassxc.org/) password
manager. To use this feature, start by creating an entry in your KeePassXC
database, putting your password into the "Password" field of that entry and
making sure it's saved.
Then, you can consume that password in your borgmatic configuration file. For
instance, if the entry's title is "borgmatic" and your KeePassXC database is
located at `/etc/keys.kdbx`, do this:
```yaml
encryption_passphrase: "{credential keepassxc /etc/keys.kdbx borgmatic}"
```
But if the entry's title is multiple words like `borg pw`, you'll
need to quote it:
```yaml
encryption_passphrase: "{credential keepassxc /etc/keys.kdbx 'borg pw'}"
```
With this in place, borgmatic runs the `keepassxc-cli` command to retrieve the
passphrase on demand. But note that `keepassxc-cli` will prompt for its own
passphrase in order to unlock its database, so be prepared to enter it when
running borgmatic.
The `{credential ...}` syntax works for several different options in a borgmatic
configuration file besides just `encryption_passphrase`. For instance, the
username, password, and API token options within database and monitoring hooks
support `{credential ...}`:
```yaml
postgresql_databases:
- name: invoices
username: postgres
password: "{credential keepassxc /etc/keys.kdbx database}"
```
### Custom command
You can also optionally override the `keepassxc-cli` command that borgmatic calls to load
passwords:
```yaml
keepassxc:
keepassxc_cli_command: /usr/local/bin/keepassxc-cli
```
Another example:
```yaml
keepassxc:
keepassxc_cli_command: docker exec keepassxc keepassxc-cli
```
### Key file
<span class="minilink minilink-addedin">New in version 2.0.0</span>KeePassXC
supports unlocking a database with a separate [key
file](https://keepassxc.org/docs/#faq-keyfile-howto) instead of or in addition
to a password. To configure borgmatic for that, use the `key_file` option:
```yaml
keepassxc:
key_file: /path/to/keyfile
```
<span class="minilink minilink-addedin">New in version 2.0.12</span>By default,
keepassxc-cli prompts the user for the password to unlock a database. But if you
only want to provide a key file to unlock your database and not a password, for
instance to support unattended backups, use the `ask_for_password` option:
```yaml
keepassxc:
ask_for_password: false
key_file: /path/to/keyfile
```
### YubiKey
<span class="minilink minilink-addedin">New in version 2.0.0</span>KeePassXC
also supports unlocking a database with the help of [a
YubiKey](https://keepassxc.org/docs/#faq-yubikey-2fa). To configure borgmatic
for that, use the `yubikey` option:
```yaml
keepassxc:
yubikey: 1:7370001
```
The value here is the YubiKey slot number (e.g., `1` or `2`) and optional serial
number (e.g., `7370001`) used to access the KeePassXC database. Join the two
values with a colon, but omit the colon if you're leaving out the serial number.

108
docs/reference/configuration/credentials/systemd.md
View file

@ -1,108 +0,0 @@
---
title: systemd service credentials
eleventyNavigation:
key: systemd
parent: 🔒 Credentials
---
<span class="minilink minilink-addedin">New in version 1.9.10</span> borgmatic
supports reading encrypted [systemd
credentials](https://systemd.io/CREDENTIALS/). To use this feature, start by
saving your password as an encrypted credential to
`/etc/credstore.encrypted/borgmatic.pw`, e.g.,
```bash
systemd-ask-password -n | systemd-creds encrypt - /etc/credstore.encrypted/borgmatic.pw
```
Then use the following in your configuration file:
```yaml
encryption_passphrase: "{credential systemd borgmatic.pw}"
```
<span class="minilink minilink-addedin">Prior to version 1.9.10</span> You can
accomplish the same thing with this configuration:
```yaml
encryption_passcommand: cat ${CREDENTIALS_DIRECTORY}/borgmatic.pw
```
Note that the name `borgmatic.pw` is hardcoded in the systemd service file.
The `{credential ...}` syntax works for several different options in a borgmatic
configuration file besides just `encryption_passphrase`. For instance, the
username, password, and API token options within database and monitoring hooks
support `{credential ...}`:
```yaml
postgresql_databases:
- name: invoices
username: postgres
password: "{credential systemd borgmatic_db1}"
```
To use these credentials, you'll need to modify the borgmatic systemd service
file to support loading multiple credentials (assuming you need to load more
than one or anything not named `borgmatic.pw`).
Start by saving each encrypted credentials to
`/etc/credstore.encrypted/borgmatic/`. E.g.,
```bash
mkdir /etc/credstore.encrypted/borgmatic
systemd-ask-password -n | systemd-creds encrypt --name=borgmatic_backupserver1 - /etc/credstore.encrypted/borgmatic/backupserver1
systemd-ask-password -n | systemd-creds encrypt --name=borgmatic_pw2 - /etc/credstore.encrypted/borgmatic/pw2
...
```
Ensure that the file names, (e.g. `backupserver1`) match the corresponding part
of the `--name` option *after* the underscore (_), and that the part *before*
the underscore matches the directory name (e.g. `borgmatic`).
Then, uncomment the appropriate line in the systemd service file:
```
systemctl edit borgmatic.service
...
# Load multiple encrypted credentials.
LoadCredentialEncrypted=borgmatic:/etc/credstore.encrypted/borgmatic/
```
Finally, use something like the following in your borgmatic configuration file
for each option value you'd like to load from systemd:
```yaml
encryption_passphrase: "{credential systemd borgmatic_backupserver1}"
```
<span class="minilink minilink-addedin">Prior to version 1.9.10</span> Use the
following instead, but only for the `encryption_passcommand` option and
not other options:
```yaml
encryption_passcommand: cat ${CREDENTIALS_DIRECTORY}/borgmatic_backupserver1
```
Adjust `borgmatic_backupserver1` according to the name of the credential and the
directory set in the service file.
<span class="minilink minilink-addedin">New in version 2.0.9</span> When using
the systemd `{credential ...}` feature, borgmatic loads systemd credentials even
when run outside of a systemd service. This works by falling back to calling
`systemd-creds decrypt` instead of reading credentials directly. To customize
this behavior, you can override the `systemd-creds` command and/or the
credential store directory it uses:
```yaml
systemd:
systemd_creds_command: /usr/local/bin/systemd-creds
encrypted_credentials_directory: /path/to/credstore.encrypted
```
<span class="minilink minilink-addedin">Prior to version 2.0.9</span> The
systemd `{credential ...}` feature did not work when run outside of a systemd
service. But depending on the borgmatic action invoked and the configuration
option where `{credential ...}` was used, you could sometimes get away without
working systemd credentials for certain actions. For instance, `borgmatic list`
doesn't connect to any databases or monitoring services, and `borgmatic config
validate` doesn't use credentials as all.

121
docs/reference/configuration/data-sources/btrfs.md
View file

@ -1,121 +0,0 @@
---
title: Btrfs
eleventyNavigation:
key: Btrfs
parent: 🗄️ Data sources
---
<span class="minilink minilink-addedin">New in version 1.9.4</span> borgmatic
supports taking snapshots with the [Btrfs
filesystem](https://btrfs.readthedocs.io/) and sending those snapshots to Borg
for backup.
The minimum configuration to enable Btrfs support is:
```yaml
btrfs:
```
## Subvolume discovery
For any read-write subvolume you'd like backed up, add its subvolume path to
borgmatic's `source_directories` option. borgmatic does not currently support
snapshotting read-only subvolumes.
<span class="minilink minilink-addedin">New in version 2.0.7</span> The path can
be either the path of the subvolume itself or the mount point where the
subvolume is mounted. Prior to version 2.0.7, the subvolume path could not be
used if the subvolume was mounted elsewhere; only the mount point could be used.
<span class="minilink minilink-addedin">New in version 1.9.6</span> Instead of
using `source_directories`, you can include the subvolume path as a root pattern
with borgmatic's `patterns` or `patterns_from` options.
During a backup, borgmatic snapshots these subvolumes and includes the
snapshotted files in the paths sent to Borg. borgmatic is also responsible for
cleaning up (deleting) these snapshots after a backup completes.
borgmatic is smart enough to look at the parent (and grandparent, etc.)
directories of each of your `source_directories` to discover any subvolumes. For
instance, let's say you add `/var/log` and `/var/lib` to your source
directories, but `/var` is a subvolume path. borgmatic will discover that and
snapshot `/var` accordingly. This also works even with nested subvolumes;
borgmatic selects the subvolume that's the "closest" parent to your source
directories.
If a subvolume has a separate filesystem mounted somewhere within it, that
filesystem won't get included in the snapshot. For instance, if `/` is a Btrfs
subvolume but `/boot` is a separate filesystem, borgmatic won't include `/boot`
as part of the subvolume snapshot. You can however add `/boot` to
`source_directories` if you'd like it included in your backup.
<span class="minilink minilink-addedin">New in version 1.9.6</span> When using
[patterns](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-help-patterns),
the initial portion of a pattern's path that you intend borgmatic to match
against a subvolume path can't have globs or other non-literal characters in
it—or it won't actually match. For instance, a subvolume path of `/var` would
match a pattern of `+ fm:/var/*/data`, but borgmatic isn't currently smart
enough to match `/var` to a pattern like `+ fm:/v*/lib/data`.
Additionally, borgmatic rewrites the snapshot file paths so that they appear at
their original subvolume locations in a Borg archive. For instance, if your
subvolume path is `/var/subvolume`, then the snapshotted files will appear in an
archive at `/var/subvolume` as well—even if borgmatic has to mount the snapshot
somewhere in `/var/subvolume/.borgmatic-snapshot/` to perform the backup.
<span class="minilink minilink-addedin">With Borg version 1.2 and
earlier</span>Snapshotted files are instead stored at a path dependent on the
temporary snapshot directory in use at the time the archive was created, as Borg
1.2 and earlier do not support path rewriting.
## Performance
<span class="minilink minilink-addedin">New in borgmatic version 2.0.13, with
Borg version 1.x</span> borgmatic uses consistent snapshot paths between
invocations, so Btrfs snapshots are cached correctly. No configuration is
necessary.
<span class="minilink minilink-addedin">Prior to borgmatic version 2.0.13, with
Borg version 1.x</span> Because of the way that Btrfs snapshot paths change from
one borgmatic invocation to the next, the [Borg file
cache](https://borgbackup.readthedocs.io/en/stable/internals/data-structures.html#cache)
never gets cache hits on snapshotted files. This makes backing up Btrfs
snapshots a little slower than non-snapshotted files that have consistent paths.
If this is an issue for you, upgrade to borgmatic to 2.0.13+.
<span class="minilink minilink-addedin">With Borg version 2.x</span> Even
snapshotted files get cache hits, because Borg 2.x is smarter about how it looks
up file paths in its cache—it constructs the cache key with the path *as it's
seen in the archive* (which is consistent across runs) rather than the full
absolute source path (which changes).
## systemd settings
If you're using [systemd to run
borgmatic](https://torsion.org/borgmatic/how-to/set-up-backups/#systemd), you
may need to disable particular security settings like `CapabilityBoundingSet` to
allow the Btrfs feature to work. See the comments in the sample systemd service
file for details.
## non-root user
<span class="minilink minilink-addedin">New in version 2.0.13</span> If you'd
like borgmatic to snapshot a Btrfs subvolume when running as a non-root user,
make the following changes to the subvolume in question:
1. `chown` the subvolume to be owned by your non-root user.
2. Mount the subvolume with the `user_subvol_rm_allowed` mount option.
These changes allow the non-root user to create and delete snapshots of the
subvolume, which is necessary for the borgmatic Btrfs hook to work.
## Full configuration
{% include snippet/configuration/sample.md %}
```yaml
{% include borgmatic/btrfs.yaml %}
```

19
docs/reference/configuration/data-sources/index.md
View file

@ -1,19 +0,0 @@
---
title: 🗄️ Data sources
eleventyNavigation:
key: 🗄️ Data sources
parent: ⚙️ Configuration
---
Data sources are built-in borgmatic integrations that, instead of backing up
plain filesystem data, can pull data directly from database servers and
filesystem snapshots.
In the case of supported database systems, borgmatic dumps your configured
databases, streaming them directly to Borg when creating a backup. And for
supported filesystems / volume managers, borgmatic takes on-demand snapshots of
configured source directories and feeds them to Borg.
Here are the supported data sources and how to configure their borgmatic
integrations:
{{ collections.all | eleventyNavigation: "🗄️ Data sources" | eleventyNavigationToHtml | replace: 'href="/reference/', 'href="/borgmatic/reference/' }}

131
docs/reference/configuration/data-sources/lvm.md
View file

@ -1,131 +0,0 @@
---
title: LVM
eleventyNavigation:
key: LVM
parent: 🗄️ Data sources
---
<span class="minilink minilink-addedin">New in version 1.9.4</span> borgmatic
supports taking snapshots with [LVM](https://sourceware.org/lvm2/) (Linux
Logical Volume Manager) and sending those snapshots to Borg for backup. LVM
isn't itself a filesystem, but it can take snapshots at the layer right below
your filesystem.
The minimum configuration to enable LVM support is:
```yaml
lvm:
```
## Snapshot size
The `snapshot_size` option is the size to allocate for each snapshot taken,
including the units to use for that size:
```yaml
lvm:
snapshot_size: 5GB
```
While borgmatic's snapshots themselves are read-only and don't change during
backups, the logical volume being snapshotted *can* change—therefore requiring
additional snapshot storage since LVM snapshots are copy-on-write. And if the
configured snapshot size is too small (and LVM isn't configured to grow
snapshots automatically), then the snapshots will fail to allocate enough space,
resulting in a broken backup.
If not specified, the `snapshot_size` option defaults to `10%ORIGIN`, which
means 10% of the size of the logical volume being snapshotted. See the
[`lvcreate --size` and `--extents`
documentation](https://www.man7.org/linux/man-pages/man8/lvcreate.8.html) for
more information about possible values here. (Under the hood, borgmatic uses
`lvcreate --extents` if the `snapshot_size` is a percentage value, and `lvcreate
--size` otherwise.)
## Logical volume discovery
For any logical volume you'd like backed up, add its mount point to
borgmatic's `source_directories` option.
<span class="minilink minilink-addedin">New in version 1.9.6</span> Or include
the mount point as a root pattern with borgmatic's `patterns` or `patterns_from`
options.
During a backup, borgmatic automatically snapshots these discovered logical volumes
(non-recursively), temporarily mounts the snapshots within its [runtime
directory](https://torsion.org/borgmatic/reference/configuration/runtime-directory/), and
includes the snapshotted files in the paths sent to Borg. borgmatic is also responsible for cleaning
up (deleting) these snapshots after a backup completes.
borgmatic is smart enough to look at the parent (and grandparent, etc.)
directories of each of your `source_directories` to discover any logical
volumes. For instance, let's say you add `/var/log` and `/var/lib` to your
source directories, but `/var` is a logical volume. borgmatic will discover
that and snapshot `/var` accordingly.
If a logical volume has a separate filesystem mounted somewhere within it, that
filesystem won't get included in the snapshot. For instance, if `/` is an LVM
logical volume but `/boot` is a separate filesystem, borgmatic won't include
`/boot` as part of the logical volume snapshot. You can however add `/boot` to
`source_directories` if you'd like it included in your backup.
<span class="minilink minilink-addedin">New in version 1.9.6</span> When using
[patterns](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-help-patterns),
the initial portion of a pattern's path that you intend borgmatic to match
against a logical volume can't have globs or other non-literal characters in
it—or it won't actually match. For instance, a logical volume of `/var` would
match a pattern of `+ fm:/var/*/data`, but borgmatic isn't currently smart
enough to match `/var` to a pattern like `+ fm:/v*/lib/data`.
Additionally, borgmatic rewrites the snapshot file paths so that they appear
at their original logical volume locations in a Borg archive. For instance, if
your logical volume is mounted at `/var/lvolume`, then the snapshotted files
will appear in an archive at `/var/lvolume` as well—even if borgmatic has to
mount the snapshot somewhere in `/run/user/1000/borgmatic/lvm_snapshots/` to
perform the backup.
<span class="minilink minilink-addedin">With Borg version 1.2 and
earlier</span>Snapshotted files are instead stored at a path dependent on the
[runtime
directory](https://torsion.org/borgmatic/reference/configuration/runtime-directory/)
in use at the time the archive was created, as Borg 1.2 and earlier do not
support path rewriting.
## Performance
<span class="minilink minilink-addedin">With Borg version 1.x</span> Because of
the way that LVM snapshot paths can change from one borgmatic invocation to the
next, the [Borg file
cache](https://borgbackup.readthedocs.io/en/stable/internals/data-structures.html#cache)
may not get cache hits on snapshotted files. This makes backing up LVM snapshots
a little slower than non-snapshotted files that have consistent paths. You can
mitigate this by setting a fixed [runtime
directory](https://torsion.org/borgmatic/reference/configuration/runtime-directory/)
(that's not located in `/tmp`). This allows borgmatic to use a consistent
snapshot path from one run to the next, thereby resulting in Borg files cache
hits.
<span class="minilink minilink-addedin">With Borg version 2.x</span> Snapshotted
files should get cache hits regardless of whether their paths change, because
Borg 2.x is smarter about how it looks up file paths in its cache—it constructs
the cache key with the path *as it's seen in the archive* (which is consistent
across runs) rather than the full absolute source path (which can change).
## systemd settings
If you're using [systemd to run
borgmatic](https://torsion.org/borgmatic/how-to/set-up-backups/#systemd), you
may need to disable particular security settings like `ProtectKernelModules`,
`CapabilityBoundingSet`, and/or `PrivateDevices` to allow the LVM feature to
work. See the comments in the sample systemd service file for details.
## Full configuration
{% include snippet/configuration/sample.md %}
```yaml
{% include borgmatic/lvm.yaml %}
```

25
docs/reference/configuration/data-sources/mariadb.md
View file

@ -1,25 +0,0 @@
---
title: MariaDB
eleventyNavigation:
key: MariaDB
parent: 🗄️ Data sources
---
<span class="minilink minilink-addedin">New in version 1.8.2</span> To backup
MariaDB with borgmatic, use the `mariadb_databases:` hook instead of
`mysql_databases:` as the MariaDB hook calls native MariaDB commands instead of
the deprecated MySQL ones. For instance:
```yaml
mariadb_databases:
- name: comments
```
### Full configuration
{% include snippet/configuration/sample.md %}
```yaml
{% include borgmatic/mariadb_databases.yaml %}
```

23
docs/reference/configuration/data-sources/mongodb.md
View file

@ -1,23 +0,0 @@
---
title: MongoDB
eleventyNavigation:
key: MongoDB
parent: 🗄️ Data sources
---
<span class="minilink minilink-addedin">New in version 1.5.22</span> To backup
MongoDB with borgmatic, use the `mongodb_databases:` hook. For example:
```yaml
mongodb_databases:
- name: messages
```
### Full configuration
{% include snippet/configuration/sample.md %}
```yaml
{% include borgmatic/mongodb_databases.yaml %}
```

23
docs/reference/configuration/data-sources/mysql.md
View file

@ -1,23 +0,0 @@
---
title: MySQL
eleventyNavigation:
key: MySQL
parent: 🗄️ Data sources
---
<span class="minilink minilink-addedin">New in version 1.4.9</span> To backup
MySQL with borgmatic, use the `mysql_databases:` hook. For instance:
```yaml
mysql_databases:
- name: posts
```
## Full configuration
{% include snippet/configuration/sample.md %}
```yaml
{% include borgmatic/mysql_databases.yaml %}
```

23
docs/reference/configuration/data-sources/postgresql.md
View file

@ -1,23 +0,0 @@
---
title: PostgreSQL
eleventyNavigation:
key: PostgreSQL
parent: 🗄️ Data sources
---
<span class="minilink minilink-addedin">New in version 1.4.0</span> To backup
PostgreSQL with borgmatic, use the `postgresql_databases:` hook. For instance:
```yaml
postgresql_databases:
- name: users
```
## Full configuration
{% include snippet/configuration/sample.md %}
```yaml
{% include borgmatic/postgresql_databases.yaml %}
```

24
docs/reference/configuration/data-sources/sqlite.md
View file

@ -1,24 +0,0 @@
---
title: SQLite
eleventyNavigation:
key: SQLite
parent: 🗄️ Data sources
---
<span class="minilink minilink-addedin">New in version 1.7.9</span> To backup
SQLite with borgmatic, use the `sqlite_databases:` hook. For example:
```yaml
sqlite_databases:
- name: mydb
path: /var/lib/sqlite3/mydb.sqlite
```
## Full configuration
{% include snippet/configuration/sample.md %}
```yaml
{% include borgmatic/sqlite_databases.yaml %}
```

120
docs/reference/configuration/data-sources/zfs.md
View file

@ -1,120 +0,0 @@
---
title: ZFS
eleventyNavigation:
key: ZFS
parent: 🗄️ Data sources
---
<span class="minilink minilink-addedin">New in version 1.9.3</span> borgmatic
supports taking snapshots with the [ZFS filesystem](https://openzfs.org/) and
sending those snapshots to Borg for backup.
The minimum configuration to enable ZFS support is:
```yaml
zfs:
```
## Dataset discovery
You have a couple of options for borgmatic to find and backup your ZFS datasets:
* For any dataset you'd like backed up, add its mount point to borgmatic's
`source_directories` option.
* <span class="minilink minilink-addedin">New in version 1.9.6</span> Or
include the mount point as a root pattern with borgmatic's `patterns` or
`patterns_from` options.
* Or set the borgmatic-specific user property
`org.torsion.borgmatic:backup=auto` onto your dataset, e.g. by running `zfs
set org.torsion.borgmatic:backup=auto datasetname`. Then borgmatic can find
and backup these datasets.
If you have multiple borgmatic configuration files with ZFS enabled, and you'd
like particular datasets to be backed up only for particular configuration
files, use the `source_directories` option instead of the user property.
<span class="minilink minilink-addedin">New in version 1.9.11</span> borgmatic
won't snapshot datasets with the `canmount=off` property, which is often set on
datasets that only serve as a container for other datasets. Use `zfs get
canmount datasetname` to see the `canmount` value for a dataset.
During a backup, borgmatic automatically snapshots these discovered datasets,
temporarily mounts the snapshots within its [runtime
directory](https://torsion.org/borgmatic/reference/configuration/runtime-directory/),
and includes the snapshotted files in the paths sent to Borg. borgmatic is also
responsible for cleaning up (destroying) these snapshots after a backup
completes.
Additionally, borgmatic rewrites the snapshot file paths so that they appear
at their original dataset locations in a Borg archive. For instance, if your
dataset is mounted at `/var/dataset`, then the snapshotted files will appear
in an archive at `/var/dataset` as well—even if borgmatic has to mount the
snapshot somewhere in `/run/user/1000/borgmatic/zfs_snapshots/` to perform the
backup.
If a dataset has a separate filesystem mounted somewhere within it, that
filesystem won't get included in the snapshot. For instance, if `/` is a ZFS
dataset but `/boot` is a separate filesystem, borgmatic won't include `/boot` as
part of the dataset snapshot. You can however add `/boot` to
`source_directories` if you'd like it included in your backup.
<span class="minilink minilink-addedin">New in version 1.9.4</span> borgmatic
is smart enough to look at the parent (and grandparent, etc.) directories of
each of your `source_directories` to discover any datasets. For instance,
let's say you add `/var/log` and `/var/lib` to your source directories, but
`/var` is a dataset. borgmatic will discover that and snapshot `/var`
accordingly. This also works even with nested datasets; borgmatic selects
the dataset that's the "closest" parent to your source directories.
<span class="minilink minilink-addedin">New in version 1.9.6</span> When using
[patterns](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-help-patterns),
the initial portion of a pattern's path that you intend borgmatic to match
against a dataset can't have globs or other non-literal characters in it—or it
won't actually match. For instance, a mount point of `/var` would match a
pattern of `+ fm:/var/*/data`, but borgmatic isn't currently smart enough to
match `/var` to a pattern like `+ fm:/v*/lib/data`.
<span class="minilink minilink-addedin">With Borg version 1.2 and
earlier</span>Snapshotted files are instead stored at a path dependent on the
[runtime
directory](https://torsion.org/borgmatic/reference/configuration/runtime-directory/)
in use at the time the archive was created, as Borg 1.2 and earlier do not
support path rewriting.
## Performance
<span class="minilink minilink-addedin">With Borg version 1.x</span> Because of
the way that ZFS snapshot paths can change from one borgmatic invocation to the
next, the [Borg file
cache](https://borgbackup.readthedocs.io/en/stable/internals/data-structures.html#cache)
may not get cache hits on snapshotted files. This makes backing up ZFS snapshots
a little slower than non-snapshotted files that have consistent paths. You can
mitigate this by setting a fixed [runtime
directory](https://torsion.org/borgmatic/reference/configuration/runtime-directory/)
(that's not located in `/tmp`). This allows borgmatic to use a consistent
snapshot path from one run to the next, thereby resulting in Borg files cache
hits.
<span class="minilink minilink-addedin">With Borg version 2.x</span> Snapshotted
files should get cache hits regardless of whether their paths change, because
Borg 2.x is smarter about how it looks up file paths in its cache—it constructs
the cache key with the path *as it's seen in the archive* (which is consistent
across runs) rather than the full absolute source path (which can change).
## systemd settings
If you're using [systemd to run
borgmatic](https://torsion.org/borgmatic/how-to/set-up-backups/#systemd), you
may need to disable particular security settings like `CapabilityBoundingSet`
and/or `PrivateDevices` to allow the ZFS feature to work. See the comments in
the sample systemd service file for details.
## Full configuration
{% include snippet/configuration/sample.md %}
```yaml
{% include borgmatic/zfs.yaml %}
```

93
docs/reference/configuration/environment-variables.md
View file

@ -1,93 +0,0 @@
---
title: 💲 Environment variables
eleventyNavigation:
key: 💲 Environment variables
parent: ⚙️ Configuration
---
<span class="minilink minilink-addedin">New in version 1.6.4</span> borgmatic
supports interpolating arbitrary environment variables directly into option
values in your configuration file. That means you can instruct borgmatic to
pull your repository passphrase, your database passwords, or any other option
values from environment variables.
Be aware though that environment variables may be less secure than some of the
other approaches above for getting credentials into borgmatic. That's because
environment variables may be visible from within child processes and/or OS-level
process metadata.
Here's an example of using an environment variable from borgmatic's
configuration file:
```yaml
encryption_passphrase: ${YOUR_PASSPHRASE}
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
this option in the `storage:` section of your configuration.
This uses the `YOUR_PASSPHRASE` environment variable as your encryption
passphrase. Note that the `{` `}` brackets are required. `$YOUR_PASSPHRASE` by
itself will not work.
In the case of `encryption_passphrase` in particular, an alternate approach
is to use Borg's `BORG_PASSPHRASE` environment variable, which doesn't even
require setting an explicit `encryption_passphrase` value in borgmatic's
configuration file.
For [database
configuration](https://torsion.org/borgmatic/reference/configuration/data-sources/),
the same approach applies. For example:
```yaml
postgresql_databases:
- name: users
password: ${YOUR_DATABASE_PASSWORD}
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
this option in the `hooks:` section of your configuration.
This uses the `YOUR_DATABASE_PASSWORD` environment variable as your database
password.
### Interpolation defaults
If you'd like to set a default for your environment variables, you can do so
with the following syntax:
```yaml
encryption_passphrase: ${YOUR_PASSPHRASE:-defaultpass}
```
Here, "`defaultpass`" is the default passphrase if the `YOUR_PASSPHRASE`
environment variable is not set. Without a default, if the environment
variable doesn't exist, borgmatic will error.
### Disabling interpolation
To disable this environment variable interpolation feature entirely, you can
pass the `--no-environment-interpolation` flag on the command-line.
Or if you'd like to disable interpolation within a single option value, you
can escape it with a backslash. For instance, if your password is literally
`${A}@!`:
```yaml
encryption_passphrase: \${A}@!
```
## Related features
Another way to override particular options within a borgmatic configuration
file is to use a [configuration
override](https://torsion.org/borgmatic/reference/configuration/overrides/)
on the command-line. But please be aware of the security implications of
specifying secrets on the command-line.
Additionally, borgmatic action hooks support their own [variable
interpolation](https://torsion.org/borgmatic/reference/configuration/command-hooks/#variable-interpolation),
although in that case it's for particular borgmatic runtime values rather than
(only) environment variables.

322
docs/reference/configuration/includes.md
View file

@ -1,322 +0,0 @@
---
title: ❗ Includes
eleventyNavigation:
key: ❗ Includes
parent: ⚙️ Configuration
---
Once you have multiple different configuration files, you might want to share
common configuration options across these files without having to copy and paste
them. To achieve this, you can put fragments of common configuration options
into a file and then include or inline that file into one or more borgmatic
configuration files.
Let's say that you want to include common consistency check configuration across all
of your configuration files. You could do that in each configuration file with
the following:
```yaml
repositories:
- path: repo.borg
checks:
!include /etc/borgmatic/common_checks.yaml
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> These
options were organized into sections like `location:` and `consistency:`.
The contents of `common_checks.yaml` could be:
```yaml
- name: repository
frequency: 3 weeks
- name: archives
frequency: 2 weeks
```
To prevent borgmatic from trying to load these configuration fragments by
themselves and complaining that they are not valid configuration files, you
should put them in a directory other than `/etc/borgmatic.d/`. (A subdirectory
is fine.)
When a configuration include is a relative path, borgmatic loads it from either
the current working directory or from the directory containing the file doing
the including.
Note that this form of include must be a value rather than an option name. For
example, this will not work:
```yaml
repositories:
- path: repo.borg
# Don't do this. It won't work!
!include /etc/borgmatic/common_checks.yaml
```
But if you do want to merge in a option name *and* its values, keep reading!
## Include merging
If you need to get even fancier and merge in common configuration options, you
can perform a YAML merge of included configuration using the YAML `<<` key.
For instance, here's an example of a main configuration file that pulls in
retention and consistency checks options via a single include:
```yaml
repositories:
- path: repo.borg
<<: !include /etc/borgmatic/common.yaml
```
This is what `common.yaml` might look like:
```yaml
keep_hourly: 24
keep_daily: 7
checks:
- name: repository
frequency: 3 weeks
- name: archives
frequency: 2 weeks
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> These
options were organized into sections like `retention:` and `consistency:`.
Once this include gets merged in, the resulting configuration has all of the
options from the original configuration file *and* the options from the
include.
Note that this `<<` include merging syntax is only for merging in mappings
(configuration options and their values). If you'd like to include a single
value directly, please see above about standard includes.
### Multiple merge includes
borgmatic has a limitation preventing multiple `<<` include merges per file or
option value. This means you can do a single `<<` merge at the global level,
another `<<` within each nested option value, etc. (This is a YAML
limitation.) For instance:
```yaml
repositories:
- path: repo.borg
# This won't work! You can't do multiple merges like this at the same level.
<<: !include common1.yaml
<<: !include common2.yaml
```
But read on for a way around this.
<span class="minilink minilink-addedin">New in version 1.8.1</span> You can
include and merge multiple configuration files all at once. For instance:
```yaml
repositories:
- path: repo.borg
<<: !include [common1.yaml, common2.yaml, common3.yaml]
```
This merges in each included configuration file in turn, such that later files
replace the options in earlier ones.
Here's another way to do the same thing:
```yaml
repositories:
- path: repo.borg
<<: !include
- common1.yaml
- common2.yaml
- common3.yaml
```
### Deep merge
<span class="minilink minilink-addedin">New in version 1.6.0</span> borgmatic
performs a deep merge of merged include files, meaning that values are merged
at all levels in the two configuration files. This allows you to include
common configuration—up to full borgmatic configuration files—while overriding
only the parts you want to customize.
For instance, here's an example of a main configuration file that pulls in
options via an include and then overrides one of them locally:
```yaml
<<: !include /etc/borgmatic/common.yaml
constants:
base_directory: /opt
repositories:
- path: repo.borg
```
This is what `common.yaml` might look like:
```yaml
constants:
app_name: myapp
base_directory: /var/lib
```
Once this include gets merged in, the resulting configuration would have an
`app_name` value of `myapp` and an overridden `base_directory` value of
`/opt`.
When there's an option collision between the local file and the merged
include, the local file's option takes precedence.
#### List merge
<span class="minilink minilink-addedin">New in version 1.6.1</span> Colliding
list values are appended together.
<span class="minilink minilink-addedin">New in version 1.7.12</span> If there
is a list value from an include that you *don't* want in your local
configuration file, you can omit it with an `!omit` tag. For instance:
```yaml
<<: !include /etc/borgmatic/common.yaml
source_directories:
- !omit /home
- /var
```
And `common.yaml` like this:
```yaml
source_directories:
- /home
- /etc
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put the
`source_directories` option in the `location:` section of your configuration.
Once this include gets merged in, the resulting configuration will have a
`source_directories` value of `/etc` and `/var`—with `/home` omitted.
This feature currently only works on scalar (e.g. string or number) list items
and will not work elsewhere in a configuration file. Be sure to put the
`!omit` tag *before* the list item (after the dash). Putting `!omit` after the
list item will not work, as it gets interpreted as part of the string. Here's
an example of some things not to do:
```yaml
<<: !include /etc/borgmatic/common.yaml
source_directories:
# Do not do this! It will not work. "!omit" belongs before "/home".
- /home !omit
# Do not do this either! "!omit" only works on scalar list items.
repositories: !omit
# Also do not do this for the same reason! This is a list item, but it's
# not a scalar.
- !omit path: repo.borg
```
Additionally, the `!omit` tag only works in a configuration file that also
performs a merge include with `<<: !include`. It doesn't make sense within,
for instance, an included configuration file itself (unless it in turn
performs its own merge include). That's because `!omit` only applies to the
file doing the include; it doesn't work in reverse or propagate through
includes.
### Shallow merge
Even though deep merging is generally pretty handy for included files,
sometimes you want specific options in the local file to take precedence over
included options—without any merging occurring for them.
<span class="minilink minilink-addedin">New in version 1.7.12</span> That's
where the `!retain` tag comes in. Whenever you're merging an included file
into your configuration file, you can optionally add the `!retain` tag to
particular local mappings or lists to retain the local values and ignore
included values.
For instance, start with this configuration file containing the `!retain` tag
on the `retention` mapping:
```yaml
<<: !include /etc/borgmatic/common.yaml
repositories:
- path: repo.borg
checks: !retain
- name: repository
```
And `common.yaml` like this:
```yaml
repositories:
- path: common.borg
checks:
- name: archives
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> These
options were organized into sections like `location:` and `consistency:`.
Once this include gets merged in, the resulting configuration will have a
`checks` value with a name of `repository` and no other values. That's because
the `!retain` tag says to retain the local version of `checks` and ignore any
values coming in from the include. But because the `repositories` list doesn't
have a `!retain` tag, it still gets merged together to contain both
`common.borg` and `repo.borg`.
The `!retain` tag can only be placed on mappings (keys/values) and lists, and
it goes right after the name of the option (and its colon) on the same line.
The effects of `!retain` are recursive, meaning that if you place a `!retain`
tag on a top-level mapping, even deeply nested values within it will not be
merged.
Additionally, the `!retain` tag only works in a configuration file that also
performs a merge include with `<<: !include`. It doesn't make sense within,
for instance, an included configuration file itself (unless it in turn
performs its own merge include). That's because `!retain` only applies to the
file doing the include; it doesn't work in reverse or propagate through
includes.
## Debugging includes
<span class="minilink minilink-addedin">New in version 1.7.15</span> If you'd
like to see what the loaded configuration looks like after includes get merged
in, run the `validate` action on your configuration file:
```bash
sudo borgmatic config validate --show
```
<span class="minilink minilink-addedin">In version 1.7.12 through
1.7.14</span> Use this command instead:
```bash
sudo validate-borgmatic-config --show
```
You'll need to specify your configuration file with `--config` if it's not in
a default location.
This will output the merged configuration as borgmatic sees it, which can be
helpful for understanding how your includes work in practice.
Also see the [`config show`
action](https://torsion.org/borgmatic/reference/command-line/actions/config-show/).

26
docs/reference/configuration/index.md
View file

@ -1,26 +0,0 @@
---
title: ⚙️ Configuration
eleventyNavigation:
key: ⚙️ Configuration
parent: Reference guides
order: 0
---
Below is a sample borgmatic configuration snippet for every available option in
the [most recent version of
borgmatic](https://projects.torsion.org/borgmatic-collective/borgmatic/releases).
A full example configuration file is also [available for
download](https://torsion.org/borgmatic/reference/config.yaml).
If you're using an older version of borgmatic, some of these options may not
work, and you should instead [generate a sample configuration file specific to
your borgmatic
version](https://torsion.org/borgmatic/how-to/set-up-backups/#configuration).
<span data-pagefind-weight="6.0">
{% for option_name in option_names %}
### {{ option_name }} option
```yaml
{% include borgmatic/{{ option_name }}.yaml %}
```
{% endfor %}
</span>

123
docs/reference/configuration/monitoring/apprise.md
View file

@ -1,123 +0,0 @@
---
title: Apprise
eleventyNavigation:
key: Apprise
parent: 🚨 Monitoring
---
<span class="minilink minilink-addedin">New in version 1.8.4</span>
[Apprise](https://github.com/caronc/apprise/wiki) is a local notification library
that "allows you to send a notification to almost all of the most popular
[notification services](https://github.com/caronc/apprise/wiki) available to
us today such as: Telegram, Discord, Slack, Amazon SNS, Gotify, etc."
Depending on how you installed borgmatic, it may not have come with Apprise.
For instance, if you originally [installed borgmatic with
pipx](https://torsion.org/borgmatic/how-to/set-up-backups/),
run the following to install Apprise so borgmatic can use it:
```bash
sudo pipx uninstall borgmatic
sudo pipx install borgmatic[Apprise]
```
Omit `sudo` if borgmatic is installed as a non-root user.
Once Apprise is installed, configure borgmatic to notify one or more [Apprise
services](https://github.com/caronc/apprise/wiki). For example:
```yaml
apprise:
services:
- url: gotify://hostname/token
label: gotify
- url: mastodons://access_key@hostname/@user
label: mastodon
states:
- start
- finish
- fail
```
With this configuration, borgmatic pings each of the configured Apprise
services when a backup begins, ends, or errors, but only when any of the
`create`, `prune`, `compact`, or `check` actions are run. (By default, if
`states` is not specified, Apprise services are only pinged on error.)
You can optionally customize the contents of the default messages sent to
these services:
```yaml
apprise:
services:
- url: gotify://hostname/token
label: gotify
start:
title: Ping!
body: Starting backup process.
finish:
title: Ping!
body: Backups successfully made.
fail:
title: Ping!
body: Your backups have failed.
states:
- start
- finish
- fail
```
### Sending logs
<span class="minilink minilink-addedin">New in version 1.8.9</span> borgmatic
can include logs in the body data sent to your Apprise services when a backup
finishes or fails. There is a `send_logs` option to enable or disable log
sending:
```yaml
apprise:
services:
- url: gotify://hostname/token
label: gotify
send_logs: true
```
<span class="minilink minilink-addedin">New in version 2.1.0</span> To avoid
revealing private log information to third-party services, logs are no longer
sent by default when `send_logs` is omitted.
<span class="minilink minilink-addedin">Prior to version 2.1.0</span> Logs were
sent by default when `send_logs` was omitted.
You can customize the verbosity of the logs that are sent with borgmatic's
`--monitoring-verbosity` flag. The `--list` and `--stats` flags may also be of
use. See [create action
documentation](https://torsion.org/borgmatic/reference/command-line/actions/create/)
for more information.
<span class="minilink minilink-addedin">New in version 2.0.0</span>Set the
defaults for these flags in your borgmatic configuration via the
`monitoring_verbosity`, `list`, and `statistics` options.
To limit the size of logs sent to Apprise services, set `logs_size_limit` to a
number of bytes:
```yaml
apprise:
services:
- url: gotify://hostname/token
label: gotify
send_logs: true
logs_size_limit: 500
```
This may be necessary for some services that reject large requests.
### Full configuration
{% include snippet/configuration/sample.md %}
```yaml
{% include borgmatic/apprise.yaml %}
```

33
docs/reference/configuration/monitoring/cronhub.md
View file

@ -1,33 +0,0 @@
---
title: Cronhub
eleventyNavigation:
key: Cronhub
parent: 🚨 Monitoring
---
[Cronhub](https://cronhub.io/) provides "instant alerts when any of your
background jobs fail silently or run longer than expected," and borgmatic has
built-in integration with it. Once you create a Cronhub account and monitor on
their site, all you need to do is configure borgmatic with the unique "Ping
URL" for your monitor. Here's an example:
```yaml
cronhub:
ping_url: https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d031
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
this option in the `hooks:` section of your configuration.
With this configuration, borgmatic pings your Cronhub monitor when a backup
begins, ends, or errors, but only when any of the `create`, `prune`,
`compact`, or `check` actions are run. Then, if the actions complete
successfully or errors, borgmatic notifies Cronhub accordingly.
Note that even though you configure borgmatic with the "start" variant of the
ping URL, borgmatic substitutes the correct state into the URL when pinging
Cronhub ("start", "finish", or "fail").
You can configure Cronhub to notify you by a [variety of
mechanisms](https://docs.cronhub.io/integrations.html) when backups fail
or it doesn't hear from borgmatic for a certain period of time.

29
docs/reference/configuration/monitoring/cronitor.md
View file

@ -1,29 +0,0 @@
---
title: Cronitor
eleventyNavigation:
key: Cronitor
parent: 🚨 Monitoring
---
[Cronitor](https://cronitor.io/) provides "Cron monitoring and uptime healthchecks
for websites, services and APIs," and borgmatic has built-in
integration with it. Once you create a Cronitor account and cron job monitor on
their site, all you need to do is configure borgmatic with the unique "Ping
API URL" for your monitor. Here's an example:
```yaml
cronitor:
ping_url: https://cronitor.link/d3x0c1
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
this option in the `hooks:` section of your configuration.
With this configuration, borgmatic pings your Cronitor monitor when a backup
begins, ends, or errors, but only when any of the `create`, `prune`,
`compact`, or `check` actions are run. Then, if the actions complete
successfully or errors, borgmatic notifies Cronitor accordingly.
You can configure Cronitor to notify you by a [variety of
mechanisms](https://cronitor.io/docs/cron-job-notifications) when backups fail
or it doesn't hear from borgmatic for a certain period of time.

77
docs/reference/configuration/monitoring/healthchecks.md
View file

@ -1,77 +0,0 @@
---
title: Healthchecks
eleventyNavigation:
key: Healthchecks
parent: 🚨 Monitoring
---
[Healthchecks](https://healthchecks.io/) is a service that provides "instant
alerts when your cron jobs fail silently," and borgmatic has built-in
integration with it. Once you create a Healthchecks account and project on
their site, all you need to do is configure borgmatic with the unique "Ping
URL" for your project. Here's an example:
```yaml
healthchecks:
ping_url: https://hc-ping.com/addffa72-da17-40ae-be9c-ff591afb942a
```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
this option in the `hooks:` section of your configuration.
With this configuration, borgmatic pings your Healthchecks project when a
backup begins, ends, or errors, but only when any of the `create`, `prune`,
`compact`, or `check` actions are run.
You can configure Healthchecks to notify you by a [variety of
mechanisms](https://healthchecks.io/#welcome-integrations) when backups fail
or it doesn't hear from borgmatic for a certain period of time.
### Sending logs
<span class="minilink minilink-addedin">New in version 1.4.11</span> If the
actions complete successfully, borgmatic can notify Healthchecks of the success
and includes borgmatic logs in the payload data sent to Healthchecks. This
means that borgmatic logs can show up in the Healthchecks UI, although be aware
that Healthchecks currently has a 100-kilobyte limit for the logs in each ping.
<span class="minilink minilink-addedin">New in version 1.6.1</span> borgmatic
has a `send_logs` option to enable or disable log sending:
```yaml
healthchecks:
ping_url: https://hc-ping.com/addffa72-da17-40ae-be9c-ff591afb942a
send_logs: true
```
<span class="minilink minilink-addedin">New in version 2.1.0</span> To avoid
revealing private log information to a third-party service, logs are no longer
sent by default when `send_logs` is omitted.
<span class="minilink minilink-addedin">Prior to version 2.1.0</span> Logs were
sent by default when `send_logs` was omitted.
If an error occurs during any action or hook, borgmatic notifies Healthchecks,
also tacking on logs including the error itself. But the logs are only
included for errors that occur when a `create`, `prune`, `compact`, or `check`
action is run.
You can customize the verbosity of the logs that are sent to Healthchecks with
borgmatic's `--monitoring-verbosity` flag. The `--list` and `--stats` flags may
also be of use. See [create action
documentation](https://torsion.org/borgmatic/reference/command-line/actions/create/)
for more information.
<span class="minilink minilink-addedin">New in version 2.0.0</span>Set the
defaults for these flags in your borgmatic configuration via the
`monitoring_verbosity`, `list`, and `statistics` options.
### Full configuration
{% include snippet/configuration/sample.md %}
```yaml
{% include borgmatic/healthchecks.yaml %}
```

Some files were not shown because too many files have changed in this diff Show more