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