/usr/share/kernel-package/docs/Kernel.htm is in kernel-package 13.018+nmu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 | <html>
<head>
<title>
Creating a Custom Linux Kernel in Debian GNU/Linux
</title>
<meta name="description" content="Creating a Custom Linux Kernel in Debian GNU/Linux" />
<meta name="keywords" content="Debian GNU/Linux custom Linux kernel kernel-package make-kpkg make menuconfig patch source compile" />
<meta name="author" content="Stephen Powell" />
<meta http-equiv="Content-Type" content="text/html;charset=ISO-8859-1" />
<meta name="revised" content="2009-11-12">
</head>
<body>
<h1 align=center>
Creating a Custom Linux Kernel in Debian GNU/Linux
</h1>
<h2>
Disclaimer
</h2>
<p>
This is not an official Debian site.
The author is not a member of the Debian kernel team.
This is not an official Linux kernel site.
This document details the author's experiences
and recommendations in
building a custom Linux kernel under Debian GNU/Linux.
All opinions expressed are those of the author and do not necessarily
represent the opinions or the official positions
of the staff or management of Debian, the Linux kernel organization,
or anyone else.
This information is presented in the hope that it will be useful,
but without any warranty or guarantee of any kind.
This information is presented free of charge, free of support,
free of service, and free of liability.
Take this information
with as many grains of salt as you think it's worth;
and use it, if you
choose to do so, entirely at your own risk.
The author hereby explicitly
places this material in the public domain.
All trademarks, registered
trademarks, service marks, etc. are the property of their respective
owners.
</p>
<h2>
Introduction
</h2>
<p>
Most of the time, the stock kernel images
obtained from Debian are adequate.
But occasionally one may need to create a custom kernel image in order to
take advantage of some special feature or solve a particular problem.
You may also want to create a custom kernel in order to create a
"lean and mean" kernel: one which is as small as possible and contains
only the code necessary to do the function assigned to this machine.
(This is often done in embedded systems.)
I assume that you already know why you need or want to build a custom
kernel.
The purpose of this document is to show you how.
The example I will use is from the s390/s390x architecture,
and it involves applying a patch to a kernel source module,
but the techniques are applicable to all architectures.
</p>
<p>
I had a roommate in college who had spent four years in the Navy.
He told me that in the Navy there are three ways to do everything:
the right way, the wrong way, and the Navy way!
Well, kernel building in Debian is like that too.
Although there are similarities to other distributions,
Debian definitely has their own way of building kernels.
Information that you may find on distribution-independent Linux
sites or sites from non-Debian-based distributions
that talk about building a custom kernel are not likely
to be very useful in Debian.
Debian wants <em>everything</em>, including the kernel itself,
to go through its package management system.
As a result, kernel building in Debian is quite different from
other non-Debian-based distributions.
</p>
<p>
I have found that the documentation for kernel building in Debian is spread
out over several different sources.
Some of these documents are out of date.
Furthermore, there are a number of small but important steps that are often
left out.
This write-up is an attempt to document the procedure in detail.
</p>
<p>
I would like to start by discussing naming conventions.
For Linux kernels
2.6.8 and earlier, the name of the kernel image package in the Debian archive
begins with "kernel-image".
An example is "kernel-image-2.6.8-2-s390".
Similarly, the kernel source code packages begin with "kernel-source".
An example is "kernel-source-2.6.8".
This naming convention implies that all
kernels are Linux kernels.
But the Hurd kernel is also now available, and the FreeBSD kernel
is on the horizon as well.
Therefore, later Linux kernels now have their image package
names begin with
"linux-image" and their source package names begin with "linux-source".
This change occurred between Sarge and Etch.
Much of the documentation for Linux
kernel building was written in the days of Sarge and previous releases and
still uses the old naming convention.
If you don't know about the naming
convention change, you will never be able to find the kernel source package
that you need in the Debian archive.
So remember, despite what the
documentation may say, look for the kernel source package under the name
"linux-source", not "kernel-source".
</p>
<p>
I am assuming that you have never downloaded or configured a
kernel source package on your system before and that you want to create a
custom kernel image of the same kernel release as the stock kernel that you
are currently running.
I'll be using kernel 2.6.26 from the Lenny release and the s390/s390x
architecture in my examples, but as I said earlier
the techniques are applicable to all releases and architectures.
Login as root to do this type of administration.
Some of the other kernel-building documents
that I've seen make a big deal about
what parts of the procedure can be done as a non-root user.
I never bother with that.
To me, kernel building and installing are administrative tasks,
and I just stay root the whole time.
It's simpler that way.
This document will assume that you are logged on as root at all times
during the procedure unless otherwise noted.
</p>
<h2>
Step 1: Update your sources.list file
</h2>
<p>
The retrieval of packages in Debian is
controlled by a file called /etc/apt/sources.list.
If you installed Debian
from a CD-ROM, chances are that only the first CD is listed in the
sources.list file.
If you have a complete set of CDs, but only the first one
is listed, you need to update this file.
However, adding CDs to sources.list
cannot be accomplished via a text editor.
Other files in other places must
be updated too in order for a CD entry in sources.list to work.
To add new
CDs to the sources.list file, use the following command:
</p>
<br>
<pre>
apt-cdrom add
</pre>
<p>
You will need to issue this command once for every CD in your set that is not
already listed in sources.list.
If you have several "disk 1" CDs in your
set, don't scan the alternate ones.
For example, Lenny ships with 3 "disk 1"
CDs: one for a GNOME-based desktop environment, one for a KDE-based desktop
environment, and one for an XFCE-based desktop environment.
If you installed
from the GNOME version of disk 1, it is the one listed in your sources.list
file.
Don't scan the other two "disk 1" CDs with apt-cdrom.
Each time you
run apt-cdrom, it will prompt you to insert a CD and press Enter.
After you
do this, it will mount the CD, scan the CD looking for package information,
then umount the CD.
When the command completes, remove the CD from the CD
drive.
apt-cdrom is also used if you have installed from DVDs.
(Of course,
there will be far fewer DVDs in a complete set than there are for a complete
set of CDs, since a DVD holds much more data per disk.)
</p>
<p>
If you have access to the internet, you should include an internet server in
sources.list.
This is true even if you installed Debian from CDs.
This will
allow you to install the most recent version of a package, if there is a newer
version than the one on the CD.
(Packages in the stable release are not
normally updated during the life of the release except to fix bugs involving
security vulnerabilities or to replace data that is highly volatile in
nature.
An example is the virus signature data for an
anti-virus software package.)
You should also make sure that the volatile and security sites
are present as well.
(But don't use the volatile site for the testing or unstable releases.)
If you didn't have access to the internet during
installation, the installer may have commented out these entries.
If you have
access to the internet now, but you didn't during installation, uncomment
these entries.
You might also want to add entries for the "non-free" and
"contrib" sections, in addition to the "main" section.
The CDs contain only
the main section.
</p>
<p>
With the exception of the volatile and security sites, which must use
HTTP, you have a choice, for most of the Debian mirrors, whether to use HTTP
or FTP as the file transfer protocol.
Be careful though -- some of the
mirrors use a different path name for HTTP and FTP.
For a full list of
Debian mirrors, see
<a href="http://www.debian.org/mirror/list">http://www.debian.org/mirror/list</a>.
Choose the mirror
nearest to you or which gives you the shortest latency or the highest data
transfer rate.
Make sure you choose a mirror which supports the file
transfer method you want to use and specify the correct path for that type of
data transfer.
Also, make sure that you choose a mirror that mirrors your
machine architecture.
(Not all mirrors mirror all architectures!)
For more
information, see the man page for sources.list
and the above-mentioned web page which lists all the mirrors.
For all sources except CDs
and DVDs, the sources.list file can and should be edited
by a text editor.
Make sure that the internet sources are listed after the CD/DVD sources, and
make sure that the volatile and security sources are listed last.
Here is a sample
sources.list file:
</p>
<br>
<pre>
.
. (possible CD entries added by apt-cdrom)
.
deb ftp://debian.uchicago.edu/debian lenny main non-free contrib
deb-src ftp://debian.uchicago.edu/debian lenny main non-free contrib
deb http://volatile.debian.org/debian-volatile lenny/volatile main non-free contrib
deb-src http://volatile.debian.org/debian-volatile lenny/volatile main non-free contrib
deb http://security.debian.org lenny/updates main non-free contrib
deb-src http://security.debian.org lenny/updates main non-free contrib
</pre>
<p>
The "deb" entries specify a server for binary packages and the "deb-src"
entries specify a server for source packages.
The University of Chicago's
Debian mirror site has been selected for both package types, using the FTP
protocol.
Only packages from the Lenny distribution will be
selected, but the "non-free" and "contrib" sections have been added to the
standard "main" section.
The standard Debian volatile and security servers have been
added at the end, using the HTTP protocol.
</p>
<h2>
Step 2: Update the list of available packages
</h2>
<p>
Once the sources.list file has been
updated, you need to update the package management system's list of available
packages.
The book says the way to do this is to issue the command:
</p>
<br>
<pre>
aptitude update
</pre>
<p>
and that will work.
"apt-get update" works too.
But I prefer "dselect update" because it provides
more information than "apt-get update" or "aptitude update"
does.
Specifically, it downloads package descriptions for all available
packages, instead of only installed packages.
dselect is not part of the standard system anymore;
so unless you explicitly installed it earlier it's
probably not installed.
In that case, the first thing you will need to do is
install dselect.
I don't recommend that you use dselect to install packages,
but I do recommend it for updating the list of available
packages.
You may need to update the list of available packages
before you can install dselect!
Use "aptitude update" or "apt-get update" to do that.
But once dselect is installed, run "dselect update"
to update the list of available packages again.
</p>
<h2>
Step 3: Apply pending updates
</h2>
<p>
After updating the list of available
packages, as outlined above, you should apply all the pending updates that
have accumulated since you last applied updates (or since installation, if
you have never applied updates).
To do this, enter the following command:
</p>
<br>
<pre>
aptitude -R full-upgrade
</pre>
<p>
While we're on the subject, now would be a good time to subscribe to the
debian-security-announce mailing list on the Debian web site.
To subscribe,
send an e-mail to
<a href="mailto:debian-security-announce-request@lists.debian.org">debian-security-announce-request@lists.debian.org</a>
with a
subject line of "subscribe" (without the quotes).
You will receive a
follow-up e-mail from Debian which will give instructions on how to confirm
the subscription.
Follow the instructions in the follow-up e-mail.
Then,
whenever you receive a security alert, update the list of packages again
with "dselect update".
Then use
</p>
<br>
<pre>
aptitude -R full-upgrade
</pre>
<p>
to install the updates.
Similarly, subscribe to the debian-volatile-announce mailing list on the
Debian web site by sending an e-mail to
<a href="mailto:debian-volatile-announce-request@lists.debian.org">debian-volatile-announce-request@lists.debian.org</a>
with a subject line of "subscribe" (without the quotes)
and following the directions in the reply.
(Once again, the debian-volatile service is not provided for
the testing or unstable releases.)
When you are finished installing package updates, use
</p>
<br>
<pre>
aptitude clean
</pre>
<p>
to delete the package files (.deb files) from the staging area
(/var/cache/apt/archives).
Once the packages have been installed, you don't
need the package files themselves anymore.
This will save disk space.
Once the updates have been installed, it is a good idea
to shutdown and reboot.
</p>
<p>
<strong>Note:</strong>
only package files downloaded from the internet are copied to the
staging area.
Package files read from CD-ROM or DVD are not copied to the
staging area but are processed directly from the mountable media.
</p>
<h2>
Step 4: Install the kernel source package
</h2>
<p>
Once you have updated the list of
available packages, you should be able to see the package information with
various tools.
In line mode, use dpkg-query to see the information about the
package.
(Information about packages that are not installed
is only available in this way
if you used "dselect update" instead of "apt-get update"
or "aptitude update" to update the list of packages.)
For example:
</p>
<br>
<pre>
dpkg-query -p linux-source-2.6.26|less
</pre>
<p>
If you don't know what kernel release you're running, you can find out by
issuing the command:
</p>
<br>
<pre>
uname -r
</pre>
<p>
dselect can also be used to browse the package cache and find the information
about the package.
To actually install the source package, use
aptitude.
For example,
</p>
<br>
<pre>
aptitude -R install linux-source-2.6.26
</pre>
<p>
This will install the kernel source code.
You can obtain kernel source packages from other places,
but I recommend using official Debian kernel source packages
because they contain all the Debian-specific modifications.
Once this command
has completed, enter
</p>
<br>
<pre>
aptitude clean
</pre>
<p>
to delete the package <strong>file</strong> (not
the package) from the staging area.
</p>
<h2>
Step 5: Unpack the kernel sources
</h2>
<p>
So what did
"aptitude -R install linux-source-2.6.26"
just do?
If everything worked correctly, you should now have a file in the /usr/src
directory that starts out as "linux-source" and ends in ".tar.bz2".
It is at
this point that many people make a mistake.
They create a directory in
/usr/src called linux-source-2.6.26, move the kernel source tar file to that
directory, then unpack the tar file from there.
Don't do that.
If you do,
you will end up with two levels of directory called
linux-source-2.6.26.
Instead, change directories to /usr/src and unpack the
kernel sources right where they
are.
For example:
</p>
<br>
<pre>
cd /usr/src
tar -xjf linux-source-2.6.26.tar.bz2
</pre>
<p>
The "x" switch of tar indicates that the "extract" function will be used.
The "j" switch tells tar to filter the archive through bzip2 to
decompress the archive first, before tar itself processes the file.
And finally, the "f" switch specifies that input is to be read from a file
specified on the command line, instead of standard input.
</p>
<p>
The above "tar" command will create a directory under the current directory
(/usr/src) called linux-source-2.6.26.
All the kernel source code and
associated files will be unpacked
to this directory and its subdirectories.
Strictly speaking,
one is not supposed to erase a file belonging to an installed
package.
But once the archive has been unpacked, there's really no use in
keeping it around.
I recommend getting rid of it.
I suppose the "right" way
to do it would be to purge the package.
But then you won't automatically
get security updates for it.
So my approach is to simply delete it once it
has been unpacked.
</p>
<br>
<pre>
rm linux-source-2.6.26.tar.bz2
</pre>
<p>
This saves a lot of disk space.
</p>
<h2>
Step 6: Install kernel-package
</h2>
<p>
If you have not already done so, install the
"kernel-package" package.
You can check to see if it is already installed
by using the search function in dselect.
In line mode, the command
</p>
<br>
<pre>
dpkg-query -l kernel-package|grep ii
</pre>
<p>
will do nicely.
If it is not already installed, install it.
Apparently, kernel-package was at one time used by,
or was intended to be used by, the
official Debian kernel team to create stock kernel
images;
but at some point there was a parting of the ways;
and the official Debian kernel team now uses other tools
to create stock kernel images.
I haven't seen any real documentation on the tools
that the Debian kernel team uses to create the stock kernel
images, and kernel-package works well,
so I continue to use it and recommend it.
</p>
<br>
<pre>
aptitude -R install kernel-package
</pre>
<p>
Read the documentation for kernel-package
</p>
<br>
<pre>
zless /usr/share/doc/kernel-package/README.gz
</pre>
<p>
Determine what additional packages you may need, assuming that you are going
to use "make menuconfig".
Since there are a number of
different kernel configuration methods (config, menuconfig, xconfig, etc.),
and since kernel-package doesn't know which one you plan to use, it does not
mark anything as a prerequisite unless it is a prerequisite for all
configuration methods.
At the time of this writing, the following packages
will be required for the menuconfig method:
</p>
<br>
<pre>
gcc
libc6-dev
bin86 (i386 architecture only)
libncurses5-dev
binutils
make
kmod
mawk | gawk (one or the other, not both)
gzip
coreutils
grep
zlib1g-dev (if CONFIG_LGUEST is set)
</pre>
<p>
Many of these packages will already be installed.
To check to see if these packages are installed, use dpkg-query.
For example:
</p>
<br>
<pre>
dpkg-query -l gcc|grep ii
</pre>
<p>
Alternatively, you can use dselect to check to see which packages need to be
installed.
Install those packages which you need with "aptitude install".
For example:
</p>
<br>
<pre>
aptitude -R install libncurses5-dev
aptitude clean
</pre>
<h2>
Step 7: Patch the kernel (if needed)
</h2>
<p>
At this point, apply any patches to the kernel
source code that are needed.
In this example, we apply a patch to dasd_diag.c to fix a problem with
read-only minidisks.
We assume here that the patch to be applied is
/root/dasd_diag.diff
and that the current directory is /usr/src.
</p>
<br>
<pre>
patch linux-source-2.6.26/drivers/s390/block/dasd_diag.c \
/root/dasd_diag.diff
</pre>
<p>
This patch file is available on my web site
<a href="dasd_diag.diff">here</a>.
Right-click on the previous link and select "Save Link as"
to download it to your system.
If you are using the lynx text-mode browser,
download the file by typing the letter "d"
(without the quotes) when the link is selected.
</p>
<h2>
Step 8: Configure the kernel
</h2>
<p>
First, change directories to the home directory for
the source code.
</p>
<br>
<pre>
cd linux-source-2.6.26
</pre>
<p>
The full working directory is now /usr/src/linux-source-2.6.26.
Now, initialize the .config file based on the configuration file
used by the stock Debian kernel.
</p>
<br>
<pre>
cp /boot/config-2.6.26-2-s390 .config
</pre>
<p>
This means that if you make no changes, your custom kernel will be configured
exactly like the stock Debian kernel.
(If you are running the 64-bit version of the s390
kernel, the file to copy is "/boot/config-2.6.26-2-s390x".)
</p>
<p>
<strong>Note:</strong> this assumes that you have
installed the kernel source code for the same level of kernel that you are
currently running.
I don't recommend that you migrate to a new kernel
release this way.
Don't use a config file from one kernel release as the
basis for customization of a different kernel release.
If you can't get
a copy of a stock kernel config file for the same release as your source
code, then don't initialize the .config file at all.
</p>
<p>
To avoid confusion between a stock kernel and a custom kernel, I recommend
that you edit the kernel-package config file (/etc/kernel-pkg.conf) and
change the "maintainer" and "email" tags to
your own name and e-mail address.
Now it's time to configure the kernel:
</p>
<br>
<pre>
make menuconfig
</pre>
<p>
After some preliminaries, an ncurses-based full-screen application will be
launched that allows you to configure the kernel.
I assume that you know
what to do here.
</p>
<p>
<strong>Note:</strong> In the process of configuring your kernel,
make sure that you leave
CONFIG_BLK_DEV_INITRD set to Y, which is the default.
This is listed under
"Block devices" as "Initial RAM filesystem and RAM disk (initramfs/initrd)
support".
You're probably going to need that.
I'll have more to say about
that later.
</p>
<p>
<strong>Note:</strong> Newer kernel config files contain
a couple of settings that you should
not use.
These include "CONFIG_LOCALVERSION" (Local version - append to
kernel release) and CONFIG_LOCALVERSION_AUTO (Automatically append version
information to the version string).
These are found under "General Setup".
Debian has its own way of specifying this information.
I'll have more to say
about that later.
</p>
<p>
<strong>Note:</strong> even if you do not plan to change
the kernel configuration file copied
from the /boot directory at all,
you must still run "make menuconfig".
make-kpkg relies on certain files that are created when you run
"make menuconfig".
If you don't wish to change anything,
immediately select "Exit" when the initial screen
is displayed.
</p>
<h2>
Step 9: Create the kernel image package
</h2>
<p>
This step will compile the kernel source
code and create a Debian package file for the custom kernel.
But before I get to
the specific commands, I need to discuss naming conventions again.
This is
critically important.
I need to talk about the difference between the kernel
version name and the kernel revision name.
Both the kernel version name and the kernel
revision name become part of the package file name
(.deb file) that gets created.
However, when the package gets installed, the kernel revision
name does not become
part of the package name.
It also does not become part of the kernel image file name or the
initial RAM disk image file name that gets installed in
the /boot directory.
Similarly, the directory in which the kernel modules
get installed (/lib/modules/...) does
not contain the kernel revision name either.
Since you want to retain your existing kernel image,
initial RAM disk image,
and modules unaltered as a backout, you must make the kernel version name
different from the stock kernel version name in some way.
</p>
<p>
This is accomplished by means of the "--append-to-version" flag
of make-kpkg.
I usually include the word "custom" in the name to distinguish it
from the stock kernel of the same version.
In this example, the stock kernel has an "--append-to-version" value
of "-2-s390".
(In other words, "uname -r" reports "2.6.26-2-s390".
The version proper is "2.6.26" and the
"--append-to-version" value is "-2-s390".)
My first cut at a custom kernel would probably have an "--append-to-version"
value of "-custom2-s390".
For subsequent custom versions of the same stock kernel image
I would probably use "-custom2a-s390", "-custom2b-s390",
etc.
(If creating a 64-bit custom kernel,
use s390x instead of s390.
For example, "-custom2-s390x".)
</p>
<p>
On the other hand, I would keep the kernel revision exactly the same
as the stock kernel.
That way, I know exactly which stock kernel revision it
corresponds to.
For example, at the time of this writing, the current "--revision" value
is "2.6.26-19lenny2".
I obtain this value from the "version" reported by
"dpkg-query -p linux-source-2.6.26"
or "dpkg-query -p linux-image-2.6.26-2-s390".
If the kernel source and the stock kernel image are in sync, their "versions"
will match.
It's confusing that the package "version" matches the kernel "revision",
but that's what it boils down to.
</p>
<p>
Also, I need to talk about initial ram disk images.
A standard stock Debian kernel is configured with almost everything built as a
module, if it can be a module, rather than built in to the kernel.
This allows for installation on
as wide a variety of hardware configurations as possible while holding the
size of the kernel down as much as possible.
But modules reside on disk.
And any kernel function that is required
for the kernel to be able to mount the
partitions or do I/O to the disks must be loaded into storage before any
kernel modules can be read from disk.
This means that either this support must be
compiled into the kernel or else it
must be loaded from the initial ram disk.
This is the primary purpose for an initial ram disk: it allows the kernel to
load modules that it needs before it can read them from disk.
Once the permanent root
file system is mounted, the initial ram disk image is freed from memory.
</p>
<p>
As an example from the i386 architecture, suppose your
permanent root file system,
which contains /lib/modules/..., is mapped
to a partition on a SCSI disk.
But the kernel support for the SCSI adapter is not compiled into the kernel:
it is a loadable module.
As an example from the s390 architecture,
how can you load the dasd driver modules from disk when those modules must
be loaded in order to do I/O to the disk?
In such cases, you need an
initial ram disk.
Stock Debian kernels are set up via the boot loader
(grub, lilo, zipl, etc.) to use initial ram disk images.
I am assuming in
these instructions that you are going to do the same.
If not, then you must do three things:
(1) You must make sure that all kernel function needed to get
the permanent root file system mounted is built-in to the kernel.
(2) You must not supply the "--initrd" flag to make-kpkg when you
invoke it.
(3) You must change your boot loader configuration so that it does
not expect an initial RAM disk image.
Taking the path of least resistance, I am assuming that you are going
to use an initial RAM disk image the way the stock kernels do.
</p>
<p>
Finally, I am assuming that you are not using any third-party kernel modules
(i.e. modules which do not ship with the kernel source).
If you are, read
the documentation for kernel-package and the man page for make-kpkg for
information on what to do.
In most cases, simply adding the modules_image
target at the end of the command will do the trick.
(But of course, the
module source code package must have previously been installed and unpacked
in the expected location.)
</p>
<p>
OK, with all that said, here are the commands:
</p>
<br>
<pre>
make-kpkg clean
</pre>
<p>
You need to run this before each kernel build.
Then issue:
</p>
<br>
<pre>
make-kpkg --append-to-version -custom2-s390 --revision 2.6.26-19lenny2 \
--initrd kernel_image
</pre>
<p>
In this example,
I am assuming an s390 kernel image package is being built.
Obviously, change the s390 specification to your architecture.
The "--initrd" flag indicates that a kernel with an initial RAM disk image is
to be built.
The actual initial RAM disk image, however, is not built at
this time.
That is deferred until the package is installed.
</p>
<p>
Compiling the entire kernel takes a while.
We're talking hours, probably,
depending on the speed of your processor.
<p>
When make-kpkg is finished, there will be a Debian kernel image package in
the parent directory (.. or /usr/src) of the current directory (. or
/usr/src/linux-source-2.6.26).
If you included the modules_image target,
there may also be one or more Debian package files (.deb files) for the
modules images as well.
</p>
<h2>
Step 10: Install the kernel image package
</h2>
<p>
You won't use aptitude, apt-get, or
dselect to install the kernel image package.
That's because it doesn't have
to be fetched from anywhere.
Instead, use the low-level package tool dpkg.
</p>
<br>
<pre>
cd ..
dpkg -i linux-image-2.6.26-custom2-s390_2.6.26-19lenny2_s390.deb
</pre>
<p>
Obviously, use the actual name of the package file, which can be determined
by using the ls command.
If you have both a kernel image package and one or
more modules image packages, install the kernel image package first, then the
modules image packages.
The latter will probably have a dependency on the
former.
</p>
<p>
The installation script will automatically re-run your boot loader if
necessary.
But before you shut down and reboot, it is a good idea to check
everything out in your boot loader configuration to make sure that the
new kernel was installed to your liking.
</p>
<h2>
Step 11: Shutdown and reboot
</h2>
<p>
Shutdown and reboot to run your new custom kernel!
</p>
<h2>
Step 12: Clean up
</h2>
<p>
Once the new kernel image package has been installed, you can
delete the package file (.deb file).
Login as root again, then
</p>
<br>
<pre>
cd /usr/src
rm linux-image-2.6.26-custom2-s390_2.6.26-19lenny2_s390.deb
</pre>
<p>
If you have also installed one or more modules image packages, you can delete
their package files too.
</p>
<p>
Once you are satisfied with the new kernel, you may wish to de-install the
old kernel image.
I like to keep at least one back version unless I know
that the old kernel will no longer work due to changes made since migrating
to the new kernel.
For example, if my system now depends on a kernel module
that did not exist in the old kernel, there's not much point in keeping the
old kernel around.
</p>
<br>
<pre>
aptitude -R purge linux-image-2.6.26-2-s390
</pre>
<p>
This will de-install the old kernel image and
save some more disk space.
</p>
<p>
<strong>Note:</strong> you must shut down and reboot using
the new kernel before de-installing
the old kernel.
aptitude will not let you de-install a running kernel!
</p>
<p>
May you have much enjoyment running your new custom kernel!
</p>
<h2>
Step 13: Maintenance
</h2>
<p>
OK, now what if you get the new kernel installed and running, but you want to
make changes to the kernel configuration.
Maybe you forgot something the
first time.
Use a sequence of commands something like this.
</p>
<br>
<pre>
cd /usr/src/linux-source-2.6.26
make menuconfig
make-kpkg clean
make-kpkg --append-to-version -custom2a-s390 --revision 2.6.26-19lenny2 \
--initrd kernel_image
cd ..
dpkg -i linux-image-2.6.26-custom2a-s390_2.6.26-19lenny2_s390.deb
rm linux-image-2.6.26-custom2a-s390_2.6.26-19lenny2_s390.deb
shutdown -r now;exit
</pre>
<p>
Something like the above will do nicely.
Notice that the "append-to-version"
flag needs to be changed slightly each time.
If you have third-party modules
to make, add the "modules_image" target to make-kpkg as well, and add
"dpkg -i" commands to install the
modules after you install the kernel.
Typically, your boot loader is configured to boot two kernels: the primary
kernel, which is the one most recently installed, and one alternate one,
which is the next most recently installed one.
If you didn't deinstall the
stock kernel last time, you should probably do so now.
You've got three kernel
images on your machine now: the original stock kernel, your first custom
kernel, and your second custom kernel.
And only the two custom ones are
bootable at this point, unless you've been customizing your boot loader
configuration as well.
</p>
<br>
<pre>
aptitude -R purge linux-image-2.6.26-2-s390
</pre>
<p>
Once your first custom kernel rolls off the boot loader menu, deinstall it
in a similar manner.
</p>
<p>
OK, you've been happily running your custom kernel for several months now,
and you get a security update notice from Debian.
You update the list of
available packages via "dselect update", then you run
"aptitude -R full-upgrade".
And when you do, you notice that an updated kernel
source package has been downloaded and installed.
What do you do now?
</p>
<p>
Well, it's time to clean house.
Of course
you've already run "aptitude clean", right?
(You should always run
"aptitude clean" after running "aptitude -R full-upgrade".)
</p>
<br>
<pre>
cd /usr/src
rm -r linux-source-2.6.26/*
rm -r linux-source-2.6.26/.*
</pre>
<p>
(You will get error messages from the second command about not being able to
remove "." and "..".
That's OK.
You don't want it to remove "." or ".."!)
</p>
<br>
<pre>
tar -xjf linux-source-2.6.26.tar.bz2
rm linux-source-2.6.26.tar.bz2
</pre>
<p>
Now proceed to step 7, with some minor variations.
The name of the config
file that gets copied from the /boot directory to .config in the current
directory must change to match the current kernel config file.
You must
re-run "make menuconfig", even if you don't change a thing in the kernel
configuration, because some files get created by "make menuconfig" that
make-kpkg needs, and you just erased them.
You must then re-run
"make-kpkg clean".
</p>
<p>
The "--append-to-version" flag must change slightly to not conflict with any
of the kernel versions you currently have installed.
That will change the
name of the package file created;
so the "dpkg -i" command will change too.
And of course, "aptitude -R purge"
must change to de-install the correct old
version of the kernel.
By now you get the idea.
</p>
<p>
<strong>Note:</strong> sometimes the stock kernel configuration file
will change with a security update.
The powers that be may have decided to change a kernel configuration
option for security reasons.
In that case, if you want to keep your custom kernel configuration file
in sync with the latest stock kernel, you will need to install the
latest stock kernel image in order to get that config file.
That's a little like buying Maxwell House to get a cup of coffee,
but I don't know how else to get that config file.
Once you have that config file copied over as
/usr/src/linux-source-2.6.26/.config,
you can de-install the stock kernel again.
Depending on which boot loader you use, de-installing the most recently
installed kernel image, even though it's not the currently running kernel,
may leave your boot loader in a broken state.
For example, on the s390 platform you will need to perform the
following steps to fix your boot loader after the above scenario.
</p>
<br>
<pre>
cd /boot
mv initrd.img.old initrd.img
mv vmlinuz.old vmlinuz
zipl
</pre>
<p>
If you had two bootable kernel images installed prior to installing (and
then de-installing) the stock kernel image, you will also need
to re-create the proper symbolic links for initrd.img.old and
vmlinuz.old prior to running zipl.
For example, let's say that prior to installing that stock kernel image
you had vmlinuz pointing to vmlinuz-2.6.26-custom2i-s390,
initrd.img pointing to initrd.img-2.6.26-custom2i-s390,
vmlinuz.old pointing to vmlinuz-2.6.26-custom2h-s390,
and initrd.img.old pointing to initrd.img-2.6.26-custom2h-s390.
After installing linux-image-2.6.26-2-s390, vmlinuz points to
vmlinuz-2.6.26-2-s390, initrd.img points to initrd.img-2.6.26-2-s390,
vmlinuz.old points to vmlinuz-2.6.26-custom2i-s390, and
initrd.img.old points to initrd.img-2.6.26-custom2i-s390, and
zipl is re-run.
Nothing points to vmlinuz-2.6.26-custom2h-s390 or
initrd.img-2.6.26-custom2h-s390 anymore, but the files are still there.
</p>
<p>
When you run "aptitude -R purge linux-image-2.6.26-2-s390",
this causes vmlinuz-2.6.26-2-s390 and initrd.img-2.6.26-2-s390 to be
deleted, and the symbolic links that point to them,
vmlinuz and initrd.img, respectively, are also deleted; since they
are now broken links.
zipl is not rerun.
To restore your boot loader back to the state it was in
prior to installing linux-image-2.6.26-2-s390,
enter the following sequence of commands:
</p>
<br>
<pre>
cd /boot
mv vmlinuz.old vmlinuz
mv initrd.img.old initrd.img
ln -s vmlinuz-2.6.26-custom2h-s390 vmlinuz.old
ln -s initrd.img-2.6.26-custom2h-s390 initrd.img.old
zipl
</pre>
<p>
lilo also uses symbolic links and needs similar processing.
grub, since it does not use symbolic links, requires less fuss.
</p>
<p>
Happy Kerneling!
If any one has any comments, suggestions, complaints, corrections,
or any other form of feedback, please drop me a line at
<a href="mailto:zlinuxman@wowway.com">zlinuxman@wowway.com</a>.
</p>
</body>
</html>
|