/[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.11 - (hide annotations) (download) (as text)
Tue Oct 11 03:48:06 2005 UTC (8 years, 9 months ago) by swift
Branch: MAIN
Changes since 1.10: +8 -3 lines
File MIME type: application/xml
#104877 - Mention module-rebuild

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

  ViewVC Help
Powered by ViewVC 1.1.20