Debian Codegraph @

upstream/debian-unstable/man2/pivot_root.2

raw
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)