From 265fd45d2510922b46ea381c714a599913f34e0a Mon Sep 17 00:00:00 2001 From: Karel Zak Date: Wed, 10 Jun 2026 11:09:03 +0200 Subject: [PATCH] docs: unshare: split --map-users/--map-groups into readable paragraphs No text changes, only line breaks to improve readability. Addresses: https://github.com/util-linux/util-linux/issues/3838 Signed-off-by: Karel Zak --- sys-utils/unshare.1.adoc | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/sys-utils/unshare.1.adoc b/sys-utils/unshare.1.adoc index d40bfee3c..114027c50 100644 --- a/sys-utils/unshare.1.adoc +++ b/sys-utils/unshare.1.adoc @@ -110,7 +110,11 @@ Just before running the program, mount the binfmt_misc filesystem at _mountpoint Run the program only after the current effective user ID has been mapped to _uid_. If this option is specified multiple times, the last occurrence takes precedence. This option implies *--user*. *--map-users* __inneruid__**:**__outeruid__**:**__count__|**auto**|**subids**|**all**:: -Run the program only after the block of user IDs of size _count_ beginning at _outeruid_ has been mapped to the block of user IDs beginning at _inneruid_. This mapping is created with **newuidmap**(1) if *unshare* was run unprivileged. The mapping specified by *--map-user* (including the convenience options *--map-root-user* and *--map-current-user*, which expand to a *--map-user*) takes precedence: it is applied first, and if the block requested here overlaps it (on either the _outeruid_ or _inneruid_ side), a "hole" is removed from this block so that the two mappings do not collide. The hole drops the highest user ID of the block, so it maps one fewer ID than _count_, and the block is split around the ID claimed by *--map-user* rather than including it. As a result, a user ID you expected this block to map (for example the first ID of an *id -u*-based range) may instead resolve to the ID set by *--map-user*, and the topmost _outeruid_ of the block may go unmapped. Use *--map-users* multiple times to map more than one block of user IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subuid_ to a block starting at user ID 0. The special value *subids* will identity map the same block. The special value *all* will create a pass-through map for every user ID available in the parent namespace. This option implies *--user*. +Run the program only after the block of user IDs of size _count_ beginning at _outeruid_ has been mapped to the block of user IDs beginning at _inneruid_. This mapping is created with **newuidmap**(1) if *unshare* was run unprivileged. ++ +The mapping specified by *--map-user* (including the convenience options *--map-root-user* and *--map-current-user*, which expand to a *--map-user*) takes precedence: it is applied first, and if the block requested here overlaps it (on either the _outeruid_ or _inneruid_ side), a "hole" is removed from this block so that the two mappings do not collide. The hole drops the highest user ID of the block, so it maps one fewer ID than _count_, and the block is split around the ID claimed by *--map-user* rather than including it. As a result, a user ID you expected this block to map (for example the first ID of an *id -u*-based range) may instead resolve to the ID set by *--map-user*, and the topmost _outeruid_ of the block may go unmapped. ++ +Use *--map-users* multiple times to map more than one block of user IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subuid_ to a block starting at user ID 0. The special value *subids* will identity map the same block. The special value *all* will create a pass-through map for every user ID available in the parent namespace. This option implies *--user*. + Before util-linux version 2.39, this option expected a comma-separated argument of the form _outeruid_**,**_inneruid_**,**_count_ but that format is now deprecated for consistency with the ordering used in _/proc/[pid]/uid_map_ and the _X-mount.idmap_ mount option. @@ -118,7 +122,11 @@ Before util-linux version 2.39, this option expected a comma-separated argument Run the program only after the current effective group ID has been mapped to _gid_. If this option is specified multiple times, the last occurrence takes precedence. This option implies *--setgroups=deny* and *--user*. *--map-groups* __innergid__**:**__outergid__**:**__count__|**auto**|**subids**|**all**:: -Run the program only after the block of group IDs of size _count_ beginning at _outergid_ has been mapped to the block of group IDs beginning at _innergid_. This mapping is created with **newgidmap**(1) if *unshare* was run unprivileged. The mapping specified by *--map-group* (including the convenience options *--map-root-user* and *--map-current-user*, which expand to a *--map-group*) takes precedence: it is applied first, and if the block requested here overlaps it (on either the _outergid_ or _innergid_ side), a "hole" is removed from this block so that the two mappings do not collide. The hole drops the highest group ID of the block, so it maps one fewer ID than _count_, and the block is split around the ID claimed by *--map-group* rather than including it. As a result, a group ID you expected this block to map (for example the first ID of an *id -g*-based range) may instead resolve to the ID set by *--map-group*, and the topmost _outergid_ of the block may go unmapped. Use *--map-groups* multiple times to map more than one block of group IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subgid_ to a block starting at group ID 0. The special value *subids* will identity map the same block. The special value *all* will create a pass-through map for every group ID available in the parent namespace. This option implies *--user*. +Run the program only after the block of group IDs of size _count_ beginning at _outergid_ has been mapped to the block of group IDs beginning at _innergid_. This mapping is created with **newgidmap**(1) if *unshare* was run unprivileged. ++ +The mapping specified by *--map-group* (including the convenience options *--map-root-user* and *--map-current-user*, which expand to a *--map-group*) takes precedence: it is applied first, and if the block requested here overlaps it (on either the _outergid_ or _innergid_ side), a "hole" is removed from this block so that the two mappings do not collide. The hole drops the highest group ID of the block, so it maps one fewer ID than _count_, and the block is split around the ID claimed by *--map-group* rather than including it. As a result, a group ID you expected this block to map (for example the first ID of an *id -g*-based range) may instead resolve to the ID set by *--map-group*, and the topmost _outergid_ of the block may go unmapped. ++ +Use *--map-groups* multiple times to map more than one block of group IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subgid_ to a block starting at group ID 0. The special value *subids* will identity map the same block. The special value *all* will create a pass-through map for every group ID available in the parent namespace. This option implies *--user*. + Before util-linux version 2.39, this option expected a comma-separated argument of the form _outergid_**,**_innergid_**,**_count_ but that format is now deprecated for consistency with the ordering used in _/proc/[pid]/gid_map_ and the _X-mount.idmap_ mount option. -- 2.47.3