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 .BR "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 .BR 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 .BR "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 .BR CLONE_NEWUTS
  50 flag in
  51 .BR clone (2).
  52 .TP
  53 .BR "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 .BR CLONE_NEWIPC
  61 flag in
  62 .BR clone (2).
  63 .TP
  64 .BR "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 .BR CLONE_NEWNET
  72 flag in
  73 .BR clone (2).
  74 .TP
  75 .BR "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 .BR CLONE_NEWPID
  82 flag in
  83 .BR clone (2).
  84 .TP
  85 .BR "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 .BR CLONE_NEWCGROUP
  92 flag in
  93 .BR clone (2).
  94 .TP
  95 .BR "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 .BR 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 .BR \-\-kill\-child [ =\fIsigname ]
 142 When \fBunshare\fR terminates, have \fIsigname\fP be sent to the forked child process.
 143 Combined with \fB--pid\fR this allows for an easy and realiable killing of the entire
 144 process tree below \fBunshare\fR.
 145 If not given, \fIsigname\fP defaults to \fBSIGKILL\fR.
 146 This option implies \fB--fork\fR.
 147 .TP
 148 .BR \-\-mount\-proc [ =\fImountpoint ]
 149 Just before running the program, mount the proc filesystem at \fImountpoint\fP
 150 (default is /proc).  This is useful when creating a new PID namespace.  It also
 151 implies creating a new mount namespace since the /proc mount would otherwise
 152 mess up existing programs on the system.  The new proc filesystem is explicitly
 153 mounted as private (with MS_PRIVATE|MS_REC).
 154 .TP
 155 .BR \-r , " \-\-map\-root\-user"
 156 Run the program only after the current effective user and group IDs have been mapped to
 157 the superuser UID and GID in the newly created user namespace.  This makes it possible to
 158 conveniently gain capabilities needed to manage various aspects of the newly created
 159 namespaces (such as configuring interfaces in the network namespace or mounting filesystems in
 160 the mount namespace) even when run unprivileged.  As a mere convenience feature, it does not support
 161 more sophisticated use cases, such as mapping multiple ranges of UIDs and GIDs.
 162 This option implies \fB--setgroups=deny\fR.
 163 .TP
 164 .BR "\-\-propagation private" | shared | slave | unchanged
 165 Recursively set the mount propagation flag in the new mount namespace.  The default
 166 is to set the propagation to \fIprivate\fP.  It is possible to disable this feature
 167 with the argument \fBunchanged\fR.  The option is silently ignored when the mount
 168 namespace (\fB\-\-mount\fP) is not requested.
 169 .TP
 170 .BR "\-\-setgroups allow" | deny
 171 Allow or deny the
 172 .BR setgroups (2)
 173 system call in a user namespace.
 174 .sp
 175 To be able to call
 176 .BR setgroups (2),
 177 the calling process must at least have CAP_SETGID.
 178 But since Linux 3.19 a further restriction applies:
 179 the kernel gives permission to call
 180 .BR \%setgroups (2)
 181 only after the GID map (\fB/proc/\fIpid\fB/gid_map\fR) has been set.
 182 The GID map is writable by root when
 183 .BR \%setgroups (2)
 184 is enabled (i.e. \fBallow\fR, the default), and
 185 the GID map becomes writable by unprivileged processes when
 186 .BR \%setgroups (2)
 187 is permanently disabled (with \fBdeny\fR).
 188 .TP
 189 .BR \-V , " \-\-version"
 190 Display version information and exit.
 191 .TP
 192 .BR \-h , " \-\-help"
 193 Display help text and exit.
 194 .SH NOTES
 195 The proc and sysfs filesystems mounting as root in a user namespace have to be
 196 restricted so that a less privileged user can not get more access to sensitive
 197 files that a more privileged user made unavailable. In short the rule for proc
 198 and sysfs is as close to a bind mount as possible.
 199 .SH EXAMPLES
 200 .TP
 201 .B # unshare --fork --pid --mount-proc readlink /proc/self
 202 .TQ
 203 1
 204 .br
 205 Establish a PID namespace, ensure we're PID 1 in it against a newly mounted
 206 procfs instance.
 207 .TP
 208 .B $ unshare --map-root-user --user sh -c whoami
 209 .TQ
 210 root
 211 .br
 212 Establish a user namespace as an unprivileged user with a root user within it.
 213 .TP
 214 .B # touch /root/uts-ns
 215 .TQ
 216 .B # unshare --uts=/root/uts-ns hostname FOO
 217 .TQ
 218 .B # nsenter --uts=/root/uts-ns hostname
 219 .TQ
 220 FOO
 221 .TQ
 222 .B # umount /root/uts-ns
 223 .br
 224 Establish a persistent UTS namespace, and modify the hostname.  The namespace
 225 is then entered with \fBnsenter\fR.  The namespace is destroyed by unmounting
 226 the bind reference.
 227 .TP
 228 .B # mount --bind /root/namespaces /root/namespaces
 229 .TQ
 230 .B # mount --make-private /root/namespaces
 231 .TQ
 232 .B # touch /root/namespaces/mnt
 233 .TQ
 234 .B # unshare --mount=/root/namespaces/mnt
 235 .br
 236 Establish a persistent mount namespace referenced by the bind mount
 237 /root/namespaces/mnt.  This example shows a portable solution, because it
 238 makes sure that the bind mount is created on a shared filesystem.
 239 .TP
 240 .B # unshare -pf --kill-child -- bash -c "(sleep 999 &) && sleep 1000" &
 241 .TQ
 242 .B # pid=$!
 243 .TQ
 244 .B # kill $pid
 245 .br
 246 Reliable killing of subprocesses of the \fIprogram\fR.
 247 When \fBunshare\fR gets killed, everything below it gets killed as well.
 248 Without it, the children of \fIprogram\fR would have orphaned and
 249 been re-parented to PID 1.
 250
 251 .SH SEE ALSO
 252 .BR clone (2),
 253 .BR unshare (2),
 254 .BR namespaces (7),
 255 .BR mount (8)
 256 .SH AUTHORS
 257 .UR dottedmag@dottedmag.net
 258 Mikhail Gusarov
 259 .UE
 260 .br
 261 .UR kzak@redhat.com
 262 Karel Zak
 263 .UE
 264 .SH AVAILABILITY
 265 The unshare command is part of the util-linux package and is available from
 266 https://www.kernel.org/pub/linux/utils/util-linux/.