]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C) 2000 by Werner Almesberger |
2297bf0e | 2 | .\" |
b55e2bb3 | 3 | .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE) |
fea681da | 4 | .\" May be distributed under GPL |
b55e2bb3 | 5 | .\" %%%LICENSE_END |
fea681da MK |
6 | .\" |
7 | .\" Written 2000-02-23 by Werner Almesberger | |
c11b1abf | 8 | .\" Modified 2004-06-17 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 9 | .\" |
63121bd4 | 10 | .TH PIVOT_ROOT 2 2019-08-02 "Linux" "Linux Programmer's Manual" |
fea681da | 11 | .SH NAME |
9ee4a2b6 | 12 | pivot_root \- change the root filesystem |
fea681da | 13 | .SH SYNOPSIS |
fea681da | 14 | .BI "int pivot_root(const char *" new_root ", const char *" put_old ); |
dbfe9c70 | 15 | .PP |
45c99e3e MK |
16 | .IR Note : |
17 | There is no glibc wrapper for this system call; see NOTES. | |
fea681da | 18 | .SH DESCRIPTION |
60a90ecd | 19 | .BR pivot_root () |
7cc1a16d MK |
20 | changes the root filesystem in the mount namespace of the calling process. |
21 | More precisely, it moves the root filesystem to the | |
22 | directory \fIput_old\fP and makes \fInew_root\fP the new root filesystem. | |
fdc558bd MK |
23 | The calling process must have the |
24 | .B CAP_SYS_ADMIN | |
25 | capability in the user namespace that owns the caller's mount namespace. | |
efeece04 | 26 | .PP |
60a90ecd MK |
27 | The typical use of |
28 | .BR pivot_root () | |
29 | is during system startup, when the | |
9ee4a2b6 MK |
30 | system mounts a temporary root filesystem (e.g., an \fBinitrd\fP), then |
31 | mounts the real root filesystem, and eventually turns the latter into | |
fea681da | 32 | the current root of all relevant processes or threads. |
efeece04 | 33 | .PP |
60a90ecd MK |
34 | .BR pivot_root () |
35 | may or may not change the current root and the current | |
ac2eb791 MK |
36 | working directory of any processes or threads that |
37 | use the old root directory and which are in | |
38 | the same mount namespace as the caller of | |
39 | .BR pivot_root (). | |
60a90ecd MK |
40 | The caller of |
41 | .BR pivot_root () | |
edd1fa35 MK |
42 | must ensure that processes with root or current working directory |
43 | at the old root operate correctly in either case. | |
c13182ef | 44 | An easy way to ensure this is to change their |
edd1fa35 | 45 | root and current working directory to \fInew_root\fP before invoking |
60a90ecd | 46 | .BR pivot_root (). |
efeece04 | 47 | .PP |
c33144e6 | 48 | The paragraph above is intentionally vague because the implementation of |
60a90ecd MK |
49 | .BR pivot_root () |
50 | may change in the future. | |
78f662e1 | 51 | Currently, |
60a90ecd | 52 | .BR pivot_root () |
81b24320 MK |
53 | changes the root directory and the current working directory |
54 | of each process or thread in the same mount namespace to | |
55 | .I new_root | |
56 | if they point to the old root directory. | |
c33144e6 | 57 | This is necessary in order to prevent kernel threads from keeping the old |
edd1fa35 MK |
58 | root directory busy with their root and current working directory, |
59 | even if they never access | |
9ee4a2b6 | 60 | the filesystem in any way. |
c13182ef | 61 | In the future, there may be a mechanism for |
9ee4a2b6 | 62 | kernel threads to explicitly relinquish any access to the filesystem, |
fea681da | 63 | such that this fairly intrusive mechanism can be removed from |
60a90ecd | 64 | .BR pivot_root (). |
efeece04 | 65 | .PP |
edd1fa35 | 66 | Note that this also applies to the calling process: |
60a90ecd | 67 | .BR pivot_root () |
c33144e6 | 68 | may or may not affect its current working directory. |
c13182ef | 69 | It is therefore recommended to call |
60a90ecd MK |
70 | \fBchdir("/")\fP immediately after |
71 | .BR pivot_root (). | |
efeece04 | 72 | .PP |
fea681da MK |
73 | The following restrictions apply to \fInew_root\fP and \fIput_old\fP: |
74 | .IP \- 3 | |
75 | They must be directories. | |
76 | .IP \- 3 | |
9ee4a2b6 | 77 | \fInew_root\fP and \fIput_old\fP must not be on the same filesystem as |
fea681da MK |
78 | the current root. |
79 | .IP \- 3 | |
c7094399 | 80 | \fIput_old\fP must be underneath \fInew_root\fP, that is, adding a nonzero |
8478ee02 | 81 | number of \fI/..\fP to the string pointed to by \fIput_old\fP must yield |
fea681da MK |
82 | the same directory as \fInew_root\fP. |
83 | .IP \- 3 | |
37704bfc MK |
84 | .I new_root |
85 | must be a mount point. | |
86 | (If it is not otherwise a mount point, it suffices to bind mount | |
87 | .I new_root | |
88 | on top of itself.) | |
14e47dbe | 89 | .IP \- 3 |
1a0b1fd7 MK |
90 | The propagation type of |
91 | .I new_root | |
92 | and its parent mount must not be | |
a39e880f MK |
93 | .BR MS_SHARED ; |
94 | similarly, if | |
95 | .I put_old | |
96 | is an existing mount point, its propagation type must not be | |
1a0b1fd7 | 97 | .BR MS_SHARED . |
14e47dbe MK |
98 | .IP \- 3 |
99 | No other filesystem may be mounted on \fIput_old\fP. | |
100 | .PP | |
101 | See also | |
102 | .BR pivot_root (8) | |
103 | for additional usage examples. | |
104 | .PP | |
93dc6336 | 105 | If the current root is not a mount point (e.g., after an earlier |
14e47dbe MK |
106 | .BR chroot (2) |
107 | or | |
93dc6336 MK |
108 | .BR pivot_root ()), |
109 | then the mount point of the filesystem containing the current root directory | |
110 | (i.e., not the directory itself) is mounted on \fIput_old\fP. | |
47297adb | 111 | .SH RETURN VALUE |
c13182ef MK |
112 | On success, zero is returned. |
113 | On error, \-1 is returned, and | |
fea681da MK |
114 | \fIerrno\fP is set appropriately. |
115 | .SH ERRORS | |
60a90ecd | 116 | .BR pivot_root () |
5f5751d3 | 117 | may fail with any of the same errors as |
60a90ecd | 118 | .BR stat (2). |
5f5751d3 | 119 | Additionally, it may fail with the following errors: |
fea681da MK |
120 | .TP |
121 | .B EBUSY | |
9ee4a2b6 MK |
122 | \fInew_root\fP or \fIput_old\fP are on the current root filesystem, |
123 | or a filesystem is already mounted on \fIput_old\fP. | |
fea681da MK |
124 | .TP |
125 | .B EINVAL | |
37704bfc MK |
126 | .I new_root |
127 | is not a mount point. | |
128 | .TP | |
129 | .B EINVAL | |
fea681da MK |
130 | \fIput_old\fP is not underneath \fInew_root\fP. |
131 | .TP | |
dc9b6c92 JS |
132 | .B EINVAL |
133 | The current root is on the rootfs (initial ramfs) filesystem. | |
134 | .TP | |
1a0b1fd7 MK |
135 | .B EINVAL |
136 | Either the mount point at | |
137 | .IR new_root , | |
138 | or the parent mount of that mount point, | |
139 | has propagation type | |
140 | .BR MS_SHARED . | |
141 | .TP | |
a39e880f MK |
142 | .B EINVAL |
143 | .I put_old | |
144 | is a mount point and has the propagation type | |
145 | .BR MS_SHARED . | |
146 | .TP | |
fea681da MK |
147 | .B ENOTDIR |
148 | \fInew_root\fP or \fIput_old\fP is not a directory. | |
149 | .TP | |
150 | .B EPERM | |
edd1fa35 | 151 | The calling process does not have the |
fea681da MK |
152 | .B CAP_SYS_ADMIN |
153 | capability. | |
a1d5f77c MK |
154 | .SH VERSIONS |
155 | .BR pivot_root () | |
156 | was introduced in Linux 2.3.41. | |
47297adb | 157 | .SH CONFORMING TO |
a1d5f77c | 158 | .BR pivot_root () |
8382f16d | 159 | is Linux-specific and hence is not portable. |
f5b03186 MK |
160 | .SH NOTES |
161 | Glibc does not provide a wrapper for this system call; call it using | |
162 | .BR syscall (2). | |
82320f42 EK |
163 | .PP |
164 | The rootfs (initial ramfs) cannot be | |
165 | .BR pivot_root ()ed. | |
52fc743c MK |
166 | The recommended method of changing the root filesystem in this case is |
167 | to delete everything in rootfs, overmount rootfs with the new root, attach | |
82320f42 EK |
168 | .IR stdin / stdout / stderr |
169 | to the new | |
170 | .IR /dev/console , | |
52fc743c MK |
171 | and exec the new |
172 | .BR init (1). | |
173 | Helper programs for this process exist; see | |
82320f42 | 174 | .BR switch_root (8). |
fea681da | 175 | .SH BUGS |
60a90ecd | 176 | .BR pivot_root () |
ac2eb791 | 177 | should not have to change root and current working directory of other |
fea681da | 178 | processes in the system. |
efeece04 | 179 | .PP |
60a90ecd MK |
180 | Some of the more obscure uses of |
181 | .BR pivot_root () | |
182 | may quickly lead to | |
fea681da | 183 | insanity. |
47297adb | 184 | .SH SEE ALSO |
fea681da MK |
185 | .BR chdir (2), |
186 | .BR chroot (2), | |
34a0f19c | 187 | .BR mount (2), |
fea681da MK |
188 | .BR stat (2), |
189 | .BR initrd (4), | |
f42778c4 | 190 | .BR mount_namespaces (7), |
b2bced6d MK |
191 | .BR pivot_root (8), |
192 | .BR switch_root (8) |