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 \fBEXAMPLE\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 uts_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 ipc_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 network_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 For further details, see
 115 .BR time_namespaces (7).
 116 .SH OPTIONS
 117 .TP
 118 .BR \-i , " \-\-ipc" [ =\fIfile ]
 119 Unshare the IPC namespace.  If \fIfile\fP is specified, then a persistent
 120 namespace is created by a bind mount.
 121 .TP
 122 .BR \-m , " \-\-mount" [ =\fIfile ]
 123 Unshare the mount namespace.  If \fIfile\fP is specified, then a persistent
 124 namespace is created by a bind mount.
 125 Note that \fIfile\fP has to be located on a filesystem with the propagation
 126 flag set to \fBprivate\fP.  Use the command \fBfindmnt \-o+PROPAGATION\fP
 127 when not sure about the current setting.  See also the examples below.
 128 .TP
 129 .BR \-n , " \-\-net" [ =\fIfile ]
 130 Unshare the network namespace.  If \fIfile\fP is specified, then a persistent
 131 namespace is created by a bind mount.
 132 .TP
 133 .BR \-p , " \-\-pid" [ =\fIfile ]
 134 Unshare the PID namespace.  If \fIfile\fP is specified then persistent
 135 namespace is created by a bind mount.  See also the \fB\-\-fork\fP and
 136 \fB\-\-mount-proc\fP options.
 137 .TP
 138 .BR \-u , " \-\-uts" [ =\fIfile ]
 139 Unshare the UTS namespace.  If \fIfile\fP is specified, then a persistent
 140 namespace is created by a bind mount.
 141 .TP
 142 .BR \-U , " \-\-user" [ =\fIfile ]
 143 Unshare the user namespace.  If \fIfile\fP is specified, then a persistent
 144 namespace is created by a bind mount.
 145 .TP
 146 .BR \-C , " \-\-cgroup"[=\fIfile\fP]
 147 Unshare the cgroup namespace. If \fIfile\fP is specified then persistent namespace is created
 148 by bind mount.
 149 .TP
 150 .BR \-T , " \-\-time"[=\fIfile\fP]
 151 Unshare the time namespace. If \fIfile\fP is specified then a persistent
 152 namespace is created by a bind mount. The \fB\-\-monotonic\fP and
 153 \fB\-\-boottime\fP options can be used to specify the corresponding
 154 offset in the time namespace.
 155 .TP
 156 .BR \-f , " \-\-fork"
 157 Fork the specified \fIprogram\fR as a child process of \fBunshare\fR rather than
 158 running it directly.  This is useful when creating a new PID namespace.
 159 .TP
 160 .B \-\-keep\-caps
 161 When the \fB\-\-user\fP option is given, ensure that capabilities granted
 162 in the user namespace are preserved in the child process.
 163 .TP
 164 .BR \-\-kill\-child [ =\fIsigname ]
 165 When \fBunshare\fR terminates, have \fIsigname\fP be sent to the forked child process.
 166 Combined with \fB\-\-pid\fR this allows for an easy and reliable killing of the entire
 167 process tree below \fBunshare\fR.
 168 If not given, \fIsigname\fP defaults to \fBSIGKILL\fR.
 169 This option implies \fB\-\-fork\fR.
 170 .TP
 171 .BR \-\-mount\-proc [ =\fImountpoint ]
 172 Just before running the program, mount the proc filesystem at \fImountpoint\fP
 173 (default is /proc).  This is useful when creating a new PID namespace.  It also
 174 implies creating a new mount namespace since the /proc mount would otherwise
 175 mess up existing programs on the system.  The new proc filesystem is explicitly
 176 mounted as private (with MS_PRIVATE|MS_REC).
 177 .TP
 178 .BI \-\-map\-user= uid|name
 179 Run the program only after the current effective user ID has been mapped to \fIuid\fP.
 180 If this option is specified multiple times, the last occurrence takes precedence.
 181 This option implies \fB\-\-user\fR.
 182 .TP
 183 .BI \-\-map\-group= gid|name
 184 Run the program only after the current effective group ID has been mapped to \fIgid\fP.
 185 If this option is specified multiple times, the last occurrence takes precedence.
 186 This option implies \fB\-\-setgroups=deny\fR and \fB\-\-user\fR.
 187 .TP
 188 .BR \-r , " \-\-map\-root\-user"
 189 Run the program only after the current effective user and group IDs have been mapped to
 190 the superuser UID and GID in the newly created user namespace.  This makes it possible to
 191 conveniently gain capabilities needed to manage various aspects of the newly created
 192 namespaces (such as configuring interfaces in the network namespace or mounting filesystems in
 193 the mount namespace) even when run unprivileged.  As a mere convenience feature, it does not support
 194 more sophisticated use cases, such as mapping multiple ranges of UIDs and GIDs.
 195 This option implies \fB\-\-setgroups=deny\fR and \fB\-\-user\fR.
 196 This option is equivalent to \fB\-\-map-user=0 \-\-map-group=0\fR.
 197 .TP
 198 .BR \-c , " \-\-map\-current\-user"
 199 Run the program only after the current effective user and group IDs have been mapped to
 200 the same UID and GID in the newly created user namespace. This option implies
 201 \fB\-\-setgroups=deny\fR and \fB\-\-user\fR.
 202 This option is equivalent to \fB\-\-map-user=$(id -ru) \-\-map-group=$(id -rg)\fR.
 203 .TP
 204 .BR "\-\-propagation private" | shared | slave | unchanged
 205 Recursively set the mount propagation flag in the new mount namespace.  The default
 206 is to set the propagation to \fIprivate\fP.  It is possible to disable this feature
 207 with the argument \fBunchanged\fR.  The option is silently ignored when the mount
 208 namespace (\fB\-\-mount\fP) is not requested.
 209 .TP
 210 .BR "\-\-setgroups allow" | deny
 211 Allow or deny the
 212 .BR setgroups (2)
 213 system call in a user namespace.
 214 .sp
 215 To be able to call
 216 .BR setgroups (2),
 217 the calling process must at least have CAP_SETGID.
 218 But since Linux 3.19 a further restriction applies:
 219 the kernel gives permission to call
 220 .BR \%setgroups (2)
 221 only after the GID map (\fB/proc/\fIpid\fB/gid_map\fR) has been set.
 222 The GID map is writable by root when
 223 .BR \%setgroups (2)
 224 is enabled (i.e., \fBallow\fR, the default), and
 225 the GID map becomes writable by unprivileged processes when
 226 .BR \%setgroups (2)
 227 is permanently disabled (with \fBdeny\fR).
 228 .TP
 229 .BR \-R, "\-\-root=\fIdir"
 230 run the command with root directory set to \fIdir\fP.
 231 .TP
 232 .BR \-w, "\-\-wd=\fIdir"
 233 change working directory to \fIdir\fP.
 234 .TP
 235 .BR \-S, "\-\-setuid \fIuid"
 236 Set the user ID which will be used in the entered namespace.
 237 .TP
 238 .BR \-G, "\-\-setgid \fIgid"
 239 Set the group ID which will be used in the entered namespace and drop
 240 supplementary groups.
 241 .TP
 242 .BI \-\-monotonic " offset"
 243 Set the offset of
 244 .B CLOCK_MONOTONIC
 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 .BI \-\-boottime " offset"
 249 Set the offset of
 250 .B CLOCK_BOOTTIME
 251 which will be used in the entered time namespace. This option requires
 252 unsharing a time namespace with \fB\-\-time\fP.
 253 .TP
 254 .BR \-V , " \-\-version"
 255 Display version information and exit.
 256 .TP
 257 .BR \-h , " \-\-help"
 258 Display help text and exit.
 259 .SH NOTES
 260 The proc and sysfs filesystems mounting as root in a user namespace have to be
 261 restricted so that a less privileged user can not get more access to sensitive
 262 files that a more privileged user made unavailable. In short the rule for proc
 263 and sysfs is as close to a bind mount as possible.
 264 .SH EXAMPLE
 265 .TP
 266 .B # unshare \-\-fork \-\-pid \-\-mount-proc readlink /proc/self
 267 .TQ
 268 1
 269 .br
 270 Establish a PID namespace, ensure we're PID 1 in it against a newly mounted
 271 procfs instance.
 272 .TP
 273 .B $ unshare \-\-map-root-user \-\-user sh \-c whoami
 274 .TQ
 275 root
 276 .br
 277 Establish a user namespace as an unprivileged user with a root user within it.
 278 .TP
 279 .B # touch /root/uts-ns
 280 .TQ
 281 .B # unshare \-\-uts=/root/uts-ns hostname FOO
 282 .TQ
 283 .B # nsenter \-\-uts=/root/uts-ns hostname
 284 .TQ
 285 FOO
 286 .TQ
 287 .B # umount /root/uts-ns
 288 .br
 289 Establish a persistent UTS namespace, and modify the hostname.  The namespace
 290 is then entered with \fBnsenter\fR.  The namespace is destroyed by unmounting
 291 the bind reference.
 292 .TP
 293 .B # mount \-\-bind /root/namespaces /root/namespaces
 294 .TQ
 295 .B # mount \-\-make-private /root/namespaces
 296 .TQ
 297 .B # touch /root/namespaces/mnt
 298 .TQ
 299 .B # unshare \-\-mount=/root/namespaces/mnt
 300 .br
 301 Establish a persistent mount namespace referenced by the bind mount
 302 /root/namespaces/mnt.  This example shows a portable solution, because it
 303 makes sure that the bind mount is created on a shared filesystem.
 304 .TP
 305 .B # unshare \-pf \-\-kill-child \-\- bash \-c "(sleep 999 &) && sleep 1000" &
 306 .TQ
 307 .B # pid=$!
 308 .TQ
 309 .B # kill $pid
 310 .br
 311 Reliable killing of subprocesses of the \fIprogram\fR.
 312 When \fBunshare\fR gets killed, everything below it gets killed as well.
 313 Without it, the children of \fIprogram\fR would have orphaned and
 314 been re-parented to PID 1.
 315 .TP
 316 .B # unshare \-\-fork \-\-time \-\-boottime 100000000 uptime
 317 .TQ
 318  10:58:48 up 1158 days,  6:05,  1 user,  load average: 0.00, 0.00, 0.00
 319
 320 .SH AUTHORS
 321 .UR dottedmag@dottedmag.net
 322 Mikhail Gusarov
 323 .UE
 324 .br
 325 .UR kzak@redhat.com
 326 Karel Zak
 327 .UE
 328 .SH SEE ALSO
 329 .BR clone (2),
 330 .BR unshare (2),
 331 .BR namespaces (7),
 332 .BR mount (8)
 333 .SH AVAILABILITY
 334 The unshare command is part of the util-linux package and is available from
 335 https://www.kernel.org/pub/linux/utils/util-linux/.