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 2021-03-22 "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_NEWTIME " (since Linux 5.6)"
 172 Unshare the time namespace,
 173 so that the calling process has a new time namespace for its children
 174 which is not shared with any previously existing process.
 175 The calling process is
 176 .I not
 177 moved into the new namespace.
 178 Use of
 179 .BR CLONE_NEWTIME
 180 requires the
 181 .BR CAP_SYS_ADMIN
 182 capability.
 183 For further information, see
 184 .BR time_namespaces (7).
 185 .TP
 186 .BR CLONE_NEWUSER " (since Linux 3.8)"
 187 This flag has the same effect as the
 188 .BR clone (2)
 189 .B CLONE_NEWUSER
 190 flag.
 191 Unshare the user namespace,
 192 so that the calling process is moved into a new user namespace
 193 which is not shared with any previously existing process.
 194 As with the child process created by
 195 .BR clone (2)
 196 with the
 197 .B CLONE_NEWUSER
 198 flag, the caller obtains a full set of capabilities in the new namespace.
 199 .IP
 200 .BR CLONE_NEWUSER
 201 requires that the calling process is not threaded; specifying
 202 .BR CLONE_NEWUSER
 203 automatically implies
 204 .BR CLONE_THREAD .
 205 Since Linux 3.9,
 206 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
 207 .\" https://lwn.net/Articles/543273/
 208 .BR CLONE_NEWUSER
 209 also automatically implies
 210 .BR CLONE_FS .
 211 .BR CLONE_NEWUSER
 212 requires that the user ID and group ID
 213 of the calling process are mapped to user IDs and group IDs in the
 214 user namespace of the calling process at the time of the call.
 215 .IP
 216 For further information on user namespaces, see
 217 .BR user_namespaces (7).
 218 .TP
 219 .BR CLONE_NEWUTS " (since Linux 2.6.19)"
 220 This flag has the same effect as the
 221 .BR clone (2)
 222 .B CLONE_NEWUTS
 223 flag.
 224 Unshare the UTS IPC namespace,
 225 so that the calling process has a private copy of the
 226 UTS namespace which is not shared with any other process.
 227 Use of
 228 .BR CLONE_NEWUTS
 229 requires the
 230 .BR CAP_SYS_ADMIN
 231 capability.
 232 .TP
 233 .BR CLONE_SYSVSEM " (since Linux 2.6.26)"
 234 .\" commit 9edff4ab1f8d82675277a04e359d0ed8bf14a7b7
 235 This flag reverses the effect of the
 236 .BR clone (2)
 237 .B CLONE_SYSVSEM
 238 flag.
 239 Unshare System\ V semaphore adjustment
 240 .RI ( semadj )
 241 values,
 242 so that the calling process has a new empty
 243 .I semadj
 244 list that is not shared with any other process.
 245 If this is the last process that has a reference to the process's current
 246 .I semadj
 247 list, then the adjustments in that list are applied
 248 to the corresponding semaphores, as described in
 249 .BR semop (2).
 250 .\" CLONE_NEWNS If CLONE_SIGHAND is set and signals are also being shared
 251 .\" (i.e., current->signal->count > 1), force CLONE_THREAD.
 252 .PP
 253 In addition,
 254 .BR CLONE_THREAD ,
 255 .BR CLONE_SIGHAND ,
 256 and
 257 .BR CLONE_VM
 258 can be specified in
 259 .I flags
 260 if the caller is single threaded (i.e., it is not sharing
 261 its address space with another process or thread).
 262 In this case, these flags have no effect.
 263 (Note also that specifying
 264 .BR CLONE_THREAD
 265 automatically implies
 266 .BR CLONE_VM ,
 267 and specifying
 268 .BR CLONE_VM
 269 automatically implies
 270 .BR CLONE_SIGHAND .)
 271 .\" As at 3.9, the following forced implications also apply,
 272 .\" although the relevant flags are not yet implemented.
 273 .\" If CLONE_THREAD is set force CLONE_VM.
 274 .\" If CLONE_VM is set, force CLONE_SIGHAND.
 275 .\"
 276 If the process is multithreaded, then
 277 the use of these flags results in an error.
 278 .\" See kernel/fork.c::check_unshare_flags()
 279 .PP
 280 If
 281 .I flags
 282 is specified as zero, then
 283 .BR unshare ()
 284 is a no-op;
 285 no changes are made to the calling process's execution context.
 286 .SH RETURN VALUE
 287 On success, zero returned.
 288 On failure, \-1 is returned and
 289 .I errno
 290 is set to indicate the error.
 291 .SH ERRORS
 292 .TP
 293 .B EINVAL
 294 An invalid bit was specified in
 295 .IR flags .
 296 .TP
 297 .B EINVAL
 298 .BR CLONE_THREAD ,
 299 .BR CLONE_SIGHAND ,
 300 or
 301 .BR CLONE_VM
 302 was specified in
 303 .IR flags ,
 304 and the caller is multithreaded.
 305 .TP
 306 .B EINVAL
 307 .BR CLONE_NEWIPC
 308 was specified in
 309 .IR flags ,
 310 but the kernel was not configured with the
 311 .B CONFIG_SYSVIPC
 312 and
 313 .BR CONFIG_IPC_NS
 314 options.
 315 .TP
 316 .B EINVAL
 317 .BR CLONE_NEWNET
 318 was specified in
 319 .IR flags ,
 320 but the kernel was not configured with the
 321 .B CONFIG_NET_NS
 322 option.
 323 .TP
 324 .B EINVAL
 325 .BR CLONE_NEWPID
 326 was specified in
 327 .IR flags ,
 328 but the kernel was not configured with the
 329 .B CONFIG_PID_NS
 330 option.
 331 .TP
 332 .B EINVAL
 333 .BR CLONE_NEWUSER
 334 was specified in
 335 .IR flags ,
 336 but the kernel was not configured with the
 337 .B CONFIG_USER_NS
 338 option.
 339 .TP
 340 .B EINVAL
 341 .BR CLONE_NEWUTS
 342 was specified in
 343 .IR flags ,
 344 but the kernel was not configured with the
 345 .B CONFIG_UTS_NS
 346 option.
 347 .TP
 348 .B EINVAL
 349 .BR CLONE_NEWPID
 350 was specified in
 351 .IR flags ,
 352 but the process has previously called
 353 .BR unshare ()
 354 with the
 355 .BR CLONE_NEWPID
 356 flag.
 357 .TP
 358 .B ENOMEM
 359 Cannot allocate sufficient memory to copy parts of caller's
 360 context that need to be unshared.
 361 .TP
 362 .BR ENOSPC " (since Linux 3.7)"
 363 .\" commit f2302505775fd13ba93f034206f1e2a587017929
 364 .B CLONE_NEWPID
 365 was specified in flags,
 366 but the limit on the nesting depth of PID namespaces
 367 would have been exceeded; see
 368 .BR pid_namespaces (7).
 369 .TP
 370 .BR ENOSPC " (since Linux 4.9; beforehand " EUSERS )
 371 .B CLONE_NEWUSER
 372 was specified in
 373 .IR flags ,
 374 and the call would cause the limit on the number of
 375 nested user namespaces to be exceeded.
 376 See
 377 .BR user_namespaces (7).
 378 .IP
 379 From Linux 3.11 to Linux 4.8, the error diagnosed in this case was
 380 .BR EUSERS .
 381 .TP
 382 .BR ENOSPC " (since Linux 4.9)"
 383 One of the values in
 384 .I flags
 385 specified the creation of a new user namespace,
 386 but doing so would have caused the limit defined by the corresponding file in
 387 .IR /proc/sys/user
 388 to be exceeded.
 389 For further details, see
 390 .BR namespaces (7).
 391 .TP
 392 .B EPERM
 393 The calling process did not have the required privileges for this operation.
 394 .TP
 395 .B EPERM
 396 .BR CLONE_NEWUSER
 397 was specified in
 398 .IR flags ,
 399 but either the effective user ID or the effective group ID of the caller
 400 does not have a mapping in the parent namespace (see
 401 .BR user_namespaces (7)).
 402 .TP
 403 .BR EPERM " (since Linux 3.9)"
 404 .\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d
 405 .B CLONE_NEWUSER
 406 was specified in
 407 .I flags
 408 and the caller is in a chroot environment
 409 .\" FIXME What is the rationale for this restriction?
 410 (i.e., the caller's root directory does not match the root directory
 411 of the mount namespace in which it resides).
 412 .TP
 413 .BR EUSERS " (from Linux 3.11 to Linux 4.8)"
 414 .B CLONE_NEWUSER
 415 was specified in
 416 .IR flags ,
 417 and the limit on the number of nested user namespaces would be exceeded.
 418 See the discussion of the
 419 .BR ENOSPC
 420 error above.
 421 .SH VERSIONS
 422 The
 423 .BR unshare ()
 424 system call was added to Linux in kernel 2.6.16.
 425 .SH CONFORMING TO
 426 The
 427 .BR unshare ()
 428 system call is Linux-specific.
 429 .SH NOTES
 430 Not all of the process attributes that can be shared when
 431 a new process is created using
 432 .BR clone (2)
 433 can be unshared using
 434 .BR unshare ().
 435 In particular, as at kernel 3.8,
 436 .\" FIXME all of the following needs to be reviewed for the current kernel
 437 .BR unshare ()
 438 does not implement flags that reverse the effects of
 439 .BR CLONE_SIGHAND ,
 440 .\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND
 441 .\" was not specified when doing clone(); i.e., unsharing
 442 .\" signal handlers is permitted if we are not actually
 443 .\" sharing signal handlers.   mtk
 444 .BR CLONE_THREAD ,
 445 or
 446 .BR CLONE_VM .
 447 .\" However, we can do unshare(CLONE_VM) if CLONE_VM
 448 .\" was not specified when doing clone(); i.e., unsharing
 449 .\" virtual memory is permitted if we are not actually
 450 .\" sharing virtual memory.   mtk
 451 Such functionality may be added in the future, if required.
 452 .\"
 453 .\"9) Future Work
 454 .\"--------------
 455 .\"The current implementation of unshare does not allow unsharing of
 456 .\"signals and signal handlers. Signals are complex to begin with and
 457 .\"to unshare signals and/or signal handlers of a currently running
 458 .\"process is even more complex. If in the future there is a specific
 459 .\"need to allow unsharing of signals and/or signal handlers, it can
 460 .\"be incrementally added to unshare without affecting legacy
 461 .\"applications using unshare.
 462 .\"
 463 .SH EXAMPLES
 464 The program below provides a simple implementation of the
 465 .BR unshare (1)
 466 command, which unshares one or more namespaces and executes the
 467 command supplied in its command-line arguments.
 468 Here's an example of the use of this program,
 469 running a shell in a new mount namespace,
 470 and verifying that the original shell and the
 471 new shell are in separate mount namespaces:
 472 .PP
 473 .in +4n
 474 .EX
 475 $ \fBreadlink /proc/$$/ns/mnt\fP
 476 mnt:[4026531840]
 477 $ \fBsudo ./unshare \-m /bin/bash\fP
 478 # \fBreadlink /proc/$$/ns/mnt\fP
 479 mnt:[4026532325]
 480 .EE
 481 .in
 482 .PP
 483 The differing output of the two
 484 .BR readlink (1)
 485 commands shows that the two shells are in different mount namespaces.
 486 .SS Program source
 487 \&
 488 .EX
 489 /* unshare.c
 490
 491    A simple implementation of the unshare(1) command: unshare
 492    namespaces and execute a command.
 493 */
 494 #define _GNU_SOURCE
 495 #include <sched.h>
 496 #include <unistd.h>
 497 #include <stdlib.h>
 498 #include <stdio.h>
 499
 500 /* A simple error\-handling function: print an error message based
 501    on the value in \(aqerrno\(aq and terminate the calling process. */
 502
 503 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 504                         } while (0)
 505
 506 static void
 507 usage(char *pname)
 508 {
 509     fprintf(stderr, "Usage: %s [options] program [arg...]\en", pname);
 510     fprintf(stderr, "Options can be:\en");
 511     fprintf(stderr, "    \-C   unshare cgroup namespace\en");
 512     fprintf(stderr, "    \-i   unshare IPC namespace\en");
 513     fprintf(stderr, "    \-m   unshare mount namespace\en");
 514     fprintf(stderr, "    \-n   unshare network namespace\en");
 515     fprintf(stderr, "    \-p   unshare PID namespace\en");
 516     fprintf(stderr, "    \-t   unshare time namespace\en");
 517     fprintf(stderr, "    \-u   unshare UTS namespace\en");
 518     fprintf(stderr, "    \-U   unshare user namespace\en");
 519     exit(EXIT_FAILURE);
 520 }
 521
 522 int
 523 main(int argc, char *argv[])
 524 {
 525     int flags, opt;
 526
 527     flags = 0;
 528
 529     while ((opt = getopt(argc, argv, "CimnptuU")) != \-1) {
 530         switch (opt) {
 531         case \(aqC\(aq: flags |= CLONE_NEWCGROUP;      break;
 532         case \(aqi\(aq: flags |= CLONE_NEWIPC;        break;
 533         case \(aqm\(aq: flags |= CLONE_NEWNS;         break;
 534         case \(aqn\(aq: flags |= CLONE_NEWNET;        break;
 535         case \(aqp\(aq: flags |= CLONE_NEWPID;        break;
 536         case \(aqt\(aq: flags |= CLONE_NEWTIME;        break;
 537         case \(aqu\(aq: flags |= CLONE_NEWUTS;        break;
 538         case \(aqU\(aq: flags |= CLONE_NEWUSER;       break;
 539         default:  usage(argv[0]);
 540         }
 541     }
 542
 543     if (optind >= argc)
 544         usage(argv[0]);
 545
 546     if (unshare(flags) == \-1)
 547         errExit("unshare");
 548
 549     execvp(argv[optind], &argv[optind]);
 550     errExit("execvp");
 551 }
 552 .EE
 553 .SH SEE ALSO
 554 .BR unshare (1),
 555 .BR clone (2),
 556 .BR fork (2),
 557 .BR kcmp (2),
 558 .BR setns (2),
 559 .BR vfork (2),
 560 .BR namespaces (7)
 561 .PP
 562 .I Documentation/userspace\-api/unshare.rst
 563 in the Linux kernel source tree
 564 .\" commit f504d47be5e8fa7ecf2bf660b18b42e6960c0eb2
 565 (or
 566 .I Documentation/unshare.txt
 567 before Linux 4.12)