All of lore.kernel.org
 help / color / mirror / Atom feed
From: Sean Anderson <seanga2@gmail.com>
To: util-linux@vger.kernel.org, Karel Zak <kzak@redhat.com>
Cc: Mikhail Gusarov <dottedmag@dottedmag.net>,
	Matthew Harm Bekkema <id@mbekkema.name>,
	James Peach <jpeach@apache.org>,
	Sean Anderson <seanga2@gmail.com>
Subject: [PATCH v2 6/6] unshare: Document --map-{groups,users,auto}
Date: Wed, 24 Nov 2021 13:26:18 -0500	[thread overview]
Message-ID: <20211124182618.1801447-7-seanga2@gmail.com> (raw)
In-Reply-To: <20211124182618.1801447-1-seanga2@gmail.com>

This documents the new options added in the previous few commits.
I have added another example to better demonstrate the these
options. The actual use is fairly straightforward, but the descriptions
are on the pithier side.

Signed-off-by: Sean Anderson <seanga2@gmail.com>
---

Changes in v2:
- Document new "auto" value for --map-user and --map-group
- Fix typo of --group instead of --user

 sys-utils/unshare.1.adoc | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/sys-utils/unshare.1.adoc b/sys-utils/unshare.1.adoc
index 74183ebc1..cb1302461 100644
--- a/sys-utils/unshare.1.adoc
+++ b/sys-utils/unshare.1.adoc
@@ -93,9 +93,18 @@ Just before running the program, mount the proc filesystem at _mountpoint_ (defa
 **--map-user=**__uid|name__::
 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=**__outeruid,inneruid,count__|**auto**::
+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 the range of user IDs overlaps with the mapping specified by *--map-user*, then a "hole" will be removed from the mapping. This may result in the highest user ID of the mapping not being mapped. 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. If this option is specified multiple times, the last occurrence takes precedence. This option implies *--user*.
+
 **--map-group=**__gid|name__::
 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=**__outergid,innergid,count__|**auto**::
+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 the range of group IDs overlaps with the mapping specified by *--map-group*, then a "hole" will be removed from the mapping. This may result in the highest group ID of the mapping not being mapped. 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. If this option is specified multiple times, the last occurrence takes precedence. This option implies *--user*.
+
+**--map-auto**::
+Map the first block of user IDs owned by the effective user from _/etc/subuid_ to a block starting at user ID 0. In the same manner, also map the first block of group IDs owned by the effective group from _/etc/subgid_ to a block starting at group ID 0. This option is intended to handle the common case where the first block of subordinate user and group IDs can map the whole user and group ID space. This option is equivalent to specifying *--map-users=auto* and *--map-groups=auto*.
+
 *-r*, *--map-root-user*::
 Run the program only after the current effective user and group IDs have been mapped to the superuser UID and GID in the newly created user namespace. This makes it possible to conveniently gain capabilities needed to manage various aspects of the newly created namespaces (such as configuring interfaces in the network namespace or mounting filesystems in the mount namespace) even when run unprivileged. As a mere convenience feature, it does not support more sophisticated use cases, such as mapping multiple ranges of UIDs and GIDs. This option implies *--setgroups=deny* and *--user*. This option is equivalent to *--map-user=0 --map-group=0*.
 
@@ -160,6 +169,27 @@ root
          0       1000          1
 ....
 
+As an unprivileged user, create a user namespace where the first 65536 IDs are all mapped, and the user's credentials are mapped to the root IDs inside the namespace. The map is determined by the subordinate IDs assigned in *subuid*(5) and *subgid*(5). Demonstrate this mapping by creating a file with user ID 1 and group ID 1. For brevity, only the user ID mappings are shown:
+
+....
+$ id -u
+1000
+$ cat /etc/subuid
+1000:100000:65536
+$ unshare --user --map-auto --map-root-user
+# id -u
+0
+# cat /proc/self/uid_map
+         0       1000          1
+         1     100000      65535
+# touch file; chown 1:1 file
+# ls -ln --time-style=+ file
+-rw-r--r-- 1 1 1 0  file
+# exit
+$ ls -ln --time-style=+ file
+-rw-r--r-- 1 100000 100000 0  file
+....
+
 The first of the following commands creates a new persistent UTS namespace and modifies the hostname as seen in that namespace. The namespace is then entered with *nsenter*(1) in order to display the modified hostname; this step demonstrates that the UTS namespace continues to exist even though the namespace had no member processes after the *unshare* command terminated. The namespace is then destroyed by removing the bind mount.
 
 ....
@@ -235,6 +265,8 @@ mailto:kzak@redhat.com[Karel Zak]
 
 == SEE ALSO
 
+*newuidmap*(1)
+*newgidmap*(1)
 *clone*(2),
 *unshare*(2),
 *namespaces*(7),
-- 
2.33.0


  parent reply	other threads:[~2021-11-24 18:26 UTC|newest]

Thread overview: 13+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-11-24 18:26 [PATCH v2 0/6] unshare: Add support for mapping ranges of user/group IDs Sean Anderson
2021-11-24 18:26 ` [PATCH v2 1/6] include/c: Add abs_diff macro Sean Anderson
2021-11-24 18:26 ` [PATCH v2 2/6] unshare: Add waitchild helper Sean Anderson
2021-11-24 18:26 ` [PATCH v2 3/6] unshare: Add some helpers for forking and synchronizing Sean Anderson
2021-11-24 18:26 ` [PATCH v2 4/6] unshare: Add options to map blocks of user/group IDs Sean Anderson
2021-11-24 18:26 ` [PATCH v2 5/6] unshare: Add option to automatically create user and group maps Sean Anderson
2021-11-24 18:26 ` Sean Anderson [this message]
2021-12-01 15:16 ` [PATCH v2 0/6] unshare: Add support for mapping ranges of user/group IDs Karel Zak
2022-01-14 10:29 ` Daniel Gerber
2022-01-14 14:42   ` Sean Anderson
2022-01-14 17:15     ` Daniel Gerber
2022-01-15  0:53       ` Sean Anderson
2022-01-18 11:50   ` Karel Zak

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20211124182618.1801447-7-seanga2@gmail.com \
    --to=seanga2@gmail.com \
    --cc=dottedmag@dottedmag.net \
    --cc=id@mbekkema.name \
    --cc=jpeach@apache.org \
    --cc=kzak@redhat.com \
    --cc=util-linux@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.