]>
Commit | Line | Data |
---|---|---|
dfa22c8b | 1 | .\" Copyright (C) 2011, Eric Biederman <ebiederm@xmission.com> |
83825f79 | 2 | .\" and Copyright (C) 2011, 2012, Michael Kerrisk <mtk.manpages@gmail.com> |
2297bf0e | 3 | .\" |
c4a99c30 | 4 | .\" %%%LICENSE_START(GPLv2_ONELINE) |
dfa22c8b | 5 | .\" Licensed under the GPLv2 |
8ff7380d | 6 | .\" %%%LICENSE_END |
dfa22c8b | 7 | .\" |
4b8c67d9 | 8 | .TH SETNS 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
dfa22c8b | 9 | .SH NAME |
7aa166c5 | 10 | setns \- reassociate thread with a namespace |
dfa22c8b EB |
11 | .SH SYNOPSIS |
12 | .nf | |
13 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" | |
14 | .B #include <sched.h> | |
68e4db0a | 15 | .PP |
dfa22c8b EB |
16 | .BI "int setns(int " fd ", int " nstype ); |
17 | .fi | |
18 | .SH DESCRIPTION | |
c07ad242 | 19 | Given a file descriptor referring to a namespace, |
7aa166c5 | 20 | reassociate the calling thread with that namespace. |
efeece04 | 21 | .PP |
92dcb220 MK |
22 | The |
23 | .I fd | |
24 | argument is a file descriptor referring to one of the namespace entries in a | |
25 | .I /proc/[pid]/ns/ | |
26 | directory; see | |
6edfe909 | 27 | .BR namespaces (7) |
c409c4ff | 28 | for further information on |
92dcb220 | 29 | .IR /proc/[pid]/ns/ . |
7aa166c5 | 30 | The calling thread will be reassociated with the corresponding namespace, |
92dcb220 MK |
31 | subject to any constraints imposed by the |
32 | .I nstype | |
33 | argument. | |
efeece04 | 34 | .PP |
dfa22c8b EB |
35 | The |
36 | .I nstype | |
c07ad242 | 37 | argument specifies which type of namespace |
7aa166c5 | 38 | the calling thread may be reassociated with. |
4e1e208d | 39 | This argument can have one of the following values: |
dfa22c8b EB |
40 | .TP |
41 | .BR 0 | |
92dcb220 | 42 | Allow any type of namespace to be joined. |
dfa22c8b | 43 | .TP |
46dd3176 MK |
44 | .BR CLONE_NEWCGROUP " (since Linux 4.6)" |
45 | .I fd | |
46 | must refer to a cgroup namespace. | |
47 | .TP | |
268a93cb | 48 | .BR CLONE_NEWIPC " (since Linux 3.0)" |
92dcb220 MK |
49 | .I fd |
50 | must refer to an IPC namespace. | |
dfa22c8b | 51 | .TP |
268a93cb | 52 | .BR CLONE_NEWNET " (since Linux 3.0)" |
92dcb220 MK |
53 | .I fd |
54 | must refer to a network namespace. | |
dfa22c8b | 55 | .TP |
268a93cb | 56 | .BR CLONE_NEWNS " (since Linux 3.8)" |
99fd2fe3 EB |
57 | .I fd |
58 | must refer to a mount namespace. | |
59 | .TP | |
268a93cb | 60 | .BR CLONE_NEWPID " (since Linux 3.8)" |
99fd2fe3 | 61 | .I fd |
ba7d7ed9 | 62 | must refer to a descendant PID namespace. |
99fd2fe3 | 63 | .TP |
268a93cb | 64 | .BR CLONE_NEWUSER " (since Linux 3.8)" |
99fd2fe3 EB |
65 | .I fd |
66 | must refer to a user namespace. | |
67 | .TP | |
268a93cb | 68 | .BR CLONE_NEWUTS " (since Linux 3.0)" |
92dcb220 MK |
69 | .I fd |
70 | must refer to a UTS namespace. | |
dfa22c8b | 71 | .PP |
92dcb220 MK |
72 | Specifying |
73 | .I nstype | |
74 | as 0 suffices if the caller knows (or does not care) | |
75 | what type of namespace is referred to by | |
76 | .IR fd . | |
77 | Specifying a nonzero value for | |
78 | .I nstype | |
79 | is useful if the caller does not know what type of namespace is referred to by | |
80 | .IR fd | |
81 | and wants to ensure that the namespace is of a particular type. | |
82 | (The caller might not know the type of the namespace referred to by | |
83 | .IR fd | |
84 | if the file descriptor was opened by another process and, for example, | |
85 | passed to the caller via a UNIX domain socket.) | |
8e23f12b MK |
86 | .\" |
87 | .SS Details for specific namespace types | |
88 | Note the following details and restrictions when reassociating with | |
89 | specific namespace types: | |
90 | .TP | |
91 | User namespaces | |
ec66fbff MK |
92 | A process reassociating itself with a user namespace must have the |
93 | .B CAP_SYS_ADMIN | |
94 | .\" See kernel/user_namespace.c:userns_install() [3.8 source] | |
95 | capability in the target user namespace. | |
563bf760 MK |
96 | (This necessarily implies that it is only possible to join |
97 | a descendant user namespace.) | |
ec66fbff MK |
98 | Upon successfully joining a user namespace, |
99 | a process is granted all capabilities in that namespace, | |
100 | regardless of its user and group IDs. | |
2e4a22de | 101 | .IP |
5c67baab | 102 | A multithreaded process may not change user namespace with |
cd7e05aa | 103 | .BR setns (). |
2e4a22de | 104 | .IP |
81714b4f MK |
105 | It is not permitted to use |
106 | .BR setns () | |
107 | to reenter the caller's current user namespace. | |
108 | This prevents a caller that has dropped capabilities from regaining | |
109 | those capabilities via a call to | |
110 | .BR setns (). | |
2e4a22de | 111 | .IP |
85e34225 MK |
112 | For security reasons, |
113 | .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 | |
114 | .\" https://lwn.net/Articles/543273/ | |
115 | a process can't join a new user namespace if it is sharing | |
8db37760 | 116 | filesystem-related attributes |
85e34225 MK |
117 | (the attributes whose sharing is controlled by the |
118 | .BR clone (2) | |
119 | .B CLONE_FS | |
120 | flag) with another process. | |
2e4a22de | 121 | .IP |
e57c3979 | 122 | For further details on user namespaces, see |
ec66fbff | 123 | .BR user_namespaces (7). |
8e23f12b MK |
124 | .TP |
125 | Mount namespaces | |
49af76fe | 126 | Changing the mount namespace requires that the caller possess both |
cd7e05aa MK |
127 | .B CAP_SYS_CHROOT |
128 | and | |
f5d401dd | 129 | .BR CAP_SYS_ADMIN |
21bfe3e9 | 130 | capabilities in its own user namespace and |
f5d401dd | 131 | .BR CAP_SYS_ADMIN |
f9d9ad21 | 132 | in the user namespace that owns the target mount namespace. |
2e4a22de | 133 | .IP |
c6b1b95b MK |
134 | A process may not be reassociated with a new mount namespace if it is |
135 | multithreaded. | |
136 | .\" Above check is in fs/namespace.c:mntns_install() [3.8 source] | |
137 | .IP | |
53d084e8 MK |
138 | See |
139 | .BR user_namespaces (7) | |
140 | for details on the interaction of user namespaces and mount namespaces. | |
8e23f12b | 141 | .TP |
0ecd5804 | 142 | PID namespaces |
a5633e6b | 143 | In order to reassociate itself with a new PID namespace, |
5fbfa733 | 144 | the caller must have the |
a5633e6b MK |
145 | .B CAP_SYS_ADMIN |
146 | capability both in its own user namespace and in the user namespace | |
147 | that owns the target PID namespace. | |
148 | .IP | |
0ecd5804 MK |
149 | If |
150 | .I fd | |
98929c31 | 151 | refers to a PID namespace, the semantics are somewhat different |
0ecd5804 MK |
152 | from other namespace types: |
153 | reassociating the calling thread with a PID namespace changes only | |
154 | the PID namespace that subsequently created child processes of | |
155 | the caller will be placed in; | |
156 | it does not change the PID namespace of the caller itself. | |
157 | .IP | |
158 | Reassociating with a PID namespace is allowed only if the | |
159 | PID namespace specified by | |
160 | .IR fd | |
161 | is a descendant (child, grandchild, etc.) | |
162 | of the PID namespace of the caller. | |
163 | .IP | |
164 | For further details on PID namespaces, see | |
165 | .BR pid_namespaces (7). | |
166 | .TP | |
8e23f12b | 167 | Cgroup namespaces |
b4e19249 | 168 | In order to reassociate itself with a new cgroup namespace, |
5fbfa733 | 169 | the caller must have the |
b4e19249 MK |
170 | .B CAP_SYS_ADMIN |
171 | capability both in its own user namespace and in the user namespace | |
172 | that owns the target cgroup namespace. | |
173 | .IP | |
46dd3176 MK |
174 | Using |
175 | .BR setns () | |
176 | to change the caller's cgroup namespace does not change | |
177 | the caller's cgroup memberships. | |
ac794195 MK |
178 | .TP |
179 | Network, IPC, and UTS namespaces | |
180 | In order to reassociate itself with a new network, IPC, or UTS namespace, | |
5fbfa733 | 181 | the caller must have the |
ac794195 MK |
182 | .B CAP_SYS_ADMIN |
183 | capability both in its own user namespace and in the user namespace | |
184 | that owns the target namespace. | |
dfa22c8b | 185 | .SH RETURN VALUE |
92dcb220 | 186 | On success, |
577b1ed5 | 187 | .BR setns () |
92dcb220 | 188 | returns 0. |
dfa22c8b EB |
189 | On failure, \-1 is returned and |
190 | .I errno | |
191 | is set to indicate the error. | |
192 | .SH ERRORS | |
193 | .TP | |
dfa22c8b | 194 | .B EBADF |
c07ad242 MK |
195 | .I fd |
196 | is not a valid file descriptor. | |
dfa22c8b EB |
197 | .TP |
198 | .B EINVAL | |
92dcb220 MK |
199 | .I fd |
200 | refers to a namespace whose type does not match that specified in | |
16fe718f MK |
201 | .IR nstype . |
202 | .TP | |
203 | .B EINVAL | |
204 | There is problem with reassociating | |
7aa166c5 | 205 | the thread with the specified namespace. |
dfa22c8b | 206 | .TP |
ba7d7ed9 MF |
207 | .\" See kernel/pid_namespace.c::pidns_install() [kernel 3.18 sources] |
208 | .B EINVAL | |
c9b0afde MK |
209 | The caller tried to join an ancestor (parent, grandparent, and so on) |
210 | PID namespace. | |
ba7d7ed9 | 211 | .TP |
edc3c3b4 MK |
212 | .B EINVAL |
213 | The caller attempted to join the user namespace | |
214 | in which it is already a member. | |
215 | .TP | |
e63259f2 MK |
216 | .B EINVAL |
217 | .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71 | |
218 | The caller shares filesystem | |
219 | .RB ( CLONE_FS ) | |
220 | state (in particular, the root directory) | |
221 | with other processes and tried to join a new user namespace. | |
222 | .TP | |
223 | .B EINVAL | |
224 | .\" See kernel/user_namespace.c::userns_install() [kernel 3.15 sources] | |
225 | The caller is multithreaded and tried to join a new user namespace. | |
226 | .TP | |
dfa22c8b EB |
227 | .B ENOMEM |
228 | Cannot allocate sufficient memory to change the specified namespace. | |
dfa22c8b EB |
229 | .TP |
230 | .B EPERM | |
7fc8e5ec | 231 | The calling thread did not have the required capability |
63b6ef41 | 232 | for this operation. |
dfa22c8b EB |
233 | .SH VERSIONS |
234 | The | |
235 | .BR setns () | |
c95b6ae1 | 236 | system call first appeared in Linux in kernel 3.0; |
268a93cb | 237 | library support was added to glibc in version 2.14. |
dfa22c8b EB |
238 | .SH CONFORMING TO |
239 | The | |
240 | .BR setns () | |
241 | system call is Linux-specific. | |
242 | .SH NOTES | |
7aa166c5 MK |
243 | Not all of the attributes that can be shared when |
244 | a new thread is created using | |
dfa22c8b EB |
245 | .BR clone (2) |
246 | can be changed using | |
247 | .BR setns (). | |
8d41e607 MK |
248 | .SH EXAMPLE |
249 | The program below takes two or more arguments. | |
250 | The first argument specifies the pathname of a namespace file in an existing | |
251 | .I /proc/[pid]/ns/ | |
252 | directory. | |
253 | The remaining arguments specify a command and its arguments. | |
254 | The program opens the namespace file, joins that namespace using | |
255 | .BR setns (), | |
256 | and executes the specified command inside that namespace. | |
efeece04 | 257 | .PP |
8d41e607 MK |
258 | The following shell session demonstrates the use of this program |
259 | (compiled as a binary named | |
a1ce9159 | 260 | .IR ns_exec ) |
8d41e607 MK |
261 | in conjunction with the |
262 | .BR CLONE_NEWUTS | |
263 | example program in the | |
264 | .BR clone (2) | |
265 | man page (complied as a binary named | |
266 | .IR newuts ). | |
efeece04 | 267 | .PP |
8d41e607 MK |
268 | We begin by executing the example program in |
269 | .BR clone (2) | |
270 | in the background. | |
271 | That program creates a child in a separate UTS namespace. | |
51ebe080 | 272 | The child changes the hostname in its namespace, |
8d41e607 MK |
273 | and then both processes display the hostnames in their UTS namespaces, |
274 | so that we can see that they are different. | |
efeece04 | 275 | .PP |
8d41e607 | 276 | .in +4n |
b8302363 | 277 | .EX |
8d41e607 | 278 | $ \fBsu\fP # Need privilege for namespace operations |
9f1b9726 | 279 | Password: |
8d41e607 MK |
280 | # \fB./newuts bizarro &\fP |
281 | [1] 3549 | |
282 | clone() returned 3550 | |
283 | uts.nodename in child: bizarro | |
284 | uts.nodename in parent: antero | |
5c977011 | 285 | # \fBuname \-n\fP # Verify hostname in the shell |
8d41e607 | 286 | antero |
b8302363 | 287 | .EE |
e646a1ba | 288 | .in |
efeece04 | 289 | .PP |
8d41e607 MK |
290 | We then run the program shown below, |
291 | using it to execute a shell. | |
292 | Inside that shell, we verify that the hostname is the one | |
293 | set by the child created by the first program: | |
efeece04 | 294 | .PP |
8d41e607 | 295 | .in +4n |
b8302363 | 296 | .EX |
a1ce9159 | 297 | # \fB./ns_exec /proc/3550/ns/uts /bin/bash\fP |
5c977011 | 298 | # \fBuname \-n\fP # Executed in shell started by ns_exec |
8d41e607 | 299 | bizarro |
b8302363 | 300 | .EE |
e646a1ba | 301 | .in |
8d41e607 | 302 | .SS Program source |
e7d0bb47 | 303 | .EX |
8d41e607 MK |
304 | #define _GNU_SOURCE |
305 | #include <fcntl.h> | |
306 | #include <sched.h> | |
307 | #include <unistd.h> | |
308 | #include <stdlib.h> | |
309 | #include <stdio.h> | |
310 | ||
311 | #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ | |
312 | } while (0) | |
313 | ||
314 | int | |
315 | main(int argc, char *argv[]) | |
316 | { | |
317 | int fd; | |
318 | ||
319 | if (argc < 3) { | |
320 | fprintf(stderr, "%s /proc/PID/ns/FILE cmd args...\\n", argv[0]); | |
321 | exit(EXIT_FAILURE); | |
322 | } | |
323 | ||
e2b63503 | 324 | fd = open(argv[1], O_RDONLY); /* Get file descriptor for namespace */ |
8d41e607 MK |
325 | if (fd == \-1) |
326 | errExit("open"); | |
327 | ||
e2b63503 | 328 | if (setns(fd, 0) == \-1) /* Join that namespace */ |
8d41e607 MK |
329 | errExit("setns"); |
330 | ||
e2b63503 | 331 | execvp(argv[2], &argv[2]); /* Execute a command in namespace */ |
8d41e607 MK |
332 | errExit("execvp"); |
333 | } | |
e7d0bb47 | 334 | .EE |
dfa22c8b | 335 | .SH SEE ALSO |
7680cb3e | 336 | .BR nsenter (1), |
dfa22c8b EB |
337 | .BR clone (2), |
338 | .BR fork (2), | |
2a9f74a9 | 339 | .BR unshare (2), |
b93a34b5 | 340 | .BR vfork (2), |
41096af1 | 341 | .BR namespaces (7), |
92dcb220 | 342 | .BR unix (7) |