]>
Commit | Line | Data |
---|---|---|
f50f6cb5 MK |
1 | .\" Copyright (C) 2006, Janak Desai <janak@us.ibm.com> |
2 | .\" and Copyright (C) 2006, Michael Kerrisk <mtk.manpages@gmail.com> | |
2297bf0e | 3 | .\" |
b55e2bb3 | 4 | .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) |
5cc01e9c | 5 | .\" Licensed under the GPL |
b55e2bb3 | 6 | .\" %%%LICENSE_END |
5cc01e9c | 7 | .\" |
d44c4bf3 | 8 | .\" Patch Justification: |
c13182ef MK |
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. | |
d44c4bf3 | 19 | .\" |
9a86ff91 | 20 | .TH UNSHARE 2 2013-04-17 "Linux" "Linux Programmer's Manual" |
5cc01e9c MK |
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 | |
d4919824 MK |
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 | |
cba9638b | 43 | .\" See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749 |
d4919824 MK |
44 | Before glibc 2.14: |
45 | _BSD_SOURCE || _SVID_SOURCE | |
46 | /* _GNU_SOURCE also suffices */ | |
47 | .PD | |
48 | .RE | |
49 | .ad b | |
5cc01e9c | 50 | .SH DESCRIPTION |
c13182ef | 51 | .BR unshare () |
5cc01e9c | 52 | allows a process to disassociate parts of its execution |
c13182ef | 53 | context that are currently being shared with other processes. |
732e54dd | 54 | Part of the execution context, such as the mount namespace, is shared |
c13182ef | 55 | implicitly when a new process is created using |
5cc01e9c MK |
56 | .BR fork (2) |
57 | or | |
c13182ef | 58 | .BR vfork (2), |
5cc01e9c | 59 | while other parts, such as virtual memory, may be |
c13182ef | 60 | shared by explicit request when creating a process using |
5cc01e9c MK |
61 | .BR clone (2). |
62 | ||
c13182ef | 63 | The main use of |
5cc01e9c MK |
64 | .BR unshare () |
65 | is to allow a process to control its | |
66 | shared execution context without creating a new process. | |
67 | ||
c13182ef MK |
68 | The |
69 | .I flags | |
70 | argument is a bit mask that specifies which parts of | |
71 | the execution context should be unshared. | |
5cc01e9c MK |
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. | |
c13182ef | 80 | Unshare the file descriptor table, so that the calling process |
5cc01e9c MK |
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) | |
c13182ef | 86 | .B CLONE_FS |
5cc01e9c | 87 | flag. |
9ee4a2b6 | 88 | Unshare filesystem attributes, so that the calling process |
f7b8bdbe MK |
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. | |
5cc01e9c | 96 | .TP |
25539b1b MK |
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. | |
efbfd7ec | 102 | Unshare the System\ V IPC namespace, |
25539b1b | 103 | so that the calling process has a private copy of the |
efbfd7ec | 104 | System\ V IPC namespace which is not shared with any other process. |
25539b1b MK |
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 | |
b3bc5386 MK |
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, | |
61f22790 LAG |
120 | so that the calling process is moved into a |
121 | new network namespace which is not shared | |
122 | with any previously existing process. | |
6f2b4a65 | 123 | Use of |
b3bc5386 MK |
124 | .BR CLONE_NEWNET |
125 | requires the | |
126 | .BR CAP_SYS_ADMIN | |
127 | capability. | |
128 | .TP | |
5cc01e9c MK |
129 | .B CLONE_NEWNS |
130 | .\" These flag name are inconsistent: | |
c13182ef | 131 | .\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM, |
5cc01e9c MK |
132 | .\" CLONE_FS, and CLONE_FILES reverse the action of the clone() |
133 | .\" flags of the same name. | |
c8e4c1bd | 134 | This flag has the same effect as the |
5cc01e9c MK |
135 | .BR clone (2) |
136 | .B CLONE_NEWNS | |
137 | flag. | |
732e54dd | 138 | Unshare the mount namespace, |
4df2eb09 | 139 | so that the calling process has a private copy of |
5cc01e9c MK |
140 | its namespace which is not shared with any other process. |
141 | Specifying this flag automatically implies | |
142 | .B CLONE_FS | |
143 | as well. | |
486d4e9b MK |
144 | Use of |
145 | .BR CLONE_NEWNS | |
146 | requires the | |
147 | .BR CAP_SYS_ADMIN | |
148 | capability. | |
a948ae52 | 149 | .TP |
78449461 MK |
150 | .BR CLONE_NEWUTS " (since Linux 2.6.19) |
151 | This flag has the same effect as the | |
152 | .BR clone (2) | |
153 | .B CLONE_NEWUTS | |
154 | flag. | |
155 | Unshare the UTS IPC namespace, | |
156 | so that the calling process has a private copy of the | |
157 | UTS namespace which is not shared with any other process. | |
158 | Use of | |
159 | .BR CLONE_NEWUTS | |
160 | requires the | |
161 | .BR CAP_SYS_ADMIN | |
162 | capability. | |
163 | .TP | |
a948ae52 | 164 | .BR CLONE_SYSVSEM " (since Linux 2.6.26) |
29015225 | 165 | .\" commit 9edff4ab1f8d82675277a04e359d0ed8bf14a7b7 |
a948ae52 MK |
166 | This flag reverses the effect of the |
167 | .BR clone (2) | |
168 | .B CLONE_SYSVSEM | |
169 | flag. | |
efbfd7ec | 170 | Unshare System\ V semaphore undo values, |
a948ae52 MK |
171 | so that the calling process has a private copy |
172 | which is not shared with any other process. | |
173 | Use of | |
174 | .BR CLONE_SYSVSEM | |
175 | requires the | |
176 | .BR CAP_SYS_ADMIN | |
177 | capability. | |
5cc01e9c | 178 | .\" As at 2.6.16, the following forced implications also apply, |
3d5f4595 | 179 | .\" although the relevant flags are not yet implemented. |
5cc01e9c | 180 | .\" If CLONE_THREAD is set force CLONE_VM. |
c13182ef | 181 | .\" If CLONE_VM is set, force CLONE_SIGHAND. |
486d4e9b | 182 | .\" CLONE_NEWNSIf CLONE_SIGHAND is set and signals are also being shared |
5cc01e9c | 183 | .\" (i.e., current->signal->count > 1), force CLONE_THREAD. |
3d5f4595 MK |
184 | .\" |
185 | .\" FIXME . CLONE_VM is not (yet, as at 2.6.16) implemented. | |
186 | .\" .TP | |
187 | .\" .B CLONE_VM | |
188 | .\" Reverse the effect of the | |
189 | .\" .BR clone (2) | |
190 | .\" .B CLONE_VM | |
191 | .\" flag. | |
192 | .\" .RB ( CLONE_VM | |
193 | .\" is also implicitly set by | |
194 | .\" .BR vfork (2), | |
195 | .\" and can be reversed using this | |
196 | .\" .BR unshare () | |
197 | .\" flag.) | |
c13182ef | 198 | .\" Unshare virtual memory, so that the calling process no |
3d5f4595 MK |
199 | .\" longer shares its virtual address space with any other process. |
200 | .PP | |
c13182ef | 201 | If |
5cc01e9c MK |
202 | .I flags |
203 | is specified as zero, then | |
204 | .BR unshare () | |
205 | is a no-op; | |
206 | no changes are made to the calling process's execution context. | |
207 | .SH RETURN VALUE | |
c13182ef MK |
208 | On success, zero returned. |
209 | On failure, \-1 is returned and | |
210 | .I errno | |
5cc01e9c MK |
211 | is set to indicate the error. |
212 | .SH ERRORS | |
213 | .TP | |
eab64696 MK |
214 | .B EINVAL |
215 | An invalid bit was specified in | |
216 | .IR flags . | |
217 | .TP | |
218 | .B ENOMEM | |
219 | Cannot allocate sufficient memory to copy parts of caller's | |
220 | context that need to be unshared. | |
221 | .TP | |
5cc01e9c | 222 | .B EPERM |
486d4e9b | 223 | The calling process did not have the required privileges for this operation. |
ff457ccb | 224 | .SH VERSIONS |
5cc01e9c MK |
225 | The |
226 | .BR unshare () | |
227 | system call was added to Linux in kernel 2.6.16. | |
2dd578fd MK |
228 | .SH CONFORMING TO |
229 | The | |
230 | .BR unshare () | |
8382f16d | 231 | system call is Linux-specific. |
ff457ccb | 232 | .SH NOTES |
c13182ef | 233 | Not all of the process attributes that can be shared when |
5cc01e9c MK |
234 | a new process is created using |
235 | .BR clone (2) | |
236 | can be unshared using | |
237 | .BR unshare (). | |
3c4e652d | 238 | In particular, as at kernel 3.8, |
f26fe082 | 239 | .\" FIXME all of the following needs to be reviewed for the current kernel |
c13182ef | 240 | .BR unshare () |
5cc01e9c MK |
241 | does not implement flags that reverse the effects of |
242 | .BR CLONE_SIGHAND , | |
3d5f4595 | 243 | .\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND |
5cc01e9c MK |
244 | .\" was not specified when doing clone(); i.e., unsharing |
245 | .\" signal handlers is permitted if we are not actually | |
246 | .\" sharing signal handlers. mtk | |
3d5f4595 MK |
247 | .BR CLONE_THREAD , |
248 | or | |
3d5f4595 | 249 | .BR CLONE_VM . |
3c4e652d | 250 | .\" However, we can do unshare(CLONE_VM) if CLONE_VM |
3d5f4595 MK |
251 | .\" was not specified when doing clone(); i.e., unsharing |
252 | .\" virtual memory is permitted if we are not actually | |
253 | .\" sharing virtual memory. mtk | |
5cc01e9c MK |
254 | Such functionality may be added in the future, if required. |
255 | .\" | |
256 | .\"9) Future Work | |
257 | .\"-------------- | |
258 | .\"The current implementation of unshare does not allow unsharing of | |
259 | .\"signals and signal handlers. Signals are complex to begin with and | |
260 | .\"to unshare signals and/or signal handlers of a currently running | |
261 | .\"process is even more complex. If in the future there is a specific | |
262 | .\"need to allow unsharing of signals and/or signal handlers, it can | |
263 | .\"be incrementally added to unshare without affecting legacy | |
264 | .\"applications using unshare. | |
265 | .\" | |
266 | .SH SEE ALSO | |
c13182ef MK |
267 | .BR clone (2), |
268 | .BR fork (2), | |
19a98048 | 269 | .BR kcmp (2), |
47b0eb1e | 270 | .BR setns (2), |
173fe7e7 DP |
271 | .BR vfork (2) |
272 | ||
273 | .I Documentation/unshare.txt | |
274 | in the Linux kernel source tree |