/usr/share/doc/debian-kernel-handbook/kernel-handbook.html/ch-update-hooks.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">

<html>

<head>

<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">

<title>Debian Linux Kernel Handbook - Package maintainer scripts and hooks</title>

<link href="index.html" rel="start">
<link href="ch-initramfs.html" rel="prev">
<link href="ch-bugs.html" rel="next">
<link href="index.html#contents" rel="contents">
<link href="index.html#copyright" rel="copyright">
<link href="ch-scope.html" rel="chapter" title="1 About this handbook">
<link href="ch-source.html" rel="chapter" title="2 Debian kernel source">
<link href="ch-packaging.html" rel="chapter" title="3 Debian kernel packages">
<link href="ch-common-tasks.html" rel="chapter" title="4 Common kernel-related tasks">
<link href="ch-versions.html" rel="chapter" title="5 Version numbers and ABIs">
<link href="ch-modules.html" rel="chapter" title="6 Managing the kernel modules">
<link href="ch-initramfs.html" rel="chapter" title="7 Managing the initial ramfs (initramfs) archive">
<link href="ch-update-hooks.html" rel="chapter" title="8 Package maintainer scripts and hooks">
<link href="ch-bugs.html" rel="chapter" title="9 Reporting and handling bugs">
<link href="ch-scope.html#s1.1" rel="section" title="1.1 Scope">
<link href="ch-scope.html#s-authors" rel="section" title="1.2 Authors and Contributors">
<link href="ch-source.html#s-changes" rel="section" title="2.1 Changes to the pristine kernel source">
<link href="ch-source.html#s-patches" rel="section" title="2.2 Debian kernel patches">
<link href="ch-source.html#s-acceptance" rel="section" title="2.3 Policy for patch acceptance">
<link href="ch-packaging.html#s-source-pkg" rel="section" title="3.1 Source package">
<link href="ch-packaging.html#s-arch-indep" rel="section" title="3.2 Architecture-independent packages">
<link href="ch-packaging.html#s-arch-dep" rel="section" title="3.3 Architecture-dependent packages">
<link href="ch-common-tasks.html#s-common-getting" rel="section" title="4.1 Obtaining the Debian kernel source">
<link href="ch-common-tasks.html#s-common-official" rel="section" title="4.2 Rebuilding official Debian kernel packages">
<link href="ch-common-tasks.html#s-common-official-vcs" rel="section" title="4.3 Building a development version of the Debian kernel package">
<link href="ch-common-tasks.html#s-gen-orig" rel="section" title="4.4 Generating orig tarball from newer upstream">
<link href="ch-common-tasks.html#s-common-building" rel="section" title="4.5 Building a custom kernel from Debian kernel source">
<link href="ch-common-tasks.html#s-kernel-org-package" rel="section" title="4.6 Building a custom kernel from the &quot;pristine&quot; kernel source">
<link href="ch-common-tasks.html#s-common-out-of-tree" rel="section" title="4.7 Building out-of-tree kernel modules">
<link href="ch-versions.html#s-version-types" rel="section" title="5.1 The different types of version">
<link href="ch-versions.html#s-abi" rel="section" title="5.2 The kernel ABI">
<link href="ch-initramfs.html#s-initramfs-gen-tools" rel="section" title="7.1 Initramfs generation tools">
<link href="ch-initramfs.html#s-initramfs-regen" rel="section" title="7.2 Regenerating the initramfs">
<link href="ch-initramfs.html#s-initramfs-exam" rel="section" title="7.3 Examining the initramfs contents">
<link href="ch-update-hooks.html#s-kernel-hooks" rel="section" title="8.1 Kernel hooks">
<link href="ch-update-hooks.html#s-kernel-hooks-loader" rel="section" title="8.2 Kernel hooks required for boot loaders">
<link href="ch-update-hooks.html#s-initramfs-hooks" rel="section" title="8.3 Initramfs hooks">
<link href="ch-update-hooks.html#s-kernel-hooks-initramfs" rel="section" title="8.4 Kernel hooks required for initramfs builders">
<link href="ch-update-hooks.html#s-loader-optimisation" rel="section" title="8.5 Optimising boot loader updates">
<link href="ch-update-hooks.html#s-deprecation" rel="section" title="8.6 Deprecated features">
<link href="ch-update-hooks.html#s-init-config" rel="section" title="8.7 Initial configuration by the installer">
<link href="ch-bugs.html#s9.1" rel="section" title="9.1 Bug handling policy for the kernel team">
<link href="ch-bugs.html#s9.2" rel="section" title="9.2 Filing a bug against a kernel package">
<link href="ch-common-tasks.html#s4.2.1" rel="subsection" title="4.2.1 Preparation">
<link href="ch-common-tasks.html#s-common-size" rel="subsection" title="4.2.1.1 Disk space requirements">
<link href="ch-common-tasks.html#s4.2.2" rel="subsection" title="4.2.2 Simple patching and building">
<link href="ch-common-tasks.html#s4.2.3" rel="subsection" title="4.2.3 Applying patches or configuration changes">
<link href="ch-common-tasks.html#s4.2.4" rel="subsection" title="4.2.4 Building many packages">
<link href="ch-common-tasks.html#s4.2.5" rel="subsection" title="4.2.5 Building packages for one flavour">
<link href="ch-versions.html#s-abi-name" rel="subsection" title="5.2.1 The ABI name">
<link href="ch-versions.html#s-abi-maintenance" rel="subsection" title="5.2.2 Maintaining and updating the ABI">
<link href="ch-bugs.html#s9.1.1" rel="subsection" title="9.1.1 Required information">
<link href="ch-bugs.html#s9.1.2" rel="subsection" title="9.1.2 Severities">
<link href="ch-bugs.html#s9.1.3" rel="subsection" title="9.1.3 Tagging">
<link href="ch-bugs.html#s9.1.4" rel="subsection" title="9.1.4 Analysis by maintainers">
<link href="ch-bugs.html#s9.1.5" rel="subsection" title="9.1.5 Testing by submitter">
<link href="ch-bugs.html#s9.1.6" rel="subsection" title="9.1.6 Keeping bugs separate">
<link href="ch-bugs.html#s9.1.7" rel="subsection" title="9.1.7 Applying patches">
<link href="ch-bugs.html#s9.1.8" rel="subsection" title="9.1.8 Talking to submitters">
<link href="ch-bugs.html#s9.2.1" rel="subsection" title="9.2.1 Bisecting (finding the upstream version that introduced a bug)">

</head>

<body>

<p><a name="ch-update-hooks"></a></p>
<hr>

<p>
[ <a href="ch-initramfs.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ <a href="ch-scope.html">1</a> ]
[ <a href="ch-source.html">2</a> ]
[ <a href="ch-packaging.html">3</a> ]
[ <a href="ch-common-tasks.html">4</a> ]
[ <a href="ch-versions.html">5</a> ]
[ <a href="ch-modules.html">6</a> ]
[ <a href="ch-initramfs.html">7</a> ]
[ 8 ]
[ <a href="ch-bugs.html">9</a> ]
[ <a href="ch-bugs.html">next</a> ]
</p>

<hr>

<h1>
Debian Linux Kernel Handbook
<br>Chapter 8 - Package maintainer scripts and hooks
</h1>

<hr>

<p>
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
<samp>/etc/kernel-img.conf</samp> and debconf questions.  Starting with Debian
6.0, this has been greatly simplified.
</p>

<p>
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.
</p>

<hr>

<h2 id="s-kernel-hooks">8.1 Kernel hooks</h2>

<p>
The maintainer scripts in Linux kernel packages must use <samp>run-parts</samp>
to invoke hook scripts in the corresponding subdirectory of
<samp>/etc/kernel</samp>, e.g.  the <samp>postinst</samp> script must invoke
scripts in <samp>/etc/kernel/postinst.d</samp>.
</p>

<p>
The arguments given to all kernel hook scripts are the kernel ABI version (the
string that <samp>uname -r</samp> reports) and, optionally, the absolute path
to the kernel image.  If the second argument is missing then the path is either
<samp>/boot/vmlinuz-<em>version</em></samp> or
<samp>/boot/vmlinux-<em>version</em></samp>, according to architecture
convention.  The environment variable <samp>DEB_MAINT_PARAMS</samp> will
contain the arguments given to the kernel maintainer script, possibly
single-quoted.  In a shell script, this variable can be parsed using:
</p>

<pre>
     eval set -- &quot;$DEB_MAINT_PARAMS&quot;
</pre>

<p>
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:
</p>

<pre>
     exec &lt;/dev/null &gt;&amp;2
</pre>

<hr>

<h2 id="s-kernel-hooks-loader">8.2 Kernel hooks required for boot loaders</h2>

<p>
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
<samp>/etc/kernel/postinst.d</samp> and <samp>/etc/kernel/postrm.d</samp>.
</p>

<p>
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 <samp>zz-</samp> and no other packages may use this prefix or
one that sorts later by the rules used by <samp>run-parts</samp>.  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.
</p>

<p>
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.
</p>

<p>
Packages for boot loaders that can provide a menu of kernel versions should
install kernel hook scripts in order to update that menu.
</p>

<hr>

<h2 id="s-initramfs-hooks">8.3 Initramfs hooks</h2>

<p>
Packages for boot loaders that need to be updated whenever the files they load
are modified must also install hook scripts in
<samp>/etc/initramfs/post-update.d</samp>.  Initramfs builders must call these
scripts using <samp>run-parts</samp> 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.
</p>

<p>
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.
</p>

<hr>

<h2 id="s-kernel-hooks-initramfs">8.4 Kernel hooks required for initramfs builders</h2>

<p>
Initramfs builders must install hook scripts in
<samp>/etc/kernel/postinst.d</samp> and <samp>/etc/kernel/postrm.d</samp>, to
create/update and delete the corresponding initramfs images.  The postinst hook
script must complete its work before returning.
</p>

<hr>

<h2 id="s-loader-optimisation">8.5 Optimising boot loader updates</h2>

<p>
During a kernel package installation, upgrade or removal, various boot loader
hooks may be invoked (in this order):
</p>
<ol type="1" start="1" >
<li>
<p>
A <samp>postinst_hook</samp> or <samp>postrm_hook</samp> command set by the
user or the installer in <samp>/etc/kernel-img.conf</samp>
</p>
</li>
</ol>
<ol type="1" start="2" >
<li>
<p>
A hook script in <samp>/etc/initramfs/post-update.d</samp>
</p>
</li>
</ol>
<ol type="1" start="3" >
<li>
<p>
A hook script in <samp>/etc/kernel/postinst.d</samp> or
...<samp>/postrm.d</samp>
</p>
</li>
</ol>

<p>
To avoid unnecessary updates, the hooks invoked at steps 1 and 2 may check
whether <samp>$DPKG_MAINTSCRIPT_PACKAGE</samp> begins with
<samp>linux-image-</samp> and do nothing in this case.
</p>

<hr>

<h2 id="s-deprecation">8.6 Deprecated features</h2>

<p>
Kernel packages must not invoke boot loaders except via hooks.  If
<samp>/etc/kernel-img.conf</samp> contains <samp>do_bootloader = yes</samp> or
equivalent, maintainer scripts that previously acted on this must warn that
they are ignoring it.  <samp>linux-base</samp> must also warn on upgrade that
the default has changed.  In Debian 7.0 'wheezy', this prohibition extends to
initramfs builder packages.
</p>

<hr>

<h2 id="s-init-config">8.7 Initial configuration by the installer</h2>

<p>
The installer must not define <samp>do_bootloader</samp>,
<samp>postinst_hook</samp> or <samp>postrm_hook</samp> in
<samp>/etc/kernel-img.conf</samp>.
</p>

<hr>

<p>
[ <a href="ch-initramfs.html">previous</a> ]
[ <a href="index.html#contents">Contents</a> ]
[ <a href="ch-scope.html">1</a> ]
[ <a href="ch-source.html">2</a> ]
[ <a href="ch-packaging.html">3</a> ]
[ <a href="ch-common-tasks.html">4</a> ]
[ <a href="ch-versions.html">5</a> ]
[ <a href="ch-modules.html">6</a> ]
[ <a href="ch-initramfs.html">7</a> ]
[ 8 ]
[ <a href="ch-bugs.html">9</a> ]
[ <a href="ch-bugs.html">next</a> ]
</p>

<hr>

<p>
Debian Linux Kernel Handbook
</p>

<address>
version 1.0.16, Fri 14 Aug 12:53:11 CEST 2015<br>
<br>
<a href="ch-scope.html#s-authors">The Debian Kernel Handbook Project</a><br>
<br>
</address>
<hr>

</body>

</html>
debian-kernel-handbook 1.0.16 / usr / share / doc / debian-kernel-handbook / kernel-handbook.html / ch-update-hooks.html
