* [PATCH v2 1/2] mount.2: document MS_REC and shared subtree flags
@ 2016-05-18 18:57 Omar Sandoval
2016-05-18 18:57 ` [PATCH v2 2/2] mount.2: MS_BIND still ignores mountflags Omar Sandoval
2016-05-19 11:22 ` [PATCH v2 1/2] mount.2: document MS_REC and shared subtree flags Michael Kerrisk (man-pages)
0 siblings, 2 replies; 6+ messages in thread
From: Omar Sandoval @ 2016-05-18 18:57 UTC (permalink / raw)
To: Michael Kerrisk; +Cc: linux-man, linux-fsdevel, 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 | 133 +++++++++++++++++++++++++++++++++++++++--------------------
1 file changed, 88 insertions(+), 45 deletions(-)
diff --git a/man2/mount.2 b/man2/mount.2
index aa6558a87cd9..419e22da800f 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,34 @@ 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.
+This flag can only be combined with
+.B MS_REC
+and
+.BR MS_SILENT .
+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 +290,21 @@ 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).
+This flag can only be combined with
+.B MS_REC
+and
+.BR MS_SILENT .
+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 +313,28 @@ 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 ).
+This flag can only be combined with
+.B MS_REC
+and
+.BR MS_SILENT .
+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 +352,21 @@ 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.
+This flag can only be combined with
+.B MS_REC
+and
+.BR MS_SILENT .
+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 +444,11 @@ 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 combined with a flag other than
+.B MS_REC
+or
+.BR MS_SILENT .
.TP
.B ELOOP
Too many links encountered during pathname resolution.
@@ -457,11 +498,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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH v2 2/2] mount.2: MS_BIND still ignores mountflags
2016-05-18 18:57 [PATCH v2 1/2] mount.2: document MS_REC and shared subtree flags Omar Sandoval
@ 2016-05-18 18:57 ` Omar Sandoval
2016-05-21 16:29 ` Michael Kerrisk (man-pages)
2016-05-19 11:22 ` [PATCH v2 1/2] mount.2: document MS_REC and shared subtree flags Michael Kerrisk (man-pages)
1 sibling, 1 reply; 6+ messages in thread
From: Omar Sandoval @ 2016-05-18 18:57 UTC (permalink / raw)
To: Michael Kerrisk; +Cc: linux-man, linux-fsdevel, Omar Sandoval
From: Omar Sandoval <osandov@fb.com>
This is clear from the do_mount() function in the kernel as of v4.6.
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 419e22da800f..bd4c35bd15ff 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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH v2 1/2] mount.2: document MS_REC and shared subtree flags
2016-05-18 18:57 [PATCH v2 1/2] mount.2: document MS_REC and shared subtree flags Omar Sandoval
2016-05-18 18:57 ` [PATCH v2 2/2] mount.2: MS_BIND still ignores mountflags Omar Sandoval
@ 2016-05-19 11:22 ` Michael Kerrisk (man-pages)
2016-06-07 18:15 ` Omar Sandoval
1 sibling, 1 reply; 6+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-05-19 11:22 UTC (permalink / raw)
To: Omar Sandoval; +Cc: mtk.manpages, linux-man, linux-fsdevel, Omar Sandoval
Hello Omar,
Thanks for tackling this. Some comments below.
On 05/18/2016 08:57 PM, Omar Sandoval wrote:
> 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 | 133 +++++++++++++++++++++++++++++++++++++++--------------------
> 1 file changed, 88 insertions(+), 45 deletions(-)
>
> diff --git a/man2/mount.2 b/man2/mount.2
> index aa6558a87cd9..419e22da800f 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,34 @@ 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
s/mountpoint/mount point/ (all occurrences)
Change "this mountpoint" to
the
.I target
mount point
(and other instances below).
> +propagate to or from replicated subtrees.
What is a "replicated subtree"? This isn't explained in the text (and, doesn't
feel quite right as a term, but perhaps that is just because you do not explain
what you mean).
> +This flag can only be combined with
s/can only be combined with/ can be combined with only/
(all occurrences)
> +.B MS_REC
> +and
> +.BR MS_SILENT .
> +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.
Change "source subtree" to
.I 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.
Change "target subtree" to
.I target
subtree.
> .TP
> .BR MS_RELATIME " (since Linux 2.6.20)"
> When a file on this filesystem is accessed,
> @@ -306,6 +290,21 @@ 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
s/Mount/Mount and unmount events/
> +(i.e., all replicas will continue to be the same).
> +This flag can only be combined with
> +.B MS_REC
> +and
> +.BR MS_SILENT .
> +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 +313,28 @@ 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
s/Mounts made/Mount and unmount events/
> +subtree, but mounts made underneath this subtree will not be propagated
s/mounts made/events/
> +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 ).
> +This flag can only be combined with
> +.B MS_REC
> +and
> +.BR MS_SILENT .
> +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 +352,21 @@ 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.
> +This flag can only be combined with
> +.B MS_REC
> +and
> +.BR MS_SILENT .
> +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 +444,11 @@ 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 combined with a flag other than
> +.B MS_REC
> +or
> +.BR MS_SILENT .
> .TP
> .B ELOOP
> Too many links encountered during pathname resolution.
> @@ -457,11 +498,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.
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH v2 2/2] mount.2: MS_BIND still ignores mountflags
2016-05-18 18:57 ` [PATCH v2 2/2] mount.2: MS_BIND still ignores mountflags Omar Sandoval
@ 2016-05-21 16:29 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 6+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-05-21 16:29 UTC (permalink / raw)
To: Omar Sandoval; +Cc: mtk.manpages, linux-man, linux-fsdevel, Omar Sandoval
On 05/18/2016 01:57 PM, Omar Sandoval wrote:
> From: Omar Sandoval <osandov@fb.com>
>
> This is clear from the do_mount() function in the kernel as of v4.6.
>
Hello Omar
I've applied this patch, and await your input on the other patch.
Cheers,
Michael
> 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 419e22da800f..bd4c35bd15ff 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
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH v2 1/2] mount.2: document MS_REC and shared subtree flags
2016-05-19 11:22 ` [PATCH v2 1/2] mount.2: document MS_REC and shared subtree flags Michael Kerrisk (man-pages)
@ 2016-06-07 18:15 ` Omar Sandoval
2016-06-07 22:40 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 6+ messages in thread
From: Omar Sandoval @ 2016-06-07 18:15 UTC (permalink / raw)
To: Michael Kerrisk (man-pages); +Cc: linux-man, linux-fsdevel, Omar Sandoval
On Thu, May 19, 2016 at 01:22:26PM +0200, Michael Kerrisk (man-pages) wrote:
> Hello Omar,
>
> Thanks for tackling this. Some comments below.
>
Hi, Michael, I see you've revamped the mount(2) man page and documented
these flags. Thanks, it looks great!
--
Omar
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH v2 1/2] mount.2: document MS_REC and shared subtree flags
2016-06-07 18:15 ` Omar Sandoval
@ 2016-06-07 22:40 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 6+ messages in thread
From: Michael Kerrisk (man-pages) @ 2016-06-07 22:40 UTC (permalink / raw)
To: Omar Sandoval; +Cc: mtk.manpages, linux-man, linux-fsdevel, Omar Sandoval
On 06/07/2016 08:15 PM, Omar Sandoval wrote:
> On Thu, May 19, 2016 at 01:22:26PM +0200, Michael Kerrisk (man-pages) wrote:
>> Hello Omar,
>>
>> Thanks for tackling this. Some comments below.
>>
>
> Hi, Michael, I see you've revamped the mount(2) man page and documented
> these flags. Thanks, it looks great!
You're welcome. That page has long needed some attention, so I did
some work. Thanks for your input, which in part motivated that work.
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2016-06-07 22:40 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-05-18 18:57 [PATCH v2 1/2] mount.2: document MS_REC and shared subtree flags Omar Sandoval
2016-05-18 18:57 ` [PATCH v2 2/2] mount.2: MS_BIND still ignores mountflags Omar Sandoval
2016-05-21 16:29 ` Michael Kerrisk (man-pages)
2016-05-19 11:22 ` [PATCH v2 1/2] mount.2: document MS_REC and shared subtree flags Michael Kerrisk (man-pages)
2016-06-07 18:15 ` Omar Sandoval
2016-06-07 22:40 ` Michael Kerrisk (man-pages)
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).