sys-utils/unshare.1

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