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 mount
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 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
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 should 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
43 may or may not affect the calling process's current working directory.
44 It is therefore recommended to call
45 \fBchdir("/")\fP immediately after
48 The paragraph above is intentionally vague because at the time when
50 was first implemented, it was unclear whether its affect
51 on other process's root and current working directories\(emand
52 the caller's current working directory\(emmight change in the future.
53 However, the behavior has remained consistent since this system call
54 was first implemented:
56 changes the root directory and the current working directory
57 of each process or thread in the same mount namespace to
59 if they point to the old root directory.
63 does not change the caller's current working directory
64 (unless it is on the old root directory),
65 and thus it should be followed by a
66 \fBchdir("/")\fP call.
68 The following restrictions apply:
78 must not be on the same mount as the current root.
80 \fIput_old\fP must be at or underneath \fInew_root\fP;
81 that is, adding a nonnegative
82 number of \fI/..\fP to the string pointed to by \fIput_old\fP must yield
83 the same directory as \fInew_root\fP.
86 must be a path to a mount point, but can't be
88 A path that is not already a mount point can be converted into one by
89 bind mounting the path onto itself.
91 The propagation type of the parent mount of
93 and the parent mount of the current root directory must not be
97 is an existing mount point, its propagation type must not be
99 These restrictions ensure that
101 never propagates any changes to another mount namespace.
103 The current root directory must be a mount point.
105 On success, zero is returned.
106 On error, \-1 is returned, and
107 \fIerrno\fP is set appropriately.
110 may fail with any of the same errors as
112 Additionally, it may fail with the following errors:
115 .\" Reconfirmed that the following error occurs on Linux 5.0 by
116 .\" specifying 'new_root' as "/rootfs" and 'put_old' as
117 .\" "/rootfs/oldrootfs", and *not* bind mounting "/rootfs" on top of
118 .\" itself. Of course, this is an odd situation, since a later check
119 .\" in the kernel code will in any case yield EINVAL if 'new_root' is
120 .\" not a mount point. However, when the system call was first added,
121 .\" 'new_root' was not required to be a mount point. So, this
122 .\" error is nowadays probably just the result of crufty accumulation.
123 .\" This error can also occur if we bind mount "/" on top of itself
124 .\" and try to specify "/" as the 'new' (again, an odd situation). So,
125 .\" the EBUSY check in the kernel does still seem necessary to prevent
126 .\" that case. Furthermore, the "or put_old" piece is probably
127 .\" redundant text (although the check is in the kernel), since,
128 .\" in another check, 'put_old' is required to be under 'new_root'.
132 is on the current root filesystem.
133 (This error covers the pathological case where
140 is not a mount point.
143 \fIput_old\fP is not underneath \fInew_root\fP.
146 The current root directory is not a mount point
147 (because of an earlier
151 The current root is on the rootfs (initial ramfs) filesystem; see NOTES.
154 Either the mount point at
156 or the parent mount of that mount point,
162 is a mount point and has the propagation type
166 \fInew_root\fP or \fIput_old\fP is not a directory.
169 The calling process does not have the
174 was introduced in Linux 2.3.41.
177 is Linux-specific and hence is not portable.
179 Glibc does not provide a wrapper for this system call; call it using
182 A command-line interface for this system call is provided by
186 allows the caller to switch to a new root filesystem while at the same time
187 placing the old root mount at a location under
189 from where it can subsequently be unmounted.
190 (The fact that it moves all processes that have a root directory
191 or current working directory on the old root directory to the
192 new root frees the old root directory of users,
193 allowing the old root mount to be unmounted more easily.)
197 is during system startup, when the
198 system mounts a temporary root filesystem (e.g., an \fBinitrd\fP), then
199 mounts the real root filesystem, and eventually turns the latter into
200 the current root of all relevant processes or threads.
201 A modern use is to set up a root filesystem during
202 the creation of a container.
206 modifies process root and current working directories in the
207 manner noted in DESCRIPTION
208 is necessary in order to prevent kernel threads from keeping the old
209 root directory busy with their root and current working directory,
210 even if they never access
211 the filesystem in any way.
213 The rootfs (initial ramfs) cannot be
215 The recommended method of changing the root filesystem in this case is
216 to delete everything in rootfs, overmount rootfs with the new root, attach
217 .IR stdin / stdout / stderr
222 Helper programs for this process exist; see
228 may be the same directory.
229 In particular, the following sequence allows a pivot-root operation
230 without needing to create and remove a temporary directory:
235 pivot_root(".", ".");
236 umount2(".", MNT_DETACH);
240 This sequence succeeds because the
242 call stacks the old root mount point
243 on top of the new root mount point at
245 At that point, the calling process's root directory and current
246 working directory refer to the new root mount point
248 During the subsequent
254 and then moves up the list of mounts stacked at
256 with the result that old root mount point is unmounted.
259 .\" Would it be better, because simpler, to use unshare(2)
260 .\" rather than clone(2) in the example below?
262 The program below demonstrates the use of
264 inside a mount namespace that is created using
266 After pivoting to the root directory named in the program's
267 first command-line argument, the child created by
269 then executes the program named in the remaining command-line arguments.
271 We demonstrate the program by creating a directory that will serve as
272 the new root filesystem and placing a copy of the (statically linked)
274 executable in that directory.
278 $ \fBmkdir /tmp/rootfs\fP
279 $ \fBls \-id /tmp/rootfs\fP # Show inode number of new root directory
281 $ \fBcp $(which busybox) /tmp/rootfs\fP
282 $ \fBPS1='bbsh$ ' sudo ./pivot_root_demo /tmp/rootfs /busybox sh\fP
284 bbsh$ \fBbusybox ln busybox ln\fP
285 bbsh$ \fBln busybox echo\fP
286 bbsh$ \fBln busybox ls\fP
289 bbsh$ \fBls \-id /\fP # Compare with inode number above
291 bbsh$ \fBecho \(aqhello world\(aq\fP
299 /* pivot_root_demo.c */
306 #include <sys/wait.h>
307 #include <sys/syscall.h>
308 #include <sys/mount.h>
309 #include <sys/stat.h>
312 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
316 pivot_root(const char *new_root, const char *put_old)
318 return syscall(SYS_pivot_root, new_root, put_old);
321 #define STACK_SIZE (1024 * 1024)
323 static int /* Startup function for cloned child */
327 char *new_root = args[0];
328 const char *put_old = "/oldrootfs";
331 /* Ensure that \(aqnew_root\(aq and its parent mount don\(aqt have
332 shared propagation (which would cause pivot_root() to
333 return an error), and prevent propagation of mount
334 events to the initial mount namespace */
336 if (mount(NULL, "/", NULL, MS_REC | MS_PRIVATE, NULL) == 1)
337 errExit("mount\-MS_PRIVATE");
339 /* Ensure that \(aqnew_root\(aq is a mount point */
341 if (mount(new_root, new_root, NULL, MS_BIND, NULL) == \-1)
342 errExit("mount\-MS_BIND");
344 /* Create directory to which old root will be pivoted */
346 snprintf(path, sizeof(path), "%s/%s", new_root, put_old);
347 if (mkdir(path, 0777) == \-1)
350 /* And pivot the root filesystem */
352 if (pivot_root(new_root, path) == \-1)
353 errExit("pivot_root");
355 /* Switch the current working directory to "/" */
357 if (chdir("/") == \-1)
360 /* Unmount old root and remove mount point */
362 if (umount2(put_old, MNT_DETACH) == \-1)
364 if (rmdir(put_old) == \-1)
367 /* Execute the command specified in argv[1]... */
369 execv(args[1], &args[1]);
374 main(int argc, char *argv[])
376 /* Create a child process in a new mount namespace */
378 char *stack = malloc(STACK_SIZE);
382 if (clone(child, stack + STACK_SIZE,
383 CLONE_NEWNS | SIGCHLD, &argv[1]) == \-1)
386 /* Parent falls through to here; wait for child */
388 if (wait(NULL) == \-1)
400 .BR mount_namespaces (7),