/[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.17 - (hide annotations) (download) (as text)
Fri Jun 22 07:01:11 2007 UTC (7 years, 3 months ago) by nightmorph
Branch: MAIN
Changes since 1.16: +16 -3 lines
File MIME type: application/xml
added a better way of upgrading one's kernel that avoids the problems of oldconfig, thanks to mark_alec for addressing the section on IRC

1 swift 1.1 <?xml version="1.0" encoding="UTF-8"?>
2 nightmorph 1.17 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/kernel-upgrade.xml,v 1.16 2006/07/23 12:27:14 neysx Exp $ -->
3 swift 1.1
4     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5 neysx 1.3 <guide link="/doc/en/kernel-upgrade.xml">
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 nightmorph 1.17 <version>0.6</version>
21     <date>2007-06-22</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     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 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 neysx 1.3 [ebuild NS ] sys-kernel/gentoo-sources-2.6.9-r2 [2.6.8-r5]
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     The kernel sources will then be installed into a subdirectory of
108 swift 1.4 <path>/usr/src</path>. In the above example, the new kernel sources will be
109 swift 1.1 installed at <path>/usr/src/linux-2.6.9-gentoo-r2</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 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     in <path>/etc/make.conf</path>.
130 swift 1.1 </p>
131    
132 neysx 1.8 <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 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     [1] linux-2.6.9-gentoo-r1
148     [2] linux-2.6.9-gentoo-r2
149     <comment>(Select the correct kernel)</comment>
150     # <i>eselect kernel set 1</i>
151     </pre>
152    
153     <p>
154 neysx 1.8 If you really want to do it yourself, the following example shows you how to
155     make the link point to <path>linux-2.6.9-gentoo-r2</path>:
156     </p>
157    
158     <pre caption="Updating the /usr/src/linux softlink manually">
159 swift 1.1 # <i>cd /usr/src</i>
160 swift 1.2 # <i>ln -sfn linux-2.6.9-gentoo-r2 linux</i>
161 swift 1.1 </pre>
162    
163     </body>
164     </section>
165     </chapter>
166    
167     <chapter id="install">
168     <title>Configuring, compiling and installing the new kernel</title>
169     <section>
170     <body>
171    
172     <p>
173     For either of these options, you should refer to the instructions given in the
174 neysx 1.16 <uri link="/doc/en/handbook/">Gentoo Handbook</uri> relating to <e>Configuring
175     the Kernel</e> and <e>Configuring the Bootloader</e>. Below is an outline of
176     the required actions:
177 swift 1.1 </p>
178    
179     </body>
180     </section>
181     <section>
182     <title>Option 1: Automatic kernel setup with Genkernel</title>
183     <body>
184    
185     <p>
186     If you are a genkernel user, you just need to repeat the stages you went
187     through when installing your kernel for the first time.
188     </p>
189    
190     <p>
191     Simply run genkernel in the normal way:
192     </p>
193    
194     <pre caption="Invoking genkernel">
195     # <i>genkernel all</i>
196     </pre>
197    
198     <p>
199     You can also use extra parameters for other genkernel functionality. For
200     example, if you wish to configure some extra kernel options using
201 neysx 1.16 <c>menuconfig</c> and you wish genkernel to automatically update your grub boot
202     loader configuration, then invoke genkernel as follows:
203 swift 1.1 </p>
204    
205     <pre caption="Invoking genkernel with some common arguments">
206     # <i>genkernel --menuconfig --bootloader=grub all</i>
207     </pre>
208    
209     <p>
210 neysx 1.16 For more info, follow the <uri link="/doc/en/genkernel.xml">Gentoo Linux
211     Genkernel Guide</uri>, or refer to the <uri link="/doc/en/handbook/">Gentoo
212 swift 1.4 Handbook</uri>. Many of the options can be set in the configuration file for
213 swift 1.6 <c>genkernel</c>, <path>/etc/genkernel.conf</path>.
214 swift 1.1 </p>
215    
216     </body>
217     </section>
218     <section>
219     <title>Option 2: Manual configuration</title>
220     <body>
221    
222     <p>
223     To begin, open the <c>menuconfig</c> utility in the kernel source tree:
224     </p>
225    
226     <pre caption="Invoking menuconfig">
227     # <i>cd /usr/src/linux</i>
228     # <i>make menuconfig</i>
229     </pre>
230    
231     <p>
232 swift 1.4 Select the options required for your hardware and operating environment. For
233     additional information on kernel configuration, refer to the chapter entitled
234     <e>Configuring the Kernel</e> of the <uri
235     link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>.
236 swift 1.1 </p>
237    
238     <p>
239     Next, compile your kernel and copy it over to your boot partition. Again,
240 swift 1.4 follow the <uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>
241     instructions outlined in the chapter on <e>Configuring the Bootloader</e>. If
242     <path>/boot</path> is a separate partition, ensure it is mounted before copying
243     the compiled kernel to this directory! Failing to do so would keep you from
244     booting the system with your new kernel.
245 swift 1.1 </p>
246    
247     <pre caption="Compiling and installing the new kernel">
248     # <i>make &amp;&amp; make modules_install</i>
249     # <i>mount /boot</i>
250     # <i>cp arch/i386/boot/bzImage /boot/bzImage-2.6.9-gentoo-r2</i>
251     </pre>
252    
253     <p>
254 swift 1.5 Finally, you should update your boot loader configuration, adding an entry for
255     the new kernel (don't delete the old one just yet!) and unmount the
256 swift 1.4 <path>/boot</path> partition. Again, refer to the
257     <uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>
258     for detailed instructions on this procedure.
259 swift 1.1 </p>
260    
261     </body>
262     </section>
263     </chapter>
264    
265     <chapter>
266     <title>Reinstalling external modules</title>
267     <section>
268     <body>
269    
270     <p>
271     If you use any kernel modules that are not included in the kernel source tree
272 neysx 1.13 but are provided elsewhere in Portage (e.g. ALSA drivers and NVIDIA or ATI
273     graphics drivers), then you must reinstall these after upgrading the kernel.
274     This is as simple as re-merging the packages involved. For more information,
275     refer to the chapter on <e>Configuring the Kernel</e> in the <uri
276 nightmorph 1.14 link="/doc/en/handbook/">Gentoo Handbook</uri>.
277 swift 1.1 </p>
278    
279 swift 1.11 <p>
280     We provide you with an easy tool (<c>sys-kernel/module-rebuild</c>) which
281 nightmorph 1.14 rebuilds all the kernel modules you have installed using separate ebuilds for
282     the kernel at <path>/usr/src/linux</path>. Its use is straightforward. After
283     emerging it, simply run <c>module-rebuild populate</c> to populate the
284     database with a list of packages that will need to be rebuilt after upgrading
285     the kernel. Once you have finished upgrading or recompiling your kernel, run
286     <c>module-rebuild rebuild</c> to rebuild the drivers for your new kernel.
287 neysx 1.13 </p>
288    
289     <p>
290     For more information, run <c>module-rebuild</c> without any options to see a
291     list of commands that can be passed to the utility.
292 swift 1.11 </p>
293    
294 swift 1.1 </body>
295     </section>
296     </chapter>
297    
298     <chapter>
299     <title>Rebooting into the new kernel</title>
300     <section>
301     <body>
302    
303     <p>
304     Next, close all applications and reboot your system. If you followed the above
305 swift 1.5 instructions correctly, the boot loader menu should include an entry for the
306 swift 1.4 new kernel. Select the new kernel and let the system boot.
307 swift 1.1 </p>
308    
309     <p>
310 swift 1.4 Hopefully, your system successfully boots with the new kernel, and you can log
311     in to resume whatever you were doing. If this is the case, then the upgrade is
312     complete.
313 swift 1.1 </p>
314 neysx 1.13
315 swift 1.1 <p>
316 swift 1.4 If you made a mistake and the system fails to boot with the new kernel, reboot
317 swift 1.5 the system and select the entry from the boot loader that corresponds to the
318 swift 1.4 last known working kernel. You can then restart from the <uri link="#install">
319     Configuring, compiling, and installing the new kernel</uri> stage -- making
320     the appropriate changes to correct your mistake. In some cases, you might not
321     even need to reboot to do this (e.g. you missed a driver for an audio device,
322 swift 1.5 Ethernet adapter, etc.)
323 swift 1.1 </p>
324    
325     </body>
326     </section>
327     </chapter>
328    
329     <chapter>
330     <title>Running multiple kernels</title>
331     <section>
332     <body>
333    
334     <p>
335     You may have noticed, that when installing the sources for your newer kernel,
336 swift 1.4 the sources for your existing kernel were not removed. This is by design -- it
337 swift 1.1 allows you to easily switch between running different kernels.
338     </p>
339    
340     <p>
341     Switching between multiple kernels is as simple as leaving the kernel sources
342     under <path>/usr/src/</path> and leaving the <path>bzImage</path> binaries on
343 swift 1.5 your <path>/boot</path> partition (referenced by entries in your boot loader
344     configuration). Every time you boot up, you will be presented with a choice of
345     which kernel to boot into.
346 swift 1.1 </p>
347    
348     </body>
349     </section>
350     </chapter>
351    
352     <chapter>
353     <title>Removing older kernels</title>
354     <section>
355     <body>
356    
357     <p>
358     Continuing on from the last section, you may be happy with your new kernel and
359     not have any need to keep older kernel versions around. To easily remove all
360     sources for a particular kernel except for the newest one, you can take
361 swift 1.4 advantage of the <e>prune</e> option available through <c>emerge</c>. Continuing
362     the example using <c>gentoo-sources</c>:
363 swift 1.1 </p>
364    
365     <pre caption="Pruning old versions">
366 neysx 1.3 # <i>emerge -P gentoo-sources</i>
367 swift 1.1 </pre>
368    
369     <p>
370     In most cases, temporary files used during compilation will still remain under
371     the appropriate source directory under <path>/usr/src</path>. It is safe to
372     remove these using <c>rm</c>.
373     </p>
374    
375     <p>
376     You can also safely delete any modules that were used by this kernel. This can
377     be done by removing the appropriate directories under <path>/lib/modules/</path>
378     that relate to the kernel versions you are removing. Be careful not to delete
379     modules belonging to kernels that you still use!
380     </p>
381    
382     <p>
383     Finally, you can mount your <path>/boot</path> partition and remove the
384 jkt 1.10 <path>bzImage</path> file(s) for the kernel(s) you are pruning. You should also
385     edit your boot loader configuration so that it no longer references such
386     kernel(s).
387 swift 1.1 </p>
388    
389     </body>
390     </section>
391     </chapter>
392    
393     <chapter>
394 neysx 1.3 <title>Advanced: Using your old kernel .config to configure a new one</title>
395     <section>
396     <body>
397    
398     <p>
399     It is sometimes possible to save time by re-using the configuration file from
400     your old kernel when configuring the new one. Note that this is generally
401 swift 1.4 unsafe -- too many changes between every kernel release for this to be a
402 neysx 1.3 reliable upgrade path.
403     </p>
404    
405     <p>
406     The only situation where this is appropriate is when upgrading from one Gentoo
407     kernel revision to another. For example, the changes made between
408     <c>gentoo-sources-2.6.9-r1</c> and <c>gentoo-sources-2.6.9-r2</c> will be very
409     small, so it is usually OK to use the following method. However, it is not
410     appropriate to use it in the example used throughout this document: upgrading
411     from 2.6.8 to 2.6.9. Too many changes between the official releases, and the
412     method described below does not display enough context to the user, often
413     resulting in the user running into problems because they disabled options that
414     they really didn't want to.
415     </p>
416    
417     <p>
418 neysx 1.16 To reuse your old <path>.config</path>, you simply need to copy it over and
419     then run <c>make oldconfig</c>. In the following example, we take the
420     configuration from <c>gentoo-sources-2.6.9-r1</c> and import it into
421 neysx 1.3 <c>gentoo-sources-2.6.9-r2</c>.
422     </p>
423    
424     <pre caption="Reusing your old config">
425     # <i>cd /usr/src/linux-2.6.9-gentoo-r2</i>
426     # <i>cp ../linux-2.6.9-gentoo-r1/.config .</i>
427     # <i>make oldconfig</i>
428     </pre>
429    
430 neysx 1.16 <pre caption="Reusing your old config with genkernel">
431     # <i>cd /etc/kernels</i>
432     # <i>cp kernel-config-x86-2.6.9-gentoo-r1 kernel-config-x86-2.6.9-gentoo-r2</i>
433     # <i>genkernel all</i>
434     </pre>
435    
436 neysx 1.3 <p>
437     At this point, you may be asked to produce answers for configuration options
438     which have changed between the two versions. Once you have done that, you can
439     compile and install your kernel as normal, without having to go through the
440     <c>menuconfig</c> configuration process.
441     </p>
442    
443 nightmorph 1.17 <p>
444     A much safer upgrading method is to copy your config as previously shown, and
445     then simply run <c>make menuconfig</c>. This avoids the problems of <c>make
446     oldconfig</c> mentioned previously, as <c>make menuconfig</c> will load up your
447     previous configuration as much as possible into the menu. Now all you have to
448     do is go through each option and look for new sections, removals, and so on. By
449     using <c>menuconfig</c>, you gain context for all the new changes, and can
450     easily view the new choices and review help screens much easier. You can even
451     use this for upgrades such as 2.6.8 to 2.6.9; just make sure you read through
452     the options carefully. Once you've finished, compile and install your kernel as
453     normal.
454     </p>
455    
456 neysx 1.3 </body>
457     </section>
458     </chapter>
459    
460     <chapter>
461 swift 1.1 <title>Problems after a kernel upgrade?</title>
462     <section>
463     <body>
464    
465     <p>
466     With the rapid development of the Linux kernel, it is inevitable that some
467 neysx 1.3 changes made from one kernel release to another may cause some problems. If you
468     have any issues with the latest versions of <uri
469     link="/doc/en/gentoo-kernel.xml#doc_chap2"> Gentoo-supported kernels</uri> then
470     please do report the issues to us.
471 swift 1.1 </p>
472    
473     </body>
474     </section>
475     </chapter>
476    
477     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20