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