README for the mkinitrd-cd Package:
-----------------------------------

mkinitrd-cd and mkbootimg can be used to automatically create initrd images.
These images can be loaded by the boot loader (lilo, syslinux, chos, ...) 
before the kernel and will then be mounted by the kernel before it attemps
to mount its root file system. Documentation/initrd.txt in any kernel source
tree explains what happens exactly during the boot procedure. In short, the
kernel mounts the initrd image as the root tree, executes /linuxrc on it
and umounts it when /linuxrc terminates. After this, the real root device is
mounted and the boot procedure continues as normal.
This offers real advantages for booting live CD-ROMs: The kernel does not
have to be compiled with all SCSI-modules in it and the boot-loader does not
need to give the kernel the root device on its command line (the root=/dev/xx
parameter). Instead the /linuxrc file on the initrd image can take care of
loading all kernel modules dynamically which are needed to mount the real
root device afterwards. It can also tell the kernel which root device to use.
You can find a description on what the /linuxrc file coming with this package 
does in the document RUNTIME.
The same initrd image can also be used for booting an installed system from a
hard disk. Only give a root=/dev/xxx parameter on the kernel boot command line
and the given partition will be used as the root filesystem. The needed 
modules to access this partition (IDE / SCSI modules) are loaded.

Since version 0.29, the scripts also support booting from a USB mass storage
device like e.g. a USB stick. The support works, but is not perfect at the
moment. Currenly, the script tries to mount an ISO image or a CRAMFS image 
from the USB stick. I have until now not found a better method to use most of
the available USB sticks, which are just formatted with FAT/VFAT (and 
therefore will not allow the file system to be used directly as I can do it 
with ISO).

A working kernel image with the matching modules is needed prior to executing
the scripts. Some options need to be compiled into the kernel so that the boot
procedure can work as expected. These are
  - isofs
  - procfs
  - ram disk
  - initrd support
  - and maybe a few others that I do not remember at the moment
You can refer to the file /usr/share/doc/mkinitrd-cd/contrib/config-2.2.14.gz
which is the kernel config that I am using at this time. It works with these
configuration options, with other ones trying it out is helpful. When I try
new kernel options, I simply let the scripts create a boot image and write it
to a floppy disc to see if the kernel works and all needed modules are there.

For the creation of the boot image, the currently running kernel must support 
at least the FAT file system and the loopback block device.

The mkinitrd-cd script should be called with three parameters:
  1. the path to the kernel modules that will be used for SCSI (and IDE if
     nedded / wanted)
  2. the filename of the initrd image that should be created
  3. "min" or "full", specifying if you want:
     - A minimal image for only booting  from CD-ROM and with restricted SCSI
       adapters support. This is intended to fit on a 1.44MB floppy disk.
     - A full image with support for CD-ROM and harddisk boot and almost all
       SCSI adapter modules. It will probably not fit on a 1.44MB floppy disk,
       but (currently) still can be used in a 2.88MB ElTorito CD boot image.
Busybox source code is shipped with the package because it is no longer 
available as a Debian package at this time. The script will then compile, create
and copy everything that is needed for a working /linuxrc script in the initrd
image and will gzip the image afterwards. During the creation phase, the
script also creates a custom, minimal subset of all libraries needed by the
binaries on the initrd image. This saves a lot of space for kernel modules.

The mkbootimg script should be called with four parameters:
  1. the filename of the kernel image that will be placed in the boot image
  2. the filename of the initrd image created by mkinitrd-cd
  3. the filename of the boot image that should be created
  4. "1440" or "2880", specifying the size of the created image in kB.
It will take the kernel, the initrd image and the file
/etc/mkinitrd-cd/id.txt and will place them on a MB FAT image
including a syslinux boot sector and an appropriate syslinux configuration
file. The resulting boot image can either be written directly do a floppy disc
with
  dd if=<boot image> of=/dev/fdX bs=512
or can be used as an El Torito image for a bootable CD-ROM.

Following files can be customized if needed:
  - /etc/mkinitrd-cd/bootmsg.txt:
    The text from this file will be displayed by syslinux during bootup.
  - /etc/mkinitrd-cd/id.txt
    The content of this file is the identifier which is used to detect if the
    correct CD-ROM is inserted. It has to be placed on the ISO image as
    /id.txt so that it can be found by the /linuxrc script from the initrd
    image.
  - /usr/share/mkinitrd-cd/scsiprobe.dat and 
    /usr/share/mkinitrd-cd/scsiprobe-min.dat
    Specifies all kernel modules that should be included in the initrd image
    and therefore all modules that can be loaded during bootup. Give on module
    per line.
You can adapt them if you need to, but normally only the files bootmsg.txt and
id.txt need to be changed. Do not forget that exactly the same id.txt file
that was used for the creation of the initrd image must also be placed on the
CD-ROM ISO image as /id.txt. If this is not done, the CD-ROM will not be
recognized by the /linuxrc script and it will not go on with the boot
procedure.


I usually simply do
  dpkg-deb -X kernel-image-<version>_<subversion>_i386.deb /tmp
  mkinitrd-cd /tmp/lib/modules/<version> /tmp/initrd.img
  mkbootimg 1440 /tmp/boot/vmlinuz-<version> /tmp/initrd.img /tmp/boot.img
to get a fully working boot image for the Gibraltar project CD-ROMs.


The following boot parameters are supported at this time by the linuxrc script
that is put into the initrd image:
  - "verbose"  Enable more information to be printed on the screen, useful for
               debugging problems but not necessary in most other cases.
  - "skipcd"   Just skip the automatic CD-ROM detection. This is useful if you
               want to boot from USB mass storage and want to save bootup time.
  - "boot"     Using this option, you can tell the script to boot from a
               location that would not be found in its default behavior (which
               is to search for all CD-ROM/DVD drives and USB mass storage
               devices).
               Supported is the syntax
                 boot=/dev/ide/hostA/busB/targetC/lunD/partE
               respectively
                 boot=/dev/scsi/....
               for booting from normal HDD partitions.
               Then the syntax
                 boot=image:/dev/ide/hostA/busB/targetC/lunD/partE/IMAGEFILE
               allows to specify an ISO image which is stored on a harddisk
               partition. This seginificantly speeds up testing new images as
               they do not need to be burnt to a CD to test them. The system
               will behave exactly as if boot from a real CD, by normally
               mounting the ISO image.
               Finally, the syntax
                 boot=umlhost:/PATH
               Allows to use the image inside a UML system and access the host
               file system transparently. This is also nice for testing a 
               master tree before even generating an ISO image out of it.


If you have any comments, suggestion or bug-reports, the please send them to
<rene.mayrhofer@gibraltar.at>. I do always try to enhance the boot concept to
make Gibraltar boot on more systems. Since I do not have very much systems to
test the bootable CDs on, I greatly appreciate every suggestion.
