/[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.7 - (hide annotations) (download) (as text)
Wed May 25 17:17:27 2005 UTC (9 years, 1 month ago) by swift
Branch: MAIN
Changes since 1.6: +7 -3 lines
File MIME type: application/xml
#92635 - genkernel updates

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

  ViewVC Help
Powered by ViewVC 1.1.20