1SETNS(2)                   Linux Programmer's Manual                  SETNS(2)
2
3
4

NAME

6       setns - reassociate thread with a namespace
7

SYNOPSIS

9       #define _GNU_SOURCE             /* See feature_test_macros(7) */
10       #include <sched.h>
11
12       int setns(int fd, int nstype);
13

DESCRIPTION

15       The  setns() system call allows the calling thread to move into differ‐
16       ent namespaces.  The fd argument is one of the following:
17
18       • a  file  descriptor  referring  to  one  of  the  magic  links  in  a
19         /proc/[pid]/ns/ directory (or a bind mount to such a link);
20
21       • a PID file descriptor (see pidfd_open(2)).
22
23       The nstype argument is interpreted differently in each case.
24
25   fd refers to a /proc/[pid]/ns/ link
26       If  fd  refers to a /proc/[pid]/ns/ link, then setns() reassociates the
27       calling thread with the namespace associated with that link, subject to
28       any  constraints  imposed  by the nstype argument.  In this usage, each
29       call to setns() changes just one of the caller's namespace memberships.
30
31       The nstype argument specifies  which  type  of  namespace  the  calling
32       thread  may  be  reassociated  with.  This argument can have one of the
33       following values:
34
35       0      Allow any type of namespace to be joined.
36
37       CLONE_NEWCGROUP (since Linux 4.6)
38              fd must refer to a cgroup namespace.
39
40       CLONE_NEWIPC (since Linux 3.0)
41              fd must refer to an IPC namespace.
42
43       CLONE_NEWNET (since Linux 3.0)
44              fd must refer to a network namespace.
45
46       CLONE_NEWNS (since Linux 3.8)
47              fd must refer to a mount namespace.
48
49       CLONE_NEWPID (since Linux 3.8)
50              fd must refer to a descendant PID namespace.
51
52       CLONE_NEWTIME (since Linux 5.8)
53              fd must refer to a time namespace.
54
55       CLONE_NEWUSER (since Linux 3.8)
56              fd must refer to a user namespace.
57
58       CLONE_NEWUTS (since Linux 3.0)
59              fd must refer to a UTS namespace.
60
61       Specifying nstype as 0 suffices if the caller knows (or does not  care)
62       what  type  of  namespace  is  referred to by fd.  Specifying a nonzero
63       value for nstype is useful if the caller does not  know  what  type  of
64       namespace  is  referred to by fd and wants to ensure that the namespace
65       is of a particular type.  (The caller might not know the  type  of  the
66       namespace  referred  to  by fd if the file descriptor was opened by an‐
67       other process and, for example, passed to the caller via a UNIX  domain
68       socket.)
69
70   fd is a PID file descriptor
71       Since  Linux  5.8,  fd may refer to a PID file descriptor obtained from
72       pidfd_open(2) or clone(3).  In this usage, setns() atomically moves the
73       calling  thread  into  one or more of the same namespaces as the thread
74       referred to by fd.
75
76       The nstype argument is a bit mask specified by ORing  together  one  or
77       more of the CLONE_NEW* namespace constants listed above.  The caller is
78       moved into each of the target thread's namespaces that is specified  in
79       nstype;  the  caller's memberships in the remaining namespaces are left
80       unchanged.
81
82       For example, the following code would move the  caller  into  the  same
83       user,  network,  and  UTS  namespaces  as PID 1234, but would leave the
84       caller's other namespace memberships unchanged:
85
86           int fd = pidfd_open(1234, 0);
87           setns(fd, CLONE_NEWUSER | CLONE_NEWNET | CLONE_NEWUTS);
88
89   Details for specific namespace types
90       Note the following details and  restrictions  when  reassociating  with
91       specific namespace types:
92
93       User namespaces
94              A  process  reassociating itself with a user namespace must have
95              the CAP_SYS_ADMIN  capability  in  the  target  user  namespace.
96              (This necessarily implies that it is only possible to join a de‐
97              scendant user namespace.)   Upon  successfully  joining  a  user
98              namespace,  a  process is granted all capabilities in that name‐
99              space, regardless of its user and group IDs.
100
101              A multithreaded process  may  not  change  user  namespace  with
102              setns().
103
104              It  is not permitted to use setns() to reenter the caller's cur‐
105              rent user namespace.  This prevents a caller  that  has  dropped
106              capabilities  from  regaining  those  capabilities via a call to
107              setns().
108
109              For security reasons, a process can't join a new user  namespace
110              if  it  is sharing filesystem-related attributes (the attributes
111              whose sharing is controlled by the clone(2) CLONE_FS flag)  with
112              another process.
113
114              For further details on user namespaces, see user_namespaces(7).
115
116       Mount namespaces
117              Changing  the  mount  namespace requires that the caller possess
118              both CAP_SYS_CHROOT and CAP_SYS_ADMIN capabilities  in  its  own
119              user namespace and CAP_SYS_ADMIN in the user namespace that owns
120              the target mount namespace.
121
122              A process can't join a new mount  namespace  if  it  is  sharing
123              filesystem-related  attributes  (the attributes whose sharing is
124              controlled by the clone(2) CLONE_FS flag) with another process.
125
126              See user_namespaces(7) for details on the  interaction  of  user
127              namespaces and mount namespaces.
128
129       PID namespaces
130              In  order  to  reassociate  itself with a new PID namespace, the
131              caller must have the CAP_SYS_ADMIN capability both  in  its  own
132              user  namespace  and  in the user namespace that owns the target
133              PID namespace.
134
135              Reassociating the PID  namespace  has  somewhat  different  from
136              other  namespace types.  Reassociating the calling thread with a
137              PID namespace changes only the PID namespace  that  subsequently
138              created child processes of the caller will be placed in; it does
139              not change the PID namespace of the caller itself.
140
141              Reassociating with a PID namespace is allowed only if the target
142              PID  namespace is a descendant (child, grandchild, etc.)  of, or
143              is the same as, the current PID namespace of the caller.
144
145              For further details on PID namespaces, see pid_namespaces(7).
146
147       Cgroup namespaces
148              In order to reassociate itself with a new cgroup namespace,  the
149              caller  must  have  the CAP_SYS_ADMIN capability both in its own
150              user namespace and in the user namespace that  owns  the  target
151              cgroup namespace.
152
153              Using  setns()  to change the caller's cgroup namespace does not
154              change the caller's cgroup memberships.
155
156       Network, IPC, time, and UTS namespaces
157              In order to reassociate itself with a new network, IPC, time, or
158              UTS namespace, the caller must have the CAP_SYS_ADMIN capability
159              both in its own user namespace and in the  user  namespace  that
160              owns the target namespace.
161

RETURN VALUE

163       On success, setns() returns 0.  On failure, -1 is returned and errno is
164       set to indicate the error.
165

ERRORS

167       EBADF  fd is not a valid file descriptor.
168
169       EINVAL fd refers to a namespace whose type does not match  that  speci‐
170              fied in nstype.
171
172       EINVAL There  is  problem with reassociating the thread with the speci‐
173              fied namespace.
174
175       EINVAL The caller tried to join an ancestor (parent,  grandparent,  and
176              so on) PID namespace.
177
178       EINVAL The  caller  attempted to join the user namespace in which it is
179              already a member.
180
181       EINVAL The caller shares filesystem (CLONE_FS)  state  (in  particular,
182              the root directory) with other processes and tried to join a new
183              user namespace.
184
185       EINVAL The caller is multithreaded and tried to join a new  user  name‐
186              space.
187
188       EINVAL fd  is  a PID file descriptor and nstype is invalid (e.g., it is
189              0).
190
191       ENOMEM Cannot allocate sufficient memory to change the specified  name‐
192              space.
193
194       EPERM  The calling thread did not have the required capability for this
195              operation.
196
197       ESRCH  fd is a PID file descriptor but the  process  it  refers  to  no
198              longer exists (i.e., it has terminated and been waited on).
199

VERSIONS

201       The  setns() system call first appeared in Linux in kernel 3.0; library
202       support was added to glibc in version 2.14.
203

CONFORMING TO

205       The setns() system call is Linux-specific.
206

NOTES

208       For further information on the /proc/[pid]/ns/ magic links,  see  name‐
209       spaces(7).
210
211       Not  all of the attributes that can be shared when a new thread is cre‐
212       ated using clone(2) can be changed using setns().
213

EXAMPLES

215       The program below takes two or  more  arguments.   The  first  argument
216       specifies   the   pathname   of   a   namespace  file  in  an  existing
217       /proc/[pid]/ns/ directory.  The remaining arguments specify  a  command
218       and  its  arguments.   The program opens the namespace file, joins that
219       namespace using setns(), and executes the specified command inside that
220       namespace.
221
222       The  following shell session demonstrates the use of this program (com‐
223       piled as a binary named ns_exec) in conjunction with  the  CLONE_NEWUTS
224       example  program  in  the clone(2) man page (complied as a binary named
225       newuts).
226
227       We begin by executing the example program  in  clone(2)  in  the  back‐
228       ground.  That program creates a child in a separate UTS namespace.  The
229       child changes the hostname in its namespace, and  then  both  processes
230       display  the hostnames in their UTS namespaces, so that we can see that
231       they are different.
232
233           $ su                   # Need privilege for namespace operations
234           Password:
235           # ./newuts bizarro &
236           [1] 3549
237           clone() returned 3550
238           uts.nodename in child:  bizarro
239           uts.nodename in parent: antero
240           # uname -n             # Verify hostname in the shell
241           antero
242
243       We then run the program shown below, using it to execute a shell.   In‐
244       side  that  shell,  we  verify  that the hostname is the one set by the
245       child created by the first program:
246
247           # ./ns_exec /proc/3550/ns/uts /bin/bash
248           # uname -n             # Executed in shell started by ns_exec
249           bizarro
250
251   Program source
252       #define _GNU_SOURCE
253       #include <fcntl.h>
254       #include <sched.h>
255       #include <unistd.h>
256       #include <stdlib.h>
257       #include <stdio.h>
258
259       #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
260                               } while (0)
261
262       int
263       main(int argc, char *argv[])
264       {
265           int fd;
266
267           if (argc < 3) {
268               fprintf(stderr, "%s /proc/PID/ns/FILE cmd args...\n", argv[0]);
269               exit(EXIT_FAILURE);
270           }
271
272           /* Get file descriptor for namespace; the file descriptor is opened
273              with O_CLOEXEC so as to ensure that it is not inherited by the
274              program that is later executed. */
275
276           fd = open(argv[1], O_RDONLY | O_CLOEXEC);
277           if (fd == -1)
278               errExit("open");
279
280           if (setns(fd, 0) == -1)       /* Join that namespace */
281               errExit("setns");
282
283           execvp(argv[2], &argv[2]);    /* Execute a command in namespace */
284           errExit("execvp");
285       }
286

SEE ALSO

288       nsenter(1), clone(2),  fork(2),  unshare(2),  vfork(2),  namespaces(7),
289       unix(7)
290

COLOPHON

292       This  page  is  part of release 5.10 of the Linux man-pages project.  A
293       description of the project, information about reporting bugs,  and  the
294       latest     version     of     this    page,    can    be    found    at
295       https://www.kernel.org/doc/man-pages/.
296
297
298
299Linux                             2020-08-13                          SETNS(2)
Impressum