<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

<!-- Process this file with docbook-to-man to generate an nroff manual
     page: `docbook-to-man manpage.sgml > manpage.1'.  You may view
     the manual page with: `docbook-to-man manpage.sgml | nroff -man |
     less'.  A typical entry in a Makefile or Makefile.am is:

manpage.1: manpage.sgml
	docbook-to-man $< > $@
  -->

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
  <!ENTITY dhfirstname "<firstname>Matt</firstname>">
  <!ENTITY dhsurname   "<surname>Zimmerman</surname>">
  <!-- Please adjust the date whenever revising the manpage. -->
  <!ENTITY dhdate      "<date>March 12, 2002</date>">
  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
       allowed: see man(7), man(1). -->
  <!ENTITY dhsection   "<manvolnum>1</manvolnum>">
  <!ENTITY dhemail     "<email>mdz@debian.org</email>">
  <!ENTITY dhusername  "Matt Zimmerman">
  <!ENTITY dhucpackage "<refentrytitle>rootstrap</refentrytitle>">
  <!ENTITY dhpackage   "rootstrap">

  <!ENTITY debian      "<productname>Debian GNU/Linux</productname>">
  <!ENTITY gnu         "<acronym>GNU</acronym>">
]>

<refentry>
  <refentryinfo>
    <address>
      &dhemail;
    </address>
    <author>
      &dhfirstname;
      &dhsurname;
    </author>
    <copyright>
      <year>2002</year>
      <holder>&dhusername;</holder>
    </copyright>
    &dhdate;
  </refentryinfo>
  <refmeta>
    &dhucpackage;

    &dhsection;
  </refmeta>
  <refnamediv>
    <refname>&dhpackage;</refname>

    <refpurpose>Construct a root filesystem image in a file</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>rootstrap</command>
      <arg choice=opt
      rep=repeat><replaceable>options</replaceable></arg>

      <arg choice=req><replaceable>image file</replaceable></arg>

    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>DESCRIPTION</title>

    <para>
      rootstrap is a tool for creating root filesystem images.  It was
      written primarily for use with User-Mode Linux, but may be
      useful for other purposes as well.
    </para>

    <para>
      Because it uses User-Mode Linux to bootstrap itself, rootstrap
      can be used without root privileges on the host system, which
      are normally required for this task in order to use chroot(2)
      and mount and unmount filesystems.  Rootstrap boots UML and uses
      tools from the host filesystem to perform installation and
      configuration tasks.
    </para>

  </refsect1>
  <refsect1>
    <title>OPTIONS</title>

    <variablelist>
      <varlistentry>
        <term>-s, --image-size</term>
        <listitem>
          <para>
            Sets the initial size of the image, overriding the
            'initialsize' option in rootstrap.conf.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-o <replaceable>logfile</replaceable></term>
        <listitem>
          <para>
            Log the output of the creation process to
            <replaceable>logfile</replaceable> instead of to standard
            output.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-u <replaceable>args</replaceable>, --umlargs <replaceable>args</replaceable></term>
        <listitem>
          <para>
            Pass additional arguments to user-mode linux when booting
            to create the image.  Supplements the 'umlargs' option in
            rootstrap.conf.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>

  </refsect1>

  <refsect1>
    <title>Configuration</title>

    <para>
      The configuration file consists of sections, starting with a
      "[section]" header, followed by "option: value" entries, with
      continuations and such in the style of RFC 822.
    </para>

    <para>
      With the exception of the special section "global", sections are
      named after a corresponding module.  When that module is
      executed, it receives the option/value pairs in its section as
      environment variables.  All modules inherit global options as
      environment variables, except where overridden by options within
      their specific section.  At least PATH must be set here, in
      addition to the required parameters listed below under [global].
    </para>

    <para>
      Documentation for configurable modules distributed with
      rootstrap is included below.  This section is currently
      incomplete.
    </para>

  </refsect1>

  <refsect1>
    <title>Modules</title>

    <refsect2>
      <title>[global]</title>

      <para>
        Contains configuration options that affect the operation of
        rootstrap itself, or several modules.
      </para>

      <variablelist>
        <varlistentry>
          <term>fstype</term>
          <listitem>
            <para>
              The type of filesystem to create (ext2, ext3, reiserfs,
              etc.)
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>initialsize</term>
          <listitem>
            <para>
              The initial size of the filesystem image (in megabytes).
              This must be large enough to contain a complete
              installed system as produced by the selected modules.
              It will be created sparsely, so additional space is not
              entirely allocated until it is used.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>freespace</term>
          <listitem>
            <para>
              The amount of free space to leave on the filesystem (in
              megabytes).  The filesystem will be resized, if
              possible, to adjust the amount of free space to
              approximately this amount.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>modules</term>
          <listitem>
            <para>
              The list of modules to invoke, in order.  Each module
              will be searched for in several directories, listed in
              the FILES section below, and passed environment
              variables based on the options set in the corresponding
              section of the configuration file.
            </para>
          </listitem>
        </varlistentry>

      </variablelist>
    </refsect2>

    <refsect2>
      <title>[network]</title>

      <para>
        Network configuration.  This module configures virtual
        networking with the user-mode Linux system used to build the
        filesystem image.  Note that this has nothing to do with
        network configuration of the resulting filesystem image; it is
        only used during image creation.  Its presence is not strictly
        necessary, if the selected modules do not require network
        access (for example, with a local package mirror) and the
        network module is not included in the global "modules" option.
      </para>

      <variablelist>
        <varlistentry>
          <term>interface</term>
          <listitem>
            <para>
              The name of the UML network interface to configure,
              typically "eth0".
              </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>host</term>
          <listitem>
            <para>
              The IP address of the host side of the interface (the
              host on which rootstrap is run)
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>uml</term>
          <listitem>
            <para>
              The IP address of the UML side of the interface (where
              the system is being built)
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>transport</term>
          <listitem>
            <para>
              The type of virtual networking interface to be used.
              Typically "tuntap".
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>netmask</term>
          <listitem>
            <para>
              The netmask for the network interface (applies to both
              sides)
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>gateway</term>
          <listitem>
            <para>
              A default gateway to be used by the user-mode Linux
              system
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

    </refsect2>

    <refsect2>
      <title>[debian]</title>

      <para>
        Debian installation.  This module installs a basic Debian
        system using debootstrap.
      </para>

      <variablelist>
        <varlistentry>
          <term>dist</term>
          <listitem>
            <para>
              The distribution to install (e.g., stable, unstable,
              potato, woody, etc.)
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>mirror</term>
          <listitem>
            <para>
              A URL for a Debian archive containing the base
              packages.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>exclude</term>
          <listitem>
            <para>
              A list of packages which should be excluded (never
              installed at all).  It is quite possible to produce a
              broken system, or fail to build a system at all, if this
              option is used improperly.  It is useful for excluding
              packages, such as pcmcia-cs, which are typically not
              necessary for UML and other applications.
            </para>

            <para>
              Corresponds to debootstrap's --exclude option
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>purge</term>
          <listitem>
            <para>
              A list of packages which should be removed after
              installation is complete.  Use this for packages which
              are required during installation, but may be removed
              afterward.  The same warning applies as with the exclude
              option.
            </para>

            <para>
              Packages are removed with dpkg --purge.
            </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>include</term>
          <listitem>
            <para>
              A list of packages which should be included in the
              initial set of packages to install.
            </para>

            <para>
              Corresponds to debootstrap's --include option
            </para>
          </listitem>
        </varlistentry>

      </variablelist>

    </refsect2>

    <refsect2>
      <title>Custom modules</title>

      <para>
        Custom modules can very easily be used by rootstrap, in
        addition to (or in place of) the supplied modules.  See FILES
        below for locations that are searched for modules.
      </para>

      <para>
        When a module is invoked, the filesystem being created is
        mounted on $TARGET.  /etc and /tmp are tmpfs filesystems
        internal to the UML system, while the root filesystem is a
        hostfs mount of the system where rootstrap is running.  This
        means that most software on the host system should be
        available and work as expected.  The working directory where
        rootstrap is run is available as $WORKDIR.  The environment is
        generated from the configuration file as described above.
      </para>
    </refsect2>

  </refsect1>

  <refsect1>
    <title>FILES</title>

    <variablelist>
      <varlistentry>
        <term>/etc/rootstrap/rootstrap.conf</term>
        <listitem>
          <para>
            System-wide default configuration
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>rootstrap.conf</term>
        <listitem>
          <para>
            Local overrides
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>/usr/lib/rootstrap/modules</term>
        <listitem>
          <para>
            Modules distributed with rootstrap
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>/etc/rootstrap/modules</term>
        <listitem>
          <para>
            System-wide overrides and additional modules
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>modules</term>
        <listitem>
          <para>
            Local overrides and additional modules
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
            
  </refsect1>

  <refsect1>
    <title>AUTHOR</title>

    <para>Rootstrap was written by &dhusername; &dhemail;</para>

  </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->