- update

[projects/geninitrd.git] / geninitrd.8.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<refentry>
  <refmeta>
    <refentrytitle>geninitrd</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo class="software">PLD</refmiscinfo>
    <refmiscinfo class="date">$Date$</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>geninitrd</refname>
    <refpurpose>
      creates initial ramdisk images for preloading modules
    </refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>geninitrd</command>
      <arg>-f</arg>
      <arg>-v</arg>
      <arg rep="repeat">--with=module</arg> 
      <arg rep="repeat">--preload=module</arg> 
      <arg>--fstab=fstab</arg>
      <arg>--lvmtoolsversion=1|2</arg>
      <arg>--modules-conf=modules.conf</arg>
	  <arg>--fs=rom|ext2|cram</arg>
	  <arg>--with-insmod-static</arg>
      <arg choice="req">image</arg>
      <arg choice="req">kernel-version</arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>geninitrd</command>
      <arg>--version</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      <application>geninitrd</application> creates filesystem images
      which are suitable for use as Linux initial ramdisk (initrd)
      images. Such images are often used for preloading the block
      device modules (such as IDE, SCSI or RAID) which are needed to
      access the root filesystem. <application>geninitrd</application>
      automatically loads all <varname>scsi_hostadapter</varname>
      entries in <filename>/etc/modules.conf</filename> when it finds
      that root fs is mounted on SCSI device, which makes it simple to
      build and use kernels using modular SCSI devices. It will also
      load IDE and RAID modules when needed. </para>
    <para>Any module options specified in
      <filename>/etc/modules.conf</filename> are passed to the modules
      as they are loaded by the initial ramdisk. </para>
    <para>If the root filesystem is modular, initrd will automatically
      add the filesystem's modules to the initrd image.</para>

    <!--    <para>If the root device is on a loop device (such as
  <filename>/dev/loop0</filename>), <application>geninitrd</application>
    will attempt to build an initrd which sets up the loopback file
    properly. To do this, the fstab must contain a comment of the form:
  <literal>
    # LOOP0: /dev/hda1 vfat /linux/rootfs
  </literal>
    LOOP0 must be the name of the loop device which needs to be configured, in
    all capital lettes. The parameters after the color are the device which 
    contains the filesystem with the loopback image on it, the filesystem which
    is on the device, and the full path to the loopback image.
  </para> -->
  </refsect1>
  <refsect1>
    <title>Options</title>

    <variablelist>
      <varlistentry>
	<term>-f</term>
	<listitem>
	  <para>Allows <application>geninitrd</application> to
	    overwrite an existing image file.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>--fstab=<filename>fstab</filename></term>
	<listitem>
	  <para>Use <filename>fstab</filename> to automatically
	    determine what type of filesystem the root device is on.
	    Normally, <filename>/etc/fstab</filename> is used.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>--ifneeded</term>
	<listitem>
	  <para>Only builds the image if their are modules that need
	    to be loaded at boot time.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>--image-version</term>
	<listitem>
	  <para>Append kernel version to initrd name.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>--nocompress</term>
	<listitem>
	  <para>Don't compress initrd.</para>
	</listitem>
      </varlistentry>
      <!-- varlistentry>
    <term>-(hack)-no-bsp</term>
    <listitem>
    <para>Don't use Braindamaged Script Processor (/bin/bsp) and use /bin/trash instead.</para>
    </listitem>
    </varlistentry -->
      <varlistentry>
	<term>--preload=<filename>module</filename></term>
	<listitem>
	  <para>Load the module <filename>module</filename> in the
	    initial ramdisk image. The module gets loaded before any
	    SCSI modules which are specified in
	    <filename>/etc/modules.conf</filename>. This option may be
	    used as many times as necessary.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>--with=<filename>module</filename></term>
	<listitem>
	  <para>Alias to --preload.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>-v</term>
	<listitem>
	  <para>Prints out verbose information while creating the
	    image (normally the <application>geninitrd</application>
	    runs silently). 
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>--version</term>
	<listitem>
	  <para>Prints the version of
	    <application>geninitrd</application> that's being used and
	    then exits.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>--initrdfs=<filename>ext2|rom|cram</filename></term>
	<listitem>
	  <para>Filesystem type to be used for the image. Only
	    selected filesystem should always be compiled into
	    kernel.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>--with-insmod-static</term>
	<listitem>
		<para>Use <filename>/sbin/insmod.static</filename> insteed of <command>bsp</command> bulitin insmod.</para>
	</listitem>
	</varlistentry>
	<varlistentry>
		<term>--lvmtoolsversion=1|2</term>
		<listitem>
			<para>Tell which version of LVM tools are used.</para>
		</listitem>
	</varlistentry>
    </variablelist>
</refsect1>
<refsect1>
	<title>SCSI support</title>
	<para>
		If geninitrd detect rootfs on SCSI disk then lookup for "scsi_hostadapter" alias in /etc/modules.conf file and use it to load proper SCSI low-level driver(s).
	</para>
</refsect1>
<refsect1>
	<title>ATA RAID support</title>
	<para>
		If geninitrd detect rootfs on ATA RAID then lookup for "ataraid_hostadapter" alias in /etc/modules.conf and use it to load proper ATA RAID low level driver.
	</para>
	<para>For eg. if you have Promise FastTrack controler then add "alias ataraid_hostadapter pdcraid" to /etc/modules.conf.</para>
</refsect1>
<refsect1>
	<title>Splash support</title>
	<para>
		Geninitrd supports both <application>bootsplash</application> and <application>fbsplash</application> (<application>splashutils</application>) incorpororation into boot proces.
	</para>
	<para>
	    For both <application>fbsplash</application> and <application>bootsplash</application> to work, the kernel needs to be patched respectivly.	
	</para>
	<para>
		Additionally, for <application>fbsplash</application> and <application>bootsplash</application> you need to pass special kernel parameters during boot. Use <application>rc-boot</application>, <application>lilo</application> or <application>grub</application> to pass the parameters. For details on parameters please consult <application>fbsplash</application> or <application>bootsplash</application> documentation.
	</para>
</refsect1>
<refsect1>
	<title>Linux 2.6.x support</title>
	<para>To bulild initrd for Linux 2.6.x kernels you must have module-init-tools and use --with-insmod-static switch or use initrd version of recent busybox that comes in busybox-initrd package.
	</para>
</refsect1>
<!-- refsect1>
	<title>Hardware RAID support</title>
	<para>
		geninitrd support following RAID controlers:
		<itemizedlist>
			<listitem>
				<para></para>
			</listitem>
		</itemizedlist>
	</para>
</refsect1 -->
  <refsect1>
    <title>FILES</title>
    <variablelist>
      <varlistentry>
	<term><filename>/etc/sysconfig/geninitrd</filename></term>
	<listitem>
	  <para>Configuraton file with default options. Putting proper
	    options there helps in automatic creation of initrd eg. on
	    kernel upgrade.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><filename
			class="devicefile">/dev/loop*</filename></term>
	<listitem>
	  <para>A block loopback device is used to create the image,
	    which makes this script useless on systems without block
	    loopback support available.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><filename>/etc/modules.conf</filename></term>
	<listitem>
	  <para>Specified SCSI modules to be loaded and module options
	    to be used.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>SEE ALSO</title>
    <para><citerefentry>
	<refentrytitle>fstab</refentrytitle>
	<manvolnum>5</manvolnum>
      </citerefentry>
      <citerefentry>
	<refentrytitle>insmod</refentrytitle>
	<manvolnum>1</manvolnum>
      </citerefentry>
      <citerefentry>
	<refentrytitle>grub</refentrytitle>
	<manvolnum>8</manvolnum>
      </citerefentry>
      <citerefentry>
	<refentrytitle>lilo</refentrytitle>
	<manvolnum>8</manvolnum>
      </citerefentry>
      <citerefentry>
	<refentrytitle>genromfs</refentrytitle>
	<manvolnum>8</manvolnum>
      </citerefentry>
    </para>
  </refsect1>
  <refsect1>
    <title>Authors</title>
    <para><application>geninitrd</application> is based on mkinitrd by
      Erik Troan <email>ewt(at)redhat.com</email> and contributors: 
      <simplelist>
	<member>Elliot Lee <email>sopwith(at)cuc.edu</email>, </member>
	<member> Miguel de Icaza
	  <email>miguel(at)nuclecu.unam.mx</email>, </member>
	<member>Christian 'Dr. Disk' Hechelmann
	  <email>drdisk(at)ds9.au.s.shuttle.de</email>, </member>
	<member>Michael K. Johnson
	  <email>johnsonm(at)redhat.com</email>, </member>
	<member>Pierre Habraken
	  <email>Pierre.Habraken(at)ujf-grenoble.fr</email>, </member>
	<member>Jakub Jelinek
	  <email>jj(at)ultra.linux.cz</email>, </member>
	<member>Carlo Arenas Belon
	  <email>carenas(at)chasqui.lared.net.pe</email>.</member>
      </simplelist>
    </para>
    <para><application>geninitrd</application> is written by Jacek
      Konieczny <email>jajcus(at)pld-linux.org</email> and contributors (in
      random order): <simplelist>
	<member>Witold Filipczyk <email>witekfl(at)poczta.onet.pl</email>, </member>
	<member>Artur Frysiak <email>wiget(at)pld-linux.org</email>, </member>
	<member>Dariusz Karolczak <email>inglod(at)pld-linux.org</email>, </member>
	<member>Tomasz Kloczko <email>kloczek(at)pld.org.pl</email>, </member>
	<member>Cezary Krzyżanowski<email>czarny(at)pld-linux.org</email>, </member>
	<member>Elan Ruusamäe<email>glen(at)pld-linux.org</email>, </member>
	<member>Arkadiusz Miskiewicz <email>arekm(at)pld-linux.org</email>, </member>
	<member>Michal Moskal <email>malekith(at)pld-linux.org</email>, </member>
	<member>Jan Rekorajski <email>baggins(at)pld-linux.org</email>, </member>
	<member>Sebastian Zagrodzki <email>zagrodzki(at)pld-linux.org</email>, </member>
	<member>Michal Zawalich <email>michuz(at)pld-linux.org</email>.</member>
      </simplelist>
    </para>
    <para> Manual page for <application>geninitrd</application> is
      based on mkinitrd.8 by Erik Troan <email>ewt(at)redhat.com</email>
      and written by Jacek Konieczny
      <email>jajcus(at)pld-linux.org</email> and contributors.</para>
  </refsect1>
</refentry>
<!-- vim: set fileencoding=utf-8 : -->