From 3643106e2c1e3b604550fa89b5a53cc232cec2fa Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Mon, 9 Aug 2021 06:40:41 +0200 Subject: [PATCH] mount_setattr.2: wfix: "idmapped/idmapping" is not natural English Let's use ID mapped, ID mapping, etc. Signed-off-by: Michael Kerrisk --- man2/mount_setattr.2 | 61 ++++++++++++++++++++++---------------------- 1 file changed, 31 insertions(+), 30 deletions(-) diff --git a/man2/mount_setattr.2 b/man2/mount_setattr.2 index e1d3af82d..7478d0b7b 100644 --- a/man2/mount_setattr.2 +++ b/man2/mount_setattr.2 @@ -350,20 +350,20 @@ field. .B MOUNT_ATTR_IDMAP If set in .I attr_set -creates an idmapped mount. +creates an ID-mapped mount. Since it is not supported to -change the idmapping of a mount after it has been idmapped, +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 idmapping is taken from the user namespace specified in +The ID mapping is taken from the user namespace specified in .I userns_fd and attached to the mount. .IP -Creating an idmapped mount allows to +Creating an ID-mapped mount allows to change the ownership of all files located under a mount. -Thus, idmapped mounts make it possible to +Thus, ID-mapped mounts make it possible to change ownership in a temporary and localized way. It is a localized change because ownership changes are restricted to a specific mount. @@ -371,8 +371,8 @@ All other users and locations where the filesystem is exposed are unaffected. And it is a temporary change because ownership changes are tied to the lifetime of the mount. .IP -Whenever callers interact with the filesystem through an idmapped mount, -the idmapping of the mount will be applied to +Whenever callers interact with the filesystem through an ID-mapped mount, +the ID mapping of the mount will be applied to user and group IDs associated with filesystem objects. This encompasses the user and group IDs associated with inodes and also the following @@ -398,7 +398,7 @@ or entries. .RE .IP -The following conditions must be met in order to create an idmapped mount: +The following conditions must be met in order to create an ID-mapped mount: .RS .IP \(bu 3 The caller must have @@ -407,17 +407,17 @@ in the initial user namespace. .IP \(bu The filesystem must be mounted in the initial user namespace. .IP \(bu -The underlying filesystem must support idmapped mounts. +The underlying filesystem must support ID-mapped mounts. Currently .BR xfs (5), .BR ext4 (5) and .B FAT -filesystems support idmapped mounts +filesystems support ID-mapped mounts with more filesystems being actively worked on. .IP \(bu -The mount must not already be idmapped. -This also implies that the idmapping of a mount cannot be altered. +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., @@ -428,24 +428,24 @@ with the flag and it must not already have been visible in the filesystem. .RE .IP -Idmappings can be created for user IDs, group IDs, and project IDs. -An idmapping is essentially a mapping of a range of user or group IDs into +ID mappings can be created for user IDs, group IDs, and project IDs. +An ID mapping is essentially a mapping of a range of user or group IDs into another or the same range of user or group IDs. -Idmappings are usually written as three numbers +ID mappings are usually written as three numbers either separated by white space or a full stop. The first two numbers specify the starting user or group ID in each of the two user namespaces. -The third number specifies the range of the idmapping. +The third number specifies the range of the ID mapping. For example, a mapping for user IDs such as 1000:1001:1 would indicate that 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. -It is possible to specify up to 340 idmappings for each idmapping 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, 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. -Further details and instructions for setting up idmappings can be found in the +Further details and instructions for setting up ID mappings can be found in the .BR user_namespaces (7) man page. .IP @@ -455,21 +455,21 @@ together with .B MOUNT_ATTR_IDMAP in .I attr_set -to create an idmapped mount will be the user namespace of a container. +to create an ID-mapped mount will be the user namespace of a container. In other scenarios it will be a dedicated user namespace associated with a user's login session as is the case for portable home directories in .BR systemd-homed.service (8)). It is also perfectly fine to create a dedicated user namespace -for the sake of idmapping a mount. +for the sake of ID mapping a mount. .IP -Idmapped mounts can be useful in the following +ID-mapped mounts can be useful in the following and a variety of other scenarios: .RS .IP \(bu 3 Sharing files between multiple users or multiple machines, especially in complex scenarios. For example, -idmapped 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) where they allow users to move their home directory to an external storage device @@ -489,7 +489,7 @@ Especially for large root filesystems, using .BR chown (2) can be prohibitively expensive. .IP \(bu -Sharing files between containers with non-overlapping idmappings. +Sharing files between containers with non-overlapping ID mappings. .IP \(bu Implementing discretionary access (DAC) permission checking for fileystems lacking a concept of ownership. @@ -497,17 +497,18 @@ for fileystems lacking a concept of ownership. Efficiently change ownership on a per-mount basis. In contrast to .BR chown (2), -changing ownership of large sets of files is instantenous with idmapped mounts. +changing ownership of large sets of files is instantenous 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. -With idmapped mounts, +With ID-mapped mounts, a single .BR mount_setattr () system call will be sufficient to change the ownership of all files. .IP \(bu Taking the current ownership into account. -Idmappings specify precisely +ID mappings specify precisely what a user or group ID is supposed to be mapped to. This contrasts with the .BR chown (2) @@ -516,7 +517,7 @@ 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. -Idmapped mounts allow to change ownership locally, +ID-mapped mounts allow 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, @@ -655,10 +656,10 @@ but the file descriptor wasn't a namespace file descriptor or did not refer to a user namespace. .TP .B EINVAL -The underlying filesystem does not support idmapped mounts. +The underlying filesystem does not support ID-mapped mounts. .TP .B EINVAL -The mount to idmap is not a detached/anonymous mount, +The mount that is to be ID mapped is not a detached/anonymous mount, i.e., the mount is already visible in the filesystem. .TP @@ -730,7 +731,7 @@ A valid file descriptor value was specified in but the file descriptor refers to the initial user namespace. .TP .B EPERM -An already idmapped mount was supposed to be idmapped. +An already ID-mapped mount was supposed to be ID mapped. .TP .B EPERM The caller does not have