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 executes the specified program.

       The  namespaces  can optionally be persisted by bind mounting /proc/[pid]/ns/[type] files to a filesystem
       path and entered with nsenter(1) even after program terminates.  Once a persistent namespace is no longer
       needed it can be unpersisted with umount(8).  See 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  (CLONE_NEWNS  flag),
              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).

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

       UTS namespace
              Setting hostname or domainname will not affect the rest of the system.  (CLONE_NEWUTS flag)

       IPC namespace
              The process will have an independent namespace for System V message  queues,  semaphore  sets  and
              shared memory segments.  (CLONE_NEWIPC flag)

       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.  (CLONE_NEWNET flag)

       pid namespace
              Children will have a distinct set of PID to process mappings  from  their  parent.   (CLONE_NEWPID
              flag)

       user namespace
              The process will have a distinct set of UIDs, GIDs and capabilities.  (CLONE_NEWUSER flag)

       See clone(2) for the exact semantics of the flags.

OPTIONS

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

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

       -n, --net[=file]
              Unshare  the  network namespace. If file is specified then persistent namespace is created by bind
              mount.

       -p, --pid[=file]
              Unshare the pid namespace. If file is specified then  persistent  namespace  is  created  by  bind
              mount. See also the --fork and --mount-proc options.

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

       -U, --user[=file]
              Unshare the user namespace. If file is specified then persistent  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.

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

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

       --setgroups allow|deny
              Allow or deny setgroups(2) syscall in user namespaces.

              setgroups(2) is only callable with CAP_SETGID and CAP_SETGID in  a  user  namespace  (since  Linux
              3.19)  does not give you permission to call setgroups(2) until after GID map has been set. The GID
              map is writable by root when setgroups(2) is enabled and GID map becomes writable by  unprivileged
              processes when setgroups(2) is permanently disabled.

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

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

EXAMPLES

       # unshare --fork --pid --mount-proc readlink /proc/self
       1
              Establish a PID namespace, ensure we're PID 1 in it against 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 hostanme FOO
       # nsenter --uts=/root/uts-ns hostname
       FOO
       # umount /root/uts-ns
              Establish  a  persistent  UTS  namespace,  modify  hostname.  The namespace maybe later entered by
              nsenter. The namespace is destroyed by umount the bind reference.

SEE ALSO

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

AUTHORS

       Mikhail Gusarov
       Karel Zak

AVAILABILITY

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

util-linux                                          July 2014                                         UNSHARE(1)