original/man2/unshare.2

   1 .\" Copyright (C) 2006, Janak Desai <janak@us.ibm.com>
   2 .\" and Copyright (C) 2006, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\" Licensed under the GPL
   4 .\"
   5 .\" Patch Justification:
   6 .\" unshare system call is needed to implement, using PAM,
   7 .\" per-security_context and/or per-user namespace to provide
   8 .\" polyinstantiated directories. Using unshare and bind mounts, a
   9 .\" PAM module can create private namespace with appropriate
  10 .\" directories(based on user's security context) bind mounted on
  11 .\" public directories such as /tmp, thus providing an instance of
  12 .\" /tmp that is based on user's security context. Without the
  13 .\" unshare system call, namespace separation can only be achieved
  14 .\" by clone, which would require porting and maintaining all commands
  15 .\" such as login, and su, that establish a user session.
  16 .\"
  17 .TH UNSHARE 2 2010-10-30 "Linux" "Linux Programmer's Manual"
  18 .SH NAME
  19 unshare \- disassociate parts of the process execution context
  20 .SH SYNOPSIS
  21 .nf
  22 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  23 .\" Actually _BSD_SOURCE || _SVID_SOURCE
  24 .\" FIXME See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749
  25 .B #include <sched.h>
  26 .sp
  27 .BI "int unshare(int " flags );
  28 .fi
  29 .SH DESCRIPTION
  30 .BR unshare ()
  31 allows a process to disassociate parts of its execution
  32 context that are currently being shared with other processes.
  33 Part of the execution context, such as the mount namespace, is shared
  34 implicitly when a new process is created using
  35 .BR fork (2)
  36 or
  37 .BR vfork (2),
  38 while other parts, such as virtual memory, may be
  39 shared by explicit request when creating a process using
  40 .BR clone (2).
  41
  42 The main use of
  43 .BR unshare ()
  44 is to allow a process to control its
  45 shared execution context without creating a new process.
  46
  47 The
  48 .I flags
  49 argument is a bit mask that specifies which parts of
  50 the execution context should be unshared.
  51 This argument is specified by ORing together zero or more
  52 of the following constants:
  53 .TP
  54 .B CLONE_FILES
  55 Reverse the effect of the
  56 .BR clone (2)
  57 .B CLONE_FILES
  58 flag.
  59 Unshare the file descriptor table, so that the calling process
  60 no longer shares its file descriptors with any other process.
  61 .TP
  62 .B CLONE_FS
  63 Reverse the effect of the
  64 .BR clone (2)
  65 .B CLONE_FS
  66 flag.
  67 Unshare file system attributes, so that the calling process
  68 no longer shares its root directory, current directory,
  69 or umask attributes with any other process.
  70 .BR chroot (2),
  71 .BR chdir (2),
  72 or
  73 .BR umask (2)
  74 .TP
  75 .BR CLONE_NEWIPC " (since Linux 2.6.19)
  76 This flag has the same effect as the
  77 .BR clone (2)
  78 .B CLONE_NEWIPC
  79 flag.
  80 Unshare the System V IPC namespace,
  81 so that the calling process has a private copy of the
  82 System V IPC namespace which is not shared with any other process.
  83 Specifying this flag automatically implies
  84 .BR CLONE_SYSVSEM
  85 as well.
  86 Use of
  87 .BR CLONE_NEWIPC
  88 requires the
  89 .BR CAP_SYS_ADMIN
  90 capability.
  91 .TP
  92 .BR CLONE_NEWNET " (since Linux 2.6.24)
  93 This flag has the same effect as the
  94 .BR clone (2)
  95 .B CLONE_NEWNET
  96 flag.
  97 Unshare the network namespace,
  98 so that the calling process is moved into a
  99 new network namespace which is not shared
 100 with any previously existing process.
 101 .BR CLONE_NEWNET
 102 requires the
 103 .BR CAP_SYS_ADMIN
 104 capability.
 105 .TP
 106 .B CLONE_NEWNS
 107 .\" These flag name are inconsistent:
 108 .\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM,
 109 .\" CLONE_FS, and CLONE_FILES reverse the action of the clone()
 110 .\" flags of the same name.
 111 This flag has the same effect as the
 112 .BR clone (2)
 113 .B CLONE_NEWNS
 114 flag.
 115 Unshare the mount namespace,
 116 so that the calling process has a private copy of
 117 its namespace which is not shared with any other process.
 118 Specifying this flag automatically implies
 119 .B CLONE_FS
 120 as well.
 121 Use of
 122 .BR CLONE_NEWNS
 123 requires the
 124 .BR CAP_SYS_ADMIN
 125 capability.
 126 .TP
 127 .BR CLONE_SYSVSEM " (since Linux 2.6.26)
 128 This flag reverses the effect of the
 129 .BR clone (2)
 130 .B CLONE_SYSVSEM
 131 flag.
 132 Unshare System V semaphore undo values,
 133 so that the calling process has a private copy
 134 which is not shared with any other process.
 135 Use of
 136 .BR CLONE_SYSVSEM
 137 requires the
 138 .BR CAP_SYS_ADMIN
 139 capability.
 140 .TP
 141 .BR CLONE_NEWUTS " (since Linux 2.6.19)
 142 This flag has the same effect as the
 143 .BR clone (2)
 144 .B CLONE_NEWUTS
 145 flag.
 146 Unshare the UTS IPC namespace,
 147 so that the calling process has a private copy of the
 148 UTS namespace which is not shared with any other process.
 149 Use of
 150 .BR CLONE_NEWUTS
 151 requires the
 152 .BR CAP_SYS_ADMIN
 153 capability.
 154 .\" As at 2.6.16, the following forced implications also apply,
 155 .\" although the relevant flags are not yet implemented.
 156 .\" If CLONE_THREAD is set force CLONE_VM.
 157 .\" If CLONE_VM is set, force CLONE_SIGHAND.
 158 .\" CLONE_NEWNSIf CLONE_SIGHAND is set and signals are also being shared
 159 .\" (i.e., current->signal->count > 1), force CLONE_THREAD.
 160 .\"
 161 .\" FIXME . CLONE_VM is not (yet, as at 2.6.16) implemented.
 162 .\" .TP
 163 .\" .B CLONE_VM
 164 .\" Reverse the effect of the
 165 .\" .BR clone (2)
 166 .\" .B CLONE_VM
 167 .\" flag.
 168 .\" .RB ( CLONE_VM
 169 .\" is also implicitly set by
 170 .\" .BR vfork (2),
 171 .\" and can be reversed using this
 172 .\" .BR unshare ()
 173 .\" flag.)
 174 .\" Unshare virtual memory, so that the calling process no
 175 .\" longer shares its virtual address space with any other process.
 176 .PP
 177 If
 178 .I flags
 179 is specified as zero, then
 180 .BR unshare ()
 181 is a no-op;
 182 no changes are made to the calling process's execution context.
 183 .SH RETURN VALUE
 184 On success, zero returned.
 185 On failure, \-1 is returned and
 186 .I errno
 187 is set to indicate the error.
 188 .SH ERRORS
 189 .TP
 190 .B EINVAL
 191 An invalid bit was specified in
 192 .IR flags .
 193 .TP
 194 .B ENOMEM
 195 Cannot allocate sufficient memory to copy parts of caller's
 196 context that need to be unshared.
 197 .TP
 198 .B EPERM
 199 The calling process did not have the required privileges for this operation.
 200 .SH VERSIONS
 201 The
 202 .BR unshare ()
 203 system call was added to Linux in kernel 2.6.16.
 204 .SH CONFORMING TO
 205 The
 206 .BR unshare ()
 207 system call is Linux-specific.
 208 .SH NOTES
 209 Not all of the process attributes that can be shared when
 210 a new process is created using
 211 .BR clone (2)
 212 can be unshared using
 213 .BR unshare ().
 214 In particular, as at kernel 2.6.16,
 215 .BR unshare ()
 216 does not implement flags that reverse the effects of
 217 .BR CLONE_SIGHAND ,
 218 .\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND
 219 .\" was not specified when doing clone(); i.e., unsharing
 220 .\" signal handlers is permitted if we are not actually
 221 .\" sharing signal handlers.   mtk
 222 .BR CLONE_SYSVSEM ,
 223 .BR CLONE_THREAD ,
 224 or
 225 .\" FIXME . check future kernel versions (e.g., 2.6.17)
 226 .\" to see if CLONE_VM gets implemented.
 227 .BR CLONE_VM .
 228 .\" However, as at 2.6.16, we can do unshare(CLONE_VM) if CLONE_VM
 229 .\" was not specified when doing clone(); i.e., unsharing
 230 .\" virtual memory is permitted if we are not actually
 231 .\" sharing virtual memory.   mtk
 232 Such functionality may be added in the future, if required.
 233 .\"
 234 .\"9) Future Work
 235 .\"--------------
 236 .\"The current implementation of unshare does not allow unsharing of
 237 .\"signals and signal handlers. Signals are complex to begin with and
 238 .\"to unshare signals and/or signal handlers of a currently running
 239 .\"process is even more complex. If in the future there is a specific
 240 .\"need to allow unsharing of signals and/or signal handlers, it can
 241 .\"be incrementally added to unshare without affecting legacy
 242 .\"applications using unshare.
 243 .\"
 244 .SH SEE ALSO
 245 .BR clone (2),
 246 .BR fork (2),
 247 .BR vfork (2),
 248 Documentation/unshare.txt