Installing Ubuntu Linux with FAI: Difference between revisions

From FAIWiki
Jump to navigation Jump to search
(add documentation for new ubuntu/multi-distribution packages)
(add warning)
 
(24 intermediate revisions by 6 users not shown)
Line 1: Line 1:
The newest and hottest way to install Ubuntu Linux with FAI:
'''WARNING: Since newer FAI versions now must use dracut instead of initramfs-tools, you cannot create a Ubuntu nfsroot any more. You can still install Ubuntu using a Debian nfsroot on an Ubuntu server. But it's not possible to create a Ubuntu nfsroot at all.'''


get all the debs from here: http://www.sprang.de/download/fai-multi-distribution/


usage:
* install the deb's from the download location, including the package fai-distributions (look into it to see what it is about)
* do everything you'd do with any other FAI install - read this wiki on how to do that.
* copy example classes as usual in FAI
* copy additional example classes:
cp -a /usr/share/doc/fai-doc/examples/classes/*/* /usr/local/share/fai/
* run make-fai-nfsroot
* run /usr/lib/fai/dists/ubuntu_hoary/make-base-tgz ( in lib because it should be called from make-fai-nfsroot)
* run /usr/lib/fai/dists/ubuntu_breezy/make-base-tgz
* name your install clients sarge, hoary, and breezy in DNS , or add them to the same classes as these example host configurations and install them as usual


It only needs one nfsroot for all.
This tutorial will:


* Install FAI 4.2.4 on an Ubuntu 14.04 (64-Bit) 'Trusty Tahr' server
* in order to be able to install clients with Ubuntu 14.04 (64-Bit) using a 14.04 NFSroot
* with the option to install other architectures (32-Bit), versions (Ubuntu 14.10, Ubuntu 12.04) and basically any other debian-based distribution '''using a single NFSroot'''.


=== notes: ===
If you are looking to Install Ubuntu 12.04 LTS with the FAI 3.4.8 packages from the Ubuntu repositories, look here: [[Installing Ubuntu 12.04 with FAI 3.4.8]].
* there's also another howto to install Ubuntu with FAI (I didn't try it yet): http://www.hpc2n.umu.se/support/showdoc.html?txt=admin/fai/ubuntu


* make-fai-nfsroot needs the package kudzu. This is not available under ubuntu.
=Introduction=
** I had to disable it in /usr/sbin/make-fai-nfsroot
You need the following prerequisites in your network:
** kudzu is available (in hoary) in universe/utils
 
* Working DNS and DHCP infrastructure (plus DHCP configured to point to your TFTP server)
* Ubuntu 14.04 (64-bit) on the FAI server
* Basic understanding of FAI (class concept, configuration space, ...)
* Adequate knowledge on the workings of DNS, DHCP, PXE and TFTP.
 
Just for your information, on this page, the following conventions are used:
* FAI server: faiserver.example.com, 192.168.0.10
* FAI client: faiclient.example.com
 
=Setting up the FAI server=
==Installing FAI==
In order to get the latest FAI packages, add the FAI repository to the Ubuntu installation. Open this file:
<pre>
vi /etc/apt/sources.list.d/fai.list
</pre>
and add this line to the empty file:
<pre>
deb http://fai-project.org/download wheezy koeln
</pre>
 
Import the GPG key of the FAI repository. If you get error messages about a wrong URI of the key server, try to run this command a second time:
<pre>
gpg -a --recv-keys 074BCDE4; gpg -a --export 074BCDE4 | apt-key add -
</pre>
 
Update the package lists and install FAI:
<pre>
apt-get update
apt-get upgrade
apt-get install fai-quickstart
</pre>
''Note'': 'fai-quickstart' will install not only FAI-related packages but additional packages like DHCP and TFTP as well. If they are already present on your infrastructure, the following alternative packages will suffice:
<pre>
apt-get install fai-server fai-doc
</pre>
==Setting up FAI==
First and foremost FAI needs to be configured. Open the ''fai.conf'' file:
<pre>
vi /etc/fai/fai.conf
</pre>
and make sure it looks like this:
<pre>
# See fai.conf(5) for detailed information.
 
# Account for saving log files and calling fai-chboot.
#LOGUSER=fai
 
SERVER=faiserver.example.com
 
# URL to access the fai config space
#FAI_CONFIG_SRC=nfs://yourservername/path/to/config/space
FAI_CONFIG_SRC=nfs://$SERVER/srv/fai/config
 
# Sending FAI install logfiles from the install client to the
# FAI server
LOGUSER=fai
LOGSERVER=$SERVER
FAI_LOGPROTO=ssh
</pre>
 
The next important step is to configure the NFSroot. Open the ''nfsroot.conf'':
<pre>
vi /etc/fai/nfsroot.conf
</pre>
and edit it like this:
<pre>
# For a detailed description see nfsroot.conf(5)
 
# "<suite> <mirror>" for debootstrap
FAI_DEBOOTSTRAP="trusty http://archive.ubuntu.com/ubuntu"
FAI_ROOTPW='$1$kBnWcO.E$djxB128U7dMkrltJHPf6d1'
 
NFSROOT=/srv/fai/nfsroot
TFTPROOT=/srv/tftp/fai
NFSROOT_HOOKS=/etc/fai/nfsroot-hooks/
FAI_DEBOOTSTRAP_OPTS="--exclude=info --include=aptitude"
 
# Configuration space
FAI_CONFIGDIR=/srv/fai/config
</pre>
 
As FAI traditionally is Debian-centric, some additional modifications to the NFSroot packages are required.
First, FAI nowadays uses the modern ''dracut'' in the NFSroot by default. Due to package dependencies the usage of dracut on Ubuntu will not work easily and would likely break the system. Solution: Use the good old ''live-boot'' instead.
Second, the Linux kernel has a different package name on Ubuntu as opposed to Debian.
Third, the mentioned network card firmware just exists on Debian.
Open this file:
<pre>
vi /etc/fai/NFSROOT
</pre>
and edit it like this:
<pre>
# package list for creating the NFSROOT
 
PACKAGES aptitude
 
#sysvinit-core # use this for booting jessie without systemd
 
nfs-common fai-nfsroot module-init-tools ssh rdate lshw rpcbind
rsync lftp less dump reiserfsprogs e2fsprogs usbutils
hwinfo psmisc pciutils hdparm smartmontools parted mdadm lvm2
dnsutils ntpdate dosfstools xfsprogs xfsdump
procinfo numactl dialog
console-common kbd
iproute moreutils udev subversion
xz-utils
cupt
pxelinux syslinux-common # in jessie we need both
 
# some network cards needs firmware
#firmware-bnx2 firmware-bnx2x firmware-realtek
#firmware-linux-nonfree
 
# dracut can replace live-boot
#dracut-network live-boot- live-boot-initramfs-tools-
 
# choose if you like live-boot or dracut inside the nfsroot
#live-boot live-boot-doc
 
# you should not edit the lines below
# architecture dependend list of packages that are installed
 
#git # git consumes a lot of disk space on the FAI CD (ISO 9660)
 
PACKAGES aptitude I386
grub-pc
#linux-image-686
 
# packages for Ubuntu natty/oneiric/precise:
linux-image-generic live-boot
 
PACKAGES aptitude AMD64
grub-pc
#linux-image-amd64
 
# packages for Ubuntu natty/oneiric/precise:
linux-image-generic live-boot
</pre>
 
And finally, FAI has to be told to get the packages from the correct repositories to build the NFSroot from. Open this file:
<pre>
vi /etc/fai/apt/sources.list
</pre>
and replace the existing contents with the following lines:
<pre>
# Using the Ubuntu repositories
deb http://archive.ubuntu.com/ubuntu/ trusty main restricted universe multiverse
deb http://archive.ubuntu.com/ubuntu/ trusty-updates main restricted universe multiverse
deb http://archive.ubuntu.com/ubuntu/ trusty-backports main restricted universe multiverse
 
deb http://security.ubuntu.com/ubuntu trusty-security main restricted universe multiverse
 
deb http://extras.ubuntu.com/ubuntu trusty main
 
# FAI repository to get the most up-to-date FAI packages on the install clients
deb http://fai-project.org/download wheezy koeln
</pre>
 
If you are installing '''Vivid''' or later you need to go back to upstart, as systemd is currently not supported by FAI.
Add a file with the following content to /etc/fai/nfsroot-hooks/ and make it executable:
<pre>
#!/bin/sh
$ROOTCMD apt-get install upstart
# If rcS.conf is not removed, FAI will be started twice.
$ROOTCMD rm /etc/init/rcS.conf
</pre>
 
 
 
==Creating the NFSroot==
Set up FAI:
<pre>
fai-setup -vl
</pre>
* '''-v''' enables verbose output of the above command - recommended!
* '''-l''' is passed to ''fai-make-nfsroot'' makes it use 'live-boot'' instead of ''dracut'', which is not supported by ubuntu.
Go get yourself a nice cup of coffee, as this will take some time.
 
The above commands create the necessary PXE boot files in ''/srv/tftp/fai''. Unfortunately, at least with FAI 4.2.4 one file in this directory has no read permissions by default, which needs to be corrected:
<pre>
chmod 644 /srv/tftp/fai/vmlinuz-*
</pre>
 
The basic setup of FAI and the NFSroot is now complete.
 
==Modifying the rest of the server==
What is still required is the modification of two other critical components of any FAI install server: NFS and TFTP.
===NFS===
You need the following settings on your exports (namely, adding a unique ''fsid'' for each export) or using FAI in this constellation won't work:
<pre>
vi /etc/exports
</pre>
Modify your exports file to look like this:
<pre>
# /etc/exports: the access control list for filesystems which may be exported
#              to NFS clients.  See exports(5).
#
# Example for NFSv2 and NFSv3:
# /srv/homes      hostname1(rw,sync,no_subtree_check) hostname2(ro,sync,no_subtree_check)
#
# Example for NFSv4:
# /srv/nfs4        gss/krb5i(rw,sync,fsid=0,crossmnt,no_subtree_check)
# /srv/nfs4/homes  gss/krb5i(rw,sync,no_subtree_check)
#
/srv/fai/config        192.168.0.0/24(fsid=1,ro,nohide,insecure,no_subtree_check,async)
/srv/fai/nfsroot        192.168.0.0/24(fsid=2,ro,nohide,insecure,no_subtree_check,async,no_root_squash)
</pre>
 
Start the NFS server:
<pre>
/etc/init.d/nfs-kernel-server start
</pre>
 
===TFTP===
Next, point the TFTP server to the correct directory:
<pre>
vi /etc/default/tftpd-hpa
</pre>
and make this file look like:
<pre>
# /etc/default/tftpd-hpa
 
TFTP_USERNAME="tftp"
TFTP_DIRECTORY="/srv/tftp/fai"
TFTP_ADDRESS="[::]:69"
TFTP_OPTIONS="--secure"
</pre>
Now, here comes the next caveat: restarting the TFTP server alone doesn't force it to read this new configuration. A tougher method has to be used:
<pre>
killall in.tftpd
/etc/init.d/tftpd-hpa restart
</pre>
 
==Preparing boot of a client==
In order to tell FAI to install a new client, this command is usually issued, which is a good thing to start with:
<pre>
fai-chboot -IB 192.168.0.7
</pre>
 
However, on Ubuntu, there are some additional pitfalls with FAI 4.2.4. First of all, using the above command only won't allow the client to be installed because some critical information is missing from the resulting ''pxelinux.cfg'' file. Open this file:
<pre>
vi /srv/tftp/fai/pxelinux.cfg/C0A80007
</pre>
The original file should look like this:
<pre>
# generated by fai-chboot for host 192.168.0.7 with IP 192.168.0.7
default fai-generated
 
label fai-generated
kernel vmlinuz-3.2.0-68-generic
append initrd=initrd.img-3.2.0-68-generic ip=dhcp  root=/srv/fai/nfsroot boot=live  FAI_FLAGS=verbose,sshd,reboot FAI_ACTION=install
</pre>
Make it look like this:
<pre>
# generated by fai-chboot for host 192.168.0.7 with IP 192.168.0.7
default fai-generated
 
label fai-generated
kernel vmlinuz-3.13.0-35-generic
append initrd=initrd.img-3.13.0-35-generic ip=dhcp root=/dev/nfs nfsroot=/srv/fai/nfsroot boot=live  FAI_FLAGS=verbose,sshd,reboot FAI_ACTION=install SERVER=faiserver.example.com FAI_CONFIG_SRC=nfs://$SERVER/srv/fai/config
</pre>
''Pro tip #1'': If something goes wrong, these FAI flags will allow you to use a second virtual terminal (''Control+Alt+F2'') on the install client to see what's going on:
<pre>
FAI_FLAGS=verbose,sshd,createvt
</pre>
''Pro tip #2'': Once on the virtual terminal, you land directly on the live filesystem which will be discarded upon reboot. The filesystem of the install client can be found mounted at ''/target''.
 
=Modifying the FAI configuration space=
So far the install clients can boot the live install system, but won't be able to do anything further, because the configuration space is still missing. The config space instructs the live install system what to do with the client [1].
 
A good starting point are the examples of the fai-doc packages. These will be the starting point of any further modifications, so first, they need to be copied over to the configspace:
<pre>
cp -a /usr/share/doc/fai-doc/examples/simple/* /srv/fai/config
</pre>
 
The examples are perfect for Debian clients, but in order to install Ubuntu, they need to be modified, or client installation will fail.
 
Before continuing, a new custom class shall be introduced: '''OS_UBUNTU_1404_AMD64'''. This class tells FAI to install:
* '''Ubuntu''' as OS
* Version '''14.04''' of this OS
* '''AMD64''' (64-Bit) as the desired architecture.
This class will act as a switch in order to decide which files FAI will use in its install sequence.
 
The most obvious one being the repository configuration. As outlined at the beginning of this tutorial, an ''Ubuntu 14.04 64-Bit server'' is used to install an ''Ubuntu 14.04 64-Bit client''. In this case, the next steps are easy: Just copy over your current apt sources from the install server to the FAI config space in order to be used by the install client.
Of course, if you have different requirements regarding what should be installed on the client (e.g. Debian), you have to adjust ''every single one'' of these files and ''name them accordingly''!
<pre>
mkdir -p /srv/fai/config/files/etc/apt/sources.list
cp /etc/apt/sources.list /srv/fai/config/files/etc/apt/sources.list/OS_UBUNTU_1404_AMD64
mkdir -p  /srv/fai/config/files/etc/apt/sources.list.d/fai.list
cp /etc/apt/sources.list.d/fai.list /srv/fai/config/files/etc/apt/sources.list.d/fai.list/OS_UBUNTU_1404_AMD64
</pre>
 
To actually put these files to use, create a new file:
<pre>
vi /srv/fai/config/hooks/updatebase.UBUNTU
</pre>
and fill it with contents:
<pre>
#! /bin/bash
 
# Import custom apt sources.lists.d
# sources.lists is copied by LAST/50-misc
echo "Preparing apt"
fcopy -v /etc/apt/sources.list.d/fai.list
</pre>
Make this file executable:
<pre>
chmod 755 /srv/fai/config/hooks/updatebase.UBUNTU
</pre>
 
As FAI is not installed from Debian, apt must have the key to verify the packages.
<pre>
gpg -a --export 074BCDE4 > /srv/fai/config/package_config/UBUNTU.asc
</pre>
 
Some additional packages need to be installed on the Ubuntu install client:
<pre>
vi /srv/fai/config/package_config/UBUNTU
</pre>
Again, modify this file to look like this:
<pre>
PACKAGES aptitude I386
linux-image-generic initramfs-tools
memtest86+
 
PACKAGES aptitude CHROOT
linux-image-generic-
 
PACKAGES aptitude AMD64
linux-image-generic initramfs-tools
memtest86+
 
PACKAGES aptitude DHCPC
isc-dhcp-client
 
PACKAGES aptitude GRUB_PC
grub-pc grub-legacy- lilo-
 
PACKAGES aptitude UBUNTU
console-setup
cryptsetup
libpam-mount
ubuntu-minimal
</pre>
 
Enable networking on the install client.
<pre>
mkdir -p /srv/fai/config/files/etc/network/interfaces
vi /srv/fai/config/files/etc/network/interfaces/UBUNTU
</pre>
Modify this file's content to your requirements; the config below will simply use DHCP, which will probably be fine:
<pre>
# The loopback network interface
auto lo
iface lo inet loopback
 
# The primary network interface
auto eth0
iface eth0 inet dhcp
</pre>
 
Now on to something crucial: In order to accomodate to the specifics of Ubuntu, three things have to be done:
* Setting the hostname
* Since Ubuntu does not use ''root'' but uses ''sudo'' instead, a local admin user with the username '''loc''' and the default password '''fai''' will be created
* The above network configuration will be copied to the install client.
Open a new file:
<pre>
mkdir -p /srv/fai/config/scripts/UBUNTU
vi /srv/fai/config/scripts/UBUNTU/10-misc
</pre>
and paste the following contents:
<pre>
#! /bin/bash
 
# Set the hostname
if [ -n $HOSTNAME ]; then
echo $HOSTNAME > $target/etc/hostname
fi
 
# Create a local admin user
$ROOTCMD useradd --password $ROOTPW --groups adm,dialout,cdrom,plugdev,sudo -c "Local Admin,,," --shell /bin/bash loc
$ROOTCMD mkdir /home/loc
$ROOTCMD chmod 0700 /home/loc
$ROOTCMD chown loc:loc /home/loc
fcopy -ir /home/loc
 
# Basic network configuration
fcopy -v /etc/network/interfaces
</pre>
Make this file executable:
<pre>
chmod 755 /srv/fai/config/scripts/UBUNTU/10-misc
</pre>
 
One final thing needs to be done: Basically activating everything you did above by specifying the correct classes for your install client. Open the main FAI control file:
<pre>
vi /srv/fai/config/class/50-host-classes
</pre>
and add the configuration for your client '''between''' the ''case $HOSTNAME in'' statement and the line containing the asterisk ''*)'', e.g. like this:
<pre>
    faiclient)
        echo "FAIBASE DHCPC UBUNTU OS_UBUNTU_1404_AMD64" ;;
</pre>
 
As you wanted to install an Ubuntu 14.04 AMD64 client using an Ubuntu 14.04 AMD64 server with an Ubuntu 14.04 AMD64 NFSroot, you are set and done. Go ahead, boot up your client - if required, choosing the network card as boot device - sit back and let FAI handle the installs for you from now on.
 
=Appendix=
==A. [Optional] Installing different operating systems and architectures==
With FAI you can install different versions of Ubuntu like Ubuntu 14.10, different architectures like AMD64 or i386 or even other distributions like Debian '''in parallel without one affecting the other'''.
 
Say, you'd like FAI to not install Ubuntu 14.04 64-bit, but a 32-bit version of Ubuntu. This can be done without any changes to the configuration above. All you have to do is:
* create of a new class matching the architecture you'd like to install, e.g. ''OS_UBUNTU_1404_I386'' and
* create a matching basefile.
 
If you would like to install previous or future versions of Ubuntu, you have to:
* create of a new class matching the Ubuntu version you'd like to install, e.g. ''OS_UBUNTU_1204_AMD64'' and
* create a matching basefile and
* appropriately modify the apt repositores, namely these files:
** /srv/fai/config/files/etc/apt/sources.list/OS_UBUNTU_1204_AMD64
** /srv/fai/config/files/etc/apt/trustdb.gpg/OS_UBUNTU_1204_AMD64
** /srv/fai/config/files/etc/apt/trusted.gpg/OS_UBUNTU_1204_AMD64
 
Installing other distributions like Debian is also possible, but out of scope of this article. However, the steps required to do so should be similiar to the ones in this tutorial. Please feel free to add a new Wiki page is you've done that!
 
===Creating the basefile===
For each target environment - e.g. Ubuntu 12.04, Ubuntu 14.04 - and architecture - i386, amd64 - you need to create a separate basefile.
 
The easiest and fastest way to do so is downloading the desired target version (in this example it is assumed you want to use Ubuntu 14.04 32-bit as target environment) and create a Live USB with it.
 
Then you boot into the Live USB. Once it finished booting, you open a terminal and update the live system first:
<pre>
apt-get update
apt-get dist-upgrade
</pre>
 
Then you install the required packages to create the basefile:
<pre>apt-get install pbuilder debootstrap</pre>
 
Important: Due to a bug [2] ''pbuilder'' will build a 'saucy' basefile by default. This is not what you want. So you need to open the file
<pre>
vi /usr/share/pbuilder/pbuilderrc
</pre>
and change the line
<pre>DISTRIBUTION = saucy</pre>
to
<pre>DISTRIBUTION = trusty</pre>
 
Then you can start building the basefile:
<pre>pbuilder create</pre>
This will take a couple of minutes.
 
The finished basefile is in ''/var/cache/pbuilder/base.tgz''. Now copy this basefile to your FAI-Server:
<pre>scp /var/cache/pbuilder/base.tgz root@faiserver.example.com:</pre>
 
You can now shutdown and discard the live environment; you don't need it anymore.
 
On the FAI server, copy the basefile to the ''basefiles'' directory of your config space:
<pre>
cp /root/base.tgz /srv/fai/config/basefiles/OS_UBUNTU_1404_I386.tar.gz
</pre>
 
The basefile needs to have a certain filename extension, so the command above did the renaming already.
 
Done! Now add the class '''OS_UBUNTU_1404_I386''' to an host in your ''50-host-classes'' file and it will install this basefile.
 
''Note'': If you are using a differnt operating system '''version''' than the NFSroot on your FAI server was built with (e.g. you want to install Ubuntu 14.10, but the NFSroot is based on Ubuntu 14.04), don't forget to modify the apt repository in the config space!
 
==B. [Optional] Using a Debian Wheezy NFSroot==
It is perfectly possible to use a Debian Wheezy NFSroot instead of a Ubuntu FAI NFSroot - on an Ubuntu 14.04 FAI server.
 
This section will talk about:
* Installing FAI 4.2.4 on an Ubuntu 14.04 (64-Bit) 'Trusty Tahr' server
* in order to be able to install clients with Ubuntu 14.04 (64-Bit) using a '''Debian Wheezy''' NFSroot
* with the option to install other architectures (32-Bit), versions (Ubuntu 14.10, Ubuntu 12.04) and basically any other debian-based distribution '''using a single NFSroot'''.
 
It is intended to replace the chapter ''Setting up the FAI server'' from the beginning of this article.
 
===Installing FAI===
In order to get the latest FAI packages, add the FAI repository to the Ubuntu installation. Open this file:
<pre>
vi /etc/apt/sources.list.d/fai.list
</pre>
and add this line to the empty file:
<pre>
deb http://fai-project.org/download wheezy koeln
</pre>
 
Import the GPG key of the FAI repository. If you get error messages about a wrong URI of the key server, try to run this command a second time:
<pre>
gpg -a --recv-keys 074BCDE4; gpg -a --export 074BCDE4 | apt-key add -
</pre>
 
Import the GPG keys of the Debian repositories, which are required for building the Debian Wheezy NFSroot:
<pre>
apt-get install debian-archive-keyring
</pre>
 
Update the package lists and install FAI:
<pre>
apt-get update
apt-get upgrade
apt-get install fai-quickstart
</pre>
''Note'': 'fai-quickstart' will install not only FAI-related packages but additional packages like DHCP and TFTP as well. If they are already present on your infrastructure, the following alternative packages will suffice:
<pre>
apt-get install fai-server fai-doc
</pre>
===Setting up FAI===
First and foremost FAI needs to be configured. Open the ''fai.conf'' file:
<pre>
vi /etc/fai/fai.conf
</pre>
and edit it like this:
<pre>
# See fai.conf(5) for detailed information.
 
# Account for saving log files and calling fai-chboot.
#LOGUSER=fai
 
SERVER=faiserver.example.com
 
# URL to access the fai config space
#FAI_CONFIG_SRC=nfs://yourservername/path/to/config/space
FAI_CONFIG_SRC=nfs://$SERVER/srv/fai/config
 
# Sending FAI install logfiles from the install client to the
# FAI server
LOGUSER=fai
LOGSERVER=$SERVER
FAI_LOGPROTO=ssh
</pre>
 
The defaults of the NFSroot are fine. If you want to review them, open the ''nfsroot.conf'':
<pre>
vi /etc/fai/nfsroot.conf
</pre>
and make sure it looks like this (which are the defaults):
<pre>
# For a detailed description see nfsroot.conf(5)
 
# "<suite> <mirror>" for debootstrap
FAI_DEBOOTSTRAP="wheezy http://http.debian.net/debian"
FAI_ROOTPW='$1$kBnWcO.E$djxB128U7dMkrltJHPf6d1'
 
NFSROOT=/srv/fai/nfsroot
TFTPROOT=/srv/tftp/fai
NFSROOT_HOOKS=/etc/fai/nfsroot-hooks/
FAI_DEBOOTSTRAP_OPTS="--exclude=info --include=aptitude"
 
# Configuration space
FAI_CONFIGDIR=/srv/fai/config
</pre>
 
Check if your FAI-specific apt sources.list. Open it:
<pre>
vi /etc/fai/apt/sources.list
</pre>
and make sure it looks like this:
<pre>
# These lines should work for many sites
 
deb http://http.debian.net/debian wheezy main contrib non-free
deb http://security.debian.org/debian-security wheezy/updates main contrib non-free
 
# repository that may contain newer fai packages for wheezy
deb http://fai-project.org/download wheezy koeln
</pre>
 
 
===Creating the NFSroot===
Set up FAI:
<pre>
fai-setup -v
</pre>
* '''-v''' enables verbose output of the above command - recommended!
Go get yourself a nice cup of coffee, as this will take some time.
 
The basic setup of FAI and the NFSroot is now complete.
 
===Modifying the rest of the server===
What is still required is the modification of two other critical components of any FAI install server: NFS and TFTP.
====NFS====
You need the following settings on your exports (namely, adding a unique ''fsid'' for each export) or using FAI in this constellation won't work:
<pre>
vi /etc/exports
</pre>
Modify your exports file to look like this:
<pre>
# /etc/exports: the access control list for filesystems which may be exported
#              to NFS clients.  See exports(5).
#
# Example for NFSv2 and NFSv3:
# /srv/homes      hostname1(rw,sync,no_subtree_check) hostname2(ro,sync,no_subtree_check)
#
# Example for NFSv4:
# /srv/nfs4        gss/krb5i(rw,sync,fsid=0,crossmnt,no_subtree_check)
# /srv/nfs4/homes  gss/krb5i(rw,sync,no_subtree_check)
#
/srv/fai/config        192.168.0.0/24(fsid=1,ro,nohide,insecure,no_subtree_check,async)
/srv/fai/nfsroot        192.168.0.0/24(fsid=2,ro,nohide,insecure,no_subtree_check,async,no_root_squash)
</pre>
 
Start the NFS server:
<pre>
/etc/init.d/nfs-kernel-server start
</pre>
 
====TFTP====
Next, point the TFTP server to the correct directory:
<pre>
vi /etc/default/tftpd-hpa
</pre>
and make this file look like:
<pre>
# /etc/default/tftpd-hpa
 
TFTP_USERNAME="tftp"
TFTP_DIRECTORY="/srv/tftp/fai"
TFTP_ADDRESS="[::]:69"
TFTP_OPTIONS="--secure"
</pre>
Now, here comes the next caveat: restarting the TFTP server alone doesn't force it to read this new configuration. A tougher method has to be used:
<pre>
killall in.tftpd
/etc/init.d/tftpd-hpa restart
</pre>
 
===Preparing boot of a client===
In order to tell FAI to install a new client, this command is usually issued, which is a good thing to start with:
<pre>
fai-chboot -IB 192.168.0.7
</pre>
 
However, on Ubuntu, there are some additional pitfalls with FAI 4.2.4. First of all, using the above command only won't allow the client to be installed because some critical information is missing from the resulting ''pxelinux.cfg'' file. Open this file:
<pre>
vi /srv/tftp/fai/pxelinux.cfg/C0A80007
</pre>
The original file should look like this:
<pre>
# generated by fai-chboot for host 192.168.0.7 with IP 192.168.0.7
default fai-generated
 
label fai-generated
kernel vmlinuz-3.2.0-68-generic
append initrd=initrd.img-3.2.0-68-generic ip=dhcp  root=/srv/fai/nfsroot boot=live  FAI_FLAGS=verbose,sshd,reboot FAI_ACTION=install
</pre>
Make it look like this:
<pre>
# generated by fai-chboot for host 192.168.0.7 with IP 192.168.0.7
default fai-generated
 
label fai-generated
kernel vmlinuz-3.2.0-4-amd64
append initrd=initrd.img-3.2.0-4-amd64 ip=dhcp  root=192.168.0.10:/srv/fai/nfsroot aufs  FAI_FLAGS=verbose,sshd,reboot FAI_ACTION=install SERVER=faiserver.example.com FAI_CONFIG_SRC=nfs://$SERVER/srv/fai/config
</pre>
''Pro tip #1'': If something goes wrong, these FAI flags will allow you to use a second virtual terminal (''Control+Alt+F2'') on the install client to see what's going on:
<pre>
FAI_FLAGS=verbose,sshd,createvt
</pre>
''Pro tip #2'': Once on the virtual terminal, you land directly on the live filesystem which will be discarded upon reboot. The filesystem of the install client can be found mounted at ''/target''.
 
All that is left to do is the modification of the FAI configuration space - see the corresponding chapter. This process is not different than the one with the Ubuntu NFSroot. One exception: You need a basefile in any case!
 
==C. Troubleshooting==
===Logs===
If something doesn't work as expected, first and foremost, check the install log. If copying the logs via SSH to your FAI server is working, you should find them at this location ''on your FAI server'':
<pre>
/var/log/fai/faiclient/last-install
</pre>
 
One of the first files to check is the error log:
<pre>
vi /var/log/fai/faiclient/last-install/error.log
</pre>
 
In case copying of the install logs to your FAI server '''is not''' working, you have to review them directly on the install client. See chapter ''Preparing boot of a client'' for details on how to do that.
 
===Permissions===
Found an error in the logs but don't know how to deal with them? Check permissions of the files and directories in the config space, especially those that you did create or modify! They should all be 644, with scripts and hooks being 755.
 
===Files===
Check the ''contents'' of all modified files. Perhaps there has been some copy&paste error.
 
=Comments=
[1] A good overview of the installation sequence and the configuration space is at http://fai-project.org/fai-guide/_anchor_id_config_xreflabel_config_installation_details.html.
 
[2] https://bugs.launchpad.net/ubuntu/+source/pbuilder/+bug/1316423

Latest revision as of 12:49, 9 November 2017

WARNING: Since newer FAI versions now must use dracut instead of initramfs-tools, you cannot create a Ubuntu nfsroot any more. You can still install Ubuntu using a Debian nfsroot on an Ubuntu server. But it's not possible to create a Ubuntu nfsroot at all.


This tutorial will:

  • Install FAI 4.2.4 on an Ubuntu 14.04 (64-Bit) 'Trusty Tahr' server
  • in order to be able to install clients with Ubuntu 14.04 (64-Bit) using a 14.04 NFSroot
  • with the option to install other architectures (32-Bit), versions (Ubuntu 14.10, Ubuntu 12.04) and basically any other debian-based distribution using a single NFSroot.

If you are looking to Install Ubuntu 12.04 LTS with the FAI 3.4.8 packages from the Ubuntu repositories, look here: Installing Ubuntu 12.04 with FAI 3.4.8.

Introduction

You need the following prerequisites in your network:

  • Working DNS and DHCP infrastructure (plus DHCP configured to point to your TFTP server)
  • Ubuntu 14.04 (64-bit) on the FAI server
  • Basic understanding of FAI (class concept, configuration space, ...)
  • Adequate knowledge on the workings of DNS, DHCP, PXE and TFTP.

Just for your information, on this page, the following conventions are used:

  • FAI server: faiserver.example.com, 192.168.0.10
  • FAI client: faiclient.example.com

Setting up the FAI server

Installing FAI

In order to get the latest FAI packages, add the FAI repository to the Ubuntu installation. Open this file:

vi /etc/apt/sources.list.d/fai.list

and add this line to the empty file:

deb http://fai-project.org/download wheezy koeln

Import the GPG key of the FAI repository. If you get error messages about a wrong URI of the key server, try to run this command a second time:

gpg -a --recv-keys 074BCDE4; gpg -a --export 074BCDE4 | apt-key add -

Update the package lists and install FAI:

apt-get update
apt-get upgrade
apt-get install fai-quickstart

Note: 'fai-quickstart' will install not only FAI-related packages but additional packages like DHCP and TFTP as well. If they are already present on your infrastructure, the following alternative packages will suffice:

apt-get install fai-server fai-doc

Setting up FAI

First and foremost FAI needs to be configured. Open the fai.conf file:

vi /etc/fai/fai.conf

and make sure it looks like this:

# See fai.conf(5) for detailed information.

# Account for saving log files and calling fai-chboot.
#LOGUSER=fai

SERVER=faiserver.example.com

# URL to access the fai config space
#FAI_CONFIG_SRC=nfs://yourservername/path/to/config/space
FAI_CONFIG_SRC=nfs://$SERVER/srv/fai/config

# Sending FAI install logfiles from the install client to the
# FAI server
LOGUSER=fai
LOGSERVER=$SERVER
FAI_LOGPROTO=ssh

The next important step is to configure the NFSroot. Open the nfsroot.conf:

vi /etc/fai/nfsroot.conf

and edit it like this:

# For a detailed description see nfsroot.conf(5)

# "<suite> <mirror>" for debootstrap
FAI_DEBOOTSTRAP="trusty http://archive.ubuntu.com/ubuntu"
FAI_ROOTPW='$1$kBnWcO.E$djxB128U7dMkrltJHPf6d1'

NFSROOT=/srv/fai/nfsroot
TFTPROOT=/srv/tftp/fai
NFSROOT_HOOKS=/etc/fai/nfsroot-hooks/
FAI_DEBOOTSTRAP_OPTS="--exclude=info --include=aptitude"

# Configuration space
FAI_CONFIGDIR=/srv/fai/config

As FAI traditionally is Debian-centric, some additional modifications to the NFSroot packages are required. First, FAI nowadays uses the modern dracut in the NFSroot by default. Due to package dependencies the usage of dracut on Ubuntu will not work easily and would likely break the system. Solution: Use the good old live-boot instead. Second, the Linux kernel has a different package name on Ubuntu as opposed to Debian. Third, the mentioned network card firmware just exists on Debian. Open this file:

vi /etc/fai/NFSROOT

and edit it like this:

# package list for creating the NFSROOT

PACKAGES aptitude

#sysvinit-core # use this for booting jessie without systemd

nfs-common fai-nfsroot module-init-tools ssh rdate lshw rpcbind
rsync lftp less dump reiserfsprogs e2fsprogs usbutils
hwinfo psmisc pciutils hdparm smartmontools parted mdadm lvm2
dnsutils ntpdate dosfstools xfsprogs xfsdump
procinfo numactl dialog
console-common kbd
iproute moreutils udev subversion
xz-utils
cupt
pxelinux syslinux-common # in jessie we need both

# some network cards needs firmware
#firmware-bnx2 firmware-bnx2x firmware-realtek
#firmware-linux-nonfree

# dracut can replace live-boot
#dracut-network live-boot- live-boot-initramfs-tools-

# choose if you like live-boot or dracut inside the nfsroot
#live-boot live-boot-doc

# you should not edit the lines below
# architecture dependend list of packages that are installed

#git # git consumes a lot of disk space on the FAI CD (ISO 9660)

PACKAGES aptitude I386
grub-pc
#linux-image-686

# packages for Ubuntu natty/oneiric/precise:
linux-image-generic live-boot

PACKAGES aptitude AMD64
grub-pc
#linux-image-amd64

# packages for Ubuntu natty/oneiric/precise:
linux-image-generic live-boot

And finally, FAI has to be told to get the packages from the correct repositories to build the NFSroot from. Open this file:

vi /etc/fai/apt/sources.list

and replace the existing contents with the following lines:

# Using the Ubuntu repositories
deb http://archive.ubuntu.com/ubuntu/ trusty main restricted universe multiverse
deb http://archive.ubuntu.com/ubuntu/ trusty-updates main restricted universe multiverse
deb http://archive.ubuntu.com/ubuntu/ trusty-backports main restricted universe multiverse

deb http://security.ubuntu.com/ubuntu trusty-security main restricted universe multiverse

deb http://extras.ubuntu.com/ubuntu trusty main

# FAI repository to get the most up-to-date FAI packages on the install clients
deb http://fai-project.org/download wheezy koeln

If you are installing Vivid or later you need to go back to upstart, as systemd is currently not supported by FAI. Add a file with the following content to /etc/fai/nfsroot-hooks/ and make it executable:

#!/bin/sh
$ROOTCMD apt-get install upstart
# If rcS.conf is not removed, FAI will be started twice.
$ROOTCMD rm /etc/init/rcS.conf


Creating the NFSroot

Set up FAI:

fai-setup -vl
  • -v enables verbose output of the above command - recommended!
  • -l is passed to fai-make-nfsroot makes it use 'live-boot instead of dracut, which is not supported by ubuntu.

Go get yourself a nice cup of coffee, as this will take some time.

The above commands create the necessary PXE boot files in /srv/tftp/fai. Unfortunately, at least with FAI 4.2.4 one file in this directory has no read permissions by default, which needs to be corrected:

chmod 644 /srv/tftp/fai/vmlinuz-*

The basic setup of FAI and the NFSroot is now complete.

Modifying the rest of the server

What is still required is the modification of two other critical components of any FAI install server: NFS and TFTP.

NFS

You need the following settings on your exports (namely, adding a unique fsid for each export) or using FAI in this constellation won't work:

vi /etc/exports

Modify your exports file to look like this:

# /etc/exports: the access control list for filesystems which may be exported
#               to NFS clients.  See exports(5).
#
# Example for NFSv2 and NFSv3:
# /srv/homes       hostname1(rw,sync,no_subtree_check) hostname2(ro,sync,no_subtree_check)
#
# Example for NFSv4:
# /srv/nfs4        gss/krb5i(rw,sync,fsid=0,crossmnt,no_subtree_check)
# /srv/nfs4/homes  gss/krb5i(rw,sync,no_subtree_check)
#
/srv/fai/config         192.168.0.0/24(fsid=1,ro,nohide,insecure,no_subtree_check,async)
/srv/fai/nfsroot        192.168.0.0/24(fsid=2,ro,nohide,insecure,no_subtree_check,async,no_root_squash)

Start the NFS server:

/etc/init.d/nfs-kernel-server start

TFTP

Next, point the TFTP server to the correct directory:

vi /etc/default/tftpd-hpa

and make this file look like:

# /etc/default/tftpd-hpa

TFTP_USERNAME="tftp"
TFTP_DIRECTORY="/srv/tftp/fai"
TFTP_ADDRESS="[::]:69"
TFTP_OPTIONS="--secure"

Now, here comes the next caveat: restarting the TFTP server alone doesn't force it to read this new configuration. A tougher method has to be used:

killall in.tftpd
/etc/init.d/tftpd-hpa restart

Preparing boot of a client

In order to tell FAI to install a new client, this command is usually issued, which is a good thing to start with:

fai-chboot -IB 192.168.0.7

However, on Ubuntu, there are some additional pitfalls with FAI 4.2.4. First of all, using the above command only won't allow the client to be installed because some critical information is missing from the resulting pxelinux.cfg file. Open this file:

vi /srv/tftp/fai/pxelinux.cfg/C0A80007

The original file should look like this:

# generated by fai-chboot for host 192.168.0.7 with IP 192.168.0.7
default fai-generated

label fai-generated
kernel vmlinuz-3.2.0-68-generic
append initrd=initrd.img-3.2.0-68-generic ip=dhcp  root=/srv/fai/nfsroot boot=live  FAI_FLAGS=verbose,sshd,reboot FAI_ACTION=install

Make it look like this:

# generated by fai-chboot for host 192.168.0.7 with IP 192.168.0.7
default fai-generated

label fai-generated
kernel vmlinuz-3.13.0-35-generic
append initrd=initrd.img-3.13.0-35-generic ip=dhcp root=/dev/nfs nfsroot=/srv/fai/nfsroot boot=live  FAI_FLAGS=verbose,sshd,reboot FAI_ACTION=install SERVER=faiserver.example.com FAI_CONFIG_SRC=nfs://$SERVER/srv/fai/config

Pro tip #1: If something goes wrong, these FAI flags will allow you to use a second virtual terminal (Control+Alt+F2) on the install client to see what's going on:

FAI_FLAGS=verbose,sshd,createvt

Pro tip #2: Once on the virtual terminal, you land directly on the live filesystem which will be discarded upon reboot. The filesystem of the install client can be found mounted at /target.

Modifying the FAI configuration space

So far the install clients can boot the live install system, but won't be able to do anything further, because the configuration space is still missing. The config space instructs the live install system what to do with the client [1].

A good starting point are the examples of the fai-doc packages. These will be the starting point of any further modifications, so first, they need to be copied over to the configspace:

cp -a /usr/share/doc/fai-doc/examples/simple/* /srv/fai/config

The examples are perfect for Debian clients, but in order to install Ubuntu, they need to be modified, or client installation will fail.

Before continuing, a new custom class shall be introduced: OS_UBUNTU_1404_AMD64. This class tells FAI to install:

  • Ubuntu as OS
  • Version 14.04 of this OS
  • AMD64 (64-Bit) as the desired architecture.

This class will act as a switch in order to decide which files FAI will use in its install sequence.

The most obvious one being the repository configuration. As outlined at the beginning of this tutorial, an Ubuntu 14.04 64-Bit server is used to install an Ubuntu 14.04 64-Bit client. In this case, the next steps are easy: Just copy over your current apt sources from the install server to the FAI config space in order to be used by the install client. Of course, if you have different requirements regarding what should be installed on the client (e.g. Debian), you have to adjust every single one of these files and name them accordingly!

mkdir -p /srv/fai/config/files/etc/apt/sources.list
cp /etc/apt/sources.list /srv/fai/config/files/etc/apt/sources.list/OS_UBUNTU_1404_AMD64
mkdir -p  /srv/fai/config/files/etc/apt/sources.list.d/fai.list
cp /etc/apt/sources.list.d/fai.list /srv/fai/config/files/etc/apt/sources.list.d/fai.list/OS_UBUNTU_1404_AMD64

To actually put these files to use, create a new file:

vi /srv/fai/config/hooks/updatebase.UBUNTU

and fill it with contents:

#! /bin/bash

# Import custom apt sources.lists.d
# sources.lists is copied by LAST/50-misc
echo "Preparing apt"
fcopy -v /etc/apt/sources.list.d/fai.list

Make this file executable:

chmod 755 /srv/fai/config/hooks/updatebase.UBUNTU

As FAI is not installed from Debian, apt must have the key to verify the packages.

gpg -a --export 074BCDE4 > /srv/fai/config/package_config/UBUNTU.asc

Some additional packages need to be installed on the Ubuntu install client:

vi /srv/fai/config/package_config/UBUNTU

Again, modify this file to look like this:

PACKAGES aptitude I386
linux-image-generic initramfs-tools
memtest86+

PACKAGES aptitude CHROOT
linux-image-generic-

PACKAGES aptitude AMD64
linux-image-generic initramfs-tools
memtest86+

PACKAGES aptitude DHCPC
isc-dhcp-client

PACKAGES aptitude GRUB_PC
grub-pc grub-legacy- lilo-

PACKAGES aptitude UBUNTU
console-setup
cryptsetup
libpam-mount
ubuntu-minimal

Enable networking on the install client.

mkdir -p /srv/fai/config/files/etc/network/interfaces
vi /srv/fai/config/files/etc/network/interfaces/UBUNTU

Modify this file's content to your requirements; the config below will simply use DHCP, which will probably be fine:

# The loopback network interface
auto lo
iface lo inet loopback

# The primary network interface
auto eth0
iface eth0 inet dhcp

Now on to something crucial: In order to accomodate to the specifics of Ubuntu, three things have to be done:

  • Setting the hostname
  • Since Ubuntu does not use root but uses sudo instead, a local admin user with the username loc and the default password fai will be created
  • The above network configuration will be copied to the install client.

Open a new file:

mkdir -p /srv/fai/config/scripts/UBUNTU
vi /srv/fai/config/scripts/UBUNTU/10-misc

and paste the following contents:

#! /bin/bash

# Set the hostname
if [ -n $HOSTNAME ]; then
	echo $HOSTNAME > $target/etc/hostname
fi

# Create a local admin user
$ROOTCMD useradd --password $ROOTPW --groups adm,dialout,cdrom,plugdev,sudo -c "Local Admin,,," --shell /bin/bash loc
$ROOTCMD mkdir /home/loc
$ROOTCMD chmod 0700 /home/loc
$ROOTCMD chown loc:loc /home/loc
fcopy -ir /home/loc

# Basic network configuration
fcopy -v /etc/network/interfaces

Make this file executable:

chmod 755 /srv/fai/config/scripts/UBUNTU/10-misc

One final thing needs to be done: Basically activating everything you did above by specifying the correct classes for your install client. Open the main FAI control file:

vi /srv/fai/config/class/50-host-classes

and add the configuration for your client between the case $HOSTNAME in statement and the line containing the asterisk *), e.g. like this:

    faiclient)
        echo "FAIBASE DHCPC UBUNTU OS_UBUNTU_1404_AMD64" ;;

As you wanted to install an Ubuntu 14.04 AMD64 client using an Ubuntu 14.04 AMD64 server with an Ubuntu 14.04 AMD64 NFSroot, you are set and done. Go ahead, boot up your client - if required, choosing the network card as boot device - sit back and let FAI handle the installs for you from now on.

Appendix

A. [Optional] Installing different operating systems and architectures

With FAI you can install different versions of Ubuntu like Ubuntu 14.10, different architectures like AMD64 or i386 or even other distributions like Debian in parallel without one affecting the other.

Say, you'd like FAI to not install Ubuntu 14.04 64-bit, but a 32-bit version of Ubuntu. This can be done without any changes to the configuration above. All you have to do is:

  • create of a new class matching the architecture you'd like to install, e.g. OS_UBUNTU_1404_I386 and
  • create a matching basefile.

If you would like to install previous or future versions of Ubuntu, you have to:

  • create of a new class matching the Ubuntu version you'd like to install, e.g. OS_UBUNTU_1204_AMD64 and
  • create a matching basefile and
  • appropriately modify the apt repositores, namely these files:
    • /srv/fai/config/files/etc/apt/sources.list/OS_UBUNTU_1204_AMD64
    • /srv/fai/config/files/etc/apt/trustdb.gpg/OS_UBUNTU_1204_AMD64
    • /srv/fai/config/files/etc/apt/trusted.gpg/OS_UBUNTU_1204_AMD64

Installing other distributions like Debian is also possible, but out of scope of this article. However, the steps required to do so should be similiar to the ones in this tutorial. Please feel free to add a new Wiki page is you've done that!

Creating the basefile

For each target environment - e.g. Ubuntu 12.04, Ubuntu 14.04 - and architecture - i386, amd64 - you need to create a separate basefile.

The easiest and fastest way to do so is downloading the desired target version (in this example it is assumed you want to use Ubuntu 14.04 32-bit as target environment) and create a Live USB with it.

Then you boot into the Live USB. Once it finished booting, you open a terminal and update the live system first:

apt-get update
apt-get dist-upgrade

Then you install the required packages to create the basefile:

apt-get install pbuilder debootstrap

Important: Due to a bug [2] pbuilder will build a 'saucy' basefile by default. This is not what you want. So you need to open the file

vi /usr/share/pbuilder/pbuilderrc

and change the line

DISTRIBUTION = saucy

to

DISTRIBUTION = trusty

Then you can start building the basefile:

pbuilder create

This will take a couple of minutes.

The finished basefile is in /var/cache/pbuilder/base.tgz. Now copy this basefile to your FAI-Server:

scp /var/cache/pbuilder/base.tgz root@faiserver.example.com:

You can now shutdown and discard the live environment; you don't need it anymore.

On the FAI server, copy the basefile to the basefiles directory of your config space:

cp /root/base.tgz /srv/fai/config/basefiles/OS_UBUNTU_1404_I386.tar.gz

The basefile needs to have a certain filename extension, so the command above did the renaming already.

Done! Now add the class OS_UBUNTU_1404_I386 to an host in your 50-host-classes file and it will install this basefile.

Note: If you are using a differnt operating system version than the NFSroot on your FAI server was built with (e.g. you want to install Ubuntu 14.10, but the NFSroot is based on Ubuntu 14.04), don't forget to modify the apt repository in the config space!

B. [Optional] Using a Debian Wheezy NFSroot

It is perfectly possible to use a Debian Wheezy NFSroot instead of a Ubuntu FAI NFSroot - on an Ubuntu 14.04 FAI server.

This section will talk about:

  • Installing FAI 4.2.4 on an Ubuntu 14.04 (64-Bit) 'Trusty Tahr' server
  • in order to be able to install clients with Ubuntu 14.04 (64-Bit) using a Debian Wheezy NFSroot
  • with the option to install other architectures (32-Bit), versions (Ubuntu 14.10, Ubuntu 12.04) and basically any other debian-based distribution using a single NFSroot.

It is intended to replace the chapter Setting up the FAI server from the beginning of this article.

Installing FAI

In order to get the latest FAI packages, add the FAI repository to the Ubuntu installation. Open this file:

vi /etc/apt/sources.list.d/fai.list

and add this line to the empty file:

deb http://fai-project.org/download wheezy koeln

Import the GPG key of the FAI repository. If you get error messages about a wrong URI of the key server, try to run this command a second time:

gpg -a --recv-keys 074BCDE4; gpg -a --export 074BCDE4 | apt-key add -

Import the GPG keys of the Debian repositories, which are required for building the Debian Wheezy NFSroot:

apt-get install debian-archive-keyring

Update the package lists and install FAI:

apt-get update
apt-get upgrade
apt-get install fai-quickstart

Note: 'fai-quickstart' will install not only FAI-related packages but additional packages like DHCP and TFTP as well. If they are already present on your infrastructure, the following alternative packages will suffice:

apt-get install fai-server fai-doc

Setting up FAI

First and foremost FAI needs to be configured. Open the fai.conf file:

vi /etc/fai/fai.conf

and edit it like this:

# See fai.conf(5) for detailed information.

# Account for saving log files and calling fai-chboot.
#LOGUSER=fai

SERVER=faiserver.example.com

# URL to access the fai config space
#FAI_CONFIG_SRC=nfs://yourservername/path/to/config/space
FAI_CONFIG_SRC=nfs://$SERVER/srv/fai/config

# Sending FAI install logfiles from the install client to the
# FAI server
LOGUSER=fai
LOGSERVER=$SERVER
FAI_LOGPROTO=ssh

The defaults of the NFSroot are fine. If you want to review them, open the nfsroot.conf:

vi /etc/fai/nfsroot.conf

and make sure it looks like this (which are the defaults):

# For a detailed description see nfsroot.conf(5)

# "<suite> <mirror>" for debootstrap
FAI_DEBOOTSTRAP="wheezy http://http.debian.net/debian"
FAI_ROOTPW='$1$kBnWcO.E$djxB128U7dMkrltJHPf6d1'

NFSROOT=/srv/fai/nfsroot
TFTPROOT=/srv/tftp/fai
NFSROOT_HOOKS=/etc/fai/nfsroot-hooks/
FAI_DEBOOTSTRAP_OPTS="--exclude=info --include=aptitude"

# Configuration space
FAI_CONFIGDIR=/srv/fai/config

Check if your FAI-specific apt sources.list. Open it:

vi /etc/fai/apt/sources.list

and make sure it looks like this:

# These lines should work for many sites

deb http://http.debian.net/debian wheezy main contrib non-free
deb http://security.debian.org/debian-security wheezy/updates main contrib non-free

# repository that may contain newer fai packages for wheezy
deb http://fai-project.org/download wheezy koeln


Creating the NFSroot

Set up FAI:

fai-setup -v
  • -v enables verbose output of the above command - recommended!

Go get yourself a nice cup of coffee, as this will take some time.

The basic setup of FAI and the NFSroot is now complete.

Modifying the rest of the server

What is still required is the modification of two other critical components of any FAI install server: NFS and TFTP.

NFS

You need the following settings on your exports (namely, adding a unique fsid for each export) or using FAI in this constellation won't work:

vi /etc/exports

Modify your exports file to look like this:

# /etc/exports: the access control list for filesystems which may be exported
#               to NFS clients.  See exports(5).
#
# Example for NFSv2 and NFSv3:
# /srv/homes       hostname1(rw,sync,no_subtree_check) hostname2(ro,sync,no_subtree_check)
#
# Example for NFSv4:
# /srv/nfs4        gss/krb5i(rw,sync,fsid=0,crossmnt,no_subtree_check)
# /srv/nfs4/homes  gss/krb5i(rw,sync,no_subtree_check)
#
/srv/fai/config         192.168.0.0/24(fsid=1,ro,nohide,insecure,no_subtree_check,async)
/srv/fai/nfsroot        192.168.0.0/24(fsid=2,ro,nohide,insecure,no_subtree_check,async,no_root_squash)

Start the NFS server:

/etc/init.d/nfs-kernel-server start

TFTP

Next, point the TFTP server to the correct directory:

vi /etc/default/tftpd-hpa

and make this file look like:

# /etc/default/tftpd-hpa

TFTP_USERNAME="tftp"
TFTP_DIRECTORY="/srv/tftp/fai"
TFTP_ADDRESS="[::]:69"
TFTP_OPTIONS="--secure"

Now, here comes the next caveat: restarting the TFTP server alone doesn't force it to read this new configuration. A tougher method has to be used:

killall in.tftpd
/etc/init.d/tftpd-hpa restart

Preparing boot of a client

In order to tell FAI to install a new client, this command is usually issued, which is a good thing to start with:

fai-chboot -IB 192.168.0.7

However, on Ubuntu, there are some additional pitfalls with FAI 4.2.4. First of all, using the above command only won't allow the client to be installed because some critical information is missing from the resulting pxelinux.cfg file. Open this file:

vi /srv/tftp/fai/pxelinux.cfg/C0A80007

The original file should look like this:

# generated by fai-chboot for host 192.168.0.7 with IP 192.168.0.7
default fai-generated

label fai-generated
kernel vmlinuz-3.2.0-68-generic
append initrd=initrd.img-3.2.0-68-generic ip=dhcp  root=/srv/fai/nfsroot boot=live  FAI_FLAGS=verbose,sshd,reboot FAI_ACTION=install

Make it look like this:

# generated by fai-chboot for host 192.168.0.7 with IP 192.168.0.7
default fai-generated

label fai-generated
kernel vmlinuz-3.2.0-4-amd64
append initrd=initrd.img-3.2.0-4-amd64 ip=dhcp  root=192.168.0.10:/srv/fai/nfsroot aufs  FAI_FLAGS=verbose,sshd,reboot FAI_ACTION=install SERVER=faiserver.example.com FAI_CONFIG_SRC=nfs://$SERVER/srv/fai/config

Pro tip #1: If something goes wrong, these FAI flags will allow you to use a second virtual terminal (Control+Alt+F2) on the install client to see what's going on:

FAI_FLAGS=verbose,sshd,createvt

Pro tip #2: Once on the virtual terminal, you land directly on the live filesystem which will be discarded upon reboot. The filesystem of the install client can be found mounted at /target.

All that is left to do is the modification of the FAI configuration space - see the corresponding chapter. This process is not different than the one with the Ubuntu NFSroot. One exception: You need a basefile in any case!

C. Troubleshooting

Logs

If something doesn't work as expected, first and foremost, check the install log. If copying the logs via SSH to your FAI server is working, you should find them at this location on your FAI server:

/var/log/fai/faiclient/last-install

One of the first files to check is the error log:

vi /var/log/fai/faiclient/last-install/error.log

In case copying of the install logs to your FAI server is not working, you have to review them directly on the install client. See chapter Preparing boot of a client for details on how to do that.

Permissions

Found an error in the logs but don't know how to deal with them? Check permissions of the files and directories in the config space, especially those that you did create or modify! They should all be 644, with scripts and hooks being 755.

Files

Check the contents of all modified files. Perhaps there has been some copy&paste error.

Comments

[1] A good overview of the installation sequence and the configuration space is at http://fai-project.org/fai-guide/_anchor_id_config_xreflabel_config_installation_details.html.

[2] https://bugs.launchpad.net/ubuntu/+source/pbuilder/+bug/1316423