From 3f5dc09141a7bfe286620a6869d1d70ffe32d6b8 Mon Sep 17 00:00:00 2001 From: Christian Brauner Date: Wed, 23 Sep 2026 14:28:00 +0200 Subject: [PATCH] docs: update the unmount propagation rule Section 5f still describes the rule propagate_umount() used before commit f0d0ba19985d ("Rewrite of propagate_umount()"). It states that a mount that receives the unmount by propagation is left alone as soon as it has any submount. That's not true anymore. A propagated unmount unmounts a mount with sub-mounts as long as every sub-mount gets unmounted together with it. This is the case when the sub-mounts are unmounted by the same propagation. Only a sub-mount that cannot be unmounted keeps its parent mounted. The section also only describes a single mount without sub-mounts. But lazy unmounts take a tree and every mount of the tree propagates its unmount from its parent mount. Link: https://patch.msgid.link/20260923-work-mount-fixes-v1-8-f424cf8d3242@kernel.org Signed-off-by: Christian Brauner (Amutable) --- Documentation/filesystems/sharedsubtree.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/Documentation/filesystems/sharedsubtree.rst b/Documentation/filesystems/sharedsubtree.rst index 8b7dc9159083..8bae6d9a7e04 100644 --- a/Documentation/filesystems/sharedsubtree.rst +++ b/Documentation/filesystems/sharedsubtree.rst @@ -564,8 +564,8 @@ f) Unmount semantics where 'A' is a mount mounted on mount 'B' at dentry 'b'. If mount 'B' is shared, then all most-recently-mounted mounts at dentry - 'b' on mounts that receive propagation from mount 'B' and does not have - sub-mounts within them are unmounted. + 'b' on mounts that receive propagation from mount 'B' are unmounted as + well, if every mount below them is also unmounted. Example: Let's say 'B1', 'B2', 'B3' are shared mounts that propagate to each other. @@ -584,10 +584,18 @@ f) Unmount semantics So all 'C1', 'C2' and 'C3' should be unmounted. - If any of 'C2' or 'C3' has some child mounts, then that mount is not - unmounted, but all other mounts are unmounted. However if 'C1' is told - to be unmounted and 'C1' has some sub-mounts, the umount operation is - failed entirely. + If any of 'C2' or 'C3' has a child mount that cannot be unmounted + then that mount is not unmounted. But all other mounts are unmounted. + A child mount that is itself unmounted by the same unmount + propagation does not keep its parent mounted. However if 'C1' is + supposed to be unmounted and 'C1' has some sub-mounts, the unmount + fails. + + A lazy umount (MNT_DETACH) takes a whole tree. Every mount of the + tree then propagates its unmount from its own parent as described + above, so the mounts that receive propagation lose the corresponding + trees as well. Documentation/filesystems/propagate_umount.txt has the + precise rules, including the ones for locked mounts. g) Clone Namespace