1 .\" Copyright (C) 2011, Eric Biederman <ebiederm@xmission.com>
2 .\" and Copyright (C) 2011, 2012, Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(GPLv2_ONELINE)
5 .\" Licensed under the GPLv2
8 .TH SETNS 2 2020-04-11 "Linux" "Linux Programmer's Manual"
10 setns \- reassociate thread with a namespace
13 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
16 .BI "int setns(int " fd ", int " nstype );
19 Given a file descriptor referring to a namespace,
20 reassociate the calling thread with that namespace.
24 argument is a file descriptor referring to one of the namespace entries in a
28 for further information on
30 The calling thread will be reassociated with the corresponding namespace,
31 subject to any constraints imposed by the
37 argument specifies which type of namespace
38 the calling thread may be reassociated with.
39 This argument can have one of the following values:
42 Allow any type of namespace to be joined.
44 .BR CLONE_NEWCGROUP " (since Linux 4.6)"
46 must refer to a cgroup namespace.
48 .BR CLONE_NEWIPC " (since Linux 3.0)"
50 must refer to an IPC namespace.
52 .BR CLONE_NEWNET " (since Linux 3.0)"
54 must refer to a network namespace.
56 .BR CLONE_NEWNS " (since Linux 3.8)"
58 must refer to a mount namespace.
60 .BR CLONE_NEWPID " (since Linux 3.8)"
62 must refer to a descendant PID namespace.
64 .BR CLONE_NEWTIME " (since Linux 5.6)"
66 must refer to a time namespace.
68 .BR CLONE_NEWUSER " (since Linux 3.8)"
70 must refer to a user namespace.
72 .BR CLONE_NEWUTS " (since Linux 3.0)"
74 must refer to a UTS namespace.
78 as 0 suffices if the caller knows (or does not care)
79 what type of namespace is referred to by
81 Specifying a nonzero value for
83 is useful if the caller does not know what type of namespace is referred to by
85 and wants to ensure that the namespace is of a particular type.
86 (The caller might not know the type of the namespace referred to by
88 if the file descriptor was opened by another process and, for example,
89 passed to the caller via a UNIX domain socket.)
91 .SS Details for specific namespace types
92 Note the following details and restrictions when reassociating with
93 specific namespace types:
96 A process reassociating itself with a user namespace must have the
98 .\" See kernel/user_namespace.c:userns_install() [3.8 source]
99 capability in the target user namespace.
100 (This necessarily implies that it is only possible to join
101 a descendant user namespace.)
102 Upon successfully joining a user namespace,
103 a process is granted all capabilities in that namespace,
104 regardless of its user and group IDs.
106 A multithreaded process may not change user namespace with
109 It is not permitted to use
111 to reenter the caller's current user namespace.
112 This prevents a caller that has dropped capabilities from regaining
113 those capabilities via a call to
116 For security reasons,
117 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
118 .\" https://lwn.net/Articles/543273/
119 a process can't join a new user namespace if it is sharing
120 filesystem-related attributes
121 (the attributes whose sharing is controlled by the
124 flag) with another process.
126 For further details on user namespaces, see
127 .BR user_namespaces (7).
130 Changing the mount namespace requires that the caller possess both
134 capabilities in its own user namespace and
136 in the user namespace that owns the target mount namespace.
138 A process can't join a new mount namespace if it is sharing
139 filesystem-related attributes
140 (the attributes whose sharing is controlled by the
143 flag) with another process.
144 .\" Above check is in fs/namespace.c:mntns_install() [3.8 source]
147 .BR user_namespaces (7)
148 for details on the interaction of user namespaces and mount namespaces.
151 In order to reassociate itself with a new PID namespace,
152 the caller must have the
154 capability both in its own user namespace and in the user namespace
155 that owns the target PID namespace.
159 refers to a PID namespace, the semantics are somewhat different
160 from other namespace types:
161 reassociating the calling thread with a PID namespace changes only
162 the PID namespace that subsequently created child processes of
163 the caller will be placed in;
164 it does not change the PID namespace of the caller itself.
166 Reassociating with a PID namespace is allowed only if the
167 PID namespace specified by
169 is a descendant (child, grandchild, etc.)
170 of the PID namespace of the caller.
172 For further details on PID namespaces, see
173 .BR pid_namespaces (7).
176 In order to reassociate itself with a new cgroup namespace,
177 the caller must have the
179 capability both in its own user namespace and in the user namespace
180 that owns the target cgroup namespace.
184 to change the caller's cgroup namespace does not change
185 the caller's cgroup memberships.
187 Network, IPC, time, and UTS namespaces
188 In order to reassociate itself with a new network, IPC, time, or UTS namespace,
189 the caller must have the
191 capability both in its own user namespace and in the user namespace
192 that owns the target namespace.
197 On failure, \-1 is returned and
199 is set to indicate the error.
204 is not a valid file descriptor.
208 refers to a namespace whose type does not match that specified in
212 There is problem with reassociating
213 the thread with the specified namespace.
215 .\" See kernel/pid_namespace.c::pidns_install() [kernel 3.18 sources]
217 The caller tried to join an ancestor (parent, grandparent, and so on)
221 The caller attempted to join the user namespace
222 in which it is already a member.
225 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
226 The caller shares filesystem
228 state (in particular, the root directory)
229 with other processes and tried to join a new user namespace.
232 .\" See kernel/user_namespace.c::userns_install() [kernel 3.15 sources]
233 The caller is multithreaded and tried to join a new user namespace.
236 Cannot allocate sufficient memory to change the specified namespace.
239 The calling thread did not have the required capability
244 system call first appeared in Linux in kernel 3.0;
245 library support was added to glibc in version 2.14.
249 system call is Linux-specific.
251 Not all of the attributes that can be shared when
252 a new thread is created using
257 The program below takes two or more arguments.
258 The first argument specifies the pathname of a namespace file in an existing
261 The remaining arguments specify a command and its arguments.
262 The program opens the namespace file, joins that namespace using
264 and executes the specified command inside that namespace.
266 The following shell session demonstrates the use of this program
267 (compiled as a binary named
269 in conjunction with the
271 example program in the
273 man page (complied as a binary named
276 We begin by executing the example program in
279 That program creates a child in a separate UTS namespace.
280 The child changes the hostname in its namespace,
281 and then both processes display the hostnames in their UTS namespaces,
282 so that we can see that they are different.
286 $ \fBsu\fP # Need privilege for namespace operations
288 # \fB./newuts bizarro &\fP
290 clone() returned 3550
291 uts.nodename in child: bizarro
292 uts.nodename in parent: antero
293 # \fBuname \-n\fP # Verify hostname in the shell
298 We then run the program shown below,
299 using it to execute a shell.
300 Inside that shell, we verify that the hostname is the one
301 set by the child created by the first program:
305 # \fB./ns_exec /proc/3550/ns/uts /bin/bash\fP
306 # \fBuname \-n\fP # Executed in shell started by ns_exec
319 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
323 main(int argc, char *argv[])
328 fprintf(stderr, "%s /proc/PID/ns/FILE cmd args...\en", argv[0]);
332 fd = open(argv[1], O_RDONLY); /* Get file descriptor for namespace */
336 if (setns(fd, 0) == \-1) /* Join that namespace */
339 execvp(argv[2], &argv[2]); /* Execute a command in namespace */