/[gentoo]/xml/htdocs/doc/en/kernel-upgrade.xml
Gentoo

Contents of /xml/htdocs/doc/en/kernel-upgrade.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.20 - (show annotations) (download) (as text)
Sun Sep 4 14:46:59 2011 UTC (2 years, 10 months ago) by swift
Branch: MAIN
Changes since 1.19: +35 -12 lines
File MIME type: application/xml
Bug #380539 - Inform users about /etc/conf.d/modules. Also update the versions in the guide to more recent examples

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/kernel-upgrade.xml,v 1.19 2011/05/29 00:39:18 nightmorph Exp $ -->
3
4 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5 <guide link="/doc/en/kernel-upgrade.xml">
6 <title>Gentoo Linux Kernel Upgrade Guide</title>
7 <author title="Author">
8 <mail link="dsd@gentoo.org">Daniel Drake</mail>
9 </author>
10
11 <abstract>
12 This document describes the process of upgrading your kernel from one release
13 to another.
14 </abstract>
15
16 <!-- The content of this document is licensed under the CC-BY-SA license -->
17 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
18 <license/>
19
20 <version>2</version>
21 <date>2011-09-04</date>
22
23 <chapter>
24 <title>Introduction</title>
25 <section>
26 <body>
27
28 <p>
29 The kernel is one of the few package classes in portage that requires some
30 manual intervention to complete the upgrade. Portage will download and
31 install the kernel source for you, but then it is up to you to step in and
32 compile the new kernel before any changes will take effect.
33 </p>
34
35 <p>
36 Although this guide is targeted at users upgrading from one kernel release
37 to another, it will also be useful for users migrating from one kernel
38 package to another.
39 </p>
40
41 <p>
42 <c>gentoo-sources</c> is used as an example in this document, however, the
43 instructions here also apply to the other packages present in our tree.
44 </p>
45
46 </body>
47 </section>
48 </chapter>
49
50 <chapter>
51 <title>Why upgrade the kernel?</title>
52 <section>
53 <body>
54
55 <p>
56 Generally, upgrading from one minor kernel release to the next won't bring any
57 major differences. There are several reasons to upgrade the kernel. One is to
58 take advantage of a specific new feature or driver; another is to be protected
59 against a security vulnerability, or just to maintain an up-to-date and healthy
60 system.
61 </p>
62
63 <p>
64 Even if you choose not to update to every new kernel revision, it is
65 recommended that you at least upgrade from time to time. It is strongly
66 recommended that you immediately upgrade to a new kernel if that new release
67 solves a security problem.
68 </p>
69
70 </body>
71 </section>
72 </chapter>
73
74 <chapter>
75 <title>Obtaining the newer sources through Portage</title>
76 <section>
77 <body>
78
79 <p>
80 You upgrade the kernel sources like you would upgrade any other package -
81 using the <c>emerge</c> utility. It will probably be the case that you want to
82 upgrade your kernel when you see the upgrade appearing on your world updates
83 list. For example:
84 </p>
85
86 <pre caption="New kernel sources appearing on update list">
87 # <i>emerge -Dup world</i>
88 Calculating dependencies ...done!
89 [ebuild NS ] sys-kernel/gentoo-sources-2.6.39-r3 [2.6.38-r6]
90 </pre>
91
92 <note>
93 The "NS" label in the above output means that the new kernel will be installed
94 in a New Slot, i.e. the sources of your old kernel will be kept around, until
95 you manually remove them.
96 </note>
97
98 <p>
99 You can then go ahead and install the update, e.g.:
100 </p>
101
102 <pre caption="Upgrading your kernel sources">
103 # <i>emerge -u gentoo-sources</i>
104 </pre>
105
106 <p>
107 The kernel sources will then be installed into a subdirectory of
108 <path>/usr/src</path>. In the above example, the new kernel sources will be
109 installed at <path>/usr/src/linux-2.6.39-gentoo-r3</path>.
110 </p>
111
112 </body>
113 </section>
114 </chapter>
115
116 <chapter>
117 <title>Updating the /usr/src/linux symbolic link</title>
118 <section>
119 <body>
120
121 <p>
122 Gentoo requires that the <path>/usr/src/linux</path> symbolic link points to
123 the sources of the kernel you are running.
124 </p>
125
126 <p>
127 Portage can update the symlink automatically when you emerge new kernel
128 sources. All you have to do is add the <c>symlink</c> flag to the USE variable
129 in <path>/etc/make.conf</path>.
130 </p>
131
132 <pre caption="Example of USE variable in /etc/make.conf">
133 <comment>(Add the symlink keyword)</comment>
134 USE="<i>symlink</i> x86 3dnow 3dnowex X aac aalib adns alsa apache2"
135 </pre>
136
137 <p>
138 Alternatively, you could use <c>app-admin/eselect</c> to modify the symlink.
139 </p>
140
141 <pre caption="Using eselect to symlink">
142 <comment>(Install eselect if you don't have it)</comment>
143 # <i>emerge eselect</i>
144 <comment>(See the list of available kernels)</comment>
145 # <i>eselect kernel list</i>
146 Available kernel symlink targets:
147 [1] linux-2.6.39-gentoo-r3
148 [2] linux-2.6.38-gentoo-r6 *
149 <comment>(Select the correct kernel)</comment>
150 # <i>eselect kernel set 1</i>
151 <comment>(Verify the kernel was symlinked)</comment>
152 # <i>eselect kernel list</i>
153 [1] linux-2.6.39-gentoo-r3 *
154 [2] linux-2.6.38-gentoo-r6
155 </pre>
156
157 <p>
158 If you really want to do it yourself, the following example shows you how to
159 make the link point to <path>linux-2.6.39-gentoo-r3</path>:
160 </p>
161
162 <pre caption="Updating the /usr/src/linux softlink manually">
163 # <i>cd /usr/src</i>
164 # <i>ln -sfn linux-2.6.39-gentoo-r3 linux</i>
165 </pre>
166
167 </body>
168 </section>
169 </chapter>
170
171 <chapter id="install">
172 <title>Configuring, compiling and installing the new kernel</title>
173 <section>
174 <body>
175
176 <p>
177 For either of these options, you should refer to the instructions given in the
178 <uri link="/doc/en/handbook/">Gentoo Handbook</uri> relating to <e>Configuring
179 the Kernel</e> and <e>Configuring the Bootloader</e>. Below is an outline of
180 the required actions:
181 </p>
182
183 </body>
184 </section>
185 <section>
186 <title>Option 1: Automatic kernel setup with Genkernel</title>
187 <body>
188
189 <p>
190 If you are a genkernel user, you just need to repeat the stages you went
191 through when installing your kernel for the first time.
192 </p>
193
194 <p>
195 Simply run genkernel in the normal way:
196 </p>
197
198 <pre caption="Invoking genkernel">
199 # <i>genkernel all</i>
200 </pre>
201
202 <p>
203 You can also use extra parameters for other genkernel functionality. For
204 example, if you wish to configure some extra kernel options using
205 <c>menuconfig</c> and you wish genkernel to automatically update your grub boot
206 loader configuration, then invoke genkernel as follows:
207 </p>
208
209 <pre caption="Invoking genkernel with some common arguments">
210 # <i>genkernel --menuconfig --bootloader=grub all</i>
211 </pre>
212
213 <p>
214 For more info, follow the <uri link="/doc/en/genkernel.xml">Gentoo Linux
215 Genkernel Guide</uri>, or refer to the <uri link="/doc/en/handbook/">Gentoo
216 Handbook</uri>. Many of the options can be set in the configuration file for
217 <c>genkernel</c>, <path>/etc/genkernel.conf</path>.
218 </p>
219
220 </body>
221 </section>
222 <section>
223 <title>Option 2: Manual configuration</title>
224 <body>
225
226 <p>
227 To begin, open the <c>menuconfig</c> utility in the kernel source tree:
228 </p>
229
230 <pre caption="Invoking menuconfig">
231 # <i>cd /usr/src/linux</i>
232 # <i>make menuconfig</i>
233 </pre>
234
235 <p>
236 Select the options required for your hardware and operating environment. For
237 additional information on kernel configuration, refer to the chapter entitled
238 <e>Configuring the Kernel</e> of the <uri
239 link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>.
240 </p>
241
242 <p>
243 Next, compile your kernel and copy it over to your boot partition. Again,
244 follow the <uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>
245 instructions outlined in the chapter on <e>Configuring the Bootloader</e>. If
246 <path>/boot</path> is a separate partition, ensure it is mounted before copying
247 the compiled kernel to this directory! Failing to do so would keep you from
248 booting the system with your new kernel.
249 </p>
250
251 <pre caption="Compiling and installing the new kernel">
252 # <i>make &amp;&amp; make modules_install</i>
253 # <i>mount /boot</i>
254 # <i>cp arch/i386/boot/bzImage /boot/bzImage-2.6.39-gentoo-r3</i>
255 </pre>
256
257 <p>
258 Finally, you should update your boot loader configuration, adding an entry for
259 the new kernel (don't delete the old one just yet!) and unmount the
260 <path>/boot</path> partition. Again, refer to the
261 <uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>
262 for detailed instructions on this procedure.
263 </p>
264
265 </body>
266 </section>
267 </chapter>
268
269 <chapter>
270 <title>Reinstalling external modules</title>
271 <section>
272 <body>
273
274 <p>
275 If you use any kernel modules that are not included in the kernel source tree
276 but are provided elsewhere in Portage (e.g. ALSA drivers and NVIDIA or ATI
277 graphics drivers), then you must reinstall these after upgrading the kernel.
278 This is as simple as re-merging the packages involved. For more information,
279 refer to the chapter on <e>Configuring the Kernel</e> in the <uri
280 link="/doc/en/handbook/">Gentoo Handbook</uri>.
281 </p>
282
283 <p>
284 We provide you with an easy tool (<c>sys-kernel/module-rebuild</c>) which
285 rebuilds all the kernel modules you have installed using separate ebuilds for
286 the kernel at <path>/usr/src/linux</path>. Its use is straightforward. After
287 emerging it, simply run <c>module-rebuild populate</c> to populate the
288 database with a list of packages that will need to be rebuilt after upgrading
289 the kernel. Once you have finished upgrading or recompiling your kernel, run
290 <c>module-rebuild rebuild</c> to rebuild the drivers for your new kernel.
291 </p>
292
293 <p>
294 For more information, run <c>module-rebuild</c> without any options to see a
295 list of commands that can be passed to the utility.
296 </p>
297
298 </body>
299 </section>
300 </chapter>
301
302 <chapter>
303 <title>Updating your module configuration</title>
304 <section>
305 <body>
306
307 <p>
308 If you have put specific module configuration entries in
309 <path>/etc/conf.d/modules</path>, then you might need to update the entries
310 accordingly.
311 </p>
312
313 <pre caption="Sample /etc/conf.d/modules file">
314 <comment># The following will only auto-load the ieee1394 module in 2.6.38-gentoo-r6 kernels</comment>
315 modules_2_6_38_gentoo_r6="ieee1394"
316
317 <comment># To support auto-loading on all possible versions, drop any reference to versions:</comment>
318 modules="ohci1394"
319 </pre>
320
321 </body>
322 </section>
323 </chapter>
324
325 <chapter>
326 <title>Rebooting into the new kernel</title>
327 <section>
328 <body>
329
330 <p>
331 Next, close all applications and reboot your system. If you followed the above
332 instructions correctly, the boot loader menu should include an entry for the
333 new kernel. Select the new kernel and let the system boot.
334 </p>
335
336 <p>
337 Hopefully, your system successfully boots with the new kernel, and you can log
338 in to resume whatever you were doing. If this is the case, then the upgrade is
339 complete.
340 </p>
341
342 <p>
343 If you made a mistake and the system fails to boot with the new kernel, reboot
344 the system and select the entry from the boot loader that corresponds to the
345 last known working kernel. You can then restart from the <uri link="#install">
346 Configuring, compiling, and installing the new kernel</uri> stage -- making
347 the appropriate changes to correct your mistake. In some cases, you might not
348 even need to reboot to do this (e.g. you missed a driver for an audio device,
349 Ethernet adapter, etc.)
350 </p>
351
352 </body>
353 </section>
354 </chapter>
355
356 <chapter>
357 <title>Running multiple kernels</title>
358 <section>
359 <body>
360
361 <p>
362 You may have noticed, that when installing the sources for your newer kernel,
363 the sources for your existing kernel were not removed. This is by design -- it
364 allows you to easily switch between running different kernels.
365 </p>
366
367 <p>
368 Switching between multiple kernels is as simple as leaving the kernel sources
369 under <path>/usr/src/</path> and leaving the <path>bzImage</path> binaries on
370 your <path>/boot</path> partition (referenced by entries in your boot loader
371 configuration). Every time you boot up, you will be presented with a choice of
372 which kernel to boot into.
373 </p>
374
375 </body>
376 </section>
377 </chapter>
378
379 <chapter>
380 <title>Removing older kernels</title>
381 <section>
382 <body>
383
384 <p>
385 Continuing on from the last section, you may be happy with your new kernel and
386 not have any need to keep older kernel versions around. To easily remove all
387 sources for a particular kernel except for the newest one, you can take
388 advantage of the <e>prune</e> option available through <c>emerge</c>. Continuing
389 the example using <c>gentoo-sources</c>:
390 </p>
391
392 <pre caption="Pruning old versions">
393 # <i>emerge -P gentoo-sources</i>
394 </pre>
395
396 <p>
397 In most cases, temporary files used during compilation will still remain under
398 the appropriate source directory under <path>/usr/src</path>. It is safe to
399 remove these using <c>rm</c>.
400 </p>
401
402 <p>
403 You can also safely delete any modules that were used by this kernel. This can
404 be done by removing the appropriate directories under <path>/lib/modules/</path>
405 that relate to the kernel versions you are removing. Be careful not to delete
406 modules belonging to kernels that you still use!
407 </p>
408
409 <p>
410 Finally, you can mount your <path>/boot</path> partition and remove the
411 <path>bzImage</path> file(s) for the kernel(s) you are pruning. You should also
412 edit your boot loader configuration so that it no longer references such
413 kernel(s).
414 </p>
415
416 </body>
417 </section>
418 </chapter>
419
420 <chapter>
421 <title>Advanced: Using your old kernel .config to configure a new one</title>
422 <section>
423 <body>
424
425 <p>
426 It is sometimes possible to save time by re-using the configuration file from
427 your old kernel when configuring the new one. Note that this is generally
428 unsafe -- too many changes between every kernel release for this to be a
429 reliable upgrade path.
430 </p>
431
432 <p>
433 The only situation where this is appropriate is when upgrading from one Gentoo
434 kernel revision to another. For example, the changes made between
435 <c>gentoo-sources-2.6.9-r1</c> and <c>gentoo-sources-2.6.9-r2</c> will be very
436 small, so it is usually OK to use the following method. However, it is not
437 appropriate to use it in the example used throughout this document: upgrading
438 from 2.6.8 to 2.6.9. Too many changes between the official releases, and the
439 method described below does not display enough context to the user, often
440 resulting in the user running into problems because they disabled options that
441 they really didn't want to.
442 </p>
443
444 <p>
445 To reuse your old <path>.config</path>, you simply need to copy it over and
446 then run <c>make oldconfig</c>. In the following example, we take the
447 configuration from <c>gentoo-sources-2.6.9-r1</c> and import it into
448 <c>gentoo-sources-2.6.9-r2</c>.
449 </p>
450
451 <pre caption="Reusing your old config">
452 # <i>cd /usr/src/linux-2.6.9-gentoo-r2</i>
453 # <i>cp ../linux-2.6.9-gentoo-r1/.config .</i>
454 # <i>make oldconfig</i>
455 </pre>
456
457 <pre caption="Reusing your old config with genkernel">
458 # <i>cd /etc/kernels</i>
459 # <i>cp kernel-config-x86-2.6.9-gentoo-r1 kernel-config-x86-2.6.9-gentoo-r2</i>
460 # <i>genkernel all</i>
461 </pre>
462
463 <p>
464 At this point, you may be asked to produce answers for configuration options
465 which have changed between the two versions. Once you have done that, you can
466 compile and install your kernel as normal, without having to go through the
467 <c>menuconfig</c> configuration process.
468 </p>
469
470 <p>
471 A much safer upgrading method is to copy your config as previously shown, and
472 then simply run <c>make menuconfig</c>. This avoids the problems of <c>make
473 oldconfig</c> mentioned previously, as <c>make menuconfig</c> will load up your
474 previous configuration as much as possible into the menu. Now all you have to
475 do is go through each option and look for new sections, removals, and so on. By
476 using <c>menuconfig</c>, you gain context for all the new changes, and can
477 easily view the new choices and review help screens much easier. You can even
478 use this for upgrades such as 2.6.8 to 2.6.9; just make sure you read through
479 the options carefully. Once you've finished, compile and install your kernel as
480 normal.
481 </p>
482
483 </body>
484 </section>
485 </chapter>
486
487 <chapter>
488 <title>Problems after a kernel upgrade?</title>
489 <section>
490 <body>
491
492 <p>
493 With the rapid development of the Linux kernel, it is inevitable that some
494 changes made from one kernel release to another may cause some problems. If you
495 have any issues with the latest versions of <uri
496 link="/doc/en/gentoo-kernel.xml#doc_chap2"> Gentoo-supported kernels</uri> then
497 please do report the issues to us.
498 </p>
499
500 </body>
501 </section>
502 </chapter>
503
504 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20