YAIRD

Section: Maintenance Commands (8) Local index Up

NAME

yaird - generate initial boot image as initramfs or initrd

SYNOPSIS

yaird --output=dest [options...] [version]
yaird --test [options...] [version]

DESCRIPTION

Yaird (Yet Another MkInitRD) generates initial boot images in initrd or initramfs format. This is an intermediate step between the boot loader and the init scripts on the root file system; it loads modules and enables devices to a level where the kernel can access the real root file system, and then hands over control to the init scripts. You need a new boot image every time you install a new kernel, and when you switch to a different root device. If you are using distribution provided kernels, building the boot image is likely to be done automatically by the installation software.

Most distributions include a distribution-specific tool called mkinitrd(8) for the same task. The yaird alternative differs in that it only supports 2.6 kernels: that means it can use the information provided by newer kernels to build smaller images and if necessary produce better error messages.

Another difference is that there is a clear separation between the code that analyses the system and the templates that determine how these actions are handled by the boot image; this separation makes it relatively simple to customise the generated images.

The following configurations are supported: SATA, SCSI, IDE, USB storage, DASD, LVM2, mdadm, cryptsetup, cryptsetup-luks, USB keyboards, NFS root, EVMS.

Not yet supported: swsusp, firewire, loopback, loopaes, dmraid.

OPTIONS

-f, --format=format: Produce the image in this format. Valid formats are: directory, cramfs, cpio. Use the cpio format to get an image for use with the 'initramfs' model of booting; this is the preferred model for 2.6 kernels. Use 'directory' to leave the image as a directory instead of packing it, either for debugging purposes or to pack it in a file system format of your preference. Use 'cramfs' to get an image in the cramfs file system format for use with the older 'initrd' model of booting. The default is determined by the main configuration file.
-o, --output=destination: Place result here. The destination must not exist yet. There is no default for this option.
-c, --config=config-file: The configuration file that specifies what the initial boot image should do. The default is .../etc/yaird/Default.conf
-h, -?, --help: Print help text and exit.
-V, --version: Print version and exit.
-v, --verbose: Print progress messages.
-d, --debug: Print debugging information.
-q, --quiet: Suppress warning messages.
-t, --test: Print overview of system data and exit; used as basis for debugging.

USAGE

Root privileges are required to use yaird.

When booting a yaird generated image, the presence of a kernel command line parameter 'ydebug' will trigger debugging options in the image: showing commands as they are executed, an interactive shell before control is handed over to the init scripts.

If you're using mdadm(8), you may find that not all md devices are created when booting with yaird. The solution is to add an "auto=md" option to all devices in /etc/mdadm/mdadm.conf.

If you're using cryptsetup(8) for your root device, you need a configuration file /etc/crypttab in order to determine which hash function is used and to verify that the passphrase will be supplied by the controlling terminal. This file is a Debian invention; if your distribution does not document it, consult your favourite search engine. For an encrypted device /dev/mapper/crypted, the configuration file should look more or less as follows:

: # <target device> <source device> <key file> <options>
crypted /dev/sda3 none cipher=aes-cbc-plain

For cryptsetup-luks, the same configuration file is used.

If you want the generated initial image to boot into a file system other than the root in the current /etc/fstab, or to do booting over NFS, modify the main configuration file.

If you're using an NFS root, note that your systems init scripts may need changes to work properly. As an example, resetting a network interface card to get it in a known state may be a good idea in general, but not if your root file system is accessed via that interface.

Although it is possible to generate initial boot images in initrd format, there's not much point in doing so: all kernels new enough to work with yaird support initramfs, which allows simpler images. Initramfs templates have undergone more testing than the initrd version.

Note that under certain conditions initramfs images can be appended to the kernel, but often it is more convenient to keep the image as a separate file that is loaded by the boot loader in the same manner as the older initrd images; see your boot loader documentation.

EXAMPLES

Assuming the main configuration file holds something like:

: CONFIG
       FORMAT  cpio

       TEMPLATE FILE "/usr/local/etc/yaird/Templates.cfg"

       GOALS

               TEMPLATE        prologue

               INPUT

               MODULE          mousedev

               MODULE          evdev

               MOUNTDIR        "/" "/mnt"

               TEMPLATE        postlude

       END GOALS

END CONFIG

To generate an image in initramfs format for the current kernel and current root disk:

: yaird --output=/boot/initrd.img

To generate, with progress report, an image for kernel version 2.6.11:

: yaird --verbose --output=/boot/initrd.img-2.6.11 2.6.11

To generate an image that will boot into /dev/vg0/root rather than the default root, edit the configuration file to replace MOUNTDIR with MOUNTDEV:

: MOUNTDEV "/dev/vg0/root" "/mnt"

To generate an image that will boot over NFS using an ethernetcard found on the current machine, edit the configuration file to replace MOUNTDIR with the following:

: NETWORK
MODULE nfs
MODULE af_packet
TEMPLATE nfsstart

To let grub load an initial boot image from local disk in combination with an NFS root file system on a server that can only handle NFS over UDP:

: title Linux 2.6.11 network boot

root (hd0,1)

kernel /vmlinuz-2.6.11 ip=eth0 nfsroot=10.1.1.1:/dat/root,udp

initrd /initrd.img-2.6.11

boot

FILES

There is a main configuration file .../etc/yaird/Default.cfg, that determines

---: The default format of the generated image;
---: A list of goals the image should achieve, such as loading a module or mounting a device;
---: The location of a secondary configuration file containing templates.

This secondary configuration file, normally .../etc/yaird/Templates.cfg, that determines what needs to be placed on the boot image in order to achieve results such as mounting a device. These templates are at a lower level than the goals specified in the main configuration file: as an example the main configuration file can specify that a module must be loaded, without specifying pathname, extensions, dependencies or options, but the template file need only be able to do a single insmod with all details spelled out. See the HTML documentation for the format of these configuration files.

Additionally, a number of other files are used to determine what should go on the boot image.

/sys: Kernel-provided overview of hardware that needs to be supported.
/etc/hotplug/blacklist, /etc/hotplug/blacklist.d: Modules listed here will not be considered as possible drivers for detected hardware.
/etc/crypttab: Determines source of passphrase and which cryptographic algorithms to use for cryptsetup or cryptsetup-luks.
/etc/fstab: Which device to use as root, file system modules, mount options.
/proc/bus/input/devices: Whether support for USB keyboards is needed.
/boot/config-2.6.11: Which drivers are compiled into the kernel, so that no additional modules need to be loaded.
/etc/modprobe.conf, /etc/modprobe.d: used indirectly via modprobe(8); determines which options to use when loading a module into the kernel.

BUGS

With VMware, you may need to add 'MODULE buslogic' to the configuration file to get the system to boot; a kernel patch to make the detection go automatically is in the works; in 2.6.14 this still is not in mainline.

With the s390 architecture, you'll need an option like dasd=autodetect for the dasd_mod module in order to activate the devices and get a bootable system. This is incompletely tested.

With SunBlade 1000, you may need to add 'MODULE qlogicfc' to the configuration file to get the system to boot.

Report bugs to <yaird-devel@lists.alioth.debian.org>; adding the output of yaird with the --test and --verbose options helps.

This document was created by man2html, using the manual pages.
Time: 22:41:48 GMT, April 16, 2011