/[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.27 - (hide annotations) (download) (as text)
Mon Dec 9 12:58:26 2013 UTC (9 months, 2 weeks ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.26: +3 -2 lines
File MIME type: application/xml
Kernel upgrade at https://wiki.gentoo.org/wiki/Kernel/Upgrade and https://wiki.gentoo.org/wiki/User:SwifT/Wikified_but_not_merged_documents/Kernel_Upgrade

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

  ViewVC Help
Powered by ViewVC 1.1.20