1unshare(2) System Calls Manual unshare(2)
2
6 unshare - disassociate parts of the process execution context
7
9 Standard C library (libc, -lc)
10
12 #define _GNU_SOURCE
13 #include <sched.h>
14 int unshare(int flags);
16
18 unshare() allows a process (or thread) to disassociate parts of its ex‐
19 ecution context that are currently being shared with other processes
20 (or threads). Part of the execution context, such as the mount name‐
21 space, is shared implicitly when a new process is created using fork(2)
22 or vfork(2), while other parts, such as virtual memory, may be shared
23 by explicit request when creating a process or thread using clone(2).
24 The main use of unshare() is to allow a process to control its shared
26 execution context without creating a new process.
27 The flags argument is a bit mask that specifies which parts of the exe‐
29 cution context should be unshared. This argument is specified by ORing
30 together zero or more of the following constants:
31 CLONE_FILES
33 Reverse the effect of the clone(2) CLONE_FILES flag. Unshare
34 the file descriptor table, so that the calling process no longer
35 shares its file descriptors with any other process.
36 CLONE_FS
38 Reverse the effect of the clone(2) CLONE_FS flag. Unshare
39 filesystem attributes, so that the calling process no longer
40 shares its root directory (chroot(2)), current directory
41 (chdir(2)), or umask (umask(2)) attributes with any other
42 process.
43 CLONE_NEWCGROUP (since Linux 4.6)
45 This flag has the same effect as the clone(2) CLONE_NEWCGROUP
46 flag. Unshare the cgroup namespace. Use of CLONE_NEWCGROUP re‐
47 quires the CAP_SYS_ADMIN capability.
48 CLONE_NEWIPC (since Linux 2.6.19)
50 This flag has the same effect as the clone(2) CLONE_NEWIPC flag.
51 Unshare the IPC namespace, so that the calling process has a
52 private copy of the IPC namespace which is not shared with any
53 other process. Specifying this flag automatically implies
54 CLONE_SYSVSEM as well. Use of CLONE_NEWIPC requires the
55 CAP_SYS_ADMIN capability.
56 CLONE_NEWNET (since Linux 2.6.24)
58 This flag has the same effect as the clone(2) CLONE_NEWNET flag.
59 Unshare the network namespace, so that the calling process is
60 moved into a new network namespace which is not shared with any
61 previously existing process. Use of CLONE_NEWNET requires the
62 CAP_SYS_ADMIN capability.
63 CLONE_NEWNS
65 This flag has the same effect as the clone(2) CLONE_NEWNS flag.
66 Unshare the mount namespace, so that the calling process has a
67 private copy of its namespace which is not shared with any other
68 process. Specifying this flag automatically implies CLONE_FS as
69 well. Use of CLONE_NEWNS requires the CAP_SYS_ADMIN capability.
70 For further information, see mount_namespaces(7).
71 CLONE_NEWPID (since Linux 3.8)
73 This flag has the same effect as the clone(2) CLONE_NEWPID flag.
74 Unshare the PID namespace, so that the calling process has a new
75 PID namespace for its children which is not shared with any pre‐
76 viously existing process. The calling process is not moved into
77 the new namespace. The first child created by the calling
78 process will have the process ID 1 and will assume the role of
79 init(1) in the new namespace. CLONE_NEWPID automatically im‐
80 plies CLONE_THREAD as well. Use of CLONE_NEWPID requires the
81 CAP_SYS_ADMIN capability. For further information, see
82 pid_namespaces(7).
83 CLONE_NEWTIME (since Linux 5.6)
85 Unshare the time namespace, so that the calling process has a
86 new time namespace for its children which is not shared with any
87 previously existing process. The calling process is not moved
88 into the new namespace. Use of CLONE_NEWTIME requires the
89 CAP_SYS_ADMIN capability. For further information, see
90 time_namespaces(7).
91 CLONE_NEWUSER (since Linux 3.8)
93 This flag has the same effect as the clone(2) CLONE_NEWUSER
94 flag. Unshare the user namespace, so that the calling process
95 is moved into a new user namespace which is not shared with any
96 previously existing process. As with the child process created
97 by clone(2) with the CLONE_NEWUSER flag, the caller obtains a
98 full set of capabilities in the new namespace.
99 CLONE_NEWUSER requires that the calling process is not threaded;
101 specifying CLONE_NEWUSER automatically implies CLONE_THREAD.
102 Since Linux 3.9, CLONE_NEWUSER also automatically implies
103 CLONE_FS. CLONE_NEWUSER requires that the user ID and group ID
104 of the calling process are mapped to user IDs and group IDs in
105 the user namespace of the calling process at the time of the
106 call.
107 For further information on user namespaces, see user_name‐
109 spaces(7).
110 CLONE_NEWUTS (since Linux 2.6.19)
112 This flag has the same effect as the clone(2) CLONE_NEWUTS flag.
113 Unshare the UTS IPC namespace, so that the calling process has a
114 private copy of the UTS namespace which is not shared with any
115 other process. Use of CLONE_NEWUTS requires the CAP_SYS_ADMIN
116 capability.
117 CLONE_SYSVSEM (since Linux 2.6.26)
119 This flag reverses the effect of the clone(2) CLONE_SYSVSEM
120 flag. Unshare System V semaphore adjustment (semadj) values, so
121 that the calling process has a new empty semadj list that is not
122 shared with any other process. If this is the last process that
123 has a reference to the process's current semadj list, then the
124 adjustments in that list are applied to the corresponding sema‐
125 phores, as described in semop(2).
126 In addition, CLONE_THREAD, CLONE_SIGHAND, and CLONE_VM can be specified
128 in flags if the caller is single threaded (i.e., it is not sharing its
129 address space with another process or thread). In this case, these
130 flags have no effect. (Note also that specifying CLONE_THREAD automat‐
131 ically implies CLONE_VM, and specifying CLONE_VM automatically implies
132 CLONE_SIGHAND.) If the process is multithreaded, then the use of these
133 flags results in an error.
134 If flags is specified as zero, then unshare() is a no-op; no changes
136 are made to the calling process's execution context.
137
139 On success, zero returned. On failure, -1 is returned and errno is set
140 to indicate the error.
141
143 EINVAL An invalid bit was specified in flags.
144 EINVAL CLONE_THREAD, CLONE_SIGHAND, or CLONE_VM was specified in flags,
146 and the caller is multithreaded.
147 EINVAL CLONE_NEWIPC was specified in flags, but the kernel was not con‐
149 figured with the CONFIG_SYSVIPC and CONFIG_IPC_NS options.
150 EINVAL CLONE_NEWNET was specified in flags, but the kernel was not con‐
152 figured with the CONFIG_NET_NS option.
153 EINVAL CLONE_NEWPID was specified in flags, but the kernel was not con‐
155 figured with the CONFIG_PID_NS option.
156 EINVAL CLONE_NEWUSER was specified in flags, but the kernel was not
158 configured with the CONFIG_USER_NS option.
159 EINVAL CLONE_NEWUTS was specified in flags, but the kernel was not con‐
161 figured with the CONFIG_UTS_NS option.
162 EINVAL CLONE_NEWPID was specified in flags, but the process has previ‐
164 ously called unshare() with the CLONE_NEWPID flag.
165 ENOMEM Cannot allocate sufficient memory to copy parts of caller's con‐
167 text that need to be unshared.
168 ENOSPC (since Linux 3.7)
170 CLONE_NEWPID was specified in flags, but the limit on the nest‐
171 ing depth of PID namespaces would have been exceeded; see
172 pid_namespaces(7).
173 ENOSPC (since Linux 4.9; beforehand EUSERS)
175 CLONE_NEWUSER was specified in flags, and the call would cause
176 the limit on the number of nested user namespaces to be ex‐
177 ceeded. See user_namespaces(7).
178 From Linux 3.11 to Linux 4.8, the error diagnosed in this case
180 was EUSERS.
181 ENOSPC (since Linux 4.9)
183 One of the values in flags specified the creation of a new user
184 namespace, but doing so would have caused the limit defined by
185 the corresponding file in /proc/sys/user to be exceeded. For
186 further details, see namespaces(7).
187 EPERM The calling process did not have the required privileges for
189 this operation.
190 EPERM CLONE_NEWUSER was specified in flags, but either the effective
192 user ID or the effective group ID of the caller does not have a
193 mapping in the parent namespace (see user_namespaces(7)).
194 EPERM (since Linux 3.9)
196 CLONE_NEWUSER was specified in flags and the caller is in a ch‐
197 root environment (i.e., the caller's root directory does not
198 match the root directory of the mount namespace in which it re‐
199 sides).
200 EUSERS (from Linux 3.11 to Linux 4.8)
202 CLONE_NEWUSER was specified in flags, and the limit on the num‐
203 ber of nested user namespaces would be exceeded. See the dis‐
204 cussion of the ENOSPC error above.
205
207 Linux.
208
210 Linux 2.6.16.
211
213 Not all of the process attributes that can be shared when a new process
214 is created using clone(2) can be unshared using unshare(). In particu‐
215 lar, as at kernel 3.8, unshare() does not implement flags that reverse
216 the effects of CLONE_SIGHAND, CLONE_THREAD, or CLONE_VM. Such func‐
217 tionality may be added in the future, if required.
218 Creating all kinds of namespace, except user namespaces, requires the
220 CAP_SYS_ADMIN capability. However, since creating a user namespace au‐
221 tomatically confers a full set of capabilities, creating both a user
222 namespace and any other type of namespace in the same unshare() call
223 does not require the CAP_SYS_ADMIN capability in the original name‐
224 space.
225
227 The program below provides a simple implementation of the unshare(1)
228 command, which unshares one or more namespaces and executes the command
229 supplied in its command-line arguments. Here's an example of the use
230 of this program, running a shell in a new mount namespace, and verify‐
231 ing that the original shell and the new shell are in separate mount
232 namespaces:
233 $ readlink /proc/$$/ns/mnt
235 mnt:[4026531840]
236 $ sudo ./unshare -m /bin/bash
237 # readlink /proc/$$/ns/mnt
238 mnt:[4026532325]
239 The differing output of the two readlink(1) commands shows that the two
241 shells are in different mount namespaces.
242 Program source
244 /* unshare.c
246 A simple implementation of the unshare(1) command: unshare
248 namespaces and execute a command.
249 */
250 #define _GNU_SOURCE
251 #include <err.h>
252 #include <sched.h>
253 #include <stdio.h>
254 #include <stdlib.h>
255 #include <unistd.h>
256 static void
258 usage(char *pname)
259 {
260 fprintf(stderr, "Usage: %s [options] program [arg...]\n", pname);
261 fprintf(stderr, "Options can be:\n");
262 fprintf(stderr, " -C unshare cgroup namespace\n");
263 fprintf(stderr, " -i unshare IPC namespace\n");
264 fprintf(stderr, " -m unshare mount namespace\n");
265 fprintf(stderr, " -n unshare network namespace\n");
266 fprintf(stderr, " -p unshare PID namespace\n");
267 fprintf(stderr, " -t unshare time namespace\n");
268 fprintf(stderr, " -u unshare UTS namespace\n");
269 fprintf(stderr, " -U unshare user namespace\n");
270 exit(EXIT_FAILURE);
271 }
272 int
274 main(int argc, char *argv[])
275 {
276 int flags, opt;
277 flags = 0;
279 while ((opt = getopt(argc, argv, "CimnptuU")) != -1) {
281 switch (opt) {
282 case 'C': flags |= CLONE_NEWCGROUP; break;
283 case 'i': flags |= CLONE_NEWIPC; break;
284 case 'm': flags |= CLONE_NEWNS; break;
285 case 'n': flags |= CLONE_NEWNET; break;
286 case 'p': flags |= CLONE_NEWPID; break;
287 case 't': flags |= CLONE_NEWTIME; break;
288 case 'u': flags |= CLONE_NEWUTS; break;
289 case 'U': flags |= CLONE_NEWUSER; break;
290 default: usage(argv[0]);
291 }
292 }
293 if (optind >= argc)
295 usage(argv[0]);
296 if (unshare(flags) == -1)
298 err(EXIT_FAILURE, "unshare");
299 execvp(argv[optind], &argv[optind]);
301 err(EXIT_FAILURE, "execvp");
302 }
303
305 unshare(1), clone(2), fork(2), kcmp(2), setns(2), vfork(2), name‐
306 spaces(7)
307 Documentation/userspace-api/unshare.rst in the Linux kernel source tree
309 (or Documentation/unshare.txt before Linux 4.12)
310Linux man-pages 6.05 2023-05-26 unshare(2)