/[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.25 - (hide annotations) (download) (as text)
Thu Aug 15 08:28:41 2013 UTC (15 months, 1 week ago) by swift
Branch: MAIN
Changes since 1.24: +6 -6 lines
File MIME type: application/xml
Fix bug #466456 - Use kernel-* for kernel image naming, also needed when using GRUB2

1 swift 1.1 <?xml version="1.0" encoding="UTF-8"?>
2 swift 1.25 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/kernel-upgrade.xml,v 1.24 2013/06/03 01:43:09 nightmorph Exp $ -->
3 swift 1.1
4     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5 swift 1.21 <guide>
6 swift 1.1 <title>Gentoo Linux Kernel Upgrade Guide</title>
7     <author title="Author">
8 neysx 1.12 <mail link="dsd@gentoo.org">Daniel Drake</mail>
9 swift 1.1 </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 jkt 1.9 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
18 swift 1.1 <license/>
19    
20 swift 1.25 <version>6</version>
21     <date>2013-08-15</date>
22 swift 1.1
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 swift 1.4 Although this guide is targeted at users upgrading from one kernel release
37 swift 1.1 to another, it will also be useful for users migrating from one kernel
38     package to another.
39     </p>
40    
41     <p>
42 neysx 1.3 <c>gentoo-sources</c> is used as an example in this document, however, the
43 swift 1.1 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 swift 1.4 <title>Why upgrade the kernel?</title>
52 swift 1.1 <section>
53     <body>
54    
55     <p>
56     Generally, upgrading from one minor kernel release to the next won't bring any
57 swift 1.4 major differences. There are several reasons to upgrade the kernel. One is to
58 swift 1.18 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 swift 1.4 system.
61 swift 1.1 </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 swift 1.20 [ebuild NS ] sys-kernel/gentoo-sources-2.6.39-r3 [2.6.38-r6]
90 swift 1.1 </pre>
91    
92 neysx 1.3 <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 swift 1.1 <p>
99     You can then go ahead and install the update, e.g.:
100     </p>
101    
102     <pre caption="Upgrading your kernel sources">
103 neysx 1.3 # <i>emerge -u gentoo-sources</i>
104 swift 1.1 </pre>
105    
106     <p>
107 swift 1.18 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 swift 1.20 installed at <path>/usr/src/linux-2.6.39-gentoo-r3</path>.
110 swift 1.1 </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 neysx 1.8 Gentoo requires that the <path>/usr/src/linux</path> symbolic link points to
123     the sources of the kernel you are running.
124 swift 1.1 </p>
125    
126     <p>
127 neysx 1.8 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 swift 1.22 in <path>/etc/portage/make.conf</path>.
130 swift 1.1 </p>
131    
132 swift 1.22 <pre caption="Example of USE variable in /etc/portage/make.conf">
133 neysx 1.8 <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 fox2mike 1.15 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 swift 1.20 [1] linux-2.6.39-gentoo-r3
148     [2] linux-2.6.38-gentoo-r6 *
149 fox2mike 1.15 <comment>(Select the correct kernel)</comment>
150     # <i>eselect kernel set 1</i>
151 nightmorph 1.19 <comment>(Verify the kernel was symlinked)</comment>
152     # <i>eselect kernel list</i>
153 swift 1.20 [1] linux-2.6.39-gentoo-r3 *
154     [2] linux-2.6.38-gentoo-r6
155 fox2mike 1.15 </pre>
156    
157     <p>
158 neysx 1.8 If you really want to do it yourself, the following example shows you how to
159 swift 1.20 make the link point to <path>linux-2.6.39-gentoo-r3</path>:
160 neysx 1.8 </p>
161    
162     <pre caption="Updating the /usr/src/linux softlink manually">
163 swift 1.1 # <i>cd /usr/src</i>
164 swift 1.20 # <i>ln -sfn linux-2.6.39-gentoo-r3 linux</i>
165 swift 1.1 </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 neysx 1.16 <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 swift 1.1 </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 neysx 1.16 <c>menuconfig</c> and you wish genkernel to automatically update your grub boot
206     loader configuration, then invoke genkernel as follows:
207 swift 1.1 </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 neysx 1.16 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 swift 1.4 Handbook</uri>. Many of the options can be set in the configuration file for
217 swift 1.23 <c>genkernel</c>, <path>/etc/genkernel.conf</path>. Also take a look at the <uri
218     link="/doc/en/initramfs-guide.xml">Gentoo Linux Initial RAM file system
219     guide</uri>.
220 swift 1.1 </p>
221    
222     </body>
223     </section>
224     <section>
225     <title>Option 2: Manual configuration</title>
226     <body>
227    
228     <p>
229     To begin, open the <c>menuconfig</c> utility in the kernel source tree:
230     </p>
231    
232     <pre caption="Invoking menuconfig">
233     # <i>cd /usr/src/linux</i>
234     # <i>make menuconfig</i>
235     </pre>
236    
237     <p>
238 swift 1.4 Select the options required for your hardware and operating environment. For
239     additional information on kernel configuration, refer to the chapter entitled
240     <e>Configuring the Kernel</e> of the <uri
241     link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>.
242 swift 1.1 </p>
243    
244     <p>
245     Next, compile your kernel and copy it over to your boot partition. Again,
246 swift 1.4 follow the <uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>
247     instructions outlined in the chapter on <e>Configuring the Bootloader</e>. If
248     <path>/boot</path> is a separate partition, ensure it is mounted before copying
249     the compiled kernel to this directory! Failing to do so would keep you from
250     booting the system with your new kernel.
251 swift 1.1 </p>
252    
253     <pre caption="Compiling and installing the new kernel">
254     # <i>make &amp;&amp; make modules_install</i>
255     # <i>mount /boot</i>
256 swift 1.25 # <i>cp arch/i386/boot/bzImage /boot/kernel-2.6.39-gentoo-r3</i>
257 swift 1.1 </pre>
258    
259     <p>
260 swift 1.18 Finally, you should update your boot loader configuration, adding an entry for
261 swift 1.5 the new kernel (don't delete the old one just yet!) and unmount the
262 swift 1.18 <path>/boot</path> partition. Again, refer to the
263 swift 1.4 <uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>
264     for detailed instructions on this procedure.
265 swift 1.1 </p>
266    
267     </body>
268     </section>
269     </chapter>
270    
271     <chapter>
272     <title>Reinstalling external modules</title>
273     <section>
274     <body>
275    
276     <p>
277     If you use any kernel modules that are not included in the kernel source tree
278 neysx 1.13 but are provided elsewhere in Portage (e.g. ALSA drivers and NVIDIA or ATI
279     graphics drivers), then you must reinstall these after upgrading the kernel.
280     This is as simple as re-merging the packages involved. For more information,
281     refer to the chapter on <e>Configuring the Kernel</e> in the <uri
282 nightmorph 1.14 link="/doc/en/handbook/">Gentoo Handbook</uri>.
283 swift 1.1 </p>
284    
285 swift 1.11 <p>
286 nightmorph 1.24 We provide you with a built-in Portage set (<c>@module-rebuild</c>) which
287     rebuilds all the kernel modules you have installed using separate ebuilds (such
288     as <c>app-laptop/tp_smapi</c>) for the kernel at <path>/usr/src/linux</path>.
289     Once you have finished upgrading or recompiling your kernel, run <c>emerge
290     @module-rebuild</c> to rebuild the drivers for your new kernel.
291 swift 1.11 </p>
292    
293 swift 1.1 </body>
294     </section>
295     </chapter>
296    
297     <chapter>
298 swift 1.20 <title>Updating your module configuration</title>
299     <section>
300     <body>
301    
302     <p>
303     If you have put specific module configuration entries in
304     <path>/etc/conf.d/modules</path>, then you might need to update the entries
305     accordingly.
306     </p>
307    
308     <pre caption="Sample /etc/conf.d/modules file">
309     <comment># The following will only auto-load the ieee1394 module in 2.6.38-gentoo-r6 kernels</comment>
310     modules_2_6_38_gentoo_r6="ieee1394"
311    
312     <comment># To support auto-loading on all possible versions, drop any reference to versions:</comment>
313     modules="ohci1394"
314     </pre>
315    
316     </body>
317     </section>
318     </chapter>
319    
320     <chapter>
321 swift 1.1 <title>Rebooting into the new kernel</title>
322     <section>
323     <body>
324    
325     <p>
326     Next, close all applications and reboot your system. If you followed the above
327 swift 1.5 instructions correctly, the boot loader menu should include an entry for the
328 swift 1.4 new kernel. Select the new kernel and let the system boot.
329 swift 1.1 </p>
330    
331     <p>
332 swift 1.4 Hopefully, your system successfully boots with the new kernel, and you can log
333     in to resume whatever you were doing. If this is the case, then the upgrade is
334     complete.
335 swift 1.1 </p>
336 neysx 1.13
337 swift 1.1 <p>
338 swift 1.18 If you made a mistake and the system fails to boot with the new kernel, reboot
339     the system and select the entry from the boot loader that corresponds to the
340 swift 1.4 last known working kernel. You can then restart from the <uri link="#install">
341 swift 1.18 Configuring, compiling, and installing the new kernel</uri> stage -- making
342     the appropriate changes to correct your mistake. In some cases, you might not
343     even need to reboot to do this (e.g. you missed a driver for an audio device,
344 swift 1.5 Ethernet adapter, etc.)
345 swift 1.1 </p>
346    
347     </body>
348     </section>
349     </chapter>
350    
351     <chapter>
352     <title>Running multiple kernels</title>
353     <section>
354     <body>
355    
356     <p>
357     You may have noticed, that when installing the sources for your newer kernel,
358 swift 1.4 the sources for your existing kernel were not removed. This is by design -- it
359 swift 1.1 allows you to easily switch between running different kernels.
360     </p>
361    
362     <p>
363     Switching between multiple kernels is as simple as leaving the kernel sources
364 swift 1.25 under <path>/usr/src/</path> and leaving the <path>kernel-*</path> binaries on
365 swift 1.18 your <path>/boot</path> partition (referenced by entries in your boot loader
366     configuration). Every time you boot up, you will be presented with a choice of
367 swift 1.5 which kernel to boot into.
368 swift 1.1 </p>
369    
370     </body>
371     </section>
372     </chapter>
373    
374     <chapter>
375     <title>Removing older kernels</title>
376     <section>
377     <body>
378    
379     <p>
380     Continuing on from the last section, you may be happy with your new kernel and
381     not have any need to keep older kernel versions around. To easily remove all
382     sources for a particular kernel except for the newest one, you can take
383 swift 1.4 advantage of the <e>prune</e> option available through <c>emerge</c>. Continuing
384     the example using <c>gentoo-sources</c>:
385 swift 1.1 </p>
386    
387     <pre caption="Pruning old versions">
388 neysx 1.3 # <i>emerge -P gentoo-sources</i>
389 swift 1.1 </pre>
390    
391     <p>
392     In most cases, temporary files used during compilation will still remain under
393 swift 1.18 the appropriate source directory under <path>/usr/src</path>. It is safe to
394 swift 1.1 remove these using <c>rm</c>.
395     </p>
396    
397     <p>
398     You can also safely delete any modules that were used by this kernel. This can
399     be done by removing the appropriate directories under <path>/lib/modules/</path>
400     that relate to the kernel versions you are removing. Be careful not to delete
401     modules belonging to kernels that you still use!
402     </p>
403    
404     <p>
405 swift 1.18 Finally, you can mount your <path>/boot</path> partition and remove the
406 swift 1.25 <path>kernel-*</path> file(s) for the kernel(s) you are pruning. You should also
407 jkt 1.10 edit your boot loader configuration so that it no longer references such
408     kernel(s).
409 swift 1.1 </p>
410    
411     </body>
412     </section>
413     </chapter>
414    
415     <chapter>
416 neysx 1.3 <title>Advanced: Using your old kernel .config to configure a new one</title>
417     <section>
418     <body>
419    
420     <p>
421     It is sometimes possible to save time by re-using the configuration file from
422     your old kernel when configuring the new one. Note that this is generally
423 swift 1.4 unsafe -- too many changes between every kernel release for this to be a
424 neysx 1.3 reliable upgrade path.
425     </p>
426    
427     <p>
428     The only situation where this is appropriate is when upgrading from one Gentoo
429     kernel revision to another. For example, the changes made between
430     <c>gentoo-sources-2.6.9-r1</c> and <c>gentoo-sources-2.6.9-r2</c> will be very
431     small, so it is usually OK to use the following method. However, it is not
432     appropriate to use it in the example used throughout this document: upgrading
433     from 2.6.8 to 2.6.9. Too many changes between the official releases, and the
434     method described below does not display enough context to the user, often
435     resulting in the user running into problems because they disabled options that
436     they really didn't want to.
437     </p>
438    
439     <p>
440 neysx 1.16 To reuse your old <path>.config</path>, you simply need to copy it over and
441     then run <c>make oldconfig</c>. In the following example, we take the
442     configuration from <c>gentoo-sources-2.6.9-r1</c> and import it into
443 neysx 1.3 <c>gentoo-sources-2.6.9-r2</c>.
444     </p>
445    
446     <pre caption="Reusing your old config">
447     # <i>cd /usr/src/linux-2.6.9-gentoo-r2</i>
448     # <i>cp ../linux-2.6.9-gentoo-r1/.config .</i>
449     # <i>make oldconfig</i>
450     </pre>
451    
452 neysx 1.16 <pre caption="Reusing your old config with genkernel">
453     # <i>cd /etc/kernels</i>
454     # <i>cp kernel-config-x86-2.6.9-gentoo-r1 kernel-config-x86-2.6.9-gentoo-r2</i>
455     # <i>genkernel all</i>
456     </pre>
457    
458 neysx 1.3 <p>
459     At this point, you may be asked to produce answers for configuration options
460     which have changed between the two versions. Once you have done that, you can
461     compile and install your kernel as normal, without having to go through the
462     <c>menuconfig</c> configuration process.
463     </p>
464    
465 nightmorph 1.17 <p>
466     A much safer upgrading method is to copy your config as previously shown, and
467     then simply run <c>make menuconfig</c>. This avoids the problems of <c>make
468     oldconfig</c> mentioned previously, as <c>make menuconfig</c> will load up your
469     previous configuration as much as possible into the menu. Now all you have to
470     do is go through each option and look for new sections, removals, and so on. By
471     using <c>menuconfig</c>, you gain context for all the new changes, and can
472     easily view the new choices and review help screens much easier. You can even
473     use this for upgrades such as 2.6.8 to 2.6.9; just make sure you read through
474     the options carefully. Once you've finished, compile and install your kernel as
475     normal.
476     </p>
477    
478 neysx 1.3 </body>
479     </section>
480     </chapter>
481    
482     <chapter>
483 swift 1.1 <title>Problems after a kernel upgrade?</title>
484     <section>
485     <body>
486    
487     <p>
488     With the rapid development of the Linux kernel, it is inevitable that some
489 neysx 1.3 changes made from one kernel release to another may cause some problems. If you
490     have any issues with the latest versions of <uri
491     link="/doc/en/gentoo-kernel.xml#doc_chap2"> Gentoo-supported kernels</uri> then
492     please do report the issues to us.
493 swift 1.1 </p>
494    
495     </body>
496     </section>
497     </chapter>
498    
499     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20