man2/pivot_root.2

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