mirror of https://github.com/mkerrisk/man-pages
mount_setattr.2: Minor wording, grammar, and formatting fixes
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
3643106e2c
commit
133e6b161c
|
@ -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,
|
||||
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 in
|
||||
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
|
||||
|
@ -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;
|
||||
|
@ -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;
|
||||
|
|
Loading…
Reference in New Issue