From c9b282bc662145de2b54effbdba33f9df37f0dd3 Mon Sep 17 00:00:00 2001
From: Christian Schwarz <me@cschwarz.com>
Date: Sun, 15 Feb 2026 23:04:53 +0000
Subject: [PATCH] draft for user delegation setups;
 https://github.com/zrepl/zrepl/discussions/926

---
 docs/installation/user-privileges.rst | 56 ++++++++++++++++++++++++---
 1 file changed, 51 insertions(+), 5 deletions(-)

diff --git a/docs/installation/user-privileges.rst b/docs/installation/user-privileges.rst
index 40d0868..4f1448e 100644
--- a/docs/installation/user-privileges.rst
+++ b/docs/installation/user-privileges.rst
@@ -3,10 +3,56 @@
 User Privileges
 ---------------
 
-It is possible to run zrepl as an unprivileged user in combination with
-`ZFS delegation <https://www.freebsd.org/doc/handbook/zfs-zfs-allow.html>`_.
-Also, there is the possibility to run it in a jail on FreeBSD by delegating a dataset to the jail.
+zrepl can run as an unprivileged user with `ZFS delegation <https://www.freebsd.org/doc/handbook/zfs-zfs-allow.html>`_.
+**Help us document working setups on this page** by opening a PR!
 
-.. TIP::
+.. NOTE::
 
-    Note: check out the :ref:`installation-freebsd-jail-with-iocage` for FreeBSD jail setup instructions.
+   Keep in mind that ``zfs send``/``recv`` was never designed with
+   untrusted input in mind. An attacker controlling the send-recv stream could probably crash the
+   receive-side kernel, exploit bugs to get code execution, or induce stateful damage to the receive-side pool.
+
+
+Known Working Setups
+^^^^^^^^^^^^^^^^^^^^
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 40 20
+
+   * - OS
+     - Use Case
+     - Last Tested Version
+   * - Linux
+     - sink job (receiving)
+     - v0.7.0
+
+.. _installation-user-privileges-my-example-setup:
+
+My Example Setup
+^^^^^^^^^^^^^^^^
+
+I'm on Linux (Ubuntu ...) and run ``zrepl daemon`` as an unprivileged user, using a custom systemd unit file.
+
+:: code-block:: bash
+   ...
+   [Service]
+   User=zrepl
+   Group=zrepl
+   ...
+
+I set up the ZFS persmissions as follows:
+
+.. code-block:: bash
+
+   # receiving side root filesystem
+   zfs allow -u zrepl bookmark,create,destroy,hold,mount,mountpoint,receive,refreservation,userprop backuppool/zrepl
+   # sending side
+   zfs allow -u zrepl bookmark,destroy,hold,send,userprop prodpool
+
+**Notes:**
+
+* ``snapshot`` is NOT needed for receiving (only for pruning operations)
+* ``refreservation`` avoids non-sparse volume issues on receiving side
+* Add ``snapshot`` if your jobs perform sender or receiver-side pruning
+* Encryption and other features may require additional permissions