mount_setattr.2: Minor wording, grammar, and formatting fixes

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2021-08-09 06:48:14 +02:00
parent 3643106e2c
commit 133e6b161c
1 changed files with 117 additions and 117 deletions

View File

@ -47,7 +47,7 @@ necessitating the use of
.SH DESCRIPTION
The
.BR mount_setattr ()
system call changes the mount properties of a mount or entire mount tree.
system call changes the mount properties of a mount or an entire mount tree.
If
.I path
is a relative pathname,
@ -57,7 +57,7 @@ the directory referred to by the file descriptor
If
.I dfd
is the special value
.B AT_FDCWD
.BR AT_FDCWD ,
then
.I path
is interpreted relative to
@ -79,14 +79,14 @@ system call uses an extensible structure
to allow for future extensions.
Any non-flag extensions to
.BR mount_setattr ()
will be implemented as new fields appended to the above structure,
will be implemented as new fields appended to the this structure,
with a zero value in a new field resulting in the kernel behaving
as though that extension field was not present.
Therefore,
the caller
.I must
zero-fill this structure on initialization.
Please see the "Extensibility" section under
See the "Extensibility" subsection under
.B NOTES
for more details.
.PP
@ -97,17 +97,17 @@ argument should usually be specified as
However,
if the caller does not intend to make use of features that
got introduced after the initial version of
.I struct mount_attr
they are free to pass
.IR "struct mount_attr" ,
it is possible to pass
the size of the initial struct together with the larger struct.
This allows the kernel to not copy later parts of the struct
that aren't used anyway.
With each extension that changes the size of
.I struct mount_attr
the kernel will expose a define of the form
.IR "struct mount_attr" ,
the kernel will expose a definition of the form
.BI MOUNT_ATTR_SIZE_VER number\c
\&.
For example the macro for the size of the initial version of
For example, the macro for the size of the initial version of
.I struct mount_attr
is
.BR MOUNT_ATTR_SIZE_VER0 .
@ -129,7 +129,7 @@ itself.
Change the mount properties of the entire mount tree.
.TP
.B AT_SYMLINK_NOFOLLOW
Don't follow trailing symlinks.
Don't follow trailing symbolic links.
.TP
.B AT_NO_AUTOMOUNT
Don't trigger automounts.
@ -143,10 +143,10 @@ is a structure of the following form:
.in +4n
.EX
struct mount_attr {
__u64 attr_set; /* Mount properties to set. */
__u64 attr_clr; /* Mount properties to clear. */
__u64 propagation; /* Mount propagation type. */
__u64 userns_fd; /* User namespace file descriptor. */
__u64 attr_set; /* Mount properties to set */
__u64 attr_clr; /* Mount properties to clear */
__u64 propagation; /* Mount propagation type */
__u64 userns_fd; /* User namespace file descriptor */
};
.EE
.in
@ -197,9 +197,10 @@ mnt->mnt_flags = current_mnt_flags;
.EE
.in
.PP
The effect of this change will be a mount or mount tree that is read-only,
blocks the execution of set-user-ID and set-group-ID binaries,
but does allow to execute programs and access to devices nodes.
As a rsult of this change, the mount or mount tree (a) is read-only;
(b) blocks the execution of set-user-ID and set-group-ID programs;
(c) allows execution of programs; and (d) allows access to devices.
.PP
Multiple changes with the same set of flags requested
in
.I attr_clr
@ -215,63 +216,63 @@ fields:
.TP
.B MOUNT_ATTR_RDONLY
If set in
.I attr_set
makes the mount read-only,
and if set in
.I attr_clr
.IR attr_set ,
makes the mount read-only.
If set in
.IR attr_clr ,
removes the read-only setting if set on the mount.
.TP
.B MOUNT_ATTR_NOSUID
If set in
.I attr_set
makes the mount not honor set-user-ID and set-group-ID binaries,
and file capabilities when executing programs.
.IR attr_set ,
causes the mount not to honor the set-user-ID and set-group-ID mode bits and
file capabilities when executing programs.
If set in
.I attr_clr
.IR attr_clr ,
clears the set-user-ID, set-group-ID,
and file capability restriction if set on this mount.
.TP
.B MOUNT_ATTR_NODEV
If set in
.I attr_set
prevents access to devices on this mount,
and if set in
.I attr_clr
removes the restriction that prevented accesing devices on this mount.
.IR attr_set ,
prevents access to devices on this mount.
If set in
.IR attr_clr ,
removes the restriction that prevented accessing devices on this mount.
.TP
.B MOUNT_ATTR_NOEXEC
If set in
.I attr_set
prevents executing programs on this mount,
and if set in
.I attr_clr
.IR attr_set ,
prevents executing programs on this mount.
If set in
.IR attr_clr ,
removes the restriction that prevented executing programs on this mount.
.TP
.B MOUNT_ATTR_NOSYMFOLLOW
If set in
.I attr_set
prevents following symlinks on this mount,
and if set in
.I attr_clr
removes the restriction that prevented following symlinks on this mount.
.IR attr_set ,
prevents following symbolic links on this mount.
If set in
.IR attr_clr ,
removes the restriction that prevented following symbolic links on this mount.
.TP
.B MOUNT_ATTR_NODIRATIME
If set in
.I attr_set
prevents updating access time for directories on this mount,
and if set in
.I attr_clr
.IR attr_set ,
prevents updating access time for directories on this mount.
If set in
.IR attr_clr ,
removes the restriction that prevented updating access time for directories.
Note that
.B MOUNT_ATTR_NODIRATIME
can be combined with other access time settings
can be combined with other access-time settings
and is implied by the noatime setting.
All other access time settings are mutually exclusive.
All other access-time settings are mutually exclusive.
.TP
.BR MOUNT_ATTR__ATIME " - Changing access time settings"
In the new mount API the access time values are an enum starting from 0.
Even though they are an enum in contrast to the other mount flags such as
.BR MOUNT_ATTR_NOEXEC ,
.BR MOUNT_ATTR__ATIME " - changing access-time settings"
In the new mount API, the access-time values are an enum starting from 0.
Even though they are an enum (in contrast to the other mount flags such as
.BR MOUNT_ATTR_NOEXEC ),
they are nonetheless passed in
.I attr_set
and
@ -280,11 +281,11 @@ for consistency with
.BR fsmount (2),
which introduced this behavior.
.IP
Note,
since access times are an enum,
not a bitmap,
users wanting to transition to a different access time setting cannot simply
specify the access time in
Note that,
since access times are an enum
not a bit map,
users wanting to transition to a different access-time setting cannot simply
specify the access-time setting in
.I attr_set
but must also set
.B MOUNT_ATTR__ATIME
@ -297,7 +298,7 @@ isn't partially set in
.IR attr_clr ,
and that
.I attr_set
doesn't have any access time bits set if
doesn't have any access-time bits set if
.B MOUNT_ATTR__ATIME
isn't set in
.IR attr_clr .
@ -309,7 +310,7 @@ update the file's last access time (atime)
only if the current value of atime is less than or equal to
the file's last modification time (mtime) or last status change time (ctime).
.IP
To enable this access time setting on a mount or mount tree,
To enable this access-time setting on a mount or mount tree,
.B MOUNT_ATTR_RELATIME
must be set in
.I attr_set
@ -322,7 +323,7 @@ field.
.B MOUNT_ATTR_NOATIME
Do not update access times for (all types of) files on this mount.
.IP
To enable this access time setting on a mount or mount tree,
To enable this access-time setting on a mount or mount tree,
.B MOUNT_ATTR_NOATIME
must be set in
.I attr_set
@ -336,7 +337,7 @@ field.
Always update the last access time (atime)
when files are accessed on this mount.
.IP
To enable this access time setting on a mount or mount tree,
To enable this access-time setting on a mount or mount tree,
.B MOUNT_ATTR_STRICTATIME
must be set in
.I attr_set
@ -349,19 +350,20 @@ field.
.TP
.B MOUNT_ATTR_IDMAP
If set in
.I attr_set
.IR attr_set ,
creates an ID-mapped mount.
The ID mapping is taken from the user namespace specified in
.I userns_fd
and attached to the mount.
.IP
Since it is not supported to
change the ID mapping of a mount after it has been ID mapped,
it is invalid to specify
.B MOUNT_ATTR_IDMAP
in
.IR attr_clr .
The ID mapping is taken from the user namespace specified in
.I userns_fd
and attached to the mount.
.IP
Creating an ID-mapped mount allows to
Creating an ID-mapped mount makes it possible to
change the ownership of all files located under a mount.
Thus, ID-mapped mounts make it possible to
change ownership in a temporary and localized way.
@ -381,12 +383,13 @@ keys:
.RS
.IP \(bu 3
.IR security.capability ,
whenever filesystem
.BR capabilities (7)
whenever filesystem capabilities
are stored or returned in the
.I VFS_CAP_REVISION_3
.B VFS_CAP_REVISION_3
format,
which stores a rootid alongside the capabilities.
which stores a root user ID alongside the capabilities
(see
.BR capabilities (7)).
.IP \(bu
.I system.posix_acl_access
and
@ -401,16 +404,16 @@ entries.
The following conditions must be met in order to create an ID-mapped mount:
.RS
.IP \(bu 3
The caller must have
.I CAP_SYS_ADMIN
in the initial user namespace.
The caller must have the
.B CAP_SYS_ADMIN
capability in the initial user namespace.
.IP \(bu
The filesystem must be mounted in the initial user namespace.
.IP \(bu
The underlying filesystem must support ID-mapped mounts.
Currently
Currently,
.BR xfs (5),
.BR ext4 (5)
.BR ext4 (5),
and
.B FAT
filesystems support ID-mapped mounts
@ -419,12 +422,12 @@ with more filesystems being actively worked on.
The mount must not already be ID-mapped.
This also implies that the ID mapping of a mount cannot be altered.
.IP \(bu
The mount must be a detached/anonymous mount,
i.e.,
The mount must be a detached/anonymous mount;
that is,
it must have been created by calling
.BR open_tree (2)
with the
.I OPEN_TREE_CLONE
.B OPEN_TREE_CLONE
flag and it must not already have been visible in the filesystem.
.RE
.IP
@ -441,15 +444,17 @@ user ID 1000 in the caller's user namespace is mapped to
user ID 1001 in its ancestor user namespace.
Since the map range is 1,
only user ID 1000 is mapped.
.IP
It is possible to specify up to 340 ID mappings for each ID mapping type.
If any user IDs or group IDs are not mapped,
all files owned by that unmapped user or group ID will appear as
being owned by the overflow user ID or overflow group ID respectively.
.IP
Further details and instructions for setting up ID mappings can be found in the
.BR user_namespaces (7)
man page.
.IP
In the common case the user namespace passed in
In the common case, the user namespace passed in
.I userns_fd
together with
.B MOUNT_ATTR_IDMAP
@ -470,7 +475,7 @@ Sharing files between multiple users or multiple machines,
especially in complex scenarios.
For example,
ID-mapped mounts are used to implement portable home directories in
.BR systemd-homed.service (8)
.BR systemd-homed.service (8),
where they allow users to move their home directory
to an external storage device
and use it on multiple computers
@ -482,7 +487,7 @@ Sharing files from the host with unprivileged containers.
This allows a user to avoid having to change ownership permanently through
.BR chown (2).
.IP \(bu
Idmapping a container's root filesystem.
ID mapping a container's root filesystem.
Users don't need to change ownership permanently through
.BR chown (2).
Especially for large root filesystems, using
@ -492,16 +497,16 @@ can be prohibitively expensive.
Sharing files between containers with non-overlapping ID mappings.
.IP \(bu
Implementing discretionary access (DAC) permission checking
for fileystems lacking a concept of ownership.
for filesystems lacking a concept of ownership.
.IP \(bu
Efficiently change ownership on a per-mount basis.
Efficiently changing ownership on a per-mount basis.
In contrast to
.BR chown (2),
changing ownership of large sets of files is instantenous with
changing ownership of large sets of files is instantaneous with
ID-mapped mounts.
This is especially useful when ownership of
an entire root filesystem of a virtual machine or container
is to be changed as we've mentioned above.
is to be changed as mentioned above.
With ID-mapped mounts,
a single
.BR mount_setattr ()
@ -517,10 +522,10 @@ take the current ownership of the files it changes into account.
It simply changes the ownership to the specified user ID and group ID.
.IP \(bu
Locally and temporarily restricted ownership changes.
ID-mapped mounts allow to change ownership locally,
ID-mapped mounts make it possible to change ownership locally,
restricting it to specific mounts,
and temporarily as the ownership changes only apply as long as the mount exists.
In contrast,
By contrast,
changing ownership via the
.BR chown (2)
system call changes the ownership globally and permanently.
@ -529,10 +534,10 @@ system call changes the ownership globally and permanently.
The
.I propagation
field is used to specify the propagation type of the mount or mount tree.
Mount propagation options are mutually exclusive,
i.e.,
Mount propagation options are mutually exclusive;
that is,
the propagation values behave like an enum.
The supported mount propagation settings are:
The supported mount propagation types are:
.TP
.B MS_PRIVATE
Turn all mounts into private mounts.
@ -583,7 +588,7 @@ is not a valid file descriptor.
.TP
.B EBUSY
The caller tried to change the mount to
.B MOUNT_ATTR_RDONLY
.BR MOUNT_ATTR_RDONLY ,
but the mount still holds files open for writing.
.TP
.B EINVAL
@ -593,7 +598,7 @@ and
.I path
arguments to
.BR mount_setattr ()
isn't a mountpoint.
isn't a mount point.
.TP
.B EINVAL
An unsupported value was set in
@ -630,7 +635,7 @@ field of
.IR mount_attr .
.TP
.B EINVAL
An access time setting was specified in the
An access-time setting was specified in the
.I attr_set
field without
.B MOUNT_ATTR__ATIME
@ -651,7 +656,7 @@ which exceeds
.TP
.B EINVAL
A valid file descriptor value was specified in
.I userns_fd
.IR userns_fd ,
but the file descriptor wasn't a namespace file descriptor
or did not refer to a user namespace.
.TP
@ -659,12 +664,11 @@ or did not refer to a user namespace.
The underlying filesystem does not support ID-mapped mounts.
.TP
.B EINVAL
The mount that is to be ID mapped is not a detached/anonymous mount,
i.e.,
the mount is already visible in the filesystem.
The mount that is to be ID mapped is not a detached/anonymous mount;
that is, the mount is already visible in the filesystem.
.TP
.B EINVAL
A partial access time setting was specified in
A partial access-time setting was specified in
.I attr_clr
instead of
.B MOUNT_ATTR__ATIME
@ -681,19 +685,19 @@ A pathname was empty or had a nonexistent component.
.TP
.B ENOMEM
When changing mount propagation to
.B MS_SHARED
a new peer group id needs to be allocated for all mounts without a peer group
id set.
Allocation of this peer group id has failed.
.BR MS_SHARED ,
a new peer group ID needs to be allocated for all mounts without a peer group
ID set.
Allocation of this peer group ID has failed.
.TP
.B ENOSPC
When changing mount propagation to
.B MS_SHARED
a new peer group id needs to be allocated for all mounts without a peer group
id set.
Allocation of this peer group id can fail.
.BR MS_SHARED ,
a new peer group ID needs to be allocated for all mounts without a peer group
ID set.
Allocation of this peer group ID can fail.
Note that technically further error codes are possible that are specific to the
id allocation implementation used.
ID allocation implementation used.
.TP
.B EPERM
One of the mounts had at least one of
@ -721,13 +725,13 @@ in
.BR clone (2),
or
.BR clone3 (2).
The aformentioned flags become locked to protect user namespaces from altering
The aforementioned flags become locked to protect user namespaces from altering
sensitive mount properties.
.RE
.TP
.B EPERM
A valid file descriptor value was specified in
.I userns_fd
.IR userns_fd ,
but the file descriptor refers to the initial user namespace.
.TP
.B EPERM
@ -735,7 +739,7 @@ An already ID-mapped mount was supposed to be ID mapped.
.TP
.B EPERM
The caller does not have
.I CAP_SYS_ADMIN
.B CAP_SYS_ADMIN
in the initial user namespace.
.SH VERSIONS
.BR mount_setattr ()
@ -750,10 +754,6 @@ is Linux-specific.
.SS Extensibility
In order to allow for future extensibility,
.BR mount_setattr ()
along with other system calls such as
.BR openat2 (2)
and
.BR clone3 (2)
requires the user-space application to specify the size of the
.I mount_attr
structure that it is passing.
@ -834,7 +834,7 @@ struct mount_attr attr = {
.EE
.in
.PP
or explicitly using
Alternatively, the structure can be zero-filled using
.BR memset (3)
or similar functions:
.PP
@ -856,8 +856,8 @@ with a structure which has every byte nonzero
.SH EXAMPLES
.EX
/*
* This program allows the caller to create a new detached mount and set
* various properties on it.
* This program allows the caller to create a new detached mount
* and set various properties on it.
*/
#define _GNU_SOURCE
#include <errno.h>
@ -928,7 +928,7 @@ main(int argc, char *argv[])
case 'a':
fd_userns = open(optarg, O_RDONLY | O_CLOEXEC);
if (fd_userns == \-1)
exit_log("%m - Failed top open %s\en", optarg);
exit_log("%m \- Failed top open %s\en", optarg);
break;
case 'b':
recursive = true;
@ -957,7 +957,7 @@ main(int argc, char *argv[])
new_argv = &argv[optind];
new_argc = argc \- optind;
if (new_argc < 2)
exit_log("Missing source or target mountpoint\en");
exit_log("Missing source or target mount point\en");
source = new_argv[0];
target = new_argv[1];
@ -967,7 +967,7 @@ main(int argc, char *argv[])
AT_EMPTY_PATH |
(recursive ? AT_RECURSIVE : 0));
if (fd_tree == \-1)
exit_log("%m - Failed to open %s\en", source);
exit_log("%m \- Failed to open %s\en", source);
if (fd_userns >= 0) {
attr->attr_set |= MOUNT_ATTR_IDMAP;