Re: [PATCH v2 14/14] Improve documentation for fuse service mount

[Bernd Schubert <bernd@bsbernd.com>]

On 9/29/26 04:43, Darrick J. Wong wrote:
> On Mon, Sep 28, 2026 at 01:02:16PM +0200, Bernd Schubert via B4 Relay wrote:
>> From: Bernd Schubert <bernd@bsbernd.com>
>>
>> Signed-off-by: Bernd Schubert <bernd@bsbernd.com>
>> ---
>>  doc/README.service-mount      | 312 +++++++++++++++++++++++++++++
>>  doc/README.service-mount-dev  | 456 ++++++++++++++++++++++++++++++++++++++++++
>>  doc/README.service-mount-flow | 201 +++++++++++++++++++
>>  doc/fuservicemount3.8         | 150 +++++++++++++-
>>  doc/mainpage.dox              |  13 ++
>>  doc/mount.fuse3.8             |  18 ++
>>  6 files changed, 1144 insertions(+), 6 deletions(-)
>>
>> diff --git a/doc/README.service-mount b/doc/README.service-mount
>> new file mode 100644
>> index 000000000000..859db863f3da
>> --- /dev/null
>> +++ b/doc/README.service-mount
>> @@ -0,0 +1,312 @@
>> +Mounting FUSE filesystems that run as a socket service
>> +======================================================
>> +
>> +This document is for administrators and end users who want to mount a FUSE
>> +filesystem whose server runs as a sandboxed systemd socket service, rather
>> +than as a process in the mount caller's own context.
>> +
>> +Developers who want to make their FUSE server runnable this way should read
>> +README.service-mount-dev instead.
>> +
>> +
>> +What a service mount is
>> +-----------------------
>> +
>> +A traditional FUSE filesystem runs as a child of whoever mounts it: it
>> +inherits that environment, needs mount permission, and can see the caller's
>> +files. A *service mount* instead keeps the FUSE server running as an
>> +independent systemd service. When someone mounts the filesystem, a small
>> +privileged helper (fuservicemount3) connects to the service over a UNIX
>> +socket, hands it the /dev/fuse device and any backing files it needs, and
>> +performs the mount on its behalf.
>> +
>> +The benefit is isolation. The server can run:
>> +
>> +  - as a separate, unprivileged uid/gid (systemd DynamicUser),
>> +  - with no capabilities at all,
>> +  - in private mount, network, and pid namespaces,
>> +  - with a restricted system-call filter,
>> +
>> +while still being mountable by an ordinary user. The server never gains mount
>> +permission and never runs in the caller's environment; the privileged work is
>> +confined to the fuservicemount3 helper. See example/service_ll@.service for a
>> +fully locked-down unit.
>> +
>> +
>> +Do I need this?
>> +---------------
>> +
>> +This feature exists for one specific goal: running a FUSE server with strong
>> +privilege separation, where the server itself is fully unprivileged and
>> +sandboxed while a separate setuid helper performs the mount. Getting that
>> +requires the server to be written to the fuse_service_* API (see
>> +README.service-mount-dev). An existing FUSE program that simply calls
>> +fuse_main() cannot be mounted this way unmodified: it opens /dev/fuse and
>> +performs the mount itself, which the sandbox does not allow.
>> +
>> +If all you want is to manage an ordinary FUSE filesystem with systemd --
>> +start/stop, journald logging, cgroup resource limits --
>> +you do NOT need this feature. Run the filesystem under a plain systemd service
>> +unit instead, launching it in the foreground so systemd can track it:
>> +
>> +    # myfs.service
>> +    [Service]
>> +    ExecStart=/usr/bin/myfs ... -f <mountpoint>
>> +
>> +systemd-run(1) starts the same thing as a transient unit, without a unit
>> +file. It passes the command line on as typed, so the filesystem can get any
>> +number of arguments. A unit file fixes them in its ExecStart= line, and a
>> +template unit (myfs@.service) takes only one parameter, the instance name.
>> +Set unit directives with -p:
>> +
>> +    sudo systemd-run -p MemoryMax=1G myfs <args> -f <mountpoint>
>> +
>> +This also works in the user's own service manager, as long as fusermount3 is
>> +installed setuid root:
>> +
>> +    systemd-run --user -p MemoryMax=1G myfs <args> -f <mountpoint>
>> +
>> +That filesystem still mounts the traditional way (through fusermount3) and
>> +runs in the service's own context; it is not isolated from the mount the way a
>> +service mount is.
>> +
>> +Use a service mount when you specifically want:
>> +
>> +  - the filesystem server to run as a separate, unprivileged uid with no
>> +    mount permission of its own,
>> +  - it confined to private mount/network/pid namespaces with no capabilities,
>> +  - the privileged mount work isolated in the fuservicemount3 helper,
>> +  - on-demand, socket-activated startup.
>> +
>> +In short: a plain systemd unit gives you lifecycle management; a service mount
>> +gives you lifecycle management AND isolation, at the cost of the fuse server
>> +author adapting the server to the service API.
> 
> "...the fuse server author needing to adapt..."
> 
> Everything below here looked ok to me, though I admit that there's a lot
> of documentation so I may have missed some fine details.


Sorry about about the verbose documentation, just painful to remember
all the details a few years later without it. And I also wanted to
explain to users why it is helpful.
Thanks again for looking it!


Cheers,
Bernd