deploy/systemd/README.md

@@ -16,7 +16,14 @@ Systemd **user** units for clawstor.
 ## Install `clawstor-fuse.service` (Linux)
 
 Prereqs: `libfuse3-dev` + `pkg-config` installed, `claw-fuse` binary built with
-`cargo build --release --features fuse --bin claw-fuse`.
+`cargo build --release --features fuse --bin claw-fuse`. Create the
+mount directory once before enabling the unit — the unit no longer
+does that itself (some Ubuntu builds refuse subsequent FUSE mounts
+after an ExecStartPre chain touches the mount point):
+
+```bash
+mkdir -p ~/clawstor-mount
+```
 
 ```bash
 # 1. Copy the binary

deploy/systemd/clawstor-fuse.service

@@ -1,24 +1,25 @@
 [Unit]
-Description=Clawstor read-only FUSE mount (blobs / snapshots / tags)
+Description=Clawstor read-only FUSE mount (blobs / snapshots / tags / refs)
 Documentation=https://git.redclaw.dev/clawverse/clawstor
-After=clawstor-cluster.service network-online.target
+After=network-online.target clawstor-cluster.service
 Wants=clawstor-cluster.service
 
 [Service]
 Type=simple
-# systemd expands %h (home) at parse time so the ExecStart binary
-# path resolves to an absolute path — env-var expansion in the
-# executable position is NOT supported (results in status=203).
-# Retarget via `systemctl --user edit clawstor-fuse.service`.
-# Create the mount point if missing (idempotent).
-ExecStartPre=/bin/mkdir -p %h/clawstor-mount
-# Best-effort pre-unmount in case a prior instance left a stale
-# mount (e.g. daemon SIGKILL). Leading `-` = ignore failure.
-ExecStartPre=-/usr/bin/fusermount3 -u -z %h/clawstor-mount
+# systemd expands %h (home) at parse time; env-var expansion in
+# the ExecStart binary position is NOT supported. Retarget via
+# `systemctl --user edit clawstor-fuse.service` if the install
+# path differs.
+#
+# Pre-6d we ran ExecStartPre=mkdir + ExecStartPre=fusermount3-u-z
+# to guard against stale mounts. On some Ubuntu builds (observed
+# on morpheus 2026-07-14) that combination made systemd refuse
+# the subsequent FUSE mount with EPERM even though a manual
+# invocation of the same binary succeeded. The minimal form here
+# — plain ExecStart, ExecStop = unmount — is what actually works
+# reliably across the fleet. Create the mount point manually
+# (mkdir -p ~/clawstor-mount) once before enabling this unit.
 ExecStart=%h/clawstor-deploy/claw-fuse --data-dir %h/clawstor-deploy/data --mount %h/clawstor-mount
-# The FUSE binary blocks until unmounted. On systemd stop we
-# unmount explicitly rather than relying on the binary's SIGTERM
-# handler.
 ExecStop=/usr/bin/fusermount3 -u %h/clawstor-mount
 Restart=on-failure
 RestartSec=5