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