.. SPDX-License-Identifier: GPL-2.0

===============
Shared Subtrees
===============

.. Contents:
	1) Overview
	2) Features
	3) Setting mount states
	4) Use-case
	5) Detailed semantics
	6) Quiz
	7) FAQ
	8) Implementation


1) Overview
-----------

Consider the following situation:

A process wants to clone its own namespace, but still wants to access the CD
that got mounted recently.  Shared subtree semantics provide the necessary
mechanism to accomplish the above.

It provides the necessary building blocks for features like per-user-namespace
and versioned filesystem.

2) Features
-----------

Shared subtree provides four different flavors of mounts; struct vfsmount to be
precise

	a. shared mount
	b. slave mount
	c. private mount
	d. unbindable mount


2a) A shared mount can be replicated to as many mountpoints and all the
replicas continue to be exactly same.

	Here is an example:

	Let's say /mnt has a mount that is shared::

	    mount --make-shared /mnt

	Note: mount(8) command now supports the --make-shared flag,
	so the sample 'smount' program is no longer needed and has been
	removed.

	::

	    # mount --bind /mnt /tmp

	The above command replicates the mount at /mnt to the mountpoint /tmp
	and the contents of both the mounts remain identical.

	::

	    #ls /mnt
	    a b c

	    #ls /tmp
	    a b c

	Now let's say we mount a device at /tmp/a::

	    # mount /dev/sd0  /tmp/a

	    #ls /tmp/a
	    t1 t2 t3

	    #ls /mnt/a
	    t1 t2 t3

	Note that the mount has propagated to the mount at /mnt as well.

	And the same is true even when /dev/sd0 is mounted on /mnt/a. The
	contents will be visible under /tmp/a too.


2b) A slave mount is like a shared mount except that mount and umount events
	only propagate towards it.

	All slave mounts have a master mount which is a shared.

	Here is an example:

	Let's say /mnt has a mount which is shared.
	# mount --make-shared /mnt

	Let's bind mount /mnt to /tmp
	# mount --bind /mnt /tmp

	the new mount at /tmp becomes a shared mount and it is a replica of
	the mount at /mnt.

	Now let's make the mount at /tmp; a slave of /mnt
	# mount --make-slave /tmp

	let's mount /dev/sd0 on /mnt/a
	# mount /dev/sd0 /mnt/a

	#ls /mnt/a
	t1 t2 t3

	#ls /tmp/a
	t1 t2 t3

	Note the mount event has propagated to the mount at /tmp

	However let's see what happens if we mount something on the mount at /tmp

	# mount /dev/sd1 /tmp/b

	#ls /tmp/b
	s1 s2 s3

	#ls /mnt/b

	Note how the mount event has not propagated to the mount at
	/mnt


2c) A private mount does not forward or receive propagation.

	This is the mount we are familiar with. Its the default type.


2d) A unbindable mount is a unbindable private mount

	let's say we have a mount at /mnt and we make it unbindable::

	    # mount --make-unbindable /mnt

	 Let's try to bind mount this mount somewhere else::

	    # mount --bind /mnt /tmp
	    mount: wrong fs type, bad option, bad superblock on /mnt,
		    or too many mounted file systems

	Binding a unbindable mount is a invalid operation.


3) Setting mount states
-----------------------

	The mount command (util-linux package) can be used to set mount
	states::

	    mount --make-shared mountpoint
	    mount --make-slave mountpoint
	    mount --make-private mountpoint
	    mount --make-unbindable mountpoint


4) Use cases
------------

	A) A process wants to clone its own namespace, but still wants to
	   access the CD that got mounted recently.

	   Solution:

		The system administrator can make the mount at /cdrom shared::

		    mount --bind /cdrom /cdrom
		    mount --make-shared /cdrom

		Now any process that clones off a new namespace will have a
		mount at /cdrom which is a replica of the same mount in the
		parent namespace.

		So when a CD is inserted and mounted at /cdrom that mount gets
		propagated to the other mount at /cdrom in all the other clone
		namespaces.

	B) A process wants its mounts invisible to any other process, but
	still be able to see the other system mounts.

	   Solution:

		To begin with, the administrator can mark the entire mount tree
		as shareable::

		    mount --make-rshared /

		A new process can clone off a new namespace. And mark some part
		of its namespace as slave::

		    mount --make-rslave /myprivatetree

		Hence forth any mounts within the /myprivatetree done by the
		process will not show up in any other namespace. However mounts
		done in the parent namespace under /myprivatetree still shows
		up in the process's namespace.


	Apart from the above semantics this feature provides the
	building blocks to solve the following problems:

	C)  Per-user namespace

		The above semantics allows a way to share mounts across
		namespaces.  But namespaces are associated with processes. If
		namespaces are made first class objects with user API to
		associate/disassociate a namespace with userid, then each user
		could have his/her own namespace and tailor it to his/her
		requirements. This needs to be supported in PAM.

	D)  Versioned files

		If the entire mount tree is visible at multiple locations, then
		an underlying versioning file system can return different
		versions of the file depending on the path used to access that
		file.

		An example is::

		    mount --make-shared /
		    mount --rbind / /view/v1
		    mount --rbind / /view/v2
		    mount --rbind / /view/v3
		    mount --rbind / /view/v4

		and if /usr has a versioning filesystem mounted, then that
		mount appears at /view/v1/usr, /view/v2/usr, /view/v3/usr and
		/view/v4/usr too

		A user can request v3 version of the file /usr/fs/namespace.c
		by accessing /view/v3/usr/fs/namespace.c . The underlying
		versioning filesystem can then decipher that v3 version of the
		filesystem is being requested and return the corresponding
		inode.

5) Detailed semantics
---------------------
	The section below explains the detailed semantics of
	bind, rbind, move, mount, umount and clone-namespace operations.

	Note: the word 'vfsmount' and the noun 'mount' have been used
	to mean the same thing, throughout this document.

5a) Mount states

	A given mount can be in one of the following states

	1) shared
	2) slave
	3) shared and slave
	4) private
	5) unbindable

	A 'propagation event' is defined as event generated on a vfsmount
	that leads to mount or unmount actions in other vfsmounts.

	A 'peer group' is defined as a group of vfsmounts that propagate
	events to each other.

	(1) Shared mounts

		A 'shared mount' is defined as a vfsmount that belongs to a
		'peer group'.

		For example::

			mount --make-shared /mnt
			mount --bind /mnt /tmp

		The mount at /mnt and that at /tmp are both shared and belong
		to the same peer group. Anything mounted or unmounted under
		/mnt or /tmp reflect in all the other mounts of its peer
		group.


	(2) Slave mounts

		A 'slave mount' is defined as a vfsmount that receives
		propagation events and does not forward propagation events.

		A slave mount as the name implies has a master mount from which
		mount/unmount events are received. Events do not propagate from
		the slave mount to the master.  Only a shared mount can be made
		a slave by executing the following command::

			mount --make-slave mount

		A shared mount that is made as a slave is no more shared unless
		modified to become shared.

	(3) Shared and Slave

		A vfsmount can be both shared as well as slave.  This state
		indicates that the mount is a slave of some vfsmount, and
		has its own peer group too.  This vfsmount receives propagation
		events from its master vfsmount, and also forwards propagation
		events to its 'peer group' and to its slave vfsmounts.

		Strictly speaking, the vfsmount is shared having its own
		peer group, and this peer-group is a slave of some other
		peer group.

		Only a slave vfsmount can be made as 'shared and slave' by
		either executing the following command::

			mount --make-shared mount

		or by moving the slave vfsmount under a shared vfsmount.

	(4) Private mount

		A 'private mount' is defined as vfsmount that does not
		receive or forward any propagation events.

	(5) Unbindable mount

		A 'unbindable mount' is defined as vfsmount that does not
		receive or forwar                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               