/[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 - (show annotations) (download) (as text)
Wed Apr 6 14:36:19 2005 UTC (9 years, 6 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 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/kernel-upgrade.xml,v 1.2 2004/12/06 10:07:29 swift 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.2</version>
21 <date>2005-04-06</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-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 NS ] sys-kernel/gentoo-sources-2.6.9-r2 [2.6.8-r5]
89 </pre>
90
91 <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 <p>
98 You can then go ahead and install the update, e.g.:
99 </p>
100
101 <pre caption="Upgrading your kernel sources">
102 # <i>emerge -u gentoo-sources</i>
103 </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 # <i>ln -sfn linux-2.6.9-gentoo-r2 linux</i>
134 </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 gentoo-sources:
318 </p>
319
320 <pre caption="Pruning old versions">
321 # <i>emerge -P gentoo-sources</i>
322 </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 <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 <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 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 </p>
408
409 </body>
410 </section>
411 </chapter>
412
413 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20