X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=sys-utils%2Funshare.1.adoc;h=e6201e28fffd46052648654f43ffac76a7dd7b06;hb=HEAD;hp=f3367a806140e795345709282b7185c27252eb16;hpb=2b2d317242303583e7f44737cb34bd069f5f3954;p=thirdparty%2Futil-linux.git diff --git a/sys-utils/unshare.1.adoc b/sys-utils/unshare.1.adoc index f3367a8061..5c2b268b19 100644 --- a/sys-utils/unshare.1.adoc +++ b/sys-utils/unshare.1.adoc @@ -90,21 +90,31 @@ When *unshare* terminates, have _signame_ be sent to the forked child process. C *--mount-proc*[**=**__mountpoint__]:: Just before running the program, mount the proc filesystem at _mountpoint_ (default is _/proc_). This is useful when creating a new PID namespace. It also implies creating a new mount namespace since the _/proc_ mount would otherwise mess up existing programs on the system. The new proc filesystem is explicitly mounted as private (with *MS_PRIVATE*|*MS_REC*). +*--mount-binfmt*[**=**__mountpoint__]:: +Just before running the program, mount the binfmt_misc filesystem at _mountpoint_ (default is /proc/sys/fs/binfmt_misc). It also implies creating a new mount namespace since the binfmt_misc mount would otherwise mess up existing programs on the system. The new binfmt_misc filesystem is explicitly mounted as private (with *MS_PRIVATE*|*MS_REC*). + **--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-users=**__inneruid:outeruid:count__|**auto**|**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. 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. 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. **--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-groups=**__innergid:outergid:count__|**auto**|**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. 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. 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. **--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*. +**--map-subids**:: +Identity map the first block of user IDs owned by the effective user from _/etc/subuid_. In the same manner, also identity map the first block of group IDs owned by the effective group from _/etc/subgid_. This option is equivalent to specifying *--map-users=subids* and *--map-groups=subids*. + *-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*. @@ -131,6 +141,10 @@ Set the user ID which will be used in the entered namespace. *-G*, *--setgid* _gid_:: Set the group ID which will be used in the entered namespace and drop supplementary groups. +*-l*, **--load-interp=**__string__:: +Load binfmt_misc definition in the namespace (implies *--mount-binfmt*). The __string__ argument is ``:name:type:offset:magic:mask:interpreter:flags``. For more details about new binary type registration see https://www.kernel.org/doc/Documentation/admin-guide/binfmt-misc.rst. +To manage the F flag in ``flags`` with **--root** parameter, binfmt_misc is mounted twice, once before the chroot to load the interpreter from the caller filesystem and once after to make it available from the chroot userspace. + *--monotonic* _offset_:: Set the offset of *CLOCK_MONOTONIC* which will be used in the entered time namespace. This option requires unsharing a time namespace with *--time*. @@ -141,11 +155,11 @@ include::man-common/help-version.adoc[] == NOTES -The proc and sysfs filesystems mounting as root in a user namespace have to be restricted so that a less privileged user can not get more access to sensitive files that a more privileged user made unavailable. In short the rule for proc and sysfs is as close to a bind mount as possible. +The proc and sysfs filesystems mounting as root in a user namespace have to be restricted so that a less privileged user cannot get more access to sensitive files that a more privileged user made unavailable. In short the rule for proc and sysfs is as close to a bind mount as possible. == EXAMPLES -The following command creates a PID namespace, using *--fork* to ensure that the executed command is performed in a child process that (being the first process in the namespace) has PID 1. The *--mount-proc* option ensures that a new mount namespace is also simultaneously created and that a new *proc*(5) filesystem is mounted that contains information corresponding to the new PID namespace. When the *readlink* command terminates, the new namespaces are automatically torn down. +The following command creates a PID namespace, using *--fork* to ensure that the executed command is performed in a child process that (being the first process in the namespace) has PID 1. The *--mount-proc* option ensures that a new mount namespace is also simultaneously created and that a new *proc*(5) filesystem is mounted that contains information corresponding to the new PID namespace. When the *readlink*(1) command terminates, the new namespaces are automatically torn down. .... # unshare --fork --pid --mount-proc readlink /proc/self @@ -159,7 +173,7 @@ $ id -u; id -g 1000 1000 $ unshare --user --map-root-user \ - sh -c ''whoami; cat /proc/self/uid_map /proc/self/gid_map'' + sh -c 'whoami; cat /proc/self/uid_map /proc/self/gid_map' root 0 1000 1 0 1000 1 @@ -210,11 +224,8 @@ The following commands demonstrate the use of the *--kill-child* option when cre .... # set +m # Don't print job status messages - # unshare --pid --fork --mount-proc --kill-child -- \ - - - bash --norc -c ''(sleep 555 &) && (ps a &) && sleep 999'' & + bash --norc -c '(sleep 555 &) && (ps a &) && sleep 999' & [1] 53456 # PID TTY STAT TIME COMMAND 1 pts/3 S+ 0:00 sleep 999 @@ -231,9 +242,7 @@ The *pidof*(1) command prints no output, because the *sleep* processes have been .... # unshare --pid --fork --mount-proc -- \ - - - bash --norc -c ''(sleep 555 &) && (ps a &) && sleep 999'' & + bash --norc -c '(sleep 555 &) && (ps a &) && sleep 999' & [1] 53479 # PID TTY STAT TIME COMMAND 1 pts/3 S+ 0:00 sleep 999 @@ -254,6 +263,20 @@ up 21 hours, 30 minutes up 9 years, 28 weeks, 1 day, 2 hours, 50 minutes .... +The following example execute a chroot into the directory /chroot/powerpc/jessie and install the interpreter /bin/qemu-ppc-static to execute the powerpc binaries. + +.... +$ unshare --map-root-user --fork --pid --load-interp=":qemu-ppc:M::\\x7fELF\x01\\x02\\x01\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x02\\x00\\x14:\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\x00\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\xfe\\xff\\xff:/bin/qemu-ppc-static:OCF" --root=/chroot/powerpc/jessie /bin/bash -l +.... + +The ``load-interp`` parameter can be read as following:: +``qemu-ppc``::: is the name of the new file created below ``/proc/sys/fs/binfmt_misc`` to register the interpreter +``M``::: defines the interpreter for a given type of magic number +``\\x7fELF\x01\\x02\\x01\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x02\\x00\\x1``::: is the magic number to recognize the file to interpret (in this case, the ELF header for PPC32) +``\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\x00\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\xff\\xfe\\xff\\xff``::: the mask to apply to the magic number +``/bin/qemu-ppc-static``::: the interpreter to use with the file +``OCF``::: the file is open by the kernel with credential and security tokens of the file itself and loaded as soon as we register it. + == AUTHORS mailto:dottedmag@dottedmag.net[Mikhail Gusarov], @@ -261,8 +284,8 @@ mailto:kzak@redhat.com[Karel Zak] == SEE ALSO -*newuidmap*(1) -*newgidmap*(1) +*newuidmap*(1), +*newgidmap*(1), *clone*(2), *unshare*(2), *namespaces*(7),