| 1 |
swift 12/07/13 18:06:52 |
| 2 |
|
| 3 |
Modified: metadoc.xml |
| 4 |
Added: grub2-migration.xml |
| 5 |
Log: |
| 6 |
Fix #316603 (part 1) - introduce grub2 migration guide |
| 7 |
|
| 8 |
Revision Changes Path |
| 9 |
1.240 xml/htdocs/doc/en/metadoc.xml |
| 10 |
|
| 11 |
file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/metadoc.xml?rev=1.240&view=markup |
| 12 |
plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/metadoc.xml?rev=1.240&content-type=text/plain |
| 13 |
diff : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/metadoc.xml?r1=1.239&r2=1.240 |
| 14 |
|
| 15 |
Index: metadoc.xml |
| 16 |
=================================================================== |
| 17 |
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v |
| 18 |
retrieving revision 1.239 |
| 19 |
retrieving revision 1.240 |
| 20 |
diff -u -r1.239 -r1.240 |
| 21 |
--- metadoc.xml 22 Apr 2012 03:37:37 -0000 1.239 |
| 22 |
+++ metadoc.xml 13 Jul 2012 18:06:52 -0000 1.240 |
| 23 |
@@ -1,8 +1,8 @@ |
| 24 |
<?xml version="1.0" encoding="UTF-8"?> |
| 25 |
<!DOCTYPE metadoc SYSTEM "/dtd/metadoc.dtd"> |
| 26 |
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v 1.239 2012/04/22 03:37:37 nightmorph Exp $ --> |
| 27 |
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/metadoc.xml,v 1.240 2012/07/13 18:06:52 swift Exp $ --> |
| 28 |
<metadoc lang="en"> |
| 29 |
- <version>1.161</version> |
| 30 |
+ <version>1.162</version> |
| 31 |
<members> |
| 32 |
<lead>nightmorph</lead> |
| 33 |
<member>cam</member> |
| 34 |
@@ -322,6 +322,7 @@ |
| 35 |
<file id="hpc-howto">/doc/en/hpc-howto.xml</file> |
| 36 |
<file id="gnap-userguide">/proj/en/base/embedded/gnap-userguide.xml</file> |
| 37 |
<file id="grub-error-guide">/doc/en/grub-error-guide.xml</file> |
| 38 |
+ <file id="grub2-migration">/doc/en/grub2-migration.xml</file> |
| 39 |
<file id="usb-guide">/doc/en/usb-guide.xml</file> |
| 40 |
<file id="liveusb">/doc/en/liveusb.xml</file> |
| 41 |
<file id="fluxbox-config">/doc/en/fluxbox-config.xml</file> |
| 42 |
@@ -994,6 +995,9 @@ |
| 43 |
<doc fileid="grub-error-guide"> |
| 44 |
<memberof>install_other</memberof> |
| 45 |
</doc> |
| 46 |
+ <doc fileid="grub2-migration"> |
| 47 |
+ <memberof>upgrade</memberof> |
| 48 |
+ </doc> |
| 49 |
<doc fileid="usb-guide"> |
| 50 |
<memberof>install_other</memberof> |
| 51 |
</doc> |
| 52 |
|
| 53 |
|
| 54 |
|
| 55 |
1.1 xml/htdocs/doc/en/grub2-migration.xml |
| 56 |
|
| 57 |
file : http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/grub2-migration.xml?rev=1.1&view=markup |
| 58 |
plain: http://sources.gentoo.org/viewvc.cgi/gentoo/xml/htdocs/doc/en/grub2-migration.xml?rev=1.1&content-type=text/plain |
| 59 |
|
| 60 |
Index: grub2-migration.xml |
| 61 |
=================================================================== |
| 62 |
<?xml version='1.0' encoding='UTF-8'?> |
| 63 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
| 64 |
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/grub2-migration.xml,v 1.1 2012/07/13 18:06:52 swift Exp $ --> |
| 65 |
|
| 66 |
<guide> |
| 67 |
<title>GRUB2 migration from GRUB Legacy</title> |
| 68 |
|
| 69 |
<author title="Author"> |
| 70 |
<mail link="cardoe"/> |
| 71 |
</author> |
| 72 |
|
| 73 |
<abstract> |
| 74 |
The goal of this guide is to provide you with a smooth migration from GRUB |
| 75 |
Legacy to GRUB2. |
| 76 |
</abstract> |
| 77 |
|
| 78 |
<!-- The content of this document is licensed under the CC-BY-SA license --> |
| 79 |
<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
| 80 |
<license/> |
| 81 |
|
| 82 |
<version>1</version> |
| 83 |
<date>2012-07-13</date> |
| 84 |
|
| 85 |
<chapter> |
| 86 |
<title>Background</title> |
| 87 |
<section> |
| 88 |
<title>What's Grub?</title> |
| 89 |
<body> |
| 90 |
|
| 91 |
<p> |
| 92 |
Grub is one of the most commonly found boot loaders in use on non-embedded |
| 93 |
Linux machines. The role of Grub is to facilitate the Linux kernel being loaded |
| 94 |
from your disk into memory and start executing the Linux kernel. |
| 95 |
</p> |
| 96 |
|
| 97 |
</body> |
| 98 |
</section> |
| 99 |
<section> |
| 100 |
<title>So Why Migrate?</title> |
| 101 |
<body> |
| 102 |
|
| 103 |
<p> |
| 104 |
Firstly, GRUB Legacy is no longer maintained and as such no longer receives |
| 105 |
updates. GRUB Legacy was created at a time when the developers felt safe in |
| 106 |
making several assumptions which no longer hold true today. For example, |
| 107 |
GRUB Legacy is unable to boot from disks larger than 2TB and assumes that |
| 108 |
newer filesystems wouldn't come to replace <path>/boot</path>. |
| 109 |
</p> |
| 110 |
|
| 111 |
<p> |
| 112 |
GRUB2 aims to be more robust, more portable, more powerful and is maintained |
| 113 |
with a cleaner code base. GRUB2 supports more hardware configurations, more |
| 114 |
filesystems and more drive layouts than its predecessor. |
| 115 |
</p> |
| 116 |
|
| 117 |
</body> |
| 118 |
</section> |
| 119 |
</chapter> |
| 120 |
|
| 121 |
<chapter> |
| 122 |
<title>Migration to GRUB2</title> |
| 123 |
<section> |
| 124 |
<body> |
| 125 |
|
| 126 |
<p> |
| 127 |
Migration to GRUB2 is fairly straightforward: it will be pulled in as part |
| 128 |
of your regular upgrade process by your package manager. If it is not pulled |
| 129 |
in automatically, you can always install <c>sys-boot/grub:2</c>. |
| 130 |
</p> |
| 131 |
|
| 132 |
</body> |
| 133 |
</section> |
| 134 |
<section id="boot_drive"> |
| 135 |
<title>Boot Drive</title> |
| 136 |
<body> |
| 137 |
|
| 138 |
<p> |
| 139 |
The first important part is to understand what your bootable drive is. For |
| 140 |
many people it will be <path>/dev/sda</path>. The easiest way to find this is |
| 141 |
to look at how your existing GRUB Legacy is setup by viewing |
| 142 |
<path>/boot/grub/grub.conf</path>. An example one is provided below. |
| 143 |
</p> |
| 144 |
|
| 145 |
<note> |
| 146 |
You must have your <path>/boot</path> mounted to be able to view these files. |
| 147 |
It should be as simple as <c>mount /boot</c> to mount <path>/boot</path>. |
| 148 |
</note> |
| 149 |
|
| 150 |
<pre caption="/boot/grub/grub.conf"> |
| 151 |
default 0 |
| 152 |
timeout 30 |
| 153 |
splashimage=(hd0,0)/boot/grub/splash.xpm.gz |
| 154 |
|
| 155 |
title Gentoo Linux 3.2.12 |
| 156 |
root (hd0,0) |
| 157 |
kernel /boot/kernel-3.2.12-gentoo root=/dev/sda3 quiet dolvm |
| 158 |
initrd /boot/initramfs-genkernel-x86_64-3.2.12-gentoo |
| 159 |
</pre> |
| 160 |
|
| 161 |
<p> |
| 162 |
Based on the above file we know that <c>(hd0)</c> is the boot drive but we |
| 163 |
must map this to a real device. To know this you must view |
| 164 |
<path>/boot/grub/device.map</path>. An example one is provided below. |
| 165 |
</p> |
| 166 |
|
| 167 |
<pre caption="/boot/grub/device.map"> |
| 168 |
(fd0) /dev/fd0 |
| 169 |
(hd0) /dev/sda |
| 170 |
(hd1) /dev/sdb |
| 171 |
</pre> |
| 172 |
|
| 173 |
<p> |
| 174 |
Based on the above file we know that <path>/dev/sda</path> is the boot drive. |
| 175 |
</p> |
| 176 |
|
| 177 |
</body> |
| 178 |
</section> |
| 179 |
<section id="grub_install"> |
| 180 |
<title>Installing and Configuring GRUB2</title> |
| 181 |
<body> |
| 182 |
|
| 183 |
<p> |
| 184 |
The next step is to install and configure GRUB2 on your <path>/boot</path> |
| 185 |
partition without removing GRUB Legacy from your MBR. The example below |
| 186 |
uses <path>/dev/sda</path> but you must replace it with your boot drive path. |
| 187 |
The first step installs the necessary GRUB2 files to <path>/boot/grub2</path>, |
| 188 |
while the second step scans your available kernels and generates a suitable |
| 189 |
config file to <path>/boot/grub2/grub.cfg</path>. |
| 190 |
</p> |
| 191 |
|
| 192 |
<pre caption="Installing and configuring GRUB2"> |
| 193 |
# <i>grub2-install --grub-setup=/bin/true /dev/sda</i> |
| 194 |
Installation finished. No error reported. |
| 195 |
# <i>grub2-mkconfig -o /boot/grub2/grub.cfg</i> |
| 196 |
Generating grub.cfg ... |
| 197 |
Found linux image: /boot/kernel-3.2.12-gentoo |
| 198 |
Found initrd image: /boot/initramfs-genkernel-x86_64-3.2.12-gentoo |
| 199 |
done |
| 200 |
</pre> |
| 201 |
|
| 202 |
<note> |
| 203 |
GRUB2 has strict naming requirements for kernels and initramfs images. A |
| 204 |
kernel must be named <c>kernel-${version}</c> while an initramfs |
| 205 |
must be named <c>initramfs-${version}</c>, |
| 206 |
<c>initramfs-genkernel-${version}</c>, |
| 207 |
<c>initramfs-genkernel-${arch}-${version}</c>, |
| 208 |
<c>initrd-${version}.img</c>, <c>initrd.img-${version}</c>, |
| 209 |
<c>initrd-${version}.gz</c>, or <c>initrd-${version}</c>. |
| 210 |
Together with ${version}, the filename must match a corresponding kernel |
| 211 |
that is available in <path>/boot</path>. |
| 212 |
</note> |
| 213 |
|
| 214 |
</body> |
| 215 |
</section> |
| 216 |
<section id="chainload"> |
| 217 |
<title>Chainloading GRUB2 from GRUB Legacy to test the setup</title> |
| 218 |
<body> |
| 219 |
|
| 220 |
<p> |
| 221 |
Because a broken GRUB configuration could mean an unbootable |
| 222 |
system, we want to test our GRUB2 configuration before making it permenant. |
| 223 |
To do this we will chainload GRUB2 from GRUB Legacy. This is done by adding |
| 224 |
a new section into <path>/boot/grub/grub.conf</path>. An example is shown |
| 225 |
below. |
| 226 |
</p> |
| 227 |
|
| 228 |
<note> |
| 229 |
Beaware that your root maybe different from <c>(hd0,0)</c> used in the |
| 230 |
example and make sure you reuse the same root value from your |
| 231 |
<path>/boot/grub/grub.conf</path>. |
| 232 |
</note> |
| 233 |
|
| 234 |
<pre caption="/boot/grub/grub.conf"> |
| 235 |
default 0 |
| 236 |
timeout 30 |
| 237 |
splashimage=(hd0,0)/boot/grub/splash.xpm.gz |
| 238 |
|
| 239 |
<i>title GRUB2 Chainload |
| 240 |
root (hd0,0) |
| 241 |
kernel /boot/grub2/i386-pc/core.img |
| 242 |
boot</i> |
| 243 |
|
| 244 |
title Gentoo Linux 3.2.12 |
| 245 |
root (hd0,0) |
| 246 |
kernel /boot/kernel-3.2.12-gentoo root=/dev/sda3 quiet dolvm |
| 247 |
initrd /boot/initramfs-genkernel-x86_64-3.2.12-gentoo |
| 248 |
</pre> |
| 249 |
|
| 250 |
<p> |
| 251 |
At this point you should reboot your machine and select the |
| 252 |
<c>GRUB2 Chainload</c> from the GRUB menu when your machine begins to boot. |
| 253 |
You will be presented with another GRUB menu which should advertise itself |
| 254 |
as GRUB 2.0.0 or higher at the top and show your available kernel(s) to boot. |
| 255 |
Should this not work, simply reboot your system and pick your normal boot |
| 256 |
option instead of <c>GRUB2 Chainload</c>. |
| 257 |
</p> |
| 258 |
|
| 259 |
</body> |
| 260 |
</section> |
| 261 |
<section id="replacement"> |
| 262 |
<title>Replacing and removing GRUB Legacy</title> |
| 263 |
<body> |
| 264 |
|
| 265 |
<p> |
| 266 |
At this point if everything worked successfully you can replace GRUB Legacy |
| 267 |
and remove it from your system. |
| 268 |
</p> |
| 269 |
|
| 270 |
<note> |
| 271 |
Since you've rebooted your system, you may need to mount <path>/boot</path> |
| 272 |
again. You should also take note to use your boot drive path instead of |
| 273 |
<path>/dev/sda</path>. |
| 274 |
</note> |
| 275 |
|
| 276 |
<pre caption="Replacing GRUB Legacy"> |
| 277 |
# <i>grub2-install /dev/sda</i> |
| 278 |
Installation finished. No error reported. |
| 279 |
# <i>rm -rf /boot/grub/</i> |
| 280 |
</pre> |
| 281 |
|
| 282 |
<p> |
| 283 |
At this point you can use your package manager to remove <c>sys-boot/grub:0</c>. |
| 284 |
The migration is complete. |
| 285 |
</p> |
| 286 |
|
| 287 |
</body> |
| 288 |
</section> |
| 289 |
</chapter> |
| 290 |
|
| 291 |
<chapter> |
| 292 |
<title>Maintaining GRUB2</title> |
| 293 |
<section> |
| 294 |
<body> |
| 295 |
|
| 296 |
<p> |
| 297 |
Whenever you install a new kernel, you must perform the next step so |
| 298 |
that your GRUB2 configuration recognizes the new kernel. |
| 299 |
</p> |
| 300 |
|
| 301 |
<note> |
| 302 |
You must have your <path>/boot</path> partition mounted for this step. |
| 303 |
</note> |
| 304 |
|
| 305 |
<pre caption="Installing a new kernel"> |
| 306 |
# <i>grub2-mkconfig -o /boot/grub2/grub.cfg</i> |
| 307 |
Generating grub.cfg ... |
| 308 |
Found linux image: /boot/kernel-3.3.8-gentoo |
| 309 |
Found initrd image: /boot/initramfs-genkernel-x86_64-3.3.8-gentoo |
| 310 |
Found linux image: /boot/kernel-3.2.12-gentoo |
| 311 |
Found initrd image: /boot/initramfs-genkernel-x86_64-3.2.12-gentoo |
| 312 |
done |
| 313 |
</pre> |
| 314 |
|
| 315 |
</body> |
| 316 |
</section> |
| 317 |
</chapter> |
| 318 |
|
| 319 |
<chapter> |
| 320 |
<title>FAQ / Known Problems / Gotchas</title> |
| 321 |
<section> |
| 322 |
<body> |
| 323 |
|
| 324 |
<p> |
| 325 |
Content to come. |
| 326 |
</p> |
| 327 |
|
| 328 |
</body> |
| 329 |
</section> |
| 330 |
</chapter> |
| 331 |
</guide> |
Archives