/[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.1 - (hide annotations) (download) (as text)
Tue Nov 2 09:36:23 2004 UTC (9 years, 9 months ago) by swift
Branch: MAIN
File MIME type: application/xml
Kernel Upgrade document, thanks to dsd@gentoo.org

1 swift 1.1 <?xml version="1.0" encoding="UTF-8"?>
2     <!-- $Header: $ -->
3    
4     <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5     <guide link="kernel-upgrade.xml">
6     <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     <version>0.1.0</version>
21     <date>November 1st, 2004</date>
22    
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     <c>gentoo-dev-sources</c> is used as an example in this document, however, the
43     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     [ebuild U ] sys-kernel/gentoo-dev-sources-2.6.9-r2 [2.6.8-r5]
89     </pre>
90    
91     <p>
92     You can then go ahead and install the update, e.g.:
93     </p>
94    
95     <pre caption="Upgrading your kernel sources">
96     # <i>emerge -u gentoo-dev-sources</i>
97     </pre>
98    
99     <p>
100     The kernel sources will then be installed into a subdirectory of
101     <path>/usr/src</path>. In the above example, my new kernel sources will be
102     installed at <path>/usr/src/linux-2.6.9-gentoo-r2</path>.
103     </p>
104    
105     </body>
106     </section>
107     </chapter>
108    
109     <chapter>
110     <title>Updating the /usr/src/linux symbolic link</title>
111     <section>
112     <body>
113    
114     <p>
115     Gentoo requires you to maintain a symbolic link, located at
116     <path>/usr/src/linux</path>. This should point to the sources of the
117     kernel you are running.
118     </p>
119    
120     <p>
121     In this case, we need to update the symbolic link to point at the kernel
122     sources that we are about to upgrade to. Continuing our example:
123     </p>
124    
125     <pre caption="Updating the /usr/src/linux softlink">
126     # <i>cd /usr/src</i>
127     # <i>ln -sf linux-2.6.9-gentoo-r2 linux</i>
128     </pre>
129    
130     </body>
131     </section>
132     </chapter>
133    
134     <chapter id="install">
135     <title>Configuring, compiling and installing the new kernel</title>
136     <section>
137     <body>
138    
139     <p>
140     For either of these options, you should refer to the instructions given in the
141     <uri link="http://www.gentoo.org/doc/en/handbook/index.xml">Gentoo
142     Handbook</uri> relating to <e>Configuring the Kernel</e> and <e>Configuring
143     the Bootloader</e>. A quick summary is provided here.
144     </p>
145    
146     </body>
147     </section>
148     <section>
149     <title>Option 1: Automatic kernel setup with Genkernel</title>
150     <body>
151    
152     <p>
153     If you are a genkernel user, you just need to repeat the stages you went
154     through when installing your kernel for the first time.
155     </p>
156    
157     <p>
158     Simply run genkernel in the normal way:
159     </p>
160    
161     <pre caption="Invoking genkernel">
162     # <i>genkernel all</i>
163     </pre>
164    
165     <p>
166     You can also use extra parameters for other genkernel functionality. For
167     example, if you wish to configure some extra kernel options using
168     <c>menuconfig</c> and you wish genkernel to automatically update your grub
169     bootloader config, then invoke genkernel as follows:
170     </p>
171    
172     <pre caption="Invoking genkernel with some common arguments">
173     # <i>genkernel --menuconfig --bootloader=grub all</i>
174     </pre>
175    
176     <p>
177     For more info, follow the
178     <uri link="http://www.gentoo.org/doc/en/genkernel.xml">Gentoo Linux Genkernel
179     Guide</uri>, or refer to the handbook.
180     </p>
181    
182     </body>
183     </section>
184     <section>
185     <title>Option 2: Manual configuration</title>
186     <body>
187    
188     <p>
189     To begin, open the <c>menuconfig</c> utility in the kernel source tree:
190     </p>
191    
192     <pre caption="Invoking menuconfig">
193     # <i>cd /usr/src/linux</i>
194     # <i>make menuconfig</i>
195     </pre>
196    
197     <p>
198     Select the options required for your hardware and operating environment. Refer
199     to the <e>Gentoo Handbook</e> for additional guidance on this.
200     </p>
201    
202     <p>
203     Next, compile your kernel and copy it over to your boot partition. Again,
204     follow the handbook instructions here, but don't forget to mount your /boot
205     partition first! In the initial installation, you would have already mounted
206     this at a much earlier stage.
207     </p>
208    
209     <pre caption="Compiling and installing the new kernel">
210     # <i>make &amp;&amp; make modules_install</i>
211     # <i>mount /boot</i>
212     # <i>cp arch/i386/boot/bzImage /boot/bzImage-2.6.9-gentoo-r2</i>
213     # <i>cp System.map /boot/System.map-2.6.9-gentoo-r2</i>
214     </pre>
215    
216     <p>
217     Finally, you should update your bootloader config, adding an entry for the
218     new kernel (don't delete the old one just yet!) and unmount the
219     <path>/boot</path> partition. Again, refer to the handbook for instructions
220     here.
221     </p>
222    
223     </body>
224     </section>
225     </chapter>
226    
227     <chapter>
228     <title>Reinstalling external modules</title>
229     <section>
230     <body>
231    
232     <p>
233     If you use any kernel modules that are not included in the kernel source tree
234     but are provided elsewhere in portage (e.g. Nvidia or ATI graphics drivers),
235     then you must reinstall these on every kernel upgrade. This is as simple as
236     re-merging the packages involved. Refer again to the
237     <uri link="http://www.gentoo.org/doc/en/handbook/index.xml">Gentoo
238     Handbook</uri> <e>Configuring the Kernel</e> chapter for more info here.
239     Re-merging these packages will ensure they build against the source tree at
240     <path>/usr/src/linux</path> - therefore they will actually being installed
241     for the kernel we just compiled.
242     </p>
243    
244     </body>
245     </section>
246     </chapter>
247    
248     <chapter>
249     <title>Rebooting into the new kernel</title>
250     <section>
251     <body>
252    
253     <p>
254     Next, close all applications and reboot your system. If you followed the above
255     instructions correctly, you will see an entry for your new kernel on your
256     bootloader. Select the new kernel and let the system boot.
257     </p>
258    
259     <p>
260     Hopefully, your system will boot without problem and you can log in and start
261     working as usual. If everything is working, then the upgrade is complete at
262     this stage.
263     </p>
264    
265     <p>
266     If you have made a mistake and your system will not boot into the new kernel,
267     then you can simply reboot and boot into your previous working kernel. You can
268     then restart from the <uri link="#install">Configuring, compiling, and
269     installing the new kernel</uri> stage - making the appropriate changes to
270     correct your mistake. In some cases (e.g. you just missed a network driver)
271     then you might not even need to reboot to do this.
272     </p>
273    
274     </body>
275     </section>
276     </chapter>
277    
278     <chapter>
279     <title>Running multiple kernels</title>
280     <section>
281     <body>
282    
283     <p>
284     You may have noticed, that when installing the sources for your newer kernel,
285     the sources for your existing kernel were not removed. This is by-design and
286     allows you to easily switch between running different kernels.
287     </p>
288    
289     <p>
290     Switching between multiple kernels is as simple as leaving the kernel sources
291     under <path>/usr/src/</path> and leaving the <path>bzImage</path> binaries on
292     your <path>/boot</path> partition (referenced by entries in your bootloader
293     config). Every time you boot up, you will be presented with a choice of which
294     kernel to boot into.
295     </p>
296    
297     </body>
298     </section>
299     </chapter>
300    
301     <chapter>
302     <title>Removing older kernels</title>
303     <section>
304     <body>
305    
306     <p>
307     Continuing on from the last section, you may be happy with your new kernel and
308     not have any need to keep older kernel versions around. To easily remove all
309     sources for a particular kernel except for the newest one, you can take
310     advantages of emerge's <e>prune</e> option. Continuing the example using
311     gentoo-dev-sources:
312     </p>
313    
314     <pre caption="Pruning old versions">
315     # <i>emerge -P gentoo-dev-sources</i>
316     </pre>
317    
318     <p>
319     In most cases, temporary files used during compilation will still remain under
320     the appropriate source directory under <path>/usr/src</path>. It is safe to
321     remove these using <c>rm</c>.
322     </p>
323    
324     <p>
325     You can also safely delete any modules that were used by this kernel. This can
326     be done by removing the appropriate directories under <path>/lib/modules/</path>
327     that relate to the kernel versions you are removing. Be careful not to delete
328     modules belonging to kernels that you still use!
329     </p>
330    
331     <p>
332     Finally, you can mount your <path>/boot</path> partition and remove the
333     <path>bzImage</path> and <path>System.map</path> files for the kernel(s)
334     you are pruning. You should also edit your bootloader config so that it
335     no longer references this kernel.
336     </p>
337    
338     </body>
339     </section>
340     </chapter>
341    
342     <chapter>
343     <title>Problems after a kernel upgrade?</title>
344     <section>
345     <body>
346    
347     <p>
348     With the rapid development of the Linux kernel, it is inevitable that some
349     changes made from one kernel release to another may cause some problems. If
350     you have any issues with the latest versions of
351     <uri link="http://www.gentoo.org/doc/en/gentoo-kernel.xml#doc_chap2">
352     Gentoo-supported kernels</uri> then please do report the issues to us.
353     </p>
354    
355     </body>
356     </section>
357     </chapter>
358    
359     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20