Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | Using the initial RAM disk (initrd) |
2 | =================================== | |
3 | ||
4 | Written 1996,2000 by Werner Almesberger <werner.almesberger@epfl.ch> and | |
5d0ad553 | 5 | Hans Lermen <lermen@fgan.de> |
1da177e4 LT |
6 | |
7 | ||
8 | initrd provides the capability to load a RAM disk by the boot loader. | |
9 | This RAM disk can then be mounted as the root file system and programs | |
10 | can be run from it. Afterwards, a new root file system can be mounted | |
11 | from a different device. The previous root (from initrd) is then moved | |
12 | to a directory and can be subsequently unmounted. | |
13 | ||
14 | initrd is mainly designed to allow system startup to occur in two phases, | |
15 | where the kernel comes up with a minimum set of compiled-in drivers, and | |
16 | where additional modules are loaded from initrd. | |
17 | ||
18 | This document gives a brief overview of the use of initrd. A more detailed | |
5d0ad553 | 19 | discussion of the boot process can be found in [#f1]_. |
1da177e4 LT |
20 | |
21 | ||
22 | Operation | |
23 | --------- | |
24 | ||
25 | When using initrd, the system typically boots as follows: | |
26 | ||
27 | 1) the boot loader loads the kernel and the initial RAM disk | |
28 | 2) the kernel converts initrd into a "normal" RAM disk and | |
29 | frees the memory used by initrd | |
5d0ad553 | 30 | 3) if the root device is not ``/dev/ram0``, the old (deprecated) |
9d9a2000 DA |
31 | change_root procedure is followed. see the "Obsolete root change |
32 | mechanism" section below. | |
5d0ad553 | 33 | 4) root device is mounted. if it is ``/dev/ram0``, the initrd image is |
9d9a2000 DA |
34 | then mounted as root |
35 | 5) /sbin/init is executed (this can be any valid executable, including | |
1da177e4 | 36 | shell scripts; it is run with uid 0 and can do basically everything |
9d9a2000 DA |
37 | init can do). |
38 | 6) init mounts the "real" root file system | |
39 | 7) init places the root file system at the root directory using the | |
1da177e4 | 40 | pivot_root system call |
5d0ad553 | 41 | 8) init execs the ``/sbin/init`` on the new root filesystem, performing |
9d9a2000 DA |
42 | the usual boot sequence |
43 | 9) the initrd file system is removed | |
1da177e4 LT |
44 | |
45 | Note that changing the root directory does not involve unmounting it. | |
46 | It is therefore possible to leave processes running on initrd during that | |
47 | procedure. Also note that file systems mounted under initrd continue to | |
48 | be accessible. | |
49 | ||
50 | ||
51 | Boot command-line options | |
52 | ------------------------- | |
53 | ||
5d0ad553 | 54 | initrd adds the following new options:: |
1da177e4 LT |
55 | |
56 | initrd=<path> (e.g. LOADLIN) | |
57 | ||
58 | Loads the specified file as the initial RAM disk. When using LILO, you | |
59 | have to specify the RAM disk image file in /etc/lilo.conf, using the | |
60 | INITRD configuration variable. | |
61 | ||
62 | noinitrd | |
63 | ||
64 | initrd data is preserved but it is not converted to a RAM disk and | |
65 | the "normal" root file system is mounted. initrd data can be read | |
66 | from /dev/initrd. Note that the data in initrd can have any structure | |
67 | in this case and doesn't necessarily have to be a file system image. | |
68 | This option is used mainly for debugging. | |
69 | ||
70 | Note: /dev/initrd is read-only and it can only be used once. As soon | |
71 | as the last process has closed it, all data is freed and /dev/initrd | |
72 | can't be opened anymore. | |
73 | ||
890fbae2 | 74 | root=/dev/ram0 |
1da177e4 LT |
75 | |
76 | initrd is mounted as root, and the normal boot procedure is followed, | |
9d9a2000 | 77 | with the RAM disk mounted as root. |
1da177e4 | 78 | |
0a5eca65 TH |
79 | Compressed cpio images |
80 | ---------------------- | |
81 | ||
82 | Recent kernels have support for populating a ramdisk from a compressed cpio | |
1810732e RD |
83 | archive. On such systems, the creation of a ramdisk image doesn't need to |
84 | involve special block devices or loopbacks; you merely create a directory on | |
0a5eca65 | 85 | disk with the desired initrd content, cd to that directory, and run (as an |
5d0ad553 | 86 | example):: |
0a5eca65 | 87 | |
5d0ad553 | 88 | find . | cpio --quiet -H newc -o | gzip -9 -n > /boot/imagefile.img |
0a5eca65 | 89 | |
5d0ad553 | 90 | Examining the contents of an existing image file is just as simple:: |
0a5eca65 | 91 | |
5d0ad553 MCC |
92 | mkdir /tmp/imagefile |
93 | cd /tmp/imagefile | |
94 | gzip -cd /boot/imagefile.img | cpio -imd --quiet | |
1da177e4 LT |
95 | |
96 | Installation | |
97 | ------------ | |
98 | ||
99 | First, a directory for the initrd file system has to be created on the | |
5d0ad553 | 100 | "normal" root file system, e.g.:: |
1da177e4 | 101 | |
5d0ad553 | 102 | # mkdir /initrd |
1da177e4 | 103 | |
5d0ad553 MCC |
104 | The name is not relevant. More details can be found on the |
105 | :manpage:`pivot_root(2)` man page. | |
1da177e4 LT |
106 | |
107 | If the root file system is created during the boot procedure (i.e. if | |
108 | you're building an install floppy), the root file system creation | |
5d0ad553 | 109 | procedure should create the ``/initrd`` directory. |
1da177e4 LT |
110 | |
111 | If initrd will not be mounted in some cases, its content is still | |
5d0ad553 | 112 | accessible if the following device has been created:: |
1da177e4 | 113 | |
5d0ad553 MCC |
114 | # mknod /dev/initrd b 1 250 |
115 | # chmod 400 /dev/initrd | |
1da177e4 LT |
116 | |
117 | Second, the kernel has to be compiled with RAM disk support and with | |
118 | support for the initial RAM disk enabled. Also, at least all components | |
119 | needed to execute programs from initrd (e.g. executable format and file | |
120 | system) must be compiled into the kernel. | |
121 | ||
122 | Third, you have to create the RAM disk image. This is done by creating a | |
123 | file system on a block device, copying files to it as needed, and then | |
124 | copying the content of the block device to the initrd file. With recent | |
125 | kernels, at least three types of devices are suitable for that: | |
126 | ||
127 | - a floppy disk (works everywhere but it's painfully slow) | |
128 | - a RAM disk (fast, but allocates physical memory) | |
129 | - a loopback device (the most elegant solution) | |
130 | ||
131 | We'll describe the loopback device method: | |
132 | ||
133 | 1) make sure loopback block devices are configured into the kernel | |
5d0ad553 MCC |
134 | 2) create an empty file system of the appropriate size, e.g.:: |
135 | ||
136 | # dd if=/dev/zero of=initrd bs=300k count=1 | |
137 | # mke2fs -F -m0 initrd | |
138 | ||
1da177e4 | 139 | (if space is critical, you may want to use the Minix FS instead of Ext2) |
5d0ad553 MCC |
140 | 3) mount the file system, e.g.:: |
141 | ||
142 | # mount -t ext2 -o loop initrd /mnt | |
143 | ||
144 | 4) create the console device:: | |
145 | ||
1da177e4 LT |
146 | # mkdir /mnt/dev |
147 | # mknod /mnt/dev/console c 5 1 | |
5d0ad553 | 148 | |
1da177e4 | 149 | 5) copy all the files that are needed to properly use the initrd |
5d0ad553 MCC |
150 | environment. Don't forget the most important file, ``/sbin/init`` |
151 | ||
152 | .. note:: ``/sbin/init`` permissions must include "x" (execute). | |
153 | ||
1da177e4 | 154 | 6) correct operation the initrd environment can frequently be tested |
5d0ad553 MCC |
155 | even without rebooting with the command:: |
156 | ||
157 | # chroot /mnt /sbin/init | |
158 | ||
1da177e4 LT |
159 | This is of course limited to initrds that do not interfere with the |
160 | general system state (e.g. by reconfiguring network interfaces, | |
161 | overwriting mounted devices, trying to start already running demons, | |
162 | etc. Note however that it is usually possible to use pivot_root in | |
163 | such a chroot'ed initrd environment.) | |
5d0ad553 MCC |
164 | 7) unmount the file system:: |
165 | ||
166 | # umount /mnt | |
167 | ||
1da177e4 | 168 | 8) the initrd is now in the file "initrd". Optionally, it can now be |
5d0ad553 MCC |
169 | compressed:: |
170 | ||
171 | # gzip -9 initrd | |
1da177e4 LT |
172 | |
173 | For experimenting with initrd, you may want to take a rescue floppy and | |
5d0ad553 MCC |
174 | only add a symbolic link from ``/sbin/init`` to ``/bin/sh``. Alternatively, you |
175 | can try the experimental newlib environment [#f2]_ to create a small | |
1da177e4 LT |
176 | initrd. |
177 | ||
178 | Finally, you have to boot the kernel and load initrd. Almost all Linux | |
179 | boot loaders support initrd. Since the boot process is still compatible | |
180 | with an older mechanism, the following boot command line parameters | |
5d0ad553 | 181 | have to be given:: |
1da177e4 | 182 | |
9d9a2000 | 183 | root=/dev/ram0 rw |
1da177e4 | 184 | |
890fbae2 | 185 | (rw is only necessary if writing to the initrd file system.) |
1da177e4 | 186 | |
5d0ad553 | 187 | With LOADLIN, you simply execute:: |
1da177e4 LT |
188 | |
189 | LOADLIN <kernel> initrd=<disk_image> | |
1da177e4 | 190 | |
5d0ad553 MCC |
191 | e.g.:: |
192 | ||
193 | LOADLIN C:\LINUX\BZIMAGE initrd=C:\LINUX\INITRD.GZ root=/dev/ram0 rw | |
194 | ||
195 | With LILO, you add the option ``INITRD=<path>`` to either the global section | |
196 | or to the section of the respective kernel in ``/etc/lilo.conf``, and pass | |
197 | the options using APPEND, e.g.:: | |
1da177e4 LT |
198 | |
199 | image = /bzImage | |
200 | initrd = /boot/initrd.gz | |
9d9a2000 | 201 | append = "root=/dev/ram0 rw" |
1da177e4 | 202 | |
5d0ad553 | 203 | and run ``/sbin/lilo`` |
1da177e4 LT |
204 | |
205 | For other boot loaders, please refer to the respective documentation. | |
206 | ||
207 | Now you can boot and enjoy using initrd. | |
208 | ||
209 | ||
210 | Changing the root device | |
211 | ------------------------ | |
212 | ||
9d9a2000 | 213 | When finished with its duties, init typically changes the root device |
1da177e4 LT |
214 | and proceeds with starting the Linux system on the "real" root device. |
215 | ||
216 | The procedure involves the following steps: | |
217 | - mounting the new root file system | |
218 | - turning it into the root file system | |
219 | - removing all accesses to the old (initrd) root file system | |
220 | - unmounting the initrd file system and de-allocating the RAM disk | |
221 | ||
222 | Mounting the new root file system is easy: it just needs to be mounted on | |
5d0ad553 | 223 | a directory under the current root. Example:: |
1da177e4 | 224 | |
5d0ad553 MCC |
225 | # mkdir /new-root |
226 | # mount -o ro /dev/hda1 /new-root | |
1da177e4 LT |
227 | |
228 | The root change is accomplished with the pivot_root system call, which | |
5d0ad553 MCC |
229 | is also available via the ``pivot_root`` utility (see :manpage:`pivot_root(8)` |
230 | man page; ``pivot_root`` is distributed with util-linux version 2.10h or higher | |
231 | [#f3]_). ``pivot_root`` moves the current root to a directory under the new | |
1da177e4 | 232 | root, and puts the new root at its place. The directory for the old root |
5d0ad553 | 233 | must exist before calling ``pivot_root``. Example:: |
1da177e4 | 234 | |
5d0ad553 MCC |
235 | # cd /new-root |
236 | # mkdir initrd | |
237 | # pivot_root . initrd | |
1da177e4 | 238 | |
9d9a2000 | 239 | Now, the init process may still access the old root via its |
1da177e4 LT |
240 | executable, shared libraries, standard input/output/error, and its |
241 | current root directory. All these references are dropped by the | |
5d0ad553 | 242 | following command:: |
1da177e4 | 243 | |
5d0ad553 | 244 | # exec chroot . what-follows <dev/console >dev/console 2>&1 |
1da177e4 | 245 | |
5d0ad553 | 246 | Where what-follows is a program under the new root, e.g. ``/sbin/init`` |
890fbae2 | 247 | If the new root file system will be used with udev and has no valid |
5d0ad553 MCC |
248 | ``/dev`` directory, udev must be initialized before invoking chroot in order |
249 | to provide ``/dev/console``. | |
1da177e4 LT |
250 | |
251 | Note: implementation details of pivot_root may change with time. In order | |
252 | to ensure compatibility, the following points should be observed: | |
253 | ||
254 | - before calling pivot_root, the current directory of the invoking | |
255 | process should point to the new root directory | |
256 | - use . as the first argument, and the _relative_ path of the directory | |
257 | for the old root as the second argument | |
258 | - a chroot program must be available under the old and the new root | |
259 | - chroot to the new root afterwards | |
260 | - use relative paths for dev/console in the exec command | |
261 | ||
262 | Now, the initrd can be unmounted and the memory allocated by the RAM | |
5d0ad553 | 263 | disk can be freed:: |
1da177e4 | 264 | |
5d0ad553 MCC |
265 | # umount /initrd |
266 | # blockdev --flushbufs /dev/ram0 | |
1da177e4 LT |
267 | |
268 | It is also possible to use initrd with an NFS-mounted root, see the | |
5d0ad553 | 269 | :manpage:`pivot_root(8)` man page for details. |
1da177e4 | 270 | |
1da177e4 LT |
271 | |
272 | Usage scenarios | |
273 | --------------- | |
274 | ||
275 | The main motivation for implementing initrd was to allow for modular | |
276 | kernel configuration at system installation. The procedure would work | |
277 | as follows: | |
278 | ||
279 | 1) system boots from floppy or other media with a minimal kernel | |
280 | (e.g. support for RAM disks, initrd, a.out, and the Ext2 FS) and | |
281 | loads initrd | |
5d0ad553 | 282 | 2) ``/sbin/init`` determines what is needed to (1) mount the "real" root FS |
1da177e4 LT |
283 | (i.e. device type, device drivers, file system) and (2) the |
284 | distribution media (e.g. CD-ROM, network, tape, ...). This can be | |
285 | done by asking the user, by auto-probing, or by using a hybrid | |
286 | approach. | |
5d0ad553 MCC |
287 | 3) ``/sbin/init`` loads the necessary kernel modules |
288 | 4) ``/sbin/init`` creates and populates the root file system (this doesn't | |
1da177e4 | 289 | have to be a very usable system yet) |
5d0ad553 | 290 | 5) ``/sbin/init`` invokes ``pivot_root`` to change the root file system and |
1da177e4 LT |
291 | execs - via chroot - a program that continues the installation |
292 | 6) the boot loader is installed | |
293 | 7) the boot loader is configured to load an initrd with the set of | |
5d0ad553 | 294 | modules that was used to bring up the system (e.g. ``/initrd`` can be |
1da177e4 | 295 | modified, then unmounted, and finally, the image is written from |
5d0ad553 | 296 | ``/dev/ram0`` or ``/dev/rd/0`` to a file) |
1da177e4 LT |
297 | 8) now the system is bootable and additional installation tasks can be |
298 | performed | |
299 | ||
300 | The key role of initrd here is to re-use the configuration data during | |
301 | normal system operation without requiring the use of a bloated "generic" | |
302 | kernel or re-compiling or re-linking the kernel. | |
303 | ||
304 | A second scenario is for installations where Linux runs on systems with | |
305 | different hardware configurations in a single administrative domain. In | |
306 | such cases, it is desirable to generate only a small set of kernels | |
307 | (ideally only one) and to keep the system-specific part of configuration | |
308 | information as small as possible. In this case, a common initrd could be | |
5d0ad553 | 309 | generated with all the necessary modules. Then, only ``/sbin/init`` or a file |
1da177e4 LT |
310 | read by it would have to be different. |
311 | ||
1810732e | 312 | A third scenario is more convenient recovery disks, because information |
1da177e4 LT |
313 | like the location of the root FS partition doesn't have to be provided at |
314 | boot time, but the system loaded from initrd can invoke a user-friendly | |
315 | dialog and it can also perform some sanity checks (or even some form of | |
316 | auto-detection). | |
317 | ||
318 | Last not least, CD-ROM distributors may use it for better installation | |
319 | from CD, e.g. by using a boot floppy and bootstrapping a bigger RAM disk | |
5d0ad553 | 320 | via initrd from CD; or by booting via a loader like ``LOADLIN`` or directly |
1da177e4 | 321 | from the CD-ROM, and loading the RAM disk from CD without need of |
5d0ad553 | 322 | floppies. |
1da177e4 LT |
323 | |
324 | ||
325 | Obsolete root change mechanism | |
326 | ------------------------------ | |
327 | ||
328 | The following mechanism was used before the introduction of pivot_root. | |
329 | Current kernels still support it, but you should _not_ rely on its | |
330 | continued availability. | |
331 | ||
332 | It works by mounting the "real" root device (i.e. the one set with rdev | |
333 | in the kernel image or with root=... at the boot command line) as the | |
334 | root file system when linuxrc exits. The initrd file system is then | |
5d0ad553 | 335 | unmounted, or, if it is still busy, moved to a directory ``/initrd``, if |
1da177e4 LT |
336 | such a directory exists on the new root file system. |
337 | ||
338 | In order to use this mechanism, you do not have to specify the boot | |
339 | command options root, init, or rw. (If specified, they will affect | |
340 | the real root file system, not the initrd environment.) | |
5d0ad553 | 341 | |
1da177e4 LT |
342 | If /proc is mounted, the "real" root device can be changed from within |
343 | linuxrc by writing the number of the new root FS device to the special | |
5d0ad553 | 344 | file /proc/sys/kernel/real-root-dev, e.g.:: |
1da177e4 LT |
345 | |
346 | # echo 0x301 >/proc/sys/kernel/real-root-dev | |
347 | ||
348 | Note that the mechanism is incompatible with NFS and similar file | |
349 | systems. | |
350 | ||
5d0ad553 MCC |
351 | This old, deprecated mechanism is commonly called ``change_root``, while |
352 | the new, supported mechanism is called ``pivot_root``. | |
1da177e4 LT |
353 | |
354 | ||
9d9a2000 DA |
355 | Mixed change_root and pivot_root mechanism |
356 | ------------------------------------------ | |
357 | ||
5d0ad553 MCC |
358 | In case you did not want to use ``root=/dev/ram0`` to trigger the pivot_root |
359 | mechanism, you may create both ``/linuxrc`` and ``/sbin/init`` in your initrd | |
360 | image. | |
9d9a2000 | 361 | |
5d0ad553 | 362 | ``/linuxrc`` would contain only the following:: |
9d9a2000 | 363 | |
5d0ad553 MCC |
364 | #! /bin/sh |
365 | mount -n -t proc proc /proc | |
366 | echo 0x0100 >/proc/sys/kernel/real-root-dev | |
367 | umount -n /proc | |
9d9a2000 DA |
368 | |
369 | Once linuxrc exited, the kernel would mount again your initrd as root, | |
5d0ad553 MCC |
370 | this time executing ``/sbin/init``. Again, it would be the duty of this init |
371 | to build the right environment (maybe using the ``root= device`` passed on | |
372 | the cmdline) before the final execution of the real ``/sbin/init``. | |
9d9a2000 DA |
373 | |
374 | ||
1da177e4 LT |
375 | Resources |
376 | --------- | |
377 | ||
5d0ad553 | 378 | .. [#f1] Almesberger, Werner; "Booting Linux: The History and the Future" |
93431e06 | 379 | https://www.almesberger.net/cv/papers/ols2k-9.ps.gz |
5d0ad553 MCC |
380 | .. [#f2] newlib package (experimental), with initrd example |
381 | https://www.sourceware.org/newlib/ | |
382 | .. [#f3] util-linux: Miscellaneous utilities for Linux | |
383 | https://www.kernel.org/pub/linux/utils/util-linux/ |