summaryrefslogtreecommitdiff
blob: b1cdd2817ec7b8f239a7821f433f46297a930893 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
<?xml version="1.0" encoding="UTF-8"?>
<!-- $Header: $ -->

<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide disclaimer="draft" link="/doc/en/grub-2-guide.xml" lang="en">
<title>GRUB 2 Guide</title>

<author title="Author">
    <mail link="matej@laitl.cz">Matěj Laitl</mail>
</author>

<author title="Editor">
    <mail link="mail@moritz-schlarb.de">Moritz Schlarb</mail>
</author>

<author title="Author">
    <mail link="scarabeus"/>
</author>

<abstract>
This guide shows you how to install and configure the GRUB 2 bootloader.
</abstract>

<!-- The  content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>1</version>
<date>2011-10-11</date>

<chapter>
<title>About</title>
<section>
<body>

<p>
GRUB 2 is next generation bootloader that brings many long awaited features
that were not available in GRUB Legacy (0.9*).
</p>

<p>
Some examples of new features:
</p>

<ul>
<li>Booting from boot partition stored on LVM</li>
<li>Booting from encrypted boot partition</li>
<li>Booting from UEFI</li>
<li>Support for native screen resolution and theming</li>
</ul>

</body>
</section>
</chapter>

<chapter>
<title>Installation</title>

<section>
<title>Optional: Creating Backup of Existing GRUB Legacy Installation</title>
<body>

<p>
Playing with bootloader always brings the danger of leaving your system in
unbootable state. Fortunately no data is lost in most cases and recovery is not
hard, but we recommend you to have a bootable CD, DVD or a USB flash disk with
Linux around (<uri link="http://www.gentoo.org/main/en/where.xml">Gentoo
LiveDVD</uri> or <uri link="http://www.sysresccd.org/">System Rescue CD</uri>
will do) and to backup your current bootloader setup. If your current
bootloader is GRUB legacy, following code sample may help you backing it up.
</p>

<pre caption="Backing up GRUB">
# <comment># copy grub modules and configuration</comment>
# <i>cp -a /boot/grub <keyword>/path/to/backup</keyword>/</i>
# <comment># backup the MBR and GRUB stage 1.5</comment>
# <i>dd if=<keyword>/dev/sda</keyword> of=<keyword>/path/to/backup</keyword>/first-sectors count=63</i>
</pre>

<note>
Replace <c>/dev/sda</c> with device node of the disk you boot from (this is
usually and the whole disk like <e>sda</e>, not a partition like sda1) and
<c>/path/to/backup</c> with path to your favourite backup medium.
</note>

<p>
When something goes wrong, you can restore previous grub installation by
booting some Linux live media and issuing following commands.
</p>

<pre caption="Restoring GRUB from backup">
# <comment># move old grub files out of the way</comment>
# <i>mv /boot/grub /boot/grub.nonfunctional</i>
# <comment># copy grub back to /boot</comment>
# <i>cp -a <keyword>/path/to/backup</keyword>/grub /boot/</i>
# <comment># replace MBR and next 62 sectors of sda with backed up copy (DANGEROUS!)</comment>
# <i>dd if=<keyword>/path/to/backup</keyword>/first-sectors of=<keyword>/dev/sda</keyword> count=63</i>
</pre>

<note>
Replace <c>/dev/sda</c> with device node of the disk you boot from and
<c>/path/to/backup</c> with path to the place where you've stored your backup.
</note>

<warn>
Writing directly to disk sectors (even those that are outside of partitions
in typical setup) is risky operation and will make your data <e>inaccessible</e>
if you changed your parititon layout between backup and restore. Other slower
and safer option would be chrooting into your Gentoo installation and
re-installing bootloader - you can use <uri link="/doc/en/handbook/">Gentoo
Handbook</uri> for that task.
</warn>

</body>
</section>

<section>
<title>Setting Useflags and Emerging</title>
<body>

<p>
By default, GRUB 2 tries to detect the desired platform during configure from your
toolchain and CPU. If you want support for other platforms or just don't want
to use the autodetection, you should use GRUB_PLATFORMS use expand. This variable
should be set in /etc/make.conf.
</p>

<p>Description of mostly used values for GRUB_PLATFORMS as of =sys-boot/grub-1.99:</p>

<ol>
<li>pc: normal BIOS pc</li>
<li>efi-64: EFI systems, their latest 64b version</li>
<li>coreboot: Coreboot replacement of BIOS</li>
<li>qemu: support for QEMU booting</li>
<li>yeelong: Support for MIPS loongson</li>

</ol>

<note>
Most users should just rely on platform detection or just use
GRUB_PLATFORMS="pc"
</note>

<warn>
One should be really careful with custom-cflags USE flag, as some CFLAGS can
easily render your system impossible to boot.
</warn>

<pre caption="Emerging GRUB 2">
# <i>emerge --ask --tree --verbose sys-boot/grub:2</i>
</pre>

</body>
</section>

<section>
<title>Variant A: Installing on a PC with BIOS and a MBR-Partitioned Disk</title>
<body>

<note>
This variant requires that you have "pc" in your GRUB_PLATFORMS. Your hardware
also needs to have a PC-BIOS or to emulate it.
</note>

<p>
Installation of GRUB 2 is similar to installation of GRUB Legacy.
</p>

<pre caption="Installing GRUB 2 on /dev/sda">
# <i>grub2-install --no-floppy <keyword>/dev/sda</keyword></i>
</pre>

<impo>
If you get ANY errors during this step do not reboot your computer,
but make sure it is fixed. Your computer won't boot if installation
failed.
</impo>

</body>
</section>

<section>
<title>Variant B: Installing GRUB 2 on Hardware That Supports EFI</title>
<body>

<p>
Some newer PCs (and all Intel Macs) come with
<uri link="http://en.wikipedia.org/wiki/Extensible_Firmware_Interface">EFI</uri>
(UEFI to be correct) as a replacement for legacy
and ageing BIOS firmware. EFI usually can emulate BIOS environment for OS, but
that also hides some unique features of EFI such as faster boot times, support
for GPT partition tables, etc. EFI firmware comes in two flavours - 32bit and
64bit and unless you have early Intel-based Mac with 32bit processor, your
firmware will be likely 64bit. Please note that unlike in user-space, <b>64bit
EFI firmware cannot run 32bit EFI bootloader.</b> This section will guide you
through installing GRUB 2 on such EFI-capable boards; it assumes that your
firmware adheres to UEFI 2.0 standard or newer (virtually every PC with EFI
support; Intel Macs do not entirely conform to the specification and may need
special treatment in some places)
</p>

<p>First thing you need is EFI-enabled Linux kernel with
<c>CONFIG_EFI</c> and <c>CONFIG_EFI_PARTITION</c> options enabled,
<c>CONFIG_FB_EFI</c> and <c>CONFIG_EFI_VARS</c> being optional but recommended.
Some platforms (namely many boards designed for <e>Intel Sandy Bridge</e>
processor generation) have <uri link="https://lkml.org/lkml/2011/5/19/377">
buggy EFI implementations</uri> and require at least kernel versions 2.6.39.1
or 3.0 in order to successfully boot.
</p>

<p>
One big difference between BIOS and EFI is that EFI is able to read partition
tables (both MBR and GPT formats should be supported) and to read from a specially
labelled FAT32 partition called <b>EFI System Partition</b>. During bootup, EFI
firmware can execute <e>EFI applications</e> stored in files in EFI System
Partition. One special EFI application is a bootloader. You may use the EFI
System Partition as your <c>/boot</c> partition if you don't mind limitations
of the FAT32 filesystem such as no support for symlinks and per-file owner and
permissions. The rest of this section assumes that you use <c>/boot</c> for
mounting EFI System Partition.
</p>

<p>
If you don't already have an EFI System Partition, let's create one. The procedure is
different for GPT and MBR-formatted disks. The partition does not need to be the first
one on the disk as in our examples. In case it is GPT-partitioned you'll need one
of the <c>gdisk</c> (CLI, sys-apps/gptfdisk), <c>parted</c> (CLI,
sys-block/parted) or <c>gparted</c> (GUI, sys-block/gparted) partitioning
tools; <c>fdisk</c>, <c>cfdisk</c> and <c>sfdisk</c> do not currently support
GPT. In the GPT case, create a partition at least 100 MiB in size with
<c>boot</c> flag (shown by (g)parted) or <c>EF00</c> Code (shown by gdisk).
</p>

<note>
Replace <c>/dev/sda</c> with the disk you want to have the EFI System Partition on and
<c>/dev/sda1</c> with the partition designated for it in all following samples.
</note>

<pre caption="EFI System Partion on GPT disk as shown by gdisk">
# <i>gdisk -l <keyword>/dev/sda</keyword></i>
<comment>(...)</comment>

Number  Start (sector)    End (sector)  Size       Code  Name
<ident>   1              34          411647   201.0 MiB   EF00  </ident>
</pre>

<pre caption="EFI System Partion on GPT disk as shown by parted">
# <i>parted -l</i>
<comment>(...)</comment>

Number  Start   End     Size    File system  Name  Flags
<ident> 1      17.4kB  211MB   211MB   fat32              boot</ident> <comment># the File system field may be empty</comment>
</pre>

<p>
In case the disk partition scheme is MBR (MS-DOS), the EFI System Partition should
have type <c>EF</c>. Create or re-type it, it should be at least 100 MiB large here, too.
</p>

<pre caption="EFI System Partion on MBR disk as shown by fdisk">
# <i>fdisk -l <keyword>/dev/sda</keyword></i>
<comment>(...)</comment>

   Device Boot      Start         End      Blocks   Id  System
<ident>/dev/sda1            2048      206847      102400   ef  EFI (FAT-12/16/32)</ident>
</pre>

<p>
Next, create a FAT32 filesystem on it if you already haven't done so. From now on,
procedure is the same for both GPT and MBR-formatted disks. Program
<c>mkdosfs</c> is from package <c>sys-fs/dosfstools</c>.
</p>

<pre caption="Creating FAT32 filesystem on EFI System Partition">
# <i>mkdosfs -F 32 -n efi-boot <keyword>/dev/sda1</keyword></i>
mkdosfs 3.0.9 (31 Jan 2010)
</pre>

<warn>
This command erases everything that was previously on <c>/dev/sda1</c>.
</warn>

<p>
The <c>-F 32</c> option tells mkdosfs to create FAT32 filesystem and <c>-n
efi-boot</c> option tells mkdosfs to set the partition label to <c>efi-boot</c>.
You may use arbitrary string up to 11 characters long as label or you may not
use it at all.
</p>

<p>
Next, you should add (or edit) an entry for the /boot partition into fstab and
mount it:
</p>

<pre caption="fstab entry and mounting of /boot">
# <i>cat /etc/fstab | grep efi-boot</i>
LABEL=efi-boot   /boot   vfat   defaults   0 2
# <i>mount /boot</i>
</pre>

<p>
Next, you should copy GRUB 2 modules into /boot where they can be found by
GRUB 2 during system boot:
</p>

<pre caption="Copying GRUB 2 modules into /boot (must be done everytime GRUB 2 is updated)">
# <i>mkdir -p /boot/grub2</i>
# <i>cp /lib/grub2/x86_64-efi/* /boot/grub2/</i>
</pre>

<p>
The most crucial step is creating the GRUB 2 image (EFI application). This is
accomplished using the <c>grub2-mkimage</c> command:
</p>

<pre caption="Creating GRUB 2 image (must be done everytime GRUB 2 is updated)">
# <i>grub2-mkimage -p /grub2 -o /boot/grub2/grub.efi -O x86_64-efi part_msdos part_gpt fat</i>
</pre>

<table>
<tr>
<th colspan="2">grub2-mkimage options</th>
<th>recommended value</th>
<th>notes</th>
</tr>

<tr>
<th>-p</th>
<ti>where should GRUB 2 look for its modules and config?</ti>
<ti><c>/grub2</c></ti>
<ti><b>relative to the root of the
partition where GRUB 2 EFI application is executed from</b></ti>
</tr>

<tr>
<th>-o</th>
<ti>where to store created image?</ti>
<ti><c>/boot/grub2/grub.efi</c></ti>
</tr>

<tr>
<th>-O</th>
<ti>platform to create image for</ti>
<ti><c>x86_64-efi</c></ti>
<ti>replace with <c>i386-efi</c> on 32bit systems (old Intel Macs)</ti>
</tr>

<tr>
<th>&lt;rest&gt;</th>
<ti>modules from /lib/grub2/[platform] to statically link in</ti>
<ti><c>part_msdos part_gpt fat</c></ti>
<ti>you only need to specify modules that are needed to be able to load other
modules from filesystem. You may drop <c>part_msdos</c> or <c>part_gpt</c> if
you don't use such partitions. You may add <c>normal</c> for a decent GRUB 2
shell available even in cases GRUB 2 cannot load other modules</ti>
</tr>
</table>

<p>When GRUB 2 image (EFI application) is made, you have to tell your firmware
to execute it upon boot. There are two ways to achieve this. If there is
already a default bootloader on your EFI System Partition that you don't want
to overwrite, you have to use the second. Otherwise you can use the first and
we encourage you to do so, since it is simpler.
</p>

<pre caption="Subvariant 1: copying grub.efi into default location for EFI bootloader  (must be done everytime GRUB 2 is updated)">
# <i>mkdir -p /boot/EFI/BOOT</i>
# <i>cp /boot/grub2/grub.efi /boot/EFI/BOOT/BOOTX64.EFI</i>
</pre>

<note>
EFI 2 specification says that the default bootloader location is <c>[EFI System
Partition]\EFI\BOOT\BOOTx64.EFI</c> for x86_64 hardware. (and
<c>...\BOOTIA32.EFI</c> on 32bit systems) While FAT32 filesystems should be
case-insesitive, it is recommended to use ALL-CAPS filenames in default
bootloader path in order to be compatible with all vfat mount options.
</note>

<pre caption="Subvariant 2: use efibootmgr to tell firmware what to execute on boot">
# <i>efibootmgr TODO TODO TODO</i>
</pre>

<warn>
Executing <c>efibootmgr</c> on Macs is known to brick (destroy) your firmware!
Various sources report that the <c>bless</c> command should be used instead.
</warn>

<p>
Last, you should create a GRUB 2 environment file (where GRUB 2 stores
persistent variables such number of the last booted item) as it is not created
automatically:
</p>

<pre caption="Creating GRUB 2 environment file">
# <i>grub2-editenv - create</i>
</pre>

<impo>
When you update GRUB 2, be sure to execute all commands that are marked as
such. Failure to do so would result in you using the previously installed GRUB
version.
</impo>

<p>
The last step is actually installing Linux kernel images into /boot, then you
can easily proceed with generating the configuration.
</p>

</body>
</section>

<section>
<title>Configuring GRUB 2</title>
<body>

<impo>
Gentoo installs all grub commands renamed to grub2. So if you read any other guide you
should replace all grub mentions with grub2 <i>(grub-mkconfig -> grub2-mkconfig)</i>.
</impo>

<p>
Compared to GRUB Legacy, GRUB 2 uses automatic generation to generate
all the required entries for you to boot. This is handled by <i>grub2-mkconfig</i>
command that probes your system for all the required data. Cooperating with
<i>sys-boot/os-prober</i>, it detects even other OSes on all disks.
</p>

<impo>
If you updated from GRUB Legacy then your <path>/boot/grub/menu.lst</path>
was converted to <path>/boot/grub2/grub.cfg</path> to ensure that your system
can boot even if you forget to generate the config. Never the less you should
take time and migrate the configuration to be automatically generated, because
next time GRUB 2 is installed it will use automatic generation and ignore
GRUB Legacy files.
</impo>

<pre caption="Generating the GRUB 2 config">
# <i>grub2-mkconfig -o /boot/grub2/grub.cfg</i>
</pre>

<p>
Tweaking the options is to be done in the <path>/etc/default/grub</path> file.
Simple text file configuration with description of some default values.
All the options are described in grub2 info pages.
</p>

<note>
This file is created by Gentoo and if you find an interesting option not used
in there just open a bugreport (possibly with a patch).
</note>

<p>
Sometimes, if automatic detection of GRUB 2 does not suffice, the file <path>
/etc/grub.d/40_custom</path> should be used to store custom entries. Full
description how to configure such with examples can be found in grub2 info
pages.
</p>

<pre caption="Custom menu entry">
menuentry "My Shiny Gentoo Kernel" {
	set root=(hd0,1)
	search --no-floppy --fs-uuid --set &lt;UUID&gt;
	linux /boot/gentookernel-5.3.2-generic root=UUID=&lt;UUID&gt;
	initrd /boot/initrd.img-5.3.2
}
</pre>

<warn>
Remember to replace the <i>&lt;UUID&gt;</i> with your device UUID.
</warn>

</body>
</section>

<section>
<title>Configuring with LVM</title>
<body>

<p>
GRUB 2 itself detects the LVM correctly, with no aditional setup required.
</p>

<impo>
If you placed your root and boot partitions inside LVM make sure that disk
you plan to use as booting one has at least few MBs of space before first
partition, because GRUB 2 needs more space to store lvm loader. In other
words: If you install it with not enough space it will just break your
partition.
</impo>

</body>
</section>
</chapter>

</guide>