sys-utils/unshare.1

   1 .TH UNSHARE 1 "February 2016" "util-linux" "User Commands"
   2 .SH NAME
   3 unshare \- run program with some namespaces unshared from parent
   4 .SH SYNOPSIS
   5 .B unshare
   6 [options]
   7 .RI [ program
   8 .RI [ arguments ]]
   9 .SH DESCRIPTION
  10 Unshares the indicated namespaces from the parent process and then executes
  11 the specified \fIprogram\fR. If \fIprogram\fR is not given, then ``${SHELL}'' is
  12 run (default: /bin/sh).
  13 .PP
  14 The namespaces can optionally be made persistent by bind mounting
  15 /proc/\fIpid\fR/ns/\fItype\fR files to a filesystem path and entered with
  16 .BR \%nsenter (1)
  17 even after the \fIprogram\fR terminates.
  18 Once a persistent \%namespace is no longer needed, it can be unpersisted with
  19 .BR umount (8).
  20 See the \fBEXAMPLES\fR section for more details.
  21 .PP
  22 The namespaces to be unshared are indicated via options.  Unshareable namespaces are:
  23 .TP
  24 .BR "mount namespace"
  25 Mounting and unmounting filesystems will not affect the rest of the system,
  26 except for filesystems which are explicitly marked as
  27 shared (with \fBmount --make-shared\fP; see \fI/proc/self/mountinfo\fP or
  28 \fBfindmnt -o+PROPAGATION\fP for the \fBshared\fP flags).
  29 For further details, see
  30 .BR mount_namespaces (7)
  31 and the discussion of the
  32 .BR CLONE_NEWNS
  33 flag in
  34 .BR clone (2).
  35 .sp
  36 .B unshare
  37 since util-linux version 2.27 automatically sets propagation to \fBprivate\fP
  38 in a new mount namespace to make sure that the new namespace is really
  39 unshared.  It's possible to disable this feature with option
  40 \fB\-\-propagation unchanged\fP.
  41 Note that \fBprivate\fP is the kernel default.
  42 .TP
  43 .BR "UTS namespace"
  44 Setting hostname or domainname will not affect the rest of the system.
  45 For further details, see
  46 .BR namespaces (7)
  47 and the discussion of the
  48 .BR CLONE_NEWUTS
  49 flag in
  50 .BR clone (2).
  51 .TP
  52 .BR "IPC namespace"
  53 The process will have an independent namespace for POSIX message queues
  54 as well as System V \%message queues,
  55 semaphore sets and shared memory segments.
  56 For further details, see
  57 .BR namespaces (7)
  58 and the discussion of the
  59 .BR CLONE_NEWIPC
  60 flag in
  61 .BR clone (2).
  62 .TP
  63 .BR "network namespace"
  64 The process will have independent IPv4 and IPv6 stacks, IP routing tables,
  65 firewall rules, the \fI/proc/net\fP and \fI/sys/class/net\fP directory trees,
  66 sockets, etc.
  67 For further details, see
  68 .BR namespaces (7)
  69 and the discussion of the
  70 .BR CLONE_NEWNET
  71 flag in
  72 .BR clone (2).
  73 .TP
  74 .BR "PID namespace"
  75 Children will have a distinct set of PID-to-process mappings from their parent.
  76 For further details, see
  77 .BR pid_namespaces (7)
  78 and
  79 the discussion of the
  80 .BR CLONE_NEWPID
  81 flag in
  82 .BR clone (2).
  83 .TP
  84 .BR "cgroup namespace"
  85 The process will have a virtualized view of \fI/proc\:/self\:/cgroup\fP, and new
  86 cgroup mounts will be rooted at the namespace cgroup root.
  87 For further details, see
  88 .BR cgroup_namespaces (7)
  89 and the discussion of the
  90 .BR CLONE_NEWCGROUP
  91 flag in
  92 .BR clone (2).
  93 .TP
  94 .BR "user namespace"
  95 The process will have a distinct set of UIDs, GIDs and capabilities.
  96 For further details, see
  97 .BR user_namespaces (7)
  98 and the discussion of the
  99 .BR CLONE_NEWUSER
 100 flag in
 101 .BR clone (2).
 102 .SH OPTIONS
 103 .TP
 104 .BR \-i , " \-\-ipc" [ =\fIfile ]
 105 Unshare the IPC namespace.  If \fIfile\fP is specified, then a persistent
 106 namespace is created by a bind mount.
 107 .TP
 108 .BR \-m , " \-\-mount" [ =\fIfile ]
 109 Unshare the mount namespace.  If \fIfile\fP is specified, then a persistent
 110 namespace is created by a bind mount.
 111 Note that \fIfile\fP has to be located on a filesystem with the propagation
 112 flag set to \fBprivate\fP.  Use the command \fBfindmnt -o+PROPAGATION\fP
 113 when not sure about the current setting.  See also the examples below.
 114 .TP
 115 .BR \-n , " \-\-net" [ =\fIfile ]
 116 Unshare the network namespace.  If \fIfile\fP is specified, then a persistent
 117 namespace is created by a bind mount.
 118 .TP
 119 .BR \-p , " \-\-pid" [ =\fIfile ]
 120 Unshare the PID namespace.  If \fIfile\fP is specified then persistent
 121 namespace is created by a bind mount.  See also the \fB--fork\fP and
 122 \fB--mount-proc\fP options.
 123 .TP
 124 .BR \-u , " \-\-uts" [ =\fIfile ]
 125 Unshare the UTS namespace.  If \fIfile\fP is specified, then a persistent
 126 namespace is created by a bind mount.
 127 .TP
 128 .BR \-U , " \-\-user" [ =\fIfile ]
 129 Unshare the user namespace.  If \fIfile\fP is specified, then a persistent
 130 namespace is created by a bind mount.
 131 .TP
 132 .BR \-C , " \-\-cgroup"[=\fIfile\fP]
 133 Unshare the cgroup namespace. If \fIfile\fP is specified then persistent namespace is created
 134 by bind mount.
 135 .TP
 136 .BR \-f , " \-\-fork"
 137 Fork the specified \fIprogram\fR as a child process of \fBunshare\fR rather than
 138 running it directly.  This is useful when creating a new PID namespace.
 139 .TP
 140 .BR \-\-mount\-proc [ =\fImountpoint ]
 141 Just before running the program, mount the proc filesystem at \fImountpoint\fP
 142 (default is /proc).  This is useful when creating a new PID namespace.  It also
 143 implies creating a new mount namespace since the /proc mount would otherwise
 144 mess up existing programs on the system.  The new proc filesystem is explicitly
 145 mounted as private (with MS_PRIVATE|MS_REC).
 146 .TP
 147 .BR \-r , " \-\-map\-root\-user"
 148 Run the program only after the current effective user and group IDs have been mapped to
 149 the superuser UID and GID in the newly created user namespace.  This makes it possible to
 150 conveniently gain capabilities needed to manage various aspects of the newly created
 151 namespaces (such as configuring interfaces in the network namespace or mounting filesystems in
 152 the mount namespace) even when run unprivileged.  As a mere convenience feature, it does not support
 153 more sophisticated use cases, such as mapping multiple ranges of UIDs and GIDs.
 154 This option implies \fB--setgroups=deny\fR.
 155 .TP
 156 .BR "\-\-propagation private" | shared | slave | unchanged
 157 Recursively set the mount propagation flag in the new mount namespace.  The default
 158 is to set the propagation to \fIprivate\fP.  It is possible to disable this feature
 159 with the argument \fBunchanged\fR.  The option is silently ignored when the mount
 160 namespace (\fB\-\-mount\fP) is not requested.
 161 .TP
 162 .BR "\-\-setgroups allow" | deny
 163 Allow or deny the
 164 .BR setgroups (2)
 165 system call in a user namespace.
 166 .sp
 167 To be able to call
 168 .BR setgroups (2),
 169 the calling process must at least have CAP_SETGID.
 170 But since Linux 3.19 a further restriction applies:
 171 the kernel gives permission to call
 172 .BR \%setgroups (2)
 173 only after the GID map (\fB/proc/\fIpid\fB/gid_map\fR) has been set.
 174 The GID map is writable by root when
 175 .BR \%setgroups (2)
 176 is enabled (i.e. \fBallow\fR, the default), and
 177 the GID map becomes writable by unprivileged processes when
 178 .BR \%setgroups (2)
 179 is permanently disabled (with \fBdeny\fR).
 180 .TP
 181 .BR \-V , " \-\-version"
 182 Display version information and exit.
 183 .TP
 184 .BR \-h , " \-\-help"
 185 Display help text and exit.
 186 .SH EXAMPLES
 187 .TP
 188 .B # unshare --fork --pid --mount-proc readlink /proc/self
 189 .TQ
 190 1
 191 .br
 192 Establish a PID namespace, ensure we're PID 1 in it against a newly mounted
 193 procfs instance.
 194 .TP
 195 .B $ unshare --map-root-user --user sh -c whoami
 196 .TQ
 197 root
 198 .br
 199 Establish a user namespace as an unprivileged user with a root user within it.
 200 .TP
 201 .B # touch /root/uts-ns
 202 .TQ
 203 .B # unshare --uts=/root/uts-ns hostname FOO
 204 .TQ
 205 .B # nsenter --uts=/root/uts-ns hostname
 206 .TQ
 207 FOO
 208 .TQ
 209 .B # umount /root/uts-ns
 210 .br
 211 Establish a persistent UTS namespace, and modify the hostname.  The namespace
 212 is then entered with \fBnsenter\fR.  The namespace is destroyed by unmounting
 213 the bind reference.
 214 .TP
 215 .B # mount --bind /root/namespaces /root/namespaces
 216 .TQ
 217 .B # mount --make-private /root/namespaces
 218 .TQ
 219 .B # touch /root/namespaces/mnt
 220 .TQ
 221 .B # unshare --mount=/root/namespaces/mnt
 222 .br
 223 Establish a persistent mount namespace referenced by the bind mount
 224 /root/namespaces/mnt.  This example shows a portable solution, because it
 225 makes sure that the bind mount is created on a shared filesystem.
 226
 227 .SH SEE ALSO
 228 .BR clone (2),
 229 .BR unshare (2),
 230 .BR namespaces (7),
 231 .BR mount (8)
 232 .SH AUTHORS
 233 .UR dottedmag@dottedmag.net
 234 Mikhail Gusarov
 235 .UE
 236 .br
 237 .UR kzak@redhat.com
 238 Karel Zak
 239 .UE
 240 .SH AVAILABILITY
 241 The unshare command is part of the util-linux package and is available from
 242 https://www.kernel.org/pub/linux/utils/util-linux/.