]>
Commit | Line | Data |
---|---|---|
f50f6cb5 | 1 | .\" Copyright (C) 2006, Janak Desai <janak@us.ibm.com> |
f919b6e4 | 2 | .\" and Copyright (C) 2006, 2012 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 | .\" |
c73595c2 | 20 | .TH UNSHARE 2 2015-04-19 "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 () |
15784e0a | 52 | allows a process (or thread) to disassociate parts of its execution |
f0d0f68d | 53 | context that are currently being shared with other processes (or threads). |
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 |
15784e0a | 60 | shared by explicit request when creating a process or thread 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. | |
1024e8ff | 102 | Unshare the IPC namespace, |
25539b1b | 103 | so that the calling process has a private copy of the |
1024e8ff | 104 | 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 |
8f141c5e MK |
150 | .BR CLONE_NEWPID " (since Linux 3.8)" |
151 | This flag has the same effect as the | |
152 | .BR clone (2) | |
153 | .B CLONE_NEWPID | |
154 | flag. | |
155 | Unshare the PID namespace, | |
37ee2d61 | 156 | so that the calling process has a new PID namespace for its children |
8f141c5e | 157 | which is not shared with any previously existing process. |
2193656a MK |
158 | The calling process is |
159 | .I not | |
160 | moved into the new namespace. | |
161 | The first child created by the calling process will have | |
162 | the process ID 1 and will assume the role of | |
163 | .BR init (1) | |
164 | in the new namespace. | |
3c881e7c MK |
165 | .BR CLONE_NEWPID |
166 | automatically implies | |
167 | .BR CLONE_THREAD | |
168 | as well. | |
8f141c5e MK |
169 | Use of |
170 | .BR CLONE_NEWPID | |
171 | requires the | |
172 | .BR CAP_SYS_ADMIN | |
173 | capability. | |
5c8d010b MK |
174 | For further information, see |
175 | .BR pid_namespaces (7). | |
8f141c5e | 176 | .TP |
c2cd5a7f MK |
177 | .BR CLONE_NEWUSER " (since Linux 3.8)" |
178 | This flag has the same effect as the | |
179 | .BR clone (2) | |
180 | .B CLONE_NEWUSER | |
181 | flag. | |
182 | Unshare the user namespace, | |
183 | so that the calling process is moved into a new user namespace | |
184 | which is not shared with any previously existing process. | |
5afd65d1 | 185 | As with the child process created by |
36ec1f75 MK |
186 | .BR clone (2) |
187 | with the | |
188 | .B CLONE_NEWUSER | |
189 | flag, the caller obtains a full set of capabilities in the new namespace. | |
88f48716 MK |
190 | .IP |
191 | .BR CLONE_NEWUSER | |
192 | requires that the calling process is not threaded; specifying | |
193 | .BR CLONE_NEWUSER | |
194 | automatically implies | |
4c3d7431 | 195 | .BR CLONE_THREAD . |
6bab36f8 | 196 | Since Linux 3.9, |
4c3d7431 MK |
197 | .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 |
198 | .\" https://lwn.net/Articles/543273/ | |
6bab36f8 MK |
199 | .BR CLONE_NEWUSER |
200 | also automatically implies | |
201 | .BR CLONE_FS . | |
37ee2d61 | 202 | .BR CLONE_NEWUSER |
88f48716 | 203 | requires that the user ID and group ID |
6f6808f9 | 204 | of the calling process are mapped to user IDs and group IDs in the |
37ee2d61 | 205 | user namespace of the calling process at the time of the call. |
f647dc5e MK |
206 | |
207 | For further information on user namespaces, see | |
333446b9 | 208 | .BR user_namespaces (7). |
c2cd5a7f | 209 | .TP |
667f4c78 | 210 | .BR CLONE_NEWUTS " (since Linux 2.6.19)" |
78449461 MK |
211 | This flag has the same effect as the |
212 | .BR clone (2) | |
213 | .B CLONE_NEWUTS | |
214 | flag. | |
215 | Unshare the UTS IPC namespace, | |
216 | so that the calling process has a private copy of the | |
217 | UTS namespace which is not shared with any other process. | |
218 | Use of | |
219 | .BR CLONE_NEWUTS | |
220 | requires the | |
221 | .BR CAP_SYS_ADMIN | |
222 | capability. | |
223 | .TP | |
a948ae52 | 224 | .BR CLONE_SYSVSEM " (since Linux 2.6.26) |
29015225 | 225 | .\" commit 9edff4ab1f8d82675277a04e359d0ed8bf14a7b7 |
a948ae52 MK |
226 | This flag reverses the effect of the |
227 | .BR clone (2) | |
228 | .B CLONE_SYSVSEM | |
229 | flag. | |
0d829b76 MK |
230 | Unshare System\ V semaphore adjustment |
231 | .RI ( semadj ) | |
232 | values, | |
233 | so that the calling process has a new empty | |
234 | .I semadj | |
235 | list that is not shared with any other process. | |
236 | If this is the last process that has a reference to the process's current | |
237 | .I semadj | |
238 | list, then the adjustments in that list are applied | |
239 | to the corresponding semaphores, as described in | |
240 | .BR semop (2). | |
eb359a09 | 241 | .\" CLONE_NEWNS If CLONE_SIGHAND is set and signals are also being shared |
5cc01e9c | 242 | .\" (i.e., current->signal->count > 1), force CLONE_THREAD. |
3d5f4595 | 243 | .PP |
4dd85833 MK |
244 | In addition, |
245 | .BR CLONE_THREAD , | |
246 | .BR CLONE_SIGHAND , | |
247 | and | |
248 | .BR CLONE_VM | |
249 | can be specified in | |
250 | .I flags | |
251 | if the caller is single threaded (i.e., it is not sharing | |
252 | its address space with another process or thread). | |
253 | In this case, these flags have no effect. | |
130fbed6 MK |
254 | (Note also that specifying |
255 | .BR CLONE_THREAD | |
256 | automatically implies | |
257 | .BR CLONE_VM , | |
258 | and specifying | |
259 | .BR CLONE_VM | |
260 | automatically implies | |
261 | .BR CLONE_SIGHAND .) | |
f231195f MK |
262 | .\" As at 3.9, the following forced implications also apply, |
263 | .\" although the relevant flags are not yet implemented. | |
264 | .\" If CLONE_THREAD is set force CLONE_VM. | |
265 | .\" If CLONE_VM is set, force CLONE_SIGHAND. | |
266 | .\" | |
4dd85833 MK |
267 | If the process is multithreaded, then |
268 | the use of these flags results in an error. | |
269 | .\" See kernel/fork.c::check_unshare_flags() | |
270 | .PP | |
c13182ef | 271 | If |
5cc01e9c MK |
272 | .I flags |
273 | is specified as zero, then | |
274 | .BR unshare () | |
275 | is a no-op; | |
276 | no changes are made to the calling process's execution context. | |
277 | .SH RETURN VALUE | |
c13182ef MK |
278 | On success, zero returned. |
279 | On failure, \-1 is returned and | |
280 | .I errno | |
5cc01e9c MK |
281 | is set to indicate the error. |
282 | .SH ERRORS | |
283 | .TP | |
eab64696 MK |
284 | .B EINVAL |
285 | An invalid bit was specified in | |
286 | .IR flags . | |
287 | .TP | |
4dd85833 MK |
288 | .B EINVAL |
289 | .BR CLONE_THREAD , | |
290 | .BR CLONE_SIGHAND , | |
291 | or | |
292 | .BR CLONE_VM | |
293 | was specified in | |
294 | .IR flags , | |
295 | and the caller is multithreaded. | |
296 | .TP | |
eab64696 MK |
297 | .B ENOMEM |
298 | Cannot allocate sufficient memory to copy parts of caller's | |
299 | context that need to be unshared. | |
300 | .TP | |
5cc01e9c | 301 | .B EPERM |
486d4e9b | 302 | The calling process did not have the required privileges for this operation. |
365d292a MK |
303 | .TP |
304 | .B EPERM | |
305 | .BR CLONE_NEWUSER | |
306 | was specified in | |
307 | .IR flags , | |
308 | but either the effective user ID or the effective group ID of the caller | |
309 | does not have a mapping in the parent namespace (see | |
f58fb24f | 310 | .BR user_namespaces (7)). |
cdd25f2e | 311 | .TP |
40a47a16 MK |
312 | .BR EPERM " (since Linux 3.9)" |
313 | .\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d | |
12f74390 AM |
314 | .B CLONE_NEWUSER |
315 | was specified in | |
40a47a16 MK |
316 | .I flags |
317 | and the caller is in a chroot environment | |
318 | .\" FIXME What is the rationale for this restriction? | |
319 | (i.e., the caller's root directory does not match the root directory | |
320 | of the mount namespace in which it resides). | |
321 | .TP | |
322 | .BR EUSERS " (since Linux 3.11)" | |
cdd25f2e MK |
323 | .B CLONE_NEWUSER |
324 | was specified in | |
325 | .IR flags , | |
326 | and the call would cause the limit on the number of | |
327 | nested user namespaces to be exceeded. | |
328 | See | |
329 | .BR user_namespaces (7). | |
ff457ccb | 330 | .SH VERSIONS |
5cc01e9c MK |
331 | The |
332 | .BR unshare () | |
333 | system call was added to Linux in kernel 2.6.16. | |
2dd578fd MK |
334 | .SH CONFORMING TO |
335 | The | |
336 | .BR unshare () | |
8382f16d | 337 | system call is Linux-specific. |
ff457ccb | 338 | .SH NOTES |
c13182ef | 339 | Not all of the process attributes that can be shared when |
5cc01e9c MK |
340 | a new process is created using |
341 | .BR clone (2) | |
342 | can be unshared using | |
343 | .BR unshare (). | |
3c4e652d | 344 | In particular, as at kernel 3.8, |
f26fe082 | 345 | .\" FIXME all of the following needs to be reviewed for the current kernel |
c13182ef | 346 | .BR unshare () |
5cc01e9c MK |
347 | does not implement flags that reverse the effects of |
348 | .BR CLONE_SIGHAND , | |
3d5f4595 | 349 | .\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND |
5cc01e9c MK |
350 | .\" was not specified when doing clone(); i.e., unsharing |
351 | .\" signal handlers is permitted if we are not actually | |
352 | .\" sharing signal handlers. mtk | |
3d5f4595 MK |
353 | .BR CLONE_THREAD , |
354 | or | |
3d5f4595 | 355 | .BR CLONE_VM . |
3c4e652d | 356 | .\" However, we can do unshare(CLONE_VM) if CLONE_VM |
3d5f4595 MK |
357 | .\" was not specified when doing clone(); i.e., unsharing |
358 | .\" virtual memory is permitted if we are not actually | |
359 | .\" sharing virtual memory. mtk | |
5cc01e9c MK |
360 | Such functionality may be added in the future, if required. |
361 | .\" | |
362 | .\"9) Future Work | |
363 | .\"-------------- | |
364 | .\"The current implementation of unshare does not allow unsharing of | |
365 | .\"signals and signal handlers. Signals are complex to begin with and | |
366 | .\"to unshare signals and/or signal handlers of a currently running | |
367 | .\"process is even more complex. If in the future there is a specific | |
368 | .\"need to allow unsharing of signals and/or signal handlers, it can | |
369 | .\"be incrementally added to unshare without affecting legacy | |
370 | .\"applications using unshare. | |
371 | .\" | |
f919b6e4 MK |
372 | .SH EXAMPLE |
373 | The program below provides a simple implementation of the | |
374 | .BR unshare (1) | |
375 | command, which unshares one or more namespaces and executes the | |
08e54e51 | 376 | command supplied in its command-line arguments. |
f919b6e4 MK |
377 | Here's an example of the use of this program, |
378 | running a shell in a new mount namespace, | |
379 | and verifying that the original shell and the | |
380 | new shell are in separate mount namespaces: | |
381 | .in +4n | |
382 | .nf | |
383 | ||
384 | $ \fBreadlink /proc/$$/ns/mnt\fP | |
385 | mnt:[4026531840] | |
386 | $ \fBsudo ./unshare -m /bin/bash\fP | |
387 | [sudo] password for cecilia: | |
388 | # \fBreadlink /proc/$$/ns/mnt\fP | |
389 | mnt:[4026532325] | |
390 | .fi | |
391 | .in | |
392 | ||
393 | The differing output of the two | |
394 | .BR readlink (1) | |
395 | commands shows that the two shells are in different mount namespaces. | |
396 | .SS Program source | |
397 | \& | |
398 | .nf | |
f5d401dd | 399 | /* unshare.c |
f919b6e4 MK |
400 | |
401 | A simple implementation of the unshare(1) command: unshare | |
402 | namespaces and execute a command. | |
403 | */ | |
404 | #define _GNU_SOURCE | |
405 | #include <sched.h> | |
406 | #include <unistd.h> | |
407 | #include <stdlib.h> | |
408 | #include <stdio.h> | |
409 | ||
410 | /* A simple error\-handling function: print an error message based | |
411 | on the value in \(aqerrno\(aq and terminate the calling process */ | |
412 | ||
413 | #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ | |
414 | } while (0) | |
415 | ||
416 | static void | |
417 | usage(char *pname) | |
418 | { | |
419 | fprintf(stderr, "Usage: %s [options] program [arg...]\\n", pname); | |
420 | fprintf(stderr, "Options can be:\\n"); | |
421 | fprintf(stderr, " \-i unshare IPC namespace\\n"); | |
422 | fprintf(stderr, " \-m unshare mount namespace\\n"); | |
423 | fprintf(stderr, " \-n unshare network namespace\\n"); | |
424 | fprintf(stderr, " \-p unshare PID namespace\\n"); | |
425 | fprintf(stderr, " \-u unshare UTS namespace\\n"); | |
426 | fprintf(stderr, " \-U unshare user namespace\\n"); | |
427 | exit(EXIT_FAILURE); | |
428 | } | |
429 | ||
430 | int | |
431 | main(int argc, char *argv[]) | |
432 | { | |
433 | int flags, opt; | |
434 | ||
435 | flags = 0; | |
436 | ||
437 | while ((opt = getopt(argc, argv, "imnpuU")) != \-1) { | |
438 | switch (opt) { | |
439 | case \(aqi\(aq: flags |= CLONE_NEWIPC; break; | |
440 | case \(aqm\(aq: flags |= CLONE_NEWNS; break; | |
441 | case \(aqn\(aq: flags |= CLONE_NEWNET; break; | |
442 | case \(aqp\(aq: flags |= CLONE_NEWPID; break; | |
443 | case \(aqu\(aq: flags |= CLONE_NEWUTS; break; | |
444 | case \(aqU\(aq: flags |= CLONE_NEWUSER; break; | |
445 | default: usage(argv[0]); | |
446 | } | |
447 | } | |
448 | ||
449 | if (optind >= argc) | |
450 | usage(argv[0]); | |
451 | ||
452 | if (unshare(flags) == \-1) | |
453 | errExit("unshare"); | |
454 | ||
f5d401dd | 455 | execvp(argv[optind], &argv[optind]); |
f919b6e4 MK |
456 | errExit("execvp"); |
457 | } | |
458 | .fi | |
5cc01e9c | 459 | .SH SEE ALSO |
e939d607 | 460 | .BR unshare (1), |
c13182ef MK |
461 | .BR clone (2), |
462 | .BR fork (2), | |
19a98048 | 463 | .BR kcmp (2), |
47b0eb1e | 464 | .BR setns (2), |
3d02560d | 465 | .BR vfork (2), |
41096af1 | 466 | .BR namespaces (7) |
173fe7e7 DP |
467 | |
468 | .I Documentation/unshare.txt | |
469 | in the Linux kernel source tree |