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