FAI Guide (Fully Automatic Installation)
JavaScript must be enabled in your browser to display the table of contents.
FAI is a non-interactive system to install, customize and manage Linux
systems and software configurations on computers as well as virtual
machines and chroot environments, from small networks to large
infrastructures and clusters.
This manual describes the Fully Automatic Installation software. This
includes the installation of the packages, setting up the server, creating of the
configuration and how to deal with errors.
+-----------------------------------------------------------------------+
| This manual describes FAI 5.4 but most things are also valid for 4.x. |
+-----------------------------------------------------------------------+
Thomas Lange
CopyrightThis man you may redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software F either version 2, or (at your option) any
later version.
This is distributed in the hope that it will be useful, but without
any warranty; without even the implied warranty of merchantability or
fitness for a particular purpose. See the GNU General Public License
for more details.
A copy of the GNU General Public License is available as
/usr/share/common-licenses/GPL in the Debian GNU/Linux distribution
or on the World Wide Web at
You can also obtain it by writing to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA ,
Introduction
Availability
Entry for sources.list
deb https://fai-project.org/download stretch koeln
Manual pages
Mailing list
Send feedback and comments to
to the mailing list.
Use the Debian bug tracking system (BTS)
User visible changes
Source tree via git
git clone git:///faiproject/fai.git
View source tree via http
The man pages always include up-to-date information and a lot of
details of all FAI commands. So, don’t forget to read them carefully.
Now read this manual, then enjoy the fully automatic installation and
your saved time.
Motivation
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?
Repeating the same task again and again is boring — and will surely
lead to errors. Also a whole lot of time could be saved if the
installations 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 planning just a
few months into the future.
In 1999, I had to perform an installation of a Linux cluster with one
server and 16 clients. Since I had much experience doing automatic
installations of Solaris operating systems on SUN SPARC hardware, the
idea to build an automatic installation for Debian was born. Solaris
has an automatic installation feature called JumpStart
. In conjunction with the auto-install scripts
from Casper Dik
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 workstations 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 used
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.
How does FAI work
The install client which will be installed using FAI, is booted via
network card or from CD or USB stick. It gets an IP address and boots
a Linux kernel which mounts its root file system via NFS (the nfsroot)
install server. After the kernel is started, the FAI startup script
performs the automatic installation which doesn’t need any
interaction. First, the hard disks will be partitioned, file systems
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.
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 create a configuration for every
new host. Hence, FAI is a scalable method to install a big cluster
with a great number of nodes even if their configuration is not identical.
FAI can also be used as a rescue system or for hardware inventory. You can boot your
computer, but it will not perform an installation. Instead it will run
a fully functional Debian GNU/Linux without using the local hard
disks. Then you
can do a remote login and backup or restore a disk partition, check a
file system, inspect the hardware or do any other task.
A fully automated installation can be performed.
Very quick unattended installation.
Flexible system through easy class concept.
Update of running systems without re-installation.
Easy creation of a virtualization environment or a chroot
Hosts can boot from network card, CD, USB stick.
Simple creation of an installation CD or USB stick.
PXE with DHCP boot method is supported.
ReiserFS, ext3/ext4, btrfs and XFS file system support.
Software RAID and LVM support.
Automatic hardware detection.
You can deploy Debian, Ubuntu, CentOS, SuSE, Scientific Linux
Remote login via ssh during installation process possible.
All similar configurations are shared among all install clients.
Log files for all installations are saved to the installation server.
Shell, Perl, Python, Ruby, expect and CFEngine scripts are supported during the customization step.
Support for many protocols like NFS, FTP, HTTPS, git
Can be used as a rescue system and for hardware inventory.
Diskless client support.
Cross-architecture support for e.g. for embedded devices
Easily add your own functions via hooks or change the default behavior.
Cloning machines using disk images is supported
The installation time is determined by the amount of software and
the speed of the hard disk. Here are some sample
times. All install clients had a 1Gbit network card installed.
Software installed
6 GB software
Core-i7 3.2GHz
4.3GB software
Core-i7 3.2GHz
471 MB software
Intel Core2 Duo
3 GB software
Quickstart - For the impatient user
My first installation
Without further ado, this section will provide a quick and easy demonstration of a fully automatic installation using the FAI CD and a virtual machine.
Just download the CD ISO image from
your VM using this CD. You will see a grub menu where you can select
from different installation types.
This installation will run without an install server. The CD
installation is the same as when run in a network environment using
the FAI install server.
My first server installation
Please note, if you intend to use QEMU/KVM then you need to have
qemu-kvm qemu-utils bridge-utils installed on the machine to
use fai-mk-network and fai-kvm .
You can do that via
# apt-get install qemu-kvm qemu-utils bridge-utils
If you intend to use VMware or VirtualBox, ensure that your client
uses a bridged network connection. A detailed description is in the
It is not possible to use
bridged network interfaces over wireless, as most WiFi network cards
do not support this featur.
For setting up your first own FAI server, we recommend creating a
test network on your computer and to use KVM. For creating this
private network there’s the script fai-mk-network (in the package
fai-server). It sets up a software bridge with several tap devices
that belong to the user &username&.
fai-mk-network &username&
After that, you can use fai-kvm (-h will give you some help) for
starting virtual machines using KVM that are connected to this private
network. Be carefull. By default, fai-kvm will create the disk images
for the virtual machines in /tmp, which is a RAM disk on most
systems. It’s no problem to create an empty 20G disk image in /tmp
(even if this partition is of 4GB size), but while the VM is writing
data to its disk, this will start to consume space in /tmp.
Start the first virtual host, which will become the FAI server
fai-kvm -Vn -s20 -u 1 cd fai-cd.iso
In the grub menu select faiserver, fixed IP. This will install a host called
faiserver with IP 192.168.33.250 which contains all software needed
for a FAI server. It will also set up a local package cache (using
apt-cacher-ng). Once the installation is finished, reboot the
machine. During the first boot of the new system, it will
automatically set up the nfsroot. This may take some minutes.
After that you can start additional hosts using network boot. For
every new host, you have to use a different value for -u, which will be used for
generating different MAC addresses and using different disk image file
fai-kvm -Vn -u 2 pxe
Those install clients will show you a menu, where you can select which
type of installation you like to perform. If the install client does
not find the server, it is usually because fai-monitor is no longer
running on it. This can happen, if you reboot the faiserver after the
installation. To remedy this, simply run fai-monitor on the faiserver
and re-attempt the client boot.
Another client could be started with:
fai-kvm -Vn -u 3 pxe
You can start as many machines in the network as tap devices are
available. All these machines can connect to the outside internet but are
only reachable from your host machine.
Overview and Concepts
FAI is a non-interactive system to install, customize and manage Linux
systems and software configurations on computers as well as virtual
machines and chroot environments, from small networks to large
infrastructures and clusters. You can take one or more virgin PCs,
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
Linux operating system 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 (bash and zsh), Perl,
Python, Ruby and expect scripts.
FAI’s target group are system administrators who have to install Linux
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. Chapter
has some useful hints for this
Important Terms
First, some terms used in this manual are described.
install server
It provides DHCP, TFTP and NFS services and the configuration data for
all install clients. In the examples of this manual this host is
called faiserver. The host where the package fai-server is installed.
install client
A host which will be installed using FAI and a configuration provided
by the install server. Also called client for short. In this manual,
the example hosts are called demohost, xfcehost, gnomehost …
This computer should boot from its network interface using PXE.
configuration space
A subdirectory structure containg several files. Those files describe
the details of how the installation of the clients will be
performed. All configuration data is stored here. It’s also called
config space for short. It includes information about:
Hard disk layout in a format similar to fstab
Local file systems, their types, mount points and mount options
Software packages
Keyboard layout, time zone, Xorg configuration, remote file
systems, user accounts, printers …
The package fai-doc includes a sample configuration space including
examples for hosts using the XFCE and GNOME environment amongst other
nfsroot, NFS-Root
A file system located on the install server. During the installation
process it’s the complete file system for the install clients. All
clients share the same nfsroot, which they mount read only. The
nfsroot needs about 780MB of free disk space.
Serves clients the initrd and kernel that is used for the installation process.
Along with the file system served by NFS, these two make up a temporary
OS in which the installations are performed.
FAI classes
Classes are names which determine which configuration file is
selected. If a client belongs to class WEBSERVER, it will be configured
as a webserver, the class DESKTOP for e.g. determines which software
packages will be installed.
A FAI profile is just a list of FAI classes assiged to a profile name,
which is extended by a description of this profile. I.e. one could have
two "Webserver" profiles, one including the APACHE class another including the NGINX class,
to then install the respective webserver solution.
The installation of a client consists of several parts, which are called tasks.
Tasks are predefined subroutines which perform a certain part of the
FAI. The following FAI tasks are performed during an installation
on the install clients.
# get the config space
# some initialization, start sshd on demand
# define FAI classes
# define variables
# evaluate FAI_ACTION
# Start the installation
# partition the harddisks, create file systems
mountdisks
# mount the file systems
# extract the base.tar.xz
# do the Debian debconf preseeding
repository
# prepare access to the package repository
updatebase
# Set up package tools and update packages
# install software packages
# call customization scripts
# do some cleanup, show installation statistics
# call tests if defined
# call fai-chboot on the install server
# save log files to local and remote location
# reboot host, eject CD if needed
These are tasks, which are only executed when a different action is performed
dirinstall
# install a chroot environment
softupdate
# only do the system configuration
# print detailed system information
# print short hardware inventory list
For a more in-depth description of tasks , see .
Note that you are not limited to the FAI tasks. You can also define additional programs or scripts which will be run
on particular occasions. They are called hooks.
Hooks are plugins, they can add additional functionality to the installation process
or even replace entire tasks of FAI. Hooks are explained in detail in
The class concept
Classes are used in nearly all tasks of the installation. Classes
determine which configuration files to choose from a list of available
alternatives. To determine which config files to use, FAI searches the
list of defined classes and uses all configuration files that match a
class name . The following loop implements
this function in pseudo shell code:
for class in $all_ do
if [ -r $config_dir/$class ]; then
# if a file with name $class exists
your_command $config_dir/$class
# call a command with this file name
# exit if only the first matching file is needed
The very nice feature of this is that you can add a new configuration
alternative and it will automatically be used by FAI without changing
the code, if the configuration file uses a class name.
This is because the loop automatically detects new configuration files
that should be used.
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 and easy.
You can group multiple hosts that share the same configuration
files by using the same class. You can also split the whole
configuration data for all clients into several classes and use them
like lego bricks and build the entire configuration for a single
client by assembling the bricks together.
If a client belongs to class A, we say the class A
is defined for this client. A class has no value, it is just defined or
undefined.
Classes determine how the installation is performed. For example, an install
client can be configured to get the XFCE desktop by just adding the
class XFCE to it. Naturally, also more granular configurations are possible. For instance, classes can describe how the hard disk should be partitioned, they can
define which software packages will be installed, or which
customization steps are performed.
Often, a client configuration is created by only changing or appending the
classes to which this client belongs, making the installation of a new
client very easy. Thus no additional information needs to be added to
the configuration space if the existing classes suffice for your
As you can see, classes are a central pillar of customizing your configuration space and with that your client installation. On how to define your own classes, refer to .
Setup your faiserver
Here’s how to set up the install server in a few minutes. Following
steps are needed:
Set up the install server
Install FAI packages
Create the nfsroot
Copy the examples to the config space
Configure network daemons
Create the PXELINUX configurations
Boot and install clients
Install the FAI packages
Install the key of the FAI project package repository:
Add the URL of the package repository of the FAI project.
Install the package fai-quickstart on your install server.
# wget -O - https://fai-project.org/download/074BCDE4.asc | apt-key add -
# echo "deb http://fai-project.org/download stretch koeln" & /etc/apt/sources.list.d/fai.list
# apt-get update
# aptitude install fai-quickstart
This will also install the packages for DHCP, TFTP and NFS server daemons.
Create the nfsroot
Also enable the package repository of the FAI project in a different
sources.list file which is used when building the nfsroot. Then,
enable the log user for FAI.
# sed -i -e 's/^#deb/deb/' /etc/fai/apt/sources.list
# sed -i -e 's/#LOGUSER/LOGUSER/' /etc/fai/fai.conf
By default, FAI uses
as package
mirror, which should attempt to find a fast package repository for you.
Now, we can run fai-setup(8)
and check if everything went well.
The log file is written to /var/log/fai/fai-setup.log.
# fai-setup -v
These are some of the lines you will see at the end of
fai-setup. A complete example of fai-setup.log is available on
the FAI web page at .
FAI packages and related packages inside the nfsroot:
dracut-network
fai-client
5.3.3~bpo8+2
fai-nfsroot
5.3.3~bpo8+2
fai-setup-storage
5.3.3~bpo8+2
Waiting for background jobs to finish
fai-make-nfsroot finished properly.
Log file written to /var/log/fai/fai-make-nfsroot.log
Adding line to /etc/exports: /srv/fai/config 192.168.33.250/25(async,ro,no_subtree_check)
Adding line to /etc/exports: /srv/fai/nfsroot 192.168.33.250/25(async,ro,no_subtree_check,no_root_squash)
Reloading nfs-kernel-server configuration (via systemctl): nfs-kernel-server.service.
You have no FAI configuration space yet. Copy the simple examples with:
cp -a /usr/share/doc/fai-doc/examples/simple/* /srv/fai/config
Then change the configuration files to meet your local needs.
Please don't forget to fill out the FAI questionnaire after you've finished your project with FAI.
FAI setup finished.
Log file written to /var/log/fai/fai-setup.log
fai-setup has created the LOGUSER, the nfsroot and has added
additional lines to /etc/exports. The subdirectories added to
/etc/exports are exported via NFS v3, so all install clients in the
same subnet can mount them via NFS.
Creating the configuration space
Install the simple examples into the configuration space
$ cp -a /usr/share/doc/fai-doc/examples/simple/* /srv/fai/config/
These examples contain configuration for some sample
hosts. Depending on the host name used, your computer will be
configured as follows:
A machine which needs only a small hard disk. This machine is
configured with network as DHCP client, and an account demo is
A XFCE desktop is installed, using LVM, and the account demo is created.
A GNOME desktop is installed, and the account demo is created.
other host names
Hosts with another host name will most notably use the classes FAIBASE,
DHCPC and GRUB.
All hosts will have an account called demo with password fai. The
root account also has the password fai.
If the FAI flag menu is added, instead of using the host name for
determing the type of installation, a menu is presented, and the user
can choose a profile for the installation.
Configure the network daemons
For booting the install client via PXE, the install server needs a DHCP and a
TFTP daemon running. The package fai-quickstart has already installed the
software packages for those daemons. Additionally the package of the NFS
server for exporting the nfsroot and the config space was installed.
Configuration of the DHCP daemon
Ideally, your faiserver should also be your DHCP server. If that is
not the case, instruct the admin responsible of the DHCP server to
configure it according to this section. Optionally, it is possible to
avoid that by using the
feature released in FAI 5.0.
An example for dhcpd.conf(5) is provided with the fai-doc
package. Start using this example and look at all options used therein.
# cp /usr/share/doc/fai-doc/examples/etc/dhcpd.conf /etc/dhcp/
The only FAI specific information inside this configuration file is to
set filename to fai/pxelinux.0 and to set next-server and
server-name to the name of your install server. All other
information is only network related data, which is used in almost all
DHCP configurations.
Adjust these network parameters to your local
deny unknown-
option dhcp-max-message-size 2048;
use-host-decl-
subnet 192.168.33.0 netmask 255.255.255.0 {
option routers 192.168.33.250;
option domain-name "my.example";
option domain-name-servers 192.168.33.250;
option time-
option ntp-
filename "fai/pxelinux.0";
If you make any changes to the DHCP configuration, you must
restart the daemon.
# invoke-rc.d isc-dhcp-server restart
If you have multiple network interfaces, you
can define on which interface the server will listen in
/etc/default/isc-dhcp-server. By default, the DHCP daemon writes its
log messages to /var/log/daemon.log.
Adding a host entry to DHCP
The MAC address is given by the hardware of the network card. For each
install client you collect its MAC address and to map it to an IP address and to a host
name. First, we add the IP address and the hostname to /etc/hosts
192.168.33.100
The mapping from the MAC address to the IP address is done in the
dhcpd.conf file. Here, we add a host entry using the command dhcp-edit(8).
Here you have to replace 01:02:03:AB:CD:EF ith the MAC you have found.
# dhcp-edit demohost 01:02:03:AB:CD:EF
After calling this command, this is what the host entry in
dhcpd.conf will look like:
host demohost {hardware ethernet 01:02:03:AB:CD:EF;fixed-}
Normally, you do not need any changes to the TFTP dameon
configuration. The files which are provided by TFTP are located in
/srv/tftp/fai.
The command fai-setup has already set up the NFS daemon add added
some lines to the configuration file /etc/exports.
It exports the directories using NFS v3.
Creating the PXELINUX configuration
The last step before booting your client for the first time
is to specify what configuration the client should boot when doing PXE
boot. We use the command fai-chboot(8) to create a pxelinux
configuration for each install client. This includes information about
the kernel, the initrd, the config space and some boot parameters. You
should read the manual page, which gives you some good examples.
Here’s the command for starting the installation for the host demohost.
$ fai-chboot -IFv -u nfs://faiserver/srv/fai/config demohost
Booting kernel vmlinuz-3.16.0-4-amd64
append initrd=initrd.img-3.16.0-4-amd64 ip=dhcp
FAI_FLAGS=verbose,sshd,createvt
FAI_CONFIG_SRC=nfs://faiserver/srv/fai/config
demohost has 192.168.33.100 in hex C0A82164
Writing file /srv/tftp/fai/pxelinux.cfg/C0A82164 for demohost
At this point, you should have a working faiserver setup and your clients should boot into FAI and be able to install one of the examples.
In the following section, you can read about planning your installation, tailoring your configuration space to your particular needs and extending FAI using hooks.
Custom server
The faiserver and its setup is by no means static. It is possible to customize and extend your server. For this, please refer to the
section in .
Plan your installation
Before starting your installation, you should invest a lot of time into
planning your installation. Once you’re happy with your installation
concept, FAI can do all the boring and repetitive tasks to turn your
plans into reality. FAI can’t do good installations if your concept is
imperfect or lacks some important details. Start planning the
installation by answering the following questions:
Will I create a Beowulf cluster, or do I
have to install some desktop machines?
What does my LAN topology look like?
Do I have uniform hardware?
Will the hardware stay uniform in the future?
Does the hardware need a special kernel?
How should the hosts be named?
How should the local hard disks be partitioned?
Which applications will be run by the users?
Do the users need a queuing system?
What software should be installed?
Which daemons should be started, and what
should the configuration for these look like?
Which remote file systems should be mounted?
How should backups be performed?
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.
But you need not start from scratch. Look at the files and scripts in
the configuration space. There are a lot of things you can use for
your own installation. A good paper called "Bootstrapping an
Infrastructure" with more aspects of building an infrastructure is
available at
The configuration space and its subdirectories
The configuration space is the collection of information about how exactly
to install a client. The central configuration space for all install
clients is located on the install server in /srv/fai/config and its
subdirectories. This will be mounted by the install clients to
/var/lib/fai/config. The main installation command fai(8) uses all
these subdirectories in the order listed except for hooks.
Scripts and files to
define classes and variables.
disk_config/
Configuration files for disk partitioning, software RAID, LVM and file system creation.
basefiles/
Normally the file base.tar.xz (located inside the nfsroot) is extracted on the install
client after the new file systems are created and before package are
installed. This is a minimal base image, created right after calling
debootstrap during the creation of the nfsroot on the install
server. If you want to install another distribution than the nfsroot
is, you can put a tar file into the subdirectory basefiles/ and name
it after a class. Then the command ftar(8) is used to extract the
tar file based on the classes defined. Thus the file has to be named CLASS.tar.xz not CLASS.base.tar.xz. This is done in task
extrbase. Use this if you want to install another distribution or
version than that running during the installation.
This basefile can also be received based on FAI classes via HTTP/HTPPS or FTP
by defining the variable FAI_BASEFILEURL. FAI will download a file
CLASSNAME.tar.xz (or tgz, or tar.gz,…) from this URL, if CLASSNAME
matches a FAI class.
FAI_BASEFILEURL=https://fai-project.org/download/basefiles
The folder must support directory listing. FAI will not probe for potentially matching files.
See chapter
for how to install different distributions.
This directory holds all debconf(7) data. The format is the same
that is used by debconf-set-selections(8).
package_config/
Files with class names contain lists of software packages to be
installed or removed by install_packages(8). Files named
&CLASS&.asc are added to the list of keys used by apt (using
apt-key(8)) for trusted package repositories.
Scripts for your local site customization. Used by fai-do-scripts(1).
Files used by customization scripts.
Most files are located in a
subtree structure which reflects the ordinary directory tree. For
example, the templates for nsswitch.conf are located in
$FAI/files/etc/nsswitch.conf and are named according to the classes
that they should match: $FAI/files/etc/nsswitch.conf/NIS is the
version of /etc/nsswitch.conf to use for the NIS class. Note that
the contents of the files directory are not automatically copied to
the target machine, rather they must be explicitly copied by
customization scripts using the fcopy(8) command.
Hooks are user defined programs or scripts, which are called during
the installation process. The can extend or replace the default tasks.
The file name must be of format taskname.CLASSNAME[.sh].
A hook called updatebase.DEBIAN is executed prior to the task updatebase
and only if the install client belongs to the class DEBIAN.
Defining classes
There are different possibilities to define classes:
Some default classes are defined for every host:
DEFAULT, LAST and its host name.
Classes may be listed within a file.
Classes may be dynamically defined by scripts.
The last option is a very nice feature, since these scripts will
define classes is a very flexible way. For example, several classes
may be defined only if certain hardware is identified or a class is
defined depending on the network subnet information.
All names of classes, except the host name, are written in
uppercase. They must not contain a hyphen, a hash, a semicolon or a
dot, but may contain underscores and digits.
The task defclass calls the command fai-class(1) to define
classes. All scripts matching ^[0-9][0-9]* (they start with two
digits) in the subdirectory
$FAI/class are executed for defining classes. Everything that is printed
to STDOUT is automatically defined as a class. For more
information on defining class, read the manual pages for
fai-class(1). The script 50-host-classes (see below a stripped
version) is used to define classes depending on the host name.
# use a list of classes for our demo machines
case $HOSTNAME in
echo "FAIBASE GRUB DHCPC DEMO" ;;
echo "FAIBASE GRUB DHCPC DEMO XORG XFCE";;
faiserver)
echo "FAIBASE DEBIAN DHCPC DEMO FAISERVER" ;;
echo "FAIBASE GRUB DHCPC" ;;
Host names 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 can be shared among several
The order of the classes is important because it defines the priority
of the classes from low to high.
Defining variables
The task defvar defines the variables for the install
client. Variables are defined by scripts in class/*.var. All global
variables can be set in DEFAULT.var. For certain groups of hosts use
a class file or for a single host use the file $HOSTNAME .var. Also
here, it’s useful to study all the examples.
The following variables are used in the examples and may also be
useful for your installation:
FAI_ACTION
Set the action FAI should perform. Normally this is done by
fai-chboot(8). If you can’t use this command, define this variable
i.e. in the script LAST.var.
FAI_ALLOW_UNSIGNED
If set to 1, FAI allows the installation of packages from unsigned
repositories.
CONSOLEFONT
Is the font which is loaded during installation by setfont(8).
Defines the keyboard map files in /usr/share/keymaps and
$FAI/files. You need not specify the full path, since this file
will be located automatically.
The encrypted root password for the new system. You can use
crypt(3), md5 and other hash types for the password. Use
mkpasswd(1) for creating the hash for a certain password.
For example, to generate a md5 hash for the password use
$ echo "yoursecrectpassword" | mkpasswd -Hmd5 -s
Set hardware clock to UTC if UTC=yes. Otherwise set clock to local
time. See clock(8) for more information.
Is the file relative to /usr/share/zoneinfo/ which indicates your
time zone. E.g.: TIMEZONE=Europe/Berlin.
MODULESLIST
A list of kernel modules which are loaded during boot of the new system (written to
/etc/modules).
Hard disk configuration
The tool setup-storage(8) reads a file in $FAI/disk_config for the
disk configuration. This file describes how
all the local disks will be partitioned, which file systems types should be
created (like ext3/4, xfs, btrfs), and where they are
mounted to. You can also create software RAID and LVM setups using this
config file. It’s also possible to preserve the disk layout or to
preserve the data on certain partitions.
During the installation process all local file systems are mounted
relative to /target. For example if you specify the mount point
/home in a disk configuration file this will be the directory
/target/home during the installation process und will become /home
for the new installed system.
Extract base file
Debconf preseeding
Access to the package repository
Software package configuration
Before installing packages, FAI will add the content of all files
named package_config/class.asc to the list of apt keys. If your local
repository is signed by your keyid AB12CD34 you can easily add this key,
so FAI will use it during installation. Use this command for creating
the CLASS.asc file:
faiserver$ gpg -a --export AB12CD34 & /srv/fai/config/package_config/MYCLASS.asc
The script install_packages(8) installs the selected software
packages. It reads all configuration files in $FAI/package_config
whose file name matches a defined class. The syntax is very simple.
# an example package class
PACKAGES taskinst
PACKAGES aptitude
adduser netstd ae
less passwd
PACKAGES remove
PACKAGES aptitude GRUB
lilo- grub
Comments are starting with a hash (#) and are ending at the end of the
line. Every package command begins with the word PACKAGES followed by a
command name, which maps to a different package tool like apt-get,
aptitude or yum for e.g. The command defines which command will be used to
install the packages named after this command. The list of all
available commands can be listed using install_packages -H.
Supported package tools are: aptitude, apt-get, smart, yast,
yum, rpm, zypper
Put a package on hold. This package will not be handled by dpkg, e.g
not upgraded.
Install all packages (using apt-get) 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.
install-norec
Like install but without installing the recommended packages.
Remove all packages that are specified in the following lines. Append
a + to the package name if the package should be installed.
Install all packages belonging to the tasks that are specified in the
following lines using tasksel(1). You can also use aptitude for
installing tasks.
Install all packages with the command aptitude. This will be the
default in the future and may replace apt-get and taskinst. Aptitude
can also install task packages.
aptitude-r
Same as aptitude with option --with-recommends.
Download package and unpack only. Do not configure the package.
dselect-upgrade
Set package selections using the following lines and install or remove
the packages specified. These lines are the output of the command
dpkg --get-selections. It’s not recommended to use this format,
since you are also specifying all packages which are only installed
because of a dependency or a recommends. It’s better just to specify
the pacakge you like to have, and to let FAI (and apt-get) resolv the
dependencies.
Multiple lines with lists of space separated names of packages follow
the PACKAGES lines. All dependencies are resolved. Packages with
suffix - (eg. lilo-) will be removed instead of installed. The
order of the packages is of no matter.
If you like to install
packages from another release than the default, you can append the
release name to the package name like in
openoffice.org/etch-backports. You can also specify a certain
version like apt=0.3.1. More information on these features are
described in aptitude(8).
A line which contains the PRELOADRM commands, downloads a file using
wget(1) into a directory before installing the packages. Using the
file: URL, this file is copied from $FAI_ROOT to the download
directory.
For example the package realplayer needs an archive to
install the software, so this archive is downloaded to the directory
/root. After installing the packages this file will be removed. If
the file shouldn’t be removed, use the command PRELOAD instead.
It’s possible to append a list of class names after the command for
apt-get. So this PACKAGE command will only be executed when the
corresponding class is defined. So you can combine many small files
into the file DEFAULT. WARNING! Use this feature only in the file
DEFAULT to keep everything simple. See this file for some examples.
If you want to remove a package name from a certain class was part of
this class before, you should not remove the package name from the
class file, but instead append a dash (-) to it. This will make sure
that the package is remove during a softupdate on hosts which were
installed using the old class definition which included this package
If you specify a package that does not exist this package will be
removed automatically from the installation list only if the command install is used.
Customization scripts
The command fai-do-scripts(1) is called to execute all scripts in
this directory. If a directory with a class name exists, all scripts
matching ^[0-9][0-9]* are executed in alphabetical order. So it’s
possible to use scripts of different languages (shell, cfengine,
Perl, Python, Ruby, expect,..) for one class.
Thoses scripts write their output to different log files, depending on
the type of script. For e.g. all shell scripts write their log to
shell.log.
Shell scripts
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 use the ifclass command for testing if certain classes
are defined.
ifclass -o A B C
checks if one of classes A, B or C are defined. Using -a (logical
AND) checks if all classes of a list are defined. The command ifclass
C checks if only class C is defined.
For copying files with classes, use the command
fcopy(8). If you want to extract an archive using classes, use
ftar(8). For appending lines to a configuration file use ainsl(1)
instead of just echo string && filename.
FAI also supports zsh(1) scripts during the
customization task. Within scripts, the variable $classes holds a space
separated list with the names of all defined classes.
Cfengine scripts
CFEngine has a rich set of functions to edit existing configuration
files, e.g LocateLineMatching, ReplaceAll, InsertLine,
AppendIfNoSuchLine, HashCommentLinesContaining. But it can’t handle
variables which are undefined. If a variable is undefined, the whole
cfengine script will abort.
More information can be found in the manual page cfengine(8) or at
the cfengine homepage .
Hooks let you specify functions or programs which are run at certain
steps of the installation process. Before a 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 several
hooks for a task exists, they are called in the order defined by the
If debug is included in $FAI_FLAG the option -d is
passed to all hooks, so you can debug your own hooks.
If some default
tasks should be skipped, use the subroutine skiptask and a list of
default tasks as parameters. In the examples provided, the hooks of
the class CENTOS skips some Debian specific tasks.
The directory $FAI/hooks/ contains all hooks. A hook is an executable
file following the naming scheme taskname.CLASSNAME[.sh] (e.g.
repository.CENTOS or savelog.LAST.sh), a task name and a
class name separated by a dot, optionally followed by '.sh. The
task name specifies which task to precede executing this hook, if the
specified class is defined for the installing client.
See section
for a complete list of default tasks that can be used.
A hook of the form hookprefix.classname 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 .sh (e.g. 'partition.DEFAULT.sh) must be Bourne
shell scripts and are sourced. So it’s possible to redefine variables
for the installation scripts.
In the first part of FAI, all hooks with prefix confdir are called.
Those hooks can not be located in the config space, since it’s not yet
available. Therefore these hooks are the only hooks located in
$nfsroot/$FAI/hooks on the install server. All other hooks are
found in $FAI_CONFIGDIR/hooks on the install server.
All hooks that are called before classes are defined can only use the
following classes: DEFAULT $HOSTNAME LAST. If a hook for class
DEFAULT should only be called if no hook for class $HOSTNAME is
available, insert these lines to the default hook:
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
Some examples for what hooks could be used:
Load kernel modules before classes are defined in $FAI/class.
Send an email to the administrator if the installation is finished.
Install a diskless client and skip local disk partitioning.
Have a look at hooks/debconf.IMAGE for how to clone a machine using a file system image.
The variable $FAI_FLAGS contains a space separated list of
flags. The following flags are known:
Create verbose output during installation. This should always be the
first flag, so consecutive definitions of flags will be verbosely
displayed.
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. A lot of debug
information will be printed out. This flag is only useful for FAI
developers.
Start the ssh daemon to enable remote logins.
You can then log in as root to all install clients during the
installation. The default password is fai and can be changed by
setting FAI_ROOTPW in nfsroot.conf(5). To log in from your server
to the install client (named demohost in this example) use:
$ ssh root@demohost
Warning: Permanently added 'demohost,192.168.33.100' to the list of known hosts.
root@demohost's password:
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 $SSH_IDENTITY.
Create two virtual terminals and execute a bash if ctrl-c is typed
in the console terminal. The additional terminals can be accessed by
typing Alt-F2 or Alt-F3. Otherwise, no terminals are available and
typing ctrl-c 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.
This enables a user menu for selecting a profile. All files
class/*.profile are read and a curses based menu will be created.
Reboot the install client after installation is finished without
typing RETURN on the console. If this flag is not set, and error.log
contains anything, the install client will stop and wait that you
press RETURN. If no errors occurred, the client will always reboot
automatically.
Halt the install client at the end of the installation, instead of
rebooting into the new system.
Used by setup-storage(8). Partitions marked with preserve_reinstall
are preserved unless this flag is set. Often, this flag is set in a
file class/*.var by using setting flag_initial=1.
FAI installs your plan
The early part of an installation
After the kernel has booted, it mounts the root file system via NFS
from the install server and starts the script
/usr/sbin/fai . This script controls the sequence of the
installation. No other scripts in /etc/init.d/ are used.
The configuration space is made available via the configured method
(an NFS mount by default) from the install server to the path defined
Boot messages
When booting the install client from network card with PXE you will some
messages like this:
Managed PC Boot Agent (MBA) v4.00
Pre-boot eXecution Environment (PXE) v2.00
DHCP MAC ADDR: 00 A2 A3 04 05 06
CLIENT MAC ADDR: 00 A2 A3 04 05 06
GUID: 3D6C4552
CLIENT IP: 192.168.33.100 MASK: 255.255.255.0
DHCP IP: 192.168.33.250
GATEWAY IP: 192.168.33.1
!PXE entry point found (we hope) at
via plan A
UNDI code segment at: 9854 len 5260
UNDI data segment at: 921D len 63A2
Getting cached packet
My Ip address seems to be C0A8.33.100
ip=192.168.33.100:192.168.33.250:192.168.33.1:255.255.255.0
BOOTIF=01-00-A2-A3-04-05-06
TFTP prefix: fai/
Trying to load pxelinux.cfg/C0A82164
Loading vmlinuz-4.9.0-3-amd64..................
Loading initrd.img-4.9.0-3-amd64......................ready.
At this point the install client has successfully received the network
config via DHCP and the kernel and initrd via TFTP. It now boots the
Linux kernel and the initrd. If everything went right, the initrd
mounts the nfsroot
and the FAI scripts are started. The first
thing you see is the red FAI copyright message.
-------------------------------------------------
Fully Automatic Installation
Thomas Lange
&lange@informatik.uni-koeln.de&
-------------------------------------------------
Calling task_confdir
Kernel currently running: Linux 4.9.0-3-amd64 x86_64 GNU/Linux
Kernel parameters: BOOT_IMAGE=vmlinuz-4.9.0-3-amd64 initrd=initrd.img-4.9.0-3-amd64 \
rw rootovl ip=dhcp root=192.168.33.250:/srv/fai/nfsroot FAI_FLAGS=verbose,sshd,createvt \
FAI_CONFIG_SRC=nfs://faiserver/srv/fai/config FAI_ACTION=install
Reading /tmp/fai/boot.log
FAI_FLAGS: verbose sshd createvt
Setting SERVER=faiserver. Value extracted from FAI_CONFIG_SRC.
FAI_CONFIG_SRC is set to nfs://faiserver/srv/fai/config
Configuration space faiserver:/srv/fai/config mounted to /var/lib/fai/config
Source hook: setup.DEFAULT.sh
setup.DEFAULT.sh
Calling task_setup
FAI_FLAGS: verbose sshd createvt
15 Sep 13:22:37 ntpdate[1533]: step time server 192.168.33.250 offset -0.342793 sec
Press ctrl-c to interrupt FAI and to get a shell
Starting FAI execution - 237
Calling task_defclass
fai-class: Defining classes.
Executing /var/lib/fai/config/class/01-short-hostname.sh.
01-short-hostname.sh OK.
Executing /var/lib/fai/config/class/10-base-classes.
10-base-classes
Executing /var/lib/fai/config/class/20-hwdetect.source.
Loading kernel module md-mod
20-hwdetect.source
Executing /var/lib/fai/config/class/50-host-classes.
50-host-classes
List of all classes: DEFAULT LINUX AMD64 FAIBASE DHCPC DEMO GRUB client01 LAST
You can also see the list of FAI classes, that are defined for this
host. This list is very important for the rest of the installation.
The first task is called confdir, which is responsible for getting
access to the config space. Here, we use an NFS mount from the install
server as you can see on the console (and later in the logs).
FAI_CONFIG_SRC is set to nfs://faiserver/srv/fai/config
Configuration space faiserver:/srv/fai/config mounted to /var/lib/fai/config
Before the installation is started ($FAI_ACTION=install) the computer
beeps three times. So, be careful when you hear three beeps but you do
not want to perform an installation and let FAI erase all yout data on
the local disk!
Rebooting the computer into the new system
For rebooting the computer during or at the end of the installation you
should use the command faireboot in favour of the normal reboot command.
Use faireboot also if logged in from remote. If the installation
hasn’t finished, use faireboot -s, so the log files are also copied
to the install server.
If the installation has finished successfully, the computer should boot a
small Debian system. You can login as user demo or root with password fai.
Starting FAI (task confdir)
After the install client has booted only the script /usr/sbin/fai is
executed. It will do some minimal initialization. The variable
$FAI_CONFIG_SRC
is used to get access to the FAI configuration space which is then
available in the directory $FAI . FAI
will not proceed without the config space.
Defining classes and variables (tasks defclass and defvar)
The command fai-class(1) executes scripts in $FAI/class for defining
classes. If the scripts write a string to stdout, this will be defined
as a class. Read all the details in the man page of fai-class(1).
After defining the classes, every file matching .var with a prefix
which matches a defined class is sourced to define variables. It must
contain vaild shell code.
Partitioning local disks, creating file systems (task partition)
For the disk partitioning exactly one disk configuration file from
$FAI/disk_config is selected using classes.
The format of the disk configuration is similar to a fstab file.
The partitioning tool setup-storage(8) performs all commands
necessary for creating the disk partition layout, software RAID, LVM
and for creating the file systems. Read the manual page of
setup-storage(8) for a detailed description and some examples of the
Debconf preseeding (task debconf)
Files in $FAI/debconf are used for the usual debconf(7) presseding
if the file names match a class name.
Installing software packages (task instsoft)
The command install_packages(8) reads the config files from
$FAI/package_config in a class based manner and installs software
packages on the new file system.
It installs the packages using apt-get(8), aptitude(1), yum or other
package tools without any manual interaction needed. Package
dependecies are also resolved by the package tools.
The format of the configuration files is described in .
Site specific customization (task configure)
Often the default configurations of the software packages will not
meet your site-specific needs. You can call arbitrary scripts which
adjust the system configuration. Therefore the command
fai-do-scripts(1) executes scripts in $FAI/scripts in a class
based manner. It is possible to have several scripts of different
types (shell, cfengine, …) to be executed for one class.
The default set of scripts in $FAI/scripts include examples for
installing Debian and CentOS machines. They set the root password, add
a demo user account, set the timezone, configure the network for DHCP
or using a fixed IP address, setup grub and more.
They should do a reasonable job for your installation. You can edit
them or add new scripts to match your local needs.
More information about these scripts are described in .
Saving log files (task savelog)
When all tasks are finished, the log files are written to
/var/log/fai/$HOSTNAME/install/
on the new system and to the account on the install server
if $LOGUSER is defined. It is also possible to specify
another host as log saving destination through the variable
$LOGSERVER. If $LOGSERVER is not defined, FAI uses the variable
$SERVER which is only defined during an initial installation (by
get-boot-info). Make sure to set $LOGSERVER in a class/*.var script
if you are using the action softupdate.
Additionally, two symlinks will be created to indicated the last
directory written to. The symlink last points to the log directory
of the last FAI action performed. The symlinks last-install and
last-sysinfo point to the directory with of the last corresponding
action. By default log files will be copied to the log
server using scp. You can use the variable $FAI_LOGPROTO in file
fai.conf(5) to choose another method for saving logs to the remote
server. Here’s an example of the symlink structure:
lrwxrwxrwx
2013 last-sysinfo -& sysinfo-237
drwxr-xr-x
2 fai fai 4096 Dec
2013 sysinfo-237
drwxr-xr-x
2 fai fai 4096 Feb 14
2014 install-150
drwxr-xr-x
2 fai fai 4096 Dec
2 11:47 install-918
lrwxrwxrwx
4 13:22 last-install -& install-351
lrwxrwxrwx
4 13:22 last -& install-351
drwxr-xr-x
2 fai fai 4096 Dec
4 13:22 install-351
Examples of the log files can be found at .
Reboot the new installed system
Before rebooting, the install client calls fai-chboot -d &hostname&
on the install server, to disable its own PXELINUX
configuration. Otherwise, it would restart the installation during the
next boot. Normally this should boot the new installed system from
its second boot device, the local hard disk.
At the end, the system is automatically rebooted if "reboot" was added to
$FAI_FLAGS.
Advanced FAI topics
Checking parameters received from DHCP servers
If the install client boots you can check
if all information from the DHCP daemon are received
correctly. The received information is written to
/tmp/fai/boot.log. An example of the result of a DHCP request can be
found in the sample log files.
Monitoring multiple client installations
You can monitor the installation of all install clients with the
command fai-monitor(8). All clients check if this daemon is running
on the install server (or the machine defined by the variable
$monserver). Each time a task starts or ends, a message is sent. The
FAI monitor daemon prints this messages to standard output. There’s
also a graphical frontend available, called fai-monitor-gui(1).
fai-monitor | fai-monitor-gui - &
Collecting Ethernet addresses for multiple hosts
You have to collect all Ethernet (MAC) addresses of the install
clients and assign a host name and IP address to each client. To
collect the MAC addresses, boot your install clients.
You can already do this before any DHCP daemon is running in your
subnet. They will fail to boot (because of the missing DHCP or missing TFTP),
but you can still collect the MAC addresses.
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:
faiserver# tcpdump -qtel broadcast and port bootpc &/tmp/mac.list
After the hosts have been sent some broadcast packets abort tcpdump
by typing ctrl-c. You get a list of all
unique MAC addresses with these commands:
faiserver$ perl -ane 'print "\U$F[0]\n"' /tmp/mac.list|sort|uniq
After that, you only have to assign these MAC addresses to host names
and IP addresses (/etc/ethers and /etc/hosts or corresponding NIS
maps). With this information you can configure your DHCP
daemon (see the section ).
Debugging the network traffic
If the client can’t successfully boot from the network card, use
tcpdump(8) to look for Ethernet packets between the install server
and the client. Search also for entries in several log files made by
tftpd(8) and dhcpd(8) :
faiserver$ egrep "tftpd|dhcpd" /var/log/*
Details of PXE booting
Here we describe the details of PXE booting, which are only needed if
you have problems when booting your install clients.
Almost all modern bootable network cards support the PXE boot environment.
PXE is the Preboot Execution Environment.
This requires the PXELINUX bootloader and a special version of the TFTP
daemon, which is available in the Debian packages pxelinux and
tftpd-hpa. PXE booting also needs a DHCP server, so that the network
card can configure its IP parameters. This is the sequence of a PXE boot:
Network card of the client sends its MAC address
DHCP server replies with IP configuration for the client
Network card configures IP
Install client gets the pxelinux.0 binary via TFTP
Get the pxelinux.cfg/C0A8210C configuration file via TFTP
C0A8210C is the IP address of the client in hexadecimal
This configuration contains kernel, initrd and additional kernel
command line parameters, which was created by fai-chboot.
Get the kernel and initrd via TFTP.
Example of a pxelinux.cfg file:
default fai-generated
label fai-generated
kernel vmlinuz-3.16.0-4-amd64
append initrd=initrd.img-3.16.0-4-amd64 ip=dhcp
root=/srv/fai/nfsroot aufs
FAI_FLAGS=verbose,sshd,createvt FAI_CONFIG_SRC=nfs://faiserver/srv/fai/config FAI_ACTION=install
See /usr/share/doc/syslinux/pxelinux.doc for more detailed
information about PXELINUX. There’s a new lpxelinux binary which also
support loading the kernel and initrd via FTP or HTTP. The command
fai-chboot(8) supports this with the option -U.
Customizing your install server setup
local/faster package mirror
different loguser
local root pw inside nfsroot
The configuration for the FAI package (not the configuration data for
the install clients) is defined in fai.conf(5). Definitions that are
only used for creating the nfsroot are located in
nfsroot.conf(5). Check these important variables in nfsroot.conf
before calling fai-setup or fai-make-nfsroot.
FAI_DEBOOTSTRAP
Building the nfsroot uses the command debootstrap(8)`. It needs the location of a Debian mirror and the
name of the distribution (wheezy, jessie, stretch, sid) for which the basic Debian
system should be built. Do not use different distributions here and in
/etc/fai/apt/sources.list. This will create a broken nfsroot.
NFSROOT_ETC_HOSTS
This variable is only needed if the clients do not have access to a DNS server.
This multiline variable is added to /etc/hosts inside the
nfsroot. Then the install clients can access those hosts by name
without using DNS.
The content of /etc/fai/apt/sources.list is
used by the install server and also by the clients. If your install
server has multiple network cards and different host names for each
card (as for a Beowulf server), use the install server name which is
known by the install clients.
If you have problems running fai-setup, they usually stem from
fai-make-nfsroot(8) which is called by former command. Adding -v
gives you a more verbose output which helps you pinpoint the
error. The output is written to
/var/log/fai/fai-make-nfsroot.log.
The setup also creates the account fai (defined by $LOGUSER) if
not already available. So you can add a user before calling
fai-setup(8) using the command adduser(8) and use this as your
local account for saving log files. The log files of all install
clients are saved to the home directory of this account. You should
change the primary group of this
account, so this account has write permissions to /srv/tftp/fai in
order to call fai-chboot for creating the PXE configuration for the hosts.
When you make changes to fai.conf, nfsroot.conf the
nfsroot has to be rebuilt by calling fai-make-nfsroot(8). If you
only like to install a new kernel package to the nfsroot add the flags -k or
-K to fai-make-nfsroot. This will not recreate your nfsroot, but
only updates your kernel and kernel modules inside the nfsroot or add
additional packages into the nfsroot.
Creating a FAI CD or and USB stick
You can easily create an installation CD (or USB stick) of your
network installation setup. This will perform the same installation
and configuration from CD without the need of the install server.
Therefore you need to create a partitial mirror of all Debian packages
needed for your FAI classes (using fai-mirror(1)). Then the command
fai-cd(8) will put this mirror, the nfsroot and the config space
onto a bootable CD. That’s it!
This installation CD contains all data needed for the
installation. The command fai-cd(8) puts the nfsroot, the
configuration space and a subset of the Debian mirror onto a
CD-ROM. A partial package mirror is created using the command
fai-mirror(1) which contains all packages that are used by the
classes used in your configuration space.
A sample ISO image is
available at .
Using the command dd(1) you can also create a bootable USB
stick by just writing the content of the ISO file to your USB stick
(here the stick is /dev/sdf).
faiserver# dd if=fai-cd.iso of=/dev/sdf bs=1M
This is no live CD of the install server.
Creating VM disk images using FAI
The command fai-diskimage(8) creates disk
images, which can be used with a virtual machine like KVM, VMware,
VirtualBox or a cloud service like OpenStack, GCE, EC2 and others. The
installation process performs the normal FAI tasks on a raw disk
image. After the installation you can boot the disk image and have a
running system. The disk image can also be converted to qcow2 format.
You do not need to setup the FAI nfsroot when only using
fai-diskimage. But you need a basefile in your configuration
space. Setting the variable $FAI_BASEFILEURL will automatically
download an appropriate base file into your config space.
Here’s an example how to create a raw disk image for a host called
cloud3, with a small set of software packages:
# export FAI_BASEFILEURL=https://fai-project.org/download/basefiles/
# fai-diskimage -vu cloud3 -S2G -cDEBIAN,STRETCH64,AMD64,FAIBASE,GRUB_PC,DHCPC,CLOUD disk.raw
This command will create a disk image called ubuntu.qcow2 for a Ubuntu 16.04 desktop
with hostname set to foobar.
# export FAI_BASEFILEURL=https://fai-project.org/download/basefiles/
# cl=DHCPC,UBUNTU,XENIAL,XENIAL64,AMD64,XORG
# fai-diskimage -Nvu foobar -S5G -c$cl ubuntu.qcow2
Building cross-architecture disk images
Starting FAI 5.4 it’s now possible to build a disk image for
different architectures than the host is running. For example you can
build an image for 64-bit ARM architecture (aarch64) on a host running on amd64
architecture. Here are the steps do to:
# apt install qemu-system-arm qemu-user-static fai-server fai-setup-storage fai-doc qemu-utils
# fai-mk-configspace
# export FAI_BASEFILEURL=https://fai-project.org/download/basefiles/
# fai-diskimage -vu armhost -S2G -cDEFAULT,DHCPC,DEBIAN,ARM64,STRETCH_ARM64,FAIBASE,DEMO,CLOUD,LAST arm64.raw
# chown your_user_id arm64.raw
# cp /var/log/fai/armhost/last/vmlinuz* vmlinuz
# cp /var/log/fai/armhost/last/initrd.img* initrd
Then you can run qemu as a normal user:
& qemu-system-aarch64 -m 1000 -M virt,gic_version=3 -cpu cortex-a57 -drive file=arm64.raw,if=virtio,index=1 -no-reboot -nographic -name ARM64 -kernel vmlinuz -initrd initrd -append "console=ttyAMA0 rw ip=dhcp root=/dev/vda1 net.ifnames=0"
Keep in mind, that this qemu network setup will have poor
performance. Use tap devices for much better performance.
This works similar for other architectures.
You can find the base files for many architectures at
, or use mk-basefile to
create your own.
If you set the variable $FAI_ACTION to sysinfo (for e.g. by using
fai-chboot -S), the client will not install a new system, but will
collect a lot of system information.
If you set $FAI_ACTION to inventory you will only get a few
hardware information.
Both actions can be used for FAI as a rescue system.
Type ctrl-c to get a shell or use Alt-F2 or Alt-F3 and you will get
another console terminal, if you have added createvt to $FAI_FLAGS.
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
/tmp/fai. There you can find much information about the boot
FAI mounts all file systems it finds on the local disks read only. It
also tells you on which partition a file /etc/fstab exists. When
only one file system table is found, the partitions are mounted
according to this information. Here’s an example:
demohost:~# df
Filesystem
Used Available Use% Mounted on
192.168.33.250:/srv/fai/nfsroot
% /live/image
2% /live/cow
192.168.33.250:/srv/fai/config
% /var/lib/fai/config
4% /target/home
4% /target/tmp
% /target/usr
% /target/var
This method can be used as a rescue environment! If you need a file
system with read-write access use the rwmount command:
demohost# rwmount /target/home
FAI without NFS
To boot into FAI and begin the installation sequence
without using the NFS protocol, you boot the client machine using PXE as
usual and then retrieve an image containing the nfsroot via http.
To create an image, use fai-cd’s -S argument and -M to avoid setting up
a partial mirror within the image.
faiserver# fai-cd -M -S squash.img
Move this image to a directory from which it can be requested via http
(usually a directory ser