diff --git a/NEWS b/NEWS
index fe0d7ac8..5e601436 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,9 @@
* #1114: Document systemd configuration changes for the ZFS filesystem hook.
* #1118: Fix a bug in which Borg hangs during database backup when different filesystems are in
use.
+ * #1125: Clarify documentation about ZFS, Btrfs, and LVM snapshotting when a separate
+ filesystem is mounted in the source directory. (Spoiler: The separate filesystem doesn't get
+ included in the snapshot.)
* #1126: Create LVM snapshots as read-write to avoid an error when snapshotting ext4 filesystems
with orphaned files that need recovery.
* #1133: Fix the "spot" check to include borgmatic configuration files that were backed up to
diff --git a/docs/how-to/snapshot-your-filesystems.md b/docs/how-to/snapshot-your-filesystems.md
index aa776015..334c4a0f 100644
--- a/docs/how-to/snapshot-your-filesystems.md
+++ b/docs/how-to/snapshot-your-filesystems.md
@@ -74,8 +74,8 @@ won't snapshot datasets with the `canmount=off` property, which is often set on
datasets that only serve as a container for other datasets. Use `zfs get
canmount datasetname` to see the `canmount` value for a dataset.
-During a backup, borgmatic automatically snapshots these discovered datasets
-(non-recursively), temporarily mounts the snapshots within its [runtime
+During a backup, borgmatic automatically snapshots these discovered datasets,
+temporarily 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 (destroying) these snapshots after a backup
@@ -88,6 +88,12 @@ in an archive at `/var/dataset` as well—even if borgmatic has to mount the
snapshot somewhere in `/run/user/1000/borgmatic/zfs_snapshots/` to perform the
backup.
+If a dataset has a separate filesystem mounted somewhere within it, that
+filesystem won't get included in the snapshot. For instance, if `/` is a ZFS
+dataset but `/boot` is a separate filesystem, borgmatic won't include `/boot` as
+part of the dataset snapshot. You can however add `/boot` to
+`source_directories` if you'd like it included in your backup.
+
New in version 1.9.4 borgmatic
is smart enough to look at the parent (and grandparent, etc.) directories of
each of your `source_directories` to discover any datasets. For instance,
@@ -189,9 +195,9 @@ used if the subvolume was mounted elsewhere; only the mount point could be used.
using `source_directories`, you can include the subvolume path as a root pattern
with borgmatic's `patterns` or `patterns_from` options.
-During a backup, borgmatic snapshots these subvolumes (non-recursively) 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.
+During a backup, borgmatic snapshots these subvolumes 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.
borgmatic is smart enough to look at the parent (and grandparent, etc.)
directories of each of your `source_directories` to discover any subvolumes. For
@@ -201,6 +207,12 @@ snapshot `/var` accordingly. This also works even with nested subvolumes;
borgmatic selects the subvolume that's the "closest" parent to your source
directories.
+If a subvolume has a separate filesystem mounted somewhere within it, that
+filesystem won't get included in the snapshot. For instance, if `/` is a Btrfs
+subvolume but `/boot` is a separate filesystem, borgmatic won't include `/boot`
+as part of the subvolume snapshot. You can however add `/boot` to
+`source_directories` if you'd like it included in your backup.
+
New in version 1.9.6 When using
[patterns](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-help-patterns),
the initial portion of a pattern's path that you intend borgmatic to match
@@ -262,8 +274,8 @@ KVM that contains an MBR, partitions, etc.).
In those cases, you can omit the `lvm:` option and use Borg's own support for
[image backup](https://borgbackup.readthedocs.io/en/stable/deployment/image-backup.html).
-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
+To use the LVM snapshot 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
@@ -334,6 +346,12 @@ volumes. For instance, let's say you add `/var/log` and `/var/lib` to your
source directories, but `/var` is a logical volume. borgmatic will discover
that and snapshot `/var` accordingly.
+If a logical volume has a separate filesystem mounted somewhere within it, that
+filesystem won't get included in the snapshot. For instance, if `/` is an LVM
+logical volume but `/boot` is a separate filesystem, borgmatic won't include
+`/boot` as part of the logical volume snapshot. You can however add `/boot` to
+`source_directories` if you'd like it included in your backup.
+
New in version 1.9.6 When using
[patterns](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-help-patterns),
the initial portion of a pattern's path that you intend borgmatic to match