diff --git a/borgmatic/config/schema.yaml b/borgmatic/config/schema.yaml
index 98e59e82..e0a7faf3 100644
--- a/borgmatic/config/schema.yaml
+++ b/borgmatic/config/schema.yaml
@@ -2308,6 +2308,16 @@ properties:
type: ["object", "null"]
additionalProperties: false
properties:
+ snapshot_size:
+ type: string
+ description: |
+ Size to allocate for each snapshot taken, including the
+ units to use for that size. Defaults to "10%ORIGIN" (10%
+ of the size of logical volume being snapshotted). See the
+ lvcreate "--size" and "--extents" documentation for more
+ information:
+ https://www.man7.org/linux/man-pages/man8/lvcreate.8.html
+ example: 5GB
lvcreate_command:
type: string
description: |
diff --git a/borgmatic/hooks/data_source/lvm.py b/borgmatic/hooks/data_source/lvm.py
index 6a3b7568..cbca7ff3 100644
--- a/borgmatic/hooks/data_source/lvm.py
+++ b/borgmatic/hooks/data_source/lvm.py
@@ -62,18 +62,18 @@ def get_logical_volumes(lsblk_command, source_directories=None):
def snapshot_logical_volume(
- lvcreate_command, snapshot_name, logical_volume_device
+ lvcreate_command, snapshot_name, logical_volume_device, snapshot_size,
): # pragma: no cover
'''
- Given an lvcreate command to run, a snapshot name, and the path to the logical volume device to
- snapshot, create a new LVM snapshot.
+ Given an lvcreate command to run, a snapshot name, the path to the logical volume device to
+ snapshot, and a snapshot size string, create a new LVM snapshot.
'''
borgmatic.execute.execute_command(
(
lvcreate_command,
'--snapshot',
- '--extents',
- '1', # The snapshot doesn't need much disk space because it's read-only.
+ ('--extents' if '%' in snapshot_size else '--size'),
+ snapshot_size,
'--name',
snapshot_name,
logical_volume_device,
@@ -102,6 +102,9 @@ def mount_snapshot(mount_command, snapshot_device, snapshot_mount_path): # prag
)
+DEFAULT_SNAPSHOT_SIZE = '10%ORIGIN'
+
+
def dump_data_sources(
hook_config,
config,
@@ -142,7 +145,8 @@ def dump_data_sources(
if not dry_run:
snapshot_logical_volume(
- hook_config.get('lvcreate_command', 'lvcreate'), snapshot_name, device_path
+ hook_config.get('lvcreate_command', 'lvcreate'), snapshot_name, device_path,
+ hook_config.get('snapshot_size', DEFAULT_SNAPSHOT_SIZE),
)
# Get the device path for the device path for the snapshot we just created.
diff --git a/docs/how-to/snapshot-your-filesystems.md b/docs/how-to/snapshot-your-filesystems.md
index d8f5327f..1330ccee 100644
--- a/docs/how-to/snapshot-your-filesystems.md
+++ b/docs/how-to/snapshot-your-filesystems.md
@@ -145,3 +145,92 @@ Subvolume snapshots are stored in a Borg archive as normal files, so you can use
the standard [extract
action](https://torsion.org/borgmatic/docs/how-to/extract-a-backup/) to extract
them.
+
+
+### LVM
+
+New in version 1.9.4 Beta feature 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.
+
+To use this feature, first you need one or more mounted LVM logical volumes.
+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 desired you can
+override some of the options used by the LVM hook. For instance:
+
+```yaml
+lvm:
+ snapshot_size: 5GB # See below for details.
+ lvcreate_command: /usr/local/bin/lvcreate
+ lvremove_command: /usr/local/bin/lvremove
+ lvs_command: /usr/local/bin/lvs
+ lsbrk_command: /usr/local/bin/lsbrk
+ mount_command: /usr/local/bin/mount
+ umount_command: /usr/local/bin/umount
+```
+
+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.
+
+
+#### Snapshot size
+
+The `snapshot_size` option is the size to allocate for each snapshot taken,
+including the units to use for that size. 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 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.
+
+During a backup, borgmatic automatically snapshots these discovered logical
+volumes (non-recursively), temporary mounts the snapshots within its [runtime
+directory](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/#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.
+
+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 `/mnt/lvolume`, then the snapshotted files
+will appear in an archive at `/mnt/lvolume` as well.
+
+With Borg version 1.2 and
+earlierSnapshotted files are instead stored at a path dependent on the
+[runtime
+directory](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/#runtime-directory)
+in use at the time the archive was created, as Borg 1.2 and earlier do not
+support path rewriting.
+
+
+#### 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/docs/how-to/extract-a-backup/) to
+extract them.