LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

234
man2/mount_setattr.2
View File

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