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