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