/[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.27 - (show annotations) (download) (as text)
Mon Dec 9 12:58:26 2013 UTC (8 months, 3 weeks ago) by swift
Branch: MAIN
CVS Tags: HEAD
Changes since 1.26: +3 -2 lines
File MIME type: application/xml
Kernel upgrade at https://wiki.gentoo.org/wiki/Kernel/Upgrade and https://wiki.gentoo.org/wiki/User:SwifT/Wikified_but_not_merged_documents/Kernel_Upgrade

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/kernel-upgrade.xml,v 1.26 2013/09/17 07:27:29 swift Exp $ -->
3
4 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5 <guide disclaimer="obsolete" redirect="https://wiki.gentoo.org/wiki/Kernel/Upgrade">
6 <!-- guide redirect=https://wiki.gentoo.org/wiki/User:SwifT/Wikified_but_not_merged_documents/Kernel_Upgrade -->
7 <title>Gentoo Linux Kernel Upgrade Guide</title>
8 <author title="Author">
9 <mail link="dsd@gentoo.org">Daniel Drake</mail>
10 </author>
11
12 <abstract>
13 This document describes the process of upgrading your kernel from one release
14 to another.
15 </abstract>
16
17 <!-- The content of this document is licensed under the CC-BY-SA license -->
18 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
19 <license/>
20
21 <version>7</version>
22 <date>2013-09-17</date>
23
24 <chapter>
25 <title>Introduction</title>
26 <section>
27 <body>
28
29 <p>
30 The kernel is one of the few package classes in portage that requires some
31 manual intervention to complete the upgrade. Portage will download and
32 install the kernel source for you, but then it is up to you to step in and
33 compile the new kernel before any changes will take effect.
34 </p>
35
36 <p>
37 Although this guide is targeted at users upgrading from one kernel release
38 to another, it will also be useful for users migrating from one kernel
39 package to another.
40 </p>
41
42 <p>
43 <c>gentoo-sources</c> is used as an example in this document, however, the
44 instructions here also apply to the other packages present in our tree.
45 </p>
46
47 </body>
48 </section>
49 </chapter>
50
51 <chapter>
52 <title>Why upgrade the kernel?</title>
53 <section>
54 <body>
55
56 <p>
57 Generally, upgrading from one minor kernel release to the next won't bring any
58 major differences. There are several reasons to upgrade the kernel. One is to
59 take advantage of a specific new feature or driver; another is to be protected
60 against a security vulnerability, or just to maintain an up-to-date and healthy
61 system.
62 </p>
63
64 <p>
65 Even if you choose not to update to every new kernel revision, it is
66 recommended that you at least upgrade from time to time. It is strongly
67 recommended that you immediately upgrade to a new kernel if that new release
68 solves a security problem.
69 </p>
70
71 </body>
72 </section>
73 </chapter>
74
75 <chapter>
76 <title>Obtaining the newer sources through Portage</title>
77 <section>
78 <body>
79
80 <p>
81 You upgrade the kernel sources like you would upgrade any other package -
82 using the <c>emerge</c> utility. It will probably be the case that you want to
83 upgrade your kernel when you see the upgrade appearing on your world updates
84 list. For example:
85 </p>
86
87 <pre caption="New kernel sources appearing on update list">
88 # <i>emerge -Dup world</i>
89 Calculating dependencies ...done!
90 [ebuild NS ] sys-kernel/gentoo-sources-2.6.39-r3 [2.6.38-r6]
91 </pre>
92
93 <note>
94 The "NS" label in the above output means that the new kernel will be installed
95 in a New Slot, i.e. the sources of your old kernel will be kept around, until
96 you manually remove them.
97 </note>
98
99 <p>
100 You can then go ahead and install the update, e.g.:
101 </p>
102
103 <pre caption="Upgrading your kernel sources">
104 # <i>emerge -u gentoo-sources</i>
105 </pre>
106
107 <p>
108 The kernel sources will then be installed into a subdirectory of
109 <path>/usr/src</path>. In the above example, the new kernel sources will be
110 installed at <path>/usr/src/linux-2.6.39-gentoo-r3</path>.
111 </p>
112
113 </body>
114 </section>
115 </chapter>
116
117 <chapter>
118 <title>Updating the /usr/src/linux symbolic link</title>
119 <section>
120 <body>
121
122 <p>
123 Gentoo requires that the <path>/usr/src/linux</path> symbolic link points to
124 the sources of the kernel you are running.
125 </p>
126
127 <p>
128 Portage can update the symlink automatically when you emerge new kernel
129 sources. All you have to do is add the <c>symlink</c> flag to the USE variable
130 in <path>/etc/portage/make.conf</path>.
131 </p>
132
133 <pre caption="Example of USE variable in /etc/portage/make.conf">
134 <comment>(Add the symlink keyword)</comment>
135 USE="<i>symlink</i> x86 3dnow 3dnowex X aac aalib adns alsa apache2"
136 </pre>
137
138 <p>
139 Alternatively, you could use <c>app-admin/eselect</c> to modify the symlink.
140 </p>
141
142 <pre caption="Using eselect to symlink">
143 <comment>(Install eselect if you don't have it)</comment>
144 # <i>emerge eselect</i>
145 <comment>(See the list of available kernels)</comment>
146 # <i>eselect kernel list</i>
147 Available kernel symlink targets:
148 [1] linux-2.6.39-gentoo-r3
149 [2] linux-2.6.38-gentoo-r6 *
150 <comment>(Select the correct kernel)</comment>
151 # <i>eselect kernel set 1</i>
152 <comment>(Verify the kernel was symlinked)</comment>
153 # <i>eselect kernel list</i>
154 [1] linux-2.6.39-gentoo-r3 *
155 [2] linux-2.6.38-gentoo-r6
156 </pre>
157
158 <p>
159 If you really want to do it yourself, the following example shows you how to
160 make the link point to <path>linux-2.6.39-gentoo-r3</path>:
161 </p>
162
163 <pre caption="Updating the /usr/src/linux softlink manually">
164 # <i>cd /usr/src</i>
165 # <i>ln -sfn linux-2.6.39-gentoo-r3 linux</i>
166 </pre>
167
168 </body>
169 </section>
170 </chapter>
171
172 <chapter id="install">
173 <title>Configuring, compiling and installing the new kernel</title>
174 <section>
175 <body>
176
177 <p>
178 For either of these options, you should refer to the instructions given in the
179 <uri link="/doc/en/handbook/">Gentoo Handbook</uri> relating to <e>Configuring
180 the Kernel</e> and <e>Configuring the Bootloader</e>. Below is an outline of
181 the required actions:
182 </p>
183
184 </body>
185 </section>
186 <section>
187 <title>Option 1: Automatic kernel setup with Genkernel</title>
188 <body>
189
190 <p>
191 If you are a genkernel user, you just need to repeat the stages you went
192 through when installing your kernel for the first time.
193 </p>
194
195 <p>
196 Simply run genkernel in the normal way:
197 </p>
198
199 <pre caption="Invoking genkernel">
200 # <i>genkernel all</i>
201 </pre>
202
203 <p>
204 You can also use extra parameters for other genkernel functionality. For
205 example, if you wish to configure some extra kernel options using
206 <c>menuconfig</c> and you wish genkernel to automatically update your grub boot
207 loader configuration, then invoke genkernel as follows:
208 </p>
209
210 <pre caption="Invoking genkernel with some common arguments">
211 # <i>genkernel --menuconfig --bootloader=grub all</i>
212 </pre>
213
214 <p>
215 For more info, follow the <uri link="/doc/en/genkernel.xml">Gentoo Linux
216 Genkernel Guide</uri>, or refer to the <uri link="/doc/en/handbook/">Gentoo
217 Handbook</uri>. Many of the options can be set in the configuration file for
218 <c>genkernel</c>, <path>/etc/genkernel.conf</path>. Also take a look at the <uri
219 link="https://wiki.gentoo.org/wiki/Initramfs/HOWTO">Gentoo Linux Initial RAM file system
220 guide</uri>.
221 </p>
222
223 </body>
224 </section>
225 <section>
226 <title>Option 2: Manual configuration</title>
227 <body>
228
229 <p>
230 To begin, open the <c>menuconfig</c> utility in the kernel source tree:
231 </p>
232
233 <pre caption="Invoking menuconfig">
234 # <i>cd /usr/src/linux</i>
235 # <i>make menuconfig</i>
236 </pre>
237
238 <p>
239 Select the options required for your hardware and operating environment. For
240 additional information on kernel configuration, refer to the chapter entitled
241 <e>Configuring the Kernel</e> of the <uri
242 link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>.
243 </p>
244
245 <p>
246 Next, compile your kernel and copy it over to your boot partition. Again,
247 follow the <uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>
248 instructions outlined in the chapter on <e>Configuring the Bootloader</e>. If
249 <path>/boot</path> is a separate partition, ensure it is mounted before copying
250 the compiled kernel to this directory! Failing to do so would keep you from
251 booting the system with your new kernel.
252 </p>
253
254 <pre caption="Compiling and installing the new kernel">
255 # <i>make &amp;&amp; make modules_install</i>
256 # <i>mount /boot</i>
257 # <i>cp arch/i386/boot/bzImage /boot/kernel-2.6.39-gentoo-r3</i>
258 </pre>
259
260 <p>
261 Finally, you should update your boot loader configuration, adding an entry for
262 the new kernel (don't delete the old one just yet!) and unmount the
263 <path>/boot</path> partition. Again, refer to the
264 <uri link="/doc/en/handbook/index.xml">Gentoo Handbook</uri>
265 for detailed instructions on this procedure.
266 </p>
267
268 </body>
269 </section>
270 </chapter>
271
272 <chapter>
273 <title>Reinstalling external modules</title>
274 <section>
275 <body>
276
277 <p>
278 If you use any kernel modules that are not included in the kernel source tree
279 but are provided elsewhere in Portage (e.g. ALSA drivers and NVIDIA or ATI
280 graphics drivers), then you must reinstall these after upgrading the kernel.
281 This is as simple as re-merging the packages involved. For more information,
282 refer to the chapter on <e>Configuring the Kernel</e> in the <uri
283 link="/doc/en/handbook/">Gentoo Handbook</uri>.
284 </p>
285
286 <p>
287 We provide you with a built-in Portage set (<c>@module-rebuild</c>) which
288 rebuilds all the kernel modules you have installed using separate ebuilds (such
289 as <c>app-laptop/tp_smapi</c>) for the kernel at <path>/usr/src/linux</path>.
290 Once you have finished upgrading or recompiling your kernel, run <c>emerge
291 @module-rebuild</c> to rebuild the drivers for your new kernel.
292 </p>
293
294 </body>
295 </section>
296 </chapter>
297
298 <chapter>
299 <title>Updating your module configuration</title>
300 <section>
301 <body>
302
303 <p>
304 If you have put specific module configuration entries in
305 <path>/etc/conf.d/modules</path>, then you might need to update the entries
306 accordingly.
307 </p>
308
309 <pre caption="Sample /etc/conf.d/modules file">
310 <comment># The following will only auto-load the ieee1394 module in 2.6.38-gentoo-r6 kernels</comment>
311 modules_2_6_38_gentoo_r6="ieee1394"
312
313 <comment># To support auto-loading on all possible versions, drop any reference to versions:</comment>
314 modules="ohci1394"
315 </pre>
316
317 </body>
318 </section>
319 </chapter>
320
321 <chapter>
322 <title>Rebooting into the new kernel</title>
323 <section>
324 <body>
325
326 <p>
327 Next, close all applications and reboot your system. If you followed the above
328 instructions correctly, the boot loader menu should include an entry for the
329 new kernel. Select the new kernel and let the system boot.
330 </p>
331
332 <p>
333 Hopefully, your system successfully boots with the new kernel, and you can log
334 in to resume whatever you were doing. If this is the case, then the upgrade is
335 complete.
336 </p>
337
338 <p>
339 If you made a mistake and the system fails to boot with the new kernel, reboot
340 the system and select the entry from the boot loader that corresponds to the
341 last known working kernel. You can then restart from the <uri link="#install">
342 Configuring, compiling, and installing the new kernel</uri> stage -- making
343 the appropriate changes to correct your mistake. In some cases, you might not
344 even need to reboot to do this (e.g. you missed a driver for an audio device,
345 Ethernet adapter, etc.)
346 </p>
347
348 </body>
349 </section>
350 </chapter>
351
352 <chapter>
353 <title>Running multiple kernels</title>
354 <section>
355 <body>
356
357 <p>
358 You may have noticed, that when installing the sources for your newer kernel,
359 the sources for your existing kernel were not removed. This is by design -- it
360 allows you to easily switch between running different kernels.
361 </p>
362
363 <p>
364 Switching between multiple kernels is as simple as leaving the kernel sources
365 under <path>/usr/src/</path> and leaving the <path>kernel-*</path> binaries on
366 your <path>/boot</path> partition (referenced by entries in your boot loader
367 configuration). Every time you boot up, you will be presented with a choice of
368 which kernel to boot into.
369 </p>
370
371 </body>
372 </section>
373 </chapter>
374
375 <chapter>
376 <title>Removing older kernels</title>
377 <section>
378 <body>
379
380 <p>
381 Continuing on from the last section, you may be happy with your new kernel and
382 not have any need to keep older kernel versions around. To easily remove all
383 sources for a particular kernel except for the newest one, you can take
384 advantage of the <e>prune</e> option available through <c>emerge</c>. Continuing
385 the example using <c>gentoo-sources</c>:
386 </p>
387
388 <pre caption="Pruning old versions">
389 # <i>emerge -P gentoo-sources</i>
390 </pre>
391
392 <p>
393 In most cases, temporary files used during compilation will still remain under
394 the appropriate source directory under <path>/usr/src</path>. It is safe to
395 remove these using <c>rm</c>.
396 </p>
397
398 <p>
399 You can also safely delete any modules that were used by this kernel. This can
400 be done by removing the appropriate directories under <path>/lib/modules/</path>
401 that relate to the kernel versions you are removing. Be careful not to delete
402 modules belonging to kernels that you still use!
403 </p>
404
405 <p>
406 Finally, you can mount your <path>/boot</path> partition and remove the
407 <path>kernel-*</path> file(s) for the kernel(s) you are pruning. You should also
408 edit your boot loader configuration so that it no longer references such
409 kernel(s).
410 </p>
411
412 </body>
413 </section>
414 </chapter>
415
416 <chapter>
417 <title>Advanced: Using your old kernel .config to configure a new one</title>
418 <section>
419 <body>
420
421 <p>
422 It is sometimes possible to save time by re-using the configuration file from
423 your old kernel when configuring the new one. Note that this is generally
424 unsafe -- too many changes between every kernel release for this to be a
425 reliable upgrade path.
426 </p>
427
428 <p>
429 The only situation where this is appropriate is when upgrading from one Gentoo
430 kernel revision to another. For example, the changes made between
431 <c>gentoo-sources-2.6.9-r1</c> and <c>gentoo-sources-2.6.9-r2</c> will be very
432 small, so it is usually OK to use the following method. However, it is not
433 appropriate to use it in the example used throughout this document: upgrading
434 from 2.6.8 to 2.6.9. Too many changes between the official releases, and the
435 method described below does not display enough context to the user, often
436 resulting in the user running into problems because they disabled options that
437 they really didn't want to.
438 </p>
439
440 <p>
441 To reuse your old <path>.config</path>, you simply need to copy it over and
442 then run <c>make oldconfig</c>. In the following example, we take the
443 configuration from <c>gentoo-sources-2.6.9-r1</c> and import it into
444 <c>gentoo-sources-2.6.9-r2</c>.
445 </p>
446
447 <pre caption="Reusing your old config">
448 # <i>cd /usr/src/linux-2.6.9-gentoo-r2</i>
449 # <i>cp ../linux-2.6.9-gentoo-r1/.config .</i>
450 # <i>make oldconfig</i>
451 </pre>
452
453 <pre caption="Reusing your old config with genkernel">
454 # <i>cd /etc/kernels</i>
455 # <i>cp kernel-config-x86-2.6.9-gentoo-r1 kernel-config-x86-2.6.9-gentoo-r2</i>
456 # <i>genkernel all</i>
457 </pre>
458
459 <p>
460 At this point, you may be asked to produce answers for configuration options
461 which have changed between the two versions. Once you have done that, you can
462 compile and install your kernel as normal, without having to go through the
463 <c>menuconfig</c> configuration process.
464 </p>
465
466 <p>
467 A much safer upgrading method is to copy your config as previously shown, and
468 then simply run <c>make menuconfig</c>. This avoids the problems of <c>make
469 oldconfig</c> mentioned previously, as <c>make menuconfig</c> will load up your
470 previous configuration as much as possible into the menu. Now all you have to
471 do is go through each option and look for new sections, removals, and so on. By
472 using <c>menuconfig</c>, you gain context for all the new changes, and can
473 easily view the new choices and review help screens much easier. You can even
474 use this for upgrades such as 2.6.8 to 2.6.9; just make sure you read through
475 the options carefully. Once you've finished, compile and install your kernel as
476 normal.
477 </p>
478
479 </body>
480 </section>
481 </chapter>
482
483 <chapter>
484 <title>Problems after a kernel upgrade?</title>
485 <section>
486 <body>
487
488 <p>
489 With the rapid development of the Linux kernel, it is inevitable that some
490 changes made from one kernel release to another may cause some problems. If you
491 have any issues with the latest versions of <uri
492 link="/doc/en/gentoo-kernel.xml#doc_chap2"> Gentoo-supported kernels</uri> then
493 please do report the issues to us.
494 </p>
495
496 </body>
497 </section>
498 </chapter>
499
500 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20