[PATCH 1/2] mount.2: document MS_REC and shared subtree flags

[PATCH 1/2] mount.2: document MS_REC and shared subtree flags

[Omar Sandoval]

From: Omar Sandoval <osandov@fb.com>

This stuff is all documented in the kernel source tree under
Documentation/filesystems/sharedsubtree.txt, so let's document it
properly for users.

Signed-off-by: Omar Sandoval <osandov@fb.com>
---
 man2/mount.2 | 122 +++++++++++++++++++++++++++++++++++++----------------------
 1 file changed, 77 insertions(+), 45 deletions(-)

diff --git a/man2/mount.2 b/man2/mount.2
index aa6558a87cd9..cc624d3fe1c6 100644
--- a/man2/mount.2
+++ b/man2/mount.2
@@ -83,44 +83,6 @@ and various mount flags
 .\" (as defined in \fI<linux/fs.h>\fP for libc4 and libc5
 .\" and in \fI<sys/mount.h>\fP for glibc2)
 in the low order 16 bits:
-.\" FIXME 2.6.15 added flags for "shared subtree" functionality:
-.\"
-.\"	MS_PRIVATE
-.\"		All mounts are private by default. Previously shared mounts
-.\"		can be re-marked PRIVATE.
-.\"	MS_SHARED
-.\"		Mount points that are marked SHARED propagate mount events
-.\"		to one another after being cloned.
-.\"			mount --make-rshared ==> MS_SHARED | MS_REC
-.\"	MS_SLAVE
-.\"		A previously shared mount point can be marked SLAVE, meaning
-.\"		it receives propagated events, but does not propagate events.
-.\"	MS_UNBINDABLE
-.\"		mounts cannot be bound into other places, and will not be
-.\"		propagated into new subtrees	
-.\"
-.\" These settings are visible in /proc/$$/mountinfo
-.\"
-.\" These need to be documented on this page.
-.\" See:
-.\"
-.\" * Documentation/filesystems/sharedsubtree.txt
-.\"
-.\" * http://lwn.net/Articles/159077/
-.\"
-.\" * https://www.kernel.org/doc/ols/2006/ols2006v2-pages-209-222.pdf
-.\"       Shared-Subtree Concept, Implementation, and Applications in Linux
-.\"       Al Viro viro@ftp.linux.org.uk
-.\"       Ram Pai linuxram@us.ibm.com
-.\"
-.\" * http://www.ibm.com/developerworks/linux/library/l-mount-namespaces/index.html
-.\"       Applying mount namespaces
-.\"
-.\"       Uncover practical applications for advanced Linux mounts features
-.\"       Serge E. Hallyn (sergeh@us.ibm.com), Software Engineer, IBM
-.\"       Ram Pai (linuxram@us.ibm.com), Software Engineer, IBM
-.\"       Date:  17 Sep 2007
-.\"
 .\" FIXME 2.6.25 Added MS_I_VERSION, which needs to be documented.
 .\"
 .TP
@@ -240,12 +202,32 @@ programs from this filesystem.
 .\" (This is a security feature to prevent users executing set-user-ID and
 .\" set-group-ID programs from removable disk devices.)
 .TP
+.BR MS_PRIVATE " (since Linux 2.6.15)"
+Set the mount propagation on this mountpoint to private. Mounts will not
+propagate to or from replicated subtrees.
+When used, this must be the only flag in
+.IR mountflags .
+The
+.IR source ,
+.IR filesystemtype ,
+and
+.IR data
+arguments are ignored.
+.TP
 .B MS_RDONLY
 Mount filesystem read-only.
-.\"
-.\" FIXME Document MS_REC, available since 2.4.11.
-.\" This flag has meaning in conjunction with MS_BIND and
-.\" also with the shared subtree flags.
+.TP
+.BR MS_REC " (since Linux 2.4.11)"
+When passed together with
+.BR MS_BIND ,
+recursively bind mount all mountpoints underneath the source subtree.
+When passed together with a shared subtree flag (one of
+.BR MS_PRIVATE ,
+.BR MS_SHARED ,
+.BR MS_SLAVE ", or"
+.BR MS_UNBINDABLE ),
+recursively apply the shared subtree setting to all mountpoints
+underneath the target subtree.
 .TP
 .BR MS_RELATIME " (since Linux 2.6.20)"
 When a file on this filesystem is accessed,
@@ -306,6 +288,19 @@ and, additionally, before kernel 2.4.10, the following could also be changed:
 .BR MS_NODEV ,
 .BR MS_NOEXEC .
 .TP
+.BR MS_SHARED " (since Linux 2.6.15)"
+Set the mount propagation on this mountpoint to shared.
+Mounts will be propagated to and from replicated subtrees
+(i.e., all replicas will continue to be the same).
+When used, this must be the only flag in
+.IR mountflags .
+The
+.IR source ,
+.IR filesystemtype ,
+and
+.IR data
+arguments are ignored.
+.TP
 .BR MS_SILENT " (since Linux 2.6.17)"
 Suppress the display of certain
 .RI ( printk ())
@@ -314,6 +309,26 @@ This flag supersedes the misnamed and obsolete
 .BR MS_VERBOSE
 flag (available since Linux 2.4.12), which has the same meaning.
 .TP
+.BR MS_SLAVE " (since Linux 2.6.15)"
+Make this mountpoint a slave of its source mountpoint, referred to as
+its master.
+Mounts made underneath the master subtree will be propagated to this
+subtree, but mounts made underneath this subtree will not be propagated
+back to the master.
+Note that a slave mountpoint can still have either private propagation
+(see
+.BR MS_PRIVATE )
+or shared propagation (see
+.BR MS_SHARED ).
+When used, this must be the only flag in
+.IR mountflags .
+The
+.IR source ,
+.IR filesystemtype ,
+and
+.IR data
+arguments are ignored.
+.TP
 .BR MS_STRICTATIME " (since Linux 2.6.30)"
 Always update the last access time (atime) when files on this
 filesystem are accessed.
@@ -331,6 +346,19 @@ the
 flag to
 .BR open (2)
 was specified for all file opens to this filesystem).
+.TP
+.BR MS_UNBINDABLE " (since Linux 2.6.15)"
+Set the mount propagation on this mountpoint to private (see
+.BR MS_PRIVATE )
+and disallow bind mounts with this mountpoint as the source.
+When used, this must be the only flag in
+.IR mountflags .
+The
+.IR source ,
+.IR filesystemtype ,
+and
+.IR data
+arguments are ignored.
 .PP
 From Linux 2.4 onward, the
 .BR MS_NODEV ", " MS_NOEXEC ", and " MS_NOSUID
@@ -408,6 +436,8 @@ Or, a move
 was attempted, but
 .I source
 was not a mount point, or was \(aq/\(aq.
+Or, more than one shared subtree flag was given.
+Or, a shared subtree flag was given and additional flags were also used.
 .TP
 .B ELOOP
 Too many links encountered during pathname resolution.
@@ -457,11 +487,13 @@ The definitions of
 .BR MS_MOVE ,
 .BR MS_REC ,
 .BR MS_RELATIME ,
+.BR MS_STRICTATIME ,
+.BR MS_PRIVATE ,
+.BR MS_SHARED ,
+.BR MS_SLAVE ,
 and
-.BR MS_STRICTATIME
+.BR MS_UNBINDABLE
 were added to glibc headers in version 2.12.
-.\" FIXME . Definitions of the so-far-undocumented MS_UNBINDABLE, MS_PRIVATE,
-.\" MS_SHARED, and MS_SLAVE were (also) only added to glibc headers in 2.12.
 .SH CONFORMING TO
 This function is Linux-specific and should not be used in
 programs intended to be portable.
-- 
2.8.2

[PATCH 2/2] mount.2: MS_BIND still ignores mountflags

[Omar Sandoval]

From: Omar Sandoval <osandov@fb.com>

This is clear from the do_mount() function in the kernel as of v4.6-rc7.

Signed-off-by: Omar Sandoval <osandov@fb.com>
---
 man2/mount.2 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/man2/mount.2 b/man2/mount.2
index cc624d3fe1c6..162bbddeba21 100644
--- a/man2/mount.2
+++ b/man2/mount.2
@@ -98,10 +98,10 @@ The
 and
 .IR data
 arguments are ignored.
-Up until Linux 2.6.26,
+The
 .I mountflags
-was also ignored
-.\" with the exception of the "hidden" MS_REC mountflags bit
+argument is also ignored, with the exception of
+.B MS_REC
 (the bind mount has the same mount options as
 the underlying mount point).
 .TP
-- 
2.8.2

Re: [PATCH 1/2] mount.2: document MS_REC and shared subtree flags

[Florian Weimer]

On 05/12/2016 09:17 AM, Omar Sandoval wrote:
> +.BR MS_PRIVATE " (since Linux 2.6.15)"
> +Set the mount propagation on this mountpoint to private. Mounts will not
> +propagate to or from replicated subtrees.
> +When used, this must be the only flag in
> +.IR mountflags .

Is the last sentence actually true?  Further down, your patch mentions 
combining MS_PRIVATE with other flags.

Thanks,
Florian

Re: [PATCH 1/2] mount.2: document MS_REC and shared subtree flags

[Omar Sandoval]

On Thu, May 12, 2016 at 10:36:00AM +0200, Florian Weimer wrote:
> On 05/12/2016 09:17 AM, Omar Sandoval wrote:
> > +.BR MS_PRIVATE " (since Linux 2.6.15)"
> > +Set the mount propagation on this mountpoint to private. Mounts will not
> > +propagate to or from replicated subtrees.
> > +When used, this must be the only flag in
> > +.IR mountflags .
> 
> Is the last sentence actually true?  Further down, your patch mentions
> combining MS_PRIVATE with other flags.
> 
> Thanks,
> Florian

Yeah, you're right, I documented that it can be combined with MS_REC,
and looking closer, it can also be combined with MS_SILENT. Even more
confusing is that there's a bunch of flags that we'll end up ignoring:

	flags &= ~(MS_NOSUID | MS_NOEXEC | MS_NODEV | MS_ACTIVE | MS_BORN |
		   MS_NOATIME | MS_NODIRATIME | MS_RELATIME| MS_KERNMOUNT |
		   MS_STRICTATIME);

So any of those flags are ignored, MS_REC and MS_SILENT are valid, and
anything else is an error. I'll try to come up with an explanation that
makes sense, but it's a bit of a mess.

-- 
Omar