manual/util-linux/original/man1/unshare.1

   1 '\" t
   2 .\"     Title: unshare
   3 .\"    Author: [see the "AUTHOR(S)" section]
   4 .\" Generator: Asciidoctor 2.0.15
   5 .\"      Date: 2022-01-24
   6 .\"    Manual: User Commands
   7 .\"    Source: util-linux 2.37.3
   8 .\"  Language: English
   9 .\"
  10 .TH "UNSHARE" "1" "2022-01-24" "util\-linux 2.37.3" "User Commands"
  11 .ie \n(.g .ds Aq \(aq
  12 .el       .ds Aq '
  13 .ss \n[.ss] 0
  14 .nh
  15 .ad l
  16 .de URL
  17 \fI\\$2\fP <\\$1>\\$3
  18 ..
  19 .als MTO URL
  20 .if \n[.g] \{\
  21 .  mso www.tmac
  22 .  am URL
  23 .    ad l
  24 .  .
  25 .  am MTO
  26 .    ad l
  27 .  .
  28 .  LINKSTYLE blue R < >
  29 .\}
  30 .SH "NAME"
  31 unshare \- run program in new namespaces
  32 .SH "SYNOPSIS"
  33 .sp
  34 \fBunshare\fP [options] [\fIprogram\fP [\fIarguments\fP]]
  35 .SH "DESCRIPTION"
  36 .sp
  37 The \fBunshare\fP command creates new namespaces (as specified by the command\-line options described below) and then executes the specified \fIprogram\fP. If \fIprogram\fP is not given, then "${SHELL}" is run (default: \fI/bin/sh\fP).
  38 .sp
  39 By default, a new namespace persists only as long as it has member processes. A new namespace can be made persistent even when it has no member processes by bind mounting /proc/\fIpid\fP/ns/\fItype\fP files to a filesystem path. A namespace that has been made persistent in this way can subsequently be entered with \fBnsenter\fP(1) even after the \fIprogram\fP terminates (except PID namespaces where a permanently running init process is required). Once a persistent namespace is no longer needed, it can be unpersisted by using \fBumount\fP(8) to remove the bind mount. See the EXAMPLES section for more details.
  40 .sp
  41 \fBunshare\fP since util\-linux version 2.36 uses \fI/proc/[pid]/ns/pid_for_children\fP and \fI/proc/[pid]/ns/time_for_children\fP files for persistent PID and TIME namespaces. This change requires Linux kernel 4.17 or newer.
  42 .sp
  43 The following types of namespaces can be created with \fBunshare\fP:
  44 .sp
  45 \fBmount namespace\fP
  46 .RS 4
  47 Mounting and unmounting filesystems will not affect the rest of the system, except for filesystems which are explicitly marked as shared (with \fBmount \-\-make\-shared\fP; see \fI/proc/self/mountinfo\fP or \fBfindmnt \-o+PROPAGATION\fP for the \fBshared\fP flags). For further details, see \fBmount_namespaces\fP(7).
  48 .sp
  49 \fBunshare\fP since util\-linux version 2.27 automatically sets propagation to \fBprivate\fP in a new mount namespace to make sure that the new namespace is really unshared. It\(cqs possible to disable this feature with option \fB\-\-propagation unchanged\fP. Note that \fBprivate\fP is the kernel default.
  50 .RE
  51 .sp
  52 \fBUTS namespace\fP
  53 .RS 4
  54 Setting hostname or domainname will not affect the rest of the system. For further details, see \fButs_namespaces\fP(7).
  55 .RE
  56 .sp
  57 \fBIPC namespace\fP
  58 .RS 4
  59 The process will have an independent namespace for POSIX message queues as well as System V message queues, semaphore sets and shared memory segments. For further details, see \fBipc_namespaces\fP(7).
  60 .RE
  61 .sp
  62 \fBnetwork namespace\fP
  63 .RS 4
  64 The process will have independent IPv4 and IPv6 stacks, IP routing tables, firewall rules, the \fI/proc/net\fP and \fI/sys/class/net\fP directory trees, sockets, etc. For further details, see \fBnetwork_namespaces\fP(7).
  65 .RE
  66 .sp
  67 \fBPID namespace\fP
  68 .RS 4
  69 Children will have a distinct set of PID\-to\-process mappings from their parent. For further details, see \fBpid_namespaces\fP(7).
  70 .RE
  71 .sp
  72 \fBcgroup namespace\fP
  73 .RS 4
  74 The process will have a virtualized view of \fI/proc/self/cgroup\fP, and new cgroup mounts will be rooted at the namespace cgroup root. For further details, see \fBcgroup_namespaces\fP(7).
  75 .RE
  76 .sp
  77 \fBuser namespace\fP
  78 .RS 4
  79 The process will have a distinct set of UIDs, GIDs and capabilities. For further details, see \fBuser_namespaces\fP(7).
  80 .RE
  81 .sp
  82 \fBtime namespace\fP
  83 .RS 4
  84 The process can have a distinct view of \fBCLOCK_MONOTONIC\fP and/or \fBCLOCK_BOOTTIME\fP which can be changed using \fI/proc/self/timens_offsets\fP. For further details, see \fBtime_namespaces\fP(7).
  85 .RE
  86 .SH "OPTIONS"
  87 .sp
  88 \fB\-i\fP, \fB\-\-ipc\fP[\fB=\fP\fIfile\fP]
  89 .RS 4
  90 Unshare the IPC namespace. If \fIfile\fP is specified, then a persistent namespace is created by a bind mount.
  91 .RE
  92 .sp
  93 \fB\-m\fP, \fB\-\-mount\fP[\fB=\fP\fIfile\fP]
  94 .RS 4
  95 Unshare the mount namespace. If \fIfile\fP is specified, then a persistent namespace is created by a bind mount. Note that \fIfile\fP must be located on a mount whose propagation type is not \fBshared\fP (or an error results). Use the command \fBfindmnt \-o+PROPAGATION\fP when not sure about the current setting. See also the examples below.
  96 .RE
  97 .sp
  98 \fB\-n\fP, \fB\-\-net\fP[\fB=\fP\fIfile\fP]
  99 .RS 4
 100 Unshare the network namespace. If \fIfile\fP is specified, then a persistent namespace is created by a bind mount.
 101 .RE
 102 .sp
 103 \fB\-p\fP, \fB\-\-pid\fP[\fB=\fP\fIfile\fP]
 104 .RS 4
 105 Unshare the PID namespace. If \fIfile\fP is specified, then a persistent namespace is created by a bind mount. (Creation of a persistent PID namespace will fail if the \fB\-\-fork\fP option is not also specified.)
 106 .sp
 107 See also the \fB\-\-fork\fP and \fB\-\-mount\-proc\fP options.
 108 .RE
 109 .sp
 110 \fB\-u\fP, \fB\-\-uts\fP[\fB=\fP\fIfile\fP]
 111 .RS 4
 112 Unshare the UTS namespace. If \fIfile\fP is specified, then a persistent namespace is created by a bind mount.
 113 .RE
 114 .sp
 115 \fB\-U\fP, \fB\-\-user\fP[\fB=\fP\fIfile\fP]
 116 .RS 4
 117 Unshare the user namespace. If \fIfile\fP is specified, then a persistent namespace is created by a bind mount.
 118 .RE
 119 .sp
 120 \fB\-C\fP, \fB\-\-cgroup\fP[\fB=\fP\fIfile\fP]
 121 .RS 4
 122 Unshare the cgroup namespace. If \fIfile\fP is specified, then persistent namespace is created by bind mount.
 123 .RE
 124 .sp
 125 \fB\-T\fP, \fB\-\-time\fP[\fB=\fP\fIfile\fP]
 126 .RS 4
 127 Unshare the time namespace. If \fIfile\fP is specified, then a persistent namespace is created by a bind mount. The \fB\-\-monotonic\fP and \fB\-\-boottime\fP options can be used to specify the corresponding offset in the time namespace.
 128 .RE
 129 .sp
 130 \fB\-f\fP, \fB\-\-fork\fP
 131 .RS 4
 132 Fork the specified \fIprogram\fP as a child process of \fBunshare\fP rather than running it directly. This is useful when creating a new PID namespace. Note that when \fBunshare\fP is waiting for the child process, then it ignores \fBSIGINT\fP and \fBSIGTERM\fP and does not forward any signals to the child. It is necessary to send signals to the child process.
 133 .RE
 134 .sp
 135 \fB\-\-keep\-caps\fP
 136 .RS 4
 137 When the \fB\-\-user\fP option is given, ensure that capabilities granted in the user namespace are preserved in the child process.
 138 .RE
 139 .sp
 140 \fB\-\-kill\-child\fP[\fB=\fP\fIsigname\fP]
 141 .RS 4
 142 When \fBunshare\fP terminates, have \fIsigname\fP be sent to the forked child process. Combined with \fB\-\-pid\fP this allows for an easy and reliable killing of the entire process tree below \fBunshare\fP. If not given, \fIsigname\fP defaults to \fBSIGKILL\fP. This option implies \fB\-\-fork\fP.
 143 .RE
 144 .sp
 145 \fB\-\-mount\-proc\fP[\fB=\fP\fImountpoint\fP]
 146 .RS 4
 147 Just before running the program, mount the proc filesystem at \fImountpoint\fP (default is \fI/proc\fP). This is useful when creating a new PID namespace. It also implies creating a new mount namespace since the \fI/proc\fP mount would otherwise mess up existing programs on the system. The new proc filesystem is explicitly mounted as private (with \fBMS_PRIVATE\fP|\fBMS_REC\fP).
 148 .RE
 149 .sp
 150 \fB\-\-map\-user=\fP\fIuid|name\fP
 151 .RS 4
 152 Run the program only after the current effective user ID has been mapped to \fIuid\fP. If this option is specified multiple times, the last occurrence takes precedence. This option implies \fB\-\-user\fP.
 153 .RE
 154 .sp
 155 \fB\-\-map\-group=\fP\fIgid|name\fP
 156 .RS 4
 157 Run the program only after the current effective group ID has been mapped to \fIgid\fP. If this option is specified multiple times, the last occurrence takes precedence. This option implies \fB\-\-setgroups=deny\fP and \fB\-\-user\fP.
 158 .RE
 159 .sp
 160 \fB\-r\fP, \fB\-\-map\-root\-user\fP
 161 .RS 4
 162 Run the program only after the current effective user and group IDs have been mapped to the superuser UID and GID in the newly created user namespace. This makes it possible to conveniently gain capabilities needed to manage various aspects of the newly created namespaces (such as configuring interfaces in the network namespace or mounting filesystems in the mount namespace) even when run unprivileged. As a mere convenience feature, it does not support more sophisticated use cases, such as mapping multiple ranges of UIDs and GIDs. This option implies \fB\-\-setgroups=deny\fP and \fB\-\-user\fP. This option is equivalent to \fB\-\-map\-user=0 \-\-map\-group=0\fP.
 163 .RE
 164 .sp
 165 \fB\-c\fP, \fB\-\-map\-current\-user\fP
 166 .RS 4
 167 Run the program only after the current effective user and group IDs have been mapped to the same UID and GID in the newly created user namespace. This option implies \fB\-\-setgroups=deny\fP and \fB\-\-user\fP. This option is equivalent to \fB\-\-map\-user=$(id \-ru) \-\-map\-group=$(id \-rg)\fP.
 168 .RE
 169 .sp
 170 \fB\-\-propagation private\fP|\fBshared\fP|\fBslave\fP|\fBunchanged\fP
 171 .RS 4
 172 Recursively set the mount propagation flag in the new mount namespace. The default is to set the propagation to \fIprivate\fP. It is possible to disable this feature with the argument \fBunchanged\fP. The option is silently ignored when the mount namespace (\fB\-\-mount\fP) is not requested.
 173 .RE
 174 .sp
 175 \fB\-\-setgroups allow\fP|\fBdeny\fP
 176 .RS 4
 177 Allow or deny the \fBsetgroups\fP(2) system call in a user namespace.
 178 .sp
 179 To be able to call \fBsetgroups\fP(2), the calling process must at least have \fBCAP_SETGID\fP. But since Linux 3.19 a further restriction applies: the kernel gives permission to call \fBsetgroups\fP(2) only after the GID map (\fB/proc/\fP\fIpid\fP*/gid_map*) has been set. The GID map is writable by root when \fBsetgroups\fP(2) is enabled (i.e., \fBallow\fP, the default), and the GID map becomes writable by unprivileged processes when \fBsetgroups\fP(2) is permanently disabled (with \fBdeny\fP).
 180 .RE
 181 .sp
 182 \fB\-R\fP, \fB\-\-root=\fP\fIdir\fP
 183 .RS 4
 184 run the command with root directory set to \fIdir\fP.
 185 .RE
 186 .sp
 187 \fB\-w\fP, \fB\-\-wd=\fP\fIdir\fP
 188 .RS 4
 189 change working directory to \fIdir\fP.
 190 .RE
 191 .sp
 192 \fB\-S\fP, \fB\-\-setuid\fP \fIuid\fP
 193 .RS 4
 194 Set the user ID which will be used in the entered namespace.
 195 .RE
 196 .sp
 197 \fB\-G\fP, \fB\-\-setgid\fP \fIgid\fP
 198 .RS 4
 199 Set the group ID which will be used in the entered namespace and drop supplementary groups.
 200 .RE
 201 .sp
 202 \fB\-\-monotonic\fP \fIoffset\fP
 203 .RS 4
 204 Set the offset of \fBCLOCK_MONOTONIC\fP which will be used in the entered time namespace. This option requires unsharing a time namespace with \fB\-\-time\fP.
 205 .RE
 206 .sp
 207 \fB\-\-boottime\fP \fIoffset\fP
 208 .RS 4
 209 Set the offset of \fBCLOCK_BOOTTIME\fP which will be used in the entered time namespace. This option requires unsharing a time namespace with \fB\-\-time\fP.
 210 .RE
 211 .sp
 212 \fB\-V\fP, \fB\-\-version\fP
 213 .RS 4
 214 Display version information and exit.
 215 .RE
 216 .sp
 217 \fB\-h\fP, \fB\-\-help\fP
 218 .RS 4
 219 Display help text and exit.
 220 .RE
 221 .SH "NOTES"
 222 .sp
 223 The proc and sysfs filesystems mounting as root in a user namespace have to be restricted so that a less privileged user can not get more access to sensitive files that a more privileged user made unavailable. In short the rule for proc and sysfs is as close to a bind mount as possible.
 224 .SH "EXAMPLES"
 225 .sp
 226 The following command creates a PID namespace, using \fB\-\-fork\fP to ensure that the executed command is performed in a child process that (being the first process in the namespace) has PID 1. The \fB\-\-mount\-proc\fP option ensures that a new mount namespace is also simultaneously created and that a new \fBproc\fP(5) filesystem is mounted that contains information corresponding to the new PID namespace. When the \fBreadlink\fP command terminates, the new namespaces are automatically torn down.
 227 .sp
 228 .if n .RS 4
 229 .nf
 230 .fam C
 231 # unshare \-\-fork \-\-pid \-\-mount\-proc readlink /proc/self
 232 1
 233 .fam
 234 .fi
 235 .if n .RE
 236 .sp
 237 As an unprivileged user, create a new user namespace where the user\(cqs credentials are mapped to the root IDs inside the namespace:
 238 .sp
 239 .if n .RS 4
 240 .nf
 241 .fam C
 242 $ id \-u; id \-g
 243 1000
 244 1000
 245 $ unshare \-\-user \-\-map\-root\-user \(rs
 246         sh \-c \(aq\(aqwhoami; cat /proc/self/uid_map /proc/self/gid_map\(aq\(aq
 247 root
 248          0       1000          1
 249          0       1000          1
 250 .fam
 251 .fi
 252 .if n .RE
 253 .sp
 254 The first of the following commands creates a new persistent UTS namespace and modifies the hostname as seen in that namespace. The namespace is then entered with \fBnsenter\fP(1) in order to display the modified hostname; this step demonstrates that the UTS namespace continues to exist even though the namespace had no member processes after the \fBunshare\fP command terminated. The namespace is then destroyed by removing the bind mount.
 255 .sp
 256 .if n .RS 4
 257 .nf
 258 .fam C
 259 # touch /root/uts\-ns
 260 # unshare \-\-uts=/root/uts\-ns hostname FOO
 261 # nsenter \-\-uts=/root/uts\-ns hostname
 262 FOO
 263 # umount /root/uts\-ns
 264 .fam
 265 .fi
 266 .if n .RE
 267 .sp
 268 The following commands establish a persistent mount namespace referenced by the bind mount \fI/root/namespaces/mnt\fP. In order to ensure that the creation of that bind mount succeeds, the parent directory (\fI/root/namespaces\fP) is made a bind mount whose propagation type is not \fBshared\fP.
 269 .sp
 270 .if n .RS 4
 271 .nf
 272 .fam C
 273 # mount \-\-bind /root/namespaces /root/namespaces
 274 # mount \-\-make\-private /root/namespaces
 275 # touch /root/namespaces/mnt
 276 # unshare \-\-mount=/root/namespaces/mnt
 277 .fam
 278 .fi
 279 .if n .RE
 280 .sp
 281 The following commands demonstrate the use of the \fB\-\-kill\-child\fP option when creating a PID namespace, in order to ensure that when \fBunshare\fP is killed, all of the processes within the PID namespace are killed.
 282 .sp
 283 .if n .RS 4
 284 .nf
 285 .fam C
 286 # set +m                # Don\(aqt print job status messages
 287
 288
 289 # unshare \-\-pid \-\-fork \-\-mount\-proc \-\-kill\-child \-\- \(rs
 290
 291
 292        bash \-\-norc \-c \(aq\(aq(sleep 555 &) && (ps a &) && sleep 999\(aq\(aq &
 293 [1] 53456
 294 #     PID TTY      STAT   TIME COMMAND
 295       1 pts/3    S+     0:00 sleep 999
 296       3 pts/3    S+     0:00 sleep 555
 297       5 pts/3    R+     0:00 ps a
 298
 299 # ps h \-o \(aqcomm\(aq $!     # Show that background job is unshare(1)
 300 unshare
 301 # kill $!               # Kill unshare(1)
 302 # pidof sleep
 303 .fam
 304 .fi
 305 .if n .RE
 306 .sp
 307 The \fBpidof\fP(1) command prints no output, because the \fBsleep\fP processes have been killed. More precisely, when the \fBsleep\fP process that has PID 1 in the namespace (i.e., the namespace\(cqs init process) was killed, this caused all other processes in the namespace to be killed. By contrast, a similar series of commands where the \fB\-\-kill\-child\fP option is not used shows that when \fBunshare\fP terminates, the processes in the PID namespace are not killed:
 308 .sp
 309 .if n .RS 4
 310 .nf
 311 .fam C
 312 # unshare \-\-pid \-\-fork \-\-mount\-proc \-\- \(rs
 313
 314
 315        bash \-\-norc \-c \(aq\(aq(sleep 555 &) && (ps a &) && sleep 999\(aq\(aq &
 316 [1] 53479
 317 #     PID TTY      STAT   TIME COMMAND
 318       1 pts/3    S+     0:00 sleep 999
 319       3 pts/3    S+     0:00 sleep 555
 320       5 pts/3    R+     0:00 ps a
 321
 322 # kill $!
 323 # pidof sleep
 324 53482 53480
 325 .fam
 326 .fi
 327 .if n .RE
 328 .sp
 329 The following example demonstrates the creation of a time namespace where the boottime clock is set to a point several years in the past:
 330 .sp
 331 .if n .RS 4
 332 .nf
 333 .fam C
 334 # uptime \-p             # Show uptime in initial time namespace
 335 up 21 hours, 30 minutes
 336 # unshare \-\-time \-\-fork \-\-boottime 300000000 uptime \-p
 337 up 9 years, 28 weeks, 1 day, 2 hours, 50 minutes
 338 .fam
 339 .fi
 340 .if n .RE
 341 .SH "AUTHORS"
 342 .sp
 343 .MTO "dottedmag\(atdottedmag.net" "Mikhail Gusarov" ","
 344 .MTO "kzak\(atredhat.com" "Karel Zak" ""
 345 .SH "SEE ALSO"
 346 .sp
 347 \fBclone\fP(2),
 348 \fBunshare\fP(2),
 349 \fBnamespaces\fP(7),
 350 \fBmount\fP(8)
 351 .SH "REPORTING BUGS"
 352 .sp
 353 For bug reports, use the issue tracker at \c
 354 .URL "https://github.com/karelzak/util\-linux/issues" "" "."
 355 .SH "AVAILABILITY"
 356 .sp
 357 The \fBunshare\fP command is part of the util\-linux package which can be downloaded from \c
 358 .URL "https://www.kernel.org/pub/linux/utils/util\-linux/" "Linux Kernel Archive" "."