focal (1) unshare.1.gz

Provided by: util-linux_2.34-0.1ubuntu9.6_amd64 bug

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

              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
              namespaces(7) and the discussion 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 routing tables, firewall rules, the
              /proc/net  and  /sys/class/net  directory  trees,  sockets,  etc.   For   further   details,   see
              namespaces(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 capabilities.   For  further  details,  see
              user_namespaces(7) and the discussion of the CLONE_NEWUSER flag in clone(2).

OPTIONS

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

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

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

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

       -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 solution, 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-parented
              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/.