From a77de447d415540d0bfdd68864b2df59b1b879d7 Mon Sep 17 00:00:00 2001
From: Dan Helfman <witten@torsion.org>
Date: Tue, 2 Dec 2025 17:25:36 -0800
Subject: [PATCH] Document potential interactions between systemd security
 settings and the ZFS, LVM, and Btrfs hooks (#1192, #1163).

---
 NEWS                                               | 2 ++
 docs/reference/configuration/data-sources/btrfs.md | 9 +++++++++
 docs/reference/configuration/data-sources/lvm.md   | 9 +++++++++
 docs/reference/configuration/data-sources/zfs.md   | 9 +++++++++
 sample/systemd/borgmatic.service                   | 9 +++++++--
 5 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/NEWS b/NEWS
index 9c731c80..83d60b1a 100644
--- a/NEWS
+++ b/NEWS
@@ -2,6 +2,8 @@
  * #1192: Fix for over-aggressive deduplication of source directories that contain the borgmatic
    runtime directory, potentially resulting in data loss (data not getting backed up) when
    snapshotting these source directories.
+ * #1192, #1163: Document potential interactions between security settings in borgmatic's sample
+   systemd service file and the ZFS, LVM, and Btrfs hooks.
  * #1194: Fix for an incorrect diff command shown when running the "generate config" action with a
    source configuration file. 
  * #1195: Fix a regression in the ZFS, LVM, and Btrfs hooks in which snapshotted paths ignored
diff --git a/docs/reference/configuration/data-sources/btrfs.md b/docs/reference/configuration/data-sources/btrfs.md
index 16cf48d3..3685df13 100644
--- a/docs/reference/configuration/data-sources/btrfs.md
+++ b/docs/reference/configuration/data-sources/btrfs.md
@@ -92,6 +92,15 @@ it looks up file paths in its cache—it constructs the cache key with the path
 full absolute source path (which changes).
 
 
+## systemd settings
+
+If you're using [systemd to run
+borgmatic](https://torsion.org/borgmatic/how-to/set-up-backups/#systemd), you
+may need to disable particular security settings like `CapabilityBoundingSet` to
+allow the Btrfs feature to work. See the comments in the sample systemd service
+file for details.
+
+
 ## Full configuration
 
 ```yaml
diff --git a/docs/reference/configuration/data-sources/lvm.md b/docs/reference/configuration/data-sources/lvm.md
index a0beb75f..3bece395 100644
--- a/docs/reference/configuration/data-sources/lvm.md
+++ b/docs/reference/configuration/data-sources/lvm.md
@@ -114,6 +114,15 @@ the cache key with the path *as it's seen in the archive* (which is consistent
 across runs) rather than the full absolute source path (which can change).
 
 
+## systemd settings
+
+If you're using [systemd to run
+borgmatic](https://torsion.org/borgmatic/how-to/set-up-backups/#systemd), you
+may need to disable particular security settings like `ProtectKernelModules`,
+`CapabilityBoundingSet`, and/or `PrivateDevices` to allow the LVM feature to
+work. See the comments in the sample systemd service file for details.
+
+
 ## Full configuration
 
 ```yaml
diff --git a/docs/reference/configuration/data-sources/zfs.md b/docs/reference/configuration/data-sources/zfs.md
index de628c3b..dcffdae7 100644
--- a/docs/reference/configuration/data-sources/zfs.md
+++ b/docs/reference/configuration/data-sources/zfs.md
@@ -103,6 +103,15 @@ the cache key with the path *as it's seen in the archive* (which is consistent
 across runs) rather than the full absolute source path (which can change).
 
 
+## systemd settings
+
+If you're using [systemd to run
+borgmatic](https://torsion.org/borgmatic/how-to/set-up-backups/#systemd), you
+may need to disable particular security settings like `CapabilityBoundingSet`
+and/or `PrivateDevices` to allow the ZFS feature to work. See the comments in
+the sample systemd service file for details.
+
+
 ## Full configuration
 
 ```yaml
diff --git a/sample/systemd/borgmatic.service b/sample/systemd/borgmatic.service
index 8e227857..e5a6ecc0 100644
--- a/sample/systemd/borgmatic.service
+++ b/sample/systemd/borgmatic.service
@@ -26,13 +26,16 @@ LockPersonality=true
 # But you can try setting it to "yes" for improved security if you don't use those features.
 MemoryDenyWriteExecute=no
 NoNewPrivileges=yes
-# Filesystem hooks like ZFS may not work unless PrivateDevices is disabled.
+# Filesystem hooks like ZFS and LVM may not work unless PrivateDevices is disabled.
 PrivateDevices=yes
 PrivateTmp=yes
 ProtectClock=yes
 ProtectControlGroups=yes
 ProtectHostname=yes
 ProtectKernelLogs=yes
+# You may need to disable this if you're using the LVM hook. But an alternative
+# might be to leave this enabled and preload the necessary kernel modules like
+# "dm_snapshot" at boot, so this service doesn't need to load them on demand.
 ProtectKernelModules=yes
 ProtectKernelTunables=yes
 RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
@@ -54,7 +57,9 @@ ProtectSystem=full
 # BindReadOnlyPaths=-/root/.ssh
 
 # May interfere with running external programs within borgmatic hooks. This
-# includes, for instance, programs to snapshot filesystems (e.g. ZFS).
+# includes, for instance, programs to snapshot filesystems (e.g. ZFS, LVM, and
+# Btrfs). But rather than commenting this out entirely, one workaround may be to
+# add "CAP_SYS_ADMIN".
 CapabilityBoundingSet=CAP_DAC_READ_SEARCH CAP_NET_RAW
 
 # Lower CPU and I/O priority.