Provided by: util-linux_2.40.2-1ubuntu1_amd64 bug

NAME

       unshare - run program in new namespaces

SYNOPSIS

       unshare [options] [program [arguments]]

DESCRIPTION

       The unshare command creates new namespaces (as specified by the command-line options
       described below) and then executes the specified program. If program is not given, then
       "${SHELL}" is run (default: /bin/sh).

       By default, a new namespace persists only as long as it has member processes. A new
       namespace can be made persistent even when it has no member processes by bind mounting
       /proc/pid/ns/type files to a filesystem path. A namespace that has been made persistent in
       this way can subsequently be entered with nsenter(1) even after the program terminates
       (except PID namespaces where a permanently running init process is required). Once a
       persistent namespace is no longer needed, it can be unpersisted by using umount(8) to
       remove the bind mount. See the EXAMPLES section for more details.

       unshare since util-linux version 2.36 uses /proc/[pid]/ns/pid_for_children and
       /proc/[pid]/ns/time_for_children files for persistent PID and TIME namespaces. This change
       requires Linux kernel 4.17 or newer.

       The following types of namespaces can be created with unshare:

       mount namespace
           Mounting and unmounting filesystems will not affect the rest of the system, except for
           filesystems which are explicitly marked as shared (with mount --make-shared; see
           /proc/self/mountinfo or findmnt -o+PROPAGATION for the shared flags). For further
           details, see mount_namespaces(7).

           unshare since util-linux version 2.27 automatically sets propagation to private in a
           new mount namespace to make sure that the new namespace is really unshared. It’s
           possible to disable this feature with option --propagation unchanged. Note that
           private is the kernel default.

       UTS namespace
           Setting hostname or domainname will not affect the rest of the system. For further
           details, see uts_namespaces(7).

       IPC namespace
           The process will have an independent namespace for POSIX message queues as well as
           System V message queues, semaphore sets and shared memory segments. For further
           details, see ipc_namespaces(7).

       network namespace
           The process will have independent IPv4 and IPv6 stacks, IP routing tables, firewall
           rules, the /proc/net and /sys/class/net directory trees, sockets, etc. For further
           details, see network_namespaces(7).

       PID namespace
           Children will have a distinct set of PID-to-process mappings from their parent. For
           further details, see pid_namespaces(7).

       cgroup namespace
           The process will have a virtualized view of /proc/self/cgroup, and new cgroup mounts
           will be rooted at the namespace cgroup root. For further details, see
           cgroup_namespaces(7).

       user namespace
           The process will have a distinct set of UIDs, GIDs and capabilities. For further
           details, see user_namespaces(7).

       time namespace
           The process can have a distinct view of CLOCK_MONOTONIC and/or CLOCK_BOOTTIME which
           can be changed using /proc/self/timens_offsets. For further details, see
           time_namespaces(7).

OPTIONS

       -i, --ipc[=file]
           Create a new IPC namespace. If file is specified, then the namespace is made
           persistent by creating a bind mount at file.

       -m, --mount[=file]
           Create a new mount namespace. If file is specified, then the namespace is made
           persistent by creating a bind mount at file. Note that file must be located on a mount
           whose propagation type is not shared (or an error results). Use the command findmnt
           -o+PROPAGATION when not sure about the current setting. See also the examples below.

       -n, --net[=file]
           Create a new network namespace. If file is specified, then the namespace is made
           persistent by creating a bind mount at file.

       -p, --pid[=file]
           Create a new PID namespace. If file is specified, then the namespace is made
           persistent by creating a bind mount at file. (Creation of a persistent PID namespace
           will fail if the --fork option is not also specified.)

           See also the --fork and --mount-proc options.

       -u, --uts[=file]
           Create a new UTS namespace. If file is specified, then the namespace is made
           persistent by creating a bind mount at file.

       -U, --user[=file]
           Create a new user namespace. If file is specified, then the namespace is made
           persistent by creating a bind mount at file.

       -C, --cgroup[=file]
           Create a new cgroup namespace. If file is specified, then the namespace is made
           persistent by creating a bind mount at file.

       -T, --time[=file]
           Create a new time namespace. If file is specified, then the namespace is made
           persistent by creating a bind mount at file. The --monotonic and --boottime options
           can be used to specify the corresponding offset in the time namespace.

       -f, --fork
           Fork the specified program as a child process of unshare rather than running it
           directly. This is useful when creating a new PID namespace. Note that when unshare is
           waiting for the child process, then it ignores SIGINT and SIGTERM and does not forward
           any signals to the child. It is necessary to send signals to the child process.

       --keep-caps
           When the --user option is given, ensure that capabilities granted in the user
           namespace are preserved in the child process.

       --kill-child[=signame]
           When unshare terminates, have signame be sent to the forked child process. Combined
           with --pid this allows for an easy and reliable killing of the entire process tree
           below unshare. If not given, signame defaults to SIGKILL. This option implies --fork.

       --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=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 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=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 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.

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

       -c, --map-current-user
           Run the program only after the current effective user and group IDs have been mapped
           to the same UID and GID in the newly created user namespace. This option implies
           --setgroups=deny and --user. This option is equivalent to --map-user=$(id -ru)
           --map-group=$(id -rg).

       --propagation private|shared|slave|unchanged
           Recursively set the mount propagation flag in the new mount namespace. The default is
           to set the propagation to private. It is possible to disable this feature with the
           argument unchanged. The option is silently ignored when the mount namespace (--mount)
           is not requested.

       --setgroups allow|deny
           Allow or deny the setgroups(2) system call in a user namespace.

           To be able to call setgroups(2), the calling process must at least have CAP_SETGID.
           But since Linux 3.19 a further restriction applies: the kernel gives permission to
           call setgroups(2) only after the GID map (/proc/pid*/gid_map*) has been set. The GID
           map is writable by root when setgroups(2) is enabled (i.e., allow, the default), and
           the GID map becomes writable by unprivileged processes when setgroups(2) is
           permanently disabled (with deny).

       -R, --root=dir
           run the command with root directory set to dir.

       -w, --wd=dir
           change working directory to dir.

       -S, --setuid uid
           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.

       --boottime offset
           Set the offset of CLOCK_BOOTTIME which will be used in the entered time namespace.
           This option requires unsharing a time namespace with --time.

       -h, --help
           Display help text and exit.

       -V, --version
           Print version and exit.

NOTES

       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(1) command
       terminates, the new namespaces are automatically torn down.

           # unshare --fork --pid --mount-proc readlink /proc/self
           1

       As an unprivileged user, create a new user namespace where the user’s credentials are
       mapped to the root IDs inside the namespace:

           $ id -u; id -g
           1000
           1000
           $ unshare --user --map-root-user \
                   sh -c 'whoami; cat /proc/self/uid_map /proc/self/gid_map'
           root
                    0       1000          1
                    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.

           # touch /root/uts-ns
           # unshare --uts=/root/uts-ns hostname FOO
           # nsenter --uts=/root/uts-ns hostname
           FOO
           # umount /root/uts-ns

       The following commands establish a persistent mount namespace referenced by the bind mount
       /root/namespaces/mnt. In order to ensure that the creation of that bind mount succeeds,
       the parent directory (/root/namespaces) is made a bind mount whose propagation type is not
       shared.

           # mount --bind /root/namespaces /root/namespaces
           # mount --make-private /root/namespaces
           # touch /root/namespaces/mnt
           # unshare --mount=/root/namespaces/mnt

       The following commands demonstrate the use of the --kill-child option when creating a PID
       namespace, in order to ensure that when unshare is killed, all of the processes within the
       PID namespace are killed.

           # set +m                # Don't print job status messages

           # unshare --pid --fork --mount-proc --kill-child -- \
                  bash --norc -c '(sleep 555 &) && (ps a &) && sleep 999' &
           [1] 53456
           #     PID TTY      STAT   TIME COMMAND
                 1 pts/3    S+     0:00 sleep 999
                 3 pts/3    S+     0:00 sleep 555
                 5 pts/3    R+     0:00 ps a

           # ps h -o 'comm' $!     # Show that background job is unshare(1)
           unshare
           # kill $!               # Kill unshare(1)
           # pidof sleep

       The pidof(1) command prints no output, because the sleep processes have been killed. More
       precisely, when the sleep process that has PID 1 in the namespace (i.e., the namespace’s
       init process) was killed, this caused all other processes in the namespace to be killed.
       By contrast, a similar series of commands where the --kill-child option is not used shows
       that when unshare terminates, the processes in the PID namespace are not killed:

           # unshare --pid --fork --mount-proc -- \
                  bash --norc -c '(sleep 555 &) && (ps a &) && sleep 999' &
           [1] 53479
           #     PID TTY      STAT   TIME COMMAND
                 1 pts/3    S+     0:00 sleep 999
                 3 pts/3    S+     0:00 sleep 555
                 5 pts/3    R+     0:00 ps a

           # kill $!
           # pidof sleep
           53482 53480

       The following example demonstrates the creation of a time namespace where the boottime
       clock is set to a point several years in the past:

           # uptime -p             # Show uptime in initial time namespace
           up 21 hours, 30 minutes
           # unshare --time --fork --boottime 300000000 uptime -p
           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

       Mikhail Gusarov <dottedmag@dottedmag.net>, Karel Zak <kzak@redhat.com>

SEE ALSO

       newuidmap(1), newgidmap(1), clone(2), unshare(2), namespaces(7), mount(8)

REPORTING BUGS

       For bug reports, use the issue tracker at https://github.com/util-linux/util-linux/issues.

AVAILABILITY

       The unshare command is part of the util-linux package which can be downloaded from Linux
       Kernel Archive <https://www.kernel.org/pub/linux/utils/util-linux/>.