The kernels in Debian are distributed in binary form, built from
the Debian kernel source. It is important to recognize that
Debian kernel source may be (and in most cases is) different
from the upstream (or "pristine") kernel source, distributed
from
The guidelines for firmware removal were set by the
The source from which the Debian binary kernels are built is obtained by taking the source from linux_version.orig.tar.xz (that is, pristine kernel source with problematic parts removed) and applying a set of Debian patches. These patches typically implement essential fixes for serious bugs and security holes. The Debian version of the kernel packages has the form version-revision where version is the upstream version of the kernel (like 3.2.20) and revision determines the patchlevel. For example, the packages with version 3.2.20-1 are built from the linux_3.2.20.orig.tar.xz source, patched up to patchlevel 1. Certain packages include extra 'featuresets' not included in the upstream source, such as rt.
The general policy of the Debian kernel team is that a patch must either fix a bug or add hardware support, and must be based on a change already accepted by the upstream kernel maintainers. The change does not need to have been included in an upstream release yet. This policy allows the team to drop most patches when moving to a new upstream version, rather than having to maintain an increasing series of Debian-specific patches. The recommended procedure for inclusion of patches introducing optional features is to submit to the upstream maintainer.
To ensure that the latest kernel version, containing all the essential bug and security fixes is available on as many architectures as possible, starting with 2.6.12 the kernel team introduced a new packaging scheme. In it most of the kernel-related binary packages are built from a single source package linux (previously linux-2.6). The linux source package supports building of kernel images and headers for all currently supported architectures. Subsequent sections of this chapter document the naming and contents of the binary packages built from the linux source package.
The kind of hardware the particular kernel package is designed for is uniquely identified by the architecture, featureset, and flavour. Kernels for all architectures are built from the same Debian kernel source tree, which is obtained using the procedure described in . Each architecture usually has multiple flavours of the binary kernel images. Different flavours correspond to different kernel configuration files, used to build the binary images from the same kernel tree.
In order to build a working kernel with an extra featureset not provided by the upstream source, additional changes to the Debian kernel source are required. Again, multiple flavours of binary images may be built from the featureset tree. For example, the i386 architecture has a number of different flavours, such as 486, 686-pae and amd64, built from the common Debian kernel source. It also contains the rt featureset. The source tree for building the kernels for each of these featuresets is obtained by applying additional patches to the Debian kernel source. It may be used to build the rt-686-pae binary image flavours. The names of the Debian binary packages incorporate the name of the flavour and, if necessary, the name of the featureset (there is no need to worry about the name of the architecture, since Debian tools will only allow installation of the packages with "correct" architecture). If the arch does not have any featuresets, the featureset part is omitted from the name, as indicated by the square brackets below.
Package names also include the abiname, a small integer, which identifies the kernel's binary compatibility level. The kernels with different abinames are binary incompatible, so upgrading to a kernel with a different abiname will most likely require recompilation of third-party binary modules against the new kernel. The list of architecture-dependent packages together with a short description is given below.
These virtual packages provide (via dependencies) the latest
binary image and matching set of header files (respectively)
for a particular flavour. Example: linux-image-rt-686-pae
In Debian 6.0 (squeeze) and earlier, the headers
metapackages were
named linux-headers-2.6[-featureset]-flavour.
This package contains the binary kernel image and
pre-built binary modules for a particular
arch/featureset/flavour combination. Names of the files
installed by this package are
architecture-dependent. Typical locations of essential
files for the i386 architecture are:
This package provides Linux kernel headers for use by userspace programs,
such as GNU glibc and other system libraries.
To get the Debian kernel source at the current maximum patchlevel,
it is sufficient to install the latest linux-source-version
package and unpack the source, for example:
You can build all or selected kernel packages by following these instructions. You may be asked to do this in order to test a potential bug fix.
For Debian 6.0 (squeeze) and earlier versions, substitute the source package name linux-2.6 for linux.
Run the following commands:
Building binary packages for a single kernel flavour with debug info enabled (currently true for the 686-pae, amd64, rt-686-pae, rt-amd64 and s390x configurations) requires up to 10 GB space in the package directory and 300 MB in /tmp (or $TMPDIR).
Building with debug info disabled requires about 2 GB and 25 MB respectively. You can disable debug info by changing the value of debug-info to false in debian/config/arch/defines.
Building all binary packages for i386 or amd64 currently requires about 20 GB space in the package directory. Other architectures with no debug info or fewer drivers will require less space.
The source package includes a script to simplify the
process of building with extra patches. You can use this
by running commands such as:
You may then need to build the linux-base package as well:
However, if you need to change the configuration or make other changes, you should not use this script and should follow the instructions below.
It is possible to apply extra patches to the source before
starting the build. In the linux source package,
the default (non-featureset) patches are automatically
applied in the top level directory. If you are building
the linux-2.6 source package or building with a
featureset, you should first apply the existing patches by
running:
To change the configuration before building, for example
for the 686-pae flavour on i386, run the commands:
If the patches or configuration changes alter type definitions for the kernel, you may need to change the ABI name; see .
To build all possible packages for this architecture, run:
For example, to build only the binary packages for 686-pae
flavour on i386 architecture, use the following commands:
For Debian 6.0 (squeeze) and earlier versions, substitute the source package name linux-2.6 for linux.
To build a kernel image based on the kernel team's
unreleased development version:
First you must add a changelog entry for the new upstream version. If the new version is a release candidate, change the string -rc to ~rc. (In Debian package versions, a suffix beginning with ~ indicates a pre-release.)
The 'orig' tarball is generated by the genorig.py
script. It takes either a tarball and optional patch from
kernel.org, or a git repository. If you have a tarball, run
a command such as:
If you have a git repository, pass the name of its
directory:
Either of these will generate a file such as
../orig/linux_3.5~rc1.orig.tar.xz.
You can then combine this tarball with the Debian packaging
by running:
This section describes the simplest possible procedure to build a custom kernel the "Debian way". It is assumed that user is somewhat familiar with kernel configuration and build process. If that's not the case, it is recommended to consult the kernel documentation and many excellent online resources dedicated to it.
The easiest way to build a custom kernel (the kernel with
the configuration different from the one used in the
official packages) from the Debian kernel source is to use
the linux-source package and the make deb-pkg
target. First, prepare the kernel tree:
The build will use less disk space if the CONFIG_DEBUG_INFO
option is disabled (see ).
Debuginfo is only needed if you plan to use binary object
tools like crash, kgdb, and SystemTap on the kernel.
After the configuration process is finished, the new or
updated kernel configuration will be stored in
.config file in the top-level directory. The build
is started using the commands
For much more information about bootloaders and their configuration please check their documentation, which can be accessed using the commands man lilo, man lilo.conf, man grub, and so on. You can also look for documentation in the /usr/share/doc/package directories, with package being the name of the package involved.
Building a kernel from the "pristine" (also sometimes called "vanilla")
kernel source, distributed from
Some kernel modules are not included in the upstream or Debian kernel source, but are provided as third-party source packages. For some of the most popular out-of-tree modules, the binary Debian packages with modules built against the stock Debian kernels are provided. For example, if you are running stock Debian kernel 3.2.0-2-686-pae (use the uname -r command to verify the version) from the linux-image-3.2.0-2-686-pae package, and would like to use the squash filesystem, all you need to do is install squashfs-modules-3.2.0-2-686-pae binary package, which provides the neccessary binary kernel modules.
If you are not so lucky, and there are no binary module packages in the archive, there is a fair chance that the Debian archive contains the packaged source for the kernel modules. Names of such packages typically end in -source, for example squashfs-source, thinkpad-source, rt2x00-source and many others. These packages contain debianized source code of the kernel modules, suitable for building using the module-assistant (or m-a) script from the module-assistant package. Typical sequence to build a custom binary module package, matching a kernel 3.2.0-2-686-pae (as returned by uname -r) from the debianized source consists of the following steps:
Install a set of kernel headers, matching the kernel for
which the modules are going to be built:
Finally, in some rare circumstances, you might need to build the kernel modules from the upstream source packages. In that case, follow the documentation included with the package to build the modules. If the build process will require you to specify the directory with the kernel headers, matching the currently running kernel, for stock Debian kernels this directory is /usr/src/linux-headers-uname, provided by the linux-headers-uname package. Here uname is the output of the uname -r command. If you are building and running your own custom kernels, it is a good idea to keep the original build tree around, as it also can be used for out-of-tree module building.
The booting in Debian is a two-stage process, involving the initial RAM filesystem (initramfs for short, sometimes it is also referred to as initrd, which stands for initial RAM disk). First, the bootloader loads the kernel and initramfs into memory, and passes the execution control to the kernel. After basic initialization the kernel extracts the initramfs archive and mounts it as a temporary root filesystem. initramfs contains kernel modules and userspace programs required to initialize the physical or logical device(s) containing the real root filesystem. The init script on the initramfs loads modules and performs other neccessary initialization steps. At the end of this stage run-init deletes the initramfs from memory, mounts the real root filesystem and passes control to the /sbin/init program on it.
Two major goals are achieved with such setup: the kernel size is kept under control by allowing most of the drivers to be compiled as modules (in a initramfs-less setup the drivers neccessary for the boot-time initialization of the root device must be compiled into it) and allow the setups which require initialization which cannot be done in-kernel, but is performed by userspace utilities.
Since initramfs usually needs to be customized for the particular hardware/device configuration and kernel version, they are not included as a part of any package, but are generated on the fly at kernel installation time. Currently there are two tools in Debian capable of generating an initramfs: update-initramfs provided by initramfs-tools (default) and dracut-update-initramfs provided by the dracut package (experimental).
If changes are desired after the corresponding
linux-image has been installed, the initramfs needs to
be regenerated. This is achieved by the command
Occasionally it is useful to examine the contents of initramfs
to diagnose a problem or for educational purposes. They are
compressed cpio archives, which may be extracted
using the command
It is also possible to list the contents of an initramfs
using the cpio -t option or the command
The main goal of this handbook is to serve as a single access
point to all kernel-related documentation. It contains the
information about the Debian packaging of Linux kernel for
Debian 7.0 (wheezy). The latest released
version is always available from
Some of the commands mentioned in the text must be executed with superuser priviliges, either by becoming the root user or by using sudo. To distinguish between commands which may be executed by an unprivileged user and those requiring superuser privileges, commands are prepended by $ or # respectively. This symbol is not a part of the command.
This handbook is maintained within the
Many programs parse the kernel version string reported by the uname system call or command and expect to find at least 3 version components separated by dots. For compatibility, the official kernel packages currently add '.0' to the upstream version, but this will be dropped in wheezy+1.
An ABI (Application Binary Interface) is an interface between two software components, considered at the level of register allocation and memory layout. The ABI between the kernel and user-space is generally maintained carefully, and is not a concern here. However, the ABI between the kernel and its modules is not. In order to support out-of-tree modules, the kernel version should be changed when the ABI between the kernel and modules changes.
In official kernel packages, we change the abiname part of the kernel version to mark ABI changes that aren't due to a new upstream version. This part comes from the abiname setting in debian/config/defines. We use either a number or 'trunk' (for experimental), but for a custom package it should be some other string.
In order to avoid the need for users to rebuild out-of-tree modules frequently, we try to avoid changing the kernel ABI during updates to a Debian stable or oldstable release. Most importantly, we avoid making such changes without changing the ABI name, except where it appears that out-of-tree modules do not depend on that part of the ABI.
Bug fixes or configuration changes to the kernel may alter the ABI. If an exported function is conditional on CONFIG_FOO, or it uses a type whose definition depends on CONFIG_FOO, then turning CONFIG_FOO on or off changes the ABI of that function, and thus of the kernel as a whole. Enabling or changing the configuration of a single driver usually doesn't change the ABI, because most drivers don't export anything.
The kernel build process generates a 'symbol version' for each exported function or variable. This is a hash of the definitions that it depends on, and should change whenever the function's ABI changes. The kernel module loader detects incompatible modules by comparing symbol versions. The whole set of symbol versions represents the kernel ABI.
We collect the symbol versions for previously uploaded packages under the directory debian/abi and then compare the new kernel with those. If the ABI name is unchanged but the ABI itself is changed - except for additions, or changes that we have marked as acceptable - then the build is aborted.
If the kernel ABI has changed you must then change the ABI
name in debian/config/defines. Then run the
command
Kernel packages for Debian have historically had complex maintainer scripts which can invoke the initramfs builder and/or a boot loader, based on a mixture of file tests, explicit configuration through the file /etc/kernel-img.conf and debconf questions. Starting with Debian 6.0, this has been greatly simplified.
The following policy applies to Debian GNU/Linux 6.0 'squeeze' and later releases. Some parts may be applicable to kernels other than Linux, but this policy does not set any requirements for them.
The maintainer scripts in Linux kernel packages must use run-parts to invoke hook scripts in the corresponding subdirectory of /etc/kernel, e.g. the postinst script must invoke scripts in /etc/kernel/postinst.d.
The arguments given to all kernel hook scripts are the kernel
ABI version (the string that uname -r reports) and,
optionally, the absolute path to the kernel image. If the
second argument is missing then the path is
either /boot/vmlinuz-version or
/boot/vmlinux-version, according to
architecture convention. The environment variable
DEB_MAINT_PARAMS will contain the arguments given to
the kernel maintainer script, possibly single-quoted. In a
shell script, this variable can be parsed using:
Kernel hook scripts may be run under debconf. In this case
they must not use stdin and stdout, and should send all output
to stderr (fd 2). A shell script can ensure that it does this
using:
Packages for boot loaders that need to be updated whenever the files they load are modified (i.e. those that store a block list) must install hook scripts in /etc/kernel/postinst.d and /etc/kernel/postrm.d.
Since these boot loaders should be updated as the last step during installation/upgrade and removal, hook scripts for boot loaders must be named using the prefix zz- and no other packages may use this prefix or one that sorts later by the rules used by run-parts. A postrm hook script should warn but exit with code 0 if the boot loader configuration file still refers to the kernel image that has been removed.
These boot loader packages must be installable on the filesystem in a disabled state where they will not write to the boot sector or other special storage. While a boot loader is disabled, any kernel hooks it includes must do nothing except (optionally) printing a warning that the boot loader is disabled, and must exit successfully.
Packages for boot loaders that can provide a menu of kernel versions should install kernel hook scripts in order to update that menu.
Packages for boot loaders that need to be updated whenever the files they load are modified must also install hook scripts in /etc/initramfs/post-update.d. Initramfs builders must call these scripts using run-parts after they create, update or delete an initramfs. The arguments given to these hook scripts are the kernel ABI version and the absolute path to the initramfs image.
While a boot loader is disabled, any initramfs hook it includes must do nothing except (optionally) printing a warning that the boot loader is disabled, and must exit successfully.
Initramfs builders must install hook scripts in /etc/kernel/postinst.d and /etc/kernel/postrm.d, to create/update and delete the corresponding initramfs images. The postinst hook script must complete its work before returning.
During a kernel package installation, upgrade or removal, various
boot loader hooks may be invoked (in this order):
To avoid unnecessary updates, the hooks invoked at steps 1 and 2 may check whether $DPKG_MAINTSCRIPT_PACKAGE begins with linux-image- and do nothing in this case.
Kernel packages must not invoke boot loaders except via hooks. If /etc/kernel-img.conf contains do_bootloader = yes or equivalent, maintainer scripts that previously acted on this must warn that they are ignoring it. linux-base must also warn on upgrade that the default has changed. In Debian 7.0 'wheezy', this prohibition extends to initramfs builder packages.
The installer must not define do_bootloader, postinst_hook or postrm_hook in /etc/kernel-img.conf.
This handbook is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.
This is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.
A copy of the GNU General Public License is available as
Submitters are expected to run
Exceptions:
Many submitters report bugs with the wrong severity. We
interpret the criteria as follows and will adjust severity
as appropriate:
We do not use user-tags. In order to aid bug triage we
should make use of the standard tags
and forwarded field defined by the BTS. In
particular:
Generally we should not expect to be able to reproduce
bugs without having similar hardware. We should consider:
Depending on the technical sophistication of the submitter
and the service requirements of the system in question
(e.g. whether it's a production server) we can request one
or more of the following:
When a bug occurs in what upstream considers the current
or previous stable release, and we cannot fix it, we ask
the submitter to report it upstream
at
Many submitters search for a characteristic error message and treat this as indicating a specific bug. This can lead to many 'me too' follow-ups where, for example, the message indicates a driver bug and the second submitter is using a different driver from the original submitter.
In order to avoid the report turning into a mess of
conflicting information about two or more different bugs:
Where the original report describes more than one bug ('...and other thing...'), we should clone it and deal with each separately.
Patches should normally be reviewed and accepted by the relevant upstream maintainer (aside from necessary adjustments for an older kernel version) before being applied.
We should always be polite to submitters. Not only is
this implied by the
We will maintain general advice to submitters at
Debian kernel team keeps track of the kernel package bugs in
the Debian Bug Tracking System (BTS). For information on how
to use the system see
Nothing in this chapter is intended to keep you from filing a
bug against one of the Debian kernel packages. However, you should
recognize that the resources of the Debian kernel team are
limited, and efficient reaction to a bug is largely determined
by the amount and quality of the information included in the
bug report. Please help us to do a better job by using the
following guidelines when preparing to file the bug against
kernel packages:
When a bug is easy to reproduce locally but hard to get developers to reproduce (as is often true of workflow- or hardware-dependent bugs), it can be useful to compile and test a few versions to narrow down what changes introduced the regression.
To start, recreate the problem with a vanilla kernel:
Initialize the bisection process by declaring which versions worked
and did not work:
Install the package, reboot, and test.
At the end of the process, the name of the "first bad commit" is printed, which is very useful for tracking down the bug. Narrowing down the regression range with a few rounds is useful even if you don't get that far; in that case, run git bisect log to produce a log. If you are the visual sort of person, git bisect visualize with the gitk package installed can show what is happening between steps.
See Christian Couder's article "Fighting regressions with git bisect"
from
Linux device drivers come in the form of kernel modules - object files which may be loaded into the running kernel to extend its functionality. The list of currently loaded kernel modules can be obtained using the lsmod command, modules may be loaded using modprobe, and removed using modprobe -r. The depmod command may be used to regenerate the list of available modules (after installation of the new modules, for example), even though it is pretty unlikely that you will ever need to invoke it by hand.
Normally, the devices are detected and neccessary kernel modules are loaded by udev during boot time. Occasionally, one may need finer control over the loading of kernel modules, for example to pass the additional parameters to the module, force loading of some modules on startup, or prevent certain module(s) from being loaded.
If some modules are not loaded automatically by udev, but
you would like them to be loaded during boot, it is possible to force
it by listing the names of the modules in /etc/modules.
This will be scanned for the names of
the modules (one name per line), which will then be loaded using
modprobe. You can also specify the arguments for the modules.
For example, a typical /etc/modules might look like that
To add custom arguments to the modules loaded by udev
early in the boot process, you need to create a custom
configuration file for modprobe, which udev
uses to load the modules. For example, to pass an
atapi_enabled=1 argument to the libata kernel
module, create /etc/modprobe.d/local file with a
following line:
Sometimes two different modules claim support for the same
device, usually because two slightly different versions of the
device exist, requiring different kernel modules to operate. In
such situation udev loads both kernel modules, with
unpredictable results. To avoid this problem, you can prevent
any module (let's say, tulip) from loading by creating
an arbitrarily named file, containing a line