man2/setns.2

   1 .\" Copyright (C) 2011, Eric Biederman <ebiederm@xmission.com>
   2 .\" and Copyright (C) 2011, 2012, Michael Kerrisk <mtk.manpages@gamil.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2_ONELINE)
   5 .\" Licensed under the GPLv2
   6 .\" %%%LICENSE_END
   7 .\"
   8 .TH SETNS 2 2013-01-01 "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 .sp
  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
  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 (5)
  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
  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_NEWIPC " (since Linux 3.0)"
  45 .I fd
  46 must refer to an IPC namespace.
  47 .TP
  48 .BR CLONE_NEWNET " (since Linux 3.0)"
  49 .I fd
  50 must refer to a network namespace.
  51 .TP
  52 .BR CLONE_NEWNS " (since Linux 3.8)"
  53 .I fd
  54 must refer to a mount namespace.
  55 .TP
  56 .BR CLONE_NEWPID " (since Linux 3.8)"
  57 .I fd
  58 must refer to a PID namespace.
  59 .TP
  60 .BR CLONE_NEWUSER " (since Linux 3.8)"
  61 .I fd
  62 must refer to a user namespace.
  63 .TP
  64 .BR CLONE_NEWUTS " (since Linux 3.0)"
  65 .I fd
  66 must refer to a UTS namespace.
  67 .PP
  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.)
  82
  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
  91 PID namespace specified by
  92 .IR fd
  93 is a descendant (child, grandchild, etc.)
  94 of the PID namespace of the caller.
  95 For further details on PID namespaces, see
  96 .BR user_namespaces (7).
  97
  98 A process reassociating itself with a user namespace must have the
  99 .B CAP_SYS_ADMIN
 100 .\" See kernel/user_namespace.c:userns_install() [3.8 source]
 101 capability in the target 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 A multithreaded process may not change user namespace with
 106 .BR setns ().
 107 It is not permitted to use
 108 .BR setns ()
 109 to reenter the caller's current user namespace.
 110 This prevents a caller that has dropped capabilities from regaining
 111 those capabilities via a call to
 112 .BR setns ().
 113 For security reasons,
 114 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
 115 .\" https://lwn.net/Articles/543273/
 116 a process can't join a new user namespace if it is sharing
 117 filesystem-related attributes
 118 (the attributes whose sharing is controlled by the
 119 .BR clone (2)
 120 .B CLONE_FS
 121 flag) with another process.
 122 For further details on user namespaces, see
 123 .BR user_namespaces (7).
 124
 125 A process may not be reassociated with a new mount namespace if it is
 126 multithreaded.
 127 .\" Above check is in fs/namespace.c:mntns_install() [3.8 source]
 128 Changing the mount namespace requires that the caller possess both
 129 .B CAP_SYS_CHROOT
 130 and
 131 .BR CAP_SYS_ADMIN
 132 capabilities in its own user namespace and
 133 .BR CAP_SYS_ADMIN
 134 in the target mount namespace.
 135 .SH RETURN VALUE
 136 On success,
 137 .IR setns ()
 138 returns 0.
 139 On failure, \-1 is returned and
 140 .I errno
 141 is set to indicate the error.
 142 .SH ERRORS
 143 .TP
 144 .B EBADF
 145 .I fd
 146 is not a valid file descriptor.
 147 .TP
 148 .B EINVAL
 149 .I fd
 150 refers to a namespace whose type does not match that specified in
 151 .IR nstype .
 152 .TP
 153 .B EINVAL
 154 There is problem with reassociating
 155 the thread with the specified namespace.
 156 .TP
 157 .B EINVAL
 158 The caller attempted to join the user namespace
 159 in which it is already a member.
 160 .TP
 161 .B ENOMEM
 162 Cannot allocate sufficient memory to change the specified namespace.
 163 .TP
 164 .B EPERM
 165 The calling thread did not have the required capability
 166 for this operation.
 167 .SH VERSIONS
 168 The
 169 .BR setns ()
 170 system call first appeared in Linux in kernel 3.0;
 171 library support was added to glibc in version 2.14.
 172 .SH CONFORMING TO
 173 The
 174 .BR setns ()
 175 system call is Linux-specific.
 176 .SH NOTES
 177 Not all of the attributes that can be shared when
 178 a new thread is created using
 179 .BR clone (2)
 180 can be changed using
 181 .BR setns ().
 182 .SH EXAMPLE
 183 The program below takes two or more arguments.
 184 The first argument specifies the pathname of a namespace file in an existing
 185 .I /proc/[pid]/ns/
 186 directory.
 187 The remaining arguments specify a command and its arguments.
 188 The program opens the namespace file, joins that namespace using
 189 .BR setns (),
 190 and executes the specified command inside that namespace.
 191
 192 The following shell session demonstrates the use of this program
 193 (compiled as a binary named
 194 .IR ns_exec )
 195 in conjunction with the
 196 .BR CLONE_NEWUTS
 197 example program in the
 198 .BR clone (2)
 199 man page (complied as a binary named
 200 .IR newuts ).
 201
 202 We begin by executing the example program in
 203 .BR clone (2)
 204 in the background.
 205 That program creates a child in a separate UTS namespace.
 206 The child changes the hostname in its namespace,
 207 and then both processes display the hostnames in their UTS namespaces,
 208 so that we can see that they are different.
 209
 210 .nf
 211 .in +4n
 212 $ \fBsu\fP                   # Need privilege for namespace operations
 213 Password:
 214 # \fB./newuts bizarro &\fP
 215 [1] 3549
 216 clone() returned 3550
 217 uts.nodename in child:  bizarro
 218 uts.nodename in parent: antero
 219 # \fBuname \-n\fP             # Verify hostname in the shell
 220 antero
 221 .in
 222 .fi
 223
 224 We then run the program shown below,
 225 using it to execute a shell.
 226 Inside that shell, we verify that the hostname is the one
 227 set by the child created by the first program:
 228
 229 .nf
 230 .in +4n
 231 # \fB./ns_exec /proc/3550/ns/uts /bin/bash\fP
 232 # \fBuname \-n\fP             # Executed in shell started by ns_exec
 233 bizarro
 234 .in
 235 .fi
 236 .SS Program source
 237 .nf
 238 #define _GNU_SOURCE
 239 #include <fcntl.h>
 240 #include <sched.h>
 241 #include <unistd.h>
 242 #include <stdlib.h>
 243 #include <stdio.h>
 244
 245 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \\
 246                         } while (0)
 247
 248 int
 249 main(int argc, char *argv[])
 250 {
 251     int fd;
 252
 253     if (argc < 3) {
 254         fprintf(stderr, "%s /proc/PID/ns/FILE cmd args...\\n", argv[0]);
 255         exit(EXIT_FAILURE);
 256     }
 257
 258     fd = open(argv[1], O_RDONLY);   /* Get descriptor for namespace */
 259     if (fd == \-1)
 260         errExit("open");
 261
 262     if (setns(fd, 0) == \-1)         /* Join that namespace */
 263         errExit("setns");
 264
 265     execvp(argv[2], &argv[2]);      /* Execute a command in namespace */
 266     errExit("execvp");
 267 }
 268 .fi
 269 .SH SEE ALSO
 270 .BR clone (2),
 271 .BR fork (2),
 272 .BR unshare (2),
 273 .BR vfork (2),
 274 .BR namespaces (7),
 275 .BR unix (7)