1 .\" Copyright (C) 2000 by Werner Almesberger
2 .\" and Copyright (C) 2019 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
5 .\" May be distributed under GPL
8 .\" Written 2000-02-23 by Werner Almesberger
9 .\" Modified 2004-06-17 Michael Kerrisk <mtk.manpages@gmail.com>
11 .TH PIVOT_ROOT 2 2019-08-02 "Linux" "Linux Programmer's Manual"
13 pivot_root \- change the root filesystem
15 .BI "int pivot_root(const char *" new_root ", const char *" put_old );
18 There is no glibc wrapper for this system call; see NOTES.
21 changes the root filesystem in the mount namespace of the calling process.
22 More precisely, it moves the root filesystem to the
23 directory \fIput_old\fP and makes \fInew_root\fP the new root filesystem.
24 The calling process must have the
26 capability in the user namespace that owns the caller's mount namespace.
29 may or may not change the current root and the current
30 working directory of any processes or threads that
31 use the old root directory and which are in
32 the same mount namespace as the caller of
36 must ensure that processes with root or current working directory
37 at the old root operate correctly in either case.
38 An easy way to ensure this is to change their
39 root and current working directory to \fInew_root\fP before invoking
42 The paragraph above is intentionally vague because the implementation of
44 may change in the future
45 (or so it was thought when this system call was first added).
47 the behavior on this point has remained consistent since
49 was first implemented:
51 changes the root directory and the current working directory
52 of each process or thread in the same mount namespace to
54 if they point to the old root directory.
55 This is necessary in order to prevent kernel threads from keeping the old
56 root directory busy with their root and current working directory,
57 even if they never access
58 the filesystem in any way.
59 Perhaps one day there may be a mechanism for
60 kernel threads to explicitly relinquish any access to the filesystem,
61 such that this fairly intrusive mechanism can be removed from
64 Note that this also applies to the calling process:
66 may or may not affect its current working directory.
67 It is therefore recommended to call
68 \fBchdir("/")\fP immediately after
71 The following restrictions apply to \fInew_root\fP and \fIput_old\fP:
73 They must be directories.
75 \fInew_root\fP and \fIput_old\fP must not be on the same filesystem as
78 \fIput_old\fP must be underneath \fInew_root\fP, that is, adding a nonzero
79 number of \fI/..\fP to the string pointed to by \fIput_old\fP must yield
80 the same directory as \fInew_root\fP.
83 must be a mount point.
84 (If it is not otherwise a mount point, it suffices to bind mount
88 The propagation type of
90 and its parent mount must not be
94 is an existing mount point, its propagation type must not be
99 for additional usage examples.
101 If the current root is not a mount point (e.g., after an earlier
105 then the mount point of the filesystem containing the current root directory
106 (i.e., not the directory itself) is mounted on \fIput_old\fP.
108 On success, zero is returned.
109 On error, \-1 is returned, and
110 \fIerrno\fP is set appropriately.
113 may fail with any of the same errors as
115 Additionally, it may fail with the following errors:
118 \fInew_root\fP or \fIput_old\fP are on the current root filesystem.
122 is not a mount point.
125 \fIput_old\fP is not underneath \fInew_root\fP.
128 The current root is on the rootfs (initial ramfs) filesystem; see NOTES.
131 Either the mount point at
133 or the parent mount of that mount point,
139 is a mount point and has the propagation type
143 \fInew_root\fP or \fIput_old\fP is not a directory.
146 The calling process does not have the
151 was introduced in Linux 2.3.41.
154 is Linux-specific and hence is not portable.
156 Glibc does not provide a wrapper for this system call; call it using
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
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 filesystem to the
166 new root filesystem frees the old root filesystem of users,
167 allowing it to be unmounted more easily.)
170 is during system startup, when the
171 system mounts a temporary root filesystem (e.g., an \fBinitrd\fP), then
172 mounts the real root filesystem, and eventually turns the latter into
173 the current root of all relevant processes or threads.
174 A modern use is to set up a root filesystem during
175 the creation of a container.
177 The rootfs (initial ramfs) cannot be
179 The recommended method of changing the root filesystem in this case is
180 to delete everything in rootfs, overmount rootfs with the new root, attach
181 .IR stdin / stdout / stderr
186 Helper programs for this process exist; see
190 should not have to change root and current working directory of other
191 processes in the system.
193 Some of the more obscure uses of
199 The program below demonstrates the use of
201 inside a mount namespace that is created using
203 After pivoting to the root directory named in the program's
204 first command-line argument, the child created by
206 then executes the program named in the remaining command-line arguments.
208 We demonstrate the program by creating a directory that will serve as
209 the new root filesystem and placing a copy of the (statically linked)
211 executable in that directory.
215 $ \fBmkdir /tmp/rootfs\fP
216 $ \fBls \-id /tmp/rootfs\fP # Show inode number of new root directory
218 $ \fBcp $(which busybox) /tmp/rootfs\fP
219 $ \fBPS1='bbsh$ ' sudo ./pivot_root_demo /tmp/rootfs /busybox sh\fP
221 bbsh$ \fBbusybox ln busybox ln\fP
222 bbsh$ \fBln busybox echo\fP
223 bbsh$ \fBln busybox ls\fP
226 bbsh$ \fBls \-id /\fP # Compare with inode number above
228 bbsh$ \fBecho \(aqhello world\(aq\fP
236 /* pivot_root_demo.c */
243 #include <sys/wait.h>
244 #include <sys/syscall.h>
245 #include <sys/mount.h>
246 #include <sys/stat.h>
249 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
253 pivot_root(const char *new_root, const char *put_old)
255 return syscall(SYS_pivot_root, new_root, put_old);
258 #define STACK_SIZE (1024 * 1024)
260 static int /* Startup function for cloned child */
264 char *new_root = args[0];
265 const char *put_old = "/oldrootfs";
268 /* Ensure that \(aqnew_root\(aq and its parent mount don\(aqt have
269 shared propagation (which would cause pivot_root() to
270 return an error), and prevent propagation of mount
271 events to the initial mount namespace */
273 if (mount(NULL, "/", NULL, MS_REC | MS_PRIVATE, NULL) == 1)
274 errExit("mount\-MS_PRIVATE");
276 /* Ensure that \(aqnew_root\(aq is a mount point */
278 if (mount(new_root, new_root, NULL, MS_BIND, NULL) == \-1)
279 errExit("mount\-MS_BIND");
281 /* Create directory to which old root will be pivoted */
283 snprintf(path, sizeof(path), "%s/%s", new_root, put_old);
284 if (mkdir(path, 0777) == \-1)
287 /* And pivot the root filesystem */
289 if (pivot_root(new_root, path) == \-1)
290 errExit("pivot_root");
292 /* Switch the current working working directory to "/" */
294 if (chdir("/") == \-1)
297 /* Unmount old root and remove mount point */
299 if (umount2(put_old, MNT_DETACH) == \-1)
301 if (rmdir(put_old) == \-1)
304 /* Execute the command specified in argv[1]... */
306 execv(args[1], &args[1]);
311 main(int argc, char *argv[])
313 /* Create a child process in a new mount namespace */
315 char *stack = malloc(STACK_SIZE);
319 if (clone(child, stack + STACK_SIZE,
320 CLONE_NEWNS | SIGCHLD, &argv[1]) == \-1)
323 /* Parent falls through to here; wait for child */
325 if (wait(NULL) == \-1)
337 .BR mount_namespaces (7),