| 1 |
.\" Copyright 2019, Michael Kerrisk <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH pivot_root 2 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
pivot_root \- change the root mount |
| 9 |
.SH LIBRARY |
| 10 |
Standard C library |
| 11 |
.RI ( libc ,\~ \-lc ) |
| 12 |
.SH SYNOPSIS |
| 13 |
.nf |
| 14 |
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */" |
| 15 |
.B #include <unistd.h> |
| 16 |
.P |
| 17 |
.BI "int syscall(SYS_pivot_root, const char *" new_root \ |
| 18 |
", const char *" put_old ); |
| 19 |
.fi |
| 20 |
.P |
| 21 |
.IR Note : |
| 22 |
glibc provides no wrapper for |
| 23 |
.BR pivot_root (), |
| 24 |
necessitating the use of |
| 25 |
.BR syscall (2). |
| 26 |
.SH DESCRIPTION |
| 27 |
.BR pivot_root () |
| 28 |
changes the root mount in the mount namespace of the calling process. |
| 29 |
More precisely, it moves the root mount to the |
| 30 |
directory |
| 31 |
.I put_old |
| 32 |
and makes |
| 33 |
.I new_root |
| 34 |
the new root mount. |
| 35 |
The calling process must have the |
| 36 |
.B CAP_SYS_ADMIN |
| 37 |
capability in the user namespace that owns the caller's mount namespace. |
| 38 |
.P |
| 39 |
.BR pivot_root () |
| 40 |
changes the root directory and the current working directory |
| 41 |
of each process or thread in the same mount namespace to |
| 42 |
.I new_root |
| 43 |
if they point to the old root directory. |
| 44 |
(See also NOTES.) |
| 45 |
On the other hand, |
| 46 |
.BR pivot_root () |
| 47 |
does not change the caller's current working directory |
| 48 |
(unless it is on the old root directory), |
| 49 |
and thus it should be followed by a |
| 50 |
.I chdir("/") |
| 51 |
call. |
| 52 |
.P |
| 53 |
The following restrictions apply: |
| 54 |
.IP \[bu] 3 |
| 55 |
.I new_root |
| 56 |
and |
| 57 |
.I put_old |
| 58 |
must be directories. |
| 59 |
.IP \[bu] |
| 60 |
.I new_root |
| 61 |
and |
| 62 |
.I put_old |
| 63 |
must not be on the same mount as the current root. |
| 64 |
.IP \[bu] |
| 65 |
.I put_old |
| 66 |
must be at or underneath |
| 67 |
.IR new_root ; |
| 68 |
that is, |
| 69 |
adding some nonnegative number of |
| 70 |
.RI \[dq] /..\& \[dq] |
| 71 |
suffixes to the pathname pointed to by |
| 72 |
.I put_old |
| 73 |
must yield the same directory as |
| 74 |
.IR new_root . |
| 75 |
.IP \[bu] |
| 76 |
.I new_root |
| 77 |
must be a path to a mount point, but can't be |
| 78 |
.IR \[dq]/\[dq] . |
| 79 |
A path that is not already a mount point can be converted into one by |
| 80 |
bind mounting the path onto itself. |
| 81 |
.IP \[bu] |
| 82 |
The propagation type of the parent mount of |
| 83 |
.I new_root |
| 84 |
and the parent mount of the current root directory must not be |
| 85 |
.BR MS_SHARED ; |
| 86 |
similarly, if |
| 87 |
.I put_old |
| 88 |
is an existing mount point, its propagation type must not be |
| 89 |
.BR MS_SHARED . |
| 90 |
These restrictions ensure that |
| 91 |
.BR pivot_root () |
| 92 |
never propagates any changes to another mount namespace. |
| 93 |
.IP \[bu] |
| 94 |
The current root directory must be a mount point. |
| 95 |
.SH RETURN VALUE |
| 96 |
On success, zero is returned. |
| 97 |
On error, \-1 is returned, and |
| 98 |
.I errno |
| 99 |
is set to indicate the error. |
| 100 |
.SH ERRORS |
| 101 |
.BR pivot_root () |
| 102 |
may fail with any of the same errors as |
| 103 |
.BR stat (2). |
| 104 |
Additionally, it may fail with the following errors: |
| 105 |
.TP |
| 106 |
.B EBUSY |
| 107 |
.\" Reconfirmed that the following error occurs on Linux 5.0 by |
| 108 |
.\" specifying 'new_root' as "/rootfs" and 'put_old' as |
| 109 |
.\" "/rootfs/oldrootfs", and *not* bind mounting "/rootfs" on top of |
| 110 |
.\" itself. Of course, this is an odd situation, since a later check |
| 111 |
.\" in the kernel code will in any case yield EINVAL if 'new_root' is |
| 112 |
.\" not a mount point. However, when the system call was first added, |
| 113 |
.\" 'new_root' was not required to be a mount point. So, this |
| 114 |
.\" error is nowadays probably just the result of crufty accumulation. |
| 115 |
.\" This error can also occur if we bind mount "/" on top of itself |
| 116 |
.\" and try to specify "/" as the 'new' (again, an odd situation). So, |
| 117 |
.\" the EBUSY check in the kernel does still seem necessary to prevent |
| 118 |
.\" that case. Furthermore, the "or put_old" piece is probably |
| 119 |
.\" redundant text (although the check is in the kernel), since, |
| 120 |
.\" in another check, 'put_old' is required to be under 'new_root'. |
| 121 |
.I new_root |
| 122 |
or |
| 123 |
.I put_old |
| 124 |
is on the current root mount. |
| 125 |
(This error covers the pathological case where |
| 126 |
.I new_root |
| 127 |
is |
| 128 |
.IR \[dq]/\[dq] .) |
| 129 |
.TP |
| 130 |
.B EINVAL |
| 131 |
.I new_root |
| 132 |
is not a mount point. |
| 133 |
.TP |
| 134 |
.B EINVAL |
| 135 |
.I put_old |
| 136 |
is not at or underneath |
| 137 |
.IR new_root . |
| 138 |
.TP |
| 139 |
.B EINVAL |
| 140 |
The current root directory is not a mount point |
| 141 |
(because of an earlier |
| 142 |
.BR chroot (2)). |
| 143 |
.TP |
| 144 |
.B EINVAL |
| 145 |
The current root is on the rootfs (initial ramfs) mount; |
| 146 |
see NOTES. |
| 147 |
.TP |
| 148 |
.B EINVAL |
| 149 |
Either the mount point at |
| 150 |
.IR new_root , |
| 151 |
or the parent mount of that mount point, |
| 152 |
has propagation type |
| 153 |
.BR MS_SHARED . |
| 154 |
.TP |
| 155 |
.B EINVAL |
| 156 |
.I put_old |
| 157 |
is a mount point and has the propagation type |
| 158 |
.BR MS_SHARED . |
| 159 |
.TP |
| 160 |
.B ENOTDIR |
| 161 |
.I new_root |
| 162 |
or |
| 163 |
.I put_old |
| 164 |
is not a directory. |
| 165 |
.TP |
| 166 |
.B EPERM |
| 167 |
The calling process does not have the |
| 168 |
.B CAP_SYS_ADMIN |
| 169 |
capability. |
| 170 |
.SH STANDARDS |
| 171 |
Linux. |
| 172 |
.SH HISTORY |
| 173 |
Linux 2.3.41. |
| 174 |
.SH NOTES |
| 175 |
A command-line interface for this system call is provided by |
| 176 |
.BR pivot_root (8). |
| 177 |
.P |
| 178 |
.BR pivot_root () |
| 179 |
allows the caller to switch to a new root filesystem while at the same time |
| 180 |
placing the old root mount at a location under |
| 181 |
.I new_root |
| 182 |
from where it can subsequently be unmounted. |
| 183 |
(The fact that it moves all processes that have a root directory |
| 184 |
or current working directory on the old root directory to the |
| 185 |
new root frees the old root directory of users, |
| 186 |
allowing the old root mount to be unmounted more easily.) |
| 187 |
.P |
| 188 |
One use of |
| 189 |
.BR pivot_root () |
| 190 |
is during system startup, when the |
| 191 |
system mounts a temporary root filesystem (e.g., an |
| 192 |
.BR initrd (4)), |
| 193 |
then mounts the real root filesystem, and eventually turns the latter into |
| 194 |
the root directory of all relevant processes and threads. |
| 195 |
A modern use is to set up a root filesystem during |
| 196 |
the creation of a container. |
| 197 |
.P |
| 198 |
The fact that |
| 199 |
.BR pivot_root () |
| 200 |
modifies process root and current working directories in the |
| 201 |
manner noted in DESCRIPTION |
| 202 |
is necessary in order to prevent kernel threads from keeping the old |
| 203 |
root mount busy with their root and current working directories, |
| 204 |
even if they never access |
| 205 |
the filesystem in any way. |
| 206 |
.P |
| 207 |
The rootfs (initial ramfs) cannot be |
| 208 |
.BR pivot_root ()ed. |
| 209 |
The recommended method of changing the root filesystem in this case is |
| 210 |
to delete everything in rootfs, overmount rootfs with the new root, attach |
| 211 |
.IR stdin / stdout / stderr |
| 212 |
to the new |
| 213 |
.IR /dev/console , |
| 214 |
and exec the new |
| 215 |
.BR init (1). |
| 216 |
Helper programs for this process exist; |
| 217 |
see |
| 218 |
.BR switch_root (8). |
| 219 |
.\" |
| 220 |
.SS pivot_root(\[dq].\[dq], \[dq].\[dq]) |
| 221 |
.I new_root |
| 222 |
and |
| 223 |
.I put_old |
| 224 |
may be the same directory. |
| 225 |
In particular, the following sequence allows a pivot-root operation |
| 226 |
without needing to create and remove a temporary directory: |
| 227 |
.P |
| 228 |
.in +4n |
| 229 |
.EX |
| 230 |
chdir(new_root); |
| 231 |
pivot_root(".", "."); |
| 232 |
umount2(".", MNT_DETACH); |
| 233 |
.EE |
| 234 |
.in |
| 235 |
.P |
| 236 |
This sequence succeeds because the |
| 237 |
.BR pivot_root () |
| 238 |
call stacks the old root mount point |
| 239 |
on top of the new root mount point at |
| 240 |
.IR / . |
| 241 |
At that point, the calling process's root directory and current |
| 242 |
working directory refer to the new root mount point |
| 243 |
.RI ( new_root ). |
| 244 |
During the subsequent |
| 245 |
.BR umount () |
| 246 |
call, resolution of |
| 247 |
.I \[dq].\[dq] |
| 248 |
starts with |
| 249 |
.I new_root |
| 250 |
and then moves up the list of mounts stacked at |
| 251 |
.IR / , |
| 252 |
with the result that old root mount point is unmounted. |
| 253 |
.\" |
| 254 |
.SS Historical notes |
| 255 |
For many years, this manual page carried the following text: |
| 256 |
.RS |
| 257 |
.P |
| 258 |
.BR pivot_root () |
| 259 |
may or may not change the current root and the current |
| 260 |
working directory of any processes or threads which use the old |
| 261 |
root directory. |
| 262 |
The caller of |
| 263 |
.BR pivot_root () |
| 264 |
must ensure that processes with root or current working directory |
| 265 |
at the old root operate correctly in either case. |
| 266 |
An easy way to ensure this is to change their |
| 267 |
root and current working directory to |
| 268 |
.I new_root |
| 269 |
before invoking |
| 270 |
.BR pivot_root (). |
| 271 |
.RE |
| 272 |
.P |
| 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 |
.P |
| 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 |
.P |
| 297 |
.in +4n |
| 298 |
.EX |
| 299 |
.RB $ " mkdir /tmp/rootfs" ; |
| 300 |
.RB $ " ls \-id /tmp/rootfs" "; # Show inode number of new root directory" |
| 301 |
319459 /tmp/rootfs |
| 302 |
.RB $ " cp $(which busybox) /tmp/rootfs" ; |
| 303 |
.RB $ " PS1=\[aq]bbsh$ \[aq] sudo ./pivot_root_demo /tmp/rootfs /busybox sh" ; |
| 304 |
.RB bbsh$ " PATH=/" ; |
| 305 |
.RB bbsh$ " busybox ln busybox ln" ; |
| 306 |
.RB bbsh$ " ln busybox echo" ; |
| 307 |
.RB bbsh$ " ln busybox ls" ; |
| 308 |
.RB bbsh$ " ls" ; |
| 309 |
busybox echo ln ls |
| 310 |
.RB bbsh$ " ls \-id /" "; # Compare with inode number above" |
| 311 |
319459 / |
| 312 |
.RB bbsh$ " echo \[aq]hello world\[aq]" ; |
| 313 |
hello world |
| 314 |
.EE |
| 315 |
.in |
| 316 |
.SS Program source |
| 317 |
\& |
| 318 |
.P |
| 319 |
.\" SRC BEGIN (pivot_root.c) |
| 320 |
.EX |
| 321 |
/* pivot_root_demo.c */ |
| 322 |
\& |
| 323 |
#define _GNU_SOURCE |
| 324 |
#include <err.h> |
| 325 |
#include <limits.h> |
| 326 |
#include <sched.h> |
| 327 |
#include <signal.h> |
| 328 |
#include <stdio.h> |
| 329 |
#include <stdlib.h> |
| 330 |
#include <sys/mman.h> |
| 331 |
#include <sys/mount.h> |
| 332 |
#include <sys/stat.h> |
| 333 |
#include <sys/syscall.h> |
| 334 |
#include <sys/wait.h> |
| 335 |
#include <unistd.h> |
| 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 path[PATH_MAX]; |
| 349 |
char **args = arg; |
| 350 |
char *new_root = args[0]; |
| 351 |
const char *put_old = "/oldrootfs"; |
| 352 |
\& |
| 353 |
/* Ensure that \[aq]new_root\[aq] and its parent mount don\[aq]t 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 |
err(EXIT_FAILURE, "mount\-MS_PRIVATE"); |
| 360 |
\& |
| 361 |
/* Ensure that \[aq]new_root\[aq] is a mount point. */ |
| 362 |
\& |
| 363 |
if (mount(new_root, new_root, NULL, MS_BIND, NULL) == \-1) |
| 364 |
err(EXIT_FAILURE, "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 |
err(EXIT_FAILURE, "mkdir"); |
| 371 |
\& |
| 372 |
/* And pivot the root filesystem. */ |
| 373 |
\& |
| 374 |
if (pivot_root(new_root, path) == \-1) |
| 375 |
err(EXIT_FAILURE, "pivot_root"); |
| 376 |
\& |
| 377 |
/* Switch the current working directory to "/". */ |
| 378 |
\& |
| 379 |
if (chdir("/") == \-1) |
| 380 |
err(EXIT_FAILURE, "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 |
err(EXIT_FAILURE, "execv"); |
| 393 |
} |
| 394 |
\& |
| 395 |
int |
| 396 |
main(int argc, char *argv[]) |
| 397 |
{ |
| 398 |
char *stack; |
| 399 |
\& |
| 400 |
/* Create a child process in a new mount namespace. */ |
| 401 |
\& |
| 402 |
stack = mmap(NULL, STACK_SIZE, PROT_READ | PROT_WRITE, |
| 403 |
MAP_PRIVATE | MAP_ANONYMOUS | MAP_STACK, \-1, 0); |
| 404 |
if (stack == MAP_FAILED) |
| 405 |
err(EXIT_FAILURE, "mmap"); |
| 406 |
\& |
| 407 |
if (clone(child, stack + STACK_SIZE, |
| 408 |
CLONE_NEWNS | SIGCHLD, &argv[1]) == \-1) |
| 409 |
err(EXIT_FAILURE, "clone"); |
| 410 |
\& |
| 411 |
/* Parent falls through to here; wait for child. */ |
| 412 |
\& |
| 413 |
if (wait(NULL) == \-1) |
| 414 |
err(EXIT_FAILURE, "wait"); |
| 415 |
\& |
| 416 |
exit(EXIT_SUCCESS); |
| 417 |
} |
| 418 |
.EE |
| 419 |
.\" SRC END |
| 420 |
.SH SEE ALSO |
| 421 |
.BR chdir (2), |
| 422 |
.BR chroot (2), |
| 423 |
.BR mount (2), |
| 424 |
.BR stat (2), |
| 425 |
.BR initrd (4), |
| 426 |
.BR mount_namespaces (7), |
| 427 |
.BR pivot_root (8), |
| 428 |
.BR switch_root (8) |