Borgmatic for Debian
====================

Intro
-----
2.0.11-1 begins the effort to make it easier to get started with
automatic backups--and to keep them running.  The goal I'm reaching
towards is to eventually implement a debconf (Debian configuration
management system, https://wiki.debian.org/debconf) interface like
Exim has.  When the goal is achieved, Debian users who chose either
the default LVM, LUKS+LVM, or btrfs config will have access to a near
out-of-the box backup solution that uses frozen/snapshotted data as
the source instead of data-in-flight.  Why?  Data-in-flight has no
guaranties of consistency, and most people don't know that attempting
to backup a database that is being written to will often create a
corrupted and useless backup where the data is out of sync with either
the transaction log.  Application databases that are used by a lot of
modern desktop software (Firefox, Thunderbird, Akonadi, etc) are part
of a user's $HOME (ie /home/john).

TODO: Documentation needs to be packaged so that this README can refer to it.
      (Bug #1056364)

Getting Started
---------------
At this time, here is the fastest way to setup Borgmatic:

  1. Congrats, if you're reading this in /usr/share/doc/borgmatic/README.Debian
     then borgmatic is already installed!
  2. Run this in a terminal:

         sudo borgmatic config generate

     This command will generate a default config at /etc/borgmatic/config.yaml
  3. /etc/borgmatic/config.yaml needs to be edited and configured.  refer to
  TODO: package local copy of docs and provide local links (Bug #1056364),
  or if someone has deleted your local copy of the documentation, these are
  the two upstream references you need:
     https://torsion.org/borgmatic/how-to/set-up-backups/
     https://torsion.org/borgmatic/reference/configuration/
  4. After completing the upstream HOWTO you will have created a borg
     repository for use by borgmatic, validated your config, manually run a
     backup, manually initiated a backup (which succeeded), and used a cron
     drop-in config or systemd unit to automate backups.
  5. Now restore your files from a recent manual or automatic backup,
     because an untested backup cannot yet be trusted to contain what
     one hopes it contains.

Other Notes
-----------
Borgmatic for Debian treats /etc/borgmatic.d/* like other locations
for drop-in configuration, thus configuration under /etc/borgmatic.d
will NOT be automaticaly migrated in case of breaking changes.  A
side-effect of this policy is that users who wish to opt-out of
auto-migrated configuration should place their configuration in
/etc/borgmatic.d rather than /etc/borgmatic

 -- Nicholas D Steeves <sten@debian.org>, Sun, 30 Nov 2025 18:20:03 -0500