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