/[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.4 - (show annotations) (download) (as text)
Mon May 23 18:35:47 2005 UTC (9 years, 7 months ago) by swift
Branch: MAIN
Changes since 1.3: +54 -43 lines
File MIME type: application/xml
#93289 - Improve explanation on upgrade path. Thanks to Jimi Ayodele for the patch.

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

  ViewVC Help
Powered by ViewVC 1.1.20