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

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