]>
Commit | Line | Data |
---|---|---|
dfa22c8b | 1 | .\" Copyright (C) 2011, Eric Biederman <ebiederm@xmission.com> |
8d41e607 | 2 | .\" and Copyright (C) 2011, 2012, Michael Kerrisk <mtk.manpages@gamil.com> |
2297bf0e | 3 | .\" |
c4a99c30 | 4 | .\" %%%LICENSE_START(GPLv2_ONELINE) |
dfa22c8b | 5 | .\" Licensed under the GPLv2 |
8ff7380d | 6 | .\" %%%LICENSE_END |
dfa22c8b | 7 | .\" |
8d41e607 | 8 | .TH SETNS 2 2013-01-01 "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> | |
15 | .sp | |
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. |
dfa22c8b | 21 | |
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 | |
27 | .BR proc (5) | |
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. | |
34 | ||
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 EB |
43 | .TP |
44 | .BR CLONE_NEWIPC | |
92dcb220 MK |
45 | .I fd |
46 | must refer to an IPC namespace. | |
dfa22c8b EB |
47 | .TP |
48 | .BR CLONE_NEWNET | |
92dcb220 MK |
49 | .I fd |
50 | must refer to a network namespace. | |
dfa22c8b | 51 | .TP |
99fd2fe3 EB |
52 | .BR CLONE_NEWNS |
53 | .I fd | |
54 | must refer to a mount namespace. | |
55 | .TP | |
56 | .BR CLONE_NEWPID | |
57 | .I fd | |
58 | must refer to a PID namespace. | |
59 | .TP | |
60 | .BR CLONE_NEWUSER | |
61 | .I fd | |
62 | must refer to a user namespace. | |
63 | .TP | |
dfa22c8b | 64 | .BR CLONE_NEWUTS |
92dcb220 MK |
65 | .I fd |
66 | must refer to a UTS namespace. | |
dfa22c8b | 67 | .PP |
92dcb220 MK |
68 | Specifying |
69 | .I nstype | |
70 | as 0 suffices if the caller knows (or does not care) | |
71 | what type of namespace is referred to by | |
72 | .IR fd . | |
73 | Specifying a nonzero value for | |
74 | .I nstype | |
75 | is useful if the caller does not know what type of namespace is referred to by | |
76 | .IR fd | |
77 | and wants to ensure that the namespace is of a particular type. | |
78 | (The caller might not know the type of the namespace referred to by | |
79 | .IR fd | |
80 | if the file descriptor was opened by another process and, for example, | |
81 | passed to the caller via a UNIX domain socket.) | |
99fd2fe3 | 82 | |
f16c7698 MK |
83 | .B CLONE_NEWPID |
84 | behaves somewhat differently from the other | |
85 | .I nstype | |
86 | values: | |
87 | reassociating the calling thread with a PID namespace only changes | |
88 | the PID namespace that child processes of the caller will be created in; | |
89 | it does not change the PID namespace of the caller itself. | |
90 | Reassociating with a PID namespace is only allowed if the | |
cd7e05aa | 91 | PID namespace specified by |
99fd2fe3 | 92 | .IR fd |
f16c7698 MK |
93 | is a descendant (child, grandchild, etc.) |
94 | PID namespace of the PID namespace of the caller. | |
99fd2fe3 | 95 | |
cd7e05aa MK |
96 | A multi-threaded process may not change user namespace with |
97 | .BR setns (). | |
49af76fe | 98 | A process may not reassociate the thread with the caller's user |
cd7e05aa | 99 | namespace. |
49af76fe | 100 | A process reassociating itself with a user namespace must have |
cd7e05aa | 101 | .B CAP_SYS_ADMIN |
49af76fe | 102 | .\" See kernel/user_namespace.c:userns_install() [3.8 source] |
cd7e05aa | 103 | privileges in the target user namespace. |
99fd2fe3 EB |
104 | |
105 | A process may not be reassociated with a new mount namespace if it is | |
49af76fe MK |
106 | multi-threaded. |
107 | .\" Above check is in fs/namespace.c:mntns_install() [3.8 source] | |
108 | Changing the mount namespace requires that the caller possess both | |
cd7e05aa MK |
109 | .B CAP_SYS_CHROOT |
110 | and | |
49af76fe | 111 | .BR CAP_SYS_ADMIN |
21bfe3e9 MK |
112 | capabilities in its own user namespace and |
113 | .BR CAP_SYS_ADMIN | |
114 | in the target mount namespace. | |
99fd2fe3 | 115 | |
dfa22c8b | 116 | .SH RETURN VALUE |
92dcb220 MK |
117 | On success, |
118 | .IR setns () | |
119 | returns 0. | |
dfa22c8b EB |
120 | On failure, \-1 is returned and |
121 | .I errno | |
122 | is set to indicate the error. | |
123 | .SH ERRORS | |
124 | .TP | |
dfa22c8b | 125 | .B EBADF |
c07ad242 MK |
126 | .I fd |
127 | is not a valid file descriptor. | |
dfa22c8b EB |
128 | .TP |
129 | .B EINVAL | |
92dcb220 MK |
130 | .I fd |
131 | refers to a namespace whose type does not match that specified in | |
7aa166c5 | 132 | .IR nstype , |
49af76fe | 133 | or there is problem with reassociating |
7aa166c5 | 134 | the thread with the specified namespace. |
dfa22c8b EB |
135 | .TP |
136 | .B ENOMEM | |
137 | Cannot allocate sufficient memory to change the specified namespace. | |
dfa22c8b EB |
138 | .TP |
139 | .B EPERM | |
c409c4ff | 140 | The calling thread did not have the required privilege |
63b6ef41 MK |
141 | .RB ( CAP_SYS_ADMIN ) |
142 | for this operation. | |
dfa22c8b EB |
143 | .SH VERSIONS |
144 | The | |
145 | .BR setns () | |
c95b6ae1 | 146 | system call first appeared in Linux in kernel 3.0; |
99fd2fe3 | 147 | library support was added to glibc in version 2.14; |
cd7e05aa | 148 | Support for PID, user, and mount namespaces first appeared in Linux 3.8. |
dfa22c8b EB |
149 | .SH CONFORMING TO |
150 | The | |
151 | .BR setns () | |
152 | system call is Linux-specific. | |
153 | .SH NOTES | |
7aa166c5 MK |
154 | Not all of the attributes that can be shared when |
155 | a new thread is created using | |
dfa22c8b EB |
156 | .BR clone (2) |
157 | can be changed using | |
158 | .BR setns (). | |
8d41e607 MK |
159 | .SH EXAMPLE |
160 | The program below takes two or more arguments. | |
161 | The first argument specifies the pathname of a namespace file in an existing | |
162 | .I /proc/[pid]/ns/ | |
163 | directory. | |
164 | The remaining arguments specify a command and its arguments. | |
165 | The program opens the namespace file, joins that namespace using | |
166 | .BR setns (), | |
167 | and executes the specified command inside that namespace. | |
168 | ||
169 | The following shell session demonstrates the use of this program | |
170 | (compiled as a binary named | |
a1ce9159 | 171 | .IR ns_exec ) |
8d41e607 MK |
172 | in conjunction with the |
173 | .BR CLONE_NEWUTS | |
174 | example program in the | |
175 | .BR clone (2) | |
176 | man page (complied as a binary named | |
177 | .IR newuts ). | |
178 | ||
179 | We begin by executing the example program in | |
180 | .BR clone (2) | |
181 | in the background. | |
182 | That program creates a child in a separate UTS namespace. | |
51ebe080 | 183 | The child changes the hostname in its namespace, |
8d41e607 MK |
184 | and then both processes display the hostnames in their UTS namespaces, |
185 | so that we can see that they are different. | |
186 | ||
187 | .nf | |
188 | .in +4n | |
189 | $ \fBsu\fP # Need privilege for namespace operations | |
9f1b9726 | 190 | Password: |
8d41e607 MK |
191 | # \fB./newuts bizarro &\fP |
192 | [1] 3549 | |
193 | clone() returned 3550 | |
194 | uts.nodename in child: bizarro | |
195 | uts.nodename in parent: antero | |
5c977011 | 196 | # \fBuname \-n\fP # Verify hostname in the shell |
8d41e607 MK |
197 | antero |
198 | .in | |
199 | .fi | |
200 | ||
201 | We then run the program shown below, | |
202 | using it to execute a shell. | |
203 | Inside that shell, we verify that the hostname is the one | |
204 | set by the child created by the first program: | |
205 | ||
206 | .nf | |
207 | .in +4n | |
a1ce9159 | 208 | # \fB./ns_exec /proc/3550/ns/uts /bin/bash\fP |
5c977011 | 209 | # \fBuname \-n\fP # Executed in shell started by ns_exec |
8d41e607 MK |
210 | bizarro |
211 | .in | |
212 | .fi | |
8d41e607 MK |
213 | .SS Program source |
214 | .nf | |
215 | #define _GNU_SOURCE | |
216 | #include <fcntl.h> | |
217 | #include <sched.h> | |
218 | #include <unistd.h> | |
219 | #include <stdlib.h> | |
220 | #include <stdio.h> | |
221 | ||
222 | #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\ | |
223 | } while (0) | |
224 | ||
225 | int | |
226 | main(int argc, char *argv[]) | |
227 | { | |
228 | int fd; | |
229 | ||
230 | if (argc < 3) { | |
231 | fprintf(stderr, "%s /proc/PID/ns/FILE cmd args...\\n", argv[0]); | |
232 | exit(EXIT_FAILURE); | |
233 | } | |
234 | ||
235 | fd = open(argv[1], O_RDONLY); /* Get descriptor for namespace */ | |
236 | if (fd == \-1) | |
237 | errExit("open"); | |
238 | ||
239 | if (setns(fd, 0) == \-1) /* Join that namespace */ | |
240 | errExit("setns"); | |
241 | ||
242 | execvp(argv[2], &argv[2]); /* Execute a command in namespace */ | |
243 | errExit("execvp"); | |
244 | } | |
245 | .fi | |
dfa22c8b EB |
246 | .SH SEE ALSO |
247 | .BR clone (2), | |
248 | .BR fork (2), | |
2a9f74a9 | 249 | .BR unshare (2), |
b93a34b5 | 250 | .BR vfork (2), |
92dcb220 MK |
251 | .BR proc (5), |
252 | .BR unix (7) |