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,
119 or a filesystem is already mounted on \fIput_old\fP.
123 is not a mount point.
126 \fIput_old\fP is not underneath \fInew_root\fP.
129 The current root is on the rootfs (initial ramfs) filesystem; see NOTES.
132 Either the mount point at
134 or the parent mount of that mount point,
140 is a mount point and has the propagation type
144 \fInew_root\fP or \fIput_old\fP is not a directory.
147 The calling process does not have the
152 was introduced in Linux 2.3.41.
155 is Linux-specific and hence is not portable.
157 Glibc does not provide a wrapper for this system call; call it using
161 allows the caller to switch to a new root filesystem while at the same time
162 placing the old root mount at a location under
164 from where it can subsequently be unmounted.
165 (The fact that it moves all processes that have a root directory
166 or current working directory on the old root filesystem to the
167 new root filesystem frees the old root filesystem of users,
168 allowing it to be unmounted more easily.)
171 is during system startup, when the
172 system mounts a temporary root filesystem (e.g., an \fBinitrd\fP), then
173 mounts the real root filesystem, and eventually turns the latter into
174 the current root of all relevant processes or threads.
175 A modern use is to set up a root filesystem during
176 the creation of a container.
178 The rootfs (initial ramfs) cannot be
180 The recommended method of changing the root filesystem in this case is
181 to delete everything in rootfs, overmount rootfs with the new root, attach
182 .IR stdin / stdout / stderr
187 Helper programs for this process exist; see
191 should not have to change root and current working directory of other
192 processes in the system.
194 Some of the more obscure uses of
200 The program below demonstrates the use of
202 inside a mount namespace that is created using
204 After pivoting to the root directory named in the program's
205 first command-line argument, the child created by
207 then executes the program named in the remaining command-line arguments.
209 We demonstrate the program by creating a directory that will serve as
210 the new root filesystem and placing a copy of the (statically linked)
212 executable in that directory.
216 $ \fBmkdir /tmp/rootfs\fP
217 $ \fBls \-id /tmp/rootfs\fP # Show inode number of new root directory
219 $ \fBcp $(which busybox) /tmp/rootfs\fP
220 $ \fBPS1='bbsh$ ' sudo ./pivot_root_demo /tmp/rootfs /busybox sh\fP
222 bbsh$ \fBbusybox ln busybox ln\fP
223 bbsh$ \fBln busybox echo\fP
224 bbsh$ \fBln busybox ls\fP
227 bbsh$ \fBls \-id /\fP # Compare with inode number above
229 bbsh$ \fBecho \(aqhello world\(aq\fP
237 /* pivot_root_demo.c */
244 #include <sys/wait.h>
245 #include <sys/syscall.h>
246 #include <sys/mount.h>
247 #include <sys/stat.h>
250 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
254 pivot_root(const char *new_root, const char *put_old)
256 return syscall(SYS_pivot_root, new_root, put_old);
259 #define STACK_SIZE (1024 * 1024)
261 static int /* Startup function for cloned child */
265 char *new_root = args[0];
266 const char *put_old = "/oldrootfs";
269 /* Ensure that \(aqnew_root\(aq and its parent mount don\(aqt have
270 shared propagation (which would cause pivot_root() to
271 return an error), and prevent propagation of mount
272 events to the initial mount namespace */
274 if (mount(NULL, "/", NULL, MS_REC | MS_PRIVATE, NULL) == 1)
275 errExit("mount\-MS_PRIVATE");
277 /* Ensure that \(aqnew_root\(aq is a mount point */
279 if (mount(new_root, new_root, NULL, MS_BIND, NULL) == \-1)
280 errExit("mount\-MS_BIND");
282 /* Create directory to which old root will be pivoted */
284 snprintf(path, sizeof(path), "%s/%s", new_root, put_old);
285 if (mkdir(path, 0777) == \-1)
288 /* And pivot the root filesystem */
290 if (pivot_root(new_root, path) == \-1)
291 errExit("pivot_root");
293 /* Switch the current working working directory to "/" */
295 if (chdir("/") == \-1)
298 /* Unmount old root and remove mount point */
300 if (umount2(put_old, MNT_DETACH) == \-1)
302 if (rmdir(put_old) == \-1)
305 /* Execute the command specified in argv[1]... */
307 execv(args[1], &args[1]);
312 main(int argc, char *argv[])
314 /* Create a child process in a new mount namespace */
316 char *stack = malloc(STACK_SIZE);
320 if (clone(child, stack + STACK_SIZE,
321 CLONE_NEWNS | SIGCHLD, &argv[1]) == \-1)
324 /* Parent falls through to here; wait for child */
326 if (wait(NULL) == \-1)
338 .BR mount_namespaces (7),