]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" This man-page is Copyright (C) 1997 John S. Kallal |
2 | .\" | |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
4 | .\" |
5 | .\" If the you wish to distribute versions of this work under other | |
c13182ef | 6 | .\" conditions than the above, please contact the author(s) at the following |
fea681da | 7 | .\" for permission: |
988db661 | 8 | .\" |
c13182ef | 9 | .\" John S. Kallal - |
fea681da MK |
10 | .\" email: <kallal@voicenet.com> |
11 | .\" mail: 518 Kerfoot Farm RD, Wilmington, DE 19803-2444, USA | |
12 | .\" phone: (302)654-5478 | |
c13182ef | 13 | .\" |
fea681da | 14 | .\" $Id: initrd.4,v 0.9 1997/11/07 05:05:32 kallal Exp kallal $ |
4c1c5274 | 15 | .TH initrd 4 (date) "Linux man-pages (unreleased)" |
fea681da MK |
16 | .SH NAME |
17 | initrd \- boot loader initialized RAM disk | |
1351674a | 18 | .SH CONFIGURATION |
1351674a MK |
19 | .I /dev/initrd |
20 | is a read-only block device assigned | |
21 | major number 1 and minor number 250. | |
22 | Typically | |
23 | .I /dev/initrd | |
24 | is owned by | |
6f5b156b | 25 | root:disk |
1351674a MK |
26 | with mode 0400 (read access by root only). |
27 | If the Linux system does not have | |
28 | .I /dev/initrd | |
29 | already created, it can be created with the following commands: | |
a2b7a144 MK |
30 | .PP |
31 | .in +4n | |
32 | .EX | |
33 | mknod \-m 400 /dev/initrd b 1 250 | |
34 | chown root:disk /dev/initrd | |
35 | .EE | |
36 | .in | |
1351674a MK |
37 | .PP |
38 | Also, support for both "RAM disk" and "Initial RAM disk" | |
15079abb | 39 | (e.g., |
1ae6b2c7 | 40 | .B CONFIG_BLK_DEV_RAM=y |
c342a49b MK |
41 | and |
42 | .BR CONFIG_BLK_DEV_INITRD=y ) | |
1351674a | 43 | must be compiled directly into the Linux kernel to use |
c342a49b | 44 | .IR /dev/initrd . |
1351674a | 45 | When using |
c342a49b | 46 | .IR /dev/initrd , |
1351674a MK |
47 | the RAM disk driver cannot be loaded as a module. |
48 | .\" | |
49 | .\" | |
50 | .\" | |
fea681da | 51 | .SH DESCRIPTION |
c13182ef MK |
52 | The special file |
53 | .I /dev/initrd | |
54 | is a read-only block device. | |
b644cdd7 MK |
55 | This device is a RAM disk that is initialized (e.g., loaded) |
56 | by the boot loader before the kernel is started. | |
57 | The kernel then can use | |
ee6a7196 | 58 | .IR /dev/initrd "'s" |
b644cdd7 | 59 | contents for a two-phase system boot-up. |
fea681da | 60 | .PP |
c13182ef | 61 | In the first boot-up phase, the kernel starts up |
9ee4a2b6 | 62 | and mounts an initial root filesystem from the contents of |
c13182ef | 63 | .I /dev/initrd |
1930dbe6 | 64 | (e.g., RAM disk initialized by the boot loader). |
c13182ef MK |
65 | In the second phase, additional drivers or other modules |
66 | are loaded from the initial root device's contents. | |
9ee4a2b6 MK |
67 | After loading the additional modules, a new root filesystem |
68 | (i.e., the normal root filesystem) is mounted from a | |
fea681da MK |
69 | different device. |
70 | .\" | |
71 | .\" | |
72 | .\" | |
73d8cece | 73 | .SS Boot-up operation |
c13182ef | 74 | When booting up with |
c342a49b MK |
75 | .BR initrd , |
76 | the system boots as follows: | |
22356d97 | 77 | .IP (1) 5 |
c4fd8ad8 | 78 | The boot loader loads the kernel program and |
c342a49b MK |
79 | .IR /dev/initrd 's |
80 | contents into memory. | |
22356d97 | 81 | .IP (2) |
c4fd8ad8 | 82 | On kernel startup, |
c13182ef | 83 | the kernel uncompresses and copies the contents of the device |
8478ee02 | 84 | .I /dev/initrd |
c13182ef MK |
85 | onto device |
86 | .I /dev/ram0 | |
87 | and then frees the memory used by | |
c342a49b | 88 | .IR /dev/initrd . |
22356d97 | 89 | .IP (3) |
b644cdd7 | 90 | The kernel then read-write mounts the device |
c13182ef | 91 | .I /dev/ram0 |
9ee4a2b6 | 92 | as the initial root filesystem. |
22356d97 | 93 | .IP (4) |
9ee4a2b6 MK |
94 | If the indicated normal root filesystem is also the initial |
95 | root filesystem (e.g., | |
b644cdd7 MK |
96 | .IR /dev/ram0 ) |
97 | then the kernel skips to the last step for the usual boot sequence. | |
22356d97 | 98 | .IP (5) |
c4fd8ad8 | 99 | If the executable file |
1ae6b2c7 | 100 | .I /linuxrc |
9ee4a2b6 | 101 | is present in the initial root filesystem, |
c342a49b | 102 | .I /linuxrc |
c13182ef MK |
103 | is executed with UID 0. |
104 | (The file | |
8478ee02 | 105 | .I /linuxrc |
c13182ef MK |
106 | must have executable permission. |
107 | The file | |
8478ee02 | 108 | .I /linuxrc |
c13182ef | 109 | can be any valid executable, including a shell script.) |
22356d97 | 110 | .IP (6) |
c4fd8ad8 | 111 | If |
8478ee02 | 112 | .I /linuxrc |
c13182ef | 113 | is not executed or when |
8478ee02 | 114 | .I /linuxrc |
9ee4a2b6 | 115 | terminates, the normal root filesystem is mounted. |
fea681da | 116 | (If |
0daa9e92 | 117 | .I /linuxrc |
9ee4a2b6 MK |
118 | exits with any filesystems mounted on the initial root |
119 | filesystem, then the behavior of the kernel is | |
c342a49b | 120 | .BR UNSPECIFIED . |
3d341b33 | 121 | See the NOTES section for the current kernel behavior.) |
22356d97 | 122 | .IP (7) |
9ee4a2b6 | 123 | If the normal root filesystem has a directory |
c342a49b | 124 | .IR /initrd , |
b644cdd7 | 125 | the device |
8478ee02 | 126 | .I /dev/ram0 |
c13182ef | 127 | is moved from |
1ae6b2c7 | 128 | .I / |
c342a49b MK |
129 | to |
130 | .IR /initrd . | |
2b9b829d | 131 | Otherwise, if the directory |
1ae6b2c7 | 132 | .I /initrd |
b644cdd7 | 133 | does not exist, the device |
c342a49b MK |
134 | .I /dev/ram0 |
135 | is unmounted. | |
c13182ef | 136 | (When moved from |
1ae6b2c7 | 137 | .I / |
616e3430 MK |
138 | to |
139 | .IR /initrd , | |
c342a49b | 140 | .I /dev/ram0 |
c13182ef | 141 | is not unmounted and therefore processes can remain running from |
c342a49b | 142 | .IR /dev/ram0 . |
c13182ef | 143 | If directory |
0daa9e92 | 144 | .I /initrd |
9ee4a2b6 | 145 | does not exist on the normal root filesystem |
c13182ef | 146 | and any processes remain running from |
1ae6b2c7 | 147 | .I /dev/ram0 |
c342a49b MK |
148 | when |
149 | .I /linuxrc | |
c13182ef | 150 | exits, the behavior of the kernel is |
c342a49b | 151 | .BR UNSPECIFIED . |
3d341b33 | 152 | See the NOTES section for the current kernel behavior.) |
22356d97 | 153 | .IP (8) |
ade562fb | 154 | The usual boot sequence (e.g., invocation of |
8478ee02 | 155 | .IR /sbin/init ) |
9ee4a2b6 | 156 | is performed on the normal root filesystem. |
c13182ef MK |
157 | .\" |
158 | .\" | |
159 | .\" | |
c4fd8ad8 | 160 | .SS Options |
b644cdd7 | 161 | The following boot loader options, when used with |
c342a49b MK |
162 | .BR initrd , |
163 | affect the kernel's boot-up operation: | |
fea681da MK |
164 | .TP |
165 | .BI initrd= "filename" | |
c13182ef | 166 | Specifies the file to load as the contents of |
c342a49b | 167 | .IR /dev/initrd . |
c10859eb | 168 | For |
c13182ef | 169 | .B LOADLIN |
76c44d83 | 170 | this is a command-line option. |
c13182ef MK |
171 | For |
172 | .B LILO | |
173 | you have to use this command in the | |
174 | .B LILO | |
175 | configuration file | |
8478ee02 | 176 | .IR /etc/lilo.config . |
fea681da | 177 | The filename specified with this |
9ee4a2b6 | 178 | option will typically be a gzipped filesystem image. |
fea681da | 179 | .TP |
d2882549 | 180 | .B noinitrd |
b644cdd7 | 181 | This boot option disables the two-phase boot-up operation. |
c13182ef MK |
182 | The kernel performs the usual boot sequence as if |
183 | .I /dev/initrd | |
184 | was not initialized. | |
fea681da | 185 | With this option, any contents of |
c13182ef | 186 | .I /dev/initrd |
fea681da | 187 | loaded into memory by the boot loader contents are preserved. |
c13182ef MK |
188 | This option permits the contents of |
189 | .I /dev/initrd | |
9ee4a2b6 | 190 | to be any data and need not be limited to a filesystem image. |
c13182ef | 191 | However, device |
8478ee02 | 192 | .I /dev/initrd |
fea681da MK |
193 | is read-only and can be read only one time after system startup. |
194 | .TP | |
195 | .BI root= "device-name" | |
9ee4a2b6 | 196 | Specifies the device to be used as the normal root filesystem. |
c342a49b MK |
197 | For |
198 | .B LOADLIN | |
76c44d83 | 199 | this is a command-line option. |
c342a49b MK |
200 | For |
201 | .B LILO | |
202 | this is a boot time option or | |
c13182ef | 203 | can be used as an option line in the |
c342a49b | 204 | .B LILO |
616e3430 | 205 | configuration file |
c342a49b | 206 | .IR /etc/lilo.config . |
62eb1a10 | 207 | The device specified by this option must be a mountable |
9ee4a2b6 | 208 | device having a suitable root filesystem. |
c13182ef MK |
209 | .\" |
210 | .\" | |
211 | .\" | |
9ee4a2b6 | 212 | .SS Changing the normal root filesystem |
c13182ef | 213 | By default, |
fea681da | 214 | the kernel's settings |
ade562fb | 215 | (e.g., set in the kernel file with |
8478ee02 | 216 | .BR rdev (8) |
fea681da MK |
217 | or compiled into the kernel file), |
218 | or the boot loader option setting | |
9ee4a2b6 MK |
219 | is used for the normal root filesystems. |
220 | For an NFS-mounted normal root filesystem, one has to use the | |
616e3430 | 221 | .B nfs_root_name |
c342a49b MK |
222 | and |
223 | .B nfs_root_addrs | |
c13182ef | 224 | boot options to give the NFS settings. |
fea681da | 225 | For more information on NFS-mounted root see the kernel documentation file |
e7dee047 ES |
226 | .I Documentation/filesystems/nfs/nfsroot.txt |
227 | .\" commit dc7a08166f3a5f23e79e839a8a88849bd3397c32 | |
228 | (or | |
229 | .I Documentation/filesystems/nfsroot.txt | |
230 | before Linux 2.6.33). | |
9ee4a2b6 | 231 | For more information on setting the root filesystem see also the |
1ae6b2c7 | 232 | .B LILO |
c342a49b | 233 | and |
1ae6b2c7 | 234 | .B LOADLIN |
c342a49b | 235 | documentation. |
fea681da | 236 | .PP |
c13182ef | 237 | It is also possible for the |
0daa9e92 | 238 | .I /linuxrc |
fea681da | 239 | executable to change the normal root device. |
c13182ef | 240 | For |
0daa9e92 | 241 | .I /linuxrc |
c13182ef | 242 | to change the normal root device, |
1ae6b2c7 | 243 | .I /proc |
c342a49b | 244 | must be mounted. |
c13182ef | 245 | After mounting |
c342a49b MK |
246 | .IR /proc , |
247 | .I /linuxrc | |
fea681da | 248 | changes the normal root device by writing into the proc files |
b49c2acb MK |
249 | .IR /proc/sys/kernel/real\-root\-dev , |
250 | .IR /proc/sys/kernel/nfs\-root\-name , | |
c342a49b | 251 | and |
b49c2acb | 252 | .IR /proc/sys/kernel/nfs\-root\-addrs . |
fea681da | 253 | For a physical root device, the root device is changed by having |
0daa9e92 | 254 | .I /linuxrc |
9ee4a2b6 | 255 | write the new root filesystem device number into |
b49c2acb | 256 | .IR /proc/sys/kernel/real\-root\-dev . |
9ee4a2b6 | 257 | For an NFS root filesystem, the root device is changed by having |
0daa9e92 | 258 | .I /linuxrc |
fea681da | 259 | write the NFS setting into files |
1ae6b2c7 | 260 | .I /proc/sys/kernel/nfs\-root\-name |
c342a49b | 261 | and |
b49c2acb | 262 | .I /proc/sys/kernel/nfs\-root\-addrs |
ade562fb | 263 | and then writing 0xff (e.g., the pseudo-NFS-device number) into file |
b49c2acb | 264 | .IR /proc/sys/kernel/real\-root\-dev . |
fea681da | 265 | For example, the following shell command line would change |
c13182ef | 266 | the normal root device to |
8478ee02 | 267 | .IR /dev/hdb1 : |
a2b7a144 MK |
268 | .PP |
269 | .in +4n | |
270 | .EX | |
d064d41a | 271 | echo 0x365 >/proc/sys/kernel/real\-root\-dev |
a2b7a144 MK |
272 | .EE |
273 | .in | |
274 | .PP | |
b644cdd7 | 275 | For an NFS example, the following shell command lines would change the |
c13182ef | 276 | normal root device to the NFS directory |
0daa9e92 | 277 | .I /var/nfsroot |
c13182ef | 278 | on a local networked NFS server with IP number 193.8.232.7 for a system with |
0ab92df8 | 279 | IP number 193.8.232.2 and named "idefix": |
a2b7a144 MK |
280 | .PP |
281 | .in +4n | |
282 | .EX | |
d064d41a | 283 | echo /var/nfsroot >/proc/sys/kernel/nfs\-root\-name |
d1a71985 | 284 | echo 193.8.232.2:193.8.232.7::255.255.255.0:idefix \e |
d064d41a MK |
285 | >/proc/sys/kernel/nfs\-root\-addrs |
286 | echo 255 >/proc/sys/kernel/real\-root\-dev | |
a2b7a144 MK |
287 | .EE |
288 | .in | |
2dad4c59 | 289 | .PP |
1a57baf2 MK |
290 | .BR Note : |
291 | The use of | |
b49c2acb | 292 | .I /proc/sys/kernel/real\-root\-dev |
9ee4a2b6 | 293 | to change the root filesystem is obsolete. |
66a9882e | 294 | See the Linux kernel source file |
96c11b3f ES |
295 | .I Documentation/admin\-guide/initrd.rst |
296 | .\" commit 9d85025b0418163fae079c9ba8f8445212de8568 | |
297 | (or | |
1a57baf2 | 298 | .I Documentation/initrd.txt |
96c11b3f | 299 | before Linux 4.10) |
1a57baf2 MK |
300 | as well as |
301 | .BR pivot_root (2) | |
302 | and | |
303 | .BR pivot_root (8) | |
9ee4a2b6 | 304 | for information on the modern method of changing the root filesystem. |
bea08fec | 305 | .\" FIXME . Should this manual page describe the pivot_root mechanism? |
c13182ef MK |
306 | .\" |
307 | .\" | |
308 | .\" | |
c4fd8ad8 | 309 | .SS Usage |
c13182ef | 310 | The main motivation for implementing |
0daa9e92 | 311 | .B initrd |
c13182ef | 312 | was to allow for modular kernel configuration at system installation. |
fea681da MK |
313 | .PP |
314 | A possible system installation scenario is as follows: | |
22356d97 | 315 | .IP (1) 5 |
c4fd8ad8 | 316 | The loader program boots from floppy or other media with a minimal kernel |
ade562fb | 317 | (e.g., support for |
616e3430 | 318 | .IR /dev/ram , |
c342a49b | 319 | .IR /dev/initrd , |
9ee4a2b6 | 320 | and the ext2 filesystem) and loads |
1ae6b2c7 | 321 | .I /dev/initrd |
9ee4a2b6 | 322 | with a gzipped version of the initial filesystem. |
22356d97 | 323 | .IP (2) |
c4fd8ad8 | 324 | The executable |
0daa9e92 | 325 | .I /linuxrc |
9ee4a2b6 MK |
326 | determines what is needed to (1) mount the normal root filesystem |
327 | (i.e., device type, device drivers, filesystem) and (2) the | |
ade562fb | 328 | distribution media (e.g., CD-ROM, network, tape, ...). |
b644cdd7 MK |
329 | This can be done by asking the user, by auto-probing, |
330 | or by using a hybrid approach. | |
22356d97 | 331 | .IP (3) |
c4fd8ad8 | 332 | The executable |
0daa9e92 | 333 | .I /linuxrc |
9ee4a2b6 | 334 | loads the necessary modules from the initial root filesystem. |
22356d97 | 335 | .IP (4) |
c4fd8ad8 | 336 | The executable |
0daa9e92 | 337 | .I /linuxrc |
9ee4a2b6 MK |
338 | creates and populates the root filesystem. |
339 | (At this stage the normal root filesystem does not have to be a | |
fea681da | 340 | completed system yet.) |
22356d97 | 341 | .IP (5) |
c4fd8ad8 | 342 | The executable |
1ae6b2c7 | 343 | .I /linuxrc |
c342a49b | 344 | sets |
b49c2acb | 345 | .IR /proc/sys/kernel/real\-root\-dev , |
eb6d799c | 346 | unmounts |
c342a49b | 347 | .IR /proc , |
28955f15 SP |
348 | the normal root filesystem and any other filesystems |
349 | it has mounted, and then terminates. | |
22356d97 | 350 | .IP (6) |
9ee4a2b6 | 351 | The kernel then mounts the normal root filesystem. |
22356d97 | 352 | .IP (7) |
9ee4a2b6 | 353 | Now that the filesystem is accessible and intact, |
fea681da | 354 | the boot loader can be installed. |
22356d97 | 355 | .IP (8) |
c4fd8ad8 | 356 | The boot loader is configured to load into |
0daa9e92 | 357 | .I /dev/initrd |
9ee4a2b6 | 358 | a filesystem with the set of modules that was used to bring up the system. |
243690b2 | 359 | (e.g., device |
0daa9e92 | 360 | .I /dev/ram0 |
fea681da | 361 | can be modified, then unmounted, and finally, the image is written from |
0daa9e92 | 362 | .I /dev/ram0 |
fea681da | 363 | to a file.) |
22356d97 | 364 | .IP (9) |
c4fd8ad8 | 365 | The system is now bootable and additional installation tasks can be |
fea681da | 366 | performed. |
fea681da | 367 | .PP |
c13182ef | 368 | The key role of |
0daa9e92 | 369 | .I /dev/initrd |
3b777aff | 370 | in the above is to reuse the configuration data during normal system operation |
fea681da MK |
371 | without requiring initial kernel selection, a large generic kernel or, |
372 | recompiling the kernel. | |
373 | .PP | |
374 | A second scenario is for installations where Linux runs on systems with | |
c13182ef | 375 | different hardware configurations in a single administrative network. |
fea681da MK |
376 | In such cases, it may be desirable to use only a small set of kernels |
377 | (ideally only one) and to keep the system-specific part of configuration | |
c13182ef MK |
378 | information as small as possible. |
379 | In this case, create a common file | |
380 | with all needed modules. | |
381 | Then, only the | |
8478ee02 | 382 | .I /linuxrc |
fea681da | 383 | file or a file executed by |
8478ee02 | 384 | .I /linuxrc |
fea681da MK |
385 | would be different. |
386 | .PP | |
c13182ef | 387 | A third scenario is more convenient recovery disks. |
9ee4a2b6 | 388 | Because information like the location of the root filesystem |
c13182ef MK |
389 | partition is not needed at boot time, the system loaded from |
390 | .I /dev/initrd | |
391 | can use a dialog and/or auto-detection followed by a | |
fea681da MK |
392 | possible sanity check. |
393 | .PP | |
c13182ef | 394 | Last but not least, Linux distributions on CD-ROM may use |
0daa9e92 | 395 | .B initrd |
c13182ef MK |
396 | for easy installation from the CD-ROM. |
397 | The distribution can use | |
0daa9e92 | 398 | .B LOADLIN |
c13182ef | 399 | to directly load |
0daa9e92 | 400 | .I /dev/initrd |
fea681da | 401 | from CD-ROM without the need of any floppies. |
c13182ef | 402 | The distribution could also use a |
0daa9e92 | 403 | .B LILO |
b083bb64 | 404 | boot floppy and then bootstrap a bigger RAM disk via |
1ae6b2c7 | 405 | .I /dev/initrd |
c342a49b | 406 | from the CD-ROM. |
c13182ef MK |
407 | .\" |
408 | .\" | |
409 | .\" | |
25768803 MK |
410 | .SH FILES |
411 | .I /dev/initrd | |
412 | .br | |
413 | .I /dev/ram0 | |
414 | .br | |
415 | .I /linuxrc | |
416 | .br | |
417 | .I /initrd | |
418 | .\" | |
419 | .\" | |
420 | .\" | |
fea681da | 421 | .SH NOTES |
22356d97 | 422 | .IP \(bu 3 |
9ee4a2b6 | 423 | With the current kernel, any filesystems that remain mounted when |
c342a49b MK |
424 | .I /dev/ram0 |
425 | is moved from | |
426 | .I / | |
427 | to | |
428 | .I /initrd | |
c13182ef MK |
429 | continue to be accessible. |
430 | However, the | |
0daa9e92 | 431 | .I /proc/mounts |
c13182ef | 432 | entries are not updated. |
22356d97 | 433 | .IP \(bu |
c4fd8ad8 | 434 | With the current kernel, if directory |
c342a49b MK |
435 | .I /initrd |
436 | does not exist, then | |
c13182ef | 437 | .I /dev/ram0 |
118d6caa | 438 | will |
4bd8c614 MK |
439 | .B not |
440 | be fully unmounted if | |
0daa9e92 | 441 | .I /dev/ram0 |
9ee4a2b6 | 442 | is used by any process or has any filesystem mounted on it. |
c13182ef | 443 | If |
1ae6b2c7 | 444 | .I /dev/ram0 |
c342a49b | 445 | is |
4bd8c614 | 446 | .B not |
c342a49b | 447 | fully unmounted, then |
0daa9e92 | 448 | .I /dev/ram0 |
fea681da | 449 | will remain in memory. |
22356d97 | 450 | .IP \(bu |
c4fd8ad8 | 451 | Users of |
0daa9e92 | 452 | .I /dev/initrd |
243690b2 | 453 | should not depend on the behavior given in the above notes. |
fea681da | 454 | The behavior may change in future versions of the Linux kernel. |
c13182ef MK |
455 | .\" |
456 | .\" | |
457 | .\" | |
d2dc6294 MK |
458 | .\" .SH AUTHORS |
459 | .\" The kernel code for device | |
460 | .\" .BR initrd | |
461 | .\" was written by Werner Almesberger <almesber@lrc.epfl.ch> and | |
462 | .\" Hans Lermen <lermen@elserv.ffm.fgan.de>. | |
463 | .\" The code for | |
464 | .\" .BR initrd | |
465 | .\" was added to the baseline Linux kernel in development version 1.3.73. | |
47297adb | 466 | .SH SEE ALSO |
e37e3282 MK |
467 | .BR chown (1), |
468 | .BR mknod (1), | |
469 | .BR ram (4), | |
470 | .BR freeramdisk (8), | |
471 | .BR rdev (8) | |
2dad4c59 | 472 | .PP |
96c11b3f ES |
473 | .I Documentation/admin\-guide/initrd.rst |
474 | .\" commit 9d85025b0418163fae079c9ba8f8445212de8568 | |
475 | (or | |
173fe7e7 | 476 | .I Documentation/initrd.txt |
96c11b3f | 477 | before Linux 4.10) |
173fe7e7 DP |
478 | in the Linux kernel source tree, the LILO documentation, |
479 | the LOADLIN documentation, the SYSLINUX documentation |