* NOTE: This document is a supplement to the README file included with the 
autoinstall package.  It is intended to give new users a quick introduction 
to the most commonly used features of autoinstall.  Only the most ocmmon 
options are covered here.  Please see the second half of the README file 
for the complete list of configuration directives.


Automating a Debian Linux Installation Using autoinstall
--------------------------------------------------------

 * Introduction

In this document I will demonstrate how to use the autoinstall tool to create a 
single 1.44Mb floppy which you can use to deploy a fleet of similarly 
configured Debian systems quickly and easily. This utility can be a valuable
tool in the your bag of tricks when you need to get multiple machines up and
running in a short amount of time.  At my employer we are using this system
to reliably deploy several dozen new systems every month.



 * Getting Started 

To begin, you will need a Debian system already installed and operational on 
which to create your installation media and create the necessary configuration 
files which will control your installs.  If you are reading this, you 
undoubtedly already have such a system.  You'll also need network access to 
a Debian mirror, either on the Internet or on your local network.  All the 
packages used to build your installed ("target") system will be pulled via 
the network.  You will also need access to a web server so that you can
make some local files available.  You do not need a dedicated web server, you 
can use any location which will be accessible via http from your target machine.

To get started, make sure you have the 'autoinstall-arch' package installed. If 
not, you can install it along with any dependencies you may need with: 
	apt-get install autoinstall-arch debootstrap
This will install both the autoinstall files necessary to create our bootable 
floppy and the debootstrap tool which we will use later on.  At the time of 
this writing, there are arch-specific packages available for i386, hppa and 
ia64.


Now that you have the autoinstall utility available you are ready to begin 
making the decisions necessary to create your installation media.  Some of 
those decisions will be: whether to use DHCP or static IPs, which Debian 
mirror to use for downloading installation packages, which packages to
install on top of the base system, etc.  These configuration choice are stored 
within a series of text files.  The typical configuration will consist of 
files named global.cfg, sources.lst, netmod.lst, partinfo.cfg, network.cfg 
and select.cfg stored within a sub-directory called 'conf'.  

The first file we will look at is called 'global.cfg'.  It contains, as you 
might expect, some high-level parameters such as networking information, 
encrypted root password, etc.  An example listing is given here:

------------
baseurl http://www.example.com/minimal.tar.gz
modulesurl http://www.example.com/scsi_mods.tar
rootpwd $1$JN7WPUOV$/VOCAlzbRYBU4AMzaL61N1
nosafe
network dhcp
------------

This file contains a crypted root password entry, and two URL's which we will 
discuss shortly. The encrypted password string can either be a known password 
copied from your /etc/shadow or passwd file, or a new password generated with 
a command such as 'mkpasswd'.  This password will become the root password of 
your installed box. The keyword "nosafe" indicates that I want the install 
process to destroy any partitions which may exist on my disk.  Without this 
option, the install will abort with an error message if it finds existing data 
on your drives. You can also choose to let the install consume only the 
available unpartitioned space on the drive.  To do that, replace "nosafe" with 
the keyword "freespace".  If you do choose a "nosafe" installation, the 
autoinstall process will provide a large warning and the chance to abort 
before it overwrites any existing partitions on your installation target.

You can specify the network interface to use with the 'interface' directive.
If you don't specify an interface, eth0 will be used.

In this example, I have chosen to use dhcp addressing for all installations by 
specifying the keywords "network dhcp".  You may prefer to allocate static 
IP addresses.  If so, simply substitute the keywords "network netdb" here and 
then populate a file called 'network.cfg' with MAC-address-to-IP pairings.
An example of such a file is shown here:

-----------------
gateway 192.168.0.1
network 192.168.0.255
netmask 255.255.255.0
nameserver 192.168.0.1
domain example.com

0001031a866e 192.168.0.2 coyote
0001032b9561 192.168.0.3 albus
0001032b9630 192.168.0.4 zugzug
0001031a867d 192.168.0.5 hunt
0001032b6bf0 192.168.0.6 magruder
default      192.168.1.55 unassigned
-----------------

This file should be created using pairs of blocks.  One pair is shown above, 
but your file may contain as many as necessary.  Each pair starts with a 
global block which contains information common to all machines in the 
immediately following block of MAC address/IP/hostname triplets.  You must
specify a hostname for each IP address.  In this case I have specified 5 
specific machines, and a default which will apply to any MAC address 
which does not match. 



Next, lets take a look at sources.lst.  This one should be self-explanatory to 
anyone familiar with the Debian system:

-----------------
deb http://http.us.debian.org/debian woody main contrib non-free
-----------------

sources.lst is identical to the sources.list file (though notice the different 
spelling of the filename necessary for the autoinstall version) found on 
every Debian system. Insert your favorite Debian mirror information here.  
If you have a local mirror on your network you can use that too.  You may 
specify several mirrors or sources if necessary.



Now we are ready to configure the networking drivers.  Your installation system 
must be able to contact the network to download packages, so we will specify 
which drivers to include on the disk.  netmod.lst contains a listing of network 
modules which your machines will need.  If all your machines are identical, 
this file may only contain one line.  If you are deploying various machines of
different pedigrees, you will need to include the network drivers necessary to 
support each machine.  Try to keep the list to a minimum as space on your 
floppy disk will be limited.  This list should be made up of one module name 
per line, without preceding path information and without a trailing ".o".  
All modules that you list here will automatically be copied to your floppy disk 
when it is created.  I have found that there is room to include about half 
a dozen network modules on the floppy.  If you are operating in an extremely 
mixed environment you may find it useful to create more than one
floppy, each containing drivers for a subset of your ethernet cards.  For my 
situation, I based my floppy on the RedHat install disk which includes drivers 
for 3c59x, 8139too, 8390, eepro100, ne2k-pci, pcnet32, and tulip based cards.  
This covers the vast majority of our hardware, and for those oddball machines 
which do not fit the mold I create a second disk with a different configuration.

Next the partinfo.cfg file.  This contains information on how to setup your 
disk partitions.  The autoinstall tool currently only supports installations 
to the first detectable drive in your system.  This means /dev/hda if you 
are on an IDE system, or /dev/sda if you run SCSI.  Future versions may 
allow you to alter this behaviour.  The format of the file is simple.  It
is made up of lines with four fields, of the form:
   <fs_type> <size> <mountpoint> <partition_type>

An example file might look like:
-----------------
ext2 30M /boot primary
ext2 100% / primary
swap 256M swap primary
-----------------

Note that the arch-specific modules may define additional fs_type's specific to 
their architecture if necessary.  (hppa does this with the 'palo' type, for 
example).  See the documentation included with your architecture specific files 
for details.


The final configuration file you will need to create is called select.cfg. This 
is where you will specify which packages you want to install on your target 
systems.  Each machine will get the minimal install necessary to function, 
and will then add any packages you specify here.  The syntax is simply
the package name followed by the keyword "install".  Thanks to Debian's 
excellent package management system, any dependencies for the packages you 
specify will be picked up automatically, so if you create the list by hand, 
you don't have to kill yourself verifying that you list out every dependency.  
An easy way to generate a typical select.cfg file is to run 
	'dpkg --get-selections' 
on your host Debian system.  Of course, if you wish, you can also choose 
packages by hand. A small example is provided:


-----------------
base-files		install
kde			install
xserver-xfree86		install
xserver-common		install
kernel-image-2.4.18	install
-----------------

If you do not specify at least one kernel-image, the autoinstall system will 
install version 2.2.20 by default.

One optional file that you may choose to create at this point is called 
'postinst'.  This file is a script which will be executed on the newly 
installed system after all other steps have been completed.  You may 
write it in any language supported by your installed system -- perl or 
python (make sure to install those packages if you wish to use them 
during postinst), any of the standard shells, or any other scripting 
language you desire.  You can use this script to perform any site-specific
customizations or other modifications that you wish.  You are limited only by 
the available space on your floppy disk.


 * Creating the installation media 

Now that you have your configuration files ready, we will need to create three 
things - a kernel which will be used to boot the installation media, a tar-ball 
containing scsi modules (if necessary), and a tarball containing a minimal 
system installation which can be used to bootstrap the target machine.

Due to the size constraints of a standard 1.44M floppy disk, the 2.4 series 
Linux kernels are generally too big to be useful for our purposes.  
I recommend using version 2.2.20 instead.  Download the source via 
'apt-get install kernel-source-2.2.20' on your host system.  You will then
want to go through the kernel configuration process to create a kernel which is 
as compact as possible and includes only the drivers you absolutely need 
for installation.  You are (most likely) not going to need infra-red, 
sound, etc support in your boot kernel so do not include them.  I
generally build in IDE support, along with the minimum set of drivers needed to 
boot a system.  A sample configuration file for the 2.2.20 kernel is 
included with this package.

Remember that your installed system will get one of the standard kernel images 
which will include all the niceties.  Once your configuration is complete, 
you must build a .deb package containing your kernel and modules since 
this is the format that the autoinstall tools expect.  The easiest way 
to do that is via the 'make-kpkg' command.  In your top-level kernel 
source directory issue 'make-kpkg kernel_image'.  In a few minutes (or hours 
depending on the speed of your machine) you will have a .deb file in 
the parent directory containing the kernel image and modules.  Remember
that file location as you will need it again in a few minutes.

Now lets get back to those URL's we saw a moment ago in global.cfg.  The first 
is called the baseurl and is used to specify the location of a tarball 
which will be used to seed your installed machines.  Since Debian no 
longer distributes an official "minimal" tarball, you will have to create 
your own.  Fortunately this is very easy using the "debootstrap" tool.  
Simply create a temporary directory (ie $HOME/minimal), and then issue 
the command "debootstrap woody $HOME/minimal [MIRROR]". Specifying a
mirror location is optional, but it can speed up the process if you choose one 
which is local.  See the debootstrap man page for various other options 
which are available.  Move into this directory, create a gzipped tar file 
of the contents with 'tar zcvf minimal.tar.gz .' and place it at the URL you 
specified in global.cfg.

Next you will need to decide if you need to use SCSI or any other kernel 
modules on your systems.  To save space on the floppy, the installation 
brings up the network interface as early as possible, and then uses that 
to download a tarball containing modules (typically SCSI) from the 
modulesurl that you specify in global.cfg. An example of the structure 
of this tarball is shown below:

-------------
./lib
./lib/modules
./lib/modules/2.2.20
./lib/modules/2.2.20/scsi
./lib/modules/2.2.20/scsi/st.o
./lib/modules/2.2.20/scsi/sg.o
./lib/modules/2.2.20/scsi/qlogicfc.o
...
./lib/modules/2.2.20/modules.dep
./etc
./etc/scsimod.lst
--------------

The easiest way to create this tarball is to setup a temporary directory and 
copy the modules, and appropriate directory structure, from your system modules 
directory.  Be sure to include the modules.dep file from your top-level 
kernel modules directory.  You will also need to include a file called 
scsimod.lst -- similar to netmod.lst this file contains a list of all the 
scsi modules in the tarball, one per line, without any preceding path or 
a trailing ".o".  As shown above, make sure this file unpacks into ./etc 
and the modules unpack into ./lib.  If you do not need any additional modules 
(perhaps all your systems use IDE drives) then simply create a tarball which 
contains any empty file. 


You are now ready to create the actual boot floppy. Make sure all the 
configuration files described above are in a sub-directory named 'conf' 
of your current working directory and then issue the
command: make-autoinst-initrd /path/to/kernel-package.deb


Specify the absolute path to the kernel .deb file you just created.  You will 
need to be root to run this command as it needs to temporarily mount a 
loop-back filesystem.  Now that your initial ramdisk has been created you 
are ready to write it along with the kernel to a floppy.  Make sure there is a
floppy disk in your drive and type 'make-autoinst-disk'.  After a few moments 
you should have a bootable floppy disk which will launch a complete Debian 
installation without the need for intervention.

 * Starting the install 

To get started with your new installation disk there is not much more to it 
than simply inserting the disk and powering on the system.  Make sure your 
BIOS is setup to boot from the floppy drive.  You will be presented with a 
simple menu which will prompt you to type 'install' to begin the process.
Once you have done that, you should not need to interact with the system again 
until the installation is complete.  Sit back and watch your hard work pay off.

Occasionally however there will be problems.  The most common source of 
problems in any floppy-based endeavor is bad media. If you run into problems, 
first make sure you are using fresh disks which are known to be good.  
Another common problem is that you configured the install to use a static 
IP but did not provide a matching MAC address in the configuration file.  Be 
aware that your machine will take the default values if the MAC address 
does not match one that is listed.  It is often simpler to use DHCP as that 
avoids the need to track down every MAC address before you create your floppy.


 * After the install 

Now that your installation is finished, you should have a complete and 
functioning Debian system.  If you would like to add or remove packages 
you can do so using the standard apt-get and dpkg tools.  During the 
install, configuration options were forced to their defaults so that 
the install could be hands-free.  If you want to reconfigure any 
packages you may do so using the standard 'dpkg-reconfigure <packagename>' 
command.


* Conclusion

This utility, while somewhat complex to setup, can be an extremely powerful 
tool to rapidly deploy multiple identical machines in a lab, classroom or 
corporate environment.  For the casual admin that only has to install Debian 
once in a while, other tools such as PGI or the standard Debian installer
may fit the bill better, but for the admin that cranks out several boxes a week 
or more this utility can be a huge time saver.



