Debian Codegraph @

upstream/debian-unstable/man4/initrd.4

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