]>
Commit | Line | Data |
---|---|---|
1 | .\" Copyright (C) 2006, Janak Desai <janak@us.ibm.com> | |
2 | .\" and Copyright (C) 2006, 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 2013-04-17 "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_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 | |
164 | .BR CLONE_SYSVSEM " (since Linux 2.6.26) | |
165 | .\" commit 9edff4ab1f8d82675277a04e359d0ed8bf14a7b7 | |
166 | This flag reverses the effect of the | |
167 | .BR clone (2) | |
168 | .B CLONE_SYSVSEM | |
169 | flag. | |
170 | Unshare System\ V semaphore undo values, | |
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. | |
178 | .\" As at 2.6.16, the following forced implications also apply, | |
179 | .\" although the relevant flags are not yet implemented. | |
180 | .\" If CLONE_THREAD is set force CLONE_VM. | |
181 | .\" If CLONE_VM is set, force CLONE_SIGHAND. | |
182 | .\" CLONE_NEWNSIf CLONE_SIGHAND is set and signals are also being shared | |
183 | .\" (i.e., current->signal->count > 1), force CLONE_THREAD. | |
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.) | |
198 | .\" Unshare virtual memory, so that the calling process no | |
199 | .\" longer shares its virtual address space with any other process. | |
200 | .PP | |
201 | If | |
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 | |
208 | On success, zero returned. | |
209 | On failure, \-1 is returned and | |
210 | .I errno | |
211 | is set to indicate the error. | |
212 | .SH ERRORS | |
213 | .TP | |
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 | |
222 | .B EPERM | |
223 | The calling process did not have the required privileges for this operation. | |
224 | .SH VERSIONS | |
225 | The | |
226 | .BR unshare () | |
227 | system call was added to Linux in kernel 2.6.16. | |
228 | .SH CONFORMING TO | |
229 | The | |
230 | .BR unshare () | |
231 | system call is Linux-specific. | |
232 | .SH NOTES | |
233 | Not all of the process attributes that can be shared when | |
234 | a new process is created using | |
235 | .BR clone (2) | |
236 | can be unshared using | |
237 | .BR unshare (). | |
238 | In particular, as at kernel 3.8, | |
239 | .\" FIXME all of the following needs to be reviewed for the current kernel | |
240 | .BR unshare () | |
241 | does not implement flags that reverse the effects of | |
242 | .BR CLONE_SIGHAND , | |
243 | .\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND | |
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 | |
247 | .BR CLONE_THREAD , | |
248 | or | |
249 | .BR CLONE_VM . | |
250 | .\" However, we can do unshare(CLONE_VM) if CLONE_VM | |
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 | |
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 | |
267 | .BR clone (2), | |
268 | .BR fork (2), | |
269 | .BR kcmp (2), | |
270 | .BR setns (2), | |
271 | .BR vfork (2) | |
272 | ||
273 | .I Documentation/unshare.txt | |
274 | in the Linux kernel source tree |