<?xml version="1.0" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBk XML V4.1.2//EN"
        "/usr/share/sgml/docbook/dtd/xml/4.1.2/docbookx.dtd"
[
<!ENTITY % progeny-entity SYSTEM "../doctools/progeny.ent">
%progeny-entity;

<!ENTITY pgi-build-refentry SYSTEM "pgi-build.refentry">

<!ENTITY build-command "<command>pgi-build</command>">
<!ENTITY codename "<replaceable>codename</replaceable>">

<!ENTITY cdrecord "<application>cdrecord</application>">
<!ENTITY emdash "&mdash;">
]
>

<book>
  <bookinfo>
    <releaseinfo>$Progeny: guide.xml,v 1.92 2002/04/23 18:16:54 branden Exp $</releaseinfo>

    <authorgroup>
      &author.branden;
      &author.shunger;
      &author.epg;
      &author.jdaily;
    </authorgroup>

    <title>Creating Debian Installers with &pgi;</title>
    <titleabbrev>&pgi;</titleabbrev>

    <copyright>
      <year>2002</year> <holder>Progeny Linux Systems, Inc.</holder>
    </copyright>
  </bookinfo>

  <chapter id="ch-overview">
    <title id="ch-overview-title">Overview</title>

    <para>&pgi;<footnote><para>pronounced <quote>piggy</quote></para>
    </footnote>, the <quote>Progeny Graphical Installer</quote>, is a
    system for creating installers for the Debian GNU/Linux operating
    system. &pgi; is based on the installer used in the Progeny Linux
    Systems, Inc. distribution of Debian.  Without customization, &pgi;
    produces a minimal Debian system installer on an ISO 9660 filesystem
    image suitable for burning to recordable CD or DVD media.  With
    customization, &pgi; is a powerful, flexible foundation upon which you
    may implement as sparse or as elaborate a Debian GNU/Linux installer
    you may desire.</para>

    <para>&pgi; conceptualizes an installation as taking place in two
    stages.  The first stage consists of running the installer itself.
    During this stage (or, at least, up until the very end of it), the
    target system &emdash; that is, the system to which one is installing
    the operating system &emdash; is regarded as <quote>not
    installed</quote>.  This means that there is no bootable Debian
    GNU/Linux system on it, or the one that is present is not desired.
    When the second stage begins, one is running the desired operating
    system, but essential system parameters may not be configured to the
    user's taste.  Under these definitions, a Debian GNU/Linux system that
    can boot to multi-user mode and present a login prompt, but has no no
    user accounts and no password on the root account is installed but not
    configured.  Thus, configuration is extremely important for security as
    well as usability.  Fundamentally, &pgi; is a first-stage installer
    only; all it does is prepare a bare, unconfigured system.  When it
    exits, you will get a login prompt if no vendor hook has been
    provided.</para>

    <para>What &pgi; lets you (the installer vendor) do is start from this
    known blank-slate state and handle only the interesting parts of the
    installation process, which consist primarily of configuration.  Do you
    want the system to <quote>just come up</quote> with the GNOME or KDE
    desktop environments pre-installed?  Is there a standard profile of
    Debian packages that you want present from the very start on the
    systems at your site?  &pgi; gives you this power without requiring you
    to fuss with the bootstrapping stages of an operating system
    installation.</para>

    <section>
      <title>Features</title>

      <para>&pgi; implements several existing technologies to ensure that
      it is both flexible enough to deal with a broad range of hardware,
      and compatible with the official Debian installation system.  The
      latter point is important because it should not matter how the user
      gets Debian GNU/Linux onto his or her computer; what is important is
      that the resulting system is compatible with any other Debian
      GNU/Linux system at the infrastructural level.</para>

      <itemizedlist>
        <listitem>
          <para>&pgi; uses &debootstrap;, Debian's official means of
          retrieving and installing the core components of a Debian
          GNU/Linux system.  Stage 1 of &pgi; (see <link
          linkend="ch-second-stage" endterm="ch-second-stage-title"/>) can
          be thought of as a <quote>wrapper</quote> around &debootstrap;;
          &pgi; gets the system into a state where &debootstrap; can be run
          successfully.</para>
        </listitem>
        <listitem>
          <para>&pgi; features both text-mode and graphical user
          interfaces.  The latter uses version 4.1.0 of the XFree86 X
          server, supporting a wide variety of video hardware at reasonable
          color depths and resolutions.  In cases where the graphical
          interface is not desired or unsupported by XFree86, a text-mode
          interface is available and provides the user with the same
          functionality.</para>
        </listitem>
        <listitem>
          <para>&pgi;'s graphical user interface autodetects most pointing
          devices (mice, trackballs, etc.) and video hardware.  In most
          cases, it is not necessary to answer any configuration questions
          to use the installer's graphical interface &emdash; it
          <quote>just comes up</quote>.  In situations where manual
          configuration is necessary, only a few easily-understood
          questions are asked of the user, to give the GUI the
          <quote>push</quote> it needs to get going.  Alternatively, you
          can run the graphical interface even when the target machine's
          video hardware is not supported by the XFree86 X server; simply
          set the <option>display</option> boot parameter and run the
          installer on an X server elsewhere on your local
          network<footnote><para>Actually, there is no reason you can't run
          the graphical installer on an X server thousands of miles distant
          &emdash; in some foreign country, perhaps &emdash; but we don't
          recommend this.</para></footnote>.</para>
        </listitem>
        <listitem>
          <para>Even when the X Window System is unavailable, &pgi;'s text
          mode spares the Linux novice the intimidation of a shell prompt.
          The <command>dialog</command> utility is used to provide a
          friendly, menu-and-button-driven interface to the text-mode
          installer.</para>
        </listitem>
        <listitem>
          <para>&pgi; is largely independent of the Linux kernel version.
          &pgi; may be built around an extremely broad variety of kernels;
          only a few kernel configuration options or mandatory for &pgi;'s
          proper operation (see <link linkend="ch-kernel-selection"
          endterm="ch-kernel-selection-title"/>).  You can create
          lean-and-mean kernels for use with &pgi;, or large, featureful
          kernels for use on a range of hardware.  You can also use &pgi;
          with the latest Linux kernel<footnote><para>The 2.5.x kernel
          series is not explicitly supported, as it is inherently
          experimental software.</para></footnote>, or your own
          specially-patched version, in the event that the target hardware
          for installation is not supported to your satisfaction by the
          stock Debian kernel.</para>
        </listitem>
        <listitem>
          <para>&pgi; uses Progeny's &discover; hardware autodetection
          system to automatically detect the correct kernel module or
          XFree86 server driver to use with PCI, AGP, USB, and PCMCIA
          devices.</para>
        </listitem>
        <listitem>
          <para>&pgi; provides and uses the GNU Parted library and utility
          for flexible and featureful disk partitioning.  A graphical
          partitioner based on Progeny's Python bindings to the Parted
          library makes partitioning easy and intuitive<footnote><para>In
          text-mode installs, the <command>parted</command> command-line
          program is used for disk partitioning.</para></footnote>.</para>
        </listitem>
        <listitem>
          <para>&pgi; is architecture-independent.  &pgi; has been designed
          for portability.  In its first release, it supports the Intel x86
          and IA-64 architectures.  Hooks are in place for developers on
          other architectures to add support for their platforms without
          having to make infrastructural changes to &pgi;.</para>
        </listitem>
        <listitem>
          <para>&pgi; is flexible.  Not only are many aspects of its
          behavior customizable at build time (and even run time), but
          &pgi; supports the simultaneous development of different
          <quote>profiles</quote>, which are referred to by code names that
          you select.  You can choose between these profiles at build time
          with a command-line option.</para>

          <para> As an example, imagine that you're responsible for
          managing a pair of university computer labs.  One lab is for
          general undergraduate use, so you want the machines to have a
          desktop environment and a large array of applications, like
          <application>Mozilla</application>,
          <application>Gnumeric</application>,
          <application>KWord</application>,
          <application>Gaim</application>, and
          <application>Kontour</application>.  Another lab is used only by
          CS students taking Systems Programming courses; some of these
          guys eschew all windowing systems<footnote><para>aside from,
          perhaps, <command>screen</command></para></footnote> and want to
          get straight into their text editors and debuggers.  For this
          audience, you might not ship the X Window System at all, and
          ensure that <application>Vim</application>,
          <application>Emacs</application>, <application>Gdb</application>,
          and <application>User-Mode Linux</application> are present.  Once
          you have set up the profiles for each, you can create ISOs for
          either at will without needing to shuffle files.</para>
        </listitem>
        <listitem>
          <para>&pgi; is network-enabled.  For GNU/Linux users in general
          and for Debian users in particular, the days of being restricted
          to installing your system from a fixed, physical medium and then
          having to hurriedly upgrade to the latest patches from your
          vendor are fast becoming a memory.</para>

          <para> &debootstrap; is network-aware, and can retrieve the base
          system from a local disk, a web server internal to your home or
          office, or directly from an official Debian mirror on the
          Internet.  &pgi; goes still further, however.  Only the earliest
          phases of installation (the booting of the Linux kernel, loading
          kernel modules necessary to support the target machine's
          hardware, and configuration of the network interface) need depend
          on the installation medium (CD or DVD).  &nfs; can then be used
          to mount the <quote>live</quote> filesystem inside which the
          installer proper runs.</para>

          <para>These network installation options allow vendors to update
          &pgi;-based installers without replacing the existing CD
          images.</para>
        </listitem>
        <listitem>
          <para>&pgi; is boot-loader agnostic.  On the x86 platform, &pgi;
          uses GNU GRUB for a friendly, menu-driven boot loader.  GNU GRUB
          also supports a powerful command-line interface at boot time, if
          the user elects to use it.  On the IA-64 platform,
          <command>elilo</command> is used, and the Linux kernel's
          interface to EFI variables is used to update the boot menu in the
          system firmware.</para>
        </listitem>
        <listitem>
          <para>&pgi; can generate ISO 9660 images that contain only a
          &pgi;-based installer, images that contain the installer plus the
          packages needed to support your installation profile, or the
          installer plus a complete snapshot of the Debian package archive.
          Multiple ISO images are generated as needed.</para>
        </listitem>
        <listitem>
          <para>&pgi;-based installers are more than just installers.  The
          installer can also be started in a system rescue/recovery mode,
          which loads the live filesystem and provides the user with a
          shell.  The live filesystem can be configured to contain
          practically anything desired, from network diagnostic tools to a
          full XFree86 installation and even a web
          browser<footnote><para>Note, however, that the environment is
          missing such things as swap space and a writeable
          <filename>/usr</filename> filesystem, since it consists of an
          eight-megabyte initial ramdisk, and the live filesystem is
          read-only.  So don't get too carried away.</para></footnote>.
          The &pgi; installation medium can also be used a simple boot
          disk, loading the kernel and getting out of the way, transferring
          control to the specified root filesystem device.</para>
        </listitem>
      </itemizedlist>

    </section>

    <section>
      <title>What &pgi; Won't Do (Without Your Help)</title>

      <para>As stated above, &pgi; breaks the installation process down
      into two<footnote><para>Behind the scenes, there are three stages;
      the first (stage 0) involves booting the Linux kernel, loading kernel
      modules for hardware support, and finding a live filesystem for
      installation.</para></footnote> stages.  The first stage is concerned
      with establishing a bootable system on the computer.  The second
      stage involves setting up that system; configuration of date and
      time, network interface card setup, and the XFree86 X server is
      typical.</para>

      <note>
        <para>Using a network connection and graphical interface for the
        first stage is not unusual, so if the network card and X server are
        configured at that time, their parameters are stored and made
        available in the second stage.</para>
      </note>

      <para>&pgi; is designed to be agnostic about the second stage, and in
      fact does not provide one for you, except by way of example. See
      <link endterm="ch-second-stage-title" linkend="ch-second-stage"/> for
      further details.</para>

    </section>

  </chapter>

  <chapter>
    <title>Procedure Highlights</title>

    <itemizedlist>
      <listitem>
        <para>Install &pgi; and related packages.  (See <link
        endterm="ch-system-requirements-title"
        linkend="ch-system-requirements"/>.)</para>
      </listitem>
      <listitem>
        <para>Install the desired kernel.  (See <link
        endterm="ch-kernel-selection-title"
        linkend="ch-kernel-selection"/>.)</para>
      </listitem>
      <listitem>
        <para>Customize <filename>/etc/pgi/&codename;/options</filename> to
        your taste, or research the command-line options you will need to
        pass to &build-command;.  (See <link
        linkend="options-and-environment"
        endterm="options-and-environment-title"/>.)</para>
      </listitem>
      <listitem>
        <para>Add desired extra packages for your post-installation vendor
        hook to <filename>/etc/pgi/&codename;/extra_packages</filename>.
        (See <link endterm="ch-second-stage-title"
        linkend="ch-second-stage"/>.)</para>
      </listitem>
      <listitem>
        <para>Create <filename>/etc/pgi/&codename;/preinst.sh</filename>.
        (See <link linkend="input-files"
        endterm="input-files-title"/>.)</para>
      </listitem>
      <listitem>
        <para>Create <filename>/etc/pgi/&codename;/postinst.sh</filename>.
        (See <link linkend="input-files"
        endterm="input-files-title"/>.)</para>
      </listitem>
      <listitem>
        <para>Customize <filename>live.files.list</filename>,
        <filename>live.dirs.list</filename>, and
        <filename>live.devices.list</filename>.  (See <link
        linkend="input-files" endterm="input-files-title"/>.)</para>
      </listitem>
      <listitem>
        <para>Install custom root window images: one, an XBM - (black &amp;
        white) called <filename>root_window.xbm</filename> and a color
        image in any format supported by the
        <application>xloadimage</application> program called, e.g.,
        <filename>root_window.png</filename>.  (See <link
        linkend="input-files" endterm="input-files-title"/>.)</para>
      </listitem>
      <listitem>
        <para>Install a custom image for the top right-hand corner of the
        stage 1 GUI screens (XPM - pixmap (color))
        <filename>logoicon.xpm</filename>.  (See <link
        linkend="input-files" endterm="input-files-title"/>.)</para>
      </listitem>
      <listitem>
        <para>Customize syslinux.screen*.txt. (i386 only) (See <link
        linkend="input-files" endterm="input-files-title"/>.)</para>
      </listitem>
    </itemizedlist>
  </chapter>

  <chapter id="ch-system-requirements">
    <title id="ch-system-requirements-title">System Requirements</title>

    <para>The process of building a &pgi;-based installer &emdash; running
    &build-command; &emdash; requires quite a bit of free disk space to
    work in, especially if a Debian package archive is included on the
    installation medium.  On an Intel x86-based machine, using the
    <parameter>--installer-only</parameter> option, the stock configuration
    requires a little over 300 megabytes of disk space (including the
    approximately 90 megabyte ISO image).  Note that this amount increases
    as, e.g., things are added to the live filesystem, the vendor-hook
    scripts are fleshed out, and so forth.</para>

    <para>When including Debian package archives, the space requirements
    grow appreciably.  At the time of this writing, including the complete
    Debian <literal>woody</literal> suite (both binary and source packages)
    occupies 7 ISO images (roughly 4.5 gigabytes).  It is wise to take a
    conservative (some would say pessimistic) approach and budget an equal
    amount for temporary usage; thus, one would perform a &pgi; build with
    9 gigabytes of free space on the disk partition containing the
    temporary directory.  The temporary directory that is used by &pgi; is
    configurable, as is the directory where the ISO images are placed.
    Needless to say, when being selective about what packages are included,
    and when providing only binary packages, space requirements can fall
    dramatically<footnote><para>Keep in mind that a great deal of the
    software in Debian GNU/Linux, including &pgi; itself, is licensed under
    the GNU General Public License (GPL).  When distributing GPL'ed
    software, you must either provide source code or a written offer with a
    term of 3 years to provide the corresponding source code.  A safe
    approach is to plan on providing at least as many source media as
    binary media.</para></footnote>.</para>

    <para>Generating ISO images with Debian package archives also requires
    access to a mirror of the Debian suite being used (e.g.,
    <literal>woody</literal>).  &http; access to a Debian APT repository in
    not sufficient, but an &nfs;-mounted mirror is.</para>

    <para>Running &build-command; is not particularly CPU or
    memory-intensive; instead, it is mostly disk-bound.  Therefore, as long
    as the disk space requirements are met, it is reasonable to run
    &build-command; on any system that is equivalent to or better than the
    target hardware in terms of processor horsepower and memory.  Fast
    drives (and drive buses) will improve the speed of the &build-command;
    process.</para>

    <para>&pgi; has extensive dependencies on underlying software; however,
    these are not particularly difficult to meet on a Debian system, since
    they are declared as dependencies of the &pgi; package.</para>

    <informalexample><screen>&prompt.root; <userinput>apt-get install pgi</userinput></screen></informalexample>

    <para>(or the equivalent operation in your favorite APT frontend) is
    sufficient to satisfy these requirements.</para>

    <note>
      <para>One requirement of &build-command; that cannot be expressed as
      a package dependency is its reliance on support for loopback-mounted
      filesystems in the running kernel.  One way to determine whether your
      kernel has support for this feature is to run the following
      command:</para>

      <informalexample><screen>&prompt.sh; <userinput>grep CONFIG_BLK_DEV_LOOP /boot/config-$(uname -r)</userinput></screen></informalexample>

      <para>If this kernel configuration variable is set to "y" or "m", you
      have the support; if it is set to "n", you do not.</para>
    </note>

    <para>The system requirements for the execution of the &pgi; installer
    itself are fairly easy to meet.  The installer uses an eight megabyte
    <literal>initrd</literal>; this is memory that will be unavailable for
    conventional purposes.  Contemporary machines ship with much more
    memory than &pgi; is likely to require.  A graphical mode installation
    requires more memory than the text mode installer because of the memory
    footprint of the X server and graphics libraries.  Recommended minimums
    for memory are 32 megabytes for text mode and 64 for graphical
    mode.</para>

    <para>There is no fundamental reason why a &pgi;-based installer would
    have difficulty running on an Intel 80386 machine, as long as the
    computer has a math co-processor installed.  Such an installation would
    be slow, as would the installation of any contemporary operating
    system.  We do not suggest any minimum requirements for desktop
    computers in production at the time of this writing; &pgi; will not
    push such machines anywhere near their limits.  The limiting factors
    for &pgi;-based installs in our experience are network bandwidth (in
    the case of network-based installations), and access times and transfer
    rates for optical drives and hard disks.  The faster your drives
    (especially the CD- or DVD-ROM drive), the faster the install will
    go.</para>

    <para>Disk space requirements for the installed system depend largely
    on the profiles you develop; a <quote>plain vanilla</quote> &pgi; build
    with no second stage at all fits comfortably in 500 megabytes of disk
    space.  As with CPU requirements, hard drive capacities have managed to
    out-pace even Debian's ability to consume space.</para>

  </chapter>

  <chapter id="ch-kernel-selection">
    <title id="ch-kernel-selection-title">Kernel and Module Selection</title>

    <para>The following functionality is needed for the kernel the
    installer uses.  Each of the following items refers to a Linux kernel
    configuration option; a brief description of why that feature is needed
    is given, as well as a note on whether the functionality may be
    compiled as module (as opposed to be being built-in to the kernel
    binary), and whether the feature may be optional in some &pgi;-based
    installers.</para>

    <variablelist>
      <varlistentry>
        <term>RAM disk support</term>
        <listitem>
          <para>Mandatory; required by the initial RAM disk support (see
          below).  Must be compiled-in, because initial RAM disk support is
          unavailable otherwise.  (Leave the related "Default RAM disk
          size" parameter at its default.)</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Initial RAM disk (initrd) support</term>
        <listitem>
          <para>Mandatory; enables the Linux kernel to boot without a root
          filesystem on the host machine.  Must be compiled-in.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Second Extended (ext2) filesystem support</term>
        <listitem>
          <para>Mandatory; used for reading and writing to the initial RAM
          disk as well as the target disk(s).  Must be compiled-in, because
          the installer's initrd is an ext2 filesystem.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>ISO 9660 filesystem support</term>
        <listitem>
          <para>Mandatory on the x86 architecture<footnote><para>On the
          Intel x86 architecture, ISO 9660 support is needed even if the
          live filesystem is mounted via &nfs;.</para></footnote>; optional
          but highly recommended on the IA-64 architecture.  Used for
          reading the installation medium.  If not enabled, only
          &nfs;-based installs will be possible.  May be compiled as a
          module.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>/proc filesystem support</term>
        <listitem>
          <para>Mandatory; the installer process requires the use of the
          <filename>/proc</filename> filesystem.  Must be compiled-in,
          because the hardware autodetection program
          <command>discover</command> uses <filename>/proc</filename> to
          identify installed hardware.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>VFAT filesystem support</term>
        <listitem>
          <para>Mandatory on the IA-64 architecture; optional but highly
          recommended on the x86 architecture.  Used to support DOS/Windows
          partitions and (on IA-64) EFI partitions.  May be compiled as a
          module.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Packet socket (Berkeley packet address family) support</term>
        <listitem>
          <para>Optional but highly recommended; used for &dhcp; support in
          the installation environment.  May be compiled as a
          module.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Unix domain socket support</term>
        <listitem>
          <para>Mandatory; used to support the X server used by the
          graphical interface.  May be compiled as a module.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>&tcpip; networking support</term>
        <listitem>
          <para>Mandatory; used to support network-based live filesystems
          and installations, as well as many features of the installed
          system.  Must be compiled-in.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>&nfs; support</term>
        <listitem>
          <para>Optional but highly recommended; used for &nfs;-mounted
          live filesystem support in the installation environment.  May be
          compiled as a module.</para> </listitem>
      </varlistentry>
      <varlistentry>
        <term>NLS Codepage 437 support</term>
        <listitem>
          <para>Used for filename recognition on DOS/VFAT filesystems.
          Same recommendations as VFAT support, above.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>IDE block device, IDE disk, and IDE CD-ROM support</term>
        <listitem>
          <para>Mandatory; used for accessing the IDE bus and attached
          devices.  May be compiled as modules.  To support usage of the
          &pgi; installation disk as a boot disk, compile this
          functionality into the kernel for users whose root filesystem
          resides on an IDE disk partition.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>Low-level SCSI drivers, SCSI disk, and SCSI CD-ROM support</term>
        <listitem>
          <para>Mandatory; Used for accessing SCSI controllers and attached
          devices.  May be compiled as modules.  Unless the hardware
          characteristics of the target machines are well-known, compile as
          many low-level SCSI drivers as possible.  To support usage of the
          &pgi; installation disk as a boot disk, compile the low-level
          driver(s) and SCSI disk support into the kernel for users whose
          root filesystem resides on a SCSI disk partition.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>SCSI emulation for IDE devices</term>
        <listitem>
          <para>Mandatory; &pgi; relies on the existence of this interface
          to simplify autodetection of the CD/DVD drive on the target
          system.  May be compiled as a module.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>USB support, UHCI support, OHCI support, USB mouse support</term>
        <listitem>
          <para>Optional; used by the graphical interface to communicate
          with USB-based input devices.  May be compiled as modules.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>AGP support</term>
        <listitem>
          <para>Optional; used by the graphical interface to support video
          cards with no dedicated video RAM.  May be compiled as a
          module.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>/proc/efi/vars support (IA-64 only)</term>
        <listitem>
          <para>Mandatory; used to update the EFI boot menu.  May be
          compiled as a module.</para>
        </listitem>
      </varlistentry>

    </variablelist>

    <note>
      <para>Also note that you may need to enable various kernel options
      for PCMCIA support, if you want your &pgi;-based installer to support
      PCMCIA devices on target systems.  This caveat holds true for Debian
      stock kernels as well; some laptops supported by Debian's
      <literal>kernel-image-2.2.20</literal> package are not supported by
      Debian's <literal>kernel-image-2.4.17-386</literal> package, for
      instance.  You may want to get into the habit of checking
      <filename>/boot/config-<replaceable>kernel-version</replaceable></filename>
      before starting a &build-command;.</para>
    </note>

  </chapter>

  <chapter>
    <title>Determining Package Placement on the Installer Media</title>

    <para>There are three configurations with respect to package placement
    on the installer media; one approach is to have no packages at all in
    the ISO image, relying upon a network connection on the installing host
    to retrieve Debian packages.  The second is to include on the ISO only
    those packages explicitly required by the &pgi; configuration, and the
    dependencies of those packages.  The third is to include all Debian
    packages, a process that will result in the generation of several ISO
    images, since there are more packages in the Debian distribution than
    will fit on one CD-ROM disc.<footnote><para>A recent calculation
    indicates that the Debian 3.0 ("woody") release's binary packages may
    barely fit on one 4.7GB DVD-ROM disc.  It would, however, be a good
    idea to plan for two.</para></footnote>  By default, a set of ISOs
    containing Debian source packages will be created as
    well<footnote><para>Source package ISOs are created by default due to
    the license terms of the GNU GPL and LGPL, under which a great deal of
    Debian software is licensed.</para></footnote>  In general, the number
    of source ISOs produced is approximately equal to the number of
    corresponding binary ISOs.</para>

    <section id="package-installer-only">
      <title>Creating Installer-Only &pgi; ISO Images</title>

      <para>By invoking &build-command; with the
      <parameter>--installer-only</parameter> option, an ISO that contains
      nothing but the files actually implementing the &pgi; installer
      itself will be generated.  This type of image is the quickest to
      generate, and will consume less than 100MB of space on
      the i386 architecture in &build-command;'s default
      configuration.  Another advantage of
      <parameter>--installer-only</parameter> builds is that they require no
      locally-mounted mirror of the Debian package archive.</para>

      <warning>
        <para>Note that because the installed packages' dependencies are
        calculated at <emphasis>build</emphasis> time, not install time,
        <application>debootstrap</application> can fail if a package to be
        installed automatically has changed its dependencies by the time
        the install is run.  For instance, if I create a &pgi; ISO with
        <parameter>--installer-only</parameter> and
        <parameter>--suite=unstable</parameter>, and am using a Debian mirror for
        package retrieval, my ISO will likely become outdated sooner or
        later.  More specifically, the <literal>python2.1</literal>
        package, for example, may not declare a dependency on
        <literal>libssl0.9.6</literal> at the time I create my ISO &mdash;
        but a few days later, when using my ISO to install a system, if the
        version of <literal>python2.1</literal> available in Debian's
        "unstable" tree depends on <literal>libssl0.9.6</literal>, I will
        be in trouble and the install will fail, becase
        <application>debootstrap</application> does not know how to resolve
        dependencies; it retrieves and installs exactly what you tell it
        to, no more and no less.</para>

        <para>Therefore, it is wise to use the
        <parameter>--installer-only</parameter> option only in conjunction with a
        stable package archive, or for short-term and/or experimental
        purposes.</para>

        <para>A future version of &pgi; may perform package dependency
        calculation at install time, and retrieve newly-required packages
        from the network.</para>

        <para>The above situation is not a problem with the other
        approaches to package placement, since the packages that the
        installer requires will be retrieved from the ISO, not the network,
        and their dependency relationships will be static.</para>
      </warning>
    </section>

    <section id="package-partial-only">
      <title>Creating &pgi; ISO Images with a Partial Package Archive</title>

      <para>By default (i.e., if neither the
      <parameter>--installer-only</parameter> nor <parameter>--complete</parameter>
      &build-command; options are specified, a limited set of Debian
      packages is included in the generated &pgi; ISO.  These packages
      include whatever <application>debootstrap</application> depends on, a
      small set of additional packages that &pgi; requires to be on the
      system (such as the <application>Discover</application> hardware
      auto-detection system, and a boot loader), any packages explicitly
      identified by the builder in the <filename>extra_packages</filename>
      and <filename>package_list</filename>, and finally any dependencies
      of any of the foregoing packages not already present.  Note that
      <filename>extra_packages</filename> refers to packages that must, in
      the builder's opinion, be installed to the system.  The
      <filename>package_list</filename> is a mechanism for
      <emphasis>including</emphasis> packages on the ISO, but of which
      installation is not compelled.</para>

      <para>Using &build-command; in this manner requires the existence of
      a Debian package archive mirror.  Use the
      <parameter>--build-mirror</parameter> option or
      <literal>PGI_BUILD_MIRROR</literal> variable to identify the location
      of such a mirror on the local filesystem.  (The mirror may be
      &nfs;-mounted from a remote host; "local" means only that the mirror
      must be accessible via a traditional pathname.)</para>
    </section>

    <section id="packae-complete">
      <title>Creating &pgi; ISO Images with a Complete Package Archive</title>

      <para>If the <parameter>--complete</parameter> option is given to
      &build-command;, a complete set of packages from the Debian
      distribution is included as part of the (generally more than one) ISO
      images generated.</para>

      <para>Using &build-command; in this manner requires the existence of
      a Debian package archive mirror.  Use the
      <parameter>--build-mirror</parameter> option or
      <literal>PGI_BUILD_MIRROR</literal> variable to identify the location
      of such a mirror on the local filesystem.  (The mirror may be
      &nfs;-mounted from a remote host; "local" means only that the mirror
      must be accessible via a traditional pathname.)</para>
    </section>
  </chapter>

  <chapter>
    <title>Networking Requirements for the Installer</title>

    <section id="network-helping-users">
      <title>Pre-configuring Network Options</title>
      <subtitle>Helping Your Users Help Themselves</subtitle>

      <para>Under some circumstances, the user of a &pgi;-based installer
      may be required to provide network parameters when booting.  As this
      can be one of the more complex tasks that the installer asks of the
      user, it is worth considering how to make the process less
      daunting.</para>

      <para>It is important to recognize that if the installer disc includes
      all needed packages, no network connectivity is required by &pgi;
      itself.  Even then, it is well worth <link
      linkend="network-user-doc">documenting</link> that fact so that the end
      user knows not to worry about the boot-time parameters.</para>

      <para>If, on the other hand, no packages are included
      (<command>&build-command;
      <parameter>--installer-only</parameter></command>), then a network
      connection will be required.  &pgi; will attempt to contact a &dhcp;
      server by default if the user does not provide any networking
      information and <parameter>--installer-only</parameter> was specified
      by the installer creator.</para>

      <para>If your installer image is targetted at a discrete set of users
      in a common network environment, pre-configuring any necessary <link
      linkend="options-and-environment">&http; proxy</link> for package
      retrieval is one way to reduce the chance of user error.  Note that it
      is not necessary to set up an &http; proxy if your users have
      unrestricted outbound &http; connectivity, or if you have configured
      &pgi; to use an internal Debian archive mirror that users don't require
      an &http; proxy to access.  Furthermore, we strongly recommend setting
      up a &dhcp; server to serve network configuration parameters to users'
      workstations.  By preparing your network in this way, and by
      pre-configuring the &http; proxy and/or archive mirror, users of
      installer-only &pgi; discs need not know anything about network
      configuration to perform an installation<footnote><para>at least for
      the first stage; what happens in the second stage is up to
      you</para></footnote>.</para>
    </section>

    <section id="network-user-doc">
      <title>Documentation for the User</title>

      <para>On the <literal>i386</literal> architecture,
      <application>syslinux</application> provides help screens that can be
      <link
      linkend="syslinux-screen-customization">customized</link>.</para>

      <para>Since the <application>syslinux</application> help screens are
      not universally available, and since there is limited room for
      comprehensive help text, a user manual is provided with the &pgi;
      package.  You should customize this manual to describe the installer
      as your users will experience it.</para>
    </section>
  </chapter>

  <chapter id="ch-second-stage">
    <title id="ch-second-stage-title">Implementing the Second Stage</title>

    <para>There are two points at which the installer executes
    vendor-supplied code &mdash; if available &mdash; before proceeding
    with its business.  These execution points ("vendor hooks") are the
    means by which a second stage is set up and run.  An example vendor
    hook is provided with &pgi; to instruct the system to run
    <command>base-config</command>, just like Debian's own boot-floppies.
    Another example demonstrates usage of Progeny's &configlet;
    configuration system, which is similar to that featured in the Progeny
    Debian distribution and is now part the of the Debian
    distribution.</para>

    <para>To implement one's own second stage, any needed packages must be
    added to the list of extra packages (see <link linkend="input-files"
    endterm="input-files-title"/>), and the vendor hooks must be written to
    ensure that appropriate tasks are carried out in the init process (in
    the provided <quote>configlets</quote> example, this means launching
    the X server and starting the configlet druid).</para>

    <para>The first vendor hook is run right before the installer scripts
    themselves.  This, the <filename>preinst.sh</filename> script, permits
    you to perform any housekeeping that needs to be done before the target
    disk is partitioned, the base system unpacked, the boot loader set up,
    or your post-installation hook executed.  To be honest, we can't think
    of many applications for the pre-installation hook, but it is present
    in the event that you are more imaginative than we.</para>

    <para>The second vendor hook is <filename>postinst.sh</filename> and,
    as you might guess from the name, it runs after the installation proper
    has occurred.  At this time, you can expect the target filesystem to be
    present and mounted at <filename>/target</filename>.  We expect typical
    applications of the post-installation hook to consist of little more
    than copying over files from the live filesystem to the target, one of
    which would likely be a shell script to be placed in
    <filename>/target/etc/rcS.d</filename> to have the booting target
    system's <command>init</command> process transfer control to programs
    of the vendor's choosing.  Note that it is not necessary to invoke
    <command>apt-get</command> from your post-installation vendor hook;
    instead, you may simply name the packages you wish to install in
    <filename>/etc/pgi/&codename;/extra_packages</filename>, and they will
    be present before your post-installation hook is executed.</para>

    <para>Both vendor hooks must be POSIX shell scripts (no Bashisms,
    please).  They will be <command>source</command>d instead of executed,
    so do not turn on the <parameter>-e</parameter> shell option (unless
    you are extremely careful with the exit status of every command you run
    and turn it back off before the end of your script), and do not
    explicitly <command>exit</command> the script.  With those caveats, you
    may do practically anything that can be done in a shell script,
    including, of course, execute any ELF programs that you may also have
    provided.  Be conservative with usage of typical shell utilities, as
    many standard commands exist in the live filesystem in their BusyBox
    implementations.  If you require a more featureful version of a
    utility, ship it on the live filesystem by editing
    <filename>live.files.list</filename> (see <link linkend="input-files"
    endterm="input-files-title"/>) or run the version in the target
    system.</para>

    <para>You can expect several variables to be in the environment of your
    vendor hook scripts (see <link endterm="codename-contents-title"
    linkend="codename-contents"/>):</para>

    <variablelist>

      <varlistentry>
        <term><varname>ARCH</varname></term>
        <listitem>
          <para>This will always be set, and contains the name of the host
          machine architecture as used by Debian packages (i.e.,
          <quote>i386</quote> for all 32-bit x86-compatible machines,
          <quote>powerpc</quote> instead of <quote>ppc</quote>, and so
          forth).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>DISPLAY</varname></term>
        <listitem>
          <para>This will only be set if &pgi;'s remote graphical
          installation feature is used.  (A local X server will not be
          running at the time the vendor hook scripts are called.) If set,
          this will contain the name of an X display on a remote
          host.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>DMESGLOG</varname></term>
        <listitem>
          <para>This is always set and contains the absolute pathname to
          the a file containing the output of the <command>dmesg</command>
          command.  (The file will be empty when your pre-installation hook
          runs, but not when the post-installation hook runs.)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>IDENTLOG</varname></term>
        <listitem>
          <para>This is always set and contains the absolute pathname to a
          file containing the RCS IDs of several files that form part of
          &pgi;.  (The file will be empty when your pre-installation hook
          runs, but not when the post-installation hook runs.)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>KERNEL_VERSION</varname></term>
        <listitem>
          <para>This is always set and contains the output of
          <command>uname -r</command>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>LD_LIBRARY_PATH</varname></term>
        <listitem>
          <para>This is always set and serves its usual purpose for the
          dynamic loader.  Meddling with this variable can break the
          installer.  If you must change it, store its value before you do
          so, and restore that value before your script finishes.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>LIVE</varname></term>
        <listitem>
          <para>This is always set and contains the absolute pathname of
          the mount point of the live filesystem.  Always use this variable
          to locate files in the live filesystem, and your customizations
          will be robust if &pgi; changes this mount point.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>LOGFILE</varname></term>
        <listitem>
          <para>This is always set and contains the the absolute pathname
          to a file containing various human-readable data of interest
          concerning the progress of the installation.  You are encouraged
          to append text to this file to debug your vendor hook scripts
          and/or provide feedback suitable for consumption by those who may
          be supporting users of your &pgi;-based installer.  For instance,
          if your hooks interact with the user and give him or her options
          to choose from, it is a good idea to record their choices here so
          that you can trace the path they took through your code.
          Overwriting this file is highly discouraged and may render your
          product unsupportable.  Also see the <function>pgilog</function>
          function described at the end of this chapter.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>MIRROR</varname></term>
        <listitem>
          <para>This is always set and contains a URI to the Debian package
          archive that &debootstrap; uses to install the base
          system.  This may be an <literal>http</literal> URI or a
          <literal>file</literal> URI.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>PATH</varname></term>
        <listitem>
          <para>This is always set and serves its usual function.  Like
          <varname>LD_LIBRARY_PATH</varname>, changing the contents of this
          variable can break the installer.  If you must change it, store
          its value before you do so, and restore that value before your
          script finishes.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>PGIDEBUG</varname></term>
        <listitem>
          <para>This is set to a non-null value if the user indicated that
          he or she wanted to run the installer in a debugging mode.  You
          may take advantage of this in your vendor hook to, for example,
          launch shells at strategic points so that developers or very
          advanced users can examine the system.  Furthermore, you can use
          it to increase the verbosity level of your scripts to the
          console.  Also see the <function>pgilog</function> function
          described at the end of this chapter.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>PROMPTING</varname></term>
        <listitem>
          <para>This is set to one of two recognized values,
          <parameter>less</parameter> and <parameter>more</parameter>.
          This is used to control the interactivity level of the installer.
          If this variable is set to <parameter>more</parameter>, you
          should not make assumptions about the user's desires or system
          configuration if you do not have to.  We recommend testing this
          variable only against the string
          <parameter>more</parameter>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>PYTHONHOME</varname></term>
        <listitem>
          <para>This is always set and tells the Python interpreter where
          to find its modules.  &pgi; relies upon this variable being set
          reasonably; if you must change it, store its value before you do
          so, and restore that value before your script finishes.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>SUITE</varname></term>
        <listitem>
          <para>This is always set and contains the name of the Debian
          archive suite from which packages are downloaded.  The suite name
          is the code name of the Debian release; e.g.,
          <literal>potato</literal>, <literal>woody</literal>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>SYSLOG</varname></term>
        <listitem>
          <para>This is always set and contains the absolute pathname of
          the system log file (as used by the <command>syslog</command>
          command) in the installer environment.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>TARGET</varname></term>
        <listitem>
          <para>This is always set and contains the absolute pathname of
          the mount point of the target root filesystem.  Always use this
          variable to locate files in the target filesystem(s), and your
          customizations will be robust if &pgi; changes this mount
          point.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>TEXTMODE</varname></term>
        <listitem>
          <para>This is set to a non-null value if the user selected at
          boot time to perform the installation in text mode.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>ip</varname></term>
        <listitem>
          <para>This is set if networking is configured; if so, it contains
          the address of the configured interface in dotted-quad notation.
          This address may have been set by the user at boot-time, or by a
          &dhcp; server.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>subnet</varname></term>
        <listitem>
          <para>This is set if networking is configured; if so, it contains
          the subnet mask of the configured interface in dotted-quad
          notation.  This mask may have been set by the user at boot-time,
          or by a &dhcp; server.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>router</varname></term>
        <listitem>
          <para>This is set if networking is configured; if so, it contains
          one or more addresses of gateway routers to be used in
          dotted-quad notation.  These addresses may have been set by the
          user at boot-time (in which case there will be only one), or by a
          &dhcp; server (in which case there is typically only one).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>broadcast</varname></term>
        <listitem>
          <para>This is set if networking is configured; if so, it contains
          the broadcast address of the configured interface in dotted-quad
          notation.  This address may have been set by the user at
          boot-time, or by a &dhcp; server.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>dns</varname></term>
        <listitem>
          <para>This is set if networking is configured; if so, it contains
          one or more addresses of &dns; name servers to be used in
          dotted-quad notation.  These addresses may have been set by the
          user at boot-time (in which case there will be only one), or by a
          &dhcp; server (in which case there is typically more than
          one).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>http_proxy</varname></term>
        <listitem>
          <para>This is set if it was specified at build time (see <link
          linkend="options-and-environment" endterm="ap-pgi-build-title"/>)
          or by the user when the installer was booted.  If set, it
          contains the URL of an &http; proxy server.</para>
        </listitem>
      </varlistentry>

    </variablelist>

    <para>When writing your vendor hook scripts, it is prudent to log
    anything interesting to the <varname>LOGFILE</varname>, even if
    <varname>PGIDEBUG</varname> is not set.  For human-readable status
    messages, you can accomplish both of above by using the built-in shell
    function <function>pgilog()</function>, which works just like
    <command>echo</command>.  You can give <function>pgilog</function> the
    <parameter>-n</parameter> option to suppress the newline at the end of
    the line.</para>
  </chapter>

  <chapter id="ch-preparing-files">
    <title id="ch-preparing-files-title">Preparing Your Files</title>

    <section>
      <title><filename>/etc/pgi/&codename;</filename></title>

      <para>As mentioned in the <link linkend="ch-overview"
      endterm="ch-overview-title"/> chapter, &pgi; can be configured to
      produce several distinct installer images without having to change
      its configuration in between.  This is achieved by associating each
      installer configuration (or profile, if you will) with a code name,
      which is then supplied on the &build-command; command line as an
      option.</para>

      <informalexample>
        <screen>
&prompt.sh; <userinput>pgi-build --codename=home</userinput>
&prompt.sh; <userinput>pgi-build --codename=work</userinput>
        </screen>
      </informalexample>

      <para>This flexibility is accomplished through the creation of a
      subdirectory under <filename>/etc/pgi</filename> containing the
      customized input files needed to generate an installer image. The
      &codename; may be any name that is useful for you, the installer
      vendor; it has nothing to do with Debian release code names, which
      are referred to as suites.</para>

      <para>The &codename; must contain only alphanumeric characters and
      underscores; it must not start with a number.</para>

      <para>For instance, to start developing the profiles in the example
      above, you could use a recursive copy command to duplicate the
      existing <literal>custom</literal> codename directory that ships with
      the &pgi; package.</para>

      <informalexample>
        <screen>
&prompt.sh; <userinput>cp -a /etc/pgi/custom /etc/pgi/home</userinput>
&prompt.sh; <userinput>cp -a /etc/pgi/custom /etc/pgi/work</userinput>
        </screen>
      </informalexample>

      <para>You would then modify the files in each of these directories as
      needed for the distinct environments.</para>

    </section>

    <section>
      <title><filename>/etc/pgi/&codename;/options</filename></title>

      <para>Use this file to define basic parameters for your build. Some
      examples of variables defined here include the destination directory
      for the ISO image(s), the kernel version to use, and where to find a
      mirror of the Debian archive.</para>

      <para>Alternatively, you may pass command-line arguments to
      &build-command; for most of these values. See <link
      linkend="options-and-environment"
      endterm="options-and-environment-title"/> for a list of command-line
      options and their corresponding variable names.</para>

    </section>

    <section id="codename-contents">
      <title id="codename-contents-title">Other Files Under <filename>/etc/pgi/&codename;</filename></title>

      <para>See <link linkend="input-files" endterm="input-files-title"/>
      for a list of the customizable files located here.</para>

    </section>
  </chapter>

  <chapter id="ch-cookbook">
    <title id="ch-cookbook-title">&build-command; Cookbook</title>

    <para>&build-command; sports a bewildering array of knobs, switches,
    and dials.  This chapter provides some example invocations and
    solutions.  For complete coverage, see <xref
    linkend="ap-pgi-build"/>.</para>

    <section>
      <title>Selecting Debian Package Archive Mirrors</title>

      <para>A Debian installer is fundamentally a delivery mechanism for
      Debian packages; &pgi; is no different.  Debian packages are kept at
      many locations on the Internet.  A large number of locations contain
      the official distribution; these sites are referred to as
      <quote>mirrors</quote>, since they are clones of a central package
      archive server which is not publicly accessible<footnote><para>due to
      overwhelming demand and limited bandwidth</para></footnote>.  There
      are also other, generally much smaller, repositories that are not run
      by or affiliated with the Debian Project, and are typically dedicated
      to providing Debian packages for a given piece of software or the
      products of a particular company.  &pgi; uses Debian mirrors in two
      distinct ways; a mirror is used by the installer itself when a Debian
      package archive cannot be found on the live filesystem, and the
      &build-command; process uses a mirror that is mounted on the system
      used to build a set of &pgi;-based installation images.  The former
      defaults to Progeny Linux Systems, Inc.'s Debian mirror,
      <literal>archive.progeny.com</literal><footnote><para>Using the
      round-robin Debian mirrors in the United States can be problematic,
      since the <filename>Packages</filename> index file may be retrieved
      from one location, and the actual packages from another location
      which is less up-to-date.  This sort of desynchronization will cause
      <application>debootstrap</application> to bomb.</para></footnote>; it
      is used if the installer can't find Debian packages on the live
      filesystem (when it's mounted via &nfs;, for example).  The latter is
      necessary when running &build-command; without the
      <parameter>--installer-only</parameter> option.  Use the
      <parameter>--build-mirror</parameter> option to specify the location
      of your Debian package mirror.  The build mirror may be
      &nfs;-mounted.</para>

      <note>
        <para>A local mirror <emphasis>must</emphasis> be available if you
        are not using the <parameter>--installer-only</parameter> option;
        there is a great deal of internal structure to a Debian package
        repository that is not accessible through the package retrieval
        methods used by, e.g., <command>apt</command>.  &build-command;
        requires a local mirror to populate the ISO image(s), because those
        ISOs will themselves contain package repositories.</para>
      </note>

      <screen>
&prompt.sh; <userinput>&build-command; --pgi-mirror=http://archive.progeny.com/debian
      --build-mirror=/archive/debian/ftp</userinput>
      </screen>

    </section>

    <section>
      <title>Selecting the Kernel Version To Be Used by &pgi;</title>

      <para>At the time of this writing, there are three versions of the
      Linux kernel that are both considered <quote>stable</quote> and
      actively maintained.  The earliest, in the
      2.0.<replaceable>x</replaceable> series, is nearly abandoned, and
      cannot be used with &pgi; since it lacks facilities that the &pgi;
      installer requires.  The others are the
      2.2.<replaceable>x</replaceable> series and the
      2.4.<replaceable>x</replaceable> series.  &pgi; supports both of
      these kernel versions on the Intel x86 architecture and continuing
      support for both is planned.  On the IA-64 architecture, only the
      2.4.<replaceable>x</replaceable> series is supported.</para>

      <para>Debian makes multiple variants of each kernel version available
      in Debian packages; these are called <quote>flavors</quote>.  Each
      flavor has different configuration options.  Some, like the stock
      2.2.20 package (<literal>kernel-image-2.2.20</literal>), take a
      <quote>kitchen sink</quote> approach, compiling many IDE and SCSI
      device controllers directly into the kernel.  Others lack SCSI
      support entirely.  There are many flavors of Linux 2.4 available for
      Debian/i386, but only one of them will work with &pgi;: the
      <literal>-386</literal> flavor.  This flavor expects its
      <literal>initrd</literal> to be an ext2 filesystem, which is what
      &pgi; requires.  Other versions use the <literal>CRAM</literal>
      (Compressed RAM) filesystem, which is small but not writable.  The
      &pgi; installer demands a writable <literal>initrd</literal>.  You
      can use the <parameter>--kernel-version</parameter> to specify a
      kernel version rather than the default (whichever kernel is running
      on your build system):</para>

      <informalexample>
        <screen>
&prompt.sh; <userinput>&build-command; --kernel-version=2.4.18-386</userinput>
        </screen>
      </informalexample>

      <para>If Debian does not provide a kernel package flavor that suits
      your needs (or &pgi;'s), you can always compile and package your own.
      For this we recommend the excellent <literal>kernel-package</literal>
      Debian package, which makes the process quite easy.</para>

    </section>

    <section>
      <title>Identifying and Branding your &pgi;-Based Installer</title>

      <para>&build-command; provides a few options for branding or
      identifying your images.  You can use the
      <parameter>--builder</parameter> option to set the builder email
      address.  The <parameter>--product</parameter> option sets the name
      of the product (default: <quote>GNU/Linux</quote>) and
      <parameter>--vendor</parameter> sets the vendor name (default:
      <quote>Debian</quote>).</para>

      <informalexample>
        <screen>
&prompt.sh; <userinput>&build-command; --builder=debian-staff@example.com --vendor="Example Penguin Unix Systems"
        --product="Debian GNU/Linux"</userinput>
        </screen>
      </informalexample>

    </section>

    <section>
      <title>Selecting the Temporary Directory Used by &pgi;</title>

      <para>When building multiple &pgi; profiles, it may be convenient to
      specify the temporary directory to be used by &build-command;.  This
      is achieved through the <parameter>--tmpdir</parameter>
      option:</para>

      <informalexample>
        <screen>
&prompt.sh; <userinput>&build-command; --tmpdir=vanilla-2.4.17-386 --kernel-version=2.4.17-386</userinput>
        </screen>
      </informalexample>

      <para>Other options for controlling where temporary files and output
      files go are available; see <link linkend="options-and-environment"
      endterm="options-and-environment-title"/>.</para>

    </section>

    <section>
      <title>Controlling Cleanup and Setting up Live Filesystems for &nfs;
      Usage</title>

      <para>By default, &build-command; does not clean any of the
      directories it uses by default; this is useful if you need to try to
      recover from a failed &build-command; and are interested in looking
      at some of the transient files produced by &build-command; or need to
      keep the live filesystem around for &nfs; export.</para>

      <warning>
        <para>Be very careful when using the <parameter>--clean</parameter>
        and <parameter>--post-clean</parameter> options in conjunction with
        any of the <parameter>--tmpdir</parameter>,
        <parameter>--misctmpdir</parameter>, or
        <parameter>--outdir</parameter> options (or their corresponding
        option variables).  The cleanup process can remove files that have
        nothing do with &pgi; if these directories are not chosen
        carefully.  For example, it is unwise to specify <literal>--clean
        --outdir=/</literal>.  The default temporary and output directory
        names that &build-command; uses are such that it is unlikely you
        will lose any data when specifying <parameter>--clean</parameter>
        or <parameter>--post-clean</parameter>.</para>
      </warning>

      <para><parameter>--clean</parameter> instructs &build-command; to
      remove everything in its temporary directories and output directory
      before going to work, and in its temporary directories after it
      finishes (the latter can be overridden with
      <parameter>--no-post-clean</parameter>.  In general, after
      investigating the cause of a &build-command; failure, you should
      specify <parameter>--clean</parameter> so that any configuration
      changes you make are reflected from the beginning of the build
      process when you run &build-command; again.  Otherwise, you run a
      good chance of producing a useless installer ISO.</para>

      <para><parameter>--post-clean</parameter> instructs &build-command;
      to not clean up its temporary directories after it finishes.  This
      option will prove useful to those who are confident that their ISO
      builds are sound and useful, and who have no need to create &nfs;
      exports containing a live filesystem for use by &pgi;.</para>

      <para>The live filesystem is found in a subdirectory of the temporary
      directory called <filename>misc/live</filename> (if the miscellaneous
      temporary directory was explicitly set, it is a subdirectory of that
      directory).</para>

      <para>If the live filesystem for a given &pgi; build is located in
      the directory
      <filename>/home/frank/pgi/vanilla-2.4.17-386/misc/live</filename> on
      a host called <literal>margaret</literal>, then the administrator of
      <literal>margaret</literal> can add the following line to
      <filename>/etc/exports</filename>:</para>

      <informalexample>
        <screen>
<userinput>/home/frank/pgi/vanilla-2.4.17-386/misc/live 192.168.0.0/16(ro)</userinput>
        </screen>
      </informalexample>

      <para>In the example above, we provide a read-only export to any
      machine with an address in the given range.  The details of &nfs;
      server configuration and <filename>/etc/exports</filename> management
      are beyond the scope of this manual, but the corresponding &pgi;
      boot-time option to access this &nfs; export is not:</para>

      <informalexample>
        <screen>
<userinput>install nfslive=margaret:/home/frank/pgi/vanilla-2.4.17-386/misc/live</userinput>
        </screen>
      </informalexample>

      <para>The above example assumes that a &dhcp; server will be
      available to supply the installing host with network configuration
      information, including a domain and DNS nameserver to use.
      Otherwise, the network will have to be configured by the user at
      install time.</para>

    </section>

  </chapter>

  <chapter id="ch-wrapping-it-up">
    <title id="ch-wrapping-it-up-title">Wrapping It Up</title>
      <para>When the scripts are finished building the installation image,
      you can then examine the image by loopback mounting it.</para>

    <section>
      <title>Examining the Generated ISO Images with Loopback Mounting</title>

      <para>Mounting an ISO image as a loopback filesystem will let you
      look in the image as directory in the filesystem.  One reason for
      doing this is to evaluate the directory structure to ensure the
      correct packages are on the ISO.</para>

      <para>Generally, loopback mounting the image is not necessary, but
      can sometimes help to track down problems with an image build.</para>

      <para>To loopback mount an image, use the following command:</para>

      <informalexample>
        <screen>
&prompt.root; <userinput>mount -t iso9660 -o loop,ro <replaceable>image.file</replaceable> <replaceable>/mount.point</replaceable></userinput>
        </screen>
      </informalexample>

      <para>This command mounts the image file
      (<filename>image.file</filename>) to the mount point
      (<filename>/mount.point</filename>) as a <literal>iso9660</literal>
      filesystem type in loopback mode.</para>

      <para>A concrete example:</para>

      <informalexample>
        <screen>
&prompt.root; <userinput>mount pgi-i386.iso /mnt -t iso9660 -o loop</userinput>
        </screen>
      </informalexample>
    </section>

    <section>
      <title>Creating CD/DVDs from ISO Images</title>

      <para>There are several applications that will burn an ISO image to a
      recordable CD or DVD.  One of these applications is
      &cdrecord;.</para>

      <para>In order to use &cdrecord;, you will need to know the logical
      location of the recording device (<quote>burner</quote>) in a
      specialized format.  &cdrecord; has an option for locating the
      device.  The following example shows the
      <parameter>-scanbus</parameter> option which identifies the burner as
      <literal>0,0,0</literal>.</para>

      <note>
        <para>&cdrecord; assumes that the burner is a SCSI device.  If you
        have an IDE burner, you will need to use SCSI emulation by loading
        the <application>ide-scsi</application> module (<command>modprobe
        ide-scsi</command>) into the kernel.</para>
      </note>

      <screen>
&prompt.root; <userinput>cdrecord -scanbus</userinput>

Cdrecord 1.10 (i686-pc-linux-gnu) Copyright (C) 1995-2001 J&ouml;rg Schilling
Linux sg driver version: 3.1.22
Using libscg version 'schily-0.5'
scsibus0:
        0,0,0     0) 'TEAC    ' 'CD-W512EB       ' '2.0A' Removable CD-ROM
        0,1,0     1) *
        0,2,0     2) *
        0,3,0     3) *
        0,4,0     4) *
        0,5,0     5) *
        0,6,0     6) *
        0,7,0     7) *
scsibus1:
        1,0,0   100) 'QUANTUM ' 'ATLAS V  9 WLS  ' '0201' Disk
        1,1,0   101) 'IBM     ' 'DDYS-T36950M    ' 'S80D' Disk
        1,2,0   102) *
        1,3,0   103) *
        1,4,0   104) 'SEAGATE ' 'ST336704LWV     ' '4301' Disk
        1,5,0   105) *
        1,6,0   106) *
        1,7,0   107) *
        </screen>

      <para>Once the burner is identified and the ISO image is available,
      you can record the image(s) to optical disc(s) using a command
      similar to the following example:</para>

      <informalexample>
        <screen>
&prompt.root; <userinput>cdrecord -verbose speed=8 -eject dev=0,0,0 pgi-i386.iso</userinput>
        </screen>
      </informalexample>

      <para>This example records the <filename>pgi-i386.iso</filename>
      image to device <literal>0,0,0</literal> at a maximum speed of 8x.
      &cdrecord; will provide verbose information about the burn and will
      eject the disc when the burn is complete.</para>

      <para>Once the disc is finished you can then use it to boot a
      computer for installation.</para>

    </section>
  </chapter>

  <appendix id="ap-pgi-build">
    <title id="ap-pgi-build-title">Running &build-command;</title>

    <refentry>
      &pgi-build-refentry;
    </refentry>
  </appendix>

  <appendix>
    <title>Example Configuration Files</title>

    <para>&pgi; comes with two example flavors or code names, both in
    <filename>/etc/pgi</filename>.  One,
    <filename>/etc/pgi/base-config</filename>, creates a second stage
    similar to Debian's.  The other,
    <filename>/etc/pgi/configlets</filename>, creates a second stage using
    the configlets, similar to the original Progeny Debian
    installer.</para>

    <note>
      <para>One fundamental limitation of
      <application>base-config</application> CDs, independent of &pgi;, is
      that either the CD set must be complete, or
      <application>base-config</application> must pull all packages from
      the network.  This limitation may be addressed in a future version of
      <application>base-config</application>.</para>
    </note>
  </appendix>

</book>

<!-- vim: set ai et tw=75 sw=2 sts=2: -->
<!--  Local variables: -->
<!--  eval: (sgml-load-dtd "../doctools/docbook.ced") -->
<!--  End: -->