[PATCH] umount.2: Document the effect of shared subtrees on umount

[ebiederm@xmission.com (Eric W. Biederman)]

Signed-off-by: Eric W. Biederman <ebiederm@xmission.com>
---
 man2/umount.2 | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/man2/umount.2 b/man2/umount.2
index aea39d8306fe..a0120b2fc811 100644
--- a/man2/umount.2
+++ b/man2/umount.2
@@ -97,6 +97,24 @@ Don't dereference
 if it is a symbolic link.
 This flag allows security problems to be avoided in set-user-ID-\fIroot\fP
 programs that allow unprivileged users to unmount filesystems.
+
+.P
+Shared mount points cause any mount activity on that mount point
+including umounts to be forwarded to every shared mount point in it's
+peer group and every slave mount of that peer group.  This means that
+umount of any peer in a set of shared mounts will cause all of it's
+peers to be unmounted and all of their slaves to be unmounted as well.
+
+This propogagtion of unmount activity can be particularly surprising
+on systems where every mount point is shared by default.  On such
+systems recursively bind mounting the root directory of the filesystem
+onto a subdirectory and then later unmounting that subdirectory with
+.BR MNT_DETACH
+will cause every mount in the mount namespace to be lazily unmounted.
+
+To ensure umount does not propagate the mount point may be
+remounted with MS_REC | MS_PRIVATE prior to umount being called.
+
 .SH RETURN VALUE
 On success, zero is returned.
 On error, \-1 is returned, and
-- 
1.9.1