Debian Codegraph @

upstream/debian-unstable/man2/unshare.2

raw
1 .\" Copyright 2006, Janak Desai <[email protected]>
2 .\" Copyright 2006-2012, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-1.0-or-later
6 .\"
7 .\" Patch Justification:
8 .\" unshare system call is needed to implement, using PAM,
9 .\" per-security_context and/or per-user namespace to provide
10 .\" polyinstantiated directories. Using unshare and bind mounts, a
11 .\" PAM module can create private namespace with appropriate
12 .\" directories(based on user's security context) bind mounted on
13 .\" public directories such as /tmp, thus providing an instance of
14 .\" /tmp that is based on user's security context. Without the
15 .\" unshare system call, namespace separation can only be achieved
16 .\" by clone, which would require porting and maintaining all commands
17 .\" such as login, and su, that establish a user session.
18 .\"
19 .TH unshare 2 2026-02-08 "Linux man-pages 6.18"
20 .SH NAME
21 unshare \- disassociate parts of the process execution context
22 .SH LIBRARY
23 Standard C library
24 .RI ( libc ,\~ \-lc )
25 .SH SYNOPSIS
26 .nf
27 .B #define _GNU_SOURCE
28 .B #include <sched.h>
29 .P
30 .BI "int unshare(int " flags );
31 .fi
32 .SH DESCRIPTION
33 .BR unshare ()
34 allows a process (or thread) to disassociate parts of its execution
35 context that are currently being shared with other processes (or threads).
36 Part of the execution context, such as the mount namespace, is shared
37 implicitly when a new process is created using
38 .BR fork (2)
39 or
40 .BR vfork (2),
41 while other parts, such as virtual memory, may be
42 shared by explicit request when creating a process or thread using
43 .BR clone (2).
44 .P
45 The main use of
46 .BR unshare ()
47 is to allow a process to control its
48 shared execution context without creating a new process.
49 .P
50 The
51 .I flags
52 argument is a bit mask that specifies which parts of
53 the execution context should be unshared.
54 This argument is specified by ORing together zero or more
55 of the following constants:
56 .TP
57 .B CLONE_FILES
58 Reverse the effect of the
59 .BR clone (2)
60 .B CLONE_FILES
61 flag.
62 Unshare the file descriptor table, so that the calling process
63 no longer shares its file descriptors with any other process.
64 .TP
65 .B CLONE_FS
66 Reverse the effect of the
67 .BR clone (2)
68 .B CLONE_FS
69 flag.
70 Unshare filesystem attributes, so that the calling process
71 no longer shares its root directory
72 .RB ( chroot (2)),
73 current directory
74 .RB ( chdir (2)),
75 or umask
76 .RB ( umask (2))
77 attributes with any other process.
78 .TP
79 .BR CLONE_NEWCGROUP " (since Linux 4.6)"
80 This flag has the same effect as the
81 .BR clone (2)
82 .B CLONE_NEWCGROUP
83 flag.
84 Unshare the cgroup namespace.
85 Use of
86 .B CLONE_NEWCGROUP
87 requires the
88 .B CAP_SYS_ADMIN
89 capability.
90 .TP
91 .BR CLONE_NEWIPC " (since Linux 2.6.19)"
92 This flag has the same effect as the
93 .BR clone (2)
94 .B CLONE_NEWIPC
95 flag.
96 Unshare the IPC namespace,
97 so that the calling process has a private copy of the
98 IPC namespace which is not shared with any other process.
99 Specifying this flag automatically implies
100 .B CLONE_SYSVSEM
101 as well.
102 Use of
103 .B CLONE_NEWIPC
104 requires the
105 .B CAP_SYS_ADMIN
106 capability.
107 .TP
108 .BR CLONE_NEWNET " (since Linux 2.6.24)"
109 This flag has the same effect as the
110 .BR clone (2)
111 .B CLONE_NEWNET
112 flag.
113 Unshare the network namespace,
114 so that the calling process is moved into a
115 new network namespace which is not shared
116 with any previously existing process.
117 Use of
118 .B CLONE_NEWNET
119 requires the
120 .B CAP_SYS_ADMIN
121 capability.
122 .TP
123 .B CLONE_NEWNS
124 .\" These flag name are inconsistent:
125 .\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM,
126 .\" CLONE_FS, and CLONE_FILES reverse the action of the clone()
127 .\" flags of the same name.
128 This flag has the same effect as the
129 .BR clone (2)
130 .B CLONE_NEWNS
131 flag.
132 Unshare the mount namespace,
133 so that the calling process has a private copy of
134 its namespace which is not shared with any other process.
135 Specifying this flag automatically implies
136 .B CLONE_FS
137 as well.
138 Use of
139 .B CLONE_NEWNS
140 requires the
141 .B CAP_SYS_ADMIN
142 capability.
143 For further information, see
144 .BR mount_namespaces (7).
145 .TP
146 .BR CLONE_NEWPID " (since Linux 3.8)"
147 This flag has the same effect as the
148 .BR clone (2)
149 .B CLONE_NEWPID
150 flag.
151 Unshare the PID namespace,
152 so that the calling process has a new PID namespace for its children
153 which is not shared with any previously existing process.
154 The calling process is
155 .I not
156 moved into the new namespace.
157 The first child created by the calling process will have
158 the process ID 1 and will assume the role of
159 .BR init (1)
160 in the new namespace.
161 .B CLONE_NEWPID
162 automatically implies
163 .B CLONE_THREAD
164 as well.
165 Use of
166 .B CLONE_NEWPID
167 requires the
168 .B CAP_SYS_ADMIN
169 capability.
170 For further information, see
171 .BR pid_namespaces (7).
172 .TP
173 .BR CLONE_NEWTIME " (since Linux 5.6)"
174 Unshare the time namespace,
175 so that the calling process has a new time namespace for its children
176 which is not shared with any previously existing process.
177 The calling process is
178 .I not
179 moved into the new namespace.
180 Use of
181 .B CLONE_NEWTIME
182 requires the
183 .B CAP_SYS_ADMIN
184 capability.
185 For further information, see
186 .BR time_namespaces (7).
187 .TP
188 .BR CLONE_NEWUSER " (since Linux 3.8)"
189 This flag has the same effect as the
190 .BR clone (2)
191 .B CLONE_NEWUSER
192 flag.
193 Unshare the user namespace,
194 so that the calling process is moved into a new user namespace
195 which is not shared with any previously existing process.
196 As with the child process created by
197 .BR clone (2)
198 with the
199 .B CLONE_NEWUSER
200 flag, the caller obtains a full set of capabilities in the new namespace.
201 .IP
202 .B CLONE_NEWUSER
203 requires that the calling process is not threaded;
204 specifying
205 .B CLONE_NEWUSER
206 automatically implies
207 .BR CLONE_THREAD .
208 Since Linux 3.9,
209 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
210 .\" https://lwn.net/Articles/543273/
211 .B CLONE_NEWUSER
212 also automatically implies
213 .BR CLONE_FS .
214 .B CLONE_NEWUSER
215 requires that the user ID and group ID
216 of the calling process are mapped to user IDs and group IDs in the
217 user namespace of the calling process at the time of the call.
218 .IP
219 For further information on user namespaces, see
220 .BR user_namespaces (7).
221 .TP
222 .BR CLONE_NEWUTS " (since Linux 2.6.19)"
223 This flag has the same effect as the
224 .BR clone (2)
225 .B CLONE_NEWUTS
226 flag.
227 Unshare the UTS IPC namespace,
228 so that the calling process has a private copy of the
229 UTS namespace which is not shared with any other process.
230 Use of
231 .B CLONE_NEWUTS
232 requires the
233 .B CAP_SYS_ADMIN
234 capability.
235 .TP
236 .BR CLONE_SYSVSEM " (since Linux 2.6.26)"
237 .\" commit 9edff4ab1f8d82675277a04e359d0ed8bf14a7b7
238 This flag reverses the effect of the
239 .BR clone (2)
240 .B CLONE_SYSVSEM
241 flag.
242 Unshare System\ V semaphore adjustment
243 .RI ( semadj )
244 values,
245 so that the calling process has a new empty
246 .I semadj
247 list that is not shared with any other process.
248 If this is the last process that has a reference to the process's current
249 .I semadj
250 list, then the adjustments in that list are applied
251 to the corresponding semaphores, as described in
252 .BR semop (2).
253 .\" CLONE_NEWNS If CLONE_SIGHAND is set and signals are also being shared
254 .\" (i.e., current->signal->count > 1), force CLONE_THREAD.
255 .P
256 In addition,
257 .BR CLONE_THREAD ,
258 .BR CLONE_SIGHAND ,
259 and
260 .B CLONE_VM
261 can be specified in
262 .I flags
263 if the caller is single threaded (i.e., it is not sharing
264 its address space with another process or thread).
265 In this case, these flags have no effect.
266 (Note also that specifying
267 .B CLONE_THREAD
268 automatically implies
269 .BR CLONE_VM ,
270 and specifying
271 .B CLONE_VM
272 automatically implies
273 .BR CLONE_SIGHAND .)
274 .\" As at 3.9, the following forced implications also apply,
275 .\" although the relevant flags are not yet implemented.
276 .\" If CLONE_THREAD is set force CLONE_VM.
277 .\" If CLONE_VM is set, force CLONE_SIGHAND.
278 .\"
279 If the process is multithreaded, then
280 the use of these flags results in an error.
281 .\" See kernel/fork.c::check_unshare_flags()
282 .P
283 If
284 .I flags
285 is specified as zero, then
286 .BR unshare ()
287 is a no-op;
288 no changes are made to the calling process's execution context.
289 .SH RETURN VALUE
290 On success, zero is returned.
291 On failure, \-1 is returned and
292 .I errno
293 is set to indicate the error.
294 .SH ERRORS
295 .TP
296 .B EINVAL
297 An invalid bit was specified in
298 .IR flags .
299 .TP
300 .B EINVAL
301 .BR CLONE_THREAD ,
302 .BR CLONE_SIGHAND ,
303 or
304 .B CLONE_VM
305 was specified in
306 .IR flags ,
307 and the caller is multithreaded.
308 .TP
309 .B EINVAL
310 .B CLONE_NEWIPC
311 was specified in
312 .IR flags ,
313 but the kernel was not configured with the
314 .B CONFIG_SYSVIPC
315 and
316 .B CONFIG_IPC_NS
317 options.
318 .TP
319 .B EINVAL
320 .B CLONE_NEWNET
321 was specified in
322 .IR flags ,
323 but the kernel was not configured with the
324 .B CONFIG_NET_NS
325 option.
326 .TP
327 .B EINVAL
328 .B CLONE_NEWPID
329 was specified in
330 .IR flags ,
331 but the kernel was not configured with the
332 .B CONFIG_PID_NS
333 option.
334 .TP
335 .B EINVAL
336 .B CLONE_NEWUSER
337 was specified in
338 .IR flags ,
339 but the kernel was not configured with the
340 .B CONFIG_USER_NS
341 option.
342 .TP
343 .B EINVAL
344 .B CLONE_NEWUTS
345 was specified in
346 .IR flags ,
347 but the kernel was not configured with the
348 .B CONFIG_UTS_NS
349 option.
350 .TP
351 .B EINVAL
352 .B CLONE_NEWPID
353 was specified in
354 .IR flags ,
355 but the process has previously called
356 .BR unshare ()
357 with the
358 .B CLONE_NEWPID
359 flag.
360 .TP
361 .B ENOMEM
362 Cannot allocate sufficient memory to copy parts of caller's
363 context that need to be unshared.
364 .TP
365 .BR ENOSPC " (since Linux 3.7)"
366 .\" commit f2302505775fd13ba93f034206f1e2a587017929
367 .B CLONE_NEWPID
368 was specified in flags,
369 but the limit on the nesting depth of PID namespaces
370 would have been exceeded;
371 see
372 .BR pid_namespaces (7).
373 .TP
374 .BR ENOSPC " (since Linux 4.9; beforehand " EUSERS )
375 .B CLONE_NEWUSER
376 was specified in
377 .IR flags ,
378 and the call would cause the limit on the number of
379 nested user namespaces to be exceeded.
380 See
381 .BR user_namespaces (7).
382 .IP
383 From Linux 3.11 to Linux 4.8, the error diagnosed in this case was
384 .BR EUSERS .
385 .TP
386 .BR ENOSPC " (since Linux 4.9)"
387 One of the values in
388 .I flags
389 specified the creation of a new user namespace,
390 but doing so would have caused the limit defined by the corresponding file in
391 .I /proc/sys/user
392 to be exceeded.
393 For further details, see
394 .BR namespaces (7).
395 .TP
396 .B EPERM
397 The calling process did not have the required privileges for this operation.
398 .TP
399 .B EPERM
400 .B CLONE_NEWUSER
401 was specified in
402 .IR flags ,
403 but either the effective user ID or the effective group ID of the caller
404 does not have a mapping in the parent namespace (see
405 .BR user_namespaces (7)).
406 .TP
407 .BR EPERM " (since Linux 3.9)"
408 .\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d
409 .B CLONE_NEWUSER
410 was specified in
411 .I flags
412 and the caller is in a chroot environment
413 .\" FIXME What is the rationale for this restriction?
414 (i.e., the caller's root directory does not match the root directory
415 of the mount namespace in which it resides).
416 .TP
417 .BR EUSERS " (from Linux 3.11 to Linux 4.8)"
418 .B CLONE_NEWUSER
419 was specified in
420 .IR flags ,
421 and the limit on the number of nested user namespaces would be exceeded.
422 See the discussion of the
423 .B ENOSPC
424 error above.
425 .SH STANDARDS
426 Linux.
427 .SH HISTORY
428 Linux 2.6.16.
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 .P
464 Creating all kinds of namespace, except user namespaces, requires the
465 .B CAP_SYS_ADMIN
466 capability.
467 However, since creating a user namespace automatically confers a full set of
468 capabilities,
469 creating both a user namespace and any other type of namespace in the same
470 .BR unshare ()
471 call does not require the
472 .B CAP_SYS_ADMIN
473 capability in the original namespace.
474 .SH EXAMPLES
475 The program below provides a simple implementation of the
476 .BR unshare (1)
477 command, which unshares one or more namespaces and executes the
478 command supplied in its command-line arguments.
479 Here's an example of the use of this program,
480 running a shell in a new mount namespace,
481 and verifying that the original shell and the
482 new shell are in separate mount namespaces:
483 .P
484 .in +4n
485 .EX
486 .RB $ " readlink /proc/$$/ns/mnt" ;
487 mnt:[4026531840]
488 .RB $ " sudo ./unshare \-m /bin/bash" ;
489 .RB # " readlink /proc/$$/ns/mnt" ;
490 mnt:[4026532325]
491 .EE
492 .in
493 .P
494 The differing output of the two
495 .BR readlink (1)
496 commands shows that the two shells are in different mount namespaces.
497 .SS Program source
498 \&
499 .\" SRC BEGIN (unshare.c)
500 .EX
501 /* unshare.c
502 \&
503 A simple implementation of the unshare(1) command: unshare
504 namespaces and execute a command.
505 */
506 #define _GNU_SOURCE
507 #include <err.h>
508 #include <sched.h>
509 #include <stdio.h>
510 #include <stdlib.h>
511 #include <unistd.h>
512 \&
513 static void
514 usage(char *pname)
515 {
516 fprintf(stderr, "Usage: %s [options] program [arg...]\[rs]n", pname);
517 fprintf(stderr, "Options can be:\[rs]n");
518 fprintf(stderr, " \-C unshare cgroup namespace\[rs]n");
519 fprintf(stderr, " \-i unshare IPC namespace\[rs]n");
520 fprintf(stderr, " \-m unshare mount namespace\[rs]n");
521 fprintf(stderr, " \-n unshare network namespace\[rs]n");
522 fprintf(stderr, " \-p unshare PID namespace\[rs]n");
523 fprintf(stderr, " \-t unshare time namespace\[rs]n");
524 fprintf(stderr, " \-u unshare UTS namespace\[rs]n");
525 fprintf(stderr, " \-U unshare user namespace\[rs]n");
526 exit(EXIT_FAILURE);
527 }
528 \&
529 int
530 main(int argc, char *argv[])
531 {
532 int flags, opt;
533 \&
534 flags = 0;
535 \&
536 while ((opt = getopt(argc, argv, "CimnptuU")) != \-1) {
537 switch (opt) {
538 case \[aq]C\[aq]: flags |= CLONE_NEWCGROUP; break;
539 case \[aq]i\[aq]: flags |= CLONE_NEWIPC; break;
540 case \[aq]m\[aq]: flags |= CLONE_NEWNS; break;
541 case \[aq]n\[aq]: flags |= CLONE_NEWNET; break;
542 case \[aq]p\[aq]: flags |= CLONE_NEWPID; break;
543 case \[aq]t\[aq]: flags |= CLONE_NEWTIME; break;
544 case \[aq]u\[aq]: flags |= CLONE_NEWUTS; break;
545 case \[aq]U\[aq]: flags |= CLONE_NEWUSER; break;
546 default: usage(argv[0]);
547 }
548 }
549 \&
550 if (optind >= argc)
551 usage(argv[0]);
552 \&
553 if (unshare(flags) == \-1)
554 err(EXIT_FAILURE, "unshare");
555 \&
556 execvp(argv[optind], &argv[optind]);
557 err(EXIT_FAILURE, "execvp");
558 }
559 .EE
560 .\" SRC END
561 .SH SEE ALSO
562 .BR unshare (1),
563 .BR clone (2),
564 .BR fork (2),
565 .BR kcmp (2),
566 .BR setns (2),
567 .BR vfork (2),
568 .BR namespaces (7)
569 .P
570 .I Documentation/userspace\-api/unshare.rst
571 in the Linux kernel source tree