| blob | 851c2b20ec672825cd10ac11566dacb8ad15bc03 |
1 .\" Copyright (C) 2006, Janak Desai <janak@us.ibm.com>
2 .\" and Copyright (C) 2006, 2012 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 2021-03-22 "Linux" "Linux Programmer's Manual"
21 .SH NAME
22 unshare \- disassociate parts of the process execution context
23 .SH SYNOPSIS
24 .nf
25 .B #define _GNU_SOURCE
26 .B #include <sched.h>
27 .PP
28 .BI "int unshare(int " flags );
29 .fi
30 .SH DESCRIPTION
31 .BR unshare ()
32 allows a process (or thread) to disassociate parts of its execution
33 context that are currently being shared with other processes (or threads).
34 Part of the execution context, such as the mount namespace, is shared
35 implicitly when a new process is created using
36 .BR fork (2)
37 or
38 .BR vfork (2),
39 while other parts, such as virtual memory, may be
40 shared by explicit request when creating a process or thread using
41 .BR clone (2).
42 .PP
43 The main use of
44 .BR unshare ()
45 is to allow a process to control its
46 shared execution context without creating a new process.
47 .PP
48 The
49 .I flags
50 argument is a bit mask that specifies which parts of
51 the execution context should be unshared.
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.
60 Unshare the file descriptor table, so that the calling process
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)
66 .B CLONE_FS
67 flag.
68 Unshare filesystem attributes, so that the calling process
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.
76 .TP
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
89 .BR CLONE_NEWIPC " (since Linux 2.6.19)"
90 This flag has the same effect as the
91 .BR clone (2)
92 .B CLONE_NEWIPC
93 flag.
94 Unshare the IPC namespace,
95 so that the calling process has a private copy of the
96 IPC namespace which is not shared with any other process.
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
106 .BR CLONE_NEWNET " (since Linux 2.6.24)"
107 This flag has the same effect as the
108 .BR clone (2)
109 .B CLONE_NEWNET
110 flag.
111 Unshare the network namespace,
112 so that the calling process is moved into a
113 new network namespace which is not shared
114 with any previously existing process.
115 Use of
116 .BR CLONE_NEWNET
117 requires the
118 .BR CAP_SYS_ADMIN
119 capability.
120 .TP
121 .B CLONE_NEWNS
122 .\" These flag name are inconsistent:
123 .\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM,
124 .\" CLONE_FS, and CLONE_FILES reverse the action of the clone()
125 .\" flags of the same name.
126 This flag has the same effect as the
127 .BR clone (2)
128 .B CLONE_NEWNS
129 flag.
130 Unshare the mount namespace,
131 so that the calling process has a private copy of
132 its namespace which is not shared with any other process.
133 Specifying this flag automatically implies
134 .B CLONE_FS
135 as well.
136 Use of
137 .BR CLONE_NEWNS
138 requires the
139 .BR CAP_SYS_ADMIN
140 capability.
141 For further information, see
142 .BR mount_namespaces (7).
143 .TP
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,
150 so that the calling process has a new PID namespace for its children
151 which is not shared with any previously existing process.
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.
159 .BR CLONE_NEWPID
160 automatically implies
161 .BR CLONE_THREAD
162 as well.
163 Use of
164 .BR CLONE_NEWPID
165 requires the
166 .BR CAP_SYS_ADMIN
167 capability.
168 For further information, see
169 .BR pid_namespaces (7).
170 .TP
171 .BR CLONE_NEWTIME " (since Linux 5.6)"
172 Unshare the time namespace,
173 so that the calling process has a new time namespace for its children
174 which is not shared with any previously existing process.
175 The calling process is
176 .I not
177 moved into the new namespace.
178 Use of
179 .BR CLONE_NEWTIME
180 requires the
181 .BR CAP_SYS_ADMIN
182 capability.
183 For further information, see
184 .BR time_namespaces (7).
185 .TP
186 .BR CLONE_NEWUSER " (since Linux 3.8)"
187 This flag has the same effect as the
188 .BR clone (2)
189 .B CLONE_NEWUSER
190 flag.
191 Unshare the user namespace,
192 so that the calling process is moved into a new user namespace
193 which is not shared with any previously existing process.
194 As with the child process created by
195 .BR clone (2)
196 with the
197 .B CLONE_NEWUSER
198 flag, the caller obtains a full set of capabilities in the new namespace.
199 .IP
200 .BR CLONE_NEWUSER
201 requires that the calling process is not threaded; specifying
202 .BR CLONE_NEWUSER
203 automatically implies
204 .BR CLONE_THREAD .
205 Since Linux 3.9,
206 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
207 .\" https://lwn.net/Articles/543273/
208 .BR CLONE_NEWUSER
209 also automatically implies
210 .BR CLONE_FS .
211 .BR CLONE_NEWUSER
212 requires that the user ID and group ID
213 of the calling process are mapped to user IDs and group IDs in the
214 user namespace of the calling process at the time of the call.
215 .IP
216 For further information on user namespaces, see
217 .BR user_namespaces (7).
218 .TP
219 .BR CLONE_NEWUTS " (since Linux 2.6.19)"
220 This flag has the same effect as the
221 .BR clone (2)
222 .B CLONE_NEWUTS
223 flag.
224 Unshare the UTS IPC namespace,
225 so that the calling process has a private copy of the
226 UTS namespace which is not shared with any other process.
227 Use of
228 .BR CLONE_NEWUTS
229 requires the
230 .BR CAP_SYS_ADMIN
231 capability.
232 .TP
233 .BR CLONE_SYSVSEM " (since Linux 2.6.26)"
234 .\" commit 9edff4ab1f8d82675277a04e359d0ed8bf14a7b7
235 This flag reverses the effect of the
236 .BR clone (2)
237 .B CLONE_SYSVSEM
238 flag.
239 Unshare System\ V semaphore adjustment
240 .RI ( semadj )
241 values,
242 so that the calling process has a new empty
243 .I semadj
244 list that is not shared with any other process.
245 If this is the last process that has a reference to the process's current
246 .I semadj
247 list, then the adjustments in that list are applied
248 to the corresponding semaphores, as described in
249 .BR semop (2).
250 .\" CLONE_NEWNS If CLONE_SIGHAND is set and signals are also being shared
251 .\" (i.e., current->signal->count > 1), force CLONE_THREAD.
252 .PP
253 In addition,
254 .BR CLONE_THREAD ,
255 .BR CLONE_SIGHAND ,
256 and
257 .BR CLONE_VM
258 can be specified in
259 .I flags
260 if the caller is single threaded (i.e., it is not sharing
261 its address space with another process or thread).
262 In this case, these flags have no effect.
263 (Note also that specifying
264 .BR CLONE_THREAD
265 automatically implies
266 .BR CLONE_VM ,
267 and specifying
268 .BR CLONE_VM
269 automatically implies
270 .BR CLONE_SIGHAND .)
271 .\" As at 3.9, the following forced implications also apply,
272 .\" although the relevant flags are not yet implemented.
273 .\" If CLONE_THREAD is set force CLONE_VM.
274 .\" If CLONE_VM is set, force CLONE_SIGHAND.
275 .\"
276 If the process is multithreaded, then
277 the use of these flags results in an error.
278 .\" See kernel/fork.c::check_unshare_flags()
279 .PP
280 If
281 .I flags
282 is specified as zero, then
283 .BR unshare ()
284 is a no-op;
285 no changes are made to the calling process's execution context.
286 .SH RETURN VALUE
287 On success, zero returned.
288 On failure, \-1 is returned and
289 .I errno
290 is set to indicate the error.
291 .SH ERRORS
292 .TP
293 .B EINVAL
294 An invalid bit was specified in
295 .IR flags .
296 .TP
297 .B EINVAL
298 .BR CLONE_THREAD ,
299 .BR CLONE_SIGHAND ,
300 or
301 .BR CLONE_VM
302 was specified in
303 .IR flags ,
304 and the caller is multithreaded.
305 .TP
306 .B EINVAL
307 .BR CLONE_NEWIPC
308 was specified in
309 .IR flags ,
310 but the kernel was not configured with the
311 .B CONFIG_SYSVIPC
312 and
313 .BR CONFIG_IPC_NS
314 options.
315 .TP
316 .B EINVAL
317 .BR CLONE_NEWNET
318 was specified in
319 .IR flags ,
320 but the kernel was not configured with the
321 .B CONFIG_NET_NS
322 option.
323 .TP
324 .B EINVAL
325 .BR CLONE_NEWPID
326 was specified in
327 .IR flags ,
328 but the kernel was not configured with the
329 .B CONFIG_PID_NS
330 option.
331 .TP
332 .B EINVAL
333 .BR CLONE_NEWUSER
334 was specified in
335 .IR flags ,
336 but the kernel was not configured with the
337 .B CONFIG_USER_NS
338 option.
339 .TP
340 .B EINVAL
341 .BR CLONE_NEWUTS
342 was specified in
343 .IR flags ,
344 but the kernel was not configured with the
345 .B CONFIG_UTS_NS
346 option.
347 .TP
348 .B EINVAL
349 .BR CLONE_NEWPID
350 was specified in
351 .IR flags ,
352 but the process has previously called
353 .BR unshare ()
354 with the
355 .BR CLONE_NEWPID
356 flag.
357 .TP
358 .B ENOMEM
359 Cannot allocate sufficient memory to copy parts of caller's
360 context that need to be unshared.
361 .TP
362 .BR ENOSPC " (since Linux 3.7)"
363 .\" commit f2302505775fd13ba93f034206f1e2a587017929
364 .B CLONE_NEWPID
365 was specified in flags,
366 but the limit on the nesting depth of PID namespaces
367 would have been exceeded; see
368 .BR pid_namespaces (7).
369 .TP
370 .BR ENOSPC " (since Linux 4.9; beforehand " EUSERS )
371 .B CLONE_NEWUSER
372 was specified in
373 .IR flags ,
374 and the call would cause the limit on the number of
375 nested user namespaces to be exceeded.
376 See
377 .BR user_namespaces (7).
378 .IP
379 From Linux 3.11 to Linux 4.8, the error diagnosed in this case was
380 .BR EUSERS .
381 .TP
382 .BR ENOSPC " (since Linux 4.9)"
383 One of the values in
384 .I flags
385 specified the creation of a new user namespace,
386 but doing so would have caused the limit defined by the corresponding file in
387 .IR /proc/sys/user
388 to be exceeded.
389 For further details, see
390 .BR namespaces (7).
391 .TP
392 .B EPERM
393 The calling process did not have the required privileges for this operation.
394 .TP
395 .B EPERM
396 .BR CLONE_NEWUSER
397 was specified in
398 .IR flags ,
399 but either the effective user ID or the effective group ID of the caller
400 does not have a mapping in the parent namespace (see
401 .BR user_namespaces (7)).
402 .TP
403 .BR EPERM " (since Linux 3.9)"
404 .\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d
405 .B CLONE_NEWUSER
406 was specified in
407 .I flags
408 and the caller is in a chroot environment
409 .\" FIXME What is the rationale for this restriction?
410 (i.e., the caller's root directory does not match the root directory
411 of the mount namespace in which it resides).
412 .TP
413 .BR EUSERS " (from Linux 3.11 to Linux 4.8)"
414 .B CLONE_NEWUSER
415 was specified in
416 .IR flags ,
417 and the limit on the number of nested user namespaces would be exceeded.
418 See the discussion of the
419 .BR ENOSPC
420 error above.
421 .SH VERSIONS
422 The
423 .BR unshare ()
424 system call was added to Linux in kernel 2.6.16.
425 .SH CONFORMING TO
426 The
427 .BR unshare ()
428 system call is Linux-specific.
429 .SH NOTES
430 Not all of the process attributes that can be shared when
431 a new process is created using
432 .BR clone (2)
433 can be unshared using
434 .BR unshare ().
435 In particular, as at kernel 3.8,
436 .\" FIXME all of the following needs to be reviewed for the current kernel
437 .BR unshare ()
438 does not implement flags that reverse the effects of
439 .BR CLONE_SIGHAND ,
440 .\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND
441 .\" was not specified when doing clone(); i.e., unsharing
442 .\" signal handlers is permitted if we are not actually
443 .\" sharing signal handlers. mtk
444 .BR CLONE_THREAD ,
445 or
446 .BR CLONE_VM .
447 .\" However, we can do unshare(CLONE_VM) if CLONE_VM
448 .\" was not specified when doing clone(); i.e., unsharing
449 .\" virtual memory is permitted if we are not actually
450 .\" sharing virtual memory. mtk
451 Such functionality may be added in the future, if required.
452 .\"
453 .\"9) Future Work
454 .\"--------------
455 .\"The current implementation of unshare does not allow unsharing of
456 .\"signals and signal handlers. Signals are complex to begin with and
457 .\"to unshare signals and/or signal handlers of a currently running
458 .\"process is even more complex. If in the future there is a specific
459 .\"need to allow unsharing of signals and/or signal handlers, it can
460 .\"be incrementally added to unshare without affecting legacy
461 .\"applications using unshare.
462 .\"
463 .SH EXAMPLES
464 The program below provides a simple implementation of the
465 .BR unshare (1)
466 command, which unshares one or more namespaces and executes the
467 command supplied in its command-line arguments.
468 Here's an example of the use of this program,
469 running a shell in a new mount namespace,
470 and verifying that the original shell and the
471 new shell are in separate mount namespaces:
472 .PP
473 .in +4n
474 .EX
475 $ \fBreadlink /proc/$$/ns/mnt\fP
476 mnt:[4026531840]
477 $ \fBsudo ./unshare \-m /bin/bash\fP
478 # \fBreadlink /proc/$$/ns/mnt\fP
479 mnt:[4026532325]
480 .EE
481 .in
482 .PP
483 The differing output of the two
484 .BR readlink (1)
485 commands shows that the two shells are in different mount namespaces.
486 .SS Program source
487 \&
488 .EX
489 /* unshare.c
491 A simple implementation of the unshare(1) command: unshare
492 namespaces and execute a command.
493 */
494 #define _GNU_SOURCE
495 #include <sched.h>
496 #include <unistd.h>
497 #include <stdlib.h>
498 #include <stdio.h>
500 /* A simple error\-handling function: print an error message based
501 on the value in \(aqerrno\(aq and terminate the calling process. */
503 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
504 } while (0)
506 static void
507 usage(char *pname)
508 {
509 fprintf(stderr, "Usage: %s [options] program [arg...]\en", pname);
510 fprintf(stderr, "Options can be:\en");
511 fprintf(stderr, " \-C unshare cgroup namespace\en");
512 fprintf(stderr, " \-i unshare IPC namespace\en");
513 fprintf(stderr, " \-m unshare mount namespace\en");
514 fprintf(stderr, " \-n unshare network namespace\en");
515 fprintf(stderr, " \-p unshare PID namespace\en");
516 fprintf(stderr, " \-t unshare time namespace\en");
517 fprintf(stderr, " \-u unshare UTS namespace\en");
518 fprintf(stderr, " \-U unshare user namespace\en");
519 exit(EXIT_FAILURE);
520 }
522 int
523 main(int argc, char *argv[])
524 {
525 int flags, opt;
527 flags = 0;
529 while ((opt = getopt(argc, argv, "CimnptuU")) != \-1) {
530 switch (opt) {
531 case \(aqC\(aq: flags |= CLONE_NEWCGROUP; break;
532 case \(aqi\(aq: flags |= CLONE_NEWIPC; break;
533 case \(aqm\(aq: flags |= CLONE_NEWNS; break;
534 case \(aqn\(aq: flags |= CLONE_NEWNET; break;
535 case \(aqp\(aq: flags |= CLONE_NEWPID; break;
536 case \(aqt\(aq: flags |= CLONE_NEWTIME; break;
537 case \(aqu\(aq: flags |= CLONE_NEWUTS; break;
538 case \(aqU\(aq: flags |= CLONE_NEWUSER; break;
539 default: usage(argv[0]);
540 }
541 }
543 if (optind >= argc)
544 usage(argv[0]);
546 if (unshare(flags) == \-1)
547 errExit("unshare");
549 execvp(argv[optind], &argv[optind]);
550 errExit("execvp");
551 }
552 .EE
553 .SH SEE ALSO
554 .BR unshare (1),
555 .BR clone (2),
556 .BR fork (2),
557 .BR kcmp (2),
558 .BR setns (2),
559 .BR vfork (2),
560 .BR namespaces (7)
561 .PP
562 .I Documentation/userspace\-api/unshare.rst
563 in the Linux kernel source tree
564 .\" commit f504d47be5e8fa7ecf2bf660b18b42e6960c0eb2
565 (or
566 .I Documentation/unshare.txt
567 before Linux 4.12)