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 (except PID namespaces where
  18 permanently running init process is required).
  19 Once a persistent \%namespace is no longer needed, it can be unpersisted with
  20 .BR umount (8).
  21 See the \fBEXAMPLES\fR section for more details.
  22 .PP
  23 The namespaces to be unshared are indicated via options.  Unshareable namespaces are:
  24 .TP
  25 .B mount namespace
  26 Mounting and unmounting filesystems will not affect the rest of the system,
  27 except for filesystems which are explicitly marked as
  28 shared (with \fBmount \-\-make-shared\fP; see \fI/proc/self/mountinfo\fP or
  29 \fBfindmnt \-o+PROPAGATION\fP for the \fBshared\fP flags).
  30 For further details, see
  31 .BR mount_namespaces (7)
  32 and the discussion of the
  33 .B CLONE_NEWNS
  34 flag in
  35 .BR clone (2).
  36 .sp
  37 .B unshare
  38 since util-linux version 2.27 automatically sets propagation to \fBprivate\fP
  39 in a new mount namespace to make sure that the new namespace is really
  40 unshared.  It's possible to disable this feature with option
  41 \fB\-\-propagation unchanged\fP.
  42 Note that \fBprivate\fP is the kernel default.
  43 .TP
  44 .B UTS namespace
  45 Setting hostname or domainname will not affect the rest of the system.
  46 For further details, see
  47 .BR namespaces (7)
  48 and the discussion of the
  49 .B CLONE_NEWUTS
  50 flag in
  51 .BR clone (2).
  52 .TP
  53 .B IPC namespace
  54 The process will have an independent namespace for POSIX message queues
  55 as well as System V \%message queues,
  56 semaphore sets and shared memory segments.
  57 For further details, see
  58 .BR namespaces (7)
  59 and the discussion of the
  60 .B CLONE_NEWIPC
  61 flag in
  62 .BR clone (2).
  63 .TP
  64 .B network namespace
  65 The process will have independent IPv4 and IPv6 stacks, IP routing tables,
  66 firewall rules, the \fI/proc/net\fP and \fI/sys/class/net\fP directory trees,
  67 sockets, etc.
  68 For further details, see
  69 .BR namespaces (7)
  70 and the discussion of the
  71 .B CLONE_NEWNET
  72 flag in
  73 .BR clone (2).
  74 .TP
  75 .B PID namespace
  76 Children will have a distinct set of PID-to-process mappings from their parent.
  77 For further details, see
  78 .BR pid_namespaces (7)
  79 and
  80 the discussion of the
  81 .B CLONE_NEWPID
  82 flag in
  83 .BR clone (2).
  84 .TP
  85 .B cgroup namespace
  86 The process will have a virtualized view of \fI/proc\:/self\:/cgroup\fP, and new
  87 cgroup mounts will be rooted at the namespace cgroup root.
  88 For further details, see
  89 .BR cgroup_namespaces (7)
  90 and the discussion of the
  91 .B CLONE_NEWCGROUP
  92 flag in
  93 .BR clone (2).
  94 .TP
  95 .B user namespace
  96 The process will have a distinct set of UIDs, GIDs and capabilities.
  97 For further details, see
  98 .BR user_namespaces (7)
  99 and the discussion of the
 100 .B CLONE_NEWUSER
 101 flag in
 102 .BR clone (2).
 103 .TP
 104 .B time namespace
 105 The process can have a distinct view of
 106 .B CLOCK_MONOTONIC
 107 and/or
 108 .B CLOCK_BOOTTIME
 109 which can be changed using \fI/proc/self/timens_offsets\fP.
 110 .SH OPTIONS
 111 .TP
 112 .BR \-i , " \-\-ipc" [ =\fIfile ]
 113 Unshare the IPC namespace.  If \fIfile\fP is specified, then a persistent
 114 namespace is created by a bind mount.
 115 .TP
 116 .BR \-m , " \-\-mount" [ =\fIfile ]
 117 Unshare the mount namespace.  If \fIfile\fP is specified, then a persistent
 118 namespace is created by a bind mount.
 119 Note that \fIfile\fP has to be located on a filesystem with the propagation
 120 flag set to \fBprivate\fP.  Use the command \fBfindmnt \-o+PROPAGATION\fP
 121 when not sure about the current setting.  See also the examples below.
 122 .TP
 123 .BR \-n , " \-\-net" [ =\fIfile ]
 124 Unshare the network namespace.  If \fIfile\fP is specified, then a persistent
 125 namespace is created by a bind mount.
 126 .TP
 127 .BR \-p , " \-\-pid" [ =\fIfile ]
 128 Unshare the PID namespace.  If \fIfile\fP is specified then persistent
 129 namespace is created by a bind mount.  See also the \fB\-\-fork\fP and
 130 \fB\-\-mount-proc\fP options.
 131 .TP
 132 .BR \-u , " \-\-uts" [ =\fIfile ]
 133 Unshare the UTS namespace.  If \fIfile\fP is specified, then a persistent
 134 namespace is created by a bind mount.
 135 .TP
 136 .BR \-U , " \-\-user" [ =\fIfile ]
 137 Unshare the user namespace.  If \fIfile\fP is specified, then a persistent
 138 namespace is created by a bind mount.
 139 .TP
 140 .BR \-C , " \-\-cgroup"[=\fIfile\fP]
 141 Unshare the cgroup namespace. If \fIfile\fP is specified then persistent namespace is created
 142 by bind mount.
 143 .TP
 144 .BR \-T , " \-\-time"[=\fIfile\fP]
 145 Unshare the time namespace. If \fIfile\fP is specified then a persistent
 146 namespace is created by a bind mount. The \fB\-\-monotonic\fP and
 147 \fB\-\-boottime\fP options can be used to specify the corresponding
 148 offset in the time namespace.
 149 .TP
 150 .BR \-f , " \-\-fork"
 151 Fork the specified \fIprogram\fR as a child process of \fBunshare\fR rather than
 152 running it directly.  This is useful when creating a new PID namespace.
 153 .TP
 154 .B \-\-keep\-caps
 155 When the \fB\-\-user\fP option is given, ensure that capabilities granted
 156 in the user namespace are preserved in the child process.
 157 .TP
 158 .BR \-\-kill\-child [ =\fIsigname ]
 159 When \fBunshare\fR terminates, have \fIsigname\fP be sent to the forked child process.
 160 Combined with \fB\-\-pid\fR this allows for an easy and reliable killing of the entire
 161 process tree below \fBunshare\fR.
 162 If not given, \fIsigname\fP defaults to \fBSIGKILL\fR.
 163 This option implies \fB\-\-fork\fR.
 164 .TP
 165 .BR \-\-mount\-proc [ =\fImountpoint ]
 166 Just before running the program, mount the proc filesystem at \fImountpoint\fP
 167 (default is /proc).  This is useful when creating a new PID namespace.  It also
 168 implies creating a new mount namespace since the /proc mount would otherwise
 169 mess up existing programs on the system.  The new proc filesystem is explicitly
 170 mounted as private (with MS_PRIVATE|MS_REC).
 171 .TP
 172 .BR \-\-map\-user=\fIuid
 173 Run the program only after the current effective user ID has been mapped to \fIuid\fP.
 174 If this option is specified multiple times, the last occurrence takes precedence.
 175 This option implies \fB\-\-user\fR.
 176 .TP
 177 .BR \-\-map\-group=\fIgid
 178 Run the program only after the current effective group ID has been mapped to \fIgid\fP.
 179 If this option is specified multiple times, the last occurrence takes precedence.
 180 This option implies \fB\-\-setgroups=deny\fR and \fB\-\-user\fR.
 181 .TP
 182 .BR \-r , " \-\-map\-root\-user"
 183 Run the program only after the current effective user and group IDs have been mapped to
 184 the superuser UID and GID in the newly created user namespace.  This makes it possible to
 185 conveniently gain capabilities needed to manage various aspects of the newly created
 186 namespaces (such as configuring interfaces in the network namespace or mounting filesystems in
 187 the mount namespace) even when run unprivileged.  As a mere convenience feature, it does not support
 188 more sophisticated use cases, such as mapping multiple ranges of UIDs and GIDs.
 189 This option implies \fB\-\-setgroups=deny\fR and \fB\-\-user\fR.
 190 This option is equivalent to \fB\-\-map-user=0 \-\-map-group=0\fR.
 191 .TP
 192 .BR \-c , " \-\-map\-current\-user"
 193 Run the program only after the current effective user and group IDs have been mapped to
 194 the same UID and GID in the newly created user namespace. This option implies
 195 \fB\-\-setgroups=deny\fR and \fB\-\-user\fR.
 196 This option is equivalent to \fB\-\-map-user=$(id -ru) \-\-map-group=$(id -rg)\fR.
 197 .TP
 198 .BR "\-\-propagation private" | shared | slave | unchanged
 199 Recursively set the mount propagation flag in the new mount namespace.  The default
 200 is to set the propagation to \fIprivate\fP.  It is possible to disable this feature
 201 with the argument \fBunchanged\fR.  The option is silently ignored when the mount
 202 namespace (\fB\-\-mount\fP) is not requested.
 203 .TP
 204 .BR "\-\-setgroups allow" | deny
 205 Allow or deny the
 206 .BR setgroups (2)
 207 system call in a user namespace.
 208 .sp
 209 To be able to call
 210 .BR setgroups (2),
 211 the calling process must at least have CAP_SETGID.
 212 But since Linux 3.19 a further restriction applies:
 213 the kernel gives permission to call
 214 .BR \%setgroups (2)
 215 only after the GID map (\fB/proc/\fIpid\fB/gid_map\fR) has been set.
 216 The GID map is writable by root when
 217 .BR \%setgroups (2)
 218 is enabled (i.e., \fBallow\fR, the default), and
 219 the GID map becomes writable by unprivileged processes when
 220 .BR \%setgroups (2)
 221 is permanently disabled (with \fBdeny\fR).
 222 .TP
 223 .BR \-R, "\-\-root=\fIdir"
 224 run the command with root directory set to \fIdir\fP.
 225 .TP
 226 .BR \-w, "\-\-wd=\fIdir"
 227 change working directory to \fIdir\fP.
 228 .TP
 229 .BR \-S, "\-\-setuid \fIuid"
 230 Set the user ID which will be used in the entered namespace.
 231 .TP
 232 .BR \-G, "\-\-setgid \fIgid"
 233 Set the group ID which will be used in the entered namespace and drop
 234 supplementary groups.
 235 .TP
 236 .BR "\-\-monotonic \fIoffset"
 237 Set the offset of
 238 .B CLOCK_MONOTONIC
 239 which will be used in the entered time namespace. This option requires
 240 unsharing a time namespace with \fB\-\-time\fP.
 241 .TP
 242 .BR "\-\-boottime \fIoffset"
 243 Set the offset of
 244 .B CLOCK_BOOTTIME
 245 which will be used in the entered time namespace. This option requires
 246 unsharing a time namespace with \fB\-\-time\fP.
 247 .TP
 248 .BR \-V , " \-\-version"
 249 Display version information and exit.
 250 .TP
 251 .BR \-h , " \-\-help"
 252 Display help text and exit.
 253 .SH NOTES
 254 The proc and sysfs filesystems mounting as root in a user namespace have to be
 255 restricted so that a less privileged user can not get more access to sensitive
 256 files that a more privileged user made unavailable. In short the rule for proc
 257 and sysfs is as close to a bind mount as possible.
 258 .SH EXAMPLES
 259 .TP
 260 .B # unshare \-\-fork \-\-pid \-\-mount-proc readlink /proc/self
 261 .TQ
 262 1
 263 .br
 264 Establish a PID namespace, ensure we're PID 1 in it against a newly mounted
 265 procfs instance.
 266 .TP
 267 .B $ unshare \-\-map-root-user \-\-user sh \-c whoami
 268 .TQ
 269 root
 270 .br
 271 Establish a user namespace as an unprivileged user with a root user within it.
 272 .TP
 273 .B # touch /root/uts-ns
 274 .TQ
 275 .B # unshare \-\-uts=/root/uts-ns hostname FOO
 276 .TQ
 277 .B # nsenter \-\-uts=/root/uts-ns hostname
 278 .TQ
 279 FOO
 280 .TQ
 281 .B # umount /root/uts-ns
 282 .br
 283 Establish a persistent UTS namespace, and modify the hostname.  The namespace
 284 is then entered with \fBnsenter\fR.  The namespace is destroyed by unmounting
 285 the bind reference.
 286 .TP
 287 .B # mount \-\-bind /root/namespaces /root/namespaces
 288 .TQ
 289 .B # mount \-\-make-private /root/namespaces
 290 .TQ
 291 .B # touch /root/namespaces/mnt
 292 .TQ
 293 .B # unshare \-\-mount=/root/namespaces/mnt
 294 .br
 295 Establish a persistent mount namespace referenced by the bind mount
 296 /root/namespaces/mnt.  This example shows a portable solution, because it
 297 makes sure that the bind mount is created on a shared filesystem.
 298 .TP
 299 .B # unshare \-pf \-\-kill-child \-\- bash \-c "(sleep 999 &) && sleep 1000" &
 300 .TQ
 301 .B # pid=$!
 302 .TQ
 303 .B # kill $pid
 304 .br
 305 Reliable killing of subprocesses of the \fIprogram\fR.
 306 When \fBunshare\fR gets killed, everything below it gets killed as well.
 307 Without it, the children of \fIprogram\fR would have orphaned and
 308 been re-parented to PID 1.
 309 .TP
 310 .B # unshare \-\-fork \-\-time \-\-boottime 100000000 uptime
 311 .TQ
 312  10:58:48 up 1158 days,  6:05,  1 user,  load average: 0.00, 0.00, 0.00
 313
 314 .SH SEE ALSO
 315 .BR clone (2),
 316 .BR unshare (2),
 317 .BR namespaces (7),
 318 .BR mount (8)
 319 .SH AUTHORS
 320 .UR dottedmag@dottedmag.net
 321 Mikhail Gusarov
 322 .UE
 323 .br
 324 .UR kzak@redhat.com
 325 Karel Zak
 326 .UE
 327 .SH AVAILABILITY
 328 The unshare command is part of the util-linux package and is available from
 329 https://www.kernel.org/pub/linux/utils/util-linux/.