man2/setns.2

   1 .\" Copyright (C) 2011, Eric Biederman <ebiederm@xmission.com>
   2 .\" and Copyright (C) 2011, 2012, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2_ONELINE)
   5 .\" Licensed under the GPLv2
   6 .\" %%%LICENSE_END
   7 .\"
   8 .TH SETNS 2 2020-04-11 "Linux" "Linux Programmer's Manual"
   9 .SH NAME
  10 setns \- reassociate thread with a namespace
  11 .SH SYNOPSIS
  12 .nf
  13 .BR "#define _GNU_SOURCE" "             /* See feature_test_macros(7) */"
  14 .B #include <sched.h>
  15 .PP
  16 .BI "int setns(int " fd ", int " nstype );
  17 .fi
  18 .SH DESCRIPTION
  19 Given a file descriptor referring to a namespace,
  20 reassociate the calling thread with that namespace.
  21 .PP
  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 namespaces (7)
  28 for further information on
  29 .IR /proc/[pid]/ns/ .
  30 The calling thread will be reassociated with the corresponding namespace,
  31 subject to any constraints imposed by the
  32 .I nstype
  33 argument.
  34 .PP
  35 The
  36 .I nstype
  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:
  40 .TP
  41 .BR 0
  42 Allow any type of namespace to be joined.
  43 .TP
  44 .BR CLONE_NEWCGROUP " (since Linux 4.6)"
  45 .I fd
  46 must refer to a cgroup namespace.
  47 .TP
  48 .BR CLONE_NEWIPC " (since Linux 3.0)"
  49 .I fd
  50 must refer to an IPC namespace.
  51 .TP
  52 .BR CLONE_NEWNET " (since Linux 3.0)"
  53 .I fd
  54 must refer to a network namespace.
  55 .TP
  56 .BR CLONE_NEWNS " (since Linux 3.8)"
  57 .I fd
  58 must refer to a mount namespace.
  59 .TP
  60 .BR CLONE_NEWPID " (since Linux 3.8)"
  61 .I fd
  62 must refer to a descendant PID namespace.
  63 .TP
  64 .BR CLONE_NEWTIME " (since Linux 5.6)"
  65 .I fd
  66 must refer to a time namespace.
  67 .TP
  68 .BR CLONE_NEWUSER " (since Linux 3.8)"
  69 .I fd
  70 must refer to a user namespace.
  71 .TP
  72 .BR CLONE_NEWUTS " (since Linux 3.0)"
  73 .I fd
  74 must refer to a UTS namespace.
  75 .PP
  76 Specifying
  77 .I nstype
  78 as 0 suffices if the caller knows (or does not care)
  79 what type of namespace is referred to by
  80 .IR fd .
  81 Specifying a nonzero value for
  82 .I nstype
  83 is useful if the caller does not know what type of namespace is referred to by
  84 .IR fd
  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
  87 .IR fd
  88 if the file descriptor was opened by another process and, for example,
  89 passed to the caller via a UNIX domain socket.)
  90 .\"
  91 .SS Details for specific namespace types
  92 Note the following details and restrictions when reassociating with
  93 specific namespace types:
  94 .TP
  95 User namespaces
  96 A process reassociating itself with a user namespace must have the
  97 .B CAP_SYS_ADMIN
  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.
 105 .IP
 106 A multithreaded process may not change user namespace with
 107 .BR setns ().
 108 .IP
 109 It is not permitted to use
 110 .BR setns ()
 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
 114 .BR setns ().
 115 .IP
 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
 122 .BR clone (2)
 123 .B CLONE_FS
 124 flag) with another process.
 125 .IP
 126 For further details on user namespaces, see
 127 .BR user_namespaces (7).
 128 .TP
 129 Mount namespaces
 130 Changing the mount namespace requires that the caller possess both
 131 .B CAP_SYS_CHROOT
 132 and
 133 .BR CAP_SYS_ADMIN
 134 capabilities in its own user namespace and
 135 .BR CAP_SYS_ADMIN
 136 in the user namespace that owns the target mount namespace.
 137 .IP
 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
 141 .BR clone (2)
 142 .B CLONE_FS
 143 flag) with another process.
 144 .\" Above check is in fs/namespace.c:mntns_install() [3.8 source]
 145 .IP
 146 See
 147 .BR user_namespaces (7)
 148 for details on the interaction of user namespaces and mount namespaces.
 149 .TP
 150 PID namespaces
 151 In order to reassociate itself with a new PID namespace,
 152 the caller must have the
 153 .B CAP_SYS_ADMIN
 154 capability both in its own user namespace and in the user namespace
 155 that owns the target PID namespace.
 156 .IP
 157 If
 158 .I fd
 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.
 165 .IP
 166 Reassociating with a PID namespace is allowed only if the
 167 PID namespace specified by
 168 .IR fd
 169 is a descendant (child, grandchild, etc.)
 170 of the PID namespace of the caller.
 171 .IP
 172 For further details on PID namespaces, see
 173 .BR pid_namespaces (7).
 174 .TP
 175 Cgroup namespaces
 176 In order to reassociate itself with a new cgroup namespace,
 177 the caller must have the
 178 .B CAP_SYS_ADMIN
 179 capability both in its own user namespace and in the user namespace
 180 that owns the target cgroup namespace.
 181 .IP
 182 Using
 183 .BR setns ()
 184 to change the caller's cgroup namespace does not change
 185 the caller's cgroup memberships.
 186 .TP
 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
 190 .B CAP_SYS_ADMIN
 191 capability both in its own user namespace and in the user namespace
 192 that owns the target namespace.
 193 .SH RETURN VALUE
 194 On success,
 195 .BR setns ()
 196 returns 0.
 197 On failure, \-1 is returned and
 198 .I errno
 199 is set to indicate the error.
 200 .SH ERRORS
 201 .TP
 202 .B EBADF
 203 .I fd
 204 is not a valid file descriptor.
 205 .TP
 206 .B EINVAL
 207 .I fd
 208 refers to a namespace whose type does not match that specified in
 209 .IR nstype .
 210 .TP
 211 .B EINVAL
 212 There is problem with reassociating
 213 the thread with the specified namespace.
 214 .TP
 215 .\" See kernel/pid_namespace.c::pidns_install() [kernel 3.18 sources]
 216 .B EINVAL
 217 The caller tried to join an ancestor (parent, grandparent, and so on)
 218 PID namespace.
 219 .TP
 220 .B EINVAL
 221 The caller attempted to join the user namespace
 222 in which it is already a member.
 223 .TP
 224 .B EINVAL
 225 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
 226 The caller shares filesystem
 227 .RB ( CLONE_FS )
 228 state (in particular, the root directory)
 229 with other processes and tried to join a new user namespace.
 230 .TP
 231 .B EINVAL
 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.
 234 .TP
 235 .B ENOMEM
 236 Cannot allocate sufficient memory to change the specified namespace.
 237 .TP
 238 .B EPERM
 239 The calling thread did not have the required capability
 240 for this operation.
 241 .SH VERSIONS
 242 The
 243 .BR setns ()
 244 system call first appeared in Linux in kernel 3.0;
 245 library support was added to glibc in version 2.14.
 246 .SH CONFORMING TO
 247 The
 248 .BR setns ()
 249 system call is Linux-specific.
 250 .SH NOTES
 251 Not all of the attributes that can be shared when
 252 a new thread is created using
 253 .BR clone (2)
 254 can be changed using
 255 .BR setns ().
 256 .SH EXAMPLE
 257 The program below takes two or more arguments.
 258 The first argument specifies the pathname of a namespace file in an existing
 259 .I /proc/[pid]/ns/
 260 directory.
 261 The remaining arguments specify a command and its arguments.
 262 The program opens the namespace file, joins that namespace using
 263 .BR setns (),
 264 and executes the specified command inside that namespace.
 265 .PP
 266 The following shell session demonstrates the use of this program
 267 (compiled as a binary named
 268 .IR ns_exec )
 269 in conjunction with the
 270 .BR CLONE_NEWUTS
 271 example program in the
 272 .BR clone (2)
 273 man page (complied as a binary named
 274 .IR newuts ).
 275 .PP
 276 We begin by executing the example program in
 277 .BR clone (2)
 278 in the background.
 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.
 283 .PP
 284 .in +4n
 285 .EX
 286 $ \fBsu\fP                   # Need privilege for namespace operations
 287 Password:
 288 # \fB./newuts bizarro &\fP
 289 [1] 3549
 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
 294 antero
 295 .EE
 296 .in
 297 .PP
 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:
 302 .PP
 303 .in +4n
 304 .EX
 305 # \fB./ns_exec /proc/3550/ns/uts /bin/bash\fP
 306 # \fBuname \-n\fP             # Executed in shell started by ns_exec
 307 bizarro
 308 .EE
 309 .in
 310 .SS Program source
 311 .EX
 312 #define _GNU_SOURCE
 313 #include <fcntl.h>
 314 #include <sched.h>
 315 #include <unistd.h>
 316 #include <stdlib.h>
 317 #include <stdio.h>
 318
 319 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 320                         } while (0)
 321
 322 int
 323 main(int argc, char *argv[])
 324 {
 325     int fd;
 326
 327     if (argc < 3) {
 328         fprintf(stderr, "%s /proc/PID/ns/FILE cmd args...\en", argv[0]);
 329         exit(EXIT_FAILURE);
 330     }
 331
 332     fd = open(argv[1], O_RDONLY); /* Get file descriptor for namespace */
 333     if (fd == \-1)
 334         errExit("open");
 335
 336     if (setns(fd, 0) == \-1)       /* Join that namespace */
 337         errExit("setns");
 338
 339     execvp(argv[2], &argv[2]);    /* Execute a command in namespace */
 340     errExit("execvp");
 341 }
 342 .EE
 343 .SH SEE ALSO
 344 .BR nsenter (1),
 345 .BR clone (2),
 346 .BR fork (2),
 347 .BR unshare (2),
 348 .BR vfork (2),
 349 .BR namespaces (7),
 350 .BR unix (7)