FAI Guide (Fully Automatic Installation)
Chapter 2 Installing FAI

2.1 Requirements

Following items are required for an installation via FAI.

A computer:

The computer must have a network interface card and a local hard disk. No floppy disk, CD-ROM, keyboard or graphic card is needed.

BOOTP or DHCP server:

The clients need one of these daemons to obtain boot information.[3]

TFTP server:

The TFTP daemon is used for transfering the kernel to the clients. Only needed when booting from network card with a boot PROM.

Client root:

A mountable directory which contains the whole filesystem for the install clients during installation. It will be created during setup of the FAI package and is also called nfsroot.

Debian mirror:

Access to a Debian mirror is needed. A local mirror of all Debian packages is recommended if you install several computers.

Install kernel:

A kernel image that supports the network card and mounts its root filesystem via NFS.

Configuration space:

A mountable directory which contains the configuration data.

The TFTP daemon and a NFS server will be enabled automatically when installing the FAI package. Different install kernel images for BOOTP and DHCP are available within the package fai-kernels. All clients must have a network card, which is recognized by the install kernel.

2.2 How to create a local Debian mirror

The script mkdebmirror [4] can be used for creating your own local Debian mirror. This script uses the script debmirror[5] and rsync(1). A partitial Debian mirror only for i386 architecture for Debian 2.2r4 (aka potato) without the source packages needs about 2.4 GB of disk space.

2.3 Setting up FAI

Before installing FAI, you have to install the package fai-kernels, which contains the install kernels for FAI. [6]

     kueppers[~]# dpkg -i fai-kernels_1.1.3_i386.deb 
     Selecting previously deselected package fai-kernels.
     (Reading database ... 40562 files and directories currently installed.)
     Unpacking fai-kernels (from .../lange/fai-kernels_1.1.3_i386.deb) ...
     Setting up fai-kernels (1.1.3) ...

Get the newest version of FAI and install it using the dpkg command:

     kueppers[~]# dpkg -i fai_2.2.3_all.deb
     Selecting previously deselected package fai.
     (Reading database ... 39564 files and directories currently installed.)
     Unpacking fai (from fai_2.2.3_all.deb) ...
     Setting up fai (2.2.3) ...
     To set up FAI edit /etc/fai.conf and call fai-setup

All definitions for the FAI package (not the configuration data) are defined in /etc/fai.conf. Since FAI doesn't use debconf yet, edit this file before calling fai-setup. These are important variables in /etc/fai.conf:

FAI_DEBOOTSTRAP

For building the nfsroot there's a new command called debootstrap(8), which replaces the use of the FAI_BASETGZ variable. It needs the location of a Debian mirror and the distribution (potato,woody,stable,unstable) for which the basic Debian system should be build.

FAI_BASETGZ

The location, where the the base file is fetched from. For building the nfsroot, the Debian base system is needed. It's a big tar file (approx. 16MB for base2_2.tgz), which is a minimal collection of all required packages for Debian. If a file base2_2.tgz is already available in /tmp this file will be used instead and no file will be fetched from the defined location. Fetching via ftp or http could take much time, if you do not have a fast connection to your Debian mirror. You can find the current version of this archive in the directory debian/dists/stable/main/disks-i386/current/ of a Debian mirror.

FAI_SOURCES_LIST

This multi line string is the definition for sources.list (used by apt-get(8)), which defines the location and access method of the Debian mirror. If this variable is undefined, the definitions of /etc/apt/sources.list will be used. For more information on the file format see sources.list(5).

FAI_DEBMIRROR

If you have NFS access to your local Debian mirror, specify the remote filesystem. It will be mounted to $MNTPOINT (defined in /etc/fai.conf). It's not needed if you use access via FTP or HTTP.

KERNELPACKAGE

You must specify the software package - build with make-kpkg(8) - which includes the default kernel for booting the install clients. The Debian package fai-kernels contains the default install kernels with BOOTP and DHCP support. Do not use the kernel with BOOTP support when you have a DHCP server running in your network and vice versa. This could lead to missing information.

NFSROOT_PACKAGES

Contains a list of additional software package, that will be added to nfsroot.

The variables FAI_SOURCES_LIST and FAI_DEBMIRROR 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.

FAI uses apt-get(8) to create the nfsroot filesystem in /usr/lib/fai/nfsroot, which needs about 100MB of free disk space. Before setting up FAI, you should get the program imggen,[7] if you like to boot from a 3Com network card. This executable converts netboot images created by mknbi-linux(8), so they can be booted by network cards from 3Com. Put that executable in your path (e.g. /usr/local/bin). After editing /etc/fai.conf call fai-setup.

     kueppers[~]# fai-setup 
     Adding system user fai...
     Stopping Name Service Cache Daemon: nscd.
     Adding new user fai (100) with group nogroup.
     Starting Name Service Cache Daemon: nscd.
     Creating home directory /home/fai.
     /home/fai/.rhosts created.
     User account fai created.
     Creating FAI nfsroot can take a long time and will
     need more than 100MB disk space in /usr/lib/fai/nfsroot.
     Unpacking /tmp/base2_2.tgz
     Upgrading /usr/lib/fai/nfsroot
     Adding additional packages to /usr/lib/fai/nfsroot:
     dhcp-client file rdate cfengine bootpc wget rsh-client less dump
     ext2resize strace hdparm parted dnsutils grub ntpdate psmisc hwtools
     dosfstools sysutils ssh expect5.31
     grep: /etc/ssh/sshd_config: No such file or directory
     grep: /etc/ssh/sshd_config: No such file or directory
     Not starting OpenBSD Secure Shell server (/etc/ssh/NOSERVER)
     make-fai-nfsroot finished.
     Stopping NFS kernel daemon: mountd nfsd.
     Unexporting directories for NFS kernel daemon...done.
     Starting NFS kernel daemon: nfsd mountd.
     Exporting directories for NFS kernel daemon...done.
     Kernel image file name  = /usr/lib/fai/nfsroot/boot/vmlinuz-2.2.19
     Output file name        = /boot/fai/installimage
     Kernel command line     = "auto rw root=/dev/nfs nfsroot=kernel nfsaddrs=kernel"
     
     Image Creator for MBA ROMs v1.00
     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 successfully added 
     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.

The setup routine adds lines to /etc/exports to export the nfsroot and the configuration space to all hosts that belong to the netgroup faiclients. 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 /etc/netgroup or in the corresponding NIS map. An example for the netgroup file can be found in /usr/share/doc/fai/examples/etc/netgroup. For more information, read the manual pages netgroup(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:

     kueppers[~]# /etc/init.d/nfs-kernel-server reload
     kueppers[~]# /etc/init.d/nfs-server reload

The setup also creates the account fai ($LOGUSER). 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 /boot/fai in order to change symbolic links to the kernel image, that is booted by a client. See also variable TFTPLINK in class/DEFAULT.var.

After that, FAI is installed successfully on your server, but has no configuration for the install clients. Start with the templates from /usr/share/fai/templates using the copy command above and read Installation details, Chapter 6. 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 Creating a boot floppy, Section 3.3.

When you make changes to /etc/fai.conf or want to install a new kernel to nfsroot, the nfsroot has to be rebuild by calling make-fai-nfsroot.

2.3.1 Troubleshooting the setup

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