Bug#339091: marked as done (initramfs-tools: lacking documentation)
Your message dated Tue, 13 Dec 2005 07:02:03 -0800
with message-id <E1EmBfH-0003sz-Ua@spohr.debian.org>
and subject line Bug#339091: fixed in initramfs-tools 0.44
has caused the attached Bug report to be marked as done.
This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.
(NB: If you are a system administrator and have no idea what I am
talking about this indicates a serious mail system misconfiguration
somewhere. Please contact me immediately.)
Debian bug tracking system administrator
(administrator, Debian Bugs database)
--------------------------------------
Received: (at submit) by bugs.debian.org; 14 Nov 2005 21:37:26 +0000
>From david@hardeman.nu Mon Nov 14 13:37:26 2005
Return-path: <david@hardeman.nu>
Received: from 1-1-12-13a.han.sth.bostream.se ([82.182.30.168] helo=palpatine.hardeman.nu)
by spohr.debian.org with esmtp (Exim 4.50)
id 1Ebm0z-0001UH-CF
for submit@bugs.debian.org; Mon, 14 Nov 2005 13:37:26 -0800
Received: from david by palpatine.hardeman.nu with local (Exim 4.50)
id 1Ebm0U-0008UT-89
for submit@bugs.debian.org; Mon, 14 Nov 2005 22:36:54 +0100
Date: Mon, 14 Nov 2005 22:36:54 +0100
From: David =?iso-8859-1?Q?H=E4rdeman?= <david@2gen.com>
To: submit@bugs.debian.org
Subject: initramfs-tools: lacking documentation
Message-ID: <20051114213654.GC32414@hardeman.nu>
Mime-Version: 1.0
Content-Type: multipart/mixed; boundary="MGYHOYXEY6WxJCY8"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
User-Agent: Mutt/1.5.9i
Delivered-To: submit@bugs.debian.org
X-Spam-Checker-Version: SpamAssassin 2.60-bugs.debian.org_2005_01_02
(1.212-2003-09-23-exp) on spohr.debian.org
X-Spam-Level:
X-Spam-Status: No, hits=-8.0 required=4.0 tests=BAYES_00,HAS_PACKAGE
autolearn=no version=2.60-bugs.debian.org_2005_01_02
--MGYHOYXEY6WxJCY8
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Disposition: inline
Package: initramfs-tools
Severity: minor
Tags: patch
Since the HACKING file included with the initramfs-tools package isn't
very helpful, I've attached a stab at a man page giving a brief introduction
to writing initramfs-tools scripts.
Feel free to proofread, alter and possibly add it to the package instead
of the HACKING file.
Re,
David
--MGYHOYXEY6WxJCY8
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: attachment; filename="initramfs_scripts.8"
Content-Transfer-Encoding: 8bit
.TH MKINITRAMFS_SCRIPTS 8 "Date: 2005/11/14" "" "mkinitramfs script overview"
.SH NAME
mkinitramfs_scripts \- an introduction to writing scripts for initramfs-tools
.SH DESCRIPTION
initramfs-tools has one main script and two different sets of subscripts which
will be used during different phases of execution. Each of these will be discussed separately below with the help of an imaginary tool which performs a frobnication of a lvm partition prior to mounting the root partition.
.SS Hook scripts
These are used when an initramfs image is created and not included in the
image itself. They can however cause files to be included in the image.
.SS Boot scripts
These are included in the initramfs image and normally executed during
kernel boot in the early user-space before the root partition has been
mounted.
.SH INIT SCRIPT
The script which is executed first and is in charge of running all other scripts can be found in /usr/share/initramfs-tools/init. It takes a number of arguments which influence the boot procedure:
.SS Boot options
.TP
\fB \fI init
the binary to hand over execution to on the root fs after the initramfs scripts are done.
.TP
\fB \fI root
the device node to mount as the rootfs.
.TP
\fB \fI nfsroot
can be either "auto" to try to get the relevant information from DHCP or a string of the form NFSSERVER:NFSPATH
.TP
\fB \fI boot
either local or nfs (affects which initramfs scripts are run, see the "Subdirectories" section under boot scripts).
.TP
\fB \fI resume
device node which holds the result of a previous suspension using swsusp (usually the swap partition).
.TP
\fB \fI quiet
reduces the amount of text output to the console during boot
.TP
\fB \fI ro
mounts the rootfs read-only
.TP
\fB \fI rw
mounts the rootfs read-write
.TP
\fB \fI debug
generates lots of output to /tmp/initramfs.debug
.TP
\fB \fI break
spawns a shell in the initramfs image before init-premount scripts are run
.SH HOOK SCRIPTS
Hooks can be found in two places: /usr/share/initramfs-tools/hooks and /etc/mkinitramfs/hooks. They are executed during generation of the initramfs-image and are responsible for including all the necessary components in the image itself. No guarantees are made as to the order in which the different scripts are executed unless the prereqs are setup in the script.
.SS Header
In order to support prereqs, each script should begin with the following lines:
.RS
.nf
#!/bin/sh
PREREQ=""
prereqs()
{
echo "$PREREQ"
}
case $1 in
prereqs)
prereqs
exit 0
;;
esac
. /usr/share/initramfs-tools/hook-functions
# Begin real processing below this line
.fi
.RE
For example, if you are writing a new hook script which relies on lvm, the line starting with PREREQ should be changed to PREREQ="lvm" which will ensure that the lvm hook script is run before your custom script.
.SS Help functions
/usr/share/initramfs-tools/hook-functions contains a number of functions which
deal with some common tasks in a hook script:
.TP
\fB \fI
manual_add_modules
adds a module (and any modules which it depends on) to the initramfs image.
.RS
.PP
.B Example:
manual_add_modules reiserfs
.RE
.TP
\fB \fI
add_modules_from_file
reads a file containing a list of modules (one per line) to be added to the initramfs image. The file can contain comments (lines starting with #) and arguments to the modules by writing the arguments on the same line as the name of the module.
.RS
.PP
.B Example:
add_modules_from_file /tmp/modlist
.RE
.TP
\fB \fI
force_load
adds a module (and its dependencies) to the initramfs image and also unconditionally loads the module during boot. Also supports passing arguments to the module by listing them after the module name.
.RS
.PP
.B Example:
force_load cdrom debug=1
.RE
.TP
\fB \fI
copy_modules_dir
copies an entire module directory from /lib/modules/KERNELVERSION/ into the initramfs image.
.RS
.PP
.B Example:
copy_modules_dir kernel/drivers/pci/foobar
.RE
.SS Including binaries
If you need to copy binaries to the initramfs module, a command like this should be used:
.PP
.RS
cp /sbin/mdadm "${DESTDIR}/sbin"
.RE
mkinitramfs will automatically detect which libraries the executable depends on and copy them to the initramfs. This means that most executables, unless compiled with klibc, will automatically include glibc in the image which will increase its size by several hundred kilobytes.
.SH BOOT SCRIPTS
Similarly to hook scripts, boot scripts can be found in two places /usr/share/initramfs-tools/scripts/ and /etc/mkinitramfs/scripts/. There are a number of subdirectories to these two directories which control the boot stage at which the scripts are executed.
.SS Header
Like for hook scripts, there are no guarantees as to the order in which the different scripts in one subdirectory (see "Subdirectories" below) are executed. In order to define a certain order, a similar header as for hook scripts should be used:
.RS
.nf
#!/bin/sh
PREREQ=""
prereqs()
{
echo "$PREREQ"
}
case $1 in
prereqs)
prereqs
exit 0
;;
esac
.fi
.RE
Where PREREQ is modified to list other scripts in the same subdirectory if necessary.
.SS Help functions
A number of functions (mostly dealing with output) are provided to boot scripts:
.TP
\fB \fI
log_success_msg
Logs a success message
.RS
.PP
.B Example:
log_success_msg "Frobnication successful"
.RE
.TP
\fB \fI
log_failure_msg
Logs a failure message
.RS
.PP
.B Example:
log_failure_msg "Frobnication component froobz missing"
.RE
.TP
\fB \fI
log_warning_msg
Logs a warning message
.RS
.PP
.B Example:
log_warning_msg "Only partial frobnication possible"
.RE
.TP
\fB \fI
log_begin_msg
Logs a message that some processing step has begun
.TP
\fB \fI
log_end_msg
Logs a message that some processing step is finished
.RS
.PP
.B Example:
.PP
.RS
.nf
log_begin_msg "Frobnication begun"
# Do something
log_end_msg
.fi
.RE
.RE
.TP
\fB \fI
panic
Logs an error message and executes a shell in the initramfs image to allow the user to investigate the situation.
.RS
.PP
.B Example:
panic "Frobnication failed"
.RE
.SS Subdirectories
Both /usr/share/initramfs-tools/scripts and /etc/mkinitramfs/scripts contains the following subdirectories.
.TP
\fB \fI
init-top
the scripts in this directory are the first scripts to be executed after sysfs and procfs have been mounted and /dev/console and /dev/null have been created. No other device files are present yet.
.TP
\fB \fI
init-premount
these scripts are run after udev has populated the /dev tree (udev is still running) and after modules specified by hooks and /etc/mkinitramfs/modules have been loaded.
.TP
\fB \fI
local-top OR nfs-top
udev is no longer running. After these scripts have been executed, the root device node is expected to be present (local) or the network interface is expected to be usable (nfs).
.TP
\fB \fI
local-premount OR nfs-premount
are run after the sanity of the root device has been verified (local) or the network interface has been brought up (nfs), but before the actual root fs has been mounted.
.TP
\fB \fI
local-bottom OR nfs-bottom
are run after the rootfs has been mounted (local) or the nfs root share has been mounted.
.TP
\fB \fI
init-bottom
are the last scripts to be executed before procfs and sysfs are unmounted and execution is turned over to the init binary which should now be found in the mounted rootfs.
.SH EXAMPLES
.SS Hook script
An example hook script would look something like this (and would usually be placed in /etc/mkinitramfs/hooks/frobnicate):
.RS
.nf
#!/bin/sh
# Example frobnication hook script
PREREQ="lvm"
prereqs()
{
echo "$PREREQ"
}
case $1 in
prereqs)
prereqs
exit 0
;;
esac
. /usr/share/initramfs-tools/hook-functions
# Begin real processing below this line
if [ ! -x "/sbin/frobnicate" ]; then
exit 0
fi
force_load frobnicator interval=10
cp /sbin/frobnicate "${DESTDIR}/sbin"
exit 0
.fi
.RE
.SS Boot script
An example boot script would look something like this (and would usually be placed in /etc/mkinitramfs/scripts/local-top/frobnicate):
.RS
.nf
#!/bin/sh
# Example frobnication boot script
PREREQ="lvm"
prereqs()
{
echo "$PREREQ"
}
case $1 in
prereqs)
prereqs
exit 0
;;
esac
# Begin real processing below this line
if [ ! -x "/sbin/frobnicate" ]; then
panic "Frobnication executable not found"
fi
if [ ! -e "/dev/mapper/frobb" ]; then
panic "Frobnication device not found"
fi
log_begin_msg "Starting frobnication"
/sbin/frobnicate "/dev/mapper/frobb" || panic "Frobnication failed"
log_end_msg
exit 0
.fi
.RE
.SH AUTHOR
The initramfs-tools are written by Jeff Bailey <jbailey@ubuntu.com>.
.PP
This manual was written by David Härdeman <david@2gen.com>.
--MGYHOYXEY6WxJCY8--
---------------------------------------
Received: (at 339091-close) by bugs.debian.org; 13 Dec 2005 15:11:00 +0000
>From katie@ftp-master.debian.org Tue Dec 13 07:11:00 2005
Return-path: <katie@ftp-master.debian.org>
Received: from katie by spohr.debian.org with local (Exim 4.50)
id 1EmBfH-0003sz-Ua; Tue, 13 Dec 2005 07:02:03 -0800
From: maximilian attems <maks@sternwelten.at>
To: 339091-close@bugs.debian.org
X-Katie: $Revision: 1.60 $
Subject: Bug#339091: fixed in initramfs-tools 0.44
Message-Id: <E1EmBfH-0003sz-Ua@spohr.debian.org>
Sender: Archive Administrator <katie@ftp-master.debian.org>
Date: Tue, 13 Dec 2005 07:02:03 -0800
X-Spam-Checker-Version: SpamAssassin 2.60-bugs.debian.org_2005_01_02
(1.212-2003-09-23-exp) on spohr.debian.org
X-Spam-Level:
X-Spam-Status: No, hits=-6.0 required=4.0 tests=BAYES_00,HAS_BUG_NUMBER
autolearn=no version=2.60-bugs.debian.org_2005_01_02
X-CrossAssassin-Score: 2
Source: initramfs-tools
Source-Version: 0.44
We believe that the bug you reported is fixed in the latest version of
initramfs-tools, which is due to be installed in the Debian FTP archive:
initramfs-tools_0.44.dsc
to pool/main/i/initramfs-tools/initramfs-tools_0.44.dsc
initramfs-tools_0.44.tar.gz
to pool/main/i/initramfs-tools/initramfs-tools_0.44.tar.gz
initramfs-tools_0.44_all.deb
to pool/main/i/initramfs-tools/initramfs-tools_0.44_all.deb
A summary of the changes between this version and the previous one is
attached.
Thank you for reporting the bug, which will now be closed. If you
have further comments please address them to 339091@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.
Debian distribution maintenance software
pp.
maximilian attems <maks@sternwelten.at> (supplier of updated initramfs-tools package)
(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@debian.org)
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Format: 1.7
Date: Mon, 12 Dec 2005 11:22:15 +0100
Source: initramfs-tools
Binary: initramfs-tools
Architecture: source all
Version: 0.44
Distribution: unstable
Urgency: high
Maintainer: Debian kernel team <debian-kernel@lists.debian.org>
Changed-By: maximilian attems <maks@sternwelten.at>
Description:
initramfs-tools - tools for generating an initramfs
Closes: 337318 337575 339091 342153
Changes:
initramfs-tools (0.44) unstable; urgency=high
.
"O partigiano portami via"
.
* Urgency high upload to stay in sync with udev for testing.
.
* initramfs.conf: Fix wording choice for resume option. (Closes: #337575)
.
* hooks/kernelextras: Really fix #335505.
Don't expand wildcase to current dir. (Closes: #342153)
.
* Add initramfs-tools.8 describing how the hooks of initramfs-tools work
and how to use them. Thanks David Härdeman <david@2gen.com> for the patch.
(Closes: #339091)
.
* initramfs.conf.5, mkinitramfs.8, update-initramfs.8: Update
cross-references of the different manpages.
.
* TODO: update to current state.
.
* scripts/functions: remove old duplicate suspend support.
.
* Sync with 0.40ubuntu8. (Closes: #337318)
- Revert the modprobe changes for now as modules-init-tools of
testing doesn't have yet the wanted interface.
Files:
ad3a7d99c2f1bf642597619e3d384fc3 629 utils optional initramfs-tools_0.44.dsc
601caa5562865bd640a2f31d2d9f4088 29817 utils optional initramfs-tools_0.44.tar.gz
361683cfdf6399f86e3679431a0f8795 34724 utils optional initramfs-tools_0.44_all.deb
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (GNU/Linux)
iD8DBQFDnuDy5M5hmdCYCpkRApNkAKCVcy/w7kAJknD9DWzUACKr+45dtgCgrBuh
SENRVtSGXlW78i9xXealUf4=
=g3Nb
-----END PGP SIGNATURE-----
Reply to: