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 2016-03-15 "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 .sp
  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
  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
  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
 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 ENOMEM
 292 Cannot allocate sufficient memory to copy parts of caller's
 293 context that need to be unshared.
 294 .TP
 295 .B EPERM
 296 The calling process did not have the required privileges for this operation.
 297 .TP
 298 .B EPERM
 299 .BR CLONE_NEWUSER
 300 was specified in
 301 .IR flags ,
 302 but either the effective user ID or the effective group ID of the caller
 303 does not have a mapping in the parent namespace (see
 304 .BR user_namespaces (7)).
 305 .TP
 306 .BR EPERM " (since Linux 3.9)"
 307 .\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d
 308 .B CLONE_NEWUSER
 309 was specified in
 310 .I flags
 311 and the caller is in a chroot environment
 312 .\" FIXME What is the rationale for this restriction?
 313 (i.e., the caller's root directory does not match the root directory
 314 of the mount namespace in which it resides).
 315 .TP
 316 .BR EUSERS " (since Linux 3.11)"
 317 .B CLONE_NEWUSER
 318 was specified in
 319 .IR flags ,
 320 and the call would cause the limit on the number of
 321 nested user namespaces to be exceeded.
 322 See
 323 .BR user_namespaces (7).
 324 .SH VERSIONS
 325 The
 326 .BR unshare ()
 327 system call was added to Linux in kernel 2.6.16.
 328 .SH CONFORMING TO
 329 The
 330 .BR unshare ()
 331 system call is Linux-specific.
 332 .SH NOTES
 333 Not all of the process attributes that can be shared when
 334 a new process is created using
 335 .BR clone (2)
 336 can be unshared using
 337 .BR unshare ().
 338 In particular, as at kernel 3.8,
 339 .\" FIXME all of the following needs to be reviewed for the current kernel
 340 .BR unshare ()
 341 does not implement flags that reverse the effects of
 342 .BR CLONE_SIGHAND ,
 343 .\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND
 344 .\" was not specified when doing clone(); i.e., unsharing
 345 .\" signal handlers is permitted if we are not actually
 346 .\" sharing signal handlers.   mtk
 347 .BR CLONE_THREAD ,
 348 or
 349 .BR CLONE_VM .
 350 .\" However, we can do unshare(CLONE_VM) if CLONE_VM
 351 .\" was not specified when doing clone(); i.e., unsharing
 352 .\" virtual memory is permitted if we are not actually
 353 .\" sharing virtual memory.   mtk
 354 Such functionality may be added in the future, if required.
 355 .\"
 356 .\"9) Future Work
 357 .\"--------------
 358 .\"The current implementation of unshare does not allow unsharing of
 359 .\"signals and signal handlers. Signals are complex to begin with and
 360 .\"to unshare signals and/or signal handlers of a currently running
 361 .\"process is even more complex. If in the future there is a specific
 362 .\"need to allow unsharing of signals and/or signal handlers, it can
 363 .\"be incrementally added to unshare without affecting legacy
 364 .\"applications using unshare.
 365 .\"
 366 .SH EXAMPLE
 367 The program below provides a simple implementation of the
 368 .BR unshare (1)
 369 command, which unshares one or more namespaces and executes the
 370 command supplied in its command-line arguments.
 371 Here's an example of the use of this program,
 372 running a shell in a new mount namespace,
 373 and verifying that the original shell and the
 374 new shell are in separate mount namespaces:
 375 .in +4n
 376 .nf
 377
 378 $ \fBreadlink /proc/$$/ns/mnt\fP
 379 mnt:[4026531840]
 380 $ \fBsudo ./unshare -m /bin/bash\fP
 381 [sudo] password for cecilia:
 382 # \fBreadlink /proc/$$/ns/mnt\fP
 383 mnt:[4026532325]
 384 .fi
 385 .in
 386
 387 The differing output of the two
 388 .BR readlink (1)
 389 commands shows that the two shells are in different mount namespaces.
 390 .SS Program source
 391 \&
 392 .nf
 393 /* unshare.c
 394
 395    A simple implementation of the unshare(1) command: unshare
 396    namespaces and execute a command.
 397 */
 398 #define _GNU_SOURCE
 399 #include <sched.h>
 400 #include <unistd.h>
 401 #include <stdlib.h>
 402 #include <stdio.h>
 403
 404 /* A simple error\-handling function: print an error message based
 405    on the value in \(aqerrno\(aq and terminate the calling process */
 406
 407 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \\
 408                         } while (0)
 409
 410 static void
 411 usage(char *pname)
 412 {
 413     fprintf(stderr, "Usage: %s [options] program [arg...]\\n", pname);
 414     fprintf(stderr, "Options can be:\\n");
 415     fprintf(stderr, "    \-i   unshare IPC namespace\\n");
 416     fprintf(stderr, "    \-m   unshare mount namespace\\n");
 417     fprintf(stderr, "    \-n   unshare network namespace\\n");
 418     fprintf(stderr, "    \-p   unshare PID namespace\\n");
 419     fprintf(stderr, "    \-u   unshare UTS namespace\\n");
 420     fprintf(stderr, "    \-U   unshare user namespace\\n");
 421     exit(EXIT_FAILURE);
 422 }
 423
 424 int
 425 main(int argc, char *argv[])
 426 {
 427     int flags, opt;
 428
 429     flags = 0;
 430
 431     while ((opt = getopt(argc, argv, "imnpuU")) != \-1) {
 432         switch (opt) {
 433         case \(aqi\(aq: flags |= CLONE_NEWIPC;        break;
 434         case \(aqm\(aq: flags |= CLONE_NEWNS;         break;
 435         case \(aqn\(aq: flags |= CLONE_NEWNET;        break;
 436         case \(aqp\(aq: flags |= CLONE_NEWPID;        break;
 437         case \(aqu\(aq: flags |= CLONE_NEWUTS;        break;
 438         case \(aqU\(aq: flags |= CLONE_NEWUSER;       break;
 439         default:  usage(argv[0]);
 440         }
 441     }
 442
 443     if (optind >= argc)
 444         usage(argv[0]);
 445
 446     if (unshare(flags) == \-1)
 447         errExit("unshare");
 448
 449     execvp(argv[optind], &argv[optind]);
 450     errExit("execvp");
 451 }
 452 .fi
 453 .SH SEE ALSO
 454 .BR unshare (1),
 455 .BR clone (2),
 456 .BR fork (2),
 457 .BR kcmp (2),
 458 .BR setns (2),
 459 .BR vfork (2),
 460 .BR namespaces (7)
 461
 462 .I Documentation/unshare.txt
 463 in the Linux kernel source tree