From 6367a0001320f50e793022b467363cbc1fd69fe6 Mon Sep 17 00:00:00 2001 From: Dan Helfman Date: Mon, 2 Dec 2024 11:09:07 -0800 Subject: [PATCH] Add snapshot_size option (#80). --- borgmatic/config/schema.yaml | 10 +++ borgmatic/hooks/data_source/lvm.py | 16 +++-- docs/how-to/snapshot-your-filesystems.md | 89 ++++++++++++++++++++++++ 3 files changed, 109 insertions(+), 6 deletions(-) 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.