trunk/doc/fai-guide.sgml

<!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [
  <!-- include version information so we don't have to hard code it
       within the document -->
  <!-- common, language independent entities -->
  <!entity % commondata SYSTEM "common.ent" > %commondata;
  <!-- CVS revision of this document -->
  <!entity cvs-rev "$Id$">

<!entity faikernelver "1.5">
<!entity faiver "2.4.1">
<!entity faiverdate "2 apr 2003">

<!entity version "2.2">
<!entity date    "4 june 2003">
]>

<debiandoc>
<book>
      <title>FAI Guide (Fully Automatic Installation)

      <author>Thomas Lange <email>lange@informatik.uni-koeln.de</email>
      <version>Version &version;, &date for FAI version &faiver;

<abstract>
This manual describes the fully automatic installation package for
&dgl;. This includes the installation of the package, the planning and
creating of the configuration and how to deal with errors.
 
<copyright>
<copyrightsummary>
Copyright &copy; 2000-2003 Thomas Lange
</copyrightsummary>
        <p>
This manual is free software; you may redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2, or (at your option) any
later version.
        <p>
This is distributed in the hope that it will be useful, but
<em>without any warranty</em>; without even the implied warranty of
merchantability or fitness for a particular purpose. See the GNU
General Public License for more details.
        <p>
A copy of the GNU General Public License is available as &file-GPL; in
the &dgl distribution or on the World Wide Web at <url id="&url-gpl;"
        name="the GNU website">. You can also obtain it by 
writing to the &fsf-addr;.

<toc detail="sect2">

<chapt id="intro">Introduction<p>
<sect id="availability">Availability<p>
The homepage of FAI is
<httpsite>http://www.informatik.uni-koeln.de</httpsite><httppath>/fai</httppath>.
There you will find any information about FAI, for example the mailing
list archive. The FAI package is also available as a Debian package from
&faidownload;. It's an official Debian package and is available from
all Debian mirrors. Send any bug or comment to
<email>fai@informatik.uni-koeln.de</email>. You can also use the
Debian bug tracking system (BTS)
<httpsite>http://www.debian.org</httpsite><httppath>/Bugs</httppath>
for reporting errors.
<p>
You can access the CVS repository containing the newest developer
version of FAI from a Bourne shell using the
following commands. The login password is empty, so only press return. 
<example>
> CVSROOT=:pserver:anonymous@cvs.debian.org:/cvs/debian-boot
> cvs login
> cvs co -P fai-kernels
> cvs co -P fai
</example>

You can also use the web interface for the CVS repository at:
<httpsite>http://cvs.debian.org/</httpsite><httppath>fai/</httppath>
(and <package>fai-kernels</package>).
<p>
Now read this manual, then enjoy the fully automatic installation and
your saved time.


<sect id="motivation">Motivation<p> Have you ever performed identical
installations of an operating system several times?  Would you like to
be able to install a Linux cluster with dozens of nodes single
handedly?

<p>
Repeating the same task time and again is boring -- and will surely
lead to mistakes. Also a whole lot of time could be saved if the
installation were done automatically. An installation process with
manual interaction does not scale. But clusters have the habit of
growing over the years. Think long-term rather than plan only just a
few months into the future.

<p>
In 1999, I had to organize an installation of a Linux cluster with one
server and 16 clients. Since I had much experience doing automatic
installation of Solaris operating system on SUN SPARC hardware, the
idea to build an automatic installation for Debian was born. Solaris
has an automatic installation feature called JumpStart<footnote> <p>
Solaris 8 Advanced Installation Guide at
<httpsite>docs.sun.com</httpsite></p> </footnote>. In conjunction
with the auto-install scripts from Casper Dik<footnote><p><url
id="ftp://ftp.wins.uva.nl:/pub/solaris/auto-install/"></p> </footnote>,
I could save a lot of time not only for every new SUN computer, but
also for re-installation of existing workstations. For example, I had
to build a temporary LAN with four SUN workstations for a conference,
which lasted only a few days. I took these workstations out of our normal
research network and set up a new installation for the conference.
When it was over, I simply integrated the workstation back into the
research network, rebooted just once, and after half an hour,
everything was up and running as before. The configuration of all
workstations was exactly the same as before the conference, because
everything was performed by the same installation process. I also use
the automatic installation for reinstalling a workstation after a
damaged hard disk had been replaced. It took two weeks until I
received the new hard disk but only a few minutes after the new disk
was installed, the workstation was running as before. And this is why
I chose to adapt this technique to a PC cluster running Linux.


<sect id="overview">Overview and concepts<p>
<p>
FAI is a non-interactive system to install a &dgl operating system
unattended on
a single computer or a whole cluster. You can take one or more virgin
PC's, turn on the power and after a few minutes Linux is installed,
configured and running on the whole cluster, without any interaction
necessary. Thus, it's a scalable method for installing and updating a
cluster unattended with little effort involved. FAI uses the &dgl;
distribution and a collection of shell and perl scripts for the
installation process. Changes to the configuration files of the
operating system can be made by cfengine, shell, perl and expect scripts.

<p>
FAI's target group are system administrators how have to install
Debian onto one or even hundreds of computers. Because it's a general
purpose installation tool, it can be used for installing a Beowulf
cluster, a rendering farm or a linux laboratory or a classroom. Also
large-scale linux networks with different hardware or different installation
requirements are easy to establish using FAI. But don't forget to plan
your installation. <ref id="plan"> has some useful hints for this topic.
<p>
First, some terms used in this manual are described.

<taglist>
          <tag> install server : <item> <p>The host where the package
          FAI is installed. It provides several services and data for
          all install clients. In the examples of this manual this
          host is called <tt>kueppers</tt>.

          <tag>install client : <item> A host which will be installed using
          FAI and a configuration from the install server. Also called
          client for short. In this manual, the example hosts are
          called <tt>bigfoot, ant01, ant02, nucleus, atom01, atom02,...</tt></p> </item>
          <tag> configuration : <item> The details of how the installation
          of the clients should be performed. This includes information about:
<list>
                <item> <p>Hard disk layout</p> </item>
                <item> <p>Local filesystems, their mount points and
                mount options</p> </item>
                <item> <p>Software packages</p>       </item>
                <item> <p>Keyboard layout, time zone, NIS,
                XFree86 configuration, remote filesystems, user accounts,
                printers ...</p>  </item>
</list>
          <tag> nfsroot : <item> A (chroot) filesystem located on the install
          server. It's the complete filesystem for the install
          clients during the installation process. All clients share the
          same nfsroot, which they mount read only.</item>
</taglist>

<sect id="work">How does FAI work?<p> 

The install client which will be installed using FAI, is
booted from floppy disk or via network card. It gets an IP address and
boots a linux kernel which mounts its root filesystem via NFS from the install
server. After the operating system is running, the FAI startup script
performs the automatic installation which doesn't need any
interaction. First, the hard disks will be partitioned, filesystems are
created and then software packages are installed. After that, the new
installed operating system is configured to your local needs using
some scripts. Finally the new operating system will be booted from the local
disk.
<p>
The details, of how to install the computer (the configuration), are
stored in the configuration space on the install server. Configuration
files are shared among groups of computers if they are similar using the
class concept. So you need not to create a configuration for every new
host. Hence, FAI is a scalable method to install a big cluster with a
great number of nodes.

<p>
FAI can also be used as an network rescue system. You can boot your
computer, but it will not perform an installation. Instead it will run a
fully functional &dgl without using the local hard disks. Then you can
do a remote login and backup or restore a disk partition, check a filesystem,
inspect the hardware or do any other task.

<sect id="features">Features<p> 
<list>
            <item> <p>A fully automated installation can be performed</p> </item>
            <item> <p>Very quick unattended installation</p> </item>
            <item> <p>Hosts can boot from floppy or from network card </p> </item>
            <item> <p>Easy creation of the common boot floppy which
            uses grub or lilo</p> </item>
            <item> <p>BOOTP and DHCP protocol and PXE boot method are supported</p> </item>
            <item> <p>No initial ramdisk is needed, 8MB RAM suffice</p> </item>
            <item> <p>Runs even on a 386 CPU </p> </item>
            <item> <p>The installation kernel can use modules</p> </item>
            <item> <p>Remote login via ssh during installation process
            possible</p> </item>
            <item> <p>Two additional virtual terminals available
            during installation</p> </item>
            <item> <p>All similar configuration are shared among
            all install clients</p> </item>
            <item> <p>Log files for all installations are saved on to the installation server</p> </item>
            <item> <p>Shell, perl, expect and cfengine scripts are
            supported for the configuration setup</p> </item>
            <item> <p>Access to a Debian mirror via NFS, FTP or HTTP</p> </item>
            <item> <p>Keyboard layout selectable</p> </item>
            <item> <p>Can be used as a rescue system</p> </item>
            <item> <p>Tested on SUN SPARC hardware running Linux or Solaris</p> </item>
            <item> <p>Flexible system through easy class concept </p> </item>
            <item> <p>Predefined Beowulf classes included </p> </item>
            <item> <p>Diskless client support</p> </item>
            <item> <p>Easily add your own functions via hooks</p> </item>
            <item> <p>Easily change the default behavior via hooks</p> </item>
            <item> <p>Lilo and grub support</p> </item>
            <item> <p>ReiserFS and ext3 support</p> </item>
            <item> <p>Automatic hardware detection</p> </item>
            <item> <p>Booting and installing from CD-ROM is in progress</p> </item>
</list>

<chapt id="inst">Installing FAI
<sect id="requirements">Requirements<p> 

The following items are required for an installation via FAI.

<taglist>
          <tag>A computer: </tag><item> The computer must have a
          network interface card. Unless a diskless installation
          should be performed a local hard disk is also needed. No floppy disk,
          CD-ROM, keyboard or graphic card is needed.</item>

          <tag>BOOTP or DHCP server: </tag><item> <p> 
The clients need one of these daemons to obtain boot information. But
          you can also put all this information onto the boot floppy.</item>

          <tag>TFTP server:<item> The TFTP daemon is used for
          transferring the kernel to the clients. It's only needed when
          booting from network card with a boot PROM.</item>
          <tag>Client root:<item> It is a mountable directory which contains the whole
          filesystem for the install clients during installation. It will
          be created during the setup of the FAI package and is also
          called <strong>nfsroot</strong>.</item>
          <tag>Debian mirror:<item> Access to a Debian
          mirror is needed. A local mirror of all Debian packages or
          an <manref name="apt-proxy" section="8"> is recommended if
          you install several computers.</item>
          <tag>Install kernel: <item> A kernel image that supports the
          network card and mounts its root filesystem via NFS. The
          Debian package <package>fai-kernels</package> provides a
          default kernel for fai.</item>
          <tag>Configuration space:<item> This directory tree which
          contains the configuration data is a mounted via NFS by
          default. But you can also get this directory from a revision
          control system like CVS.
        </taglist>
<p>
The TFTP daemon and a NFS server will be enabled automatically when
installing the FAI package. All clients must have a network card
which is recognized by the install kernel.
<p>


<sect id="debian-mirror">How to create a local Debian mirror<p> 

The script <prgn>mkdebmirror</prgn> <footnote> You can find the script in
 <p><file>/usr/share/fai/utils/</file>.</p> </footnote> can be used
 for creating your own local Debian mirror. This script uses the
 script <prgn>debmirror</prgn><footnote> Available as a Debian package
 or at the FAI homepage.</footnote> and <manref name="rsync"
 section="1">. A partial Debian mirror only for i386 architecture for
 Debian 3.0 (aka woody) without the source packages needs about
 &mirrorsize of disk space. Accessing the mirror via NFS will be the
 normal and fastest way in most cases.

To use HTTP access to the local Debian mirror, install the webserver
software and create a symlink to the local directory where you mirror
is located:

<example># apt-get install apache
# ln -s /files/scratch/debmirror /var/www/debmirror
</example>

Don't forget to adjust the variable <var>FAI_SOURCES_LIST</var> in &fc
to access the Debian mirror.

<sect id=faisetup> Setting up FAI<p>

Before installing FAI, you have to install the package <package>fai-kernels</package>,
which contains the install kernels for FAI. You can install both
packages using

<example>
kueppers[~]# apt-get install fai fai-kernels
Reading Package Lists... Done
Building Dependency Tree... Done
The following NEW packages will be installed:
  fai fai-kernels 
0 packages upgraded, 2 newly installed, 0 to remove and 1  not upgraded.
Need to get 0B/12.7MB of archives. After unpacking 13.9MB will be used.
Selecting previously deselected package fai.
(Reading database ... 48317 files and directories currently installed.)
Unpacking fai (from .../main/f/fai/fai_2.4.1_all.deb) ...
Selecting previously deselected package fai-kernels.
Unpacking fai-kernels (from .../fai-kernels_1.5_i386.deb) ...
Setting up fai (2.4.1) ...
To set up FAI, edit /etc/fai/fai.conf and call fai-setup.

Setting up fai-kernels (1.5) ...
</example>


You can also get the newest version of <package>fai</package> and
<package>fai-kernels</package> from the download page of fai and
install the packages using the
<prgn>dpkg</prgn> command.
<p>The configuration for the FAI package (not the configuration data
for the install clients) are defined in &fc;. Since FAI doesn't use
<prgn>debconf</prgn> yet, edit this file before calling
<prgn>fai-setup</prgn>. These are important variables in &fc;:

<taglist>
            <tag><var>FAI_DEBOOTSTRAP</var></tag>
            <item>
          <p>For building the nfsroot there's the command called
          <manref name="debootstrap" section="8">. It needs
          the location of a Debian mirror and the name of the distribution
          (woody,sarge,sid) for which the basic Debian
          system should be built.
            </p> </item>

            <tag><var>FAI_SOURCES_LIST</var></tag> <item> <p>This
            multi line string is the content of
            <file>sources.list</file> (used by <manref name="apt-get"
            section="8">); it defines the location and access
            method for the Debian mirror. If this variable is undefined,
            the file <file>/etc/fai/sources.list</file> or
            <file>/etc/apt/sources.list</file> will 
            be used. For more information on the
            file format see <manref name="sources.list" section="5">.
            </p> </item>

            <tag><var>FAI_DEBMIRROR</var></tag>
            <item>
              <p> If you have NFS access to your local Debian mirror,
              specify the remote filesystem. It will be mounted to
              <var>$MNTPOINT</var>, which must also be defined. It's
              not needed if you use access via FTP or HTTP.</p>
              </item>

            <tag><var>KERNELPACKAGE</var></tag>
            <item>
          <p> You must specify the software package - build with <manref
              name="make-kpkg" section="8"> - which includes
              the default kernel for booting the install clients. The
              Debian package <package>fai-kernels</package> contains the
              default install kernels which supports both the BOOTP
              and DHCP protocol.</p></item>
        <tag> <var>NFSROOT_PACKAGES</var></tag>
            <item>
          <p> This variable contains a list of additional software packages which
          will be added to the nfsroot.</p></item>
            <tag><var>FAI_LOCATION</var></tag>
            <item><p>This is the host name and the remote directory of
          the configuration space, which will be mounted via NFS.</p></item>

            <tag><var>FAI_BOOT</var></tag>
            <item><p>
            which of DHCP and/or BOOTP should the server create setups for
            (when make-fai-nfsroot is run). Default are to create setups for 
            both.
            </p></item>
          </taglist>
<p>

The variables <var>FAI_SOURCES_LIST</var> and <var>FAI_DEBMIRROR</var>
are used by the install server and also by the clients. If your
install server has multiple network card and different host names for
each card (as for a Beowulf server), use the install
server name which is known by the install clients.<p>

FAI uses <manref name="apt-get" section="8"> to create the nfsroot
filesystem in <file>/usr/lib/fai/nfsroot</file>. It needs about
&nfsrootsize of free disk space. Before setting up FAI, you should get
the program <prgn>imggen</prgn>,<footnote>Available at the download
page <httpsite>http://www.ltsp.org</httpsite> or from the FAI download
page &faidownload;.</footnote> if you like to boot from a 3Com network
card. This executable converts netboot images created by <manref
name="mknbi-linux" section="8">, so they can be booted by network
cards from 3Com. Put that executable in your path
(e.g. <file>/usr/local/bin</file>). After editing &fc; call
<prgn>fai-setup</prgn>.

<example>
kueppers[~]# fai-setup
Account $LOGUSER=fai already exists.
Make sure that all install clients can
log into this account without a password.
Using interface eth0 to determine local hostname.
Adding kueppers to known_hosts.
/home/fai/.ssh/known_hosts created.
/home/fai/.ssh/authorized_keys created.
User account fai set up.
Creating FAI nfsroot can take a long time and will
need more than  &nfsrootsize disk space in /usr/lib/fai/nfsroot.
/usr/lib/fai/nfsroot already exists. Removing /usr/lib/fai/nfsroot
Creating nfsroot for woody using debootstrap
dpkg: base-passwd: dependency problems, but configuring anyway as you request:
 base-passwd depends on libc6 (>= 2.2.4-4); however:
  Package libc6 is not installed.
dpkg: base-files: dependency problems, but configuring anyway as you request:
.
.
.
Automatically converting /etc/network/interfaces succeeded.
Old interfaces file saved as interfaces.dpkg-old.
Creating base.tgz
Upgrading /usr/lib/fai/nfsroot
Adding additional packages to /usr/lib/fai/nfsroot:
portmap file rdate cfengine bootpc wget rsh-client less dump
ext2resize strace hdparm parted dnsutils grub ntpdate 
dosfstools sysutils dialog libdetect0 discover mdetect read-edid kudzu hwtools
Detecting hardware: 3c59x ide-scsi usb-uhci usb-uhci
modprobe: Can't open dependencies file /lib/modules/2.4.20/modules.dep (No such file or directory)
Skipping 3c59x; assuming it is compiled into the kernel.
modprobe: Can't open dependencies file /lib/modules/2.4.20/modules.dep (No such file or directory)
Skipping usb-uhci; assuming it is compiled into the kernel.
Creating SSH2 RSA key
Creating SSH2 DSA key
Restarting OpenBSD Secure Shell server: sshd.
DHCP environment prepared. Now enable dhcpd and the special tftp daemon
Kernel image file name  = /usr/lib/fai/nfsroot/boot/vmlinuz-&kver;
Output file name        = /boot/fai/installimage
Kernel command line     = "auto rw root=/dev/nfs nfsroot=kernel nfsaddrs=kernel ip=both"

Image Creator for MBA ROMs v1.01, Date: Nov 26, 2001
Design and Coding by Nick Kroupetski &lt;NickKroupetski@hotmail.com&gt;
Usage: imggen [OPTION] inputfile outputfile
  -a,   Add 3Com MBA/BootWare support
  -r,   Remove 3Com MBA/BootWare support from image file
  -i,   Show information on an image
  -h,   Help screen

In filename: /boot/fai/installimage
Out filename: /boot/fai/installimage_3com
Adding MBA support...
MBA support has been succesfully added 
BOOTP environment prepared.
make-fai-nfsroot finished.
Stopping NFS kernel daemon: mountd nfsd.
Unexporting directories for NFS kernel daemon...done.
Exporting directories for NFS kernel daemon...done.
Starting NFS kernel daemon: nfsd mountd.
You have no FAI configuration. Copy FAI template files with:
cp -a /usr/share/fai/templates/* /usr/local/share/fai
Then change the configuration files to meet your local needs.
FAI setup finished.
</example>

<p>
The warning messages from dpkg about dependencies problems can be ignored.
If you have problems running fai-setup, they stem usually from 
make-fai-nfsroot. You may restart it by calling 'make-fai-nfsroot -r' 
(recover). Adding '-v' gives you a more verbose output which may help you 
pinpoint the error. If you want to create a log file you may use
<example>
sudo /usr/sbin/make-fai-nfsroot -r -v | tee make-fai-nfsroot.log
</example>
It may helpful to enter manually the chroot environment 
<example>
sudo chroot /usr/lib/fai/nfsroot
</example>
The setup routine adds some lines to <file>/etc/exports</file> to export
the nfsroot and the configuration space to all hosts that belong to
the netgroup <em>faiclients</em>. If you already export a parent directory
of these directories, you may comment out these lines, since the kernel nfs
server has problems exporting a directory and one of its
subdirectories with different options.

All install clients must belong to this netgroup,
in order to mount these directories successfully. Netgroups are
defined in <file>/etc/netgroup</file> or in the corresponding NIS
map. An example for the netgroup file can be found in
<file>/usr/share/doc/fai/examples/etc/netgroup</file>. For more
information, read the manual pages <manref name="netgroup"
section="5"> and the NIS HOWTO. After changing the netgroups, the NFS
server has to reload its configuration. Use one of the following
commands, depending on which NFS server you are using:

<example>
kueppers# /etc/init.d/nfs-kernel-server reload
kueppers# /etc/init.d/nfs-user-server reload
</example>

<p>
The setup also creates the account <tt>fai</tt> (defined by $LOGUSER)
if not already available. The log
files of all install clients are saved to the home directory of this
account. If you boot from network card, you should change the primary
group of this account, so this account has write permissions to
<file>/boot/fai</file> in order to change the symbolic links to the kernel
image which is booted by a client. See also variable
<var>TFTPLINK</var> in <file>class/DEFAULT.var</file>.


<p>
After that, FAI is installed successfully on your server, but has no
configuration for the install clients. Start with the templates from
<tt> /usr/share/fai/templates</tt> using the copy command above
and read <ref id="config">. Before you can set up a DHCP or BOOTP
daemon, you should collect some network information of all your
install clients. This is described in section <ref id="bootfloppy">.
<p>
When you make changes to &fc; or want to install a new kernel to
nfsroot, the nfsroot has to be rebuilt by calling <prgn>make-fai-nfsroot</prgn>.

<sect1 id=troublefaisetup> Troubleshooting the setup<p>

The setup of FAI adds the FAI account, exports file systems and calls
<prgn>make-fai-nfsroot</prgn>. If you call <tt>make-fai-nfsroot -v</tt> you
will see more messages. When using a local Debian mirror, it's
important that the install server can mount this directory via
NFS. If this mount fails, check <file>/etc/exports</file> and <file>/etc/netgroup</file>.
An example can be found in <file>/usr/share/doc/fai/examples/etc/netgroup</file>.


<chapt id="booting">Preparing booting <p> 

Before booting for the first time, you have to choose which medium you
use for booting. You can use the boot floppy or configure the computer
to boot via network card using a boot PROM, which is much smarter. 

<sect id="nicboot">Booting from 3Com network card with boot PROM
<p>
If you have a 3Com network card that is equipped with a boot ROM by
Lanworks Technologies or already includes the DynamicAccess Managed PC
Boot Agent (MBA) software<footnote> <p><httpsite>http://support.3com.com/</httpsite>
<httppath>infodeli/tools/nic/mba.htm</httppath></p></footnote>, you
can enter the MBA setup by typing <tt>Ctrl+Alt+B</tt> during boot. The
setup will look like this:

<example>
Managed PC Boot Agent (MBA) v4.00
(C) Copyright 1999 Lanworks Technologies Co. a subsidiary of 3Com Corporation
All rights reserved.
===============================================================================
                            Configuration

Boot Method:                PXE

Default Boot:               Network
Local Boot:                 Enabled
Config Message:             Enabled
Message Timeout:            3 Seconds
Boot Failure Prompt:        Wait for key
===============================================================================
  Use cursor keys to edit: Up/Down change field, Left/Right change value
  ESC to quit, F9 restore previous settings, F10 to save
</example>

Set the boot method to <tt>PXE</tt> or set it to <tt>TCP/IP</tt> and
the protocol to <tt>BOOTP</tt>. The advantage of the BOOTP protocol
it, that the BOOTP daemon automatically reloads its configuration when
it has changed, but using the PXE environment is more comfortable.

When using BOOTP, you have to make a
symbolic link from the hostname of your client to the appropriate
kernel image in <file>/boot/fai</file>. In the following example the
host is called <tt>bigfoot</tt>. The file
<file>installimage_3com</file> is created by <prgn>imggen</prgn> and
suitable for booting 3Com network cards<footnote> <p>If you have
problems booting with a 3Com network card and get the error "BOOTP
record too large" after the kernel is transfered to the computer, try
the imggen-1.00 program to convert the netboot image to a
installimage_3com image. I had this problem using netboot 0.8.1-4 and
Image Creator for MBA ROMs v1.01, Date: Nov 26, 2001 but only on an
Athlon computer.
</p></footnote>
You can also use the utility
<prgn>tlink</prgn> (<file>/usr/share/fai/utils/tlink</file>) to create
this link.

<example> 
kueppers# cd /boot/fai
kueppers# ln -s installimage_3com bigfoot
</example>

<sect id="pxeboot">Booting from network card with a PXE conforming boot ROM<p>
Some network cards (e.g. Intel EtherExpress PRO 100) have a fixed
boot configuration, so they can only use the PXE boot protocol. This requires a PXE
Linux boot loader and a special version of the <tt>TFTP</tt> daemon,
which is available in the Debian package <package>tftpd-hpa</package>.

First install following additional needed packages:

<example>
# apt-get install dhcp3-server syslinux tftp-hpa
</example>

Then set up the DHCP daemon. A sample configuration files can be
found in <file>/usr/share/doc/fai/examples/etc/dhcpd.conf</file>.
Then enable the special tftp daemon
using this line in file <file>/etc/inetd.conf</file>: 
<example>
tftp dgram udp wait root /usr/sbin/in.tftpd in.tftpd -r blksize -s /boot/fai
</example>

See <file>/usr/share/doc/syslinux/pxelinux.doc.gz</file> for more
information about how to boot such an environment. There are also some
mails in the FAI mailing list archive concerning this topic. The PXE
environment uses the original kernel image (not the netboot image made
by mknbi-linux)
which is copied to <file>/boot/fai/vmlinuz-install</file>. A default
configuration for pxelinux is written to
<file>/boot/fai/pxelinux.cfg/default</file>.

<sect id="bootfloppy">Creating a boot floppy
<p>

If your network card can't boot itself, you have two options. The
first is to create a small boot floppy that uses etherboot, so you can
use DHCP and TFTP to get the install kernel that was created with
<manref name="mknbi-linux" section="8">.  A lot of ethernet cards
support booting via ethernet if a special boot eprom is inserted or
booted from floppy <httpsite>http://rom-o-matic.net/</httpsite>. In
depth documentation about booting via ethernet may be found at
<httpsite>http://etherboot.sourceforge.net</httpsite>.

The seconde is to via floppy disk that is created with the command <manref
name="make-fai-bootfloppy" section="8">. Since there's no client specific
information on this floppy, it's suitable for all your install
clients. You can also specify additional kernel parameters for this
boot floppy or set other variables, if desired. Do not enable BOOTP
support when you have a DHCP server running in your network and vice
versa. This could lead to missing information. There's also a manual
page for <manref name="make-fai-bootfloppy" section="8">. If you have
no BOOTP or DHCP server, supply the network configuration as kernel
parameters. The format is:
<example>ip=&lt;client-ip&gt;:&lt;server-ip&gt;:&lt;gw-ip&gt;:&lt;netmask&gt;:&lt;hostname&gt;:&lt;device&gt;:&lt;autoconf&gt;
</example>For additional information see
<file>/usr/src/linux/Documentation/nfsroot.txt</file> in the kernel
sources.

<sect id="cdboot">Booting from a CD-ROM<p>

There some ongoing work to create a bootable CD-ROM which can boot and
install an install client. Currently this script is not included in
the FAI package but a beta version is available. It will contain the
nfsroot, the configuration space and a subset of the Debian mirror,
which contains all packages that you need for an unattended
installation. Look at the mailing list archive of FAI for more
information. A first version is available at
<httpsite>http://members.iinet.net.au</httpsite><httppath>/~niall/fai/</httppath>.

<sect id="mac">Collecting Ethernet addresses<p>

Now it's time to boot your install clients for the first time. They
will fail to boot completely, because no BOOTP or DHCP daemon is running yet or
recognizes the hosts. But you can use this first boot attempt to
easily collect all Ethernet addresses of the network cards.
<p>

You have to collect all Ethernet (MAC) addresses of the install clients
and assign a hostname and IP address to each client. To collect 
 all MAC addresses, now boot all your install clients. While the
install clients are booting, they send broadcast packets to the LAN. You
can log the MAC addresses of these hosts by running the following
command simultaneously on the server:

<example># tcpdump -qte broadcast and port bootpc >/tmp/mac.lis</example>

<p>
After the hosts has been sent some broadcast packets (they will fail
to boot because <prgn>bootpd</prgn> isn't running or does not recognize the MAC
address yet) abort <prgn>tcpdump</prgn> by typing <tt>ctrl-c</tt>. You get a list
of all unique MAC addresses with these commands:

<example># perl -ane 'print "\U$F[0]\n"' /tmp/mac.lis|sort|uniq</example>

After that, you only have to assign these MAC addresses to hostnames
and IP addresses (<file>/etc/ethers</file> and <file>/etc/hosts</file>
or corresponding NIS maps). With this information you can configure
your <prgn>BOOTP</prgn> or <prgn>DHCP</prgn> daemon (see the section
<ref id="bootptab">). I recommend to write the MAC addresses (last
three bytes will suffice if you have network cards from the same
vendor) and the hostname in the front of each chassis.

<sect id=bootptab>Configuration of the BOOTP daemon<p>

An example configuration for the BOOTP daemon can be found in
<file>/usr/share/doc/fai/examples/etc/bootptab</file>.

<example>
# /etc/bootptab example for FAI
# replace FAISERVER with the name of your install server

.faiglobal:\
 :ms=1024:\
 :hd=/boot/fai:\
 :hn:bs=auto:\
 :rp=/usr/lib/fai/nfsroot:

.failocal:\
 :tc=.faiglobal:\
 :sa=FAISERVER:\
 :ts=FAISERVER:\
 :sm=255.255.255.0:\
 :gw=134.95.9.254:\
 :dn=informatik.uni-koeln.de:\
 :ds=134.95.9.136,134.95.100.209,134.95.100.208,134.95.140.208:\
 :ys=rubens:yd=informatik4711.YP:\
 :nt=time.rrz.uni-koeln.de,time2.rrz.uni-koeln.de:

# now one entry for each install client
bigfoot:ha=0x00105A240012:bf=bigfoot:tc=.failocal:T172="verbose sshd createvt debug":
ant01:ha=0x00105A000000:bf=ant01:tc=.failocal:T172="sshd":
</example>

Insert one line for each install client at the end of this file as
done for the hosts <em>bigfoot</em> and <em>ant01</em>. Replace the string
<tt>FAISERVER</tt> with the name of your install server. If the
install server has multiple network cards and host names, use the host
name of the network card to which the install clients are
connected. Then adjust the other network tags (<tt>sm, gw, dn,
ds</tt>) to your local needs.

<taglist>
 <tag>sm:</tag> <item>  <p>Subnet mask</p> </item>
 <tag>gw:</tag> <item>  <p>Default gateway / router</p> </item>
 <tag>dn:</tag> <item>  <p>Domain name</p> </item>
 <tag>ds:</tag> <item>  <p>List of DNS server. The
 <file>/etc/resolv.conf</file> file will be created using this list
 of DNS servers and the domain name.
 <tag>T172:</tag> <item>  <p>List of <var>FAI_FLAGS</var>;
 e.g. verbose, debug, reboot, createvt, sshd, syslogd</p> </item>
 <tag>T173:</tag> <item>  <p>Reserved for future use</p> </item>
 </taglist>

The tags for NIS and time servers (<tt>yp, yd, nt</tt>) are
optional. Tags with prefix <tt>T</tt> (starting from T170) are generic
tags which are used to transfer some FAI specific data to the
clients<footnote>T170=FAI_LOCATION, T171=FAI_ACTION. You should define
theses variables in a class/*.var script. But for backward compatibility,
you can define theses variables also from a BOOTP or DHCP server.</footnote>

The list of <var>FAI_FLAGS</var> can be space or comma
separated. <var>FAI_FLAGS</var> in <file>bootptab</file> must be
separated by whitespace. If you define <var>FAI_FLAGS</var> as
an additional kernel parameter, the flags must be separated with a
comma.
If you do not have full control over the BOOTP or DHCP daemon (because
this service is managed by a central service group) you can also
define the variable <var>FAI_ACTION</var> in
a <file>/fai/class/*.var</file> scripts. Look at
<file>LAST.var</file> for an example. The variable <var>T170</var>
can also be defined by a daemon. It's better to use a script for that.

When you have created your <file>bootptab</file> file, you have to
enable the BOOTP daemon once. It's installed but Debian does not enable it
by default. Edit <file>/etc/inetd.conf</file> and remove the comment
(the hash) in the line containing <tt>#bootps</tt>. Then tell
<prgn>inetd</prgn> to reload its configuration.

<example># /etc/init.d/inetd reload</example>

The BOOTP daemon automatically reloads the configuration file if any changes are
made to it. The daemon for DHCP must always be manually restarted
after changes to the configuration file are made.

<p>
Now it's time to boot all install clients again!
FAI can perform several actions when the client is booting. This action
is defined in the variable <var>FAI_ACTION</var>.
Be very careful if you set <var>FAI_ACTION </var> to
<em>install</em>. This can destroy all your data on the install
client, indeed most time it should do this ;-). It's recommended to change this only
on a per-client base in the BOOTP configuration. Do not change it in
the section <tt>.failocal</tt> in <file>/etc/bootptab</file>, which
is a definition for all clients.

<sect1 id=troublebootp>Troubleshooting BOOTP daemon<p>
The BOOTP daemon can also be started in debug mode if it is not
enabled in <file>inetd.conf</file>:
<example># bootpd -d7</example>

<sect id="bootdhcp">Configuration of the DHCP daemon <p>
An example for <manref name="dhcp.conf" section="5"> is available in
<file>/usr/share/doc/fai/examples/etc</file>, which is tested with
version 2.x of the DHCP daemon. Version 3 needs a slightly
different configuration file. Start using this example
and look at all options used therein. If you make any changes
to this configuration, you must restart the daemon.
<example># /etc/init.d/dhcp3-server restart</example>
Therefore it's recommended to only supply data into this configuration
file, which doesn't change frequently. You should define the variables
<var>FAI_ACTION</var> in a script in the configuration space.

<sect id="bootmesg">Boot messages <p>

These are the messages when booting from floppy disk.
<example>
GRUB loading stage2..............
&lt now the grub menu is displayed &gt;
BOOTING 'FAI-BOTH'
kernel (fd0)/vmlinuz-2.4.20 root=/dev/nfs ip=both
  [Linux-bzImage, setup=0x1400, size=0xd8450]

Uncompressing Linux... OK, booting the Kernel.
Linux version &kver; (root@kueppers) (gcc version 2.95.4 20011002
.
.
.
</example>
After this, the rest of the boot message will be equal to those when booting from
network card. When booting from network card you will see:
<example>
BOOTP.
TFTP....
Linux Net Boot Image Loader Version 0.8.1 (netboot)
.
Uncompressing Linux... OK, booting the Kernel.
Linux version &kver; (root@kueppers) (gcc version 2.95.4 20011002
.
.
.

Sending BOOTP requests . OK
IP-Config: Complete:


Sending BOOTP requests ..... OK
IP-Config: Got BOOTP answer from 134.95.9.150, my address is 134.95.9.200
IP-Config: Complete:
   device=eth0, addr=134.95.9.200, mask=255.255.255.0, gw=134.95.9.254,
   host=bigfoot, domain=informatik.uni-koeln.de, nis-domain=informatik4711.YP,
   bootserver=134.95.9.150, rootserver=134.95.9.150, rootpath=/usr/lib/fai/nfsroot
Partition check:
.
.
   ------------------------------------------------------
     FAI &faiver;, &faiverdate;
     Fully Automatic Installation for Debian GNU/Linux

     Copyright (c) 1999-2003, Thomas Lange
             lange@informatik.uni-koeln.de
   ------------------------------------------------------

Calling task_confdir
Kernel parameters:auto rw root=/dev/nfs ip=both
Defining variable: root=/dev/nfs
Defining variable: ip=both
Sending BOOTP request using device eth0
FAI_FLAGS: verbose=1
FAI_FLAGS: createvt=1
.
Calling task_setup
.
.
Calling task_defclass
/usr/bin/fai-class: Defining classes.
.
.
Calling task_action
FAI_ACTION: install
Performing FAI installation. All data may be overwritten!
.
.
Press &lt;RETURN&gt; to reboot or ctrl-c to execute a shell
</example>

When the copyright message is shown, the install client has mounted
the nfsroot<footnote> <p><file>/usr/lib/fai/nfsroot</file> from the
install server</p> </footnote> to the clients' root directory
<file>/</file>. This is the whole filesystem for the client at this
moment. 

After <tt>task_confdir</tt> is executed, the configuration space is
mounted or received from an CVS repository.

Before the installation is started (FAI_ACTION=install) the computer
beeps three times. So, be watchful when you hear three beeps
but you do not want to perform an installation!

<sect id=booterror>Troubleshooting boot messages<p>

This is the error message you will see, when your network card is
working, but the install server does not export the configuration
space directory to the install clients.
<example>
Root-NFS: Server returned error -13 while mounting /usr/lib/fai/nfsroot
VFS: Unable to mount root fs via NFS, trying floppy.
VFS: Cannot open root device "nfs" or 02:00
Kernel panic: VFS Unable to mount root fs on 02:00
</example>
Use the following command to see which directories are exported
from the install server (named kueppers):
<example>showmount -e kueppers</example>

<p>

The following error message indicates that your install client doesn't
get an answer from a BOOTP server. Check your cables or start the
<manref name="bootpd" section="8"> daemon with the debug flag enabled.
<example>
Sending BOOTP requests ........ timed out!
IP-Config: Retrying forever (NFS root)...
</example>

If you get the following error message, the install kernel has
no driver compiled in for your network card. 
<example>
IP-Config: No network devices available
Partition check:
 hda: hda1 hda2 < hda5 hda6 hda7 hda8 >
Root-NFS: No NFS server available, giving up.
VFS: Unable to mount root fs via NFS, trying floppy.
VFS: Insert root floppy and press ENTER
</example>
Then you have to compile the driver for your network card into a new
kernel. This driver must not be a kernel module. To compile the new
kernel, start using the default kernel configuration of FAI.
<example>
kueppers# cd /usr/src/kernel-source-&kver;
kueppers# cp /usr/lib/fai/nfsroot/boot/config-&kver; .config
kueppers# make menuconfig
</example>
Call <prgn>make menuconfig</prgn> and add the driver in menu <tt>Network
device support/Ethernet</tt> which supports your network card. Then
create a Debian package using <manref name="make-kpkg" section="8">:
<example>
kueppers# make-kpkg clean
kueppers# make-kpkg --revision fai2 kernel-image
</example>

This command creates the file 
<file>/usr/src/kernel-image-&kver;_fai2_i386.deb</file>. Adjust 
the variable <var>KERNELPACKAGE</var> in  &fc; and rebuild the nfsroot.
<example>
kueppers# make-fai-nfsroot
</example> 
After that, you have to create a new boot floppy if you need it. Now your network
card should be recognized and the install kernel should mount
the nfsroot successfully. More information how to compile an
install kernel can be found in the <file>README</file> of the package <tt>fai-kernels</tt>.

<sect id="sysinfo">Collecting other system information 
<p>

Now the clients have booted with <var>FAI_ACTION</var> set to <em>sysinfo</em>. Type
<tt>ctrl-c</tt> to get a shell or use <tt>Alt-F2</tt> or
<tt>Alt-F3</tt> and you will get another console terminal, if you have added <tt>createvt</tt>
to <var>FAI_FLAGS</var>.

Remote login is available via the secure shell if <tt>sshd</tt> is
added to <var>FAI_FLAGS</var>. The encrypted password is set with
variable <var>FAI_ROOTPW</var> in &fc; and defaults to "fai". This
is only the root password during the installation process, not for the
new installed system. You can also log in without a password when
using <var> SSH_IDENTITY</var>. To log in from your server to the
install client (named ant01 in this example) use:

<example>> ssh root@ant01
Warning: Permanently added 'ant01,134.95.9.200' to the list of known hosts.
root@ant01's password: 
</example>


You now have a running Linux system on the install client
without using the local hard disk. Use this as a rescue system if
your local disk is damaged or the computer can't boot properly from
hard disk. You will get a shell and you can execute various commands
(dmesg, lsmod, df, lspci, ...). Look at the log file in
<file>/tmp/fai</file>. There you can find much information about the boot
process.

All log files from <file>/tmp/fai</file> are also written to the
<var>$LOGSERVER</var> (if not defined: the install server) into the
directory <tt>~fai/ant01/sysinfo/</tt><footnote>More general:
<tt>~$LOGUSER/$HOSTNAME/$FAI_ACTION/</tt>. Two additional symbolic
links are created. The symlink <file>last</file> points to the log
directory of the last fai action performed. The symlinks
<file>last-install</file> and <file>last-sysinfo</file> point to the
directory with of the last corresponding action.

Examples of the log
files can be found on the FAI homepage.
</footnote>

<p>
A very nice feature is that FAI mounts all filesystems it finds on
the local disks read only. It also tells you on which partition a file
<file>/etc/fstab</file> exists. When only one file system table is found, the
partitions are mounted according to this information. Here's an
example:
<example>
ant01:~# df

Filesystem 1k-blocks     Used Available Use% Mounted on
rootfs       2064192  1071184    888152  55% /
/dev/root    2064192  1071184    888152  55% /
shm            63548       76     63472   1% /tmp
kueppers:/usr/local/share/fai
             2064192   994480   964856   51% /fai
/dev/hda1      54447     9859    41777   19% /tmp/target
/dev/hda10   1153576       20  1141992    0% /tmp/target/files/install
/dev/hda9     711540       20   711520    0% /tmp/target/home
/dev/hda8     303336       13   300191    0% /tmp/target/tmp
/dev/hda7    1517948    98252  1342588    7% /tmp/target/usr
/dev/hda6     202225     8834   182949    5% /tmp/target/var
</example>

<strong>This method can be used as a rescue environment!</strong> In the
future it will be possible to make backups or restore data to existing
filesystems. If you need a filesystem with read-write access use the
<prgn>rwmount</prgn> command:

<example>ant01:~# rwmount /tmp/target/home</example> 

<sect id=checkbootp>Checking parameters from BOOTP and DHCP servers<p>

If the install client boots with action <em>sysinfo</em>, you can also
check if all information from the BOOTP or DHCP daemons are received
correctly. The received information is written to
<file>/tmp/fai/boot.log</file>. An example of the result of a BOOTP
request can be found in <ref id="s1">.


<sect id=reboot>Rebooting the computer<p>
At any time you can reboot the computer using the command
<prgn>faireboot</prgn>, also if logged in from remote. If the
installation hasn't finished, use <tt>faireboot -s</tt>, so the log
files are also copied to the install server.

<chapt id=instprocess>Overview of the installation sequence<p>

The following tasks are performed during an installation after the linux kernel
has booted on the install clients.

<enumlist>
            <item> <p>Set up FAI </p> </item>
            <item> <p>Load kernel modules</p> </item>
            <item> <p>Define classes</p> </item>
            <item> <p>Define variables</p> </item>
            <item> <p>Partition local disks</p> </item>
            <item> <p>Create and mount local filesystems</p> </item>
            <item> <p>Install software packages</p> </item>
            <item> <p>Call site specific configuration scripts</p> </item>
            <item> <p>Save log files</p> </item>
            <item> <p>Reboot the new installed system</p> </item>
          </enumlist>

You can also define additional programs or scripts
which will be run on particular
occasions. They are called <tt>hooks</tt>. Hooks can add additional
functions to the installation process or replace the default subtasks
of FAI. So it's very easy to
customize the whole installation process. Hooks are explained in
detail in <ref id="hooks">.

<p>
The installation time is determined by the amount of software but also
by the speed of the processor and hard disk. Here are some sample
times. All install clients have an 100Mbit network card installed.
Using a 10 Mbit LAN does not decrease the installation time
considerably, so the network will not be the bottleneck when
installing several clients simultaneously.

<example>
Athlon XP1600+    , 896MB,SCSI disk,   1 GB software  6 min
AMD-K7, 500MHz    , 320MB, IDE disk, 780 MB software 12 min
PentiumPro 200MHz , 128MB, IDE disk, 800 MB software 28 min
Pentium III 850MHz, 256MB, IDE disk, 820 MB software 10 min
Pentium III 850MHz, 256MB, IDE disk, 180 MB software  3 min
</example>


<sect id=isetup>Set up FAI<p>

After the install client has booted, only the script
<file>/sbin/rcS_fai</file><footnote><p>Since the root filesystem on
the clients is mounted via NFS, <prgn>rcS_fai</prgn> is located in
<file>/usr/lib/fai/nfsroot/sbin</file> on the install server.</p>
</footnote> is executed. This is the main script which controls the
sequence of tasks for FAI. No other scripts in
<file>/etc/init.d/</file> are executed.
<p>
A ramdisk is created and mounted to <file>/tmp</file>, which is the
only writable directory until local filesystems are
mounted. Additional parameters are received from the BOOTP or DHCP
daemon and the configuration space if
mounted via NFS from the install server to <file>/fai</file>. The
setup is finished after additional virtual terminals are created and
the secure shell daemon for remote access is started on demand.

<sect id=iclass>Defining classes, variables and loading kernel modules<p>

Now the script <manref name="fai-class" section="1"> is used to define
classes. Therefore several scripts in <file>/fai/class/</file> are executed to define classes. All scripts matching <tt>[0-9]*</tt>
are executed in alphabetical order. Scripts ending in <tt>.source</tt>
are sourced, so they can define new classes by adding these classes to
the variable <var>newclasses</var> (see <file>06hwdetect.source</file> for an
example). Every word that these scripts print to the standard output
are interpreted as class names. These classes are defined for the
install client. You can also say this client belongs to these
classes. A class is defined or undefined and has no value. Only
defined classes are of interest for an install client. The description
of all classes can be found in
<file>/usr/share/doc/fai/classes_description.txt</file>. It is
advisable to document the job a new class performs. Then, this
documentation is the base for composing the whole configuration from classes.

<p>
The scripts <prgn>11modules.source</prgn> loads kernel modules
on demand. So you can use classes when loading modules and also define
more classes after the kernel has loaded modules and recognized new hardware.
But normally you only have to deal with the file <file>DEFAULT.mod</file>.
The complete description of all these scripts can be found in <ref id="cscripts">.

<p>
The script <file>30menu.source</file> pops up a little menu and asks
the user which kind of installation should be performed (e.g. CAD
workstation, notebook, scientific workstation, work group server, Gnome
desktop...). Keep in mind that this won't lead to a fully automatic
installation ;-)
<p>
After defining the classes, every file matching <tt>*.var</tt> with a
prefix which matches a defined class is executed to define variables.
There, you should define the variable <var>FAI_ACTION</var> and
others. Currently, <var>FAI_ACTION</var> is defined in
<file>LAST.var</file> for all install clients.


<sect id=ipartition>Partitioning local disks, creating filesystems<p>

For disk partitioning exactly one disk configuration file from
<file>/fai/disk_config</file> is selected using classes. It's the
description of how all the local disks will be partitioned, where
filesystems should be created (and their types like ext2, ext3,
reiserfs), and how they are mounted. It's also possible to preserve
the disk layout or to preserve the data on certain partitions. It's
done by the command <prgn>setup_harddisks</prgn>, which uses
<prgn>sfdisk</prgn> for partitioning. The format of the configuration
file is described in
<file>/usr/share/doc/fai/README.disk_config</file>.
<p>
During the installation process all local filesystems are mounted
relative to <file>/tmp/target</file>. For example
<file>/tmp/target/home</file> will become <file>/home</file> in the
new installed system.

<sect id=ipackages>Installing software packages<p>

When local filesystems are created, they are all empty (except for
preserved partitions). Now the Debian base system and all requested
software packages are installed on the new filesystems. First the
base archive is unpacked, then the command
<manref name="install_packages" section="8"> installs all packages using <manref
name="apt-get" section="8"> without any manual interaction needed. If
a packages requires an other package, <manref name="apt-get" section="8"> resolves
this dependency by installing the required package.
<p>

Classes are also used when selecting the configuration files in
<file>/fai/package_config/</file> for software installation. The
format of the configuration files is described in <ref
id="packageconfig">.

<sect id=icscripts>Site specific configuration<p>

After all requested software packages are installed, the system is
nearly ready to go. But not all default configurations of the software
packages will meet your site specific needs. So you can call arbitrary
scripts which adjust the system configuration. Therefore scripts which
match a class name in <file>/fai/scripts</file> will be executed. If
<file>/fai/scripts/</file><var>classname/</var> is a directory, all
scripts that match <tt>S[0-9]*</tt> in this directory are executed. So
it is possible to have several scripts of different types (shell,
cfengine, ...) to be executed for one class. FAI comes with some
templates for these scripts, but you can write your own Bourne, bash,
perl, cfengine or expect scripts.
<p>
These important scripts are described in detail in <ref
id="cscripts">.

<sect id=isavelog>Save log files<p> When all installation tasks are
finished, the log files are written to
<tt>/var/log/fai/$HOSTNAME/install/</tt> <footnote>
<p><file>/var/log/fai/localhost/install/</file> is a link to this
directory.</p> </footnote> on the new system and to the account on the
install server if <var>$LOGUSER</var> is defined in &fc;. It is also
possible to specify another host as destination of the log saving by
in a file in <file>/fai/class/</file>. Additionally, two symlinks will
be created to indicated the last directory written.

<sect id=ireboot>Reboot the new installed system<p>

At least the system is automatically rebooted if "reboot" was added to
<var>FAI_FLAGS</var>. This is only useful
if booting from network card or if you can change the boot device
using the command <manref name="bootsector" section="8">. Otherwise, you have to
remove the floppy disk and type return or call <prgn>faireboot</prgn>
from a remote login. You must change the boot device to boot the new
installed system otherwise the installation would be performed
again. Read <ref id="changeboot"> for how to change the boot device.

<chapt id=plan>How to plan your installation<p>
<em>Plan your installation, and FAI installs your plans.</em>
<p>
Before starting your installation, you should spend much time in
planning your installation. When you're happy with your installation
concept, FAI can do all the boring, repetitive tasks to turn your plans
into practice. FAI can't do good installations if your concept is
imperfect or lacks some important details. Start planning the
installations by answering the following
questions:

<taglist>
  <tag></tag> <item> <p>Will I create a Beowulf cluster, or do I
  have multiple workstations, each only used by a single user?</p> </item>
  <tag></tag> <item> <p>How does my LAN topology looks like?</p> </item>
  <tag></tag> <item> <p>Do I have uniform hardware?</p> </item>
  <tag></tag> <item> <p>Will the hardware stay uniform in the future?</p> </item>
  <tag></tag> <item> <p>Does the hardware need a special kernel?</p> </item>
  <tag></tag> <item> <p>How should the hosts be named?</p> </item>
  <tag></tag> <item> <p>How should the local hard disks be partitioned?</p> </item>
  <tag></tag> <item> <p>Which applications will be run by the users?</p> </item>
  <tag></tag> <item> <p>Do the users need a queueing system?</p> </item>
  <tag></tag> <item> <p>What software should be installed?</p> </item>
  <tag></tag> <item> <p>Which daemons should be started, and what
  should the configuration for these look like?</p> </item>
  <tag></tag> <item> <p>Which remote filesystems should be mounted?</p> </item>
  <tag></tag> <item> <p>How should backups be performed?</p> </item>
</taglist>

You also have to think about user accounts, printers, a mail system, cron jobs,
graphic cards, dual boot, NIS, NTP, timezone, keyboard layout,
exporting and mounting directories via NFS and many other things. So,
there's a lot to do before starting an installation. And remember
that knowledge is power, and it's up to you to use it. Installation
and administration is a process, not a product. FAI can't do things
you don't tell it to do.
<p>
But you need not to start from scratch. Look at all files and scripts
in the configuration space. There are a lot of things you can use for
your own installation.

A good paper with more aspects of building an infrastructure is
<url id="http://www.infrastructures.org/papers/bootstrap/">
"Bootstrapping an Infrastructure".

<chapt id=config>Installation details<p>

<sect id=c3>The configuration space<p>

The configuration is the collection of information about how exactly to
install a computer. The central configuration space for all install
clients is located on the install server in <file>/usr/local/share/fai</file>
and its subdirectories. This will be mounted by the install clients to
<file>/fai</file>. It's also possible to receive all the
configuration data from a <manref name="cvs" section="1"> repository.
The following subdirectories are present and include
several files:

<taglist>
          <tag><tt>class/</tt></tag> <item> <p>Scripts and files to
           define classes and variables and to load kernel modules.</p> </item>

          <tag><tt>disk_config/</tt></tag> <item> <p>Configuration
          files for disk partitioning and file system creation.</p> </item>

          <tag><tt>debconf/</tt></tag> <item> <p>This directory holds
          all <manref name="debconf" section="8"> data. Not yet used.</p> </item>

          <tag><tt>package_config/</tt></tag> <item> <p>File with
           lists of software
          packages to be installed or removed.</p> </item>

          <tag><tt>scripts/</tt></tag> <item> <p>Script for local site
           customization.</p> </item>

          <tag><tt>files/</tt></tag> <item> <p>Files used by
          customization scripts, e.g. user created kernel
           packages. Most files are located in a subtree structure
           which reflects the ordinary directory tree. For example, the
           templates for <file>nsswitch.conf</file> are located in
           <file>/fai/files/etc/nsswich.conf</file>. The directory
          <file>files/pacakges/</file> can contain you local Debian
          packages, which can be installed when adding them to the
          variables <var>addpackages</var>. See <ref
          id="classvariables"> for more information.</p> </item>

          <tag><tt>hooks/</tt></tag> <item> <p>Hooks are user defined
          programs or scripts, which are called during the
          installation process.</p> </item>
</taglist>

The main installation script <prgn>rcS_fai</prgn> uses all these
subdirectories in the order listed except for hooks. The FAI package contains templates
for all these configuration scripts and files in
<file>/usr/share/fai/templates</file>. Copy the configuration templates
to the configuration space and start an installation. These files need
not belong to the root account. You can change their ownership and
then edit the configuration with a normal user account.

<example>
# cp -a /usr/share/fai/templates/* /usr/local/share/fai
# chown -R fai /usr/local/share/fai
</example>

These files contain configuration for some example hosts. Examples
are: a cluster of workstations (<em>bigfoot, ant01, ant02,...</em>)
and a Beowulf cluster with a master node called <em>nucleus</em> and
computing nodes called <em>atom01, atom02,...</em> and our desktop
machines <em>kueppers, dom</em> and our notebooks <em>pittermaennche, paeffgen</em>.

<taglist>  
   <tag>bigfoot</tag>  <item> <p>This is a server with much software. It
   provides the home directory and <file>/usr</file> for its NFS clients. Also some
   daemons are installed and activated by default.</p> </item>
   <tag>ant01,...</tag>  <item> <p>These dataless clients mount
   <file>/usr</file> and <file>/home</file> from <em>bigfoot</em>. Most of
   the disk space is spent on a scratch partition, which is exported
   to a netgroup of hosts. The host <em>kueppers</em> has a similar
   configuration.</p> </item>

   <tag>nucleus</tag>  <item> <p>This Beowulf master node is a server with much software. It
   provides the home directory and <file>/usr/local</file> for its computing nodes. Also some
   daemons are installed and activated by default.</p> </item>
   <tag>atom01,...</tag>  <item> <p>These Beowulf clients mount
   <file>/usr/local</file> and <file>/home</file> from <em>nucleus</em>. Most of
   the disk space is spent on a scratch partition, which is exported
   to a netgroup of hosts. All scratch partitions are mounted on all
   Beowulf clients via the automounter.</p> </item>

   <tag>dom</tag> <item> <p>It's a desktop machine, which mounts
   <file>/home</file> from a server and synchronizes the
   <file>/usr/local</file> partition via <manref name="rsync"
   section="1"> from the server. If it belongs to the class
   <tt>USR_LOCAL_MOUNT</tt> it will mount this directory from the
   server.</p> </item>
</taglist>
Start looking at these examples and study them. Then change or add
things to these examples. But don't forget to plan your own
installation!

<sect id=tasks>The default tasks<p>

After the kernel has booted, it mounts the root file system via NFS
from the install server and <manref name="init" section="8"> starts the script
<file>/sbin/rcS_fai</file>. This script controls the
sequence of the installation. No other scripts in
<file>/etc/init.d/</file> are used.
<p>

The installation script uses many subroutines, which are defined in
<file>/usr/share/fai/subroutines</file>, and an operating system specific
file <footnote><file>/usr/share/fai/subroutines-linux</file> for Linux,
<file>/usr/share/fai/subroutines-sunos</file> for Solaris.</footnote>.
All important tasks of the
installation are called via the subroutine <tt>task</tt>
appended by the name of the task as an option (e.g. <tt>task
instsoft</tt>). The subroutine <tt>task</tt> calls hooks with prefix
<em>name</em> if available and then calls the default task (defined as
<tt>task_<em>name</em></tt> in <file>subroutines</file>). The default
task and its hooks can be skipped on demand by using the subroutine
<tt>skiptask()</tt>.<p>

Now follows the description of all default tasks.
<taglist>

      <tag>confdir</tag> <item><p>The kernel appended parameters define
variables, the syslog and kernel log daemon are started. The list of
network devices is stored in <var>$netdevices</var>. Then additional
parameters are fetched from a DHCP or BOOTP server and also
additional variables
are defined. The DNS resolver configuration file is created. The
configuration space is mounted from the install server to
<file>/fai</file> or it is checked out from the corresponding <manref
name="cvs" section="1"> repository. To use a cvs repository, you have
to set the variables <var>$FAI_CVSROOT, $FAI_CVSTAG,
$FAI_CVSMODULE</var>. For details look a the subroutine
<prgn>get_fai_cvs()</prgn>. After that, the file
<file>/fai/hooks/subroutines</file> is sourced if it exists. Using
this file, you can define your own subroutines or override the
definition of FAI's subroutines.

    <tag>setup</tag> <item><p>This task sets the system time, all
      <var>FAI_FLAGS</var> are defined and two additional virtual
      terminals are opened on demand. A secure shell daemon is started
      on demand for remote logins.

     <tag>defclass</tag> <item><p>Calls <manref name="fai-class"
      section="1"> t odefine classes using scripts and
      files in <file>/fai/class</file> and classes from
      <file>/tmp/fai/additional-classes</file>.</p> </item>

     <tag>defvar</tag> <item><p>Sources all files
      <file>/fai/class/*.var</file> for every defined class. If a hook
      has written some variable definitions to the file
      <file>/tmp/fai/additional.var</file>, this file is also
      sourced.</p></item>

      <tag>action</tag> <item><p>Depending on the value of
      <var>$FAI_ACTION</var> this subroutine decides which action FAI
      should perform. The default available actions are:
      <tt>sysinfo</tt> and <tt>install</tt>. If <var>$FAI_ACTION</var>
      has another value, a user defined action is called if a file
      <file>/fai/hooks/$FAI_ACTION</file> exists. So you
      can easily define your own actions.<p>


      <tag>sysinfo</tag> <item><p>Called when no installation is
      performed but the action is <tt>sysinfo</tt>. It shows information
      about the detected hardware and mounts the local hard disks read
      only to <file>/tmp/target/<var>partitionname</var></file> or with regard to a
      <file>fstab</file> file found inside a partition. Log files are
      stored to the install server.</p> </item> 

     <tag>install</tag> <item><p>This task controls the installation
     sequence. You will here three beeps before the installation
     starts. The major work is to call other tasks and to save the
     output to <file>/tmp/fai/rcS.log</file>. If you have any problems
     during installation, look at all files in
     <file>/tmp/fai/</file>. You can find examples of the log files
     for some hosts in the download directory of the FAI homepage.</p>
     </item>

     <tag>partition</tag> <item><p>Calls <prgn>setup_harddisk</prgn>
      to partition the hard disks. The task writes variable
      definitions for the root and boot partition and device (<var>$ROOT_PARTITION,
      $BOOT_PARTITION, $BOOT_DEVICE</var>) to
      <file>/tmp/fai/disk_var.sh</file> and creates a <file>fstab</file> file.</p></item>

      <tag>mountdisks</tag> <item><p>Mounts the created partitions
      according to the created <file>/tmp/fai/fstab</file> file relative to
      <var>$FAI_ROOT</var>.</p> </item>

      <tag>extrbase</tag> <item><p>Extracts the base tar file
      <file>base.tgz</file>, which consists of all required
      packages. This is a snapshot of a basic Debian system created
      by <manref name="debootstrap" section="8"></p> </item>

      <tag>mirror</tag> <item><p>If a local Debian mirror is accessed via NFS
      (when <var>$FAI_DEBMIRROR</var> is defined), this directory will
      be mounted to <var>$MNTPOINT</var>.</p> </item>

      <tag>updatebase</tag> <item><p>Prepares the extracted Debian
      base system for further installation and updates the list of
      available packages. Updates the packages to the newest
      version. It also fakes some commands (called diversions) inside
      the new installed system using <manref name="dpkg-divert"
      section="8">.</p>
      </item>

      <tag>instsoft</tag> <item><p>Installs the desired software
      packages using class files in
      <file>/fai/packages_config</file>.</p> </item>

        <tag>configure</tag> <item><p>Calls scripts in
      <file>/fai/scripts/</file> and its subdirectories for every
      defined class.</p> </item>

      <tag>finish</tag> <item><p>Unmounts all filesystems in the
      new installed system and removes diversions of files
      using the command <prgn>fai-divert</prgn>.</p></item>

      <tag>faiend</tag> <item><p>Wait for background jobs to finish
      (e.g. emacs compiling lisp files) and automatically reboots the install
      clients or waits for manual input before reboot.</p> </item>

      <tag>chboot</tag> <item><p>Changes the symbolic link on the install
      server which indicates which kernel image to load on the next
      boot from network card via TFTP.</p> </item>

      <tag>savelog</tag> <item><p>Saves log files to local disk and to
      the account <var>$LOGUSER</var> on <var>$LOGSERVER</var> (defaults to
      the install server). Currenty the file <file>error.log</file>
      will not be copied to the log server.</p> </item>

 </taglist>


<sect id=s1>The setup routines of the install clients<p>

After the subroutine <prgn>fai_init</prgn> has done some basic
initialization (create ramdisk, read <file>fai.conf</file> and all
subroutines definitions, set path, print copyright notice), the setup
continues by calling the task <tt>confdir</tt> and the task
<tt>setup</tt>. The command <prgn>get-boot-info</prgn> is called to
get all information from the BOOTP or DHCP server. This command writes
the file <file>/tmp/fai/boot.log</file>, which then is sourced to
define the corresponding global variables. This is an example for this
log file when using a BOOTP server.
<example>
# cat /tmp/fai/boot.log

netdevices_all=" eth0"
netdevices_up=""
netdevices="eth0"
# --- network device eth0 ---
SERVER='134.95.9.150'
IPADDR='134.95.9.200'
BOOTFILE='/boot/fai'
NETMASK='255.255.255.0'
NETWORK='134.95.9.0'
BROADCAST='134.95.9.255'
GATEWAYS_1='134.95.9.254'
GATEWAYS='134.95.9.254'
ROOT_PATH='/usr/lib/fai/nfsroot'
DNSSRVS_1='134.95.9.136'
DNSSRVS_2='134.95.129.23'
DNSSRVS_3='134.95.100.208'
DNSSRVS_4='134.95.140.208'
DNSSRVS='134.95.9.136 134.95.129.23 134.95.100.208 134.95.140.208'
DOMAIN='informatik.uni-koeln.de'
SEARCH='informatik.uni-koeln.de uni-koeln.de'
YPSRVR_1='134.95.9.10'
YPSRVR='134.95.9.10'
YPDOMAIN='informatik4711.YP'
TIMESRVS_1='134.95.9.10'
TIMESRVS='134.95.9.10'
NTPSRVS_1='192.76.170.145'
NTPSRVS_2='134.95.4.37'
NTPSRVS='192.76.170.145 134.95.4.37'
HOSTNAME='bigfoot'
T172='verbose sshd createvt syslogd'
# define variable if T17x is defined
[ "$T170" ] && FAI_LOCATION=$T170
[ "$T171" ] && FAI_ACTION=$T171
[ "$T172" ] && FAI_FLAGS=$T172
</example>

The last part is shell code which maps the T17X tags to shell variables.
The tag <tt>T172</tt> is the definition for <var>$FAI_FLAGS</var>. It
contains a space separated list of flags. The following flags are known:
<taglist>
 <tag>verbose</tag> <item> <p>Create verbose output during
 installation. This should always be the first flag, so consecutive
 definitions of flags will be verbosely displayed.</p> </item>

 <tag>debug</tag> <item> <p>Create debug output. No unattended
 installation is performed. During package installation you have to
 answer all questions of the postinstall scripts on the
 client's console. </p> </item>

 <tag>sshd</tag> <item> <p>Start the ssh daemon to enable remote
 logins.</p> </item>

 <tag>syslogd</tag> <item> <p>Start the system and kernel log daemon, so
  processes can use it to give out information. This flag should only be 
  used when the syslogd is not already running on the system, so it should
  only be set when initially installing, <em>not</em> on updates!
</p> </item> 

  <tag>createvt</tag> <item> <p>Create two virtual terminals and
  execute a bash if <tt>ctrl-c</tt> is typed in the console
  terminal. The additional terminals can be accessed by typing
  <tt>Alt-F2</tt> or <tt>Alt-F3</tt>. Otherwise no terminals are
  available and typing <tt>ctrl-c</tt> will reboot the install
  client. Setting this flag is useful for debugging. If you want an
  installation which should not be interruptible, do not set this
  flag.</p> </item>

 <tag>reboot</tag> <item> <p>Reboot the install client after installation
 is finished without typing RETURN on the console. This is only useful if you can
 change the boot image or boot device automatically or your assembly robot
 can remove the boot floppy via remote control :-)
 Currently this should only be used when
 booting from network card and using <var>$TFTPLINK</var>.</p> </item>
</taglist>


<sect id=classc> The class concept<p>

Classes determine which configuration file to choose from a list of
available templates. Classes are used in all further tasks of the
installation. To determine which config file to use, an install
client searches the list of defined classes and uses all
configuration files that match a class name. It's also possible to use
only the configuration file with the highest priority since the order
of classes define the priority from low to high. There are some
predefined classes (DEFAULT, LAST and the hostname), but classes can
also be listed in a file or defined dynamically by scripts. So it's
easy to define a class depending on the subnet information or on some
hardware that is available on the install client.
<p>
The idea of using classes in general and using certain files matching
a class name for a configuration is adopted from the installation
scripts by Casper Dik for Solaris. This technique proved to be very
useful for the SUN workstations, so I also use it for the fully
automatic installation of Linux. One simple and very efficient feature
of Casper's scripts is to call a command with all files (or on the
first one) whose file
names are also a class. The following loop implements this function
in pseudo shell code:

<example>
   for class in $all_classes; do
   if [ -r $config_dir/$class ]; then
      your_command $config_dir/$class
      # exit if only the first matching file is needed
   fi
   done
</example>
Therefore it is possible to add a new file to
the configuration without changing the script. This is because the
loop automatically detects new configurations files that should be
used. Unfortunately cfengine does not support this nice feature, so
all classes being used in cfengine need also to be specified inside
the cfengine scripts. Classes are very important for the fully
automatic installation. If a client belongs to class <tt>A</tt>, we
say the class <tt>A</tt> is defined. A class has no value, it is just
defined or undefined. Within scripts, the variable <var>$classes</var>
holds a space separated list with the names of all defined classes.
Classes determine how the installation is performed. For example, an
install client can be configured to become a FTP server by just adding
the class <tt>FTP</tt> to it.

Mostly a configuration is created by only changing or appending the
classes to which a client belongs, making the installation of a new
client very easy. Thus no additional information needs to be added to
the configuration files if the existing classes suffice for your needs.
There are different possibilities to define classes:
<enumlist>
     <item><p>Some default classes are defined for every host:
     DEFAULT, LAST and its hostname.</p> </item>
     <item><p>Classes may be listed within a file.</p> </item>
     <item><p>Classes may be defined by scripts.</p> </item>
 </enumlist>

The last option is a very nice feature, since these scripts will
define classes automatically. For example, several classes are
defined only if certain hardware is identified. We use Perl and shell
scripts to define classes. All names of classes, except the hostname,
are written in uppercase. They must not contain a hyphen, a hash or a
dot, but may contain underscores. A description of all classes can be
found in <file>/usr/share/doc/fai/classes_description.txt</file>.
<p>

Hostnames should rarely be used for the configuration files in the
configuration space. Instead, a class should be defined and
then added for a given host. This is because most of the time the
configuration data is not specific for one host, but is can be shared
among several hosts.

<sect id=s2> Defining classes<p>

The default task <em>defclass</em> calls the script <manref
name="fai-class" section="1"> to define classes. Therefore, scripts
matching <tt>[0-9][0-9]*</tt> in <tt>/fai/class</tt> are
executed. Additionally, files in this directory can contain a list of
classes. We use a file <file>koeln</file> which is used for all our
hosts that belong to a certain subnet. When we want to add a class to
all these hsots, we just add the class to this file.
For more information on defining class, read the manual pages for <manref
name="fai-class" section="1">. <p>

The list of all defined classes is stored in the variable
<var>$classes</var> and saved to
<file>/tmp/fai/FAI_CLASSES</file>. The list of all classes is
transfered to <prgn>cfengine</prgn>, so it can use them too. The
script <file>01alias</file> (see below) is used to define classes for
several groups of hosts. First this script defines the class with the
name of the hardware architecture in uppercase letters.  All hosts
with the prefix <var>ant</var> use all classes in the file
<file>anthill</file>. Hosts which have an IP address in subnet
134.95.9.0 also belong to the class <tt>NET_9</tt>, hosts in ther
class B subnet 134.95 use all classes of the file
<file>koeln</file>. All Beowulf nodes with prefix <var>atom</var>
except <var>atom00</var> (master server) will belong to the classes
listed in file <file>atoms</file>. Some notebooks get also some
special classes.

<example>
# cat 01alias

uname -s | tr /a-z/ /A-Z/
[ -x "`which dpkg`" ] && dpkg --print-installation-architecture | tr /a-z/ /A-Z/

# all hosts named ant?? are using the classes in file anthill
case $HOSTNAME in
    ant??) cat anthill ;;
esac

# all hosts named nuerburg? are becoming web kiosk systems
case $HOSTNAME in
    nuerburg?) cat wwwkiosk ;;
esac

# the Beowulf cluster; all nodes except the master node
# use classes from file class/atoms
case $HOSTNAME in
    atom00) echo BEOWULF_MASTER ;;
    atom??) cat atoms ;;
esac

# if host belongs to class C subnet 134.95.9.0 use class NET_9
# exclude all hosts with an IP address above 200
case $IPADDR in
    134.95.9.2??) ;;
    134.95.*.*) cat koeln ; echo "CS_KOELN NET_9" ;;
    134.95.9.*) echo "CS_KOELN NET_9" ;;
esac

# our notebooks
case $HOSTNAME in
    paeffgen|schlaeffli)
        cat notebook
        echo "BOOTWINDOWS"
        ;;
    pittermaennche)
        cat notebook
        echo "BOOTP_SERVER"
        ;;
esac
</example>

Script <file>18disk</file> can be used to define classes depending
on the number of local disks or the size of these disks<footnote>
<p>It uses the library <file>Fai.pm</file>, which includes some useful
subroutines, e.g. <tt>class</tt>, <tt>classes</tt>,
<tt>read_memory_info</tt>, <tt>read_ethernet_info</tt>.</p>
</footnote>. But you can also use a range of partition size in the
disk configuration file (in <file>disk_config</file>), so you may not
need a class for every different disk size.
<p>
The script <file>24nis</file> automatically defines classes
corresponding to NIS. The name of the NIS domain (defined via BOOTP or
DHCP) will also become a class (only uppercase letters and minus is
replaced by underscore). If no NIS domain is defined, then only the
class NONIS is defined.
<p>
Depending on partition names defined in the first matching
<file>disk_config</file> found, <file>70partitions</file> defines
additional classes. For example, if a partition
<file>/files/scratch</file> exists, the class FILES_SCRATCH is
defined, which forces the install client to export
this directory via NFS and to install the NFS server packages.
<p>
The script <prgn>11modules.source</prgn> does not define any class, but
is responsible for loading kernel modules. Kernel modules are
important for detecting hardware. This script calls the script
<var>$HOSTNAME</var><tt>.mod</tt> and all scripts that have the format
<tt>&lt;classname&gt;.mod</tt> and those class names are already
defined. Classes which are used for loading modules must be defined
before this script is called. For example, if class <tt>DEFAULT</tt> is
defined (this class is always defined) and a file
<file>DEFAULT.mod</file> exists, this script is executed. These
scripts should contain all commands for loading kernel modules:

<example>
DEFAULT.mod:

kernelmodules="rtc floppy parport_pc usbkbd usb-uhci keybdev"

for mod in $kernelmodules; do
    [ "$verbose" ] && echo loading kernel module $mod
    modprobe -a $mod
done
</example>

You can find messages from modprobe in <file>/tmp/fai/dmesg.log</file> and
the on the fourth console terminal by pressing <tt>Alt-F4</tt>.<p>

<sect id=classvariables> Defining Variables<p>

The task <tt>defvar</tt> defines the variables for the install
client. Variables are defined by scripts in
<tt>class/*.var</tt>. All global variables can be set in
<file>DEFAULT.var</file>. For certain groups of hosts use a class file
or for a single host use the file
<var>$HOSTNAME</var><tt>.var</tt>. Also here, it's useful to study all
the examples.

The following variables are used in the examples and may be also useful
for your installation:

<taglist>
   <tag>FAI_ACTION</tag> <item> <p>Set the action fai should
   perform. Currently this is done in the script <file>LAST.var</file>.

   <tag>FAI_CONSOLEFONT</tag> <item> <p>Is the font which is loaded during
   installation by <manref name="consolechars" section="8">.</p> </item>

   <tag>FAI_KEYMAP</tag> <item> <p>Defines the keyboard map files in
   <file>/usr/share/keymaps</file> and <file>$FAI/files</file>. You
   need not specify the complete path, since this file will be located
   automatically.</p> </item>

   <tag>kernelimage</tag> <item> <p>The kernel that is installed to
   the new system. If a Debian package
   <file>/fai/files/packages/</file><var>$kernelimage</var> exists,
   install this kernel package. Otherwise install the package
   <var>$kernelimage</var> from the Debian mirror. For example, if
   <tt>kernelimage=kernel-image-&kver;-idepci</tt> this kernel will be
   installed. To install a special kernel for host bigfoot, set the
   variable
   <example>kernelimage=kernel-image-&kver;_bigfoot1_i386.deb</example>
   and this kernel will be installed from
   <file>/fai/files/packages/</file>.
  <p>The easiest way to install your local kernel package is to put
   this Debian package in
   <file>/usr/local/share/fai/files/packages/</file> on the install
   server. Then define the kernel name with
   <example>kernelimage=kernel-image-&kver;-wwwkiosk</example> without
   specifining the revision of the Debian package. Now fai will
   install this kernel using <manref name="apt-get" section="8">.
   </p></item>

   <tag>rootpw</tag> <item> <p>The root password for the new
   system. Additionally, FAI creates an root account with the same
   password called <tt>roott</tt>, which uses the <manref name="tcsh"
   section="1">.</p> </item>

   <tag>UTC</tag> <item> <p>Set hardware clock to UTC if
   <tt>$UTC=yes</tt>. Otherwise set clock to local time. See <manref
   name="clock" section="8"> for more information.</p> </item>

   <tag>time_zone</tag> <item> <p>Is the file relative to
   <file>/usr/share/zoneinfo/</file> which indicates your time
   zone.</p> </item>

   <tag>liloappend</tag> <item> <p>Append parameters for the kernel of
   the new system (written to <file>/etc/lilo.conf</file>).</p> </item>

   <tag>moduleslist</tag> <item> <p>Can be a multi line
   definition. List of modules (including kernel parameters) which are
   loaded during boot of the new system (written to /etc/modules).</p>
   </item>

   <tag>TFTPLINK</tag> <item> <p>Link to the TFTP kernel image which boots
   using the root file system from the local disk. </p> </item>

   <tag>hserver, bserver</tag> <item> <p>The names of the NFS servers for
   <file>/home</file> and <file>/usr</file>.</p> </item> 

   <tag>printers</tag> <item> <p>List of printers, for which a spool
   directory is created. The config scripts does not set up
   <file>/etc/printcap</file>.</p> </item> 

   <tag>addpackages</tag> <item> <p>The list of additional packages
   which are installed on the new system if they are available in
   <file>/fai/files/packages</file>. You can create a simple
   repository by using following commands on the install server:

<example>
# cd /usr/local/share/fai/files
# dpkg-scanpackages packages /dev/null | gzip -9 > packages/Packages.gz
</example>

Additionally, you can also create a Release file in this
directory. Then <var>addpackages</var> can be the list of packages
without a version number.  For more information, refer to the
repository HOWTO
<footnote>http://www.isotton.com/debian/docs/repository-howto/</footnote>.
This can be used to install local site specific
packages.

</taglist>


<sect id=diskconfig>Hard disk configuration<p> 

The format of the hard disk configuration files is described in
<file>/usr/share/doc/fai/README.disk_config.gz</file>. The config file
<file>/fai/disk_config/CS_KOELN</file> is a generic description for
one IDE hard disk, which should fit for most installations. If you
can't partition your hard disk using this script <footnote><p>Currently
this script uses the command <tt>sfdisk(8)</tt>, which isn't available
on SUN SPARC.</p> </footnote>, use a hook instead. The hook should
write the new partition table, create the file systems and create the
files <file>/tmp/fai/fstab</file> and <file>/tmp/fai/disk_var.sh</file>, which
contains definitions of boot and root partitions.
<p>

<sect id=packageconfig>Software package configuration<p>
The script <prgn>install_packages</prgn> installs the selected software
packages. It uses all configuration files in <file>/fai/package_config</file>
whose file name matches a defined class. The syntax is very
simple.

<example>
# an example package class

PACKAGES taskinst
german science

PACKAGES install
adduser netstd ae
less passwd

PACKAGES remove
gpm xdm

PACKAGES dselect-upgrade
ddd                     install
a2ps                    install
</example>

Comments are starting with a hash (#) and are ending at the end of
the line. Every command begins with the word <tt>PACKAGES</tt>
followed by a command name. The command name is similar to those of
<prgn>apt-get</prgn>. Here's the list of supported command names:


<taglist>
<tag>hold:</tag> <item> <p>Put a package on hold. This package will
not be handled by dpkg, e.g not upgraded.</p> </item>

<tag>install:</tag> <item> <p>Install all packages that are specified
in the following lines. If a hyphen is appended to the package name
   (with no intervening space), the package will be removed, not
   installed. All package names are checked for misspellings. 
Any package which does not exist, will be removed from the list of
packages to install. So be careful not to misspell any package names.</p> </item>

<tag>remove:</tag> <item> <p>Remove all packages that are specified in
the following lines. Append a + to the package name if the package
should be installed.</p> </item>

<tag>taskinst:</tag> <item> <p>Install all packages belonging to the
task that are specified in the following lines using <manref
name="tasksel" section="1">.</p> </item>

<tag>dselect-upgrade</tag> <item> <p> Set package selections using the
following lines and install or remove the packages specified. These
lines are the output of the command <tt>dpkg --get-selections</tt>.
</taglist>


Multiple lines with lists of space separated names of packages follows
the commands install and remove. All dependencies are resolved and <prgn>apt-get</prgn>
is used to perform the installation or removal of packages. The order of the
packages is of no matter. 
<p>
A line which contains the <tt>PRELOADRM</tt> commands, downloads a
file using <manref name="wget" section="1"> into a directory before
installing the packages. Using the <tt>file:</tt> URL, this file is copied
from <var>$FAI_ROOT</var> to the download directory.
For examples the package
<prgn>realplayer</prgn> needs an archive to install the software, so
this archive is downloaded to the directory <file>/root</file>. After
installing the packages this file will be removed. If the file
shouldn't be removed, use the the command <tt>PRELOAD</tt> instead.

<p>
Now it's possible to append a list of class names after the command for
apt-get. So this <tt>PACKAGE</tt> command will only be executed when
the corresponding class is defined. So you can combine many small
files into the file DEFAULT. <tt>WARNING!</tt> Use this feature only
in the file DEFAULT. See this file for some examples.

<p>
If you specify a package that does not exists this package will be
removed from the installation list. You can also test all software package
configuration files with the utility <prgn>chkdebnames</prgn>, which
is available in <file>/usr/share/fai/utils/</file>.
<example>
> chkdebnames stable /usr/local/share/fai/package_config/*
</example>

<sect id=cscripts>Scripts in <tt>/fai/scripts</tt><p>

The default set of scripts in this directory is only an example. But
they should do a reasonable job for your installation. You can edit them
or add new scripts to match your local needs.
<p>
If a directory with a class name exists, all scripts matching
<file>S[0-9]*</file> are executed in alphabetical order. So it's
possible to use scripts of different lanuages (sheel, cfengine,
perl,..) for one class.

<sect1 id=shell>Shell scripts<p>

Most scripts are Bourne shell scripts. Shell scripts are useful if the
configuration task only needs to call some shell commands or create a
file from scratch. In order not to write many short scripts, it's
possible to distinguish classes within a script using the command
<tt>ifclass</tt>. For copying files with classes, use the command
<manref name="fcopy" section="8">. If you like to extract an archive
using classes, use <manref name="ftar" section="8">.
But now have a look at the scripts and see what they are doing.

<sect1 id=perl>Perl scripts<p>
Currently no Perl script is used for modifying the system
configuration.

<sect1 id=expect>Expect scripts<p>
Currently no expect scripts are used for modifying the system
configuration.

<sect1 id=cfengine>Cfengine scripts<p>

Cfengine has a rich set of functions to edit existing configuration
files, e.g <tt>LocateLineMatching, ReplaceAll, InsertLine,
AppendIfNoSuchLine, HashCommentLinesContaining</tt>. But it can't
handle variables which are undefined. If a variable is undefined,
the whole cfengine script will abort. Study the examples that are
included in the fai package.

More information can be found in the manual page <manref
name="cfengine" section="8"> or at the cfengine homepage
<httpsite>http://www.cfengine.org</httpsite>.


<sect id=changeboot>Changing the boot device<p>

Changing the boot sequence is normally done in the BIOS setup. But
you can't change the BIOS from a running Linux system as far as I
know. If you know how to perform this, please send me an email. But there's
another way of swapping the boot device of a running Linux system.

<p>
Change the boot sequence in the BIOS, so the first boot device is the
local disk where the master boot record is located. The second boot
device should be set to LAN or floppy disk, depending from which media
you boot when the installation process is performed.
<p>
After the installation is performed, <manref name="lilo" section="8">
or <manref name="grub" section="8">
will write a valid boot sector to the local disk. Since it's the first
boot device, the computer will boot the new installed system. If you
like to perform an installation again, you have to disable this boot
sector using the command <manref name="bootsector" section="8"><footnote><p>The
command <manref name="bootsector" section="8"> is part of the package
<package>fai</package> and will be installed to
<file>/usr/local/sbin</file> on the install clients.</p></footnote>
. For more information use: <example># bootsector -h
</example>


This is how to set up the a 3Com network card as second boot device,
even if the BIOS doesn't support this. Enable LAN as first boot device
in the BIOS.

<example>
Boot From LAN First: Enabled
Boot Sequence      : C only
</example>

Then enter the MBA setup of the 3Com network card and change it as follows:
<example>
Default Boot           Local
Local Boot             Enabled
Message Timeout        3 Seconds
Boot Failure Prompt    Wait for timeout
Boot Failure           Next boot device
</example>

This will enable the first IDE hard disk as first boot device. If the
boot sector of the hard disk is disabled, the computer will use the
network interface as second boot device and boot from it. Maybe the
disk partitioning tool can't work on such a disk. So you have to
enable the boot sector before you want to partition the disk.

If booting from a FAI floppy disk, another solution can be used to skip a
re-installation if the BIOS is configured to boot from the floppy disk
first and you are not here to remove the floppy disk : use
<example>
# lilo -R ...
</example>
to instruct the FAI floppy to boot from the hard disk only once (see
<manref name="lilo" section="8">). Thus after this first reboot, the FAI
floppy disk can be used for another FAI installation.


<sect id=hooks>Hooks<p>

Hooks let you specify functions or programs which are run at certain
steps of the installation process. Before a default task is called,
FAI searches for existing hooks for this task and executes them. As you
might expect, classes are also used when calling hooks. Hooks are
executed for every defined class. You only have to create the hook
with the name for the desired class and it will be used. If
<tt>debug</tt> is included in <var>$FAI_FLAG</var> the option
<tt>-d</tt> is passed to all hooks, so you can debug your own hooks.
If some default tasks should be skipped, use the subroutine
<tt>skiptask</tt> and a list of default tasks as parameters. The
example <file>partition.DISKLESS</file> skips some default tasks.
<p>


The directory <file>/fai/hooks/</file> contains all hooks. The file
name of a hook consists of a hook name as a prefix and a class name,
separated by a dot. The prefix describes the time when the hook is
called, if the class is defined for the install client. For example,
the hook <file>partition.DISKLESS</file> is called for every client
belonging to the class <tt>DISKLESS</tt> before the local disks would
be partitioned. If it should become a diskless client, this hook
can mount remote filesystems via NFS and create a <tt>/tmp/fai/fstab</tt>.
After that, the installation process will not try to partition and
format a local hard disk, because a file <file>/tmp/fai/fstab</file>
already exists.
<p>
A hook of the form <tt>hookprefix.classname</tt>  can't define
variables for the installation script, because it's a subprocess. But
you can use any binary executable or any script you wrote. Hooks that
have the suffix <tt>.source</tt> (e.g. <file>partition.DEFAULT.source</file>) must
be Bourne shell scripts and are sourced. So it's possible to
redefine variables for the installation scripts.
<p>

In the first part of fai, all hooks with prefix <tt>confdir</tt> are called.
Since the configuration directory <file>/fai</file> is mounted in the
default task <tt>confdir</tt>, the hooks for this task are the only
hooks located in <var>$nfsroot</var><file>/fai/hooks</file> on the
install server. All other hooks are found in
<file>/usr/local/share/fai/hooks</file> on the install server.

All hooks that are called before classes are defined can only use the
following classes: <tt>DEFAULT $HOSTNAME LAST</tt>. If a hook for
class <tt>DEFAULT</tt> should only be called if no hook for class
<var>$HOSTNAME</var> is available, insert these lines to the default
hook:

<example>
hookexample.DEFAULT:

#! /bin/sh

# skip DEFAULT hook if a hook for $HOSTNAME exists
scriptname=$(basename $0 .DEFAULT)
[-f /fai/hooks/$scriptname.$HOSTNAME ] && exit
# here follows the actions for class DEFAULT
.
.
</example>


<p> Some examples for what hooks could be used:

<list>
<item> <p>Use <prgn>ssh</prgn> in the very beginning to verify that
you mounted the configuration from the correct server and not a
possible spoofing host.</p></item>

<item> <p>Do not mount the configuration directory, instead get a
compressed archive via HTTP or from floppy disk and extract it into a
new ram disk, then redefine <var>$FAI_LOCATION</var>.</p></item>

<item> <p>Load kernel modules before classes are defined
in <file>/fai/class</file>. </p></item>

<item> <p>Send an email to the administrator if the installation is finished.</p></item>

<item> <p>Install a diskless client and skip local disk
partitioning. See <file>hooks/partition.DISKLESS</file>.</p></item>
</list>

<sect id=errors>Looking for errors<p>
If the client can't successfully boot from the network card, use
<manref name="tcpdump" section="8"> to look for Ethernet packets
between the install server and the client. Search also for entries in
several log files made by <manref name="in.tftpd" section="8"> and
<manref name="bootpd" section="8">:

<example>egrep "tftpd|bootpd" /var/log/*</example>


If the installation process finishes, the hook
<file>faiend.LAST</file> searches all log files for common errors and
write them to the file <file>error.log</file>. So, you should first
look into this file for errors. To be sure, you should look for errors
in all log files.<p>

Sometimes the installation seems to stop, but there's only a
postinstall script of a software package that requires manual input
from the console. Change to another virtual terminal and look which
process is running  with tools like <manref name="top" section="1"> and <manref
name="pstree" section="1">. You can add <tt>debug</tt> to
<tt>FAI_FLAGS</tt> to make the installation process show all output
from the postinst scripts on the console and get its input also from the
console. Don't hesitate to send an email to the mailing list or to
<email>fai@informatik.uni-koeln.de</email> if you have any
questions. Sample log files from successful installed computers are
available on the FAI homepage.

<chapt id=beowulf>How to build a Beowulf cluster using FAI<p>

This chapter describes the details about building a Beowulf
cluster using &dgl; and FAI. For more information about the Beowulf
concept look at <httpsite>http://www.beowulf.org</httpsite>. 

<sect id=beoplan> Planning the Beowulf setup<p>

The example of a Beowulf cluster consists of one master node and 25
clients. A big rack was assembled which all the cases were put into. A
keyboard and a monitor, which are connected to the master server
most of the time,
were also put into the rack. But since we have very long
cables for monitor and keyboard, they can also be connected to all
nodes if something has to be changed in the BIOS, or when looking for
errors when a node does not boot. Power supply is another topic you
have to think about. Don't connect many nodes to one power cord and
one outlet. Distribute them among several breakout boxes and outlets.
And what about the heat emission? A dozen nodes in a small room can
create too much heat, so you will need an air conditioner. Will the
power supplies of each node go to stand by mode or are all nodes
turned on simultaneously after a power failure?

<p>

All computers are connected to a Fast Ethernet switch. The master node
(or master server) is called <em>nucleus</em>. It has two network
cards. One for the connection to the external Internet, one for the
connection to the internal cluster network. If connected from the
external Internet, it's called <em>nucleus</em>, but the cluster nodes
access the master node with the name <em>atom00</em>, which is a name
for the second network interface. The master server is also the
install server for the computing nodes. A local Debian mirror will be
installed on the local harddisk. The home directories of all user
accounts is also located on the master server. It will be exported via
NFS to all computing nodes. NIS will be used to distribute account,
host, and printer information to all nodes.

<p>
All client nodes <em>atom01</em> to <em>atom25</em> are connected via
the switch with the second interface card of the master node. They can
only connect to the other nodes or the master, but can't communicate
to any host outside their cluster network. So, all services (NTP, DNS,
NIS, ...) must be available on the master server. I choose the class C
network address <em>192.168.42.0</em> for building the local Beowulf
cluster network. You can replace the subnet 42 with any other number
you like. If you have more that 253 computing nodes, choose a class A
network address (10.X.X.X).

<p>
In the phase of preparing the installation, you have to boot the first
install client many time, until there's no fault in your configuration
scripts. Therefore you should have physical access to the master
server and one client node. If you have little space, connect both
computers to a switch box, so one keyboard and monitor can be shared
among both.

<sect id=master> Set up the master server<p>

The master server will be installed by hand if it is your
first computer installed with Debian. If you already have a Debian
host running, you can also install it via FAI. Create a partition on
<file>/files/scratch</file> for the local Debian mirror with more that
&mirrorsize GB space available.

<sect1 id=beonetworkmaster> Set up the network<p>

Add the following lines for the second network card to
<file>/etc/network/interfaces</file>:
<example>
# Beowulf cluster connection
auto eth1
iface eth1 inet static
address 192.168.42.250
netmask 255.255.255.0
broadcast 192.168.42.255
</example>

Add the IP addresses for the client nodes. The FAI package has an
example for this <file>/etc/hosts</file> file:
<example>
# Beowulf nodes
# atom00 is the master server
192.168.42.250 atom00
192.168.42.1 atom01
192.168.42.2 atom02
</example>

You can give the internal Beowulf network a name when you add this
line to <file>/etc/networks</file>:
<example>beowcluster 192.168.42.0</example>


Activate the second network interface with: <tt>/etc/init.d/networking start</tt>.

<sect1 id=beonis> Setting up NIS<p>

Add a normal user account <var>tom</var> which is the person who edits
the configuration space and manages the local Debian mirror:
<example># adduser tom
# addgroup linuxadmin
</example>

This user should also be in the group <var>linuxadmin</var>. So, add a
line to <file>/etc/group</file>:
<example>
linuxadmin:x:101:tom
</example>

To initialize the master server as NIS server call <tt>ypinit -m</tt>.
Then, copy the file <file>netgroup</file> from the examples directory
to <file>/etc</file> and edit other files there. Adjust access to the
NIS service.

<example># cat /etc/ypserv.securenets
# Always allow access for localhost
255.0.0.0       127.0.0.0
# This line gives access to the Beowulf cluster
255.255.255.0 192.168.42.0
</example>

Rebuild the NIS maps:
<example># cd /var/yp; make</example>

<sect1 id=beomirror> Create a local Debian mirror<p>

Now the user <var>tom</var> can create a local Debian mirror on
<file>/files/scratch/</file> using <prgn>mkdebmirror</prgn>. This will
need about &mirrorsize GB disk space for Debian 3.0 (aka woody). Export this
directory to the netgroup <tt>@faiclients</tt> read only.

<sect1 id=fai1> Install FAI package on the master server<p>

Add the following packages to the install server:
<example>nucleus:/# apt-get install ntp tftp bootp nfs-kernel-server fai fai-kernels
nucleus:/# tasksel -q -n install dns-server
nucleus:/# apt-get dselect-upgrade
</example>
Configure NTP so that the master server will have the correct system time.

<p>
It's very important to use the internal network name <var>atom00</var>
 for the master sever (not the external name <var>nucleus</var>) in
 <file>/etc/bootptab</file> and &fc;. Replace
 the strings FAISERVER with <tt>atom00</tt> in
 <file>/etc/bootptab</file> and uncomment the following line in &fc;
 so the Beowulf nodes can use the name for connecting their master
 server.
<example>
NFSROOT_ETC_HOSTS="192.168.42.250 atom00"
</example>

<file>/etc/bootptab:</file>
<example>
.
.
.failocal:\
        :tc=.faiglobal:\
        :sa=atom00:\
        :ts=atom00:\
        :T172="verbose createvt sshd":\
        :sm=255.255.255.0:\
        :gw=192.168.42.250:\
        :dn=beowulf.debian.org:\
        :ds=192.168.42.250:\
        :ys=atom00:yd=nisnucleus:\
        :nt=atom00:
.
.
</example>

<sect1 id=bootp1> Prepare network booting<p>

Uncomment the following line in <file>/etc/inetd.conf</file>:
<example>#bootps dgram udp wait root /usr/sbin/bootpd bootpd -i -t 120
</example>
and restart the inetd daemon.

The user <var>tom</var> should have permission to create the
symlinks for booting via network card, so change the group and add
some utilities.

<example># chgrp -R linuxadmin /boot/fai; chmod -R g+rwx /boot/fai
# cp /usr/share/fai/utils/* /usr/local/bin
</example>

Now, the user <var>tom</var> can create a symlink in
<file>/boot/fai</file> using 
<example>> tlink atom_install atom01</example>
to boot the first client node for the first
time. Then start to adjust the configuration for your client
nodes. Don't forget to build the kernel for the cluster nodes using
<manref name="make-kpkg" section="8"> and store it in <file>/usr/local/share/fai/files/packages</file>.

<sect id=beotools> Tools for Beowulf clusters<p>

The following tools for a Beowulf cluster are now available in
<file>/usr/local/bin</file>:

<taglist>
          <tag> tlink <item> <p>Change the symbolic link that points to
          the kernel image for booting from a network card.</p></item>

          <tag> all_hosts <item> <p>Print a list of all hosts, print
          only the hosts which respond to a ping or the hosts which
          do not respond. The complete list of hosts is defined by the
          netgroup <tt>allhosts</tt>. Look at
          <file>/usr/share/doc/fai/examples/etc/netgroup</file> for an
          example.</p></item>

        <tag>rshall<item><p>Execute a command on all hosts which are
        up via rsh. Uses <prgn>all_hosts</prgn> to get the list of all
        hosts up. You can also use the <manref name="dsh" section="1">
        command (dancer's shell, or distributed shell).

  <tag>rgang</tag> <item> <p>For a huge cluster try
  <prgn>rgang</prgn>. It's is a tool which executes commands on or
  distributes files to many nodes. It uses an algorithm to build a
  tree-like structure to allow the distribution processing time to
  scale very well to 1000 or more nodes (available at
  <httpsite>http://fermitools.fnal.gov/</httpsite>
  <httppath>abstracts/rgang/abstract.html</httppath>). </p></item>

  <tag>jmon</tag><item><p>For observing the resources of all
  clients (CPU, memory, swap,...)  you can use <manref
  name="jmon" section="1"> which installs a simple daemon on
  every cluster node. </item>

  <tag>ganglia</tag><item><p>This toolkit is very good for monitoring
   your cluster. Available at
   <httpsite>http://ganglia.sourceforge.net/</httpsite> </p> </item>

</taglist>

But there are a lot of other tools
available which are not yet included in a Debian package. </p>

<sect id=wol> Wake on LAN with 3Com network cards<p>

Wake on LAN is a very nice feature to power on a computer without
having physical access to it. By sending a special ethernet packet to
the network card, the computer will be turned on. The following things
have to be done, to use the wake on LAN (WOL) feature.<p>

<enumlist>
<item><p>Connect the network card to the Wake-On-LAN connector on the
motherboard using a 3 pin cable.</p></item>
 <item><p>My ASUS K7M motherboard has a jumper called
<tt>Vaux (3VSBSLT)</tt> which allows to select the voltage supplied to add-in
PCI cards. Set it to <tt>Add 3VSB</tt> (3 Volt stand by).</p></item>
<item><p>Turn on the wake on LAN feature in BIOS</p></item>
<item><p>For a 2.2 kernel you have to use the following driver: 
<httpsite>http://www.uow.edu.au/</httpsite><httppath>~andrewm/linux/#3c59x-bc</httppath></p></item>
</enumlist>

There's a little problem to enable the wake on LAN feature with a
2.2.19 kernel and a 3Com 3C905C network card. You have to use a
patched 3c59x driver. But I managed to get it to work. Download the file
<file>poll-ioctl-2.2.18-pre16.c.gz</file> and copy it to kernel
sources to <file>drivers/net/3c59x.c</file>. Then make a new kernel
package and install this new kernel.

To wake up a computer use the tool etherwake (in woody) or get the
single C source file. For more information look at
<httpsite>http://www.scyld.com/</httpsite><httppath>expert/wake-on-lan.html</httppath>.

<chapt id=sparc>FAI on SUN SPARC hardware running Linux<p>
Although FAI is architecture independent, there are some packages which
are only available for certain architectures (e.g. silo, sparc-utils).

SUN SPARC computers can boot from their boot prompt and don't need a
boot floppy. To boot a SUN use: <example>boot net</example>

You have to convert the kernel image from ELF format to a.out
format. Use the program <prgn>elftoaout</prgn> (mentioned in
the FAQ). The symlink to the kernel image to be booted is not the host
name. Look at the FAQ at
<httpsite>http://www.ultralinux.org</httpsite> for more information.

A success report is available at
<httpsite>http://www.opossum.ch/</httpsite><httppath>fai/</httppath>
and a HOWTO can be found at
<httpsite>http://toolbox.rutgers.edu/</httpsite><httppath>~amurphy/fai</httppath>.

<chapt id=hints>Various hints<p>

This chapter has various hints which may not always be explained in great
detail.
<p>
When using HTTP access to a Debian mirror, the local <tt>/var</tt>
partition on all install clients must be big enough to keep the
downloaded Debian packages. Do not try with less than 250 Mbytes
unless you know why.
<p>


You can merge two directories which contain configuration
information, if one is a global one, and the other a local one. We use
it to merge the temples from the fai package, and our local
configuration, which contains encrypted passwords and other
information that should not be readable for others. This is how our
setup looks like.
<p>
We have a local configuration space located in
<file>~admin/additional-fai/</file> which contains following files:
<example>
./files
./files/etc
./files/etc/hosts
./files/etc/hosts/NUERBURG1
./files/etc/hosts/NUERBURG2
./files/etc/network
./files/etc/network/interfaces
./files/etc/network/interfaces/NUERBURG1
./files/etc/network/interfaces/NUERBURG2
./files/etc/bootptab
./files/etc/bootptab/kueppers
./files/etc/kueppers.tar.gz
./files/packages
./files/packages/kernel-image-2.4.20-cskoeln_2_i386.deb
./files/packages/cloop-2.4.20-cskoeln_0.63.1-4+2_i386.deb
./files/packages/xv-doc_3.10a-26_all.deb
./files/packages/xv_3.10a-26_i386.deb
./files/packages/Packages.gz
./files/packages/ltmodem-2.4.20_8.26a9_i386.deb
./files/packages/cloop-2.4.20-acer_0.63.1-4+1_i386.deb
./files/packages/kernel-image-2.4.20-acer_1_i386.deb
./files/packages/pcmcia-modules-2.4.20-acer_3.1.33-6+1_i386.deb
./files/packages/kernel-headers-2.4.20-acer_1_i386.deb
./files/packages/ltmodem-2.4.20-acer_8.26a9_i386.deb
./files/packages/debmirror_20020427-1_all.deb
./files/usr
./files/usr/local
./files/usr/local/ACROREAD5.tar.gz
./files/usr/local/share
./files/usr/local/share/LPRng
./files/usr/local/share/LPRng/pcfilter
./files/usr/local/share/LPRng/pcfilter/NISLPRCLIENT
./files/usr/lib
./files/usr/lib/mozilla
./files/usr/lib/mozilla/CS_KOELN.tar.gz
./class
./class/dom.var
./class/NET_9.var
./mk-packages-gz
./scripts
./scripts/kueppers
./README
./disk_config
./disk_config/dom
./disk_config/kueppers
</example>

The file <file>mk-packages-gz</file> is just the simple script which
creates the <file>Packages.gz</file> as explained above. In order to
copy this local configuration data into the fai config space we use
this command:

<example>cp -a ~admin/additional-fai/* /usr/local/share/fai
</example>

If you remove a file in you local configuration, do not forget to
remove this file also in the configuration space, otherwise it will
still be used.
<p>
AFter calling <prgn>set-dis-kinfo</prgn>, a list of all local hard disks is
stored to <var>$disklist</var> and <var>$device_size</var>
contains a list of disk devices and their sizes.
<p>


Use <prgn>fai-divert -a</prgn> if a postinst script calls a
configuration program, e.g. the postinst script for package apache calls
apacheconfig, which needs manual input. You can fake the configuration
program so the installation can be fully automatic. But don't forget
to use <prgn>fai-divert -R</prgn> to remove all faked script.

<p>
During the installation you can execute commands
inside the newly installed system in a chroot environment by using <tt>chroot /tmp/target</tt>
or just <tt>$ROOTCMD</tt> followed by the command you want to call; for
example <tt>$ROOTCMD dpkg -l</tt> shows the packages installed on
the new system.
<p>

The only task which has to be done manually for new hardware is to
assign the MAC address to a hostname and to an IP address, and to define
classes for this host if the existing configuration files are not generic
enough to deal with this new host.
<p>
There's a tradeoff between writing a few large configuration scripts,
or many short scripts, one for each class. Large scripts can
distinguish classes by using case statements, the <tt>ifclass</tt>
test or with class mechanisms for <tt>cfengine</tt> scripts.
<p>
If your computer can't boot from the network card, you do not always need to boot
from floppy. Define a partition <file>/fai-boot</file> in your
<file>disk_config</file> configuration file. Then the class
<tt>FAI_BOOTPART</tt> will automatically be defined and will create a lilo entry for
booting the FAI bootfloppy from this partition. So you can start the
re-installation without a boot floppy. This will also make the test
phase shorter, since booting from hard disk is much  faster than booting
from floppy.
<p>
To use the <file>/file/scratch</file> partitions on all Beowulf nodes,
use the kernel automounter and the following configuration.

<example>
nucleus[~]> cat /etc/auto.master
/scratch /etc/nodes.scratch
</example>

<example>
nucleus[~]> cat /etc/nodes.scratch 
*               -rw,soft,intr           &:/files/scratch
</example>

<sect id=functions>Useful functions for advanced administrators<p>

<taglist>
<tag>fai-divert</tag> <item> <p>Add or remove a file to the list of diversions
and replace the file with a dummy script. This is useful when a
postinst script needs manual input. At the end of the installation all
diversions are removed.</p> </item>

<tag>skiptask</tag> <item> <p>This given list of tasks are
skipped. For use e.g. in <file>partition.DISKLESS</file>.</p> </item> </taglist>

</book>
</debiandoc>

<!-- 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:nil
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-declaration:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision