original/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 2014-09-21 "Linux" "Linux Programmer's Manual"
  21 .SH NAME
  22 unshare \- disassociate parts of the process execution context
  23 .SH SYNOPSIS
  24 .nf
  25 .B #include <sched.h>
  26 .sp
  27 .BI "int unshare(int " flags );
  28 .fi
  29 .sp
  30 .in -4n
  31 Feature Test Macro Requirements for glibc (see
  32 .BR feature_test_macros (7)):
  33 .in
  34 .sp
  35 .BR unshare ():
  36 .ad l
  37 .RS 4
  38 .PD 0
  39 .TP 4
  40 Since glibc 2.14:
  41 _GNU_SOURCE
  42 .TP 4
  43 .\" See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749
  44 Before glibc 2.14:
  45 _BSD_SOURCE || _SVID_SOURCE
  46     /* _GNU_SOURCE also suffices */
  47 .PD
  48 .RE
  49 .ad b
  50 .SH DESCRIPTION
  51 .BR unshare ()
  52 allows a process to disassociate parts of its execution
  53 context that are currently being shared with other processes.
  54 Part of the execution context, such as the mount namespace, is shared
  55 implicitly when a new process is created using
  56 .BR fork (2)
  57 or
  58 .BR vfork (2),
  59 while other parts, such as virtual memory, may be
  60 shared by explicit request when creating a process using
  61 .BR clone (2).
  62
  63 The main use of
  64 .BR unshare ()
  65 is to allow a process to control its
  66 shared execution context without creating a new process.
  67
  68 The
  69 .I flags
  70 argument is a bit mask that specifies which parts of
  71 the execution context should be unshared.
  72 This argument is specified by ORing together zero or more
  73 of the following constants:
  74 .TP
  75 .B CLONE_FILES
  76 Reverse the effect of the
  77 .BR clone (2)
  78 .B CLONE_FILES
  79 flag.
  80 Unshare the file descriptor table, so that the calling process
  81 no longer shares its file descriptors with any other process.
  82 .TP
  83 .B CLONE_FS
  84 Reverse the effect of the
  85 .BR clone (2)
  86 .B CLONE_FS
  87 flag.
  88 Unshare filesystem attributes, so that the calling process
  89 no longer shares its root directory
  90 .RB ( chroot (2)),
  91 current directory
  92 .RB ( chdir (2)),
  93 or umask
  94 .RB ( umask (2))
  95 attributes with any other process.
  96 .TP
  97 .BR CLONE_NEWIPC " (since Linux 2.6.19)
  98 This flag has the same effect as the
  99 .BR clone (2)
 100 .B CLONE_NEWIPC
 101 flag.
 102 Unshare the System\ V IPC namespace,
 103 so that the calling process has a private copy of the
 104 System\ V IPC namespace which is not shared with any other process.
 105 Specifying this flag automatically implies
 106 .BR CLONE_SYSVSEM
 107 as well.
 108 Use of
 109 .BR CLONE_NEWIPC
 110 requires the
 111 .BR CAP_SYS_ADMIN
 112 capability.
 113 .TP
 114 .BR CLONE_NEWNET " (since Linux 2.6.24)
 115 This flag has the same effect as the
 116 .BR clone (2)
 117 .B CLONE_NEWNET
 118 flag.
 119 Unshare the network namespace,
 120 so that the calling process is moved into a
 121 new network namespace which is not shared
 122 with any previously existing process.
 123 Use of
 124 .BR CLONE_NEWNET
 125 requires the
 126 .BR CAP_SYS_ADMIN
 127 capability.
 128 .TP
 129 .B CLONE_NEWNS
 130 .\" These flag name are inconsistent:
 131 .\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM,
 132 .\" CLONE_FS, and CLONE_FILES reverse the action of the clone()
 133 .\" flags of the same name.
 134 This flag has the same effect as the
 135 .BR clone (2)
 136 .B CLONE_NEWNS
 137 flag.
 138 Unshare the mount namespace,
 139 so that the calling process has a private copy of
 140 its namespace which is not shared with any other process.
 141 Specifying this flag automatically implies
 142 .B CLONE_FS
 143 as well.
 144 Use of
 145 .BR CLONE_NEWNS
 146 requires the
 147 .BR CAP_SYS_ADMIN
 148 capability.
 149 .TP
 150 .BR CLONE_NEWPID " (since Linux 3.8)"
 151 This flag has the same effect as the
 152 .BR clone (2)
 153 .B CLONE_NEWPID
 154 flag.
 155 Unshare the PID namespace,
 156 so that the calling process has a new PID namespace for its children
 157 which is not shared with any previously existing process.
 158 The calling process is
 159 .I not
 160 moved into the new namespace.
 161 The first child created by the calling process will have
 162 the process ID 1 and will assume the role of
 163 .BR init (1)
 164 in the new namespace.
 165 .BR CLONE_NEWPID
 166 automatically implies
 167 .BR CLONE_THREAD
 168 as well.
 169 Use of
 170 .BR CLONE_NEWPID
 171 requires the
 172 .BR CAP_SYS_ADMIN
 173 capability.
 174 For further information, see
 175 .BR pid_namespaces (7).
 176 .TP
 177 .BR CLONE_NEWUSER " (since Linux 3.8)"
 178 This flag has the same effect as the
 179 .BR clone (2)
 180 .B CLONE_NEWUSER
 181 flag.
 182 Unshare the user namespace,
 183 so that the calling process is moved into a new user namespace
 184 which is not shared with any previously existing process.
 185 As with the child process created by
 186 .BR clone (2)
 187 with the
 188 .B CLONE_NEWUSER
 189 flag, the caller obtains a full set of capabilities in the new namespace.
 190 .IP
 191 .BR CLONE_NEWUSER
 192 requires that the calling process is not threaded; specifying
 193 .BR CLONE_NEWUSER
 194 automatically implies
 195 .BR CLONE_THREAD .
 196 Since Linux 3.9,
 197 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
 198 .\" https://lwn.net/Articles/543273/
 199 .BR CLONE_NEWUSER
 200 also automatically implies
 201 .BR CLONE_FS .
 202 .BR CLONE_NEWUSER
 203 requires that the user ID and group ID
 204 of the calling process are mapped to user IDs and group IDs in the
 205 user namespace of the calling process at the time of the call.
 206
 207 For further information on user namespaces, see
 208 .BR user_namespaces (7).
 209 .TP
 210 .BR CLONE_NEWUTS " (since Linux 2.6.19)"
 211 This flag has the same effect as the
 212 .BR clone (2)
 213 .B CLONE_NEWUTS
 214 flag.
 215 Unshare the UTS IPC namespace,
 216 so that the calling process has a private copy of the
 217 UTS namespace which is not shared with any other process.
 218 Use of
 219 .BR CLONE_NEWUTS
 220 requires the
 221 .BR CAP_SYS_ADMIN
 222 capability.
 223 .TP
 224 .BR CLONE_SYSVSEM " (since Linux 2.6.26)
 225 .\" commit 9edff4ab1f8d82675277a04e359d0ed8bf14a7b7
 226 This flag reverses the effect of the
 227 .BR clone (2)
 228 .B CLONE_SYSVSEM
 229 flag.
 230 Unshare System\ V semaphore adjustment
 231 .RI ( semadj )
 232 values,
 233 so that the calling process has a new empty
 234 .I semadj
 235 list that is not shared with any other process.
 236 If this is the last process that has a reference to the process's current
 237 .I semadj
 238 list, then the adjustments in that list are applied
 239 to the corresponding semaphores, as described in
 240 .BR semop (2).
 241 .\" CLONE_NEWNS If CLONE_SIGHAND is set and signals are also being shared
 242 .\" (i.e., current->signal->count > 1), force CLONE_THREAD.
 243 .PP
 244 In addition,
 245 .BR CLONE_THREAD ,
 246 .BR CLONE_SIGHAND ,
 247 and
 248 .BR CLONE_VM
 249 can be specified in
 250 .I flags
 251 if the caller is single threaded (i.e., it is not sharing
 252 its address space with another process or thread).
 253 In this case, these flags have no effect.
 254 (Note also that specifying
 255 .BR CLONE_THREAD
 256 automatically implies
 257 .BR CLONE_VM ,
 258 and specifying
 259 .BR CLONE_VM
 260 automatically implies
 261 .BR CLONE_SIGHAND .)
 262 .\" As at 3.9, the following forced implications also apply,
 263 .\" although the relevant flags are not yet implemented.
 264 .\" If CLONE_THREAD is set force CLONE_VM.
 265 .\" If CLONE_VM is set, force CLONE_SIGHAND.
 266 .\"
 267 If the process is multithreaded, then
 268 the use of these flags results in an error.
 269 .\" See kernel/fork.c::check_unshare_flags()
 270 .PP
 271 If
 272 .I flags
 273 is specified as zero, then
 274 .BR unshare ()
 275 is a no-op;
 276 no changes are made to the calling process's execution context.
 277 .SH RETURN VALUE
 278 On success, zero returned.
 279 On failure, \-1 is returned and
 280 .I errno
 281 is set to indicate the error.
 282 .SH ERRORS
 283 .TP
 284 .B EINVAL
 285 An invalid bit was specified in
 286 .IR flags .
 287 .TP
 288 .B EINVAL
 289 .BR CLONE_THREAD ,
 290 .BR CLONE_SIGHAND ,
 291 or
 292 .BR CLONE_VM
 293 was specified in
 294 .IR flags ,
 295 and the caller is multithreaded.
 296 .TP
 297 .B ENOMEM
 298 Cannot allocate sufficient memory to copy parts of caller's
 299 context that need to be unshared.
 300 .TP
 301 .B EPERM
 302 The calling process did not have the required privileges for this operation.
 303 .TP
 304 .B EPERM
 305 .BR CLONE_NEWUSER
 306 was specified in
 307 .IR flags ,
 308 but either the effective user ID or the effective group ID of the caller
 309 does not have a mapping in the parent namespace (see
 310 .BR user_namespaces (7)).
 311 .TP
 312 .BR EPERM " (since Linux 3.9)"
 313 .\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d
 314 .B CLONE_NEWUSER
 315 was specified in
 316 .I flags
 317 and the caller is in a chroot environment
 318 .\" FIXME What is the rationale for this restriction?
 319 (i.e., the caller's root directory does not match the root directory
 320 of the mount namespace in which it resides).
 321 .TP
 322 .BR EUSERS " (since Linux 3.11)"
 323 .B CLONE_NEWUSER
 324 was specified in
 325 .IR flags ,
 326 and the call would cause the limit on the number of
 327 nested user namespaces to be exceeded.
 328 See
 329 .BR user_namespaces (7).
 330 .SH VERSIONS
 331 The
 332 .BR unshare ()
 333 system call was added to Linux in kernel 2.6.16.
 334 .SH CONFORMING TO
 335 The
 336 .BR unshare ()
 337 system call is Linux-specific.
 338 .SH NOTES
 339 Not all of the process attributes that can be shared when
 340 a new process is created using
 341 .BR clone (2)
 342 can be unshared using
 343 .BR unshare ().
 344 In particular, as at kernel 3.8,
 345 .\" FIXME all of the following needs to be reviewed for the current kernel
 346 .BR unshare ()
 347 does not implement flags that reverse the effects of
 348 .BR CLONE_SIGHAND ,
 349 .\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND
 350 .\" was not specified when doing clone(); i.e., unsharing
 351 .\" signal handlers is permitted if we are not actually
 352 .\" sharing signal handlers.   mtk
 353 .BR CLONE_THREAD ,
 354 or
 355 .BR CLONE_VM .
 356 .\" However, we can do unshare(CLONE_VM) if CLONE_VM
 357 .\" was not specified when doing clone(); i.e., unsharing
 358 .\" virtual memory is permitted if we are not actually
 359 .\" sharing virtual memory.   mtk
 360 Such functionality may be added in the future, if required.
 361 .\"
 362 .\"9) Future Work
 363 .\"--------------
 364 .\"The current implementation of unshare does not allow unsharing of
 365 .\"signals and signal handlers. Signals are complex to begin with and
 366 .\"to unshare signals and/or signal handlers of a currently running
 367 .\"process is even more complex. If in the future there is a specific
 368 .\"need to allow unsharing of signals and/or signal handlers, it can
 369 .\"be incrementally added to unshare without affecting legacy
 370 .\"applications using unshare.
 371 .\"
 372 .SH EXAMPLE
 373 The program below provides a simple implementation of the
 374 .BR unshare (1)
 375 command, which unshares one or more namespaces and executes the
 376 command supplied in its command-line arguments.
 377 Here's an example of the use of this program,
 378 running a shell in a new mount namespace,
 379 and verifying that the original shell and the
 380 new shell are in separate mount namespaces:
 381 .in +4n
 382 .nf
 383
 384 $ \fBreadlink /proc/$$/ns/mnt\fP
 385 mnt:[4026531840]
 386 $ \fBsudo ./unshare -m /bin/bash\fP
 387 [sudo] password for cecilia:
 388 # \fBreadlink /proc/$$/ns/mnt\fP
 389 mnt:[4026532325]
 390 .fi
 391 .in
 392
 393 The differing output of the two
 394 .BR readlink (1)
 395 commands shows that the two shells are in different mount namespaces.
 396 .SS Program source
 397 \&
 398 .nf
 399 /* unshare.c
 400
 401    A simple implementation of the unshare(1) command: unshare
 402    namespaces and execute a command.
 403 */
 404 #define _GNU_SOURCE
 405 #include <sched.h>
 406 #include <unistd.h>
 407 #include <stdlib.h>
 408 #include <stdio.h>
 409
 410 /* A simple error\-handling function: print an error message based
 411    on the value in \(aqerrno\(aq and terminate the calling process */
 412
 413 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \\
 414                         } while (0)
 415
 416 static void
 417 usage(char *pname)
 418 {
 419     fprintf(stderr, "Usage: %s [options] program [arg...]\\n", pname);
 420     fprintf(stderr, "Options can be:\\n");
 421     fprintf(stderr, "    \-i   unshare IPC namespace\\n");
 422     fprintf(stderr, "    \-m   unshare mount namespace\\n");
 423     fprintf(stderr, "    \-n   unshare network namespace\\n");
 424     fprintf(stderr, "    \-p   unshare PID namespace\\n");
 425     fprintf(stderr, "    \-u   unshare UTS namespace\\n");
 426     fprintf(stderr, "    \-U   unshare user namespace\\n");
 427     exit(EXIT_FAILURE);
 428 }
 429
 430 int
 431 main(int argc, char *argv[])
 432 {
 433     int flags, opt;
 434
 435     flags = 0;
 436
 437     while ((opt = getopt(argc, argv, "imnpuU")) != \-1) {
 438         switch (opt) {
 439         case \(aqi\(aq: flags |= CLONE_NEWIPC;        break;
 440         case \(aqm\(aq: flags |= CLONE_NEWNS;         break;
 441         case \(aqn\(aq: flags |= CLONE_NEWNET;        break;
 442         case \(aqp\(aq: flags |= CLONE_NEWPID;        break;
 443         case \(aqu\(aq: flags |= CLONE_NEWUTS;        break;
 444         case \(aqU\(aq: flags |= CLONE_NEWUSER;       break;
 445         default:  usage(argv[0]);
 446         }
 447     }
 448
 449     if (optind >= argc)
 450         usage(argv[0]);
 451
 452     if (unshare(flags) == \-1)
 453         errExit("unshare");
 454
 455     execvp(argv[optind], &argv[optind]);
 456     errExit("execvp");
 457 }
 458 .fi
 459 .SH SEE ALSO
 460 .BR unshare (1),
 461 .BR clone (2),
 462 .BR fork (2),
 463 .BR kcmp (2),
 464 .BR setns (2),
 465 .BR vfork (2),
 466 .BR namespaces (7)
 467
 468 .I Documentation/unshare.txt
 469 in the Linux kernel source tree
 470 .SH COLOPHON
 471 This page is part of release 3.78 of the Linux
 472 .I man-pages
 473 project.
 474 A description of the project,
 475 information about reporting bugs,
 476 and the latest version of this page,
 477 can be found at
 478 \%http://www.kernel.org/doc/man\-pages/.