From 88ecb96b98046c69e096f934660f426450b7a6b5 Mon Sep 17 00:00:00 2001
From: Dan Helfman <witten@torsion.org>
Date: Fri, 18 Jul 2025 21:32:49 -0700
Subject: [PATCH] Document systemd configuration changes for the ZFS filesystem
 hook (#1114).

---
 NEWS                                     |  1 +
 docs/how-to/snapshot-your-filesystems.md | 12 ++++++++++++
 sample/systemd/borgmatic.service         |  6 ++++--
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/NEWS b/NEWS
index 9981d239..f119c4c3 100644
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,5 @@
 2.0.8.dev0
+ * #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.
  * When running tests, use Ruff for faster and more comprehensive code linting and formatting,
diff --git a/docs/how-to/snapshot-your-filesystems.md b/docs/how-to/snapshot-your-filesystems.md
index c8e61d4d..aa776015 100644
--- a/docs/how-to/snapshot-your-filesystems.md
+++ b/docs/how-to/snapshot-your-filesystems.md
@@ -41,6 +41,10 @@ zfs:
     umount_command: /usr/local/bin/umount
 ```
 
+If you're using systemd to run borgmatic, you will likely need to modify the [sample systemd service
+file](https://projects.torsion.org/borgmatic-collective/borgmatic/raw/branch/main/sample/systemd/borgmatic.service)
+to work with ZFS. See the comments in that file for details.
+
 As long as the ZFS 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
@@ -160,6 +164,10 @@ btrfs:
     findmnt_command: /usr/local/bin/findmnt
 ```
 
+If you're using systemd to run borgmatic, you may need to modify the [sample systemd service
+file](https://projects.torsion.org/borgmatic-collective/borgmatic/raw/branch/main/sample/systemd/borgmatic.service)
+to work with Btrfs. See the comments in that file for details.
+
 As long as the Btrfs 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
@@ -276,6 +284,10 @@ lvm:
     umount_command: /usr/local/bin/umount
 ```
 
+If you're using systemd to run borgmatic, you may need to modify the [sample systemd service
+file](https://projects.torsion.org/borgmatic-collective/borgmatic/raw/branch/main/sample/systemd/borgmatic.service)
+to work with LVM. See the comments in that file for details.
+
 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
diff --git a/sample/systemd/borgmatic.service b/sample/systemd/borgmatic.service
index 564cbe99..8e227857 100644
--- a/sample/systemd/borgmatic.service
+++ b/sample/systemd/borgmatic.service
@@ -26,6 +26,7 @@ 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.
 PrivateDevices=yes
 PrivateTmp=yes
 ProtectClock=yes
@@ -39,7 +40,7 @@ RestrictNamespaces=yes
 RestrictRealtime=yes
 RestrictSUIDSGID=yes
 SystemCallArchitectures=native
-SystemCallFilter=@system-service
+SystemCallFilter=@system-service @mount
 SystemCallErrorNumber=EPERM
 # To restrict write access further, change "ProtectSystem" to "strict" and
 # uncomment "ReadWritePaths", "TemporaryFileSystem", "BindPaths" and
@@ -52,7 +53,8 @@ ProtectSystem=full
 # BindPaths=-/root/.cache/borg -/root/.config/borg -/root/.borgmatic
 # BindReadOnlyPaths=-/root/.ssh
 
-# May interfere with running external programs within borgmatic hooks.
+# May interfere with running external programs within borgmatic hooks. This
+# includes, for instance, programs to snapshot filesystems (e.g. ZFS).
 CapabilityBoundingSet=CAP_DAC_READ_SEARCH CAP_NET_RAW
 
 # Lower CPU and I/O priority.