man2/unshare.2

   1 .\" Copyright (C) 2006, Janak Desai <janak@us.ibm.com>
   2 .\" and Copyright (C) 2006, 2012 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   5 .\" Licensed under the GPL
   6 .\" %%%LICENSE_END
   7 .\"
   8 .\" Patch Justification:
   9 .\" unshare system call is needed to implement, using PAM,
  10 .\" per-security_context and/or per-user namespace to provide
  11 .\" polyinstantiated directories. Using unshare and bind mounts, a
  12 .\" PAM module can create private namespace with appropriate
  13 .\" directories(based on user's security context) bind mounted on
  14 .\" public directories such as /tmp, thus providing an instance of
  15 .\" /tmp that is based on user's security context. Without the
  16 .\" unshare system call, namespace separation can only be achieved
  17 .\" by clone, which would require porting and maintaining all commands
  18 .\" such as login, and su, that establish a user session.
  19 .\"
  20 .TH UNSHARE 2 2019-03-06 "Linux" "Linux Programmer's Manual"
  21 .SH NAME
  22 unshare \- disassociate parts of the process execution context
  23 .SH SYNOPSIS
  24 .nf
  25 .B #define _GNU_SOURCE
  26 .B #include <sched.h>
  27 .PP
  28 .BI "int unshare(int " flags );
  29 .fi
  30 .SH DESCRIPTION
  31 .BR unshare ()
  32 allows a process (or thread) to disassociate parts of its execution
  33 context that are currently being shared with other processes (or threads).
  34 Part of the execution context, such as the mount namespace, is shared
  35 implicitly when a new process is created using
  36 .BR fork (2)
  37 or
  38 .BR vfork (2),
  39 while other parts, such as virtual memory, may be
  40 shared by explicit request when creating a process or thread using
  41 .BR clone (2).
  42 .PP
  43 The main use of
  44 .BR unshare ()
  45 is to allow a process to control its
  46 shared execution context without creating a new process.
  47 .PP
  48 The
  49 .I flags
  50 argument is a bit mask that specifies which parts of
  51 the execution context should be unshared.
  52 This argument is specified by ORing together zero or more
  53 of the following constants:
  54 .TP
  55 .B CLONE_FILES
  56 Reverse the effect of the
  57 .BR clone (2)
  58 .B CLONE_FILES
  59 flag.
  60 Unshare the file descriptor table, so that the calling process
  61 no longer shares its file descriptors with any other process.
  62 .TP
  63 .B CLONE_FS
  64 Reverse the effect of the
  65 .BR clone (2)
  66 .B CLONE_FS
  67 flag.
  68 Unshare filesystem attributes, so that the calling process
  69 no longer shares its root directory
  70 .RB ( chroot (2)),
  71 current directory
  72 .RB ( chdir (2)),
  73 or umask
  74 .RB ( umask (2))
  75 attributes with any other process.
  76 .TP
  77 .BR CLONE_NEWCGROUP " (since Linux 4.6)"
  78 This flag has the same effect as the
  79 .BR clone (2)
  80 .B CLONE_NEWCGROUP
  81 flag.
  82 Unshare the cgroup namespace.
  83 Use of
  84 .BR CLONE_NEWCGROUP
  85 requires the
  86 .BR CAP_SYS_ADMIN
  87 capability.
  88 .TP
  89 .BR CLONE_NEWIPC " (since Linux 2.6.19)"
  90 This flag has the same effect as the
  91 .BR clone (2)
  92 .B CLONE_NEWIPC
  93 flag.
  94 Unshare the IPC namespace,
  95 so that the calling process has a private copy of the
  96 IPC namespace which is not shared with any other process.
  97 Specifying this flag automatically implies
  98 .BR CLONE_SYSVSEM
  99 as well.
 100 Use of
 101 .BR CLONE_NEWIPC
 102 requires the
 103 .BR CAP_SYS_ADMIN
 104 capability.
 105 .TP
 106 .BR CLONE_NEWNET " (since Linux 2.6.24)"
 107 This flag has the same effect as the
 108 .BR clone (2)
 109 .B CLONE_NEWNET
 110 flag.
 111 Unshare the network namespace,
 112 so that the calling process is moved into a
 113 new network namespace which is not shared
 114 with any previously existing process.
 115 Use of
 116 .BR CLONE_NEWNET
 117 requires the
 118 .BR CAP_SYS_ADMIN
 119 capability.
 120 .TP
 121 .B CLONE_NEWNS
 122 .\" These flag name are inconsistent:
 123 .\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM,
 124 .\" CLONE_FS, and CLONE_FILES reverse the action of the clone()
 125 .\" flags of the same name.
 126 This flag has the same effect as the
 127 .BR clone (2)
 128 .B CLONE_NEWNS
 129 flag.
 130 Unshare the mount namespace,
 131 so that the calling process has a private copy of
 132 its namespace which is not shared with any other process.
 133 Specifying this flag automatically implies
 134 .B CLONE_FS
 135 as well.
 136 Use of
 137 .BR CLONE_NEWNS
 138 requires the
 139 .BR CAP_SYS_ADMIN
 140 capability.
 141 For further information, see
 142 .BR mount_namespaces (7).
 143 .TP
 144 .BR CLONE_NEWPID " (since Linux 3.8)"
 145 This flag has the same effect as the
 146 .BR clone (2)
 147 .B CLONE_NEWPID
 148 flag.
 149 Unshare the PID namespace,
 150 so that the calling process has a new PID namespace for its children
 151 which is not shared with any previously existing process.
 152 The calling process is
 153 .I not
 154 moved into the new namespace.
 155 The first child created by the calling process will have
 156 the process ID 1 and will assume the role of
 157 .BR init (1)
 158 in the new namespace.
 159 .BR CLONE_NEWPID
 160 automatically implies
 161 .BR CLONE_THREAD
 162 as well.
 163 Use of
 164 .BR CLONE_NEWPID
 165 requires the
 166 .BR CAP_SYS_ADMIN
 167 capability.
 168 For further information, see
 169 .BR pid_namespaces (7).
 170 .TP
 171 .BR CLONE_NEWUSER " (since Linux 3.8)"
 172 This flag has the same effect as the
 173 .BR clone (2)
 174 .B CLONE_NEWUSER
 175 flag.
 176 Unshare the user namespace,
 177 so that the calling process is moved into a new user namespace
 178 which is not shared with any previously existing process.
 179 As with the child process created by
 180 .BR clone (2)
 181 with the
 182 .B CLONE_NEWUSER
 183 flag, the caller obtains a full set of capabilities in the new namespace.
 184 .IP
 185 .BR CLONE_NEWUSER
 186 requires that the calling process is not threaded; specifying
 187 .BR CLONE_NEWUSER
 188 automatically implies
 189 .BR CLONE_THREAD .
 190 Since Linux 3.9,
 191 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
 192 .\" https://lwn.net/Articles/543273/
 193 .BR CLONE_NEWUSER
 194 also automatically implies
 195 .BR CLONE_FS .
 196 .BR CLONE_NEWUSER
 197 requires that the user ID and group ID
 198 of the calling process are mapped to user IDs and group IDs in the
 199 user namespace of the calling process at the time of the call.
 200 .IP
 201 For further information on user namespaces, see
 202 .BR user_namespaces (7).
 203 .TP
 204 .BR CLONE_NEWUTS " (since Linux 2.6.19)"
 205 This flag has the same effect as the
 206 .BR clone (2)
 207 .B CLONE_NEWUTS
 208 flag.
 209 Unshare the UTS IPC namespace,
 210 so that the calling process has a private copy of the
 211 UTS namespace which is not shared with any other process.
 212 Use of
 213 .BR CLONE_NEWUTS
 214 requires the
 215 .BR CAP_SYS_ADMIN
 216 capability.
 217 .TP
 218 .BR CLONE_SYSVSEM " (since Linux 2.6.26)
 219 .\" commit 9edff4ab1f8d82675277a04e359d0ed8bf14a7b7
 220 This flag reverses the effect of the
 221 .BR clone (2)
 222 .B CLONE_SYSVSEM
 223 flag.
 224 Unshare System\ V semaphore adjustment
 225 .RI ( semadj )
 226 values,
 227 so that the calling process has a new empty
 228 .I semadj
 229 list that is not shared with any other process.
 230 If this is the last process that has a reference to the process's current
 231 .I semadj
 232 list, then the adjustments in that list are applied
 233 to the corresponding semaphores, as described in
 234 .BR semop (2).
 235 .\" CLONE_NEWNS If CLONE_SIGHAND is set and signals are also being shared
 236 .\" (i.e., current->signal->count > 1), force CLONE_THREAD.
 237 .PP
 238 In addition,
 239 .BR CLONE_THREAD ,
 240 .BR CLONE_SIGHAND ,
 241 and
 242 .BR CLONE_VM
 243 can be specified in
 244 .I flags
 245 if the caller is single threaded (i.e., it is not sharing
 246 its address space with another process or thread).
 247 In this case, these flags have no effect.
 248 (Note also that specifying
 249 .BR CLONE_THREAD
 250 automatically implies
 251 .BR CLONE_VM ,
 252 and specifying
 253 .BR CLONE_VM
 254 automatically implies
 255 .BR CLONE_SIGHAND .)
 256 .\" As at 3.9, the following forced implications also apply,
 257 .\" although the relevant flags are not yet implemented.
 258 .\" If CLONE_THREAD is set force CLONE_VM.
 259 .\" If CLONE_VM is set, force CLONE_SIGHAND.
 260 .\"
 261 If the process is multithreaded, then
 262 the use of these flags results in an error.
 263 .\" See kernel/fork.c::check_unshare_flags()
 264 .PP
 265 If
 266 .I flags
 267 is specified as zero, then
 268 .BR unshare ()
 269 is a no-op;
 270 no changes are made to the calling process's execution context.
 271 .SH RETURN VALUE
 272 On success, zero returned.
 273 On failure, \-1 is returned and
 274 .I errno
 275 is set to indicate the error.
 276 .SH ERRORS
 277 .TP
 278 .B EINVAL
 279 An invalid bit was specified in
 280 .IR flags .
 281 .TP
 282 .B EINVAL
 283 .BR CLONE_THREAD ,
 284 .BR CLONE_SIGHAND ,
 285 or
 286 .BR CLONE_VM
 287 was specified in
 288 .IR flags ,
 289 and the caller is multithreaded.
 290 .TP
 291 .B EINVAL
 292 .BR CLONE_NEWIPC
 293 was specified in
 294 .IR flags ,
 295 but the kernel was not configured with the
 296 .B CONFIG_SYSVIPC
 297 and
 298 .BR CONFIG_IPC_NS
 299 options.
 300 .TP
 301 .B EINVAL
 302 .BR CLONE_NEWNET
 303 was specified in
 304 .IR flags ,
 305 but the kernel was not configured with the
 306 .B CONFIG_NET_NS
 307 option.
 308 .TP
 309 .B EINVAL
 310 .BR CLONE_NEWPID
 311 was specified in
 312 .IR flags ,
 313 but the kernel was not configured with the
 314 .B CONFIG_PID_NS
 315 option.
 316 .TP
 317 .B EINVAL
 318 .BR CLONE_NEWUSER
 319 was specified in
 320 .IR flags ,
 321 but the kernel was not configured with the
 322 .B CONFIG_USER_NS
 323 option.
 324 .TP
 325 .B EINVAL
 326 .BR CLONE_NEWUTS
 327 was specified in
 328 .IR flags ,
 329 but the kernel was not configured with the
 330 .B CONFIG_UTS_NS
 331 option.
 332 .TP
 333 .B EINVAL
 334 .BR CLONE_NEWPID
 335 was specified in
 336 .IR flags ,
 337 but the process has previously called
 338 .BR unshare ()
 339 with the
 340 .BR CLONE_NEWPID
 341 flag.
 342 .TP
 343 .B ENOMEM
 344 Cannot allocate sufficient memory to copy parts of caller's
 345 context that need to be unshared.
 346 .TP
 347 .BR ENOSPC " (since Linux 3.7)"
 348 .\" commit f2302505775fd13ba93f034206f1e2a587017929
 349 .B CLONE_NEWPID
 350 was specified in flags,
 351 but the limit on the nesting depth of PID namespaces
 352 would have been exceeded; see
 353 .BR pid_namespaces (7).
 354 .TP
 355 .BR ENOSPC " (since Linux 4.9; beforehand " EUSERS )
 356 .B CLONE_NEWUSER
 357 was specified in
 358 .IR flags ,
 359 and the call would cause the limit on the number of
 360 nested user namespaces to be exceeded.
 361 See
 362 .BR user_namespaces (7).
 363 .IP
 364 From Linux 3.11 to Linux 4.8, the error diagnosed in this case was
 365 .BR EUSERS .
 366 .TP
 367 .BR ENOSPC " (since Linux 4.9)"
 368 One of the values in
 369 .I flags
 370 specified the creation of a new user namespace,
 371 but doing so would have caused the limit defined by the corresponding file in
 372 .IR /proc/sys/user
 373 to be exceeded.
 374 For further details, see
 375 .BR namespaces (7).
 376 .TP
 377 .B EPERM
 378 The calling process did not have the required privileges for this operation.
 379 .TP
 380 .B EPERM
 381 .BR CLONE_NEWUSER
 382 was specified in
 383 .IR flags ,
 384 but either the effective user ID or the effective group ID of the caller
 385 does not have a mapping in the parent namespace (see
 386 .BR user_namespaces (7)).
 387 .TP
 388 .BR EPERM " (since Linux 3.9)"
 389 .\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d
 390 .B CLONE_NEWUSER
 391 was specified in
 392 .I flags
 393 and the caller is in a chroot environment
 394 .\" FIXME What is the rationale for this restriction?
 395 (i.e., the caller's root directory does not match the root directory
 396 of the mount namespace in which it resides).
 397 .TP
 398 .BR EUSERS " (from Linux 3.11 to Linux 4.8)"
 399 .B CLONE_NEWUSER
 400 was specified in
 401 .IR flags ,
 402 and the limit on the number of nested user namespaces would be exceeded.
 403 See the discussion of the
 404 .BR ENOSPC
 405 error above.
 406 .SH VERSIONS
 407 The
 408 .BR unshare ()
 409 system call was added to Linux in kernel 2.6.16.
 410 .SH CONFORMING TO
 411 The
 412 .BR unshare ()
 413 system call is Linux-specific.
 414 .SH NOTES
 415 Not all of the process attributes that can be shared when
 416 a new process is created using
 417 .BR clone (2)
 418 can be unshared using
 419 .BR unshare ().
 420 In particular, as at kernel 3.8,
 421 .\" FIXME all of the following needs to be reviewed for the current kernel
 422 .BR unshare ()
 423 does not implement flags that reverse the effects of
 424 .BR CLONE_SIGHAND ,
 425 .\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND
 426 .\" was not specified when doing clone(); i.e., unsharing
 427 .\" signal handlers is permitted if we are not actually
 428 .\" sharing signal handlers.   mtk
 429 .BR CLONE_THREAD ,
 430 or
 431 .BR CLONE_VM .
 432 .\" However, we can do unshare(CLONE_VM) if CLONE_VM
 433 .\" was not specified when doing clone(); i.e., unsharing
 434 .\" virtual memory is permitted if we are not actually
 435 .\" sharing virtual memory.   mtk
 436 Such functionality may be added in the future, if required.
 437 .\"
 438 .\"9) Future Work
 439 .\"--------------
 440 .\"The current implementation of unshare does not allow unsharing of
 441 .\"signals and signal handlers. Signals are complex to begin with and
 442 .\"to unshare signals and/or signal handlers of a currently running
 443 .\"process is even more complex. If in the future there is a specific
 444 .\"need to allow unsharing of signals and/or signal handlers, it can
 445 .\"be incrementally added to unshare without affecting legacy
 446 .\"applications using unshare.
 447 .\"
 448 .SH EXAMPLE
 449 The program below provides a simple implementation of the
 450 .BR unshare (1)
 451 command, which unshares one or more namespaces and executes the
 452 command supplied in its command-line arguments.
 453 Here's an example of the use of this program,
 454 running a shell in a new mount namespace,
 455 and verifying that the original shell and the
 456 new shell are in separate mount namespaces:
 457 .PP
 458 .in +4n
 459 .EX
 460 $ \fBreadlink /proc/$$/ns/mnt\fP
 461 mnt:[4026531840]
 462 $ \fBsudo ./unshare -m /bin/bash\fP
 463 # \fBreadlink /proc/$$/ns/mnt\fP
 464 mnt:[4026532325]
 465 .EE
 466 .in
 467 .PP
 468 The differing output of the two
 469 .BR readlink (1)
 470 commands shows that the two shells are in different mount namespaces.
 471 .SS Program source
 472 \&
 473 .EX
 474 /* unshare.c
 475
 476    A simple implementation of the unshare(1) command: unshare
 477    namespaces and execute a command.
 478 */
 479 #define _GNU_SOURCE
 480 #include <sched.h>
 481 #include <unistd.h>
 482 #include <stdlib.h>
 483 #include <stdio.h>
 484
 485 /* A simple error\-handling function: print an error message based
 486    on the value in \(aqerrno\(aq and terminate the calling process */
 487
 488 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 489                         } while (0)
 490
 491 static void
 492 usage(char *pname)
 493 {
 494     fprintf(stderr, "Usage: %s [options] program [arg...]\en", pname);
 495     fprintf(stderr, "Options can be:\en");
 496     fprintf(stderr, "    \-i   unshare IPC namespace\en");
 497     fprintf(stderr, "    \-m   unshare mount namespace\en");
 498     fprintf(stderr, "    \-n   unshare network namespace\en");
 499     fprintf(stderr, "    \-p   unshare PID namespace\en");
 500     fprintf(stderr, "    \-u   unshare UTS namespace\en");
 501     fprintf(stderr, "    \-U   unshare user namespace\en");
 502     exit(EXIT_FAILURE);
 503 }
 504
 505 int
 506 main(int argc, char *argv[])
 507 {
 508     int flags, opt;
 509
 510     flags = 0;
 511
 512     while ((opt = getopt(argc, argv, "imnpuU")) != \-1) {
 513         switch (opt) {
 514         case \(aqi\(aq: flags |= CLONE_NEWIPC;        break;
 515         case \(aqm\(aq: flags |= CLONE_NEWNS;         break;
 516         case \(aqn\(aq: flags |= CLONE_NEWNET;        break;
 517         case \(aqp\(aq: flags |= CLONE_NEWPID;        break;
 518         case \(aqu\(aq: flags |= CLONE_NEWUTS;        break;
 519         case \(aqU\(aq: flags |= CLONE_NEWUSER;       break;
 520         default:  usage(argv[0]);
 521         }
 522     }
 523
 524     if (optind >= argc)
 525         usage(argv[0]);
 526
 527     if (unshare(flags) == \-1)
 528         errExit("unshare");
 529
 530     execvp(argv[optind], &argv[optind]);
 531     errExit("execvp");
 532 }
 533 .EE
 534 .SH SEE ALSO
 535 .BR unshare (1),
 536 .BR clone (2),
 537 .BR fork (2),
 538 .BR kcmp (2),
 539 .BR setns (2),
 540 .BR vfork (2),
 541 .BR namespaces (7)
 542 .PP
 543 .I Documentation/userspace-api/unshare.rst
 544 in the Linux kernel source tree
 545 .\" commit f504d47be5e8fa7ecf2bf660b18b42e6960c0eb2
 546 (or
 547 .I Documentation/unshare.txt
 548 before Linux 4.12)