/[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.3 - (hide annotations) (download) (as text)
Wed Apr 6 14:36:19 2005 UTC (9 years, 5 months ago) by neysx
Branch: MAIN
Changes since 1.2: +67 -13 lines
File MIME type: application/xml
#77313: reuse .config from previous config

1 swift 1.1 <?xml version="1.0" encoding="UTF-8"?>
2 neysx 1.3 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/kernel-upgrade.xml,v 1.2 2004/12/06 10:07:29 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 neysx 1.3 <version>0.1.2</version>
21     <date>2005-04-06</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     Although this guide is targetted at users upgrading from one kernel release
37     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     <title>Why upgrade kernel?</title>
52     <section>
53     <body>
54    
55     <p>
56     Generally, upgrading from one minor kernel release to the next won't bring any
57     major differences. Reasons for upgrading kernel are generally either to take
58     advantage of a specific new feature or driver, to be protected against a
59     security vulnerability, or just to maintain an up-to-date and healthy system.
60     </p>
61    
62     <p>
63     Even if you choose not to update to every new kernel revision, it is
64     recommended that you at least upgrade from time to time. It is strongly
65     recommended that you immediately upgrade to a new kernel if that new release
66     solves a security problem.
67     </p>
68    
69     </body>
70     </section>
71     </chapter>
72    
73     <chapter>
74     <title>Obtaining the newer sources through Portage</title>
75     <section>
76     <body>
77    
78     <p>
79     You upgrade the kernel sources like you would upgrade any other package -
80     using the <c>emerge</c> utility. It will probably be the case that you want to
81     upgrade your kernel when you see the upgrade appearing on your world updates
82     list. For example:
83     </p>
84    
85     <pre caption="New kernel sources appearing on update list">
86     # <i>emerge -Dup world</i>
87     Calculating dependencies ...done!
88 neysx 1.3 [ebuild NS ] sys-kernel/gentoo-sources-2.6.9-r2 [2.6.8-r5]
89 swift 1.1 </pre>
90    
91 neysx 1.3 <note>
92     The "NS" label in the above output means that the new kernel will be installed
93     in a New Slot, i.e. the sources of your old kernel will be kept around, until
94     you manually remove them.
95     </note>
96    
97 swift 1.1 <p>
98     You can then go ahead and install the update, e.g.:
99     </p>
100    
101     <pre caption="Upgrading your kernel sources">
102 neysx 1.3 # <i>emerge -u gentoo-sources</i>
103 swift 1.1 </pre>
104    
105     <p>
106     The kernel sources will then be installed into a subdirectory of
107     <path>/usr/src</path>. In the above example, my new kernel sources will be
108     installed at <path>/usr/src/linux-2.6.9-gentoo-r2</path>.
109     </p>
110    
111     </body>
112     </section>
113     </chapter>
114    
115     <chapter>
116     <title>Updating the /usr/src/linux symbolic link</title>
117     <section>
118     <body>
119    
120     <p>
121     Gentoo requires you to maintain a symbolic link, located at
122     <path>/usr/src/linux</path>. This should point to the sources of the
123     kernel you are running.
124     </p>
125    
126     <p>
127     In this case, we need to update the symbolic link to point at the kernel
128     sources that we are about to upgrade to. Continuing our example:
129     </p>
130    
131     <pre caption="Updating the /usr/src/linux softlink">
132     # <i>cd /usr/src</i>
133 swift 1.2 # <i>ln -sfn linux-2.6.9-gentoo-r2 linux</i>
134 swift 1.1 </pre>
135    
136     </body>
137     </section>
138     </chapter>
139    
140     <chapter id="install">
141     <title>Configuring, compiling and installing the new kernel</title>
142     <section>
143     <body>
144    
145     <p>
146     For either of these options, you should refer to the instructions given in the
147     <uri link="http://www.gentoo.org/doc/en/handbook/index.xml">Gentoo
148     Handbook</uri> relating to <e>Configuring the Kernel</e> and <e>Configuring
149     the Bootloader</e>. A quick summary is provided here.
150     </p>
151    
152     </body>
153     </section>
154     <section>
155     <title>Option 1: Automatic kernel setup with Genkernel</title>
156     <body>
157    
158     <p>
159     If you are a genkernel user, you just need to repeat the stages you went
160     through when installing your kernel for the first time.
161     </p>
162    
163     <p>
164     Simply run genkernel in the normal way:
165     </p>
166    
167     <pre caption="Invoking genkernel">
168     # <i>genkernel all</i>
169     </pre>
170    
171     <p>
172     You can also use extra parameters for other genkernel functionality. For
173     example, if you wish to configure some extra kernel options using
174     <c>menuconfig</c> and you wish genkernel to automatically update your grub
175     bootloader config, then invoke genkernel as follows:
176     </p>
177    
178     <pre caption="Invoking genkernel with some common arguments">
179     # <i>genkernel --menuconfig --bootloader=grub all</i>
180     </pre>
181    
182     <p>
183     For more info, follow the
184     <uri link="http://www.gentoo.org/doc/en/genkernel.xml">Gentoo Linux Genkernel
185     Guide</uri>, or refer to the handbook.
186     </p>
187    
188     </body>
189     </section>
190     <section>
191     <title>Option 2: Manual configuration</title>
192     <body>
193    
194     <p>
195     To begin, open the <c>menuconfig</c> utility in the kernel source tree:
196     </p>
197    
198     <pre caption="Invoking menuconfig">
199     # <i>cd /usr/src/linux</i>
200     # <i>make menuconfig</i>
201     </pre>
202    
203     <p>
204     Select the options required for your hardware and operating environment. Refer
205     to the <e>Gentoo Handbook</e> for additional guidance on this.
206     </p>
207    
208     <p>
209     Next, compile your kernel and copy it over to your boot partition. Again,
210     follow the handbook instructions here, but don't forget to mount your /boot
211     partition first! In the initial installation, you would have already mounted
212     this at a much earlier stage.
213     </p>
214    
215     <pre caption="Compiling and installing the new kernel">
216     # <i>make &amp;&amp; make modules_install</i>
217     # <i>mount /boot</i>
218     # <i>cp arch/i386/boot/bzImage /boot/bzImage-2.6.9-gentoo-r2</i>
219     # <i>cp System.map /boot/System.map-2.6.9-gentoo-r2</i>
220     </pre>
221    
222     <p>
223     Finally, you should update your bootloader config, adding an entry for the
224     new kernel (don't delete the old one just yet!) and unmount the
225     <path>/boot</path> partition. Again, refer to the handbook for instructions
226     here.
227     </p>
228    
229     </body>
230     </section>
231     </chapter>
232    
233     <chapter>
234     <title>Reinstalling external modules</title>
235     <section>
236     <body>
237    
238     <p>
239     If you use any kernel modules that are not included in the kernel source tree
240     but are provided elsewhere in portage (e.g. Nvidia or ATI graphics drivers),
241     then you must reinstall these on every kernel upgrade. This is as simple as
242     re-merging the packages involved. Refer again to the
243     <uri link="http://www.gentoo.org/doc/en/handbook/index.xml">Gentoo
244     Handbook</uri> <e>Configuring the Kernel</e> chapter for more info here.
245     Re-merging these packages will ensure they build against the source tree at
246     <path>/usr/src/linux</path> - therefore they will actually being installed
247     for the kernel we just compiled.
248     </p>
249    
250     </body>
251     </section>
252     </chapter>
253    
254     <chapter>
255     <title>Rebooting into the new kernel</title>
256     <section>
257     <body>
258    
259     <p>
260     Next, close all applications and reboot your system. If you followed the above
261     instructions correctly, you will see an entry for your new kernel on your
262     bootloader. Select the new kernel and let the system boot.
263     </p>
264    
265     <p>
266     Hopefully, your system will boot without problem and you can log in and start
267     working as usual. If everything is working, then the upgrade is complete at
268     this stage.
269     </p>
270    
271     <p>
272     If you have made a mistake and your system will not boot into the new kernel,
273     then you can simply reboot and boot into your previous working kernel. You can
274     then restart from the <uri link="#install">Configuring, compiling, and
275     installing the new kernel</uri> stage - making the appropriate changes to
276     correct your mistake. In some cases (e.g. you just missed a network driver)
277     then you might not even need to reboot to do this.
278     </p>
279    
280     </body>
281     </section>
282     </chapter>
283    
284     <chapter>
285     <title>Running multiple kernels</title>
286     <section>
287     <body>
288    
289     <p>
290     You may have noticed, that when installing the sources for your newer kernel,
291     the sources for your existing kernel were not removed. This is by-design and
292     allows you to easily switch between running different kernels.
293     </p>
294    
295     <p>
296     Switching between multiple kernels is as simple as leaving the kernel sources
297     under <path>/usr/src/</path> and leaving the <path>bzImage</path> binaries on
298     your <path>/boot</path> partition (referenced by entries in your bootloader
299     config). Every time you boot up, you will be presented with a choice of which
300     kernel to boot into.
301     </p>
302    
303     </body>
304     </section>
305     </chapter>
306    
307     <chapter>
308     <title>Removing older kernels</title>
309     <section>
310     <body>
311    
312     <p>
313     Continuing on from the last section, you may be happy with your new kernel and
314     not have any need to keep older kernel versions around. To easily remove all
315     sources for a particular kernel except for the newest one, you can take
316     advantages of emerge's <e>prune</e> option. Continuing the example using
317 neysx 1.3 gentoo-sources:
318 swift 1.1 </p>
319    
320     <pre caption="Pruning old versions">
321 neysx 1.3 # <i>emerge -P gentoo-sources</i>
322 swift 1.1 </pre>
323    
324     <p>
325     In most cases, temporary files used during compilation will still remain under
326     the appropriate source directory under <path>/usr/src</path>. It is safe to
327     remove these using <c>rm</c>.
328     </p>
329    
330     <p>
331     You can also safely delete any modules that were used by this kernel. This can
332     be done by removing the appropriate directories under <path>/lib/modules/</path>
333     that relate to the kernel versions you are removing. Be careful not to delete
334     modules belonging to kernels that you still use!
335     </p>
336    
337     <p>
338     Finally, you can mount your <path>/boot</path> partition and remove the
339     <path>bzImage</path> and <path>System.map</path> files for the kernel(s)
340     you are pruning. You should also edit your bootloader config so that it
341     no longer references this kernel.
342     </p>
343    
344     </body>
345     </section>
346     </chapter>
347    
348     <chapter>
349 neysx 1.3 <title>Advanced: Using your old kernel .config to configure a new one</title>
350     <section>
351     <body>
352    
353     <p>
354     It is sometimes possible to save time by re-using the configuration file from
355     your old kernel when configuring the new one. Note that this is generally
356     unsafe - too many changes between every kernel release for this to be a
357     reliable upgrade path.
358     </p>
359    
360     <p>
361     The only situation where this is appropriate is when upgrading from one Gentoo
362     kernel revision to another. For example, the changes made between
363     <c>gentoo-sources-2.6.9-r1</c> and <c>gentoo-sources-2.6.9-r2</c> will be very
364     small, so it is usually OK to use the following method. However, it is not
365     appropriate to use it in the example used throughout this document: upgrading
366     from 2.6.8 to 2.6.9. Too many changes between the official releases, and the
367     method described below does not display enough context to the user, often
368     resulting in the user running into problems because they disabled options that
369     they really didn't want to.
370     </p>
371    
372     <p>
373     To reuse your old config, you simply need to copy it over and then run <c>make
374     oldconfig</c>. In the following example, we take the config from
375     <c>gentoo-sources-2.6.9-r1</c> and import it into
376     <c>gentoo-sources-2.6.9-r2</c>.
377     </p>
378    
379     <pre caption="Reusing your old config">
380     # <i>cd /usr/src/linux-2.6.9-gentoo-r2</i>
381     # <i>cp ../linux-2.6.9-gentoo-r1/.config .</i>
382     # <i>make oldconfig</i>
383     </pre>
384    
385     <p>
386     At this point, you may be asked to produce answers for configuration options
387     which have changed between the two versions. Once you have done that, you can
388     compile and install your kernel as normal, without having to go through the
389     <c>menuconfig</c> configuration process.
390     </p>
391    
392     </body>
393     </section>
394     </chapter>
395    
396     <chapter>
397 swift 1.1 <title>Problems after a kernel upgrade?</title>
398     <section>
399     <body>
400    
401     <p>
402     With the rapid development of the Linux kernel, it is inevitable that some
403 neysx 1.3 changes made from one kernel release to another may cause some problems. If you
404     have any issues with the latest versions of <uri
405     link="/doc/en/gentoo-kernel.xml#doc_chap2"> Gentoo-supported kernels</uri> then
406     please do report the issues to us.
407 swift 1.1 </p>
408    
409     </body>
410     </section>
411     </chapter>
412    
413     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20