man2/pivot_root.2

   1 .\" Copyright (C) 2000 by Werner Almesberger
   2 .\" and Copyright (C) 2019 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   5 .\" May be distributed under GPL
   6 .\" %%%LICENSE_END
   7 .\"
   8 .\" Written 2000-02-23 by Werner Almesberger
   9 .\" Modified 2004-06-17 Michael Kerrisk <mtk.manpages@gmail.com>
  10 .\"
  11 .TH PIVOT_ROOT 2 2019-08-02 "Linux" "Linux Programmer's Manual"
  12 .SH NAME
  13 pivot_root \- change the root mount
  14 .SH SYNOPSIS
  15 .BI "int pivot_root(const char *" new_root ", const char *" put_old );
  16 .PP
  17 .IR Note :
  18 There is no glibc wrapper for this system call; see NOTES.
  19 .SH DESCRIPTION
  20 .BR pivot_root ()
  21 changes the root mount in the mount namespace of the calling process.
  22 More precisely, it moves the root mount to the
  23 directory \fIput_old\fP and makes \fInew_root\fP the new root mount.
  24 The calling process must have the
  25 .B CAP_SYS_ADMIN
  26 capability in the user namespace that owns the caller's mount namespace.
  27 .PP
  28 .BR pivot_root ()
  29 changes the root directory and the current working directory
  30 of each process or thread in the same mount namespace to
  31 .I new_root
  32 if they point to the old root directory.
  33 (See also NOTES.)
  34 On the other hand,
  35 .BR pivot_root ()
  36 does not change the caller's current working directory
  37 (unless it is on the old root directory),
  38 and thus it should be followed by a
  39 \fBchdir("/")\fP call.
  40 .PP
  41 The following restrictions apply:
  42 .IP \- 3
  43 .IR new_root
  44 and
  45 .IR put_old
  46 must be directories.
  47 .IP \-
  48 .I new_root
  49 and
  50 .I put_old
  51 must not be on the same mount as the current root.
  52 .IP \-
  53 \fIput_old\fP must be at or underneath \fInew_root\fP;
  54 that is, adding some nonnegative
  55 number of "\fI/..\fP" prefixes to the pathname pointed to by
  56 .I put_old
  57 must yield the same directory as \fInew_root\fP.
  58 .IP \-
  59 .I new_root
  60 must be a path to a mount point, but can't be
  61 .IR """/""" .
  62 A path that is not already a mount point can be converted into one by
  63 bind mounting the path onto itself.
  64 .IP \-
  65 The propagation type of the parent mount of
  66 .IR new_root
  67 and the parent mount of the current root directory must not be
  68 .BR MS_SHARED ;
  69 similarly, if
  70 .I put_old
  71 is an existing mount point, its propagation type must not be
  72 .BR MS_SHARED .
  73 These restrictions ensure that
  74 .BR pivot_root ()
  75 never propagates any changes to another mount namespace.
  76 .IP \-
  77 The current root directory must be a mount point.
  78 .SH RETURN VALUE
  79 On success, zero is returned.
  80 On error, \-1 is returned, and
  81 \fIerrno\fP is set appropriately.
  82 .SH ERRORS
  83 .BR pivot_root ()
  84 may fail with any of the same errors as
  85 .BR stat (2).
  86 Additionally, it may fail with the following errors:
  87 .TP
  88 .B EBUSY
  89 .\" Reconfirmed that the following error occurs on Linux 5.0 by
  90 .\" specifying 'new_root' as "/rootfs" and 'put_old' as
  91 .\" "/rootfs/oldrootfs", and *not* bind mounting "/rootfs" on top of
  92 .\" itself. Of course, this is an odd situation, since a later check
  93 .\" in the kernel code will in any case yield EINVAL if 'new_root' is
  94 .\" not a mount point. However, when the system call was first added,
  95 .\" 'new_root' was not required to be a mount point. So, this
  96 .\" error is nowadays probably just the result of crufty accumulation.
  97 .\" This error can also occur if we bind mount "/" on top of itself
  98 .\" and try to specify "/" as the 'new' (again, an odd situation). So,
  99 .\" the EBUSY check in the kernel does still seem necessary to prevent
 100 .\" that case.  Furthermore, the "or put_old" piece is probably
 101 .\" redundant text (although the check is in the kernel), since,
 102 .\" in another check, 'put_old' is required to be under 'new_root'.
 103 .I new_root
 104 or
 105 .I put_old
 106 is on the current root mount.
 107 (This error covers the pathological case where
 108 .I new_root
 109 is
 110 .IR """/""" .)
 111 .TP
 112 .B EINVAL
 113 .I new_root
 114 is not a mount point.
 115 .TP
 116 .B EINVAL
 117 \fIput_old\fP is not at or underneath \fInew_root\fP.
 118 .TP
 119 .B EINVAL
 120 The current root directory is not a mount point
 121 (because of an earlier
 122 .BR chroot (2)).
 123 .TP
 124 .B EINVAL
 125 The current root is on the rootfs (initial ramfs) mount; see NOTES.
 126 .TP
 127 .B EINVAL
 128 Either the mount point at
 129 .IR new_root ,
 130 or the parent mount of that mount point,
 131 has propagation type
 132 .BR MS_SHARED .
 133 .TP
 134 .B EINVAL
 135 .I put_old
 136 is a mount point and has the propagation type
 137 .BR MS_SHARED .
 138 .TP
 139 .B ENOTDIR
 140 \fInew_root\fP or \fIput_old\fP is not a directory.
 141 .TP
 142 .B EPERM
 143 The calling process does not have the
 144 .B CAP_SYS_ADMIN
 145 capability.
 146 .SH VERSIONS
 147 .BR pivot_root ()
 148 was introduced in Linux 2.3.41.
 149 .SH CONFORMING TO
 150 .BR pivot_root ()
 151 is Linux-specific and hence is not portable.
 152 .SH NOTES
 153 Glibc does not provide a wrapper for this system call; call it using
 154 .BR syscall (2).
 155 .PP
 156 A command-line interface for this system call is provided by
 157 .BR pivot_root (8).
 158 .PP
 159 .BR pivot_root ()
 160 allows the caller to switch to a new root filesystem while at the same time
 161 placing the old root mount at a location under
 162 .I new_root
 163 from where it can subsequently be unmounted.
 164 (The fact that it moves all processes that have a root directory
 165 or current working directory on the old root directory to the
 166 new root frees the old root directory of users,
 167 allowing the old root mount to be unmounted more easily.)
 168 .PP
 169 One use of
 170 .BR pivot_root ()
 171 is during system startup, when the
 172 system mounts a temporary root filesystem (e.g., an
 173 .BR initrd (4)),
 174 then mounts the real root filesystem, and eventually turns the latter into
 175 the root directory of all relevant processes and threads.
 176 A modern use is to set up a root filesystem during
 177 the creation of a container.
 178 .PP
 179 The fact that
 180 .BR pivot_root ()
 181 modifies process root and current working directories in the
 182 manner noted in DESCRIPTION
 183 is necessary in order to prevent kernel threads from keeping the old
 184 root mount busy with their root and current working directories,
 185 even if they never access
 186 the filesystem in any way.
 187 .PP
 188 The rootfs (initial ramfs) cannot be
 189 .BR pivot_root ()ed.
 190 The recommended method of changing the root filesystem in this case is
 191 to delete everything in rootfs, overmount rootfs with the new root, attach
 192 .IR stdin / stdout / stderr
 193 to the new
 194 .IR /dev/console ,
 195 and exec the new
 196 .BR init (1).
 197 Helper programs for this process exist; see
 198 .BR switch_root (8).
 199 .\"
 200 .SS pivot_root(\(dq.\(dq, \(dq.\(dq)
 201 .PP
 202 .I new_root
 203 and
 204 .I put_old
 205 may be the same directory.
 206 In particular, the following sequence allows a pivot-root operation
 207 without needing to create and remove a temporary directory:
 208 .PP
 209 .in +4n
 210 .EX
 211 chdir(new_root);
 212 pivot_root(".", ".");
 213 umount2(".", MNT_DETACH);
 214 .EE
 215 .in
 216 .PP
 217 This sequence succeeds because the
 218 .BR pivot_root ()
 219 call stacks the old root mount point
 220 on top of the new root mount point at
 221 .IR / .
 222 At that point, the calling process's root directory and current
 223 working directory refer to the new root mount point
 224 .RI ( new_root ).
 225 During the subsequent
 226 .BR umount ()
 227 call, resolution of
 228 .IR """."""
 229 starts with
 230 .I new_root
 231 and then moves up the list of mounts stacked at
 232 .IR / ,
 233 with the result that old root mount point is unmounted.
 234 .\"
 235 .SS Historical notes
 236 For many years, this manual page carried the following text:
 237 .RS
 238 .PP
 239 .BR pivot_root ()
 240 may or may not change the current root and the current
 241 working directory of any processes or threads which use the old
 242 root directory.
 243 The caller of
 244 .BR pivot_root ()
 245 must ensure that processes with root or current working directory
 246 at the old root operate correctly in either case.
 247 An easy way to ensure this is to change their
 248 root and current working directory to \fInew_root\fP before invoking
 249 .BR pivot_root ().
 250 .RE
 251 .PP
 252 This text, written before the system call implementation was
 253 even finalized in the kernel, was probably intended to warn users
 254 at that time that the implementation might change before final release.
 255 However, the behavior stated in DESCRIPTION
 256 has remained consistent since this system call
 257 was first implemented and will not change now.
 258 .SH EXAMPLE
 259 .\" FIXME
 260 .\" Would it be better, because simpler, to use unshare(2)
 261 .\" rather than clone(2) in the example below?
 262 .PP
 263 The program below demonstrates the use of
 264 .BR pivot_root ()
 265 inside a mount namespace that is created using
 266 .BR clone (2).
 267 After pivoting to the root directory named in the program's
 268 first command-line argument, the child created by
 269 .BR clone (2)
 270 then executes the program named in the remaining command-line arguments.
 271 .PP
 272 We demonstrate the program by creating a directory that will serve as
 273 the new root filesystem and placing a copy of the (statically linked)
 274 .BR busybox (1)
 275 executable in that directory.
 276 .PP
 277 .in +4n
 278 .EX
 279 $ \fBmkdir /tmp/rootfs\fP
 280 $ \fBls \-id /tmp/rootfs\fP    # Show inode number of new root directory
 281 319459 /tmp/rootfs
 282 $ \fBcp $(which busybox) /tmp/rootfs\fP
 283 $ \fBPS1='bbsh$ ' sudo ./pivot_root_demo /tmp/rootfs /busybox sh\fP
 284 bbsh$ \fBPATH=/\fP
 285 bbsh$ \fBbusybox ln busybox ln\fP
 286 bbsh$ \fBln busybox echo\fP
 287 bbsh$ \fBln busybox ls\fP
 288 bbsh$ \fBls\fP
 289 busybox  echo     ln       ls
 290 bbsh$ \fBls \-id /\fP          # Compare with inode number above
 291 319459 /
 292 bbsh$ \fBecho \(aqhello world\(aq\fP
 293 hello world
 294 .EE
 295 .in
 296 .SS Program source
 297 \&
 298 .PP
 299 .EX
 300 /* pivot_root_demo.c */
 301
 302 #define _GNU_SOURCE
 303 #include <sched.h>
 304 #include <stdio.h>
 305 #include <stdlib.h>
 306 #include <unistd.h>
 307 #include <sys/wait.h>
 308 #include <sys/syscall.h>
 309 #include <sys/mount.h>
 310 #include <sys/stat.h>
 311 #include <limits.h>
 312
 313 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 314                         } while (0)
 315
 316 static int
 317 pivot_root(const char *new_root, const char *put_old)
 318 {
 319     return syscall(SYS_pivot_root, new_root, put_old);
 320 }
 321
 322 #define STACK_SIZE (1024 * 1024)
 323
 324 static int              /* Startup function for cloned child */
 325 child(void *arg)
 326 {
 327     char **args = arg;
 328     char *new_root = args[0];
 329     const char *put_old = "/oldrootfs";
 330     char path[PATH_MAX];
 331
 332     /* Ensure that \(aqnew_root\(aq and its parent mount don\(aqt have
 333        shared propagation (which would cause pivot_root() to
 334        return an error), and prevent propagation of mount
 335        events to the initial mount namespace */
 336
 337     if (mount(NULL, "/", NULL, MS_REC | MS_PRIVATE, NULL) == 1)
 338         errExit("mount\-MS_PRIVATE");
 339
 340     /* Ensure that \(aqnew_root\(aq is a mount point */
 341
 342     if (mount(new_root, new_root, NULL, MS_BIND, NULL) == \-1)
 343         errExit("mount\-MS_BIND");
 344
 345     /* Create directory to which old root will be pivoted */
 346
 347     snprintf(path, sizeof(path), "%s/%s", new_root, put_old);
 348     if (mkdir(path, 0777) == \-1)
 349         errExit("mkdir");
 350
 351     /* And pivot the root filesystem */
 352
 353     if (pivot_root(new_root, path) == \-1)
 354         errExit("pivot_root");
 355
 356     /* Switch the current working directory to "/" */
 357
 358     if (chdir("/") == \-1)
 359         errExit("chdir");
 360
 361     /* Unmount old root and remove mount point */
 362
 363     if (umount2(put_old, MNT_DETACH) == \-1)
 364         perror("umount2");
 365     if (rmdir(put_old) == \-1)
 366         perror("rmdir");
 367
 368     /* Execute the command specified in argv[1]... */
 369
 370     execv(args[1], &args[1]);
 371     errExit("execv");
 372 }
 373
 374 int
 375 main(int argc, char *argv[])
 376 {
 377     /* Create a child process in a new mount namespace */
 378
 379     char *stack = malloc(STACK_SIZE);
 380     if (stack == NULL)
 381         errExit("malloc");
 382
 383     if (clone(child, stack + STACK_SIZE,
 384                 CLONE_NEWNS | SIGCHLD, &argv[1]) == \-1)
 385         errExit("clone");
 386
 387     /* Parent falls through to here; wait for child */
 388
 389     if (wait(NULL) == \-1)
 390         errExit("wait");
 391
 392     exit(EXIT_SUCCESS);
 393 }
 394 .EE
 395 .SH SEE ALSO
 396 .BR chdir (2),
 397 .BR chroot (2),
 398 .BR mount (2),
 399 .BR stat (2),
 400 .BR initrd (4),
 401 .BR mount_namespaces (7),
 402 .BR pivot_root (8),
 403 .BR switch_root (8)