Add snapshot_size option (#80).

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