unshare(1)



UNSHARE(1)                       User Commands                      UNSHARE(1)

NAME
       unshare - run program with some namespaces unshared from parent

SYNOPSIS
       unshare [options] [program [arguments]]

DESCRIPTION
       Unshares the indicated namespaces from the parent process and then exe-
       cutes the specified program. If program is not given, then ``${SHELL}''
       is run (default: /bin/sh).

       The  namespaces  can  optionally  be  made  persistent by bind mounting
       /proc/pid/ns/type  files  to  a  filesystem  path  and   entered   with
       nsenter(1)  even  after  the  program terminates (except PID namespaces
       where permanently running init process is required).  Once a persistent
       namespace  is  no  longer needed, it can be unpersisted with umount(8).
       See the EXAMPLES section for more details.

       The namespaces to be unshared are indicated via  options.   Unshareable
       namespaces are:

       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  de-
              tails,   see  mount_namespaces(7)  and  the  discussion  of  the
              CLONE_NEWNS flag in clone(2).

              unshare since util-linux version 2.27 automatically sets  propa-
              gation 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 namespaces(7) and the discus-
              sion of the CLONE_NEWUTS flag in clone(2).

       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  namespaces(7)
              and the discussion of the CLONE_NEWIPC flag in clone(2).

       network namespace
              The process will have independent IPv4 and IPv6 stacks, IP rout-
              ing tables, firewall rules, the /proc/net and /sys/class/net di-
              rectory  trees,  sockets,  etc.   For further details, see name-
              spaces(7)  and  the  discussion  of  the  CLONE_NEWNET  flag  in
              clone(2).

       PID namespace
              Children  will  have  a  distinct set of PID-to-process mappings
              from their parent.  For further details,  see  pid_namespaces(7)
              and the discussion of the CLONE_NEWPID flag in clone(2).

       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) and the
              discussion of the CLONE_NEWCGROUP flag in clone(2).

       user namespace
              The process will have a distinct set of UIDs, GIDs and capabili-
              ties.   For further details, see user_namespaces(7) and the dis-
              cussion of the CLONE_NEWUSER flag in clone(2).

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

       -m, --mount[=file]
              Unshare  the mount namespace.  If file is specified, then a per-
              sistent namespace is created by a bind mount.   Note  that  file
              has  to be located on a filesystem with the propagation flag set
              to private.  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 persistent
              namespace  is  created by a bind mount.  See also the --fork and
              --mount-proc options.

       -u, --uts[=file]
              Unshare the UTS namespace.  If file is specified, then a persis-
              tent namespace is created by a bind mount.

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

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

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

       --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 name-
              space 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).

       -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  net-
              work  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  --set-
              groups=deny and --user.

       -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  cre-
              ated  user  namespace.  This option implies --setgroups=deny and
              --user.

       --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  un-
              changed.   The  option  is silently ignored when the mount name-
              space (--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 restric-
              tion 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 unpriv-
              ileged 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.

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

       -h, --help
              Display help text 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 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
       # unshare --fork --pid --mount-proc readlink /proc/self
       1
              Establish a PID namespace, ensure we're PID 1 in  it  against  a
              newly mounted procfs instance.

       $ unshare --map-root-user --user sh -c whoami
       root
              Establish  a  user namespace as an unprivileged user with a root
              user within it.

       # touch /root/uts-ns
       # unshare --uts=/root/uts-ns hostname FOO
       # nsenter --uts=/root/uts-ns hostname
       FOO
       # umount /root/uts-ns
              Establish a persistent UTS namespace, and modify  the  hostname.
              The  namespace  is  then entered with nsenter.  The namespace is
              destroyed by unmounting the bind reference.

       # mount --bind /root/namespaces /root/namespaces
       # mount --make-private /root/namespaces
       # touch /root/namespaces/mnt
       # unshare --mount=/root/namespaces/mnt
              Establish a persistent mount namespace referenced  by  the  bind
              mount /root/namespaces/mnt.  This example shows a portable solu-
              tion, because it makes sure that the bind mount is created on  a
              shared filesystem.

       # unshare -pf --kill-child -- bash -c (sleep 999 &) && sleep 1000 &
       # pid=$!
       # kill $pid
              Reliable  killing  of subprocesses of the program.  When unshare
              gets killed, everything below it gets killed as  well.   Without
              it, the children of program would have orphaned and been re-par-
              ented to PID 1.

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

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

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

util-linux                       February 2016                      UNSHARE(1)

Man(1) output converted with man2html
list of all man pages