mount_setattr.2: wfix: "idmapped/idmapping" is not natural English

Let's use ID mapped, ID mapping, etc.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2021-08-09 06:40:41 +02:00
parent 736498624f
commit 3643106e2c
1 changed files with 31 additions and 30 deletions

View File

@ -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