From 133e6b161c7cb35437a147d0b9e33ef819993106 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Mon, 9 Aug 2021 06:48:14 +0200 Subject: [PATCH] mount_setattr.2: Minor wording, grammar, and formatting fixes Signed-off-by: Michael Kerrisk --- man2/mount_setattr.2 | 234 +++++++++++++++++++++---------------------- 1 file changed, 117 insertions(+), 117 deletions(-) diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2 index 7478d0b7b..756f6d21b 100644 --- a/man2/mount_setattr.2 +++ b/man2/mount_setattr.2 @@ -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 @@ -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;