unshare(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | NOTES | EXAMPLES | AUTHORS | SEE ALSO | AVAILABILITY | COLOPHON

UNSHARE(1)                    User Commands                   UNSHARE(1)

NAME         top

       unshare - run program in new namespaces

SYNOPSIS         top

       unshare [options] [program [arguments]]

DESCRIPTION         top

       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         top

       -i, --ipc[=file]
              Unshare the IPC namespace.  If file is specified, then a
              persistent namespace is created by a bind mount.

       -m, --mount[=file]
              Unshare the mount namespace.  If file is specified, then a
              persistent namespace is created by a bind mount.  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]
              Unshare the network namespace.  If file is specified, then
              a persistent namespace is created by a bind mount.

       -p, --pid[=file]
              Unshare the PID namespace.  If file is specified, then a
              persistent namespace is created by a bind mount.
              (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]
              Unshare the UTS namespace.  If file is specified, then a
              persistent namespace is created by a bind mount.

       -U, --user[=file]
              Unshare the user namespace.  If file is specified, then a
              persistent namespace is created by a bind mount.

       -C, --cgroup[=file]
              Unshare the cgroup namespace. If file is specified then
              persistent namespace is created by bind mount.

       -T, --time[=file]
              Unshare the time namespace. If file is specified then a
              persistent namespace is created by a bind mount. 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).

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

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

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

       -V, --version
              Display version information and exit.

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

NOTES         top

       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.

EXAMPLES         top

       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.

           # 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

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

AUTHORS         top

       Mikhail Gusarov ⟨dottedmag@dottedmag.net⟩
       Karel Zak ⟨kzak@redhat.com⟩

SEE ALSO         top

       clone(2), unshare(2), namespaces(7), mount(8)

AVAILABILITY         top

       The unshare command is part of the util-linux package and is
       available from
       https://www.kernel.org/pub/linux/utils/util-linux/.

COLOPHON         top

       This page is part of the util-linux (a random collection of Linux
       utilities) project.  Information about the project can be found
       at ⟨https://www.kernel.org/pub/linux/utils/util-linux/⟩.  If you
       have a bug report for this manual page, send it to
       util-linux@vger.kernel.org.  This page was obtained from the
       project's upstream Git repository
       ⟨git://git.kernel.org/pub/scm/utils/util-linux/util-linux.git⟩ on
       2020-12-18.  (At that time, the date of the most recent commit
       that was found in the repository was 2020-12-17.)  If you
       discover any rendering problems in this HTML version of the page,
       or you believe there is a better or more up-to-date source for
       the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original
       manual page), send a mail to man-pages@man7.org

util-linux                    February 2016                   UNSHARE(1)

Pages that refer to this page: unshare(2)cgroup_namespaces(7)ipc_namespaces(7)mount_namespaces(7)namespaces(7)network_namespaces(7)time_namespaces(7)uts_namespaces(7)findmnt(8)lsns(8)