FAI (Fully Automatic Installation) Guide NOT YET FINISHED ! <author>Thomas Lange <email>lange@informatik.uni-koeln.de</email> <version>ver. &version;, &date; <abstract> This manual describes the fully automatic installation package for &dgl;. This includes the installation of the package, the planing and creating of the configuration and how to deal with errors. <copyright> <copyrightsummary> Copyright © 2000-2001 Thomas Lange </copyrightsummary> This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. 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 &file-GPL; in the &dgl distribution or on the World Wide Web at <url id="&url-gpl;" name="the GNU website">. You can also obtain it by writing to the &fsf-addr;. <toc detail="sect2"> <chapt id="motivation">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 time and again is boring -- and will surely lead to mistakes. Also a whole lot of time could be saved, if the installation were done automatically. An installation process with manual interaction does not scale. But clusters have the habit of growing over the years. Think long-term rather than plan only just a few months into the future. In 1999 I had to install a Linux cluster with one server and 16 clients. Since I had much experience doing automatic installation of Solaris operating system on SUN SPARC hardware, the idea to build an automatic installation for Debian was born. <chapt id="overview">Overview and concepts of FAI FAI is a non interactive system to install a &dgl operating system on a single computer or a whole cluster. You can take one or more virgin PC's, turn on the power and after a few minutes Linux is installed, configured and running on the whole cluster, without any interaction necessary. Thus, it's a scalable method for installing and updating a cluster unattended with little effort involved. FAI uses the &dgl; distribution and a collection of shell and perl scripts for the installation process. Changes to the configuration files of the operating system can be made by cfengine, shell, perl and expect scripts. FAI's target group are system administrators how have to install Debian onto one or even hundreds of computers. Because it's a general purpose installation tool, it can be used for installing a beowulf cluster, a rendering farm or a linux laboratory or a classroom. Also large-scale linux networks with different hardware or different installation requirements are easy to establish using FAI. First, some terms used in this manual, are described. <taglist> <tag> install server : <item> The host, where the package FAI is installed. It provides several services for all install clients. <tag>install client : <item> A host, which will be installed using FAI and a configuration from the install server. Also called client for short. </item> <tag> configuration : <item> The details, how the installation of the clients should be performed. This includes information about: <list> <item> Hard disk layout </item> <item> Local filesystems </item> <item> Software packages </item> <item> Keyboard layout, time zone, NIS, X11 configuration, remote filesystems, user accounts, printers ... </item> </list> <tag> nfsroot : <item> A filesystem located on the install server. It's the complete filesystem for the install client, which is mounted by the client during installation process.</item> </taglist> <sect id="work">How does FAI work ? The computer, which will be installed using FAI (called client), is booted from floppy disk or via network card. It gets an IP-address and boots a linux kernel which mounts all filesystems via NFS from the install server. After the operating system is running, the FAI startup script performs the automatic installation which doesn't need any interaction. First, the hard disks will be partitioned, filesystems are created and then software packages are installed. After that, the new installed operating system is configured to your local needs using some scripts. Finally the new oprating 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 multiple computers if the are similar. So you need not to create a configuration for every new host. Hence, FAI is a scalable method to install a big cluster with a great number of nodes. FAI can also be used as an network rescue system. You can boot your computer without performing an installation. Instead it will run a fully functional &dgl without using the local hard disks. Then you can do a remote login and backup or restore a disk partition, check a filesystem, inspect the hardware or do any other task. <sect id="features">Features of FAI <list> <item> </item> <item> A fully automatic installation can be perfomed </item> <item> Hosts can boot from floppy or from network card </item> <item> BOOTP and DHCP protocol are supported </item> <item> No initial ramdisk is needed, 8MB RAM suffice </item> <item> The installation kernel can use modules </item> <item> Remote login via ssh during installation process possible </item> <item> Two additional virtual terminals available during installation </item> <item> All similar configuration are shared among all install clients </item> <item> Log files are saved on to the installation server </item> <item> Shell, perl, expect and cfengine scripts are supported for the configuration </item> <item> Access to a Debian mirror via NFS, FTP or HTTP </item> <item> Very quick unattended installation </item> <item> Runs even on a 386 CPU (partially tested on SUN SPARC in 2001) </item> <item> Easy creation of boot floppy </item> <item> Keyboard layout selectable </item> <item> Can be used as a rescue system </item> <item> </item> </list> <chapt id="inst">Installing FAI <sect id="requirements">Requirements Following items are required for an installation via FAI. <taglist> <tag>A computer: </tag><item> with a network interface card XXX BOOTPROM</item> <tag>BOOTP or DHCP server: </tag><item> The clients need one of these daemons to obtain information.<footnote> It's also possible without a server, if all information a included on the boot disk. </footnote> </item> <tag>TFTP server:<item> The TFTP daemon is used for transfering the kernel to the clients. Only needed when booting from network card.</item> <tag>Debian mirror:<item> Access to a Debian mirror is needed. A local mirror of all Debian packages is recommended if you install multiple computers.</item> <tag>Install kernel image: <item> A kernel image that supports the network card and mounts its root filesystem via NFS. </item> <tag>Configuration space:<item> A mountable directory which contains the configuration data. </item> </taglist> The TFTP daemon and a NFS server will be enabled automatically when installing the FAI package. Different install kernel images for BOOTP and DHCP are available within the package. All clients must have a network card, which is recognized by the install kernel. The FAI package is available as a Debian package from &faidownload; until it will be an official Debian package soon. <sect id="debian-mirror">How to create a local Debian mirror There are two scripts available for creating a local partitial mirror in <file>/usr/share/doc/fai/examples/utils/</file>, <prgn>mkdebmirror</prgn> uses debmirror <httpsite>http://cvs.kitenet.net/</httpsite><httppath>joey-cvs/bin/debmirror</httppath>. Use these script for building a mirror only for i386 architecture. <sect id=aptsetup> Setting up FAI First, get the newest version of FAI and install it using the <prgn>dpkg</prgn> command: <example> kueppers[~]# dpkg -i fai_1.5.0_all.deb Selecting previously deselected package fai. (Reading database ... 39564 files and directories currently installed.) Unpacking fai (from fai_1.5.0_all.deb) ... Setting up fai (1.5.0) ... To set up FAI edit /etc/fai.conf and call fai-setup </example> All definitions for the FAI package are defined in &fc;. Since FAI doesn't use <prgn>debconf</prgn> yet, edit this file and call <prgn>fai-setup</prgn>. These are important variables in &fc;: <taglist> <tag><var>FAI_BASETGZ</var></tag> <item> The location, where the the base file is fetched from. For building the nfsroot, the Debian base system is needed. It's a big tar file (&basetgzsize for &basetgz) , which is a minimal collection of all required packages for Debian. It is not used, when a file &basetgz is already available in <file>/tmp</file>. Fetching via ftp or http could take much time, if you do not have a fast connection to your Debian mirror. You can find the current version in the directory <tt>debian/dists/stable/main/disks-i386/current/</tt> of your Debian mirror. </item> <tag><var>FAI_SOURCES_LIST</var></tag> <item> This multi line string is the definition for <file>sources.list</file> (used by <manref name="apt-get" section="8">), which defines the location and access method of the Debian mirror. For more information on the file format see <manref name="sources.list" section="5">. </item> <tag><var>FAI_DEBMIRROR</var></tag> <item> If you have NFS access to your local Debian mirror, specify the remote filesystem. It will be mounted to <var>$MNTPOINT</var>. It's not needed if you use FTP or HTTP access. </item> <tag><var>KERNELPACKAGE</var></tag> <item> You must specify the software package (build with <manref name="make-kpkg" section="8">), which includes the default kernel for booting the install clients. The Debian package <package>fai-kernels</package> contains the default install kernels with BOOTP and DHCP support.</item> <tag> <var>NFSROOT_PACKAGES</var></tag> <item> Contains a list of additional software package, that will be installed to nfsroot.</item> </taglist> FAI uses <manref name="apt-get" section="8"> to create the nfsroot filesystem in <file>/usr/lib/fai/nfsroot</file>, which needs about &nfsrootsize of free disk space. You should also install the package <package>fai-kernels</package>, which will be automaticlly installed when you use <prgn>apt-get</prgn> for installing FAI. <example> kueppers[~]# dpkg -i ~lange/fai-kernels_1.1_i386.deb Selecting previously deselected package fai-kernels. (Reading database ... 40562 files and directories currently installed.) Unpacking fai-kernels (from .../lange/fai-kernels_1.1_i386.deb) ... Setting up fai-kernels (1.1) ... </example> Before setting up FAI, you should get the program <prgn>imggen</prgn>, if you like to boot from a 3Com network card. This executable converts netboot images, so they can be booted by 3Com cards. You can get this compiled program from the download page &faidownload;. Put that executable in your path (e.g. <file>/usr/local/bin</file>). After editing &fc; call <prgn>fai-setup</prgn>. <example> kueppers[~]# fai-setup Adding system user fai... Stopping Name Service Cache Daemon: nscd. Adding new user fai (100) with group nogroup. Starting Name Service Cache Daemon: nscd. Creating home directory /home/fai. /home/fai/.rhosts created. User account fai created. Creating FAI nfsroot can take a long time and will need more than 100MB disk space in /usr/lib/fai/nfsroot. Unpacking /tmp/base2_2.tgz Upgrading /usr/lib/fai/nfsroot Adding additional packages to /usr/lib/fai/nfsroot: perl-5.005 dhcp-client file rdate cfengine bootpc wget rsh-client less dump ext2resize raidtools2 strace expect5.31 hdparm parted dnsutils grub ssh grep: /etc/ssh/sshd_config: No such file or directory grep: /etc/ssh/sshd_config: No such file or directory Not starting OpenBSD Secure Shell server (/etc/ssh/NOSERVER) make-fai-nfsroot finished. Stopping NFS kernel daemon: mountd nfsd. Unexporting directories for NFS kernel daemon...done. Starting NFS kernel daemon: nfsd mountd. Exporting directories for NFS kernel daemon...done. Kernel image file name = /usr/lib/fai/nfsroot/boot/vmlinuz-2.2.19 Output file name = /boot/fai/installimage Kernel command line = "auto rw root=/dev/nfs nfsroot=kernel nfsaddrs=kernel" Image Creator for MBA ROMs v1.00 Usage: imggen [OPTION] inputfile outputfile -a, Add 3Com MBA/BootWare support -r, Remove 3Com MBA/BootWare support from image file -i, Show information on an image -h, Help screen In filename: /boot/fai/installimage Out filename: /boot/fai/installimage_3com Adding MBA support... MBA support has been succesfully added You have no FAI configuration. Copy FAI template files with: cp -a /usr/share/doc/fai/templates/* /usr/local/share/fai Then change the configuration files to meet your local needs. FAI setup finished. </example> The setup routine adds lines to <file>/etc/exports</file> to export some directories to all hosts that belong to the netgroup faiclients. Netgroups are defined in <file>/etc/netgroup</file> or in the correspondening NIS map. An example for the netgroup file can be found in <file>/usr/share/doc/fai/examples/etc/netgroup</file>. For more information, read the manual pages <manref name="netgroup" section="5"> and the NIS HOWTO. After changing the netgroups , the nfs server has to reload its configuration. Use one of the following commands, depending on which nfs server you are using: <example> kueppers[~]# /etc/init.d/nfs-kernel-server reload kueppers[~]# /etc/init.d/nfs-server reload </example> The set up also creates the account <tt>fai</tt> ($LOGUSER). If you will boot from network card, you should change the primary group of this account, so this account has write permissions to <file>/boot/fai</file> in order to change symbolic links to the kernel image, that is bootet by a client. See also <file>/etc/fai.conf</file>. After that, FAI is installed successfully on your server, but has no configuration for the install clients. Start with the templates from <tt> /usr/share/doc/fai/templates</tt> using the copy command above and read <ref id="config">. Before you can set up a DHCP or BOOTP daemon, you should collect some network information of all your install clients. This is described in section <ref id="bootfloppy">. When you make changes to &fc or want to install a new kernel to nfsroot, the nfsroot has to be rebuild by calling <prgn>fai-setup</prgn>. <chapt id="booting">Preparing booting Before booting for the first time, you have to choose which medium you use for booting. You can use the boot floppy or configure the computer to boot via network card, which is much smarter. <sect id="nicboot">Configuring a 3Com network card If you have a 3Com network card that is equipped with a boot ROM by Lanworks Technologie or already includes the DynamicAccess Managed PC Boot Agent (MBA <footnote> see <httpsite>http://www.3com.com/</httpsite> <httppath>products/software/dynamicaccess/</httppath></footnote>) software, you can enter the MBA setup by typing <tt>Ctrl+Alt+B</tt> during boot. The setup will look like this: <example> Managed PC Boot Agent (MBA) v4.00 (C) Copyright 1999 Lanworks Technologies Co. a subsidiary of 3Com Corporation All rights reserved. =============================================================================== Configuration Boot Method: TCP/IP Protocol: BOOTP Default Boot: Network Local Boot: Enabled Config Message: Enabled Message Timeout: 3 Seconds Boot Failure Prompt: Wait for key =============================================================================== Use cursor keys to edit: Up/Down change field, Left/Right change value ESC to quit, F9 restore previous settings, F10 to save </example> Set the boot method to <tt>TCP/IP</tt> and the protocol to either <tt>BOOTP</tt> or <tt>DHCP</tt>. I prefer the BOOTP protocol. <sect id="pxeboot">Booting from network card with a PXE conforming boot ROM My notebook has an builtin Intel EtherExpress PRO 100 network interface card, with a fixed configuration for booting using the PXE protocol. This requires a PXE Linux boot loader. See <file>/usr/share/doc/syslinux/pxelinux.doc.gz</file> for more information, how to boot in such an environment. There are also some mail in the mailling list archive concerning this topic. <sect id="bootnetwork">Booting via network card Make a symbolic link from the hostname of your client to the appropriate kernel image in <file>/boot/fai</file>. The file <file>installimage_3com</file> is created by <prgn>imggen</prgn> and suitable for booting 3Com network cards. <example> kueppers[~]# cd /boot/fai kueppers[~]# ln -s installimage_3com bigfoot </example> <sect id="bootfloppy">Creating a boot floppy If your network card can't boot itself, you have to boot via floppy. Use the command <prgn>make-fai-bootfloppy</prgn> to create the boot floppy. Since there's no client specific information on this floppy, it's suitable for all your install clients. You can also specify additional kernel parameters for this boot floppy, it desired. See <example>make-fai-bootfloppy -h XX</example> for more information. If you have no BOOTP or DHCP server, supply the network configuration as kernel parameters: <footnote> For additional information see <file>/usr/src/linux/Documentation/nfsroot.txt</file> in the kernel sources. </footnote> <example>ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf> </example> <example>"nfsroot=<ip of install server>:/usr/lib/fai/nfsroot"</example> <sect id="mac">Collecting Ethernet addresses Now it's time to boot your install clients for the first time. They will fail to boot, because no BOOTP or DHCP daemon is running yet or recognizes the hosts. But you can use this first boot attempt to easily collect all Ethernet addresses of the network cards. You have to collect all Ethernet (MAC) addresses of the install clients and assign a hostname and IP address to each client. To collect all MAC addresses, now boot all your install clients. While the install clients are booting, they send broadcast packets to the LAN. You can log the MAC addresses of these hosts, if following command is running simultaneously on the server: <example># tcpdump -qte broadcast and port bootpc >/tmp/mac.lis</example> After the hosts has been sent some broadcast packets (they will fail to boot because <prgn>bootpd</prgn> isn't running or does not recognise the MAC address yet) abort <prgn>tcpdump</prgn> by typing <tt>ctrl-c</tt>. You get a list of all unique MAC addresses with these commands: <example># perl -ane 'print "\U$F[0]\n"' /tmp/mac.lis|sort|uniq</example> After that, you only have to assign these MAC addresses to hostnames and IP addresses (<file>/etc/ethers</file> and <file>/etc/hosts</file> or corresponding NIS maps). With these information you can configure your <prgn>BOOTP</prgn> or <prgn>DHCP</prgn> daemon (see the section <ref id="bootptab">). I recommend to write the MAC addresses (last three bytes will suffice if you have network card from the same vendor) and the hostname in the front of each chassis. <sect id=bootptab>Configuration of BOOTP daemon An example configuration for the BOOTP daemon is included in FAI. If you have no <file>/etc/bootptab</file> file you can use <file>/usr/share/doc/fai/examples/etc/bootptab</file> as template. <example> # /etc/bootptab example for FAI # replace FAISERVER with the name of your install server .faiglobal:\ :ms=1024:\ :hd=/boot/fai:\ :hn:bs=auto:\ :rp=/usr/lib/fai/nfsroot: # rp: $NFSROOT # your local values # # sa: your tftp server (install server) # ts: your timeserver (time enabled in inetd.conf) # T170 location of FAI configuration directory # T171 FAI_ACTION # T172 FAI_FLAGS, e.g. verbose, debug, reboot, sshd # T173 reserved for future use # T174 reserved for backup devices and backup options; NOT YET USED # sm: subnet mask # gw: router/gateway address # dn: domainname # ds: list of nameservers # these are optional # ys: NIS server # yd: NIS domainname # nt: list of NTP servers .failocal:\ :tc=.faiglobal:\ :sa=FAISERVER:\ :ts=FAISERVER:\ :T170="FAISERVER:/usr/local/share/fai":\ :T171="sysinfo":\ :sm=255.255.255.0:\ :gw=134.95.9.254:\ :dn=informatik.uni-koeln.de:\ :ds=134.95.9.136,134.95.100.209,134.95.100.208,134.95.140.208:\ :ys=rubens:yd=informatik4711.YP:\ :nt=time.rrz.uni-koeln.de,time2.rrz.uni-koeln.de: # now one entry for each install client bigfoot:ha=0x00105A240012:bf=bigfoot:tc=.failocal:T171="sysinfo":T172="sshd verbose debug ": ant01:ha=0x00105A000000:bf=ant01:tc=.failocal:T172="sshd": </example> Insert one line for each install client at the end of this file as done for bigfoot and ant01. Replace the string <tt>FAISERVER</tt> with the name of your install server. Then adjust the other network tags (<tt>sm, gw, dn, ds</tt>) to your local needs. The tags for NIS and time servers (<tt>yp, yd, nt</tt>) are optional. Tags with prefix <tt>T</tt> (starting from T170) are generic tags which are used to transfer some FAI specific data to the clients. It is important, that T171 (equivalent to variable <var>FAI_ACTION</var><footnote> Theses names are used in the main installation script <file>rcS_fai</file>. The configuration files for DHCP and BOOTP daemons use other names. Example: <var>FAI_ACTION</var> is equal to <tt>T171</tt> in bootptab or <tt>option-171</tt> in dhcp.conf. </footnote>. is set to <tt>sysinfo</tt> ! Later you can set it to <tt>install</tt>, in order to start the automatic installation. For more information see <manref name="bootptab" section="5"> and section (TODO: explain all tags). When you have created your <file>bootptab</file> file, you have to enable the BOOTP daemon once. It's installed but Debian does not enable it by default. Edit <file>/etc/inetd.conf</file> and remove the comment (the hash) in the line containing <tt>#bootps</tt>. Then tell <prgn>inetd</prgn> to reload its configuration. <example># /etc/init.d/inetd reload</example> I recommend to use the BOOTP daemon and protocol for booting because it automatically reloads the configuration file if any changes are made to it. The daemon for DHCP must always be manually restarted after changes to the configuration file are made <footnote> If you can't use one of these, there's also the possibility to supply all information via a file or compile them into the kernel, but it's easier to use a daemon. </footnote>. Now it's time to boot all install clients again! <sect id="boot">Boot messages These are the messages, when booting from floppy. <example> LILO Loading FAI-BOOTP. Uncompressing Linux... OK, booting the Kernel. Linux version 2.2.19 (root@kueppers) (gcc version 2.95.2 20000220 . . . </example> The rest of the boot message will be equal to those when booting from network card. When booting from network card you will see: <example> BOOTP. TFTP.... Linux Net Boot Image Loader Version 0.8.1 (netboot) . Uncompressing Linux... OK, booting the Kernel. Linux version 2.2.19 (root@kueppers) (gcc version 2.95.2 20000220 . . . Sending BOOTP requests ..... OK IP-Config: Got BOOTP answer from 134.95.9.149 IP-Config: Complete: device=eth0, addr=134.95.9.200, mask=255.255.255.0, gw=134.95.9.254, host=ant01, domain=informatik.uni-koeln.de, nis-domain=informatik4711.YP, bootserver=134.95.9.149, rootserver=134.95.9.149, rootpath=/usr/lib/fai/nfsroot . . . ------------------------------------------------------ FAI 1.5.0, XXXX XX, 2001 Fully Automatic Installation for Debian GNU/Linux Copyright (c) 1999-2001, Thomas Lange lange@informatik.uni-koeln.de ------------------------------------------------------ Press ctrl-c to interrupt FAI and to get a shell . . . Press <RETURN> to reboot or ctrl-c to execute a shell </example> There will be some error message from modprobe and insmod, but that doesn't matter. If you get the following error message, the kernel has no driver compiled in for your network card. Compile a new kernel which supports your network card. <example> IP-Config: No network devices available Partition check: hda: hda1 hda2 < hda5 hda6 hda7 hda8 > Root-NFS: No NFS server available, giving up. VFS: Unable to mount root fs via NFS, trying floppy. VFS: Insert root floppy and press ENTER </example> To compile a new kernel, start using the default kernel configuration of FAI. Call <prgn>make menuconfig</prgn> and add a driver in menu <tt>Network device support/Ethernet</tt> which supports your network card. Then create a Debian package using: <example> kueppers# cd /usr/src/linux kueppers# cp /usr/lib/fai/nfsroot/boot/config-2.2.19 .config kueppers# make menuconfig kueppers# make-kpkg clean kueppers# make-kpkg --revision BOOTP2 kernel-image </example> The created file is <file>/usr/src/kernel-image-2.2.19_BOOTP2_i386.deb</file>. Adjust the variable <var>KERNELPACKAGE</var> in &fc; and rebuild the nfsroot by calling. <example> kueppers# fai-setup </example> After that, you have to create a new boot floppy. Now your network card should be recognized and your host should boot correctly. <sect id="sysinfo">Collecting other system information Now the clients have booted with <var>FAI_ACTION</var> set to sysinfo. Type <tt>ctrl-c</tt> to get a shell or use <tt>Alt-F2</tt> or <tt>Alt-F3</tt> to open a virtual terminal, where you can log in as <tt>root</tt> with the password defined by <var>FAI_ROOTPW</var> in &fc;. Remote login is available via the secure shell. To log in from your server to the client (for eg. named ant01) use: <example>> ssh -l root ant01 Warning: Permanently added 'ant01,134.95.9.200' to the list of known hosts. root@ant01's password: </example> You have now a running Linux system without using the local hard disk. Use this as a rescue system, if your local disk are damaged or the computer can't boot properly from hard disk. You will get a shell and can execute various commands (dmesg, lsmod, df, lspci, ...). Look at the log file in <file>/tmp</file>. There you can find much information about the boot process. All log files from <file>/tmp </file> are also written to the server in the directory <tt>~fai/ant01/sysinfo/</tt><footnote>More general: <tt>~$LOGUSER/$HOSTNAME/$FAI_ACTION/</tt>. </footnote> A very nice feature is, that FAI mounts all filesystems (all fs types linux supports) it finds on the local disks read only. It also tells you on which partition a file <file>/etc/fstab</file> exists. When only one fstab is found, the partitions are mounted according to this information. Here's an example: <example> ant01:~# df Filesystem 1k-blocks Used Available Use% Mounted on /dev/root 1249132 855648 330032 72% / /dev/ram0 3963 36 3927 1% /tmp kueppers:/usr/local/share/fai 1249132 855648 330032 72% /fai /dev/hda1 54447 9859 41777 19% /tmp//target /dev/hda10 1153576 20 1141992 0% /tmp/target/files/install /dev/hda9 711540 20 711520 0% /tmp/target/home /dev/hda8 303336 13 300191 0% /tmp/target/tmp /dev/hda7 1517948 98252 1342588 7% /tmp/target/usr /dev/hda6 202225 8834 182949 5% /tmp/target/var </example> This method can be used as an rescue environment ! In future it will be possible to make backups or restore data to existing filesystems. If you need a filesystem with read-write access use: <example>ant01:~# rwmount /tmp/target/home</example> You can reboot the computer using the command <prgn>faireboot</prgn>. <chapt id=instprocess>The installation process FAI can perform several actions when the client is booting. This action is defined in the variable <var>FAI_ACTION</var> Be very carefully if you set <var>FAI_ACTION </var> to install. This can destroy all your data on the install client, indeed most time it should do this ;-). It's recommended to change this only on a per client base in the BOOTP configuration. Do not change it in the section <tt>.failocal</tt> in <file>/etc/bootptab</file>, which is a definition for all clients. <sect id=isequence>The installation sequence Following steps are performed during an installation after the linux kernel has booted on the install clients. <enumlist> <item> Set up FAI </item> <item> Load kernel modules </item> <item> Define classes </item> <item> Define variables </item> <item> Partitioning local disks </item> <item> Create and mount local filesystems </item> <item> Install software packages </item> <item> Call site specific configuration scripts </item> <item> Save log files </item> <item> Reboot the new installed system </item> </enumlist> <sect1 id=isetup>Set up FAI After the install client has booted the program <file>/sbin/rcS_fai</file><footnote>Since the root filesystem on the clients is mounted via NFS, <prgn>rcS_fai</prgn> is located in <file>/usr/lib/fai/nfsroot/sbin</file> on the install server. </footnote> is executed. This is the main script, that controls the sequence of tasks for FAI. A ramdisk is created and mounted to <file>/tmp</file>, which is the only writeable directory, until local filesystems are mounted. Additional parameters are received from the BOOTP or DHCP daemon <footnote>If these information daemons can't be used, FAI also reads definitions from <file>/fai/fai_config/global.conf</file> and <tt>/fai/fai_config/$HOSTNAME</tt>. This is done before and after <file>/fai</file> is mounted from the install server. So the first time the data will be read from <file>/usr/lib/fai/nfsroot/fai/fai_config</file> and after mounting <file>/fai</file> they are read from <file>/usr/local/share/fai/fai_config</file>. This is not the recommended way to specify the information. Use one the daemons instead if possible! </footnote> and all needed remote filesystems are mounted. The set up is finished after additional virtual terminals are created and the secure shell daemon is started on demand. <sect1 id=iclass>Define classes One of the most important feature of FAI are the classes. Using classes you can share configuration data among multiple clients. Details are described in <ref id="classes">.XXXX All define classes are listed in <file>FAI_CLASSES</file>. The main scripts executes all scripts in <file>/fai/class</file>, which name conforms matches <tt>S[0-9]*.{sh,pl}</tt>. Every word that these scripts print to the standard ouput are interpreted as class names. A complete description of all these scripts can be found in <ref id="cscripts">. The script <file>S05modules.sh</file> and all file with suffix <tt>.mod</tt> will load kernel modules but not define any class. Script ending in <tt>.var</tt> are used for defining variables, that are later used in the site specific configuration scripts. <sect1 id=ipartition>Partitioning local disks After all classes and variables are defined, one disk configuration file from <file>/fai/disk_config</file> is selected. It's a description how the local disks will be partitioned, which filesystems should be created or preserved and how they are mounted. Refer to XXXX for more information. This is done by the command <prgn>setup_harddisks</prgn>, which uses <prgn>sfdisk</prgn> for obtaining disk information and for partitioning. If <prgn>/usr/local/bin/my-fdisk</prgn> exists, this command is used instead. <sect1 id=imount>Create and mount local filesystems Creation is also done by <prgn>setup_harddisks</prgn>. Mounting the filesystems is done by the routine <tt>mount2target</tt>. It's possible to specify parameters for filesystems creation and also to give mount options. All local filesystems are mounted relativ to <file>/tmp/target</file> during the installation process. So, for eg. <file>/tmp/target/home</file> will become <file>/home</file> in the new installed system. A more detailed description is in XXXXX. In future, this command will be completely rewritten. Plans are to use <prgn>parted</prgn> and the device filesystems <tt>devfs</tt>. Then things are becoming much easier. <sect1 id=ipackages>Install software packages When local filesystems are created, they are all empty (except for preserved partitions). Now the Debian base system and all requested software packages must be installed on the new filesystems. First the base tar file is unpacked, then the command <prgn>install_packages</prgn> installes all packages witout any manually interaction needed. If a packages requires an other packages, <prgn>apt-get</prgn> resolves this dependency by installing the required package. <sect1 id=icscripts>Configuration scripts After all demanded software packages are installed, the system is nearly ready to go. But not all default configurations of the software packages will meet your site specific needs. So you can call arbitrary scripts, which adjust the configuration. Therefore scripts, that match a class name in <file>/fai/scripts</file><footnote> <file>/usr/local/share/fai/scripts</file> on the install server. </footnote> will be executed. FAI comes with some templates for these scripts, but you can write your own bourne/bash, perl, cfengine or expect scripts. Using cfengine, you can easily edit any existing text file or remove files, create links or directories. It has a rich set of editing commands (AppendIfNoSuchLine, ReplaceAll, LocateLineMatching, InsertLine, HashCommentLinesContaining,...) and support the use of classes. If you have to create a new file or append many line to an exiting one, it's better to use perl or a shell script. Cfengine is also sensitive to undefined variables. A cfengine script does not get executed, if any of the used variables is undefinded. Hence, it's not useful if you have a variable number of parameters in your configuration (a famous example are the DNS server for <file>/etc/resolv.conf</file>). For copying files use <prgn>fcopy</prgn>. It's included in FAI and can handle classes Shell scripts are useful if most functions can be done by unix commands, or a single command (e.g. calling lilo) must be executed. There's a tradeoff between writing a few large script, which use definitions by cases or to write a single script for each class. It may also be useful to write two scripts, that together perform one task. Try to find the right way, and let us participate in your scripts. <sect1 id=isavelog>Save log files When all installation tasks are finished, the log files are written to <tt>/var/log/fai/$HOSTNAME/install/</tt> on the new system and to the install server, if <var>LOGUSER</var> is defined. <sect1 id=ireboot>Reboot new installed system At least the system is automatically reboot. Only usefull if booting from network card. Else you have to remove the floppy disk and type return or call <prgn>faireboot</prgn> from a remote login. Currently it's not possible to edit the BIOS from Linux, to change the boot device, so next time the host will boot from another device (local disk). <chapt id=config>The configuration The configuration is the collection information how to partition local hard disks, where to mount the filesystems, which software packages to install, and how to make local customization to the installation. The configuration space is located on the server in <file>/usr/local/share/fai</file> and is mounted by the install clients to <file>/fai</file>. Following subdirectories are available: <taglist>  <tag><tt>class/</tt></tag> <item> scripts and files to load kernel modules and define classes and variables </item> <tag><tt>disk_config/</tt></tag> <item> configuration files for disk partitioning and file system creation </item> <tag><tt>package_config/</tt></tag> <item> software packages to be installed or removed </item> <tag><tt>scripts/</tt></tag> <item> script for customization </item> <tag><tt>files/</tt></tag> <item> files used by customization scripts </item> </taglist> The main installation script <prgn>rcS_fai</prgn> uses these subdirectories in the listed order. <sect id=classes>Defining classes All defined classes are listed in <file>/tmp/FAI_CLASSES</file> and in the variable <var>$classes</var>. <sect id=diskconfig>Hard disk configuration Please read <file>/usr/share/doc/fai/README.disk_config.gz</file>. <sect id=packageconfig>Software package configuration Please read <file>/usr/share/doc/fai/README.package_config.gz</file>. <sect id=cscripts>Scripts in <tt>/fai/class</tt> <sect id=errors>Looking for errors If the installation process stops or even it finishes, parse all log files for errors using: <example> > egrep "no such variable|bad variable|E:|ERROR" *.log </example>   </book> </debiandoc>

%commondata; ]> FAI (Fully Automatic Installation) Guide NOT YET FINISHED ! <author>Thomas Lange <email>lange@informatik.uni-koeln.de</email> <version>ver. &version;, &date; <abstract> This manual describes the fully automatic installation package for &dgl;. This includes the installation of the package, the planing and creating of the configuration and how to deal with errors. <copyright> <copyrightsummary> Copyright © 2000-2001 Thomas Lange </copyrightsummary> This manual is free software; you may redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. 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 &file-GPL; in the &dgl distribution or on the World Wide Web at <url id="&url-gpl;" name="the GNU website">. You can also obtain it by writing to the &fsf-addr;. <toc detail="sect2"> <chapt id="motivation">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 time and again is boring -- and will surely lead to mistakes. Also a whole lot of time could be saved, if the installation were done automatically. An installation process with manual interaction does not scale. But clusters have the habit of growing over the years. Think long-term rather than plan only just a few months into the future. In 1999 I had to install a Linux cluster with one server and 16 clients. Since I had much experience doing automatic installation of Solaris operating system on SUN SPARC hardware, the idea to build an automatic installation for Debian was born. <chapt id="overview">Overview and concepts of FAI FAI is a non interactive system to install a &dgl operating system on a single computer or a whole cluster. You can take one or more virgin PC's, turn on the power and after a few minutes Linux is installed, configured and running on the whole cluster, without any interaction necessary. Thus, it's a scalable method for installing and updating a cluster unattended with little effort involved. FAI uses the &dgl; distribution and a collection of shell and perl scripts for the installation process. Changes to the configuration files of the operating system can be made by cfengine, shell, perl and expect scripts. FAI's target group are system administrators how have to install Debian onto one or even hundreds of computers. Because it's a general purpose installation tool, it can be used for installing a beowulf cluster, a rendering farm or a linux laboratory or a classroom. Also large-scale linux networks with different hardware or different installation requirements are easy to establish using FAI. First, some terms used in this manual, are described. <taglist> <tag> install server : <item> The host, where the package FAI is installed. It provides several services for all install clients. <tag>install client : <item> A host, which will be installed using FAI and a configuration from the install server. Also called client for short. </item> <tag> configuration : <item> The details, how the installation of the clients should be performed. This includes information about: <list> <item> Hard disk layout </item> <item> Local filesystems </item> <item> Software packages </item> <item> Keyboard layout, time zone, NIS, X11 configuration, remote filesystems, user accounts, printers ... </item> </list> <tag> nfsroot : <item> A filesystem located on the install server. It's the complete filesystem for the install client, which is mounted by the client during installation process.</item> </taglist> <sect id="work">How does FAI work ? The computer, which will be installed using FAI (called client), is booted from floppy disk or via network card. It gets an IP-address and boots a linux kernel which mounts all filesystems via NFS from the install server. After the operating system is running, the FAI startup script performs the automatic installation which doesn't need any interaction. First, the hard disks will be partitioned, filesystems are created and then software packages are installed. After that, the new installed operating system is configured to your local needs using some scripts. Finally the new oprating 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 multiple computers if the are similar. So you need not to create a configuration for every new host. Hence, FAI is a scalable method to install a big cluster with a great number of nodes. FAI can also be used as an network rescue system. You can boot your computer without performing an installation. Instead it will run a fully functional &dgl without using the local hard disks. Then you can do a remote login and backup or restore a disk partition, check a filesystem, inspect the hardware or do any other task. <sect id="features">Features of FAI <list> <item> </item> <item> A fully automatic installation can be perfomed </item> <item> Hosts can boot from floppy or from network card </item> <item> BOOTP and DHCP protocol are supported </item> <item> No initial ramdisk is needed, 8MB RAM suffice </item> <item> The installation kernel can use modules </item> <item> Remote login via ssh during installation process possible </item> <item> Two additional virtual terminals available during installation </item> <item> All similar configuration are shared among all install clients </item> <item> Log files are saved on to the installation server </item> <item> Shell, perl, expect and cfengine scripts are supported for the configuration </item> <item> Access to a Debian mirror via NFS, FTP or HTTP </item> <item> Very quick unattended installation </item> <item> Runs even on a 386 CPU (partially tested on SUN SPARC in 2001) </item> <item> Easy creation of boot floppy </item> <item> Keyboard layout selectable </item> <item> Can be used as a rescue system </item> <item> </item> </list> <chapt id="inst">Installing FAI <sect id="requirements">Requirements Following items are required for an installation via FAI. <taglist> <tag>A computer: </tag><item> with a network interface card XXX BOOTPROM</item> <tag>BOOTP or DHCP server: </tag><item> The clients need one of these daemons to obtain information.<footnote> It's also possible without a server, if all information a included on the boot disk. </footnote> </item> <tag>TFTP server:<item> The TFTP daemon is used for transfering the kernel to the clients. Only needed when booting from network card.</item> <tag>Debian mirror:<item> Access to a Debian mirror is needed. A local mirror of all Debian packages is recommended if you install multiple computers.</item> <tag>Install kernel image: <item> A kernel image that supports the network card and mounts its root filesystem via NFS. </item> <tag>Configuration space:<item> A mountable directory which contains the configuration data. </item> </taglist> The TFTP daemon and a NFS server will be enabled automatically when installing the FAI package. Different install kernel images for BOOTP and DHCP are available within the package. All clients must have a network card, which is recognized by the install kernel. The FAI package is available as a Debian package from &faidownload; until it will be an official Debian package soon. <sect id="debian-mirror">How to create a local Debian mirror There are two scripts available for creating a local partitial mirror in <file>/usr/share/doc/fai/examples/utils/</file>, <prgn>mkdebmirror</prgn> uses debmirror <httpsite>http://cvs.kitenet.net/</httpsite><httppath>joey-cvs/bin/debmirror</httppath>. Use these script for building a mirror only for i386 architecture. <sect id=aptsetup> Setting up FAI First, get the newest version of FAI and install it using the <prgn>dpkg</prgn> command: <example> kueppers[~]# dpkg -i fai_1.5.0_all.deb Selecting previously deselected package fai. (Reading database ... 39564 files and directories currently installed.) Unpacking fai (from fai_1.5.0_all.deb) ... Setting up fai (1.5.0) ... To set up FAI edit /etc/fai.conf and call fai-setup </example> All definitions for the FAI package are defined in &fc;. Since FAI doesn't use <prgn>debconf</prgn> yet, edit this file and call <prgn>fai-setup</prgn>. These are important variables in &fc;: <taglist> <tag><var>FAI_BASETGZ</var></tag> <item> The location, where the the base file is fetched from. For building the nfsroot, the Debian base system is needed. It's a big tar file (&basetgzsize for &basetgz) , which is a minimal collection of all required packages for Debian. It is not used, when a file &basetgz is already available in <file>/tmp</file>. Fetching via ftp or http could take much time, if you do not have a fast connection to your Debian mirror. You can find the current version in the directory <tt>debian/dists/stable/main/disks-i386/current/</tt> of your Debian mirror. </item> <tag><var>FAI_SOURCES_LIST</var></tag> <item> This multi line string is the definition for <file>sources.list</file> (used by <manref name="apt-get" section="8">), which defines the location and access method of the Debian mirror. For more information on the file format see <manref name="sources.list" section="5">. </item> <tag><var>FAI_DEBMIRROR</var></tag> <item> If you have NFS access to your local Debian mirror, specify the remote filesystem. It will be mounted to <var>$MNTPOINT</var>. It's not needed if you use FTP or HTTP access. </item> <tag><var>KERNELPACKAGE</var></tag> <item> You must specify the software package (build with <manref name="make-kpkg" section="8">), which includes the default kernel for booting the install clients. The Debian package <package>fai-kernels</package> contains the default install kernels with BOOTP and DHCP support.</item> <tag> <var>NFSROOT_PACKAGES</var></tag> <item> Contains a list of additional software package, that will be installed to nfsroot.</item> </taglist> FAI uses <manref name="apt-get" section="8"> to create the nfsroot filesystem in <file>/usr/lib/fai/nfsroot</file>, which needs about &nfsrootsize of free disk space. You should also install the package <package>fai-kernels</package>, which will be automaticlly installed when you use <prgn>apt-get</prgn> for installing FAI. <example> kueppers[~]# dpkg -i ~lange/fai-kernels_1.1_i386.deb Selecting previously deselected package fai-kernels. (Reading database ... 40562 files and directories currently installed.) Unpacking fai-kernels (from .../lange/fai-kernels_1.1_i386.deb) ... Setting up fai-kernels (1.1) ... </example> Before setting up FAI, you should get the program <prgn>imggen</prgn>, if you like to boot from a 3Com network card. This executable converts netboot images, so they can be booted by 3Com cards. You can get this compiled program from the download page &faidownload;. Put that executable in your path (e.g. <file>/usr/local/bin</file>). After editing &fc; call <prgn>fai-setup</prgn>. <example> kueppers[~]# fai-setup Adding system user fai... Stopping Name Service Cache Daemon: nscd. Adding new user fai (100) with group nogroup. Starting Name Service Cache Daemon: nscd. Creating home directory /home/fai. /home/fai/.rhosts created. User account fai created. Creating FAI nfsroot can take a long time and will need more than 100MB disk space in /usr/lib/fai/nfsroot. Unpacking /tmp/base2_2.tgz Upgrading /usr/lib/fai/nfsroot Adding additional packages to /usr/lib/fai/nfsroot: perl-5.005 dhcp-client file rdate cfengine bootpc wget rsh-client less dump ext2resize raidtools2 strace expect5.31 hdparm parted dnsutils grub ssh grep: /etc/ssh/sshd_config: No such file or directory grep: /etc/ssh/sshd_config: No such file or directory Not starting OpenBSD Secure Shell server (/etc/ssh/NOSERVER) make-fai-nfsroot finished. Stopping NFS kernel daemon: mountd nfsd. Unexporting directories for NFS kernel daemon...done. Starting NFS kernel daemon: nfsd mountd. Exporting directories for NFS kernel daemon...done. Kernel image file name = /usr/lib/fai/nfsroot/boot/vmlinuz-2.2.19 Output file name = /boot/fai/installimage Kernel command line = "auto rw root=/dev/nfs nfsroot=kernel nfsaddrs=kernel" Image Creator for MBA ROMs v1.00 Usage: imggen [OPTION] inputfile outputfile -a, Add 3Com MBA/BootWare support -r, Remove 3Com MBA/BootWare support from image file -i, Show information on an image -h, Help screen In filename: /boot/fai/installimage Out filename: /boot/fai/installimage_3com Adding MBA support... MBA support has been succesfully added You have no FAI configuration. Copy FAI template files with: cp -a /usr/share/doc/fai/templates/* /usr/local/share/fai Then change the configuration files to meet your local needs. FAI setup finished. </example> The setup routine adds lines to <file>/etc/exports</file> to export some directories to all hosts that belong to the netgroup faiclients. Netgroups are defined in <file>/etc/netgroup</file> or in the correspondening NIS map. An example for the netgroup file can be found in <file>/usr/share/doc/fai/examples/etc/netgroup</file>. For more information, read the manual pages <manref name="netgroup" section="5"> and the NIS HOWTO. After changing the netgroups , the nfs server has to reload its configuration. Use one of the following commands, depending on which nfs server you are using: <example> kueppers[~]# /etc/init.d/nfs-kernel-server reload kueppers[~]# /etc/init.d/nfs-server reload </example> The set up also creates the account <tt>fai</tt> ($LOGUSER). If you will boot from network card, you should change the primary group of this account, so this account has write permissions to <file>/boot/fai</file> in order to change symbolic links to the kernel image, that is bootet by a client. See also <file>/etc/fai.conf</file>. After that, FAI is installed successfully on your server, but has no configuration for the install clients. Start with the templates from <tt> /usr/share/doc/fai/templates</tt> using the copy command above and read <ref id="config">. Before you can set up a DHCP or BOOTP daemon, you should collect some network information of all your install clients. This is described in section <ref id="bootfloppy">. When you make changes to &fc or want to install a new kernel to nfsroot, the nfsroot has to be rebuild by calling <prgn>fai-setup</prgn>. <chapt id="booting">Preparing booting Before booting for the first time, you have to choose which medium you use for booting. You can use the boot floppy or configure the computer to boot via network card, which is much smarter. <sect id="nicboot">Configuring a 3Com network card If you have a 3Com network card that is equipped with a boot ROM by Lanworks Technologie or already includes the DynamicAccess Managed PC Boot Agent (MBA <footnote> see <httpsite>http://www.3com.com/</httpsite> <httppath>products/software/dynamicaccess/</httppath></footnote>) software, you can enter the MBA setup by typing <tt>Ctrl+Alt+B</tt> during boot. The setup will look like this: <example> Managed PC Boot Agent (MBA) v4.00 (C) Copyright 1999 Lanworks Technologies Co. a subsidiary of 3Com Corporation All rights reserved. =============================================================================== Configuration Boot Method: TCP/IP Protocol: BOOTP Default Boot: Network Local Boot: Enabled Config Message: Enabled Message Timeout: 3 Seconds Boot Failure Prompt: Wait for key =============================================================================== Use cursor keys to edit: Up/Down change field, Left/Right change value ESC to quit, F9 restore previous settings, F10 to save </example> Set the boot method to <tt>TCP/IP</tt> and the protocol to either <tt>BOOTP</tt> or <tt>DHCP</tt>. I prefer the BOOTP protocol. <sect id="pxeboot">Booting from network card with a PXE conforming boot ROM My notebook has an builtin Intel EtherExpress PRO 100 network interface card, with a fixed configuration for booting using the PXE protocol. This requires a PXE Linux boot loader. See <file>/usr/share/doc/syslinux/pxelinux.doc.gz</file> for more information, how to boot in such an environment. There are also some mail in the mailling list archive concerning this topic. <sect id="bootnetwork">Booting via network card Make a symbolic link from the hostname of your client to the appropriate kernel image in <file>/boot/fai</file>. The file <file>installimage_3com</file> is created by <prgn>imggen</prgn> and suitable for booting 3Com network cards. <example> kueppers[~]# cd /boot/fai kueppers[~]# ln -s installimage_3com bigfoot </example> <sect id="bootfloppy">Creating a boot floppy If your network card can't boot itself, you have to boot via floppy. Use the command <prgn>make-fai-bootfloppy</prgn> to create the boot floppy. Since there's no client specific information on this floppy, it's suitable for all your install clients. You can also specify additional kernel parameters for this boot floppy, it desired. See <example>make-fai-bootfloppy -h XX</example> for more information. If you have no BOOTP or DHCP server, supply the network configuration as kernel parameters: <footnote> For additional information see <file>/usr/src/linux/Documentation/nfsroot.txt</file> in the kernel sources. </footnote> <example>ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf> </example> <example>"nfsroot=<ip of install server>:/usr/lib/fai/nfsroot"</example> <sect id="mac">Collecting Ethernet addresses Now it's time to boot your install clients for the first time. They will fail to boot, because no BOOTP or DHCP daemon is running yet or recognizes the hosts. But you can use this first boot attempt to easily collect all Ethernet addresses of the network cards. You have to collect all Ethernet (MAC) addresses of the install clients and assign a hostname and IP address to each client. To collect all MAC addresses, now boot all your install clients. While the install clients are booting, they send broadcast packets to the LAN. You can log the MAC addresses of these hosts, if following command is running simultaneously on the server: <example># tcpdump -qte broadcast and port bootpc >/tmp/mac.lis</example> After the hosts has been sent some broadcast packets (they will fail to boot because <prgn>bootpd</prgn> isn't running or does not recognise the MAC address yet) abort <prgn>tcpdump</prgn> by typing <tt>ctrl-c</tt>. You get a list of all unique MAC addresses with these commands: <example># perl -ane 'print "\U$F[0]\n"' /tmp/mac.lis|sort|uniq</example> After that, you only have to assign these MAC addresses to hostnames and IP addresses (<file>/etc/ethers</file> and <file>/etc/hosts</file> or corresponding NIS maps). With these information you can configure your <prgn>BOOTP</prgn> or <prgn>DHCP</prgn> daemon (see the section <ref id="bootptab">). I recommend to write the MAC addresses (last three bytes will suffice if you have network card from the same vendor) and the hostname in the front of each chassis. <sect id=bootptab>Configuration of BOOTP daemon An example configuration for the BOOTP daemon is included in FAI. If you have no <file>/etc/bootptab</file> file you can use <file>/usr/share/doc/fai/examples/etc/bootptab</file> as template. <example> # /etc/bootptab example for FAI # replace FAISERVER with the name of your install server .faiglobal:\ :ms=1024:\ :hd=/boot/fai:\ :hn:bs=auto:\ :rp=/usr/lib/fai/nfsroot: # rp: $NFSROOT # your local values # # sa: your tftp server (install server) # ts: your timeserver (time enabled in inetd.conf) # T170 location of FAI configuration directory # T171 FAI_ACTION # T172 FAI_FLAGS, e.g. verbose, debug, reboot, sshd # T173 reserved for future use # T174 reserved for backup devices and backup options; NOT YET USED # sm: subnet mask # gw: router/gateway address # dn: domainname # ds: list of nameservers # these are optional # ys: NIS server # yd: NIS domainname # nt: list of NTP servers .failocal:\ :tc=.faiglobal:\ :sa=FAISERVER:\ :ts=FAISERVER:\ :T170="FAISERVER:/usr/local/share/fai":\ :T171="sysinfo":\ :sm=255.255.255.0:\ :gw=134.95.9.254:\ :dn=informatik.uni-koeln.de:\ :ds=134.95.9.136,134.95.100.209,134.95.100.208,134.95.140.208:\ :ys=rubens:yd=informatik4711.YP:\ :nt=time.rrz.uni-koeln.de,time2.rrz.uni-koeln.de: # now one entry for each install client bigfoot:ha=0x00105A240012:bf=bigfoot:tc=.failocal:T171="sysinfo":T172="sshd verbose debug ": ant01:ha=0x00105A000000:bf=ant01:tc=.failocal:T172="sshd": </example> Insert one line for each install client at the end of this file as done for bigfoot and ant01. Replace the string <tt>FAISERVER</tt> with the name of your install server. Then adjust the other network tags (<tt>sm, gw, dn, ds</tt>) to your local needs. The tags for NIS and time servers (<tt>yp, yd, nt</tt>) are optional. Tags with prefix <tt>T</tt> (starting from T170) are generic tags which are used to transfer some FAI specific data to the clients. It is important, that T171 (equivalent to variable <var>FAI_ACTION</var><footnote> Theses names are used in the main installation script <file>rcS_fai</file>. The configuration files for DHCP and BOOTP daemons use other names. Example: <var>FAI_ACTION</var> is equal to <tt>T171</tt> in bootptab or <tt>option-171</tt> in dhcp.conf. </footnote>. is set to <tt>sysinfo</tt> ! Later you can set it to <tt>install</tt>, in order to start the automatic installation. For more information see <manref name="bootptab" section="5"> and section (TODO: explain all tags). When you have created your <file>bootptab</file> file, you have to enable the BOOTP daemon once. It's installed but Debian does not enable it by default. Edit <file>/etc/inetd.conf</file> and remove the comment (the hash) in the line containing <tt>#bootps</tt>. Then tell <prgn>inetd</prgn> to reload its configuration. <example># /etc/init.d/inetd reload</example> I recommend to use the BOOTP daemon and protocol for booting because it automatically reloads the configuration file if any changes are made to it. The daemon for DHCP must always be manually restarted after changes to the configuration file are made <footnote> If you can't use one of these, there's also the possibility to supply all information via a file or compile them into the kernel, but it's easier to use a daemon. </footnote>. Now it's time to boot all install clients again! <sect id="boot">Boot messages These are the messages, when booting from floppy. <example> LILO Loading FAI-BOOTP. Uncompressing Linux... OK, booting the Kernel. Linux version 2.2.19 (root@kueppers) (gcc version 2.95.2 20000220 . . . </example> The rest of the boot message will be equal to those when booting from network card. When booting from network card you will see: <example> BOOTP. TFTP.... Linux Net Boot Image Loader Version 0.8.1 (netboot) . Uncompressing Linux... OK, booting the Kernel. Linux version 2.2.19 (root@kueppers) (gcc version 2.95.2 20000220 . . . Sending BOOTP requests ..... OK IP-Config: Got BOOTP answer from 134.95.9.149 IP-Config: Complete: device=eth0, addr=134.95.9.200, mask=255.255.255.0, gw=134.95.9.254, host=ant01, domain=informatik.uni-koeln.de, nis-domain=informatik4711.YP, bootserver=134.95.9.149, rootserver=134.95.9.149, rootpath=/usr/lib/fai/nfsroot . . . ------------------------------------------------------ FAI 1.5.0, XXXX XX, 2001 Fully Automatic Installation for Debian GNU/Linux Copyright (c) 1999-2001, Thomas Lange lange@informatik.uni-koeln.de ------------------------------------------------------ Press ctrl-c to interrupt FAI and to get a shell . . . Press <RETURN> to reboot or ctrl-c to execute a shell </example> There will be some error message from modprobe and insmod, but that doesn't matter. If you get the following error message, the kernel has no driver compiled in for your network card. Compile a new kernel which supports your network card. <example> IP-Config: No network devices available Partition check: hda: hda1 hda2 < hda5 hda6 hda7 hda8 > Root-NFS: No NFS server available, giving up. VFS: Unable to mount root fs via NFS, trying floppy. VFS: Insert root floppy and press ENTER </example> To compile a new kernel, start using the default kernel configuration of FAI. Call <prgn>make menuconfig</prgn> and add a driver in menu <tt>Network device support/Ethernet</tt> which supports your network card. Then create a Debian package using: <example> kueppers# cd /usr/src/linux kueppers# cp /usr/lib/fai/nfsroot/boot/config-2.2.19 .config kueppers# make menuconfig kueppers# make-kpkg clean kueppers# make-kpkg --revision BOOTP2 kernel-image </example> The created file is <file>/usr/src/kernel-image-2.2.19_BOOTP2_i386.deb</file>. Adjust the variable <var>KERNELPACKAGE</var> in &fc; and rebuild the nfsroot by calling. <example> kueppers# fai-setup </example> After that, you have to create a new boot floppy. Now your network card should be recognized and your host should boot correctly. <sect id="sysinfo">Collecting other system information Now the clients have booted with <var>FAI_ACTION</var> set to sysinfo. Type <tt>ctrl-c</tt> to get a shell or use <tt>Alt-F2</tt> or <tt>Alt-F3</tt> to open a virtual terminal, where you can log in as <tt>root</tt> with the password defined by <var>FAI_ROOTPW</var> in &fc;. Remote login is available via the secure shell. To log in from your server to the client (for eg. named ant01) use: <example>> ssh -l root ant01 Warning: Permanently added 'ant01,134.95.9.200' to the list of known hosts. root@ant01's password: </example> You have now a running Linux system without using the local hard disk. Use this as a rescue system, if your local disk are damaged or the computer can't boot properly from hard disk. You will get a shell and can execute various commands (dmesg, lsmod, df, lspci, ...). Look at the log file in <file>/tmp</file>. There you can find much information about the boot process. All log files from <file>/tmp </file> are also written to the server in the directory <tt>~fai/ant01/sysinfo/</tt><footnote>More general: <tt>~$LOGUSER/$HOSTNAME/$FAI_ACTION/</tt>. </footnote> A very nice feature is, that FAI mounts all filesystems (all fs types linux supports) it finds on the local disks read only. It also tells you on which partition a file <file>/etc/fstab</file> exists. When only one fstab is found, the partitions are mounted according to this information. Here's an example: <example> ant01:~# df Filesystem 1k-blocks Used Available Use% Mounted on /dev/root 1249132 855648 330032 72% / /dev/ram0 3963 36 3927 1% /tmp kueppers:/usr/local/share/fai 1249132 855648 330032 72% /fai /dev/hda1 54447 9859 41777 19% /tmp//target /dev/hda10 1153576 20 1141992 0% /tmp/target/files/install /dev/hda9 711540 20 711520 0% /tmp/target/home /dev/hda8 303336 13 300191 0% /tmp/target/tmp /dev/hda7 1517948 98252 1342588 7% /tmp/target/usr /dev/hda6 202225 8834 182949 5% /tmp/target/var </example> This method can be used as an rescue environment ! In future it will be possible to make backups or restore data to existing filesystems. If you need a filesystem with read-write access use: <example>ant01:~# rwmount /tmp/target/home</example> You can reboot the computer using the command <prgn>faireboot</prgn>. <chapt id=instprocess>The installation process FAI can perform several actions when the client is booting. This action is defined in the variable <var>FAI_ACTION</var> Be very carefully if you set <var>FAI_ACTION </var> to install. This can destroy all your data on the install client, indeed most time it should do this ;-). It's recommended to change this only on a per client base in the BOOTP configuration. Do not change it in the section <tt>.failocal</tt> in <file>/etc/bootptab</file>, which is a definition for all clients. <sect id=isequence>The installation sequence Following steps are performed during an installation after the linux kernel has booted on the install clients. <enumlist> <item> Set up FAI </item> <item> Load kernel modules </item> <item> Define classes </item> <item> Define variables </item> <item> Partitioning local disks </item> <item> Create and mount local filesystems </item> <item> Install software packages </item> <item> Call site specific configuration scripts </item> <item> Save log files </item> <item> Reboot the new installed system </item> </enumlist> <sect1 id=isetup>Set up FAI After the install client has booted the program <file>/sbin/rcS_fai</file><footnote>Since the root filesystem on the clients is mounted via NFS, <prgn>rcS_fai</prgn> is located in <file>/usr/lib/fai/nfsroot/sbin</file> on the install server. </footnote> is executed. This is the main script, that controls the sequence of tasks for FAI. A ramdisk is created and mounted to <file>/tmp</file>, which is the only writeable directory, until local filesystems are mounted. Additional parameters are received from the BOOTP or DHCP daemon <footnote>If these information daemons can't be used, FAI also reads definitions from <file>/fai/fai_config/global.conf</file> and <tt>/fai/fai_config/$HOSTNAME</tt>. This is done before and after <file>/fai</file> is mounted from the install server. So the first time the data will be read from <file>/usr/lib/fai/nfsroot/fai/fai_config</file> and after mounting <file>/fai</file> they are read from <file>/usr/local/share/fai/fai_config</file>. This is not the recommended way to specify the information. Use one the daemons instead if possible! </footnote> and all needed remote filesystems are mounted. The set up is finished after additional virtual terminals are created and the secure shell daemon is started on demand. <sect1 id=iclass>Define classes One of the most important feature of FAI are the classes. Using classes you can share configuration data among multiple clients. Details are described in <ref id="classes">.XXXX All define classes are listed in <file>FAI_CLASSES</file>. The main scripts executes all scripts in <file>/fai/class</file>, which name conforms matches <tt>S[0-9]*.{sh,pl}</tt>. Every word that these scripts print to the standard ouput are interpreted as class names. A complete description of all these scripts can be found in <ref id="cscripts">. The script <file>S05modules.sh</file> and all file with suffix <tt>.mod</tt> will load kernel modules but not define any class. Script ending in <tt>.var</tt> are used for defining variables, that are later used in the site specific configuration scripts. <sect1 id=ipartition>Partitioning local disks After all classes and variables are defined, one disk configuration file from <file>/fai/disk_config</file> is selected. It's a description how the local disks will be partitioned, which filesystems should be created or preserved and how they are mounted. Refer to XXXX for more information. This is done by the command <prgn>setup_harddisks</prgn>, which uses <prgn>sfdisk</prgn> for obtaining disk information and for partitioning. If <prgn>/usr/local/bin/my-fdisk</prgn> exists, this command is used instead. <sect1 id=imount>Create and mount local filesystems Creation is also done by <prgn>setup_harddisks</prgn>. Mounting the filesystems is done by the routine <tt>mount2target</tt>. It's possible to specify parameters for filesystems creation and also to give mount options. All local filesystems are mounted relativ to <file>/tmp/target</file> during the installation process. So, for eg. <file>/tmp/target/home</file> will become <file>/home</file> in the new installed system. A more detailed description is in XXXXX. In future, this command will be completely rewritten. Plans are to use <prgn>parted</prgn> and the device filesystems <tt>devfs</tt>. Then things are becoming much easier. <sect1 id=ipackages>Install software packages When local filesystems are created, they are all empty (except for preserved partitions). Now the Debian base system and all requested software packages must be installed on the new filesystems. First the base tar file is unpacked, then the command <prgn>install_packages</prgn> installes all packages witout any manually interaction needed. If a packages requires an other packages, <prgn>apt-get</prgn> resolves this dependency by installing the required package. <sect1 id=icscripts>Configuration scripts After all demanded software packages are installed, the system is nearly ready to go. But not all default configurations of the software packages will meet your site specific needs. So you can call arbitrary scripts, which adjust the configuration. Therefore scripts, that match a class name in <file>/fai/scripts</file><footnote> <file>/usr/local/share/fai/scripts</file> on the install server. </footnote> will be executed. FAI comes with some templates for these scripts, but you can write your own bourne/bash, perl, cfengine or expect scripts. Using cfengine, you can easily edit any existing text file or remove files, create links or directories. It has a rich set of editing commands (AppendIfNoSuchLine, ReplaceAll, LocateLineMatching, InsertLine, HashCommentLinesContaining,...) and support the use of classes. If you have to create a new file or append many line to an exiting one, it's better to use perl or a shell script. Cfengine is also sensitive to undefined variables. A cfengine script does not get executed, if any of the used variables is undefinded. Hence, it's not useful if you have a variable number of parameters in your configuration (a famous example are the DNS server for <file>/etc/resolv.conf</file>). For copying files use <prgn>fcopy</prgn>. It's included in FAI and can handle classes Shell scripts are useful if most functions can be done by unix commands, or a single command (e.g. calling lilo) must be executed. There's a tradeoff between writing a few large script, which use definitions by cases or to write a single script for each class. It may also be useful to write two scripts, that together perform one task. Try to find the right way, and let us participate in your scripts. <sect1 id=isavelog>Save log files When all installation tasks are finished, the log files are written to <tt>/var/log/fai/$HOSTNAME/install/</tt> on the new system and to the install server, if <var>LOGUSER</var> is defined. <sect1 id=ireboot>Reboot new installed system At least the system is automatically reboot. Only usefull if booting from network card. Else you have to remove the floppy disk and type return or call <prgn>faireboot</prgn> from a remote login. Currently it's not possible to edit the BIOS from Linux, to change the boot device, so next time the host will boot from another device (local disk). <chapt id=config>The configuration The configuration is the collection information how to partition local hard disks, where to mount the filesystems, which software packages to install, and how to make local customization to the installation. The configuration space is located on the server in <file>/usr/local/share/fai</file> and is mounted by the install clients to <file>/fai</file>. Following subdirectories are available: <taglist>  <tag><tt>class/</tt></tag> <item> scripts and files to load kernel modules and define classes and variables </item> <tag><tt>disk_config/</tt></tag> <item> configuration files for disk partitioning and file system creation </item> <tag><tt>package_config/</tt></tag> <item> software packages to be installed or removed </item> <tag><tt>scripts/</tt></tag> <item> script for customization </item> <tag><tt>files/</tt></tag> <item> files used by customization scripts </item> </taglist> The main installation script <prgn>rcS_fai</prgn> uses these subdirectories in the listed order. <sect id=classes>Defining classes All defined classes are listed in <file>/tmp/FAI_CLASSES</file> and in the variable <var>$classes</var>. <sect id=diskconfig>Hard disk configuration Please read <file>/usr/share/doc/fai/README.disk_config.gz</file>. <sect id=packageconfig>Software package configuration Please read <file>/usr/share/doc/fai/README.package_config.gz</file>. <sect id=cscripts>Scripts in <tt>/fai/class</tt> <sect id=errors>Looking for errors If the installation process stops or even it finishes, parse all log files for errors using: <example> > egrep "no such variable|bad variable|E:|ERROR" *.log </example>   </book> </debiandoc>