Adding upstream version 6.05.01.upstream/6.05.01

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1371 insertions, 0 deletions

diff --git a/man7/mount_namespaces.7 b/man7/mount_namespaces.7
new file mode 100644
index 0000000..0ce2fee
--- /dev/null
+++ b/man7/mount_namespaces.7
@@ -0,0 +1,1371 @@
+'\" t
+.\" Copyright (c) 2016, 2019, 2021 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\"
+.TH mount_namespaces 7 2023-05-03 "Linux man-pages 6.05.01"
+.SH NAME
+mount_namespaces \- overview of Linux mount namespaces
+.SH DESCRIPTION
+For an overview of namespaces, see
+.BR namespaces (7).
+.PP
+Mount namespaces provide isolation of the list of mounts seen
+by the processes in each namespace instance.
+Thus, the processes in each of the mount namespace instances
+will see distinct single-directory hierarchies.
+.PP
+The views provided by the
+.IR /proc/ pid /mounts ,
+.IR /proc/ pid /mountinfo ,
+and
+.IR /proc/ pid /mountstats
+files (all described in
+.BR proc (5))
+correspond to the mount namespace in which the process with the PID
+.I pid
+resides.
+(All of the processes that reside in the same mount namespace
+will see the same view in these files.)
+.PP
+A new mount namespace is created using either
+.BR clone (2)
+or
+.BR unshare (2)
+with the
+.B CLONE_NEWNS
+flag.
+When a new mount namespace is created,
+its mount list is initialized as follows:
+.IP \[bu] 3
+If the namespace is created using
+.BR clone (2),
+the mount list of the child's namespace is a copy
+of the mount list in the parent process's mount namespace.
+.IP \[bu]
+If the namespace is created using
+.BR unshare (2),
+the mount list of the new namespace is a copy of
+the mount list in the caller's previous mount namespace.
+.PP
+Subsequent modifications to the mount list
+.RB ( mount (2)
+and
+.BR umount (2))
+in either mount namespace will not (by default) affect the
+mount list seen in the other namespace
+(but see the following discussion of shared subtrees).
+.\"
+.SH SHARED SUBTREES
+After the implementation of mount namespaces was completed,
+experience showed that the isolation that they provided was,
+in some cases, too great.
+For example, in order to make a newly loaded optical disk
+available in all mount namespaces,
+a mount operation was required in each namespace.
+For this use case, and others,
+the shared subtree feature was introduced in Linux 2.6.15.
+This feature allows for automatic, controlled propagation of
+.BR mount (2)
+and
+.BR umount (2)
+.I events
+between namespaces
+(or, more precisely, between the mounts that are members of a
+.I peer group
+that are propagating events to one another).
+.PP
+Each mount is marked (via
+.BR mount (2))
+as having one of the following
+.IR "propagation types" :
+.TP
+.B MS_SHARED
+This mount shares events with members of a peer group.
+.BR mount (2)
+and
+.BR umount (2)
+events immediately under this mount will propagate
+to the other mounts that are members of the peer group.
+.I Propagation
+here means that the same
+.BR mount (2)
+or
+.BR umount (2)
+will automatically occur
+under all of the other mounts in the peer group.
+Conversely,
+.BR mount (2)
+and
+.BR umount (2)
+events that take place under
+peer mounts will propagate to this mount.
+.TP
+.B MS_PRIVATE
+This mount is private; it does not have a peer group.
+.BR mount (2)
+and
+.BR umount (2)
+events do not propagate into or out of this mount.
+.TP
+.B MS_SLAVE
+.BR mount (2)
+and
+.BR umount (2)
+events propagate into this mount from
+a (master) shared peer group.
+.BR mount (2)
+and
+.BR umount (2)
+events under this mount do not propagate to any peer.
+.IP
+Note that a mount can be the slave of another peer group
+while at the same time sharing
+.BR mount (2)
+and
+.BR umount (2)
+events
+with a peer group of which it is a member.
+(More precisely, one peer group can be the slave of another peer group.)
+.TP
+.B MS_UNBINDABLE
+This is like a private mount,
+and in addition this mount can't be bind mounted.
+Attempts to bind mount this mount
+.RB ( mount (2)
+with the
+.B MS_BIND
+flag) will fail.
+.IP
+When a recursive bind mount
+.RB ( mount (2)
+with the
+.B MS_BIND
+and
+.B MS_REC
+flags) is performed on a directory subtree,
+any bind mounts within the subtree are automatically pruned
+(i.e., not replicated)
+when replicating that subtree to produce the target subtree.
+.PP
+For a discussion of the propagation type assigned to a new mount,
+see NOTES.
+.PP
+The propagation type is a per-mount-point setting;
+some mounts may be marked as shared
+(with each shared mount being a member of a distinct peer group),
+while others are private
+(or slaved or unbindable).
+.PP
+Note that a mount's propagation type determines whether
+.BR mount (2)
+and
+.BR umount (2)
+of mounts
+.I immediately under
+the mount are propagated.
+Thus, the propagation type does not affect propagation of events for
+grandchildren and further removed descendant mounts.
+What happens if the mount itself is unmounted is determined by
+the propagation type that is in effect for the
+.I parent
+of the mount.
+.PP
+Members are added to a
+.I peer group
+when a mount is marked as shared and either:
+.IP (a) 5
+the mount is replicated during the creation of a new mount namespace; or
+.IP (b)
+a new bind mount is created from the mount.
+.PP
+In both of these cases, the new mount joins the peer group
+of which the existing mount is a member.
+.PP
+A new peer group is also created when a child mount is created under
+an existing mount that is marked as shared.
+In this case, the new child mount is also marked as shared and
+the resulting peer group consists of all the mounts
+that are replicated under the peers of parent mounts.
+.PP
+A mount ceases to be a member of a peer group when either
+the mount is explicitly unmounted,
+or when the mount is implicitly unmounted because a mount namespace is removed
+(because it has no more member processes).
+.PP
+The propagation type of the mounts in a mount namespace
+can be discovered via the "optional fields" exposed in
+.IR /proc/ pid /mountinfo .
+(See
+.BR proc (5)
+for details of this file.)
+The following tags can appear in the optional fields
+for a record in that file:
+.TP
+.I shared:X
+This mount is shared in peer group
+.IR X .
+Each peer group has a unique ID that is automatically
+generated by the kernel,
+and all mounts in the same peer group will show the same ID.
+(These IDs are assigned starting from the value 1,
+and may be recycled when a peer group ceases to have any members.)
+.TP
+.I master:X
+This mount is a slave to shared peer group
+.IR X .
+.TP
+.IR propagate_from:X " (since Linux 2.6.26)"
+.\" commit 97e7e0f71d6d948c25f11f0a33878d9356d9579e
+This mount is a slave and receives propagation from shared peer group
+.IR X .
+This tag will always appear in conjunction with a
+.I master:X
+tag.
+Here,
+.I X
+is the closest dominant peer group under the process's root directory.
+If
+.I X
+is the immediate master of the mount,
+or if there is no dominant peer group under the same root,
+then only the
+.I master:X
+field is present and not the
+.I propagate_from:X
+field.
+For further details, see below.
+.TP
+.I unbindable
+This is an unbindable mount.
+.PP
+If none of the above tags is present, then this is a private mount.
+.SS MS_SHARED and MS_PRIVATE example
+Suppose that on a terminal in the initial mount namespace,
+we mark one mount as shared and another as private,
+and then view the mounts in
+.IR /proc/self/mountinfo :
+.PP
+.in +4n
+.EX
+sh1# \fBmount \-\-make\-shared /mntS\fP
+sh1# \fBmount \-\-make\-private /mntP\fP
+sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+77 61 8:17 / /mntS rw,relatime shared:1
+83 61 8:15 / /mntP rw,relatime
+.EE
+.in
+.PP
+From the
+.I /proc/self/mountinfo
+output, we see that
+.I /mntS
+is a shared mount in peer group 1, and that
+.I /mntP
+has no optional tags, indicating that it is a private mount.
+The first two fields in each record in this file are the unique
+ID for this mount, and the mount ID of the parent mount.
+We can further inspect this file to see that the parent mount of
+.I /mntS
+and
+.I /mntP
+is the root directory,
+.IR / ,
+which is mounted as private:
+.PP
+.in +4n
+.EX
+sh1# \fBcat /proc/self/mountinfo | awk \[aq]$1 == 61\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+61 0 8:2 / / rw,relatime
+.EE
+.in
+.PP
+On a second terminal,
+we create a new mount namespace where we run a second shell
+and inspect the mounts:
+.PP
+.in +4n
+.EX
+$ \fBPS1=\[aq]sh2# \[aq] sudo unshare \-m \-\-propagation unchanged sh\fP
+sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+222 145 8:17 / /mntS rw,relatime shared:1
+225 145 8:15 / /mntP rw,relatime
+.EE
+.in
+.PP
+The new mount namespace received a copy of the initial mount namespace's
+mounts.
+These new mounts maintain the same propagation types,
+but have unique mount IDs.
+(The
+.I \-\-propagation\~unchanged
+option prevents
+.BR unshare (1)
+from marking all mounts as private when creating a new mount namespace,
+.\" Since util-linux 2.27
+which it does by default.)
+.PP
+In the second terminal, we then create submounts under each of
+.I /mntS
+and
+.I /mntP
+and inspect the set-up:
+.PP
+.in +4n
+.EX
+sh2# \fBmkdir /mntS/a\fP
+sh2# \fBmount /dev/sdb6 /mntS/a\fP
+sh2# \fBmkdir /mntP/b\fP
+sh2# \fBmount /dev/sdb7 /mntP/b\fP
+sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+222 145 8:17 / /mntS rw,relatime shared:1
+225 145 8:15 / /mntP rw,relatime
+178 222 8:22 / /mntS/a rw,relatime shared:2
+230 225 8:23 / /mntP/b rw,relatime
+.EE
+.in
+.PP
+From the above, it can be seen that
+.I /mntS/a
+was created as shared (inheriting this setting from its parent mount) and
+.I /mntP/b
+was created as a private mount.
+.PP
+Returning to the first terminal and inspecting the set-up,
+we see that the new mount created under the shared mount
+.I /mntS
+propagated to its peer mount (in the initial mount namespace),
+but the new mount created under the private mount
+.I /mntP
+did not propagate:
+.PP
+.in +4n
+.EX
+sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+77 61 8:17 / /mntS rw,relatime shared:1
+83 61 8:15 / /mntP rw,relatime
+179 77 8:22 / /mntS/a rw,relatime shared:2
+.EE
+.in
+.\"
+.SS MS_SLAVE example
+Making a mount a slave allows it to receive propagated
+.BR mount (2)
+and
+.BR umount (2)
+events from a master shared peer group,
+while preventing it from propagating events to that master.
+This is useful if we want to (say) receive a mount event when
+an optical disk is mounted in the master shared peer group
+(in another mount namespace),
+but want to prevent
+.BR mount (2)
+and
+.BR umount (2)
+events under the slave mount
+from having side effects in other namespaces.
+.PP
+We can demonstrate the effect of slaving by first marking
+two mounts as shared in the initial mount namespace:
+.PP
+.in +4n
+.EX
+sh1# \fBmount \-\-make\-shared /mntX\fP
+sh1# \fBmount \-\-make\-shared /mntY\fP
+sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+132 83 8:23 / /mntX rw,relatime shared:1
+133 83 8:22 / /mntY rw,relatime shared:2
+.EE
+.in
+.PP
+On a second terminal,
+we create a new mount namespace and inspect the mounts:
+.PP
+.in +4n
+.EX
+sh2# \fBunshare \-m \-\-propagation unchanged sh\fP
+sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+168 167 8:23 / /mntX rw,relatime shared:1
+169 167 8:22 / /mntY rw,relatime shared:2
+.EE
+.in
+.PP
+In the new mount namespace, we then mark one of the mounts as a slave:
+.PP
+.in +4n
+.EX
+sh2# \fBmount \-\-make\-slave /mntY\fP
+sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+168 167 8:23 / /mntX rw,relatime shared:1
+169 167 8:22 / /mntY rw,relatime master:2
+.EE
+.in
+.PP
+From the above output, we see that
+.I /mntY
+is now a slave mount that is receiving propagation events from
+the shared peer group with the ID 2.
+.PP
+Continuing in the new namespace, we create submounts under each of
+.I /mntX
+and
+.IR /mntY :
+.PP
+.in +4n
+.EX
+sh2# \fBmkdir /mntX/a\fP
+sh2# \fBmount /dev/sda3 /mntX/a\fP
+sh2# \fBmkdir /mntY/b\fP
+sh2# \fBmount /dev/sda5 /mntY/b\fP
+.EE
+.in
+.PP
+When we inspect the state of the mounts in the new mount namespace,
+we see that
+.I /mntX/a
+was created as a new shared mount
+(inheriting the "shared" setting from its parent mount) and
+.I /mntY/b
+was created as a private mount:
+.PP
+.in +4n
+.EX
+sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+168 167 8:23 / /mntX rw,relatime shared:1
+169 167 8:22 / /mntY rw,relatime master:2
+173 168 8:3 / /mntX/a rw,relatime shared:3
+175 169 8:5 / /mntY/b rw,relatime
+.EE
+.in
+.PP
+Returning to the first terminal (in the initial mount namespace),
+we see that the mount
+.I /mntX/a
+propagated to the peer (the shared
+.IR /mntX ),
+but the mount
+.I /mntY/b
+was not propagated:
+.PP
+.in +4n
+.EX
+sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+132 83 8:23 / /mntX rw,relatime shared:1
+133 83 8:22 / /mntY rw,relatime shared:2
+174 132 8:3 / /mntX/a rw,relatime shared:3
+.EE
+.in
+.PP
+Now we create a new mount under
+.I /mntY
+in the first shell:
+.PP
+.in +4n
+.EX
+sh1# \fBmkdir /mntY/c\fP
+sh1# \fBmount /dev/sda1 /mntY/c\fP
+sh1# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+132 83 8:23 / /mntX rw,relatime shared:1
+133 83 8:22 / /mntY rw,relatime shared:2
+174 132 8:3 / /mntX/a rw,relatime shared:3
+178 133 8:1 / /mntY/c rw,relatime shared:4
+.EE
+.in
+.PP
+When we examine the mounts in the second mount namespace,
+we see that in this case the new mount has been propagated
+to the slave mount,
+and that the new mount is itself a slave mount (to peer group 4):
+.PP
+.in +4n
+.EX
+sh2# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+168 167 8:23 / /mntX rw,relatime shared:1
+169 167 8:22 / /mntY rw,relatime master:2
+173 168 8:3 / /mntX/a rw,relatime shared:3
+175 169 8:5 / /mntY/b rw,relatime
+179 169 8:1 / /mntY/c rw,relatime master:4
+.EE
+.in
+.\"
+.SS MS_UNBINDABLE example
+One of the primary purposes of unbindable mounts is to avoid
+the "mount explosion" problem when repeatedly performing bind mounts
+of a higher-level subtree at a lower-level mount.
+The problem is illustrated by the following shell session.
+.PP
+Suppose we have a system with the following mounts:
+.PP
+.in +4n
+.EX
+# \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP
+/dev/sda1 on /
+/dev/sdb6 on /mntX
+/dev/sdb7 on /mntY
+.EE
+.in
+.PP
+Suppose furthermore that we wish to recursively bind mount
+the root directory under several users' home directories.
+We do this for the first user, and inspect the mounts:
+.PP
+.in +4n
+.EX
+# \fBmount \-\-rbind / /home/cecilia/\fP
+# \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP
+/dev/sda1 on /
+/dev/sdb6 on /mntX
+/dev/sdb7 on /mntY
+/dev/sda1 on /home/cecilia
+/dev/sdb6 on /home/cecilia/mntX
+/dev/sdb7 on /home/cecilia/mntY
+.EE
+.in
+.PP
+When we repeat this operation for the second user,
+we start to see the explosion problem:
+.PP
+.in +4n
+.EX
+# \fBmount \-\-rbind / /home/henry\fP
+# \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP
+/dev/sda1 on /
+/dev/sdb6 on /mntX
+/dev/sdb7 on /mntY
+/dev/sda1 on /home/cecilia
+/dev/sdb6 on /home/cecilia/mntX
+/dev/sdb7 on /home/cecilia/mntY
+/dev/sda1 on /home/henry
+/dev/sdb6 on /home/henry/mntX
+/dev/sdb7 on /home/henry/mntY
+/dev/sda1 on /home/henry/home/cecilia
+/dev/sdb6 on /home/henry/home/cecilia/mntX
+/dev/sdb7 on /home/henry/home/cecilia/mntY
+.EE
+.in
+.PP
+Under
+.IR /home/henry ,
+we have not only recursively added the
+.I /mntX
+and
+.I /mntY
+mounts, but also the recursive mounts of those directories under
+.I /home/cecilia
+that were created in the previous step.
+Upon repeating the step for a third user,
+it becomes obvious that the explosion is exponential in nature:
+.PP
+.in +4n
+.EX
+# \fBmount \-\-rbind / /home/otto\fP
+# \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP
+/dev/sda1 on /
+/dev/sdb6 on /mntX
+/dev/sdb7 on /mntY
+/dev/sda1 on /home/cecilia
+/dev/sdb6 on /home/cecilia/mntX
+/dev/sdb7 on /home/cecilia/mntY
+/dev/sda1 on /home/henry
+/dev/sdb6 on /home/henry/mntX
+/dev/sdb7 on /home/henry/mntY
+/dev/sda1 on /home/henry/home/cecilia
+/dev/sdb6 on /home/henry/home/cecilia/mntX
+/dev/sdb7 on /home/henry/home/cecilia/mntY
+/dev/sda1 on /home/otto
+/dev/sdb6 on /home/otto/mntX
+/dev/sdb7 on /home/otto/mntY
+/dev/sda1 on /home/otto/home/cecilia
+/dev/sdb6 on /home/otto/home/cecilia/mntX
+/dev/sdb7 on /home/otto/home/cecilia/mntY
+/dev/sda1 on /home/otto/home/henry
+/dev/sdb6 on /home/otto/home/henry/mntX
+/dev/sdb7 on /home/otto/home/henry/mntY
+/dev/sda1 on /home/otto/home/henry/home/cecilia
+/dev/sdb6 on /home/otto/home/henry/home/cecilia/mntX
+/dev/sdb7 on /home/otto/home/henry/home/cecilia/mntY
+.EE
+.in
+.PP
+The mount explosion problem in the above scenario can be avoided
+by making each of the new mounts unbindable.
+The effect of doing this is that recursive mounts of the root
+directory will not replicate the unbindable mounts.
+We make such a mount for the first user:
+.PP
+.in +4n
+.EX
+# \fBmount \-\-rbind \-\-make\-unbindable / /home/cecilia\fP
+.EE
+.in
+.PP
+Before going further, we show that unbindable mounts are indeed unbindable:
+.PP
+.in +4n
+.EX
+# \fBmkdir /mntZ\fP
+# \fBmount \-\-bind /home/cecilia /mntZ\fP
+mount: wrong fs type, bad option, bad superblock on /home/cecilia,
+       missing codepage or helper program, or other error
+\&
+       In some cases useful info is found in syslog \- try
+       dmesg | tail or so.
+.EE
+.in
+.PP
+Now we create unbindable recursive bind mounts for the other two users:
+.PP
+.in +4n
+.EX
+# \fBmount \-\-rbind \-\-make\-unbindable / /home/henry\fP
+# \fBmount \-\-rbind \-\-make\-unbindable / /home/otto\fP
+.EE
+.in
+.PP
+Upon examining the list of mounts,
+we see there has been no explosion of mounts,
+because the unbindable mounts were not replicated
+under each user's directory:
+.PP
+.in +4n
+.EX
+# \fBmount | awk \[aq]{print $1, $2, $3}\[aq]\fP
+/dev/sda1 on /
+/dev/sdb6 on /mntX
+/dev/sdb7 on /mntY
+/dev/sda1 on /home/cecilia
+/dev/sdb6 on /home/cecilia/mntX
+/dev/sdb7 on /home/cecilia/mntY
+/dev/sda1 on /home/henry
+/dev/sdb6 on /home/henry/mntX
+/dev/sdb7 on /home/henry/mntY
+/dev/sda1 on /home/otto
+/dev/sdb6 on /home/otto/mntX
+/dev/sdb7 on /home/otto/mntY
+.EE
+.in
+.\"
+.SS Propagation type transitions
+The following table shows the effect that applying a new propagation type
+(i.e.,
+.IR mount\~\-\-make\-xxxx )
+has on the existing propagation type of a mount.
+The rows correspond to existing propagation types,
+and the columns are the new propagation settings.
+For reasons of space, "private" is abbreviated as "priv" and
+"unbindable" as "unbind".
+.TS
+lb2 lb2 lb2 lb2 lb1
+lb | l l l l l.
+	make-shared	make-slave	make-priv	make-unbind
+_
+shared	shared	slave/priv [1]	priv	unbind
+slave	slave+shared	slave [2]	priv	unbind
+slave+shared	slave+shared	slave	priv	unbind
+private	shared	priv [2]	priv	unbind
+unbindable	shared	unbind [2]	priv	unbind
+.TE
+.sp 1
+Note the following details to the table:
+.IP [1] 4
+If a shared mount is the only mount in its peer group,
+making it a slave automatically makes it private.
+.IP [2]
+Slaving a nonshared mount has no effect on the mount.
+.\"
+.SS Bind (MS_BIND) semantics
+Suppose that the following command is performed:
+.PP
+.in +4n
+.EX
+mount \-\-bind A/a B/b
+.EE
+.in
+.PP
+Here,
+.I A
+is the source mount,
+.I B
+is the destination mount,
+.I a
+is a subdirectory path under the mount point
+.IR A ,
+and
+.I b
+is a subdirectory path under the mount point
+.IR B .
+The propagation type of the resulting mount,
+.IR B/b ,
+depends on the propagation types of the mounts
+.I A
+and
+.IR B ,
+and is summarized in the following table.
+.PP
+.TS
+lb2 lb1 lb2 lb2 lb2 lb0
+lb2 lb1 lb2 lb2 lb2 lb0
+lb lb | l l l l l.
+			source(A)
+		shared	private	slave	unbind
+_
+dest(B)	shared	shared	shared	slave+shared	invalid
+	nonshared	shared	private	slave	invalid
+.TE
+.sp 1
+Note that a recursive bind of a subtree follows the same semantics
+as for a bind operation on each mount in the subtree.
+(Unbindable mounts are automatically pruned at the target mount point.)
+.PP
+For further details, see
+.I Documentation/filesystems/sharedsubtree.rst
+in the kernel source tree.
+.\"
+.SS Move (MS_MOVE) semantics
+Suppose that the following command is performed:
+.PP
+.in +4n
+.EX
+mount \-\-move A B/b
+.EE
+.in
+.PP
+Here,
+.I A
+is the source mount,
+.I B
+is the destination mount, and
+.I b
+is a subdirectory path under the mount point
+.IR B .
+The propagation type of the resulting mount,
+.IR B/b ,
+depends on the propagation types of the mounts
+.I A
+and
+.IR B ,
+and is summarized in the following table.
+.PP
+.TS
+lb2 lb1 lb2 lb2 lb2 lb0
+lb2 lb1 lb2 lb2 lb2 lb0
+lb lb | l l l l l.
+			source(A)
+		shared	private	slave	unbind
+_
+dest(B)	shared	shared	shared	slave+shared	invalid
+	nonshared	shared	private	slave	unbindable
+.TE
+.sp 1
+Note: moving a mount that resides under a shared mount is invalid.
+.PP
+For further details, see
+.I Documentation/filesystems/sharedsubtree.rst
+in the kernel source tree.
+.\"
+.SS Mount semantics
+Suppose that we use the following command to create a mount:
+.PP
+.in +4n
+.EX
+mount device B/b
+.EE
+.in
+.PP
+Here,
+.I B
+is the destination mount, and
+.I b
+is a subdirectory path under the mount point
+.IR B .
+The propagation type of the resulting mount,
+.IR B/b ,
+follows the same rules as for a bind mount,
+where the propagation type of the source mount
+is considered always to be private.
+.\"
+.SS Unmount semantics
+Suppose that we use the following command to tear down a mount:
+.PP
+.in +4n
+.EX
+umount A
+.EE
+.in
+.PP
+Here,
+.I A
+is a mount on
+.IR B/b ,
+where
+.I B
+is the parent mount and
+.I b
+is a subdirectory path under the mount point
+.IR B .
+If
+.B B
+is shared, then all most-recently-mounted mounts at
+.I b
+on mounts that receive propagation from mount
+.I B
+and do not have submounts under them are unmounted.
+.\"
+.SS The /proc/ pid /mountinfo "propagate_from" tag
+The
+.I propagate_from:X
+tag is shown in the optional fields of a
+.IR /proc/ pid /mountinfo
+record in cases where a process can't see a slave's immediate master
+(i.e., the pathname of the master is not reachable from
+the filesystem root directory)
+and so cannot determine the
+chain of propagation between the mounts it can see.
+.PP
+In the following example, we first create a two-link master-slave chain
+between the mounts
+.IR /mnt ,
+.IR /tmp/etc ,
+and
+.IR /mnt/tmp/etc .
+Then the
+.BR chroot (1)
+command is used to make the
+.I /tmp/etc
+mount point unreachable from the root directory,
+creating a situation where the master of
+.I /mnt/tmp/etc
+is not reachable from the (new) root directory of the process.
+.PP
+First, we bind mount the root directory onto
+.I /mnt
+and then bind mount
+.I /proc
+at
+.I /mnt/proc
+so that after the later
+.BR chroot (1)
+the
+.BR proc (5)
+filesystem remains visible at the correct location
+in the chroot-ed environment.
+.PP
+.in +4n
+.EX
+# \fBmkdir \-p /mnt/proc\fP
+# \fBmount \-\-bind / /mnt\fP
+# \fBmount \-\-bind /proc /mnt/proc\fP
+.EE
+.in
+.PP
+Next, we ensure that the
+.I /mnt
+mount is a shared mount in a new peer group (with no peers):
+.PP
+.in +4n
+.EX
+# \fBmount \-\-make\-private /mnt\fP  # Isolate from any previous peer group
+# \fBmount \-\-make\-shared /mnt\fP
+# \fBcat /proc/self/mountinfo | grep \[aq]/mnt\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+239 61 8:2 / /mnt ... shared:102
+248 239 0:4 / /mnt/proc ... shared:5
+.EE
+.in
+.PP
+Next, we bind mount
+.I /mnt/etc
+onto
+.IR /tmp/etc :
+.PP
+.in +4n
+.EX
+# \fBmkdir \-p /tmp/etc\fP
+# \fBmount \-\-bind /mnt/etc /tmp/etc\fP
+# \fBcat /proc/self/mountinfo | egrep \[aq]/mnt|/tmp/\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+239 61 8:2 / /mnt ... shared:102
+248 239 0:4 / /mnt/proc ... shared:5
+267 40 8:2 /etc /tmp/etc ... shared:102
+.EE
+.in
+.PP
+Initially, these two mounts are in the same peer group,
+but we then make the
+.I /tmp/etc
+a slave of
+.IR /mnt/etc ,
+and then make
+.I /tmp/etc
+shared as well,
+so that it can propagate events to the next slave in the chain:
+.PP
+.in +4n
+.EX
+# \fBmount \-\-make\-slave /tmp/etc\fP
+# \fBmount \-\-make\-shared /tmp/etc\fP
+# \fBcat /proc/self/mountinfo | egrep \[aq]/mnt|/tmp/\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+239 61 8:2 / /mnt ... shared:102
+248 239 0:4 / /mnt/proc ... shared:5
+267 40 8:2 /etc /tmp/etc ... shared:105 master:102
+.EE
+.in
+.PP
+Then we bind mount
+.I /tmp/etc
+onto
+.IR /mnt/tmp/etc .
+Again, the two mounts are initially in the same peer group,
+but we then make
+.I /mnt/tmp/etc
+a slave of
+.IR /tmp/etc :
+.PP
+.in +4n
+.EX
+# \fBmkdir \-p /mnt/tmp/etc\fP
+# \fBmount \-\-bind /tmp/etc /mnt/tmp/etc\fP
+# \fBmount \-\-make\-slave /mnt/tmp/etc\fP
+# \fBcat /proc/self/mountinfo | egrep \[aq]/mnt|/tmp/\[aq] | sed \[aq]s/ \- .*//\[aq]\fP
+239 61 8:2 / /mnt ... shared:102
+248 239 0:4 / /mnt/proc ... shared:5
+267 40 8:2 /etc /tmp/etc ... shared:105 master:102
+273 239 8:2 /etc /mnt/tmp/etc ... master:105
+.EE
+.in
+.PP
+From the above, we see that
+.I /mnt
+is the master of the slave
+.IR /tmp/etc ,
+which in turn is the master of the slave
+.IR /mnt/tmp/etc .
+.PP
+We then
+.BR chroot (1)
+to the
+.I /mnt
+directory, which renders the mount with ID 267 unreachable
+from the (new) root directory:
+.PP
+.in +4n
+.EX
+# \fBchroot /mnt\fP
+.EE
+.in
+.PP
+When we examine the state of the mounts inside the chroot-ed environment,
+we see the following:
+.PP
+.in +4n
+.EX
+# \fBcat /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]\fP
+239 61 8:2 / / ... shared:102
+248 239 0:4 / /proc ... shared:5
+273 239 8:2 /etc /tmp/etc ... master:105 propagate_from:102
+.EE
+.in
+.PP
+Above, we see that the mount with ID 273
+is a slave whose master is the peer group 105.
+The mount point for that master is unreachable, and so a
+.I propagate_from
+tag is displayed, indicating that the closest dominant peer group
+(i.e., the nearest reachable mount in the slave chain)
+is the peer group with the ID 102 (corresponding to the
+.I /mnt
+mount point before the
+.BR chroot (1)
+was performed).
+.\"
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.4.19.
+.\"
+.SH NOTES
+The propagation type assigned to a new mount depends
+on the propagation type of the parent mount.
+If the mount has a parent (i.e., it is a non-root mount
+point) and the propagation type of the parent is
+.BR MS_SHARED ,
+then the propagation type of the new mount is also
+.BR MS_SHARED .
+Otherwise, the propagation type of the new mount is
+.BR MS_PRIVATE .
+.PP
+Notwithstanding the fact that the default propagation type
+for new mount is in many cases
+.BR MS_PRIVATE ,
+.B MS_SHARED
+is typically more useful.
+For this reason,
+.BR systemd (1)
+automatically remounts all mounts as
+.B MS_SHARED
+on system startup.
+Thus, on most modern systems, the default propagation type is in practice
+.BR MS_SHARED .
+.PP
+Since, when one uses
+.BR unshare (1)
+to create a mount namespace,
+the goal is commonly to provide full isolation of the mounts
+in the new namespace,
+.BR unshare (1)
+(since
+.I util\-linux
+2.27) in turn reverses the step performed by
+.BR systemd (1),
+by making all mounts private in the new namespace.
+That is,
+.BR unshare (1)
+performs the equivalent of the following in the new mount namespace:
+.PP
+.in +4n
+.EX
+mount \-\-make\-rprivate /
+.EE
+.in
+.PP
+To prevent this, one can use the
+.I \-\-propagation\~unchanged
+option to
+.BR unshare (1).
+.PP
+An application that creates a new mount namespace directly using
+.BR clone (2)
+or
+.BR unshare (2)
+may desire to prevent propagation of mount events to other mount namespaces
+(as is done by
+.BR unshare (1)).
+This can be done by changing the propagation type of
+mounts in the new namespace to either
+.B MS_SLAVE
+or
+.BR MS_PRIVATE ,
+using a call such as the following:
+.PP
+.in +4n
+.EX
+mount(NULL, "/", MS_SLAVE | MS_REC, NULL);
+.EE
+.in
+.PP
+For a discussion of propagation types when moving mounts
+.RB ( MS_MOVE )
+and creating bind mounts
+.RB ( MS_BIND ),
+see
+.IR Documentation/filesystems/sharedsubtree.rst .
+.\"
+.\" ============================================================
+.\"
+.SS Restrictions on mount namespaces
+Note the following points with respect to mount namespaces:
+.IP [1] 4
+Each mount namespace has an owner user namespace.
+As explained above, when a new mount namespace is created,
+its mount list is initialized as a copy of the mount list
+of another mount namespace.
+If the new namespace and the namespace from which the mount list
+was copied are owned by different user namespaces,
+then the new mount namespace is considered
+.IR "less privileged" .
+.IP [2]
+When creating a less privileged mount namespace,
+shared mounts are reduced to slave mounts.
+This ensures that mappings performed in less
+privileged mount namespaces will not propagate to more privileged
+mount namespaces.
+.IP [3]
+Mounts that come as a single unit from a more privileged mount namespace are
+locked together and may not be separated in a less privileged mount
+namespace.
+(The
+.BR unshare (2)
+.B CLONE_NEWNS
+operation brings across all of the mounts from the original
+mount namespace as a single unit,
+and recursive mounts that propagate between
+mount namespaces propagate as a single unit.)
+.IP
+In this context, "may not be separated" means that the mounts
+are locked so that they may not be individually unmounted.
+Consider the following example:
+.IP
+.in +4n
+.EX
+$ \fBsudo sh\fP
+# \fBmount \-\-bind /dev/null /etc/shadow\fP
+# \fBcat /etc/shadow\fP       # Produces no output
+.EE
+.in
+.IP
+The above steps, performed in a more privileged mount namespace,
+have created a bind mount that
+obscures the contents of the shadow password file,
+.IR /etc/shadow .
+For security reasons, it should not be possible to
+.BR umount (2)
+that mount in a less privileged mount namespace,
+since that would reveal the contents of
+.IR /etc/shadow .
+.IP
+Suppose we now create a new mount namespace
+owned by a new user namespace.
+The new mount namespace will inherit copies of all of the mounts
+from the previous mount namespace.
+However, those mounts will be locked because the new mount namespace
+is less privileged.
+Consequently, an attempt to
+.BR umount (2)
+the mount fails as show
+in the following step:
+.IP
+.in +4n
+.EX
+# \fBunshare \-\-user \-\-map\-root\-user \-\-mount \e\fP
+               \fBstrace \-o /tmp/log \e\fP
+               \fBumount /mnt/dir\fP
+umount: /etc/shadow: not mounted.
+# \fBgrep \[aq]\[ha]umount\[aq] /tmp/log\fP
+umount2("/etc/shadow", 0)     = \-1 EINVAL (Invalid argument)
+.EE
+.in
+.IP
+The error message from
+.BR mount (8)
+is a little confusing, but the
+.BR strace (1)
+output reveals that the underlying
+.BR umount2 (2)
+system call failed with the error
+.BR EINVAL ,
+which is the error that the kernel returns to indicate that
+the mount is locked.
+.IP
+Note, however, that it is possible to stack (and unstack) a
+mount on top of one of the inherited locked mounts in a
+less privileged mount namespace:
+.IP
+.in +4n
+.EX
+# \fBecho \[aq]aaaaa\[aq] > /tmp/a\fP    # File to mount onto /etc/shadow
+# \fBunshare \-\-user \-\-map\-root\-user \-\-mount \e\fP
+    \fBsh \-c \[aq]mount \-\-bind /tmp/a /etc/shadow; cat /etc/shadow\[aq]\fP
+aaaaa
+# \fBumount /etc/shadow\fP
+.EE
+.in
+.IP
+The final
+.BR umount (8)
+command above, which is performed in the initial mount namespace,
+makes the original
+.I /etc/shadow
+file once more visible in that namespace.
+.IP [4]
+Following on from point [3],
+note that it is possible to
+.BR umount (2)
+an entire subtree of mounts that
+propagated as a unit into a less privileged mount namespace,
+as illustrated in the following example.
+.IP
+First, we create new user and mount namespaces using
+.BR unshare (1).
+In the new mount namespace,
+the propagation type of all mounts is set to private.
+We then create a shared bind mount at
+.IR /mnt ,
+and a small hierarchy of mounts underneath that mount.
+.IP
+.in +4n
+.EX
+$ \fBPS1=\[aq]ns1# \[aq] sudo unshare \-\-user \-\-map\-root\-user \e\fP
+                       \fB\-\-mount \-\-propagation private bash\fP
+ns1# \fBecho $$\fP        # We need the PID of this shell later
+778501
+ns1# \fBmount \-\-make\-shared \-\-bind /mnt /mnt\fP
+ns1# \fBmkdir /mnt/x\fP
+ns1# \fBmount \-\-make\-private \-t tmpfs none /mnt/x\fP
+ns1# \fBmkdir /mnt/x/y\fP
+ns1# \fBmount \-\-make\-private \-t tmpfs none /mnt/x/y\fP
+ns1# \fBgrep /mnt /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]\fP
+986 83 8:5 /mnt /mnt rw,relatime shared:344
+989 986 0:56 / /mnt/x rw,relatime
+990 989 0:57 / /mnt/x/y rw,relatime
+.EE
+.in
+.IP
+Continuing in the same shell session,
+we then create a second shell in a new user namespace and a new
+(less privileged) mount namespace and
+check the state of the propagated mounts rooted at
+.IR /mnt .
+.IP
+.in +4n
+.EX
+ns1# \fBPS1=\[aq]ns2# \[aq] unshare \-\-user \-\-map\-root\-user \e\fP
+                       \fB\-\-mount \-\-propagation unchanged bash\fP
+ns2# \fBgrep /mnt /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]\fP
+1239 1204 8:5 /mnt /mnt rw,relatime master:344
+1240 1239 0:56 / /mnt/x rw,relatime
+1241 1240 0:57 / /mnt/x/y rw,relatime
+.EE
+.in
+.IP
+Of note in the above output is that the propagation type of the mount
+.I /mnt
+has been reduced to slave, as explained in point [2].
+This means that submount events will propagate from the master
+.I /mnt
+in "ns1", but propagation will not occur in the opposite direction.
+.IP
+From a separate terminal window, we then use
+.BR nsenter (1)
+to enter the mount and user namespaces corresponding to "ns1".
+In that terminal window, we then recursively bind mount
+.I /mnt/x
+at the location
+.IR /mnt/ppp .
+.IP
+.in +4n
+.EX
+$ \fBPS1=\[aq]ns3# \[aq] sudo nsenter \-t 778501 \-\-user \-\-mount\fP
+ns3# \fBmount \-\-rbind \-\-make\-private /mnt/x /mnt/ppp\fP
+ns3# \fBgrep /mnt /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]\fP
+986 83 8:5 /mnt /mnt rw,relatime shared:344
+989 986 0:56 / /mnt/x rw,relatime
+990 989 0:57 / /mnt/x/y rw,relatime
+1242 986 0:56 / /mnt/ppp rw,relatime
+1243 1242 0:57 / /mnt/ppp/y rw,relatime shared:518
+.EE
+.in
+.IP
+Because the propagation type of the parent mount,
+.IR /mnt ,
+was shared, the recursive bind mount propagated a small subtree of
+mounts under the slave mount
+.I /mnt
+into "ns2",
+as can be verified by executing the following command in that shell session:
+.IP
+.in +4n
+.EX
+ns2# \fBgrep /mnt /proc/self/mountinfo | sed \[aq]s/ \- .*//\[aq]\fP
+1239 1204 8:5 /mnt /mnt rw,relatime master:344
+1240 1239 0:56 / /mnt/x rw,relatime
+1241 1240 0:57 / /mnt/x/y rw,relatime
+1244 1239 0:56 / /mnt/ppp rw,relatime
+1245 1244 0:57 / /mnt/ppp/y rw,relatime master:518
+.EE
+.in
+.IP
+While it is not possible to
+.BR umount (2)
+a part of the propagated subtree
+.RI ( /mnt/ppp/y )
+in "ns2",
+it is possible to
+.BR umount (2)
+the entire subtree,
+as shown by the following commands:
+.IP
+.in +4n
+.EX
+ns2# \fBumount /mnt/ppp/y\fP
+umount: /mnt/ppp/y: not mounted.
+ns2# \fBumount \-l /mnt/ppp | sed \[aq]s/ \- .*//\[aq]\fP      # Succeeds...
+ns2# \fBgrep /mnt /proc/self/mountinfo\fP
+1239 1204 8:5 /mnt /mnt rw,relatime master:344
+1240 1239 0:56 / /mnt/x rw,relatime
+1241 1240 0:57 / /mnt/x/y rw,relatime
+.EE
+.in
+.IP [5]
+The
+.BR mount (2)
+flags
+.BR MS_RDONLY ,
+.BR MS_NOSUID ,
+.BR MS_NOEXEC ,
+and the "atime" flags
+.RB ( MS_NOATIME ,
+.BR MS_NODIRATIME ,
+.BR MS_RELATIME )
+settings become locked
+.\" commit 9566d6742852c527bf5af38af5cbb878dad75705
+.\" Author: Eric W. Biederman <ebiederm@xmission.com>
+.\" Date:   Mon Jul 28 17:26:07 2014 -0700
+.\"
+.\"      mnt: Correct permission checks in do_remount
+.\"
+when propagated from a more privileged to
+a less privileged mount namespace,
+and may not be changed in the less privileged mount namespace.
+.IP
+This point is illustrated in the following example where,
+in a more privileged mount namespace,
+we create a bind mount that is marked as read-only.
+For security reasons,
+it should not be possible to make the mount writable in
+a less privileged mount namespace, and indeed the kernel prevents this:
+.IP
+.in +4n
+.EX
+$ \fBsudo mkdir /mnt/dir\fP
+$ \fBsudo mount \-\-bind \-o ro /some/path /mnt/dir\fP
+$ \fBsudo unshare \-\-user \-\-map\-root\-user \-\-mount \e\fP
+               \fBmount \-o remount,rw /mnt/dir\fP
+mount: /mnt/dir: permission denied.
+.EE
+.in
+.IP [6]
+.\" (As of 3.18-rc1 (in Al Viro's 2014-08-30 vfs.git#for-next tree))
+A file or directory that is a mount point in one namespace that is not
+a mount point in another namespace, may be renamed, unlinked, or removed
+.RB ( rmdir (2))
+in the mount namespace in which it is not a mount point
+(subject to the usual permission checks).
+Consequently, the mount point is removed in the mount namespace
+where it was a mount point.
+.IP
+Previously (before Linux 3.18),
+.\" mtk: The change was in Linux 3.18, I think, with this commit:
+.\"     commit 8ed936b5671bfb33d89bc60bdcc7cf0470ba52fe
+.\"     Author: Eric W. Biederman <ebiederman@twitter.com>
+.\"     Date:   Tue Oct 1 18:33:48 2013 -0700
+.\"
+.\"         vfs: Lazily remove mounts on unlinked files and directories.
+attempting to unlink, rename, or remove a file or directory
+that was a mount point in another mount namespace would result in the error
+.BR EBUSY .
+That behavior had technical problems of enforcement (e.g., for NFS)
+and permitted denial-of-service attacks against more privileged users
+(i.e., preventing individual files from being updated
+by bind mounting on top of them).
+.SH EXAMPLES
+See
+.BR pivot_root (2).
+.SH SEE ALSO
+.BR unshare (1),
+.BR clone (2),
+.BR mount (2),
+.BR mount_setattr (2),
+.BR pivot_root (2),
+.BR setns (2),
+.BR umount (2),
+.BR unshare (2),
+.BR proc (5),
+.BR namespaces (7),
+.BR user_namespaces (7),
+.BR findmnt (8),
+.BR mount (8),
+.BR pam_namespace (8),
+.BR pivot_root (8),
+.BR umount (8)
+.PP
+.I Documentation/filesystems/sharedsubtree.rst
+in the kernel source tree.