Re: [PATCH v2 24/25] Add mount and daemonization README documents

[Bernd Schubert <bernd@bsbernd.com>]

On 3/31/26 03:17, Darrick J. Wong wrote:
> On Thu, Mar 26, 2026 at 10:34:57PM +0100, Bernd Schubert wrote:
>> These are useful to
>>
>> Signed-off-by: Bernd Schubert <bernd@bsbernd.com>
>> ---
>>  doc/README.daemonize  | 197 +++++++++++++++++++++++++++
>>  doc/README.fusermount | 362 ++++++++++++++++++++++++++++++++++++++++++++++++++
>>  doc/README.mount      |  86 ++++++++++++
>>  doc/README.sync-init  | 184 +++++++++++++++++++++++++
>>  4 files changed, 829 insertions(+)
>>
>> diff --git a/doc/README.daemonize b/doc/README.daemonize
>> new file mode 100644
>> index 0000000000000000000000000000000000000000..7b56c33077f29edbd335a2778120d9b6db6022ad
>> --- /dev/null
>> +++ b/doc/README.daemonize
>> @@ -0,0 +1,197 @@
>> +FUSE Daemonization API
>> +======================
>> +
>> +This document describes the FUSE daemonization APIs, including the legacy
>> +fuse_daemonize() function and the new fuse_daemonize_start()/signal() API
>> +introduced in libfuse 3.19.
>> +
>> +
>> +Overview
>> +--------
>> +
>> +FUSE filesystems often need to run as background daemons. Daemonization
>> +involves forking the process, creating a new session, and redirecting
>> +standard file descriptors. The challenge is properly reporting initialization
>> +failures to the parent process.
> 
> But why is it important to report init failures to the parent?
> 
> "The parent can, in turn, pass those errors up to whichever process
> started the fuse server."?
> 
>> +
>> +
>> +Old API: fuse_daemonize()
>> +--------------------------
>> +
>> +Function signature:
>> +    int fuse_daemonize(int foreground);
>> +
>> +Location: lib/helper.c
>> +
>> +This is the legacy daemonization API, primarily used with the high-level
>> +fuse_main() interface.
>> +
>> +Behavior:
>> +- If foreground=0: forks the process, creates a new Unix session,
>> +  redirects stdio
>> +- If foreground=1: only changes directory to "/"
>> +- Parent waits for a single byte on a pipe before exiting
>> +- Child writes completion byte immediately after redirecting stdio
>> +- Always changes directory to "/"
>> +
>> +Limitations:
>> +1. No failure reporting: The parent receives notification immediately after
>> +   fork/setsid, before any meaningful initialization (like mounting the
>> +   filesystem or starting threads).
>> +
>> +2. Timing constraint: Must be called AFTER fuse_session_mount() in existing
>> +   examples, because there's no way to report mount failures to the parent.
> 
> "...to report mount() failures...", specifically.
> 
>> +
>> +3. Thread initialization: Cannot report failures from complex initialization
>> +   steps like:
>> +   - Starting worker threads
>> +   - Network connection setup
>> +   - RDMA memory registration
>> +   - Resource allocation
>> +
>> +4. FUSE_SYNC_INIT incompatibility: With the FUSE_SYNC_INIT feature, FUSE_INIT
>> +   happens at mount time and may start io_uring threads. This requires
>> +   daemonization BEFORE mount, which the old API cannot handle properly.
>> +
>> +Example usage (old API):
>> +    fuse = fuse_new(...);
>> +    fuse_mount(fuse, mountpoint);
>> +    fuse_daemonize(opts.foreground);  // After mount, can't report mount failure
>> +    fuse_set_signal_handlers(se);
>> +    fuse_session_loop(se);
>> +
>> +
>> +New API: fuse_daemonize_start() / fuse_daemonize_success() / fuse_daemonize_fail()
>> +---------------------------------------------------------------------------------
>> +
>> +Functions:
>> +    int fuse_daemonize_start(unsigned int flags);
>> +    void fuse_daemonize_success(void);
>> +    void fuse_daemonize_fail(void);
>> +    bool fuse_daemonize_active(void);
>> +
>> +Location: lib/fuse_daemonize.c, include/fuse_daemonize.h
>> +Available since: libfuse 3.19
>> +
>> +This new API solves the limitations of fuse_daemonize() by splitting
>> +daemonization into two phases:
>> +
>> +1.   fuse_daemonize_start() - Fork and setup, but parent waits
>> +2.1. fuse_daemonize_fail() - Signal failure to parent
>> +2.2  fuse_daenmize_success() - Signal startup to success to the parent
> 
> fuse_daemonize_success()
> 
>> +     See below for an important detail.
>> +
>> +
>> +fuse_daemonize_start()
>> +----------------------
>> +
>> +Flags:
>> +- FUSE_DAEMONIZE_NO_CHDIR: Don't change directory to "/"
>> +- FUSE_DAEMONIZE_NO_BACKGROUND: Don't fork (foreground mode)
>> +
>> +Behavior:
>> +- Unless NO_BACKGROUND: forks the process
>> +- Parent waits for status signal from child
>> +- Child creates new session and continues
>> +- Unless NO_CHDIR: changes directory to "/"
>> +- Closes stdin immediately in child
>> +- Starts a watcher thread to detect parent death
>> +- Returns 0 in child on success, negative errno on error
>> +
>> +Parent death detection:
>> +- Uses a "death pipe" - parent keeps write end open
>> +- Child's watcher thread polls the read end
>> +- When parent dies, pipe gets POLLHUP and child exits
> 
> "If parent dies"?  Using the word "when" make it sound like the parent
> is supposed to die before the child.
> 
>> +- Prevents orphaned daemons if parent is killed
> 
> If the child dies unexpectedly, the read(signal_pipe[0], ...) call
> returns zero, so the parent will also exit, right?  I think that should
> be mentioned here.
> 
>> +
>> +
>> +fuse_daemonize_fail(int err)
>> +----------------------------
>> +
>> +Behavior:
>> +- Signals the parent about the provided error
>> +- Parent will exit with that error
>> +
>> +fuse_daemonize_success()
>> +------------------------
>> +- Signals the parent process with succes
>> +- On success: redirects stdout/stderr to /dev/null
> 
> For systemd service mode, it'd be nice to have a third flag that
> disables stdout/stderr redirection too, since it's expected in systemd
> land that stdout goes to journald/syslog.  I can add that in my own
> patchset.

I have definitely planned that, but please feel free to add it. I
frequently need stdout/err in syslog for ASAN runs.
I had patch/PR for passthrough_hp, but didn't like it and recently
closed the PR, because can be generalized with new daemonize API.

> 
>> +- Stops the parent watcher thread
>> +- Cleans up pipes and internal state
>> +- Safe to call multiple times
>> +- Safe to call even if fuse_daemonize_start() failed
>> +- *Important*: Should be called twice, once from ->init
>> +  (struct fuse_lowlevel_ops::init or for high level interface
>> +   struct fuse_operations::init) and after fuse_session_mount().
>> +  It will internally figure out which of these two calls will
>> +  actually signal the parent about success. Reason is that
>> +  sucess must only be signaled when the mount is complete and
> 
> success ^^^
> 
>> +  that depends on if synchronous or asynchronous FUSE_INIT is
>> +  used. 
>> +
>> +
>> +fuse_daemonize_active()
>> +-----------------------
>> +
>> +Returns true if daemonization is active and waiting for signal.
>> +
>> +Used by the high-level fuse_main() to detect if the application already
>> +called the new API, avoiding double-daemonization.
>> +
>> +
>> +Example usage (new API):
>> +-------------------------
>> +
>> +    // Start daemonization BEFORE mount
>> +    unsigned int daemon_flags = 0;
>> +    if (foreground)
>> +        daemon_flags |= FUSE_DAEMONIZE_NO_BACKGROUND;
>> +
>> +    if (fuse_daemonize_start(daemon_flags) != 0)
>> +        goto error;
>> +
>> +    // Complex initialization can fail and be reported
>> +    if (setup_threads() != 0)
>> +        goto error_signal;
>> +
>> +    if (setup_network() != 0)
>> +        goto error_signal;
>> +    // Mount can now fail and be reported to parent
>> +    if (fuse_session_mount(se, mountpoint) != 0)
>> +        goto error_signal;
>> +
>> +    // Signal success - parent exits with EXIT_SUCCESS
>> +    // This is typically done in the init() callback after FUSE_INIT
>> +    fuse_daemonize_signal(FUSE_DAEMONIZE_SUCCESS);
>> +
>> +    // Run main loop
>> +    fuse_session_loop(se);
>> +
>> +    return 0;
>> +
>> +error_signal:
>> +    // Signal failure - parent exits with EXIT_FAILURE
>> +    fuse_daemonize_signal(FUSE_DAEMONIZE_FAILURE);
>> +error:
>> +    return 1;
>> +
>> +
>> +When to signal success
>> +----------------------
>> +
>> +The success signal should be sent after all critical initialization is
>> +complete. For FUSE filesystems, this is typically in the init() callback,
>> +after FUSE_INIT has been processed successfully.
>> +
>> +Example (from passthrough_hp.cc):
>> +    static void sfs_init(void *userdata, fuse_conn_info *conn) {
>> +        // ... initialization ...
>> +        fuse_daemonize_signal(FUSE_DAEMONIZE_SUCCESS);
>> +    }
>> +
>> +This ensures the parent only exits after:
>> +- Mount succeeded
>> +- FUSE_INIT completed
>> +- All threads started
>> +- Filesystem is ready to serve requests
>> +
>> diff --git a/doc/README.fusermount b/doc/README.fusermount
>> new file mode 100644
>> index 0000000000000000000000000000000000000000..5b81651c8690aa25fef12db322af977c9cba1d31
>> --- /dev/null
>> +++ b/doc/README.fusermount
>> @@ -0,0 +1,362 @@
>> +Synchronous FUSE_INIT Protocol
>> +================================
> 
> Hm.  I thought I just got done reading a documnet about how synchronous
> FUSE_INIT works?  Looking at the copious references to fusermount3 under
> "Protocol Flow", is this the doc for how it works when fusermount is
> involved?
> 
>> +
>> +Overview
>> +--------
>> +
>> +The sync-init feature enables the FUSE library to start worker threads and
>> +perform initialization ioctl calls BEFORE the actual mount() syscall happens.
>> +This is required for the kernel's synchronous FUSE_INIT feature, where the
>> +mount() syscall blocks until the FUSE daemon processes the INIT request.
>> +
>> +Without this feature, there would be a deadlock:
>> +- mount() blocks waiting for INIT response
>> +- Worker threads can't start because mount() hasn't returned
>> +- INIT request can't be processed because worker threads aren't running
>> +
>> +
>> +Protocol Flow
>> +-------------
>> +
>> +Traditional mount flow:
>> +  1. Library calls fusermount3
>> +  2. fusermount3 opens /dev/fuse
>> +  3. fusermount3 performs mount() syscall
>> +  4. fusermount3 sends fd to library
>> +  5. Library starts worker threads
>> +  6. Worker threads process FUSE requests
>> +
>> +Sync-init mount flow:
>> +  1. Library calls fusermount3 with --sync-init flag
>> +  2. fusermount3 opens /dev/fuse
>> +  3. fusermount3 sends fd to library
>> +  4. Library receives fd
>> +  5. Library performs FUSE_DEV_IOC_SYNC_INIT ioctl
>> +  6. Library starts worker threads
>> +  7. Library sends "proceed" signal to fusermount3
>> +  8. fusermount3 performs mount() syscall (blocks until INIT completes)
>> +  9. Worker threads process INIT request
>> +  10. mount() syscall completes
>> +  11. fusermount3 exits
>> +
>> +
>> +Implementation Details
>> +----------------------
>> +
>> +Bidirectional Communication:
>> +  - Uses the existing unix socket (_FUSE_COMMFD environment variable)
>> +  - Simple 1-byte protocol for signaling
>> +  - Library signals fusermount3 when ready to proceed with mount
>> +
>> +fusermount3 Changes:
>> +  - New --sync-init command-line option
>> +  - Split mount operation into two phases:
>> +    * mount_fuse_prepare(): Opens device, prepares parameters
>> +    * mount_fuse_finish_fsmount(): Performs actual mount() syscall
>> +  - wait_for_signal(): Waits for library to signal readiness
>> +  - struct mount_context: Preserves state between phases
>> +
>> +Library Changes:
>> +  - fuse_session_mount_new_api(): Uses new protocol when available
>> +  - Sends "proceed" signal after worker thread is ready
>> +  - Handles both old and new mount protocols for compatibility
>> +
>> +
>> +Backward Compatibility
>> +----------------------
>> +
>> +The implementation maintains full backward compatibility:
>> +  - Old library + new fusermount3: Works (uses traditional flow)
>> +  - New library + old fusermount3: Falls back to traditional flow
> 
> "traditional", as in async FUSE_INIT?
> 
>> +  - New library + new fusermount3: Uses sync-init flow when appropriate
>> +
>> +
>> +Error Handling
>> +--------------
>> +
>> +If any step fails during the sync-init flow:
>> +  - fusermount3 closes the fd and exits with error
>> +  - Library detects failure and cleans up
>> +  - No mount is left in inconsistent state
>> +
>> +Connection closure:
>> +  - If library closes socket before signaling, fusermount3 detects and exits
>> +  - If fusermount3 crashes, library detects closed socket
>> +
>> +
>> +Security Considerations
>> +-----------------------
>> +
>> +The sync-init protocol does not introduce new security concerns:
>> +  - Uses the same privilege separation as traditional mount
>> +  - Socket communication is already established and trusted
>> +  - No new privileged operations are added
>> +  - File descriptor passing uses existing SCM_RIGHTS mechanism
>> +
>> +
>> +Performance Impact
>> +------------------
>> +
>> +Minimal performance impact:
>> +  - One additional recv() call in fusermount3
>> +  - One additional send() call in library
>> +  - Total overhead: ~2 context switches
>> +  - Only affects mount time, not runtime performance
>> +
>> +
>> +Future Enhancements
>> +-------------------
>> +
>> +Potential improvements:
>> +  - Extended protocol for more complex initialization sequences
>> +  - Support for multiple worker threads coordination
>> +  - Enhanced error reporting through the socket
>> +  - Timeout mechanisms for detecting hung initialization
> 
> Is that for libfuse detecting that a fusermount has hung?  Or for
> fusermount detecting that the fuse server hasn't responded to FUSE_INIT
> and giving up?  I suspect the former.
> 
>> +
>> +
>> +ASCII Workflow Diagrams
>> +========================
>> +
>> +1. Traditional Mount Flow (without --sync-init, async INIT)
>> +------------------------------------------------------------
>> +
>> +Library                   fusermount3              Kernel
>> +   |                           |                      |
>> +   |--- spawn fusermount3 ---->|                      |
>> +   |                           |                      |
>> +   |                      [open /dev/fuse]            |
>> +   |                           |------- open -------->|
>> +   |                           |<------ fd ---------- |
>> +   |                           |                      |
>> +   |                      [mount() syscall]           |
>> +   |                           |------ mount -------->|
>> +   |                           |<----- success ------ | [mount returns immediately]
>> +   |                           |                      | [INIT queued in kernel]
>> +   |                      [send_fd(fd)]               |
>> +   |<------- fd --------------|                      |
>> +   |                           |                      |
>> +   |                      [fusermount3 exits]         |
>> +   |                                                  |
>> +   |  [start worker thread]                          |
>> +   |  [worker reads /dev/fuse]                       |
>> +   |---------------------------------------- read -->|
>> +   |<--------------------------------------- INIT ---| [dequeued from kernel]
>> +   |                                                  |
>> +   | OK: INIT was queued, worker reads it later      |
>> +   |     Works fine for async INIT                   |
>> +
>> +
>> +1b. Problem: Synchronous INIT without --sync-init
>> +--------------------------------------------------
>> +
>> +Library                   fusermount3              Kernel
>> +   |                           |                      |
>> +   |--- spawn fusermount3 ---->|                      |
>> +   |                           |                      |
>> +   |                      [open /dev/fuse]            |
>> +   |                           |------- open -------->|
>> +   |                           |<------ fd ---------- |
>> +   |                           |                      |
>> +   |                      [mount() syscall]           |
>> +   |                           |------ mount -------->|
>> +   |                           |                      | [mount BLOCKS waiting for INIT]
>> +   |                           | (BLOCKED)            | [needs worker to process INIT]
>> +   |                           |                      |
>> +   |  [waiting for fd...]      |                      |
>> +   |                           |                      |
>> +   |                           |                      |
>> +   | DEADLOCK: mount() waits for INIT response       |
>> +   |           but worker thread not started yet     |
>> +   |           because we're waiting for fd          |
>> +
>> +
>> +2. Sync-Init Mount Flow (with --sync-init)
>> +-------------------------------------------
>> +
>> +Library                   fusermount3              Kernel
>> +   |                           |                      |
>> +   |--- spawn fusermount3 ---->|                      |
>> +   |    with --sync-init       |                      |
>> +   |                           |                      |
>> +   |                      [open /dev/fuse]            |
>> +   |                           |------- open -------->|
>> +   |                           |<------ fd ---------- |
>> +   |                           |                      |
>> +   |                      [send_fd(fd)]               |
>> +   |<------- fd --------------|                      |
>> +   |                           |                      |
>> +   |                      [wait_for_signal()]         |
>> +   |                           | (BLOCKED)            |
>> +   |                           |                      |
>> +   |  [ioctl SYNC_INIT]        |                      |
>> +   |---------------------------------------- ioctl -->|
>> +   |                                                  |
>> +   |  [start worker thread]                          |
>> +   |  [worker ready]                                 |
>> +   |                           |                      |
>> +   |--- "proceed" signal ----->|                      |
>> +   |                      [signal received]           |
>> +   |                           |                      |
>> +   |                      [mount() syscall]           |
>> +   |                           |------ mount -------->|
>> +   |                           |                      | [mount blocks]
>> +   |                           |                      | [sends INIT]
>> +   |<------------------------------------------------ |
>> +   |                           |                      |
>> +   | [worker processes INIT]   |                      |
>> +   |------------------------------------------------->|
>> +   |                           |                      | [mount unblocks]
>> +   |                           |<----- success ------ |
>> +   |                           |                      |
>> +   |                      [fusermount3 exits]         |
>> +   |                                                  |
>> +   | SUCCESS: Worker ready before mount()            |
>> +   |          INIT processed synchronously           |
>> +
>> +
>> +3. Error Scenario: Library Crashes Before Signaling
>> +----------------------------------------------------
>> +
>> +Library                   fusermount3              Kernel
>> +   |                           |                      |
>> +   |--- spawn fusermount3 ---->|                      |
>> +   |    with --sync-init       |                      |
>> +   |                           |                      |
>> +   |                      [open /dev/fuse]            |
>> +   |                           |------- open -------->|
>> +   |                           |<------ fd ---------- |
>> +   |                           |                      |
>> +   |                      [send_fd(fd)]               |
>> +   |<------- fd --------------|                      |
>> +   |                           |                      |
>> +   |                      [wait_for_signal()]         |
>> +   |                           | (BLOCKED)            |
>> +   |                           |                      |
>> +   X  [library crashes]        |                      |
>> +   |                           |                      |
>> +   |                      [recv() returns 0]          |
>> +   |                      [socket closed]             |
>> +   |                           |                      |
>> +   |                      [cleanup and exit]          |
>> +   |                           X                      |
>> +   |                                                  |
>> +   | RESULT: Clean failure, no mount performed       |
>> +
>> +
>> +4. Detailed Function Call Flow
>> +-------------------------------
>> +
>> +Library (lib/fuse_lowlevel.c):
>> +fuse_session_mount_new_api()
>> +   |
>> +   +-- fuse_kern_mount_prepare()  [lib/mount.c]
>> +   |      |
>> +   |      +-- fuse_mount_fusermount()  [lib/mount_util.c]
>> +   |             |
>> +   |             +-- socketpair()  [create comm socket]
>> +   |             |
>> +   |             +-- fork()
>> +   |             |
>> +   |             +-- [child] execl("fusermount3", "--sync-init", ...)
>> +   |             |
>> +   |             +-- [parent] receive_fd()  <--- BLOCKS until fd arrives
>> +   |                    |
>> +   |                    +-- recvmsg(SCM_RIGHTS)
>> +   |                    |
>> +   |                    +-- return fd
>> +   |
>> +   +-- session_start_sync_init()  [lib/fuse_lowlevel.c]
>> +   |      |
>> +   |      +-- ioctl(fd, FUSE_DEV_IOC_SYNC_INIT)
>> +   |      |
>> +   |      +-- pthread_create(worker_thread)
>> +   |      |
>> +   |      +-- return
>> +   |
>> +   +-- fuse_fusermount_proceed_mnt(socket)  [lib/mount.c] <--- NEW: Bidirectional handshake
>> +          |
>> +          +-- send(socket, "proceed", 1)  <--- Signal fusermount3 to proceed
>> +          |
>> +          +-- recv(socket, &status, 1)  <--- BLOCKS until mount result arrives
>> +          |      |
>> +          |      +-- [fusermount3 performs mount and sends status byte]
>> +          |
>> +          +-- if (status != 0) return -1  <--- Mount failed
>> +          |
>> +          +-- return 0  <--- Mount succeeded
>> +
>> +
>> +Utility (util/fusermount.c):
>> +fusermount3 main() with --sync-init
>> +   |
>> +   +-- mount_fuse_sync_init()  [util/fusermount.c]
>> +          |
>> +          +-- mount_fuse_prepare()  [util/fusermount.c]
>> +          |      |
>> +          |      +-- open("/dev/fuse")
>> +          |      |
>> +          |      +-- check_perm()  [util/fusermount.c]
>> +          |      |
>> +          |      +-- return fd
>> +          |
>> +          +-- send_fd(socket, fd)  [util/fusermount.c]
>> +          |      |
>> +          |      +-- sendmsg(SCM_RIGHTS)
>> +          |
>> +          +-- wait_for_signal(socket)  [util/fusermount.c] <--- BLOCKS until library signals
>> +          |      |
>> +          |      +-- recv(socket, buf, 1)
>> +          |      |
>> +          |      +-- return 0
>> +          |
>> +          +-- mount_fuse_finish_fsmount()  [util/fusermount.c]
>> +          |      |
>> +          |      +-- fuse_kern_fsmount()  [lib/mount_fsmount.c]
>> +          |      |      |
>> +          |      |      +-- fsopen("fuse", FSOPEN_CLOEXEC)
>> +          |      |      |      |
>> +          |      |      |      +-- [kernel creates filesystem context]
>> +          |      |      |
>> +          |      |      +-- fsconfig(fsfd, SET_STRING, "source", ...)
>> +          |      |      +-- fsconfig(fsfd, SET_STRING, "fd", fd_value, ...)
>> +          |      |      +-- fsconfig(fsfd, ...) [apply mount options]
>> +          |      |      +-- fsconfig(fsfd, CMD_CREATE, ...)
>> +          |      |      |
>> +          |      |      +-- fsmount(fsfd, FSMOUNT_CLOEXEC, mount_attrs)
>> +          |      |      |      |
>> +          |      |      |      +-- [kernel sends FUSE_INIT here]
>> +          |      |      |      |
>> +          |      |      |      +-- [worker thread processes INIT]
>> +          |      |      |      |
>> +          |      |      |      +-- [fsmount returns mntfd]
>> +          |      |      |
>> +          |      |      +-- move_mount(mntfd, "", AT_FDCWD, target, ...)
>> +          |      |      |      |
>> +          |      |      |      +-- [attach mount to target directory]
>> +          |      |      |      |
>> +          |      |      |      +-- [no blocking - INIT already processed]
>> +          |      |      |
>> +          |      |      +-- add_mount()  [lib/mount_fsmount.c - update /etc/mtab]
>> +          |      |      |
>> +          |      |      +-- return 0 on success, -1 on failure
>> +          |      |
>> +          |      +-- if mount failed: return -1
>> +          |      +-- if mount succeeded: continue
>> +          |
>> +          +-- send_status_byte(socket)  [util/fusermount.c] <--- NEW: Send result to library
>> +          |      |
>> +          |      +-- status = (mount_result == 0) ? 0 : 1
>> +          |      +-- send(socket, &status, 1)
>> +          |      |
>> +          |      +-- return
>> +          |
>> +          +-- return 0
>> +
>> +
>> +Note: The new mount API (fsopen/fsconfig/fsmount/move_mount) is REQUIRED
>> +      for sync-init because fsmount() triggers FUSE_INIT before the mount
>> +      is attached. This allows the worker thread to process INIT before
>> +      move_mount() completes, preventing deadlock.
>> +      And also so we don't expose the directory tree to the mountns until we
>> +      know that FUSE_INIT didn't crash the server.
> 
> Question: Can libfuse call fuse_reply_err in response to an ->init call
> if the fuse server wants to fail a synchronous mount?  Right now it
> looks as if it always calls fuse_reply_ok, but I'm curious because that
> might be a more graceful way for a fuse server to fail than just
> terminating.

I guess so, see fs/fuse/dev.c fuse_request_end()

	if (test_bit(FR_ASYNC, &req->flags))
		req->args->end(fm, req->args, req->out.h.error);


> 
> (Granted the kernel still has to handle the fuse server blowing up
> unintentionally.)
> 
>> +
>> diff --git a/doc/README.mount b/doc/README.mount
>> new file mode 100644
>> index 0000000000000000000000000000000000000000..526382ad8a5f6b405a7cb1927b79bacd6c2c2c5c
>> --- /dev/null
>> +++ b/doc/README.mount
>> @@ -0,0 +1,86 @@
>> +FUSE Mount API Flowcharts
>> +=========================
>> +
>> +Old Mount API
>> +-------------
>> +
>> +fuse_kern_mount()
>> +  |
>> +  +-- fuse_mount_sys()
>> +  |     +-- Try direct mount → mount() syscall
>> +  |     +-- On EPERM: fuse_mount_fusermount()
>> +  |           +-- socketpair()
>> +  |           +-- spawn fusermount3 (no --sync-init)
>> +  |           +-- fusermount3: open /dev/fuse, mount(), send fd
>> +  |           +-- receive_fd() → return fd
>> +  |
>> +  +-- Worker threads started AFTER mount
>> +  └─> FUSE_INIT asynchronous (queued in kernel)
>> +
>> +
>> +New Mount API - Privileged Mount
>> +---------------------------------
>> +
>> +fuse_session_mount_new_api()
>> +  |
>> +  +-- fuse_kern_mount_prepare() → open /dev/fuse → fd
>> +  |
>> +  +-- session_start_sync_init(se, fd)
>> +  |     +-- ioctl(fd, FUSE_DEV_IOC_SYNC_INIT)
>> +  |     +-- pthread_create(worker) → ready to process FUSE_INIT
>> +  |
>> +  +-- fuse_kern_fsmount_mo()
>> +  |     +-- fsopen/fsconfig/fsmount (BLOCKS until FUSE_INIT completes)
>> +  |     +-- Worker processes FUSE_INIT during fsmount()
>> +  |     +-- move_mount()
>> +  |
>> +  +-- session_wait_sync_init_completion(se) → pthread_join
>> +  └─> return fd
>> +
>> +
>> +New Mount API - EPERM Fallback (fusermount3 with sync-init)
>> +------------------------------------------------------------
>> +
>> +fuse_session_mount_new_api()
>> +  |
>> +  +-- fuse_kern_mount_prepare() → open /dev/fuse → fd1
>> +  |
>> +  +-- session_start_sync_init(se, fd1)
>> +  |     +-- ioctl(fd1, FUSE_DEV_IOC_SYNC_INIT)
>> +  |     +-- pthread_create(worker) → ready with fd1
>> +  |
>> +  +-- fuse_kern_fsmount_mo() → EPERM
>> +  |
>> +  +-- *** FALLBACK TO FUSERMOUNT3 WITH SYNC-INIT ***
>> +  |
>> +  +-- session_wait_sync_init_completion(se)
>> +  |     +-- pthread_cancel/join → terminate worker with wrong fd1
>> +  |
>> +  +-- close(fd1)
>> +  |
>> +  +-- fuse_mount_fusermount_sync_init()  [NEW]
>> +  |     +-- socketpair()
>> +  |     +-- spawn fusermount3 --sync-init
>> +  |     +-- fusermount3: open /dev/fuse → fd2, send fd2
>> +  |     +-- receive_fd() → fd2
>> +  |     +-- fusermount3 waits for signal
>> +  |     └─> return fd2, sock
>> +  |
>> +  +-- session_start_sync_init(se, fd2)
>> +  |     +-- ioctl(fd2, FUSE_DEV_IOC_SYNC_INIT)
>> +  |     +-- pthread_create(worker) → ready with fd2
>> +  |
>> +  +-- send_proceed_signal(sock)  [NEW]
>> +  |     +-- send(sock, "\0", 1) → signal fusermount3
>> +  |
>> +  +-- fusermount3: mount() (BLOCKS)
>> +  |     +-- Kernel sends FUSE_INIT to fd2
>> +  |     +-- Worker processes FUSE_INIT
>> +  |     +-- mount() returns
>> +  |
>> +  +-- close(sock)
>> +  |
>> +  +-- session_wait_sync_init_completion(se) → pthread_join
>> +  |
>> +  └─> return fd2
> 
> I'm not sure how useful it is to mention what's inside these functions,
> since one could read the code and I worry that the code will diverge
> very quickly.
> 
>> +
>> diff --git a/doc/README.sync-init b/doc/README.sync-init
>> new file mode 100644
>> index 0000000000000000000000000000000000000000..44e47a2eef2c45026abaa19562537eef37f256b9
>> --- /dev/null
>> +++ b/doc/README.sync-init
>> @@ -0,0 +1,184 @@
>> +FUSE Synchronous vs Asynchronous FUSE_INIT
>> +============================================
>> +
>> +This document explains the difference between asynchronous and synchronous
>> +FUSE_INIT processing, and when each mode is used.
>> +
>> +
>> +Overview
>> +--------
>> +
>> +FUSE_INIT is the initial handshake between the kernel FUSE module and the
>> +userspace filesystem daemon. During this handshake, the kernel and daemon
>> +negotiate capabilities, protocol version, and various feature flags.
>> +
>> +Asynchronous FUSE_INIT (Traditional Behavior)
>> +----------------------------------------------
>> +
>> +In the traditional asynchronous mode:
>> +
>> +1. mount() syscall completes and returns to caller
>> +2. Filesystem appears mounted to the system
>> +3. FUSE daemon starts worker threads
>> +4. Worker threads process FUSE_INIT request
>> +5. Filesystem becomes fully operational
>> +
>> +Timeline:
>> +    mount() -----> returns
>> +                   |
>> +                   v
>> +            FUSE_INIT sent
>> +                   |
>> +                   v
>> +            daemon processes FUSE_INIT
>> +                   |
>> +                   v
>> +            filesystem ready
>> +
>> +Limitations:
>> +
>> +1. **No early requests**: The kernel cannot send requests (like getxattr)
>> +   during the mount() syscall. This breaks SELinux, which needs to query
>> +   extended attributes on the root inode immediately upon mounting.
>> +
>> +2. **Daemonization timing**: With the old fuse_daemonize() API, the daemon
>> +   must call it AFTER mount, because there's no way to report mount failures
>> +   to the parent process if daemonization happens first.
>> +
>> +3. **No custom root inode**: The root inode ID is hardcoded to FUSE_ROOT_ID (1)
>> +   because FUSE_INIT hasn't been processed yet when the mount completes.
>> +
>> +4. **Thread startup after mount**: io_uring threads and other worker threads
>> +   can only start after mount() returns, not before.
>> +
>> +
>> +Synchronous FUSE_INIT (New Behavior)
>> +-------------------------------------
>> +
>> +Kernel support: Linux kernel commit dfb84c330794 (v6.18+)
>> +libfuse support: libfuse 3.19+
>> +
>> +In synchronous mode:
>> +
>> +1. FUSE daemon opens /dev/fuse
>> +2. Daemon calls ioctl(fd, FUSE_DEV_IOC_SYNC_INIT)
>> +3. Daemon starts worker thread
>> +4. Daemon calls mount() syscall
>> +5. Kernel sends FUSE_INIT during mount() - mount() blocks
>> +6. Worker thread processes FUSE_INIT while mount() is blocked
>> +7. Worker thread may process additional requests (getxattr, etc.)
>> +8. mount() syscall completes and returns
>> +9. Filesystem is fully operational
>> +
>> +Timeline:
>> +    open /dev/fuse
>> +         |
>> +         v
>> +    ioctl(FUSE_DEV_IOC_SYNC_INIT)
>> +         |
>> +         v
>> +    start worker thread
>> +         |
>> +         v
>> +    mount() -----> blocks
>> +         |         |
>> +         |         v
>> +         |    FUSE_INIT sent
>> +         |         |
>> +         |         v
>> +         |    worker processes FUSE_INIT
>> +         |         |
>> +         |         v
>> +         |    (possible getxattr, etc.)
>> +         |         |
>> +         +-------> returns
>> +                   |
>> +                   v
>> +            filesystem ready
>> +
>> +Advantages:
>> +
>> +1. **SELinux support**: The kernel can send getxattr requests during mount()
>> +   to query security labels on the root inode.
>> +
>> +2. **Early daemonization**: The daemon can fork BEFORE mount using the new
>> +   fuse_daemonize_start()/signal() API, and report mount failures to the
>> +   parent process.
>> +
>> +3. **Custom root inode**: The daemon can specify a custom root inode ID
>> +   during FUSE_INIT, before mount() completes.
> 
> Where?  Or are you talking about this?
> https://lore.kernel.org/linux-fsdevel/177188735166.3936993.12658858435281080344.stgit@frogsfrogsfrogs/
> 
> but perhaps the root nodeid can be supplied in the reply from the
> synchronous FUSE_INIT?
> 
>> +
>> +4. **Thread startup before mount**: io_uring threads and worker threads
>> +   start before mount(), ensuring they're ready to handle requests.
>> +
>> +5. **Better error reporting**: Mount failures and initialization errors
>> +   can be properly reported to the parent process when using the new
>> +   daemonization API.
>> +
>> +
>> +When Synchronous FUSE_INIT is Used
>> +-----------------------------------
>> +
>> +libfuse automatically enables synchronous FUSE_INIT when:
>> +
>> +1. The application calls fuse_session_want_sync_init(), OR
>> +2. The new daemonization API is used (fuse_daemonize_start() was called)
>> +
>> +Synchronous FUSE_INIT requires:
>> +- Kernel support (commit dfb84c330794 or later)
>> +- Worker thread started before mount()
>> +- ioctl(FUSE_DEV_IOC_SYNC_INIT) succeeds
>> +
>> +If the kernel doesn't support synchronous FUSE_INIT, libfuse automatically
>> +falls back to asynchronous mode.
>> +
>> +
>> +Implementation Details
>> +----------------------
>> +
>> +The synchronous FUSE_INIT implementation uses a worker thread:
>> +
>> +- **session_sync_init_worker()**: Thread function that polls /dev/fuse
>> +  and processes FUSE_INIT and any subsequent requests until mount completes.
>> +
>> +- **session_start_sync_init()**: Creates the worker thread before mount().
>> +  Calls ioctl(FUSE_DEV_IOC_SYNC_INIT) to enable kernel support.
>> +
>> +- **session_wait_sync_init_completion()**: Waits for the worker thread
>> +  to complete after mount() returns. Checks for errors.
>> +
>> +The worker thread processes requests in a loop until se->terminate_mount_worker
>> +is set, which happens after mount() completes successfully.
> 
> Now that I've looked through this more carefully, I think it's all right
> to do this.
> 
>> +
>> +
>> +Compatibility
>> +-------------
>> +
>> +Synchronous FUSE_INIT is fully backward compatible:
>> +
>> +- Old kernels: ioctl returns ENOTTY, libfuse falls back to async mode
>> +- Old applications: Continue to work with async FUSE_INIT
>> +- New applications on old kernels: Graceful fallback to async mode
>> +- New applications on new kernels: Automatic sync mode when appropriate
>> +
>> +
>> +Example: Enabling Synchronous FUSE_INIT
>> +----------------------------------------
>> +
>> +Explicit request:
>> +    struct fuse_session *se = fuse_session_new(...);
>> +    fuse_session_want_sync_init(se);
>> +    fuse_session_mount(se, mountpoint);
>> +
>> +Automatic (with new daemonization API):
>> +    fuse_daemonize_start(0);  // Triggers sync init automatically
>> +    fuse_session_mount(se, mountpoint);
>> +
>> +
>> +See Also
>> +--------
>> +
>> +- doc/README.daemonize - New daemonization API documentation
>> +- doc/README.fusermount - Synchronous FUSE_INIT protocol with fusermount3
>> +- doc/README.mount - Mount implementation details
> 
> Thanks for splitting out the documentation updates.
> 
> --D
> 
>> +
>>
>> -- 
>> 2.43.0
>>
>>