Automatic Installer System
==========================

This is the autoinstall system designed by Progeny Linux Systems for
Progeny Debian 1.x and updated to work with Debian 3.0 (woody).  The
goal for this system is to make it possible to configure a special
install floppy, which will set up other systems automatically.

Quick usage guide:

1.  Write a set of configuration files, and put them in a "conf"
subdirectory.

2.  Run "make-autoinst-initrd <kernel-package>", where
<kernel-package> is a Debian kernel package, either included with
Debian or built using Debian's "kernel-package" kernel build system.
This creates the initial RAM disk (initrd) that is used to bootstrap
the system.

3.  Stick a floppy disk in the floppy drive, and run
"make-autoinst-disk".  This creates the autoinstall floppy.

An "update-autoinst-disk" utility also exists, which will update an
already-created floppy with new initrd, kernel, and configuration
information.

The make-autoinst-initrd, make-autoinst-disk, and update-autoinst-disk
tools all have manual pages which you may consult for more
information.

To install a new system with the autoinstall floppy, just put it in
the floppy drive and turn on the system.  The system will need to be
set to boot from floppy, and it will need an installation source
(which can be the network or a CD).

Configuration
-------------

All of the autoinstaller's behavior is controlled via configuration
files, which are written from the "conf" subdirectory to the floppy at
configuration time.  The files are:

  global.cfg         The global configuration file.
  debconf.cfg        Saved debconf configuration information.
  netmod.lst         List of network modules to load.
  scsimod.lst        List of SCSI modules to load.
  scsip1.lst         List of SCSI modules to preload.
  network.cfg        Networking configuration database.
  partinfo.cfg       Partitioning information.
  select.cfg         Package selections list.
  postinst           Post-installation script.
  sources.lst        Apt's sources.list file (package download).

Some of these files have fairly simple contents.  The module list
files for the network and SCSI simply consist of module names, one per
line, which are to be included on the autoinstall floppy (without the
path name or ".o").  (The "scsip1.lst" and "scsimod.lst" files both
contain SCSI modules that can be loaded; the difference is when they
load.  See below, under "Hard Disk Autoinstallation", for details on
the difference between the two files.)  The select.cfg file consists
of the output of "dpkg --get-selections" on an existing system.  The
sources.lst file is a standard apt sources.list file, designed for use
in the autoinstall environment; if you intend to autoinstall from the
network, most likely the standard working sources.list on a standard
Debian system will work.  The postinst file is a program that is run
after the installation is complete; it can be written in any language
supported by the fully installed system. It is run chrooted into the
installed system.

NOTE: It's sources.lst, NOT sources.list. If you do not rename
      sources.list to sources.lst, your autoinstall floppy WILL
      NOT WORK.

The other files are a bit more complex.  The global.cfg file contains
the master installation information.  These are stored as key-value
pairs, one per line, with a space separating the key from the value,
or as single-word options.  Some of these are:

 - baseurl: This value contains the URL for the minimal system
 tarball. This can be either a cdrom: fake "URL" or an actual
 http URL. cdrom: "URLs" should be of the form "cdrom:PATH",
 where PATH is the path to the minimal tarball relative to the
 root of the CD-ROM.  See below for more information on obtaining a
 minimal system tarball.

 - rootpwd: This value contains the hash of the password that the
 "root" user is set to.

 - nosafe: This option causes the autoinstall floppy to be "unsafe".
By default, the autoinstall floppy will abort if the system that's
been installed has a filesystem on it, to protect against accidental
destruction of a system.  By setting this option, you can tell the
autoinstaller to continue no matter what.

 - network: This option allows the autoinstaller to configure the
network.  This can be set to "dhcp" (use DHCP), "netdb" (configure
using the network database file, described below), or "none" (no
network).

 - cdinst: This option tells the system to install via a CD, instead
of over the network.

 - nfscd: This option contains the path to an NFS-mounted CD image
that can be used to install the system.

 - proxy: This option causes all utilities that download via HTTP
(including apt) to use a Web proxy.  The value for this option should
be the same as the value for the "http_proxy" environment variable: a
URL for the proxy server, such as http://proxy.example.com:3128/.

 - noxconf: If this is set, the system will not attempt to configure
the X Window System even if X server packages are set to be
installed.

The debconf.cfg file contains a dump of the debconf database, as
produced by the "autoinst-read-debconf" utility provided in the
autoinstall package.  This contains debconf values, one per line, in
the form "templatename questionname answer".

The network.cfg file contains the network database.

Minimal Tarball
---------------

The autoinstaller currently relies on a "minimal system tarball".
This could be an official minimal system tarball such as that used by
Debian 2.2 (potato) or Progeny Debian 1.0 (newton).  

Debian 3.0 (woody) does not have a minimal tarball.  Instead, it
contains the "debootstrap" program, which installs a minimal set of
packages directly onto the target system.  You can use debootstrap to
create a minimal system tarball and place it on a Web server.  After
installing debootstrap ("apt-get install debootstrap" should do the
trick) and following debootstrap's instructions for creating a minimal
system in a directory, do this:

  cd <dir> && tar cf - . | gzip -9 > ../base.tgz

This will create a tarball suitable for use with the autoinstaller.

A future version of the autoinstaller will likely be able to use
debootstrap itself, removing the need for a minimal tarball.

Kernel Handling
---------------

The current stock Debian kernels are too big to fit on an autoinstall
floppy.  This means that the autoinstaller currently requires building
a custom kernel.

We recommend building a kernel package using the kernel-package suite
(see its documentation for details).  In particular, we recommend
that the kernel package installed by the autoinstaller be the same as
the kernel package used to build the autoinstall floppy.  This will
mean making sure that the custom kernel-image package be available in
an apt repository, and it should have a version number higher than any
stock kernels (perhaps with an epoch in the version number).

If this is not possible, then the autoinstall can be done with a
different kernel on the floppy than is installed on the disk.
However, in this case, you should reboot the system after installation
is finished before you use it.  This ensures that the kernel can get
to any modules it needs.

Package Selection and Debconf
-----------------------------

In order to achieve a fully-automated install, it is necessary to
avoid specifying any packages that do not use debconf but which
require user interactivity during the installation process.

Hard Disk Autoinstallation
--------------------------

As an option, it's possible to create an autoinstallation system that
can be booted by other means, such as from an already-formatted hard
disk.  This can be useful if, for example, you want to reinstall or
migrate systems over the network.

To do this, perform steps 1 and 2 above.  Then, on the destination
system, create a "/conf" directory and copy your configuration files
(from the "conf" subdirectory) into that directory.  Finally, copy
your kernel and the initrd.gz that was created in step 2 to the
destination system, and configure its boot loader to load the new
kernel with the new initrd.

When configuring the boot loader, you will need to pass two kernel
command line arguments:

 - aidrv: the drive that contains the "/conf"
   directory you created.  This is the location from which the
   configuration files will be loaded.

 - aifs: the file system type for the drive where
   the configuration will be loaded.  Set this to "ext2" or "msdos" as
   appropriate.

On a SCSI system, you may need to load a SCSI driver before you can
mount the configuration drive.  In that case, before running steps 1
and 2, put the necessary drivers in the "scsip1.lst" file.  Drivers in
this file can be loaded before any of the configuration files are
available; drivers in scsimod.lst are only available once the
configuration files are loaded.

Root Access
-----------

Note that root access may be needed for some of the steps
involved in the creation of an autoinstall floppy. Reading the
debconf database requires root access, for example. Depending on
how your devices are configured, mortal users on your system
probably do not have write access to the floppy device, so you
will need root access for that as well.

# vim:ai:et:tw=70: