/[gentoo]/xml/htdocs/doc/en/initramfs-guide.xml
Gentoo

Contents of /xml/htdocs/doc/en/initramfs-guide.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.4 - (show annotations) (download) (as text)
Tue Sep 17 07:27:29 2013 UTC (12 months ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.3: +2 -2 lines
File MIME type: application/xml
Initramfs guide moved to https://wiki.gentoo.org/wiki/Initramfs/HOWTO

1 <?xml version='1.0' encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/initramfs-guide.xml,v 1.3 2012/07/24 12:12:51 swift Exp $ -->
3
4 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5
6 <guide disclaimer="obsolete" redirect="https://wiki.gentoo.org/wiki/Initramfs/HOWTO">
7 <title>Gentoo Linux Initial RAM File System Guide</title>
8
9 <author title="Author">
10 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
11 </author>
12
13 <abstract>
14 More and more systems require an initramfs to boot up properly. In this guide,
15 we tackle the concepts of the initramfs as well as how to properly create and
16 manage initramfs instances.
17 </abstract>
18
19 <!-- The content of this document is licensed under the CC-BY-SA license -->
20 <!-- See http://creativecommons.org/licenses/by-sa/3.0 -->
21 <license/>
22
23 <version>2</version>
24 <date>2012-07-24</date>
25
26 <chapter>
27 <title>Initramfs concepts</title>
28 <section>
29 <title>Introduction</title>
30 <body>
31
32 <p>
33 For many users, an initramfs system is of no concern. Their system uses a simple
34 partitioning schema with no exotic drivers or setups (like encrypted file
35 systems), so the Linux kernel is well able to hand over control to the
36 <c>init</c> binary on their system. But for many systems, an initramfs is almost
37 mandatory.
38 </p>
39
40 <p>
41 The key concept to understanding what an initramfs is (or is needed for) is to
42 understand how the Linux boot process works, even in a high-level approach.
43 </p>
44
45 </body>
46 </section>
47 <section>
48 <title>Linux boot process</title>
49 <body>
50
51 <p>
52 Once the Linux kernel has control over the system (which it gets after being
53 loaded by the boot loader), it prepares its memory structures and drivers as
54 well as it can. It then hands over control to an application (usually
55 <c>init</c>) whose task it is to further prepare the system and make sure that,
56 at the end of the boot process, all necessary services are running and the user
57 is able to log on. The <c>init</c> application does that by launching, among
58 other services, the <c>udev</c> daemon who will further load up and prepare the
59 system based on the detected devices. When <c>udev</c> is launched, all
60 remaining file systems that have not been mounted are mounted, and the remainder
61 of services is started.
62 </p>
63
64 <p>
65 For systems where all necessary files and tools reside on the same file system,
66 the <c>init</c> application can perfectly control the further boot process. But
67 when multiple file systems are defined (or more exotic installations are done),
68 this might become a bit more tricky:
69 </p>
70
71 <ul>
72 <li>
73 When the <path>/usr</path> partition is on a separate file system, tools and
74 drivers that have files stored within <path>/usr</path> cannot be used
75 unless <path>/usr</path> is available. If those tools are needed to make
76 <path>/usr</path> available, then we cannot boot up the system.
77 </li>
78 <li>
79 If the root file system is encrypted, then the Linux kernel will not be able
80 to find the <c>init</c> application, resulting in an unbootable system.
81 </li>
82 </ul>
83
84 <p>
85 The solution for this problem has since long been to use an <e>initrd</e>
86 (initial root device).
87 </p>
88
89 </body>
90 </section>
91 <section>
92 <title>The initial root disk</title>
93 <body>
94
95 <p>
96 The <e>initrd</e> is an in-memory disk structure (ramdisk) that
97 contains the necessary tools and scripts to mount the needed file systems before
98 control is handed over to the <c>init</c> application on the root file system.
99 The Linux kernel triggers the setup script (usually called <c>linuxrc</c> but
100 that is not mandatory) on this root disk, which prepares the system, switches to
101 the real root file system and then calls <c>init</c>.
102 </p>
103
104 <p>
105 Although the initrd method is all that is needed, it had a few drawbacks:
106 </p>
107
108 <ul>
109 <li>
110 It is a full-fledged block device, requiring the overhead of an entire
111 file system on it, and has a fixed size. Choose an initrd that is too small,
112 and you won't be able to fit in all needed scripts. Make it too big, and
113 you're wasting memory.
114 </li>
115 <li>
116 Because it is a real device, it also consumes cache memory in the Linux
117 kernel and is prone to the memory- and file management methods in use (such
118 as paging), making it even worse in memory consumption.
119 </li>
120 </ul>
121
122 <p>
123 To resolve these (for some perhaps hardly called) problems, the initramfs was
124 created.
125 </p>
126
127 </body>
128 </section>
129 <section>
130 <title>The initial ram file system</title>
131 <body>
132
133 <p>
134 An <e>initramfs</e> is an initial ram file system based on <e>tmpfs</e>
135 (a size-flexible, in-memory lightweight file system), which also didn't use a
136 separate block device (so no caching was done and all overhead mentioned earlier
137 disappears). Just like the initrd, it contains the tools and scripts needed to
138 mount the file systems before the <c>init</c> binary on the real root file
139 system is called. These tools can be decryption abstraction layers (for
140 encrypted file systems), logical volume managers, software raid, bluetooth
141 driver based file system loaders, etc.
142 </p>
143
144 <p>
145 The content of the initramfs is made by creating a cpio archive. <c>cpio</c> is
146 an old (but proven) file archiver solution (and its resulting archive files are
147 called <e>cpio files</e>). You can definitely compare it to <c>tar</c>. The
148 choice of <c>cpio</c> here was because it is easier to implement (code-wise) and
149 supported (back then) device files (which <c>tar</c> couldn't).
150 </p>
151
152 <p>
153 All files, tools, libraries, configuration settings (if applicable), etc. are
154 put into the cpio archive. This archive is then compressed using the <c>gzip</c>
155 utility and stored alongside the Linux kernel. The boot loader will then offer
156 it to the Linux kernel at boot time so the kernel knows an initramfs is needed.
157 </p>
158
159 <p>
160 Once detected, the Linux kernel will create a tmpfs file system, extract the
161 contents of the archive on it, and then launches the <c>init</c> script located
162 in the root of the tmpfs file system. This script will then mount the real root
163 file system (after making sure it can mount it, for instance by loading
164 additional modules, preparing an encryption abstraction layer, etc.) as well as
165 vital other file systems (such as <path>/usr</path> and <path>/var</path>).
166 </p>
167
168 <p>
169 Once the root file system and the other vital file systems are mounted, the
170 <c>init</c> script from the initramfs will switch the root towards the real root
171 file system and finally call the <c>/sbin/init</c> on that system to continue
172 the boot process.
173 </p>
174
175 </body>
176 </section>
177 </chapter>
178
179 <chapter>
180 <title>Creating an initramfs</title>
181 <section>
182 <title>Introduction and bootloader configuration</title>
183 <body>
184
185 <p>
186 To create an initramfs, it is important that you know what additional drivers,
187 scripts and tools you need to boot your system. For instance, if you use LVM,
188 then you will need to support LVM tools on the initramfs. Likewise, if you use
189 software RAID, you need <c>mdadm</c>, etc.
190 </p>
191
192 <p>
193 Some tools exist that help you create initramfs' (compressed cpio archives) for
194 your system. But for those that want total control, you can easily create your
195 own initramfs as well.
196 </p>
197
198 <p>
199 Once created, you will need to adjust the bootloader configuration to tell it
200 that an initramfs is to be used. For instance, if the initramfs file is stored
201 as <path>/boot/initramfs-3.2.2-gentoo-r5</path>, then the configuration in
202 <path>/boot/grub/grub.conf</path> could look like so:
203 </p>
204
205 <pre caption="Example entry in grub.conf for booting with an initramfs">
206 title Gentoo Linux 3.2.2-r5
207 root (hd0,0)
208 kernel /boot/kernel-3.2.2-gentoo-r5
209 initrd /boot/initramfs-3.2.2-gentoo-r5
210 </pre>
211
212 </body>
213 </section>
214 <section id="genkernel">
215 <title>Using genkernel</title>
216 <body>
217
218 <p>
219 Gentoo's kernel building utility, <c>genkernel</c>, can be used to generate an
220 initramfs, even if you didn't use <c>genkernel</c> to configure and build your
221 kernel.
222 </p>
223
224 <p>
225 To use <c>genkernel</c> for generating an initramfs, it is recommended that you
226 include all necessary drivers and code that is needed to mount your
227 <path>/</path> and <path>/usr</path> file systems in the kernel (and not as
228 modules). Then, call <c>genkernel</c> as follows:
229 </p>
230
231 <pre caption="Running genkernel to setup an initramfs">
232 # <i>genkernel --install --no-ramdisk-modules initramfs</i>
233 </pre>
234
235 <p>
236 Depending on your system, you might want to add one or more of the following
237 options:
238 </p>
239
240 <table>
241 <tr>
242 <th>Option</th>
243 <th>Description</th>
244 </tr>
245 <tr>
246 <ti>--disklabel</ti>
247 <ti>Add support for <c>LABEL=</c> settings in your <path>/etc/fstab</path></ti>
248 </tr>
249 <tr>
250 <ti>--dmraid</ti>
251 <ti>Add support for fake hardware RAID</ti>
252 </tr>
253 <tr>
254 <ti>--firmware</ti>
255 <ti>Add in firmware code found on the system</ti>
256 </tr>
257 <tr>
258 <ti>--gpg</ti>
259 <ti>Add in GnuPG support</ti>
260 </tr>
261 <tr>
262 <ti>--iscsi</ti>
263 <ti>Add support for iSCSI</ti>
264 </tr>
265 <tr>
266 <ti>--luks</ti>
267 <ti>Add support for luks encryption containers</ti>
268 </tr>
269 <tr>
270 <ti>--lvm</ti>
271 <ti>Add support for LVM</ti>
272 </tr>
273 <tr>
274 <ti>--mdadm</ti>
275 <ti>Add support for software RAID</ti>
276 </tr>
277 <tr>
278 <ti>--multipath</ti>
279 <ti>Add support for multiple I/O access towards a SAN</ti>
280 </tr>
281 <tr>
282 <ti>--zfs</ti>
283 <ti>Add support for ZFS</ti>
284 </tr>
285 </table>
286
287 <p>
288 When finished, the resulting initramfs file will be stored in your
289 <path>/boot</path>.
290 </p>
291
292 </body>
293 </section>
294 <section id="dracut">
295 <title>Using dracut</title>
296 <body>
297
298 <warn>
299 At the time of writing, dracut is not marked stable yet, so you might need to
300 unmask it before continuing.
301 </warn>
302
303 <p>
304 The <c>dracut</c> utility is created for the sole purpose of managing initramfs
305 files. It uses a highly modular approach on which support you want to include
306 and which not.
307 </p>
308
309 <p>
310 When you install <c>dracut</c>, you will need to take care to include support
311 for the correct <c>DRACUT_MODULES</c>. This is a variable you can set in
312 <path>/etc/portage/make.conf</path> to include support for specific setups:
313 </p>
314
315 <pre caption="Preparing to install dracut">
316 DRACUT_MODULES="dmraid lvm syslog -biosdevname -btrfs -caps -crypt -crypt-gpg
317 -dmsquash-live -gensplash -iscsi -livenet -mdraid -multipath -nbd -nfs -plymouth
318 -ssh-client"
319 </pre>
320
321 <p>
322 It is adviseable to set (or unset) those modules you need (and don't need).
323 Afterwards, <c>emerge dracut</c> to install the utility on your system.
324 </p>
325
326 <p>
327 The next step is to configure <c>dracut</c> by editing
328 <path>/etc/dracut.conf</path>. In the configuration file, which is well
329 commented, you can add in support for specific modules where needed.
330 </p>
331
332 <p>
333 Once configured, create an initramfs by calling <c>dracut</c> as follows:
334 </p>
335
336 <pre caption="Calling dracut to generate an initramfs">
337 # <i>dracut</i>
338 </pre>
339
340 <p>
341 The resulting image supports generic system boots based on the configuration in
342 <path>/etc/dracut.conf</path>. You can also opt to generate an initramfs
343 specifically tailored to your system (in which <c>dracut</c> tries to detect the
344 needed tools, drivers, etc. from your existing system). If you know that the
345 needed support (code and drivers) is built in in your kernel (and not as
346 module), then you can even add in <c>--no-kernel</c>:
347 </p>
348
349 <pre caption="Allowing dracut to generate a host-specific initramfs">
350 # <i>dracut --host-only --no-kernel</i>
351 </pre>
352
353 <p>
354 For more information, check out the <c>dracut</c> and <c>dracut.cmdline</c>
355 manual pages.
356 </p>
357
358 </body>
359 </section>
360 </chapter>
361
362 <chapter>
363 <title>Additional resources</title>
364 <section>
365 <title>Gentoo-specific</title>
366 <body>
367
368 <ul>
369 <li>
370 <uri link="http://en.gentoo-wiki.com/wiki/Initramfs">Initramfs</uri> on
371 Gentoo-wiki.com
372 </li>
373 <li>
374 <uri link="http://wiki.gentoo.org/wiki/Initramfs">Initramfs</uri> on the
375 official Gentoo Wiki
376 </li>
377 <li>
378 <uri link="http://wiki.gentoo.org/wiki/Dracut">Dracut</uri> on the official
379 Gentoo Wiki
380 </li>
381 </ul>
382
383 </body>
384 </section>
385 <section>
386 <title>General resources</title>
387 <body>
388
389 <ul>
390 <li>
391 <uri
392 link="https://www.kernel.org/doc/Documentation/filesystems/ramfs-rootfs-initramfs.txt">ramfs-rootfs-initramfs.txt</uri>
393 within the Linux kernel documentation
394 </li>
395 </ul>
396
397 </body>
398 </section>
399 </chapter>
400
401 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20