<?xml version='1.0' encoding='utf-8'?>
<!-- -*- DocBook -*- -->
<chapter id="ch-common-tasks">
<?dbhtml filename="ch-common-tasks.html" ?>
<title>Common kernel-related tasks</title>
<section id="s-common-getting"><title>Obtaining the Debian kernel source</title>
<para>
To get the Debian kernel source, it is sufficient to install the latest
<package>linux-source-<replaceable>version</replaceable></package> package and unpack
the source, for example:
</para>
<screen>
<prompt>#</prompt> <userinput>apt-get install linux-source-4.3</userinput>
<prompt>$</prompt> <userinput>tar xaf /usr/src/linux-source-4.3.tar.xz</userinput>
</screen>
<para>
The unpacked source tree then will be available in
<filename>linux-source-4.3</filename> directory.
</para>
</section>

<section id="s-common-building"><title>Building a custom kernel from Debian kernel source</title>
<para>
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.
</para>
<para>
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 <package>linux-source</package> package and the
<command>make bindeb-pkg</command> target.  First, prepare the kernel tree:
</para>
<screen>
<prompt>#</prompt> <userinput>apt-get install linux-source-4.3</userinput>
<prompt>$</prompt> <userinput>tar xaf /usr/src/linux-source-4.3.tar.xz</userinput>
<prompt>$</prompt> <userinput>cd linux-source-4.3</userinput>
</screen>
<para>
The kernel now needs to be configured, that is you have to set the kernel
options and select the drivers which are going to be included, either as
built-in, or as external modules.
</para>
<para>
It is possible to reuse an old configuration file by placing it as a
<filename>.config</filename> file in the top-level directory.
Alternately, you can use the default configuration for the
architecture (<command>make defconfig</command>) or generate a
configuration based on the running kernel and the currently loaded
modules (<command>make localmodconfig</command>).
</para>
<para>
If you reuse a Debian kernel config file, you may need to disable
module signing (<command>scripts/config --disable
MODULE_SIG</command>) or enable signing with an ephemeral key
(<command>scripts/config --set-str MODULE_SIG_KEY
certs/signing_key.pem</command>).  The build will use less time and
disk space (see <xref linkend="s-common-size"/>) if debug information
is disabled (<command>scripts/config --disable DEBUG_INFO</command>).
Debuginfo is only needed if you plan to use binary object tools like
crash, kgdb, and SystemTap on the kernel.
</para>
<para>
The kernel build infrastructure offers a number of targets, which
invoke different configuration frontends.  For example, one can use
console-based menu configuration by invoking the command
</para>
<screen>
<prompt>$</prompt> <userinput>make nconfig</userinput>
</screen>
<para>
Instead of <literal>nconfig</literal> one can use <literal>oldconfig</literal>
(text-based line-by-line configuration frontend) or <literal>xconfig</literal>
(graphical configuration frontend).  Note that different frontends may require different additional
libraries and utilities to be installed to function properly.  For example, the
<literal>nconfig</literal> frontend requires the <literal>ncurses</literal>
library, which is provided by the <package>libncurses-dev</package> package.
</para>
<para>
After the configuration process is finished, the new or updated kernel
configuration will be stored in <filename>.config</filename> file in the
top-level directory.  The build is started using the commands
</para>
<screen>
<prompt>$</prompt> <userinput>make clean</userinput>
<prompt>$</prompt> <userinput>make bindeb-pkg</userinput>
</screen>
<para>
As a result of the build, a custom kernel package
<filename>linux-image-3.2.19_3.2.19-1_i386.deb</filename> (name will reflect the
version of the kernel and build number) will be created in the directory one
level above the top of the tree.  It may be installed using
<command>dpkg</command> just as any other package:
</para>
<screen>
<prompt>#</prompt> <userinput>dpkg -i ../linux-image-3.2.19_3.2.19-1_i386.deb</userinput>
</screen>
<para>
This command will unpack the kernel, generate the initrd if necessary (see
<xref linkend="ch-initramfs"/> for details), and configure the bootloader to make
the newly installed kernel the default one.  If this command completed without
any problems, you can reboot using the
</para>
<screen>
<prompt>#</prompt> <userinput>shutdown -r now</userinput>
</screen>
<para>
command to boot the new kernel.
</para>
<para>
For much more information about bootloaders and their configuration please
check their documentation.  For GRUB this can be accessed using the command
<command>info grub</command>.  You can also look for documentation in the
<filename>/usr/share/doc/<replaceable>package</replaceable></filename> directories,
with <replaceable>package</replaceable> being the name of the
package involved.
</para>
</section>

<section id="s-kernel-org-package"><title>Building a custom kernel from the "pristine" kernel source</title>
<para>
Building a kernel from the "pristine" (also sometimes called "vanilla") kernel
source, distributed from <ulink
url="https://www.kernel.org">www.kernel.org</ulink> and its mirrors, may be
occasionally useful for debugging or in the situations when a newer kernel
version is desired.  The procedure differs only in obtaining the kernel source:
instead of unpacking the kernel source from Debian packages, the "pristine"
source is downloaded using your favourite browser or using wget, as follows:
</para>
<screen>
<prompt>$</prompt> <userinput>wget https://kernel.org/pub/linux/kernel/v4.x/linux-4.3.tar.xz</userinput>
</screen>
<para>
The integrity of the downloaded archive may be verified by fetching the
corresponding cryptographic signature
</para>
<screen>
<prompt>$</prompt> <userinput>wget https://kernel.org/pub/linux/kernel/v4.x/linux-4.3.tar.sign</userinput>
</screen>
<para>
and running this command (<package>gnupg</package> package must be installed):
</para>
<screen>
<prompt>$</prompt> <userinput>unxz -c linux-4.3.tar.xz | gpg --verify linux-4.3.tar.sign -</userinput>
</screen>
<para>
Successful verification results in output similar to the one below:
</para>
<screen>
<computeroutput>gpg: Signature made Mon 21 May 2012 01:48:14 AM CEST using RSA key ID 00411886
gpg: Good signature from "Linus Torvalds &lt;torvalds@linux-foundation.org&gt;"
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: ABAF 11C6 5A29 70B1 30AB  E3C4 79BE 3E43 0041 1886</computeroutput>
</screen>
<para>
After that the archive may be unpacked using
</para>
<screen>
<prompt>$</prompt> <userinput>tar xaf linux-4.3.tar.xz</userinput>
<prompt>$</prompt> <userinput>cd linux-4.3</userinput>
</screen>
<para>
The unpacked kernel tree (in <filename>linux-4.3</filename>) can now be
configured and built, in the same way described in the previous section.
</para>
</section>
<section id="s-common-out-of-tree"><title>Out-of-tree kernel modules</title>
<para>
Some kernel modules are not included in the upstream or Debian kernel source,
but are provided as third-party source packages.
There is a fair chance that the Debian archive contains the
<emphasis>source</emphasis> for the kernel modules, packaged for use
with the Dynamic Kernel Module System (DKMS), with a package name
ending with <literal>-dkms</literal>.  Alternatively, it might be
packaged for use with Debian's module-assistant (m-a), with a package
name ending with <literal>-source</literal>.
</para>

<section id="s-common-out-of-tree-dkms"><title>Building modules with DKMS</title>
<para>
Check the current kernel release by running <command>uname
-r</command>.  If it shows, for example,
<literal>5.10.0-16-amd64</literal>, you need the package
<package>linux-headers-5.10.0-16-amd64</package>.  However, usually
you should not install this directly.  Instead, note the "flavour"
name that appears after the four numbers, which in this case is
<literal>amd64</literal>.  You can then run:
</para>
<screen>
<prompt>#</prompt> <userinput>apt-get install linux-headers-<replaceable>flavour</replaceable> <replaceable>module-name</replaceable>-dkms</userinput>
</screen>
<para>
The installation of these packages will automatically invoke DKMS to
build and install the module(s) for the current kernel release.
Future kernel package upgrades will also automatically invoke DKMS to
rebuild and install the module(s).
</para>
</section>

<section id="s-common-out-of-tree-m-a"><title>Building modules with module-assistant</title>
<para>
First, install module-assistant:
</para>
<screen>
<prompt>#</prompt> <userinput>apt-get install module-assistant</userinput>
</screen>
<para>
To build a custom binary module package for the currently running
kernel:
</para>
<screen>
<prompt>#</prompt> <userinput>m-a a-i <replaceable>module-name</replaceable>-source</userinput>
</screen>
<para>
Check out the <command>module-assistant</command> documentation (<command>man
module-assistant</command>) for other options and much more information on how
to use it.
</para>
</section>

<section id="s-common-out-of-tree-unpackaged"><title>Building unpackaged modules</title>
<para>
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
<filename>/usr/src/linux-headers-<replaceable>uname</replaceable></filename>, provided
by the <package>linux-headers-<replaceable>uname</replaceable></package> package.
Here <replaceable>uname</replaceable> is the output of the
<command>uname -r</command> 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.
</para>
</section>

<section id="s-common-out-of-tree-signing"><title>Out-of-tree modules and Secure Boot</title>
<para>
In case your computer has UEFI Secure Boot enabled, the Debian
packaged kernel will normally only allow modules signed by a trusted
key to be loaded.  In order to load the modules you build, you need
to either:
</para>
<itemizedlist>
<listitem>
<para>
Generate a signing key, add it to the trust list of your computer, and
use it to sign all out-of-tree modules; or
</para>
</listitem>
<listitem>
<para>
Disable Secure Boot enforcement
</para>
</listitem>
</itemizedlist>
<para>
Both options are documented on the Debian wiki's
<ulink
url="https://wiki.debian.org/SecureBoot#MOK_-_Machine_Owner_Key">SecureBoot
page, under "MOK - Machine Owner Key"</ulink>.
</para>
</section>

</section>

<section id="s-common-official"><title>Rebuilding official Debian kernel packages</title>
<para>
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.
</para>
<section><title>Preparation</title>
<para>
Run the following commands:
</para>
<variablelist>
<varlistentry>
<term><prompt>#</prompt> <userinput>apt-get install build-essential</userinput></term>
<term><prompt>#</prompt> <userinput>apt-get build-dep linux</userinput></term>
<listitem>
<para>
This will install the packages required by the kernel build process.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><prompt>$</prompt> <userinput>apt-get source linux</userinput></term>
<listitem>
<para>
This will download and unpack the <package>linux</package> source package,
making the tree available in the
<filename>linux-<replaceable>version</replaceable></filename> directory.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><prompt>$</prompt> <userinput>cd linux-<replaceable>version</replaceable></userinput></term>
<listitem>
<para>
Enter the source directory.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><prompt>$</prompt> <userinput>export MAKEFLAGS=-j$(nproc)</userinput></term>
<listitem>
<para>
Enable parallel builds using one job per CPU by default.
</para>
</listitem>
</varlistentry>
</variablelist>
<section id="s-common-size"><title>Disk space requirements</title>
<para>
Building binary packages for a single kernel flavour requires up to
15 GB space in the package directory and 300 MB in
<filename>/tmp</filename> (or <envar>$TMPDIR</envar>).
</para>
<para>
Building with debug info disabled requires about 2 GB and 25 MB respectively.
In packages of kernel version 5.17 or later, you can disable building
debug info through build profiles:
</para>
<screen>
<prompt>$</prompt> <userinput>export DEB_BUILD_PROFILES='pkg.linux.nokerneldbg pkg.linux.nokerneldbginfo'</userinput>
</screen>
<para>
In older package versions, you must change the value of
<literal>debug-info</literal> to <literal>false</literal> in
<filename>debian/config/<replaceable>arch</replaceable>/defines</filename>,
if it's set there, or in
<filename>debian/config/defines</filename> otherwise.
</para>
<para>
Building all binary packages for i386 or amd64 currently requires
about 50 GB space in the package directory.  Other architectures with
fewer drivers will require less space.
</para>
</section>

</section>

<section><title>Simple patching and building</title>
<para>
The source package includes a script to simplify the process of building with
extra patches.  You can use this by running commands such as:
</para>
<screen>
<prompt>#</prompt> <userinput>apt-get install devscripts</userinput>
<prompt>$</prompt> <userinput>debian/bin/test-patches ../fix-bug123456.patch ../add-foo-driver.patch</userinput>
</screen>
<para>
This script has options to control the flavour, featureset, etc.  For a summary
of the options, run:
</para>
<screen>
<prompt>$</prompt> <userinput>debian/bin/test-patches</userinput>
</screen>
<para>
However, if you need to change the configuration or make other changes, you
should not use this script and should follow the instructions below.
</para>
<warning>
<para>
Older versions of the <command>test-patches</command> script (before
package version 6.1.27-1), have some important bugs and limitations:
</para>
<itemizedlist>
<listitem>
<para>
The <package>linux-image</package> package it builds will usually
replace or conflict with the currently installed kernel package.
</para>
</listitem>
<listitem>
<para>
The <package>linux-headers</package> package it builds won't be
installable.
</para>
</listitem>
<listitem>
<para>
In package versions from 5.17 onward, it is not possible to disable
building debug info.
</para>
</listitem>
</itemizedlist>
<para>
To avoid these bugs in older versions of the source package, follow
the instructions below.
</para>
</warning>
</section>

<section><title>Applying patches or configuration changes</title>
<para>
It is possible to apply extra patches to the source before starting the build.
In the <package>linux</package> source package, the default (non-featureset)
patches are automatically applied in the top level directory.
</para>
<para>
The patched source appears in the following directories.
</para>
<variablelist>
<varlistentry>
<term>default source:</term>
<listitem>
<para>
top level
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>source with featureset:</term>
<listitem>
<para>
<filename>debian/build/source_<replaceable>featureset</replaceable></filename>
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
You should apply the extra patches in the appropriate directory.  In the
<package>linux</package> source package you can use the
<command>quilt</command> utility to do this.
</para>
<para>
You should also change the ABI name so that the resulting packages are
co-installable with the current kernel packages; see <xref
linkend="s-abi-name"/>.
</para>
<para>
To change the configuration before building, for example for the 686-pae
flavour on i386, run the commands:
</para>
<screen>
<prompt>$</prompt> <userinput>make -f debian/rules.gen setup_i386_none_686-pae</userinput>
<prompt>$</prompt> <userinput>make -C debian/build/build_i386_none_686-pae nconfig</userinput>
</screen>
</section>

<section><title>Building many packages</title>
<para>
To build all possible packages for this architecture, run:
</para>
<screen>
<prompt>$</prompt> <userinput>dpkg-buildpackage -b -nc -uc</userinput>
</screen>
<para>
To build all architecture-dependent packages, run:
</para>
<screen>
<prompt>$</prompt> <userinput>dpkg-buildpackage -B -nc -uc</userinput>
</screen>
<para>
To build all architecture-independent packages, run:
</para>
<screen>
<prompt>$</prompt> <userinput>dpkg-buildpackage -A -nc -uc</userinput>
</screen>
</section>

<section><title>Building packages for one flavour</title>
<para>
For example, to build only the binary packages for 686-pae flavour on i386
architecture, use the following commands:
</para>
<screen>
<prompt>$</prompt> <userinput>debian/rules source</userinput>
<prompt>$</prompt> <userinput>DEB_RULES_REQUIRES_ROOT=no make -f debian/rules.gen binary-arch_i386_none_686-pae</userinput>
</screen>
<para>
The target in this command has the general form of
<literal><replaceable>target</replaceable>_<replaceable>arch</replaceable>_<replaceable>featureset</replaceable>_<replaceable>flavour</replaceable></literal>.
Replace the <literal><replaceable>featureset</replaceable></literal> with
<literal>none</literal> if you do not want any of the extra featuresets.  This
command will build the linux image and kernel headers packages.  You may also
need the <package>linux-headers-<replaceable>version</replaceable>-common</package>
binary package, which can be built using the commands:
</para>
<screen>
<prompt>$</prompt> <userinput>debian/rules source</userinput>
<prompt>$</prompt> <userinput>DEB_RULES_REQUIRES_ROOT=no make -f debian/rules.gen binary-indep_none_real</userinput>
</screen>
<para>
The target in this command has the general form of
<literal>binary-indep_<replaceable>featureset</replaceable>_real</literal>
</para>
</section>

</section>

<section id="s-common-official-vcs"><title>Building a development version of the Debian kernel package</title>
<para>
To build a kernel image based on the kernel team's unreleased development
version:
</para>
<variablelist>
<varlistentry>
<term><prompt>#</prompt> <userinput>apt-get install build-essential rsync git</userinput></term>
<term><prompt>#</prompt> <userinput>apt-get build-dep linux</userinput></term>
<listitem>
<para>
The last two commands will install the build dependencies required by the
kernel build process.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><prompt>$</prompt> <userinput>git clone -b <replaceable>dist</replaceable> --single-branch https://salsa.debian.org/kernel-team/linux.git</userinput></term>
<listitem>
<para>
This will check out the Debian packaging.  <replaceable>dist</replaceable> is
normally the distribution codename such as <literal>wheezy</literal> or
<literal>sid</literal> (unstable).  For the very latest version, usually based
on an upstream release candidate, use <literal>master</literal>.  Note that
this will download several hundred megabytes of data.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><prompt>$</prompt> <userinput>apt-get source -d linux</userinput></term>
<listitem>
<para>
This will download the <package>linux</package> upstream source (and the last
released Debian patches).  Depending on which version you are trying to build,
you might need to override APT's version selection or download a tarball from
<ulink url="https://people.debian.org">people.debian.org</ulink> instead.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><prompt>$</prompt> <userinput>cd linux</userinput></term>
<term><prompt>$</prompt> <userinput>debian/rules orig</userinput></term>
<listitem>
<para>
This unpacks the upstream source and merges it with the Debian packaging.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><prompt>$</prompt> <userinput>debian/rules debian/control</userinput></term>
<listitem>
<para>
This generates a Debian package control file based on the current definitions
of the various kernel flavours which can be built.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><prompt>$</prompt> <userinput>DEB_RULES_REQUIRES_ROOT=no debian/rules <replaceable>target</replaceable></userinput></term>
<listitem>
<para>
Finally, build binary packages as explained in <xref
linkend="s-common-official"/>.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>

<section id="s-gen-orig"><title>Generating orig tarball from newer upstream</title>
<para>
First you must add a changelog entry for the new upstream version.  If the new
version is a release candidate, change the string <literal>-rc</literal> to
<literal>~rc</literal>.  (In Debian package versions, a suffix beginning with
<literal>~</literal> indicates a pre-release.)
</para>
<para>
The 'orig' tarball is generated by the <command>genorig.py</command>
script, which requires an upstream Git repository.  For Debian 12
"bookworm" onward, this can be a remote repository; for older stable
branches it must be local.  Run:
</para>
<screen>
<prompt>$</prompt> <userinput>debian/bin/genorig.py <replaceable>repository</replaceable></userinput>
</screen>
<para>
This will generate a file such as
<filename>../orig/linux_5.19~rc6.orig.tar.xz</filename>.  You can then combine
this tarball with the Debian packaging by running:
</para>
<screen>
<prompt>$</prompt> <userinput>debian/rules orig</userinput>
</screen>
</section>

</chapter>