Add snapshot_size option (#80).

This commit is contained in:
Dan Helfman 2024-12-02 11:09:07 -08:00
parent cd654cbb57
commit 6367a00013
3 changed files with 109 additions and 6 deletions

View File

@ -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: |

View File

@ -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.

View File

@ -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
<span class="minilink minilink-addedin">New in version 1.9.4</span> <span
class="minilink minilink-addedin">Beta feature</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.
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.
<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/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.