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 .SH OPTIONS
 104 .TP
 105 .BR \-i , " \-\-ipc" [ =\fIfile ]
 106 Unshare the IPC namespace.  If \fIfile\fP is specified, then a persistent
 107 namespace is created by a bind mount.
 108 .TP
 109 .BR \-m , " \-\-mount" [ =\fIfile ]
 110 Unshare the mount namespace.  If \fIfile\fP is specified, then a persistent
 111 namespace is created by a bind mount.
 112 Note that \fIfile\fP has to be located on a filesystem with the propagation
 113 flag set to \fBprivate\fP.  Use the command \fBfindmnt \-o+PROPAGATION\fP
 114 when not sure about the current setting.  See also the examples below.
 115 .TP
 116 .BR \-n , " \-\-net" [ =\fIfile ]
 117 Unshare the network namespace.  If \fIfile\fP is specified, then a persistent
 118 namespace is created by a bind mount.
 119 .TP
 120 .BR \-p , " \-\-pid" [ =\fIfile ]
 121 Unshare the PID namespace.  If \fIfile\fP is specified then persistent
 122 namespace is created by a bind mount.  See also the \fB\-\-fork\fP and
 123 \fB\-\-mount-proc\fP options.
 124 .TP
 125 .BR \-u , " \-\-uts" [ =\fIfile ]
 126 Unshare the UTS namespace.  If \fIfile\fP is specified, then a persistent
 127 namespace is created by a bind mount.
 128 .TP
 129 .BR \-U , " \-\-user" [ =\fIfile ]
 130 Unshare the user namespace.  If \fIfile\fP is specified, then a persistent
 131 namespace is created by a bind mount.
 132 .TP
 133 .BR \-C , " \-\-cgroup"[=\fIfile\fP]
 134 Unshare the cgroup namespace. If \fIfile\fP is specified then persistent namespace is created
 135 by bind mount.
 136 .TP
 137 .BR \-f , " \-\-fork"
 138 Fork the specified \fIprogram\fR as a child process of \fBunshare\fR rather than
 139 running it directly.  This is useful when creating a new PID namespace.
 140 .TP
 141 .B \-\-keep\-caps
 142 When the \fB\-\-user\fP option is given, ensure that capabilities granted
 143 in the user namespace are preserved in the child process.
 144 .TP
 145 .BR \-\-kill\-child [ =\fIsigname ]
 146 When \fBunshare\fR terminates, have \fIsigname\fP be sent to the forked child process.
 147 Combined with \fB\-\-pid\fR this allows for an easy and reliable killing of the entire
 148 process tree below \fBunshare\fR.
 149 If not given, \fIsigname\fP defaults to \fBSIGKILL\fR.
 150 This option implies \fB\-\-fork\fR.
 151 .TP
 152 .BR \-\-mount\-proc [ =\fImountpoint ]
 153 Just before running the program, mount the proc filesystem at \fImountpoint\fP
 154 (default is /proc).  This is useful when creating a new PID namespace.  It also
 155 implies creating a new mount namespace since the /proc mount would otherwise
 156 mess up existing programs on the system.  The new proc filesystem is explicitly
 157 mounted as private (with MS_PRIVATE|MS_REC).
 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 .TP
 168 .BR \-c , " \-\-map\-current\-user"
 169 Run the program only after the current effective user and group IDs have been mapped to
 170 the same UID and GID in the newly created user namespace. This option implies
 171 \fB\-\-setgroups=deny\fR and \fB\-\-user\fR.
 172 .TP
 173 .BR "\-\-propagation private" | shared | slave | unchanged
 174 Recursively set the mount propagation flag in the new mount namespace.  The default
 175 is to set the propagation to \fIprivate\fP.  It is possible to disable this feature
 176 with the argument \fBunchanged\fR.  The option is silently ignored when the mount
 177 namespace (\fB\-\-mount\fP) is not requested.
 178 .TP
 179 .BR "\-\-setgroups allow" | deny
 180 Allow or deny the
 181 .BR setgroups (2)
 182 system call in a user namespace.
 183 .sp
 184 To be able to call
 185 .BR setgroups (2),
 186 the calling process must at least have CAP_SETGID.
 187 But since Linux 3.19 a further restriction applies:
 188 the kernel gives permission to call
 189 .BR \%setgroups (2)
 190 only after the GID map (\fB/proc/\fIpid\fB/gid_map\fR) has been set.
 191 The GID map is writable by root when
 192 .BR \%setgroups (2)
 193 is enabled (i.e., \fBallow\fR, the default), and
 194 the GID map becomes writable by unprivileged processes when
 195 .BR \%setgroups (2)
 196 is permanently disabled (with \fBdeny\fR).
 197 .TP
 198 .BR \-R, "\-\-root=\fIdir"
 199 run the command with root directory set to \fIdir\fP.
 200 .TP
 201 .BR \-w, "\-\-wd=\fIdir"
 202 change working directory to \fIdir\fP.
 203 .TP
 204 .BR \-S, "\-\-setuid \fIuid"
 205 Set the user ID which will be used in the entered namespace.
 206 .TP
 207 .BR \-G, "\-\-setgid \fIgid"
 208 Set the group ID which will be used in the entered namespace and drop
 209 supplementary groups.
 210 .TP
 211 .BR \-V , " \-\-version"
 212 Display version information and exit.
 213 .TP
 214 .BR \-h , " \-\-help"
 215 Display help text and exit.
 216 .SH NOTES
 217 The proc and sysfs filesystems mounting as root in a user namespace have to be
 218 restricted so that a less privileged user can not get more access to sensitive
 219 files that a more privileged user made unavailable. In short the rule for proc
 220 and sysfs is as close to a bind mount as possible.
 221 .SH EXAMPLES
 222 .TP
 223 .B # unshare \-\-fork \-\-pid \-\-mount-proc readlink /proc/self
 224 .TQ
 225 1
 226 .br
 227 Establish a PID namespace, ensure we're PID 1 in it against a newly mounted
 228 procfs instance.
 229 .TP
 230 .B $ unshare \-\-map-root-user \-\-user sh \-c whoami
 231 .TQ
 232 root
 233 .br
 234 Establish a user namespace as an unprivileged user with a root user within it.
 235 .TP
 236 .B # touch /root/uts-ns
 237 .TQ
 238 .B # unshare \-\-uts=/root/uts-ns hostname FOO
 239 .TQ
 240 .B # nsenter \-\-uts=/root/uts-ns hostname
 241 .TQ
 242 FOO
 243 .TQ
 244 .B # umount /root/uts-ns
 245 .br
 246 Establish a persistent UTS namespace, and modify the hostname.  The namespace
 247 is then entered with \fBnsenter\fR.  The namespace is destroyed by unmounting
 248 the bind reference.
 249 .TP
 250 .B # mount \-\-bind /root/namespaces /root/namespaces
 251 .TQ
 252 .B # mount \-\-make-private /root/namespaces
 253 .TQ
 254 .B # touch /root/namespaces/mnt
 255 .TQ
 256 .B # unshare \-\-mount=/root/namespaces/mnt
 257 .br
 258 Establish a persistent mount namespace referenced by the bind mount
 259 /root/namespaces/mnt.  This example shows a portable solution, because it
 260 makes sure that the bind mount is created on a shared filesystem.
 261 .TP
 262 .B # unshare \-pf \-\-kill-child \-\- bash \-c "(sleep 999 &) && sleep 1000" &
 263 .TQ
 264 .B # pid=$!
 265 .TQ
 266 .B # kill $pid
 267 .br
 268 Reliable killing of subprocesses of the \fIprogram\fR.
 269 When \fBunshare\fR gets killed, everything below it gets killed as well.
 270 Without it, the children of \fIprogram\fR would have orphaned and
 271 been re-parented to PID 1.
 272
 273 .SH SEE ALSO
 274 .BR clone (2),
 275 .BR unshare (2),
 276 .BR namespaces (7),
 277 .BR mount (8)
 278 .SH AUTHORS
 279 .UR dottedmag@dottedmag.net
 280 Mikhail Gusarov
 281 .UE
 282 .br
 283 .UR kzak@redhat.com
 284 Karel Zak
 285 .UE
 286 .SH AVAILABILITY
 287 The unshare command is part of the util-linux package and is available from
 288 https://www.kernel.org/pub/linux/utils/util-linux/.