.\" Hey, Emacs! This is an -*- nroff -*- source file.
.\" Copyright (c) 2000 Manoj Srivastava <srivasta@debian.org>
.\"
.\" This is free documentation; you can 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 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual 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.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
.\" USA.
.\"
.\" $Id: kernel-img.conf.5,v 1.18 2002/04/12 20:03:33 srivasta Exp $
.\"
.TH KERNEL\-IMG.CONF 5 "Mar 21 2000" "Debian" "Debian GNU/Linux manual" 
.\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection
.\" other parms are allowed: see man(7), man(1)
.SH NAME
kernel\-img.conf \- site wide configuration file for kernel image packages
.SH SYNOPSIS
.I /etc/kernel\-img.conf
.SH "DESCRIPTION"
The file 
.I /etc/kernel\-img.conf
is a simple file looked at by the kernel image post installation
process to allow local options for handling some aspects of the
installation, overriding the defaults built into the image itself. 
.PP
The format of the file is a simple 
.B VAR = VALUE 
pair. Boolean values may be specified as
.I Yes, True, 1,
and
.I No, False, 0,
and are case insensitive. 
This file is automatically created by the installation script if
it does not exist, and neither does the symbolic link
.I /vmlinuz.
The script asks the user whether the symbolic link should be created, 
and stashes the answer into 
.I /etc/kernel\-img.conf
.PP
At the moment, the user modifiable variables supported are:
.TP
.B image_in_boot
Set to Yes if you want the kernel image 
.I vmlinuz 
in 
.I /boot 
rather than the default 
.I /.  
Defaults to No.
.TP
.B do_symlinks
By default, the kernel image post installation script shall create or
update the 
.I /vmlinuz
and 
.I /vmlinuz.old 
symbolic links. This is true if a 
.I /vmlinuz
link already exists, however, in absence of
.I /vmlinuz,
the script looks to see if this configuration file exists. If it does
not, the configuration script asks the user whether to create the
symbolic link, and stashes the answer in a newly created
.I /etc/kernel-img.conf.
If the configuration file already exists, and 
if this option is set to No, no symbolic link is ever created. This
for people who have other means of booting their machines, and do not
like the symbolic links cluttering up their / directory.  Defaults to Yes. 
.TP
.B minimal_swap
By default, if the /vmlinuz symbolic link does not point to an image
which is the same as the image being installed, the postinst moves
/vmlinuz to /vmlinuz.old, and creates a symbolic link to the kernel
image in /vmlinuz (the exception is to prevent both /vmlinuz and
/vmlinuz.old from pointing to the current kernel image -- potentially
disastrous if the current image is defective or lacking in any
way). However, if this option is enabled, no action is taken if
/vmlinuz.old points to the currently installed image (by default, the
symbolic links are swapped).  Defaults to no.
.TP
.B no_symlinks
Whether to use symlinks to the 
.I image
file. 
Mutually exclusive to 
.I reverse_symlinks. 
Can be used with
.I image_in_boot. 
If set to Yes, the image is placed in vmlinuz (instead of /boot/vmlinuz-X.X.XX).
The old vmlinuz is moved to vmlinuz.old unconditionally. (Normally, that
is only done if the version of the new image differs from the old
one). This restricts you to two images, unless you take additional
action and save copies of older images. This is for people who have
.I /boot 
on a system that does not use symbolic links (and say, they use
loadlin as a bootloader). This is a Hack.
Defaults to No. 
.TP
.B reverse_symlinks
Whether to use reverse symlinks (that is, the real file is the one
without the version number, and the number version is the link) to the 
.I image
file. 
Mutually exclusive to 
.I no_symlinks.
Can be used with
.I image_in_boot.
Just like 
.I no_symlinks, 
except that the
/boot/vmlinuz-X.XX is a symbolic link to the real new
image, vmlinuz. This, too, restricts you to just two
images unless further action is taken. The older
symlinks are left dangling. This is for people with
.I /boot 
on umsdos, and who can't see the link in dos, but
do want to know the image version when in Linux. 
This is a Hack.
Defaults to  No.
.TP
.B image_dest 
If you want the symbolic link (or image, if 
.B move_image 
is set) to be stored elsewhere than
.I /
set this variable to the dir where you want the symbolic link.
Please note that this is not a boolean variable.  This may be of
help to
.B loadlin
users, who may set both this and
.B move_image 
Defaults to 
.I /.
This can be used in conjunction with all above options except
.B image_in_boot,
which would not make sense. (If both 
.B image_dest 
and 
.B image_in_boot
are set, 
.B image_in_boot
overrides)
.TP
.B postinst_hook 
Set this variable to a script to be executed during installation after
all the symbolic 
links are created, but before running the bootloader or offering to
create a floppy. This script shall be called with two arguments,
the first being the
.I version
of the kernel image, and the second argument being the
.I location
of the kernel image itself. Errors in the script shall produce a
warning message, but shall be otherwise ignored. An example script for
grub users is present in /usr/share/doc/kernel-package/ directory.
.TP
.B postrm_hook 
Set this variable to a script to be executed in the postrm (that is,
after the image has been removed) after all the remove actions have
been performed. This script shall be called with two arguments,
the first being the
.I version
of the kernel image, and the second argument being the
.I location
of the kernel image itself. Errors in the script shall produce a
warning message, but shall be otherwise ignored.
.TP
.B preinst_hook 
Set this variable to a script to be executed before the package is
unpacked, and can be used to put in additional checks. This script
shall be called with two arguments, the first being the
.I version
of the kernel image, and the second argument being the
.I location
of the kernel image itself. 
.TP
.B prerm_hook 
Set this variable to a script to be executed before the package files
are removed (so any added files may be removed) . This script shall be
called with two arguments, the first being the
.I version
of the kernel image, and the second argument being the
.I location
of the kernel image itself. Errors in the script shall produce a
warning message, but shall be otherwise ignored.
.TP
.B move_image 
Instead of creating symbolic links to (or, if 
.B reverse_symlinks 
is set, from)
.B image_dest,
the image is moved from its location in
.I /boot
into 
.B image_dest.
If 
.B reverse_symlinks 
is set, 
.I /boot
shall contain a symbolic link to the actual image.
This option can be useful to people using loadlin, who may need the
image to be moved to a different, dos partition.
This variable is unset by default.
.TP
.B clobber_modules
If set, the preinst shall silently try to move /lib/modules/version
out of the way if it is the same version as the image being
installed. Use at your own risk.
This variable is unset by default.
.TP
.B do_boot_enable
If set to NO, this short circuits all attempts to create
boot floppies, run lilo, etc. This has the additional
side effect that the postinst is silent. Setting both
.B do_bootfloppy
and 
.B do_bootloader
to NO implies setting
.B do_boot_enable 
to NO. Defaults to Yes.
.TP
.B do_bootfloppy
If set to NO, this prevents the postinst from asking
questions about creating a boot floppy. and no boot
floppy is created. The bootloader shall still be run.
This may cut down on the interaction the postinst has.
(It still prompts before formatting 
.I /dev/fd0) 
Defaults
to Yes.
.TP
.B do_bootloader
If set to NO, this prevents the postinst from running the boot
loader. The user may still be asked to create a floppy, unless 
.B do_bootfloppy
is also set to NO. Defaults to Yes.
.TP
.B relative_links
If set to yes, the kernel image postinst script shall go to extra
ordinary lengths to ensure that the symbolic links are
relative. Normally, the symbolic links are relative when it is easily
determinable that relative links shall work. Defaults to No.
.TP
.B do_initrd
Set to YES to prevent the
.I kernel-image
post installation script from issueing a warning when installing an
intrd kernel. This assumes you have correctly set up your boot loader
to be able to boot the initrd image. Default: no. This is deprecated
in favour of the more descriptive
.B warn_initrd
option (please note that the sense of the option is inverted).
.TP
.B warn_initrd
Set to NO to prevent the
.I kernel-image
post installation script from issueing a warning when installing an
intrd kernel. This assumes you have correctly set up your boot loader
to be able to boot the initrd image. This is now preferred to 
.B do_initrd,
since 
.I warnings
are what are prevented. Default: YES
.TP
.B use_hard_links
This option has been put in for the people who can't handle symbolic
links (a boot loader that does not handle symbolic links, for
example). If set to YES, this shall cause the kernel image  postinst
to use hard link instead of symbolic links for the automatically
handled /vmlinuz and /vmlinuz.old.  I have tried to make it compatible
with 
.B move_image
and
.B reverse_symlinks
Caveat: It is up to the end user to ensure that the 
.B image_dest
directory and the location of the image (nominally /boot) live on the
same file system (since one can't make hard links scross file
systems. 
.B You have been warned.
.TP
.B silent_modules
This option has been put in for the people who are vastly irritated on
being warned about preexisting modules directory 
.TT /lib/modules/$version
That directory may belong to an old or defunct 
.TT kernel-image-$version 
package, in which case problems may arise with lefover modules in that
dir tree, or the directory may legitimately exist due to a independent
modules paqckage being installed for this kernel version that has
already been unpacked.  In this latter case the existence of the
directory is benign.  If you set this varable, you shall no longer be
given a chance to abort if a preexisting modules directory 
.TT /lib/modules/$version
is detected.  This is unset be default.
.TP
.B silent_loader
If set, this option shall cause the question asked before running the
boot laoder in the installation process to be skipped. Whether or not
the boot loader is run is unaffected by this option ( see
.B do_bootloader
to see how to control whether the boot loader is run or not, and the
absense of the configuration file will also make the install process
voluble and interactive).
.SH FILES
The file described here is
.I /etc/kernel-img.conf.
.SH "SEE ALSO"
.BR make-kpkg (1),
.BR kernel-pkg.conf (5),
.BR make (1),
.B The GNU Make manual.
.SH BUGS
There are no bugs.  Any resemblance thereof is delirium. Really.
.SH AUTHOR
This manual page was written by Manoj Srivastava <srivasta@debian.org>,
for the Debian GNU/Linux system.