.\"                                      Hey, EMACS: -*- nroff -*-
.if \n(zZ=1 .ig zZ
.if \n(zY=1 .ig zY
.TH fai-cd 8 "Dez 2025" "FAI 6"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.de }1
.ds ]X \&\\*(]B\\
.nr )E 0
.if !"\\$1"" .nr )I \\$1n
.}f
.ll \\n(LLu
.in \\n()Ru+\\n(INu+\\n()Iu
.ti \\n(INu
.ie !\\n()Iu+\\n()Ru-\w\\*(]Xu-3p \{\\*(]X
.br\}
.el \\*(]X\h|\\n()Iu+\\n()Ru\c
.}f
..
.\"
.\" File Name macro.  This used to be `.PN', for Path Name,
.\" but Sun doesn't seem to like that very much.
.\"
.de FN
\fI\|\\$1\|\fP
..
.SH NAME
fai-cd \- make a bootable CD-ROM or USB stick that performs an FAI
.SH SYNOPSIS
.B fai-cd
[\fIOPTION\fR] \-m MIRROR \fIISOFILE\fR
.br
.B fai-cd
[\fIOPTION\fR] \-B \fIFILE\fR
.br
.B fai-cd
[\fIOPTION\fR] \-d \fIURL\fR
.br
.B fai-cd
[\fIOPTION\fR] \-S \fIIMAGEFILE\fR
.br
.SH DESCRIPTION
This command creates a bootable ISO CD-ROM image that performs the
fully automatic installation from the CD-ROM without an install server. The
ISO image will be written to FILE. To create the image the
command requires the NFSROOT, configuration space, and optionally a partial
mirror (which is created by fai-mirror). The ISO image will contain a compressed
squashfs filesystem. This hybrid CD image can
be written to an USB stick using dd(1).

NOTE: By default, fai-cd uses the grub file from /etc/fai/grub.cfg, which is
designed for demo purposes.  This grub menu passes the "menu" flag to the
FAI_FLAGS parameter, which causes a menu with various installation and
boot options to be displayed on each boot.  To avoid this, you must specify
your own grub file using the -g flag, as described below.

.SH OPTIONS
.TP
.BI \-A
Create a boot only CD image (also usable for an USB stick) with
autodiscover functionality. The CD will scan the subnet for a FAI
server. By default it shows a menu with all profiles available from
which you can select a type of installation. This image only needs 25MB.
You can add the -J option to make the image smaller.
.TP
.BI \-B
Create a boot only ISO image which does a network installation. It does not include the nfsroot, the
partial mirror and the config space; however for it to automatically
initiate the installation -d has to be set. By default CONFIG_SRC will
be empty.
.TP
.BI \-b
After creating the ISO image burn it by calling wodim(1) (a version of
cdrecord).
.TP
.BI "\-c " DIRECTORY
Override the value of FAI_CONFIGDIR set in nfsroot.conf.
.TP
.BI "\-C " DIRECTORY
Use DIRECTORY as the configuration directory instead of the default
/etc/fai. You can also set the environment variable FAI_ETC_DIR.
.TP
.BI "\-d " URL
Do not include the config space in the image. Instead set the variable
to the location of the config space to URL. This sets FAI_CONFIG_SRC in the grub config, which
is obtained from the FAI configuration dir (see -C). Set it to "" to not
set FAI_CONFIG_SRC at all. If not set, the config space is taken from
FAI_CONFIGDIR and copied to /var/lib/fai/config in the image. Currently
no file: is allowed here, instead set FAI_CONFIGDIR in nfsroot.conf(5).
.TP
.BI \-e
Exclude the directory /var/tmp from the nfsroot. You may put the
file base.tar.xz in the configuration space into the subdirectory
basefiles. This option will save about 50MB of disk space. This option
will exclude the directory even when \-H is given.
.TP
.BI \-f
Force removal of an existing ISO image before creating a new one.
.TP
.BI "\-g " FILE
Use FILE as the grub.cfg file. The script will look for FILE
in CFDIR. If FILE is located in another directory then a full path
must be specified. If not specified, use /etc/fai/grub.cfg.
.TP
.BI \-h
Show simple help and version.
.TP
.BI \-H
Do not hide directories. Using this option will consume about 45MB more
disk space on your media. By default, some directories like man pages
and locales are hidden and will not be put onto the CD or the USB stick.
.TP
.BI \-J
Use xz compression when calling mksquashfs. Default is zstd, which is
much faster.
.TP
.BI "\-M "
Do not add the package mirror to the CD. Packages that would be fetched
from the mirror are obtained from the normal sources configured
elsewhere, usually remote repositories.
.TP
.BI "\-m " DIRECTORY
Use DIRECTORY as partial FAI mirror. This option is mandatory, unless
you use -M or -B.
.TP
.BI "\-n " DIRECTORY
Override the value of NFSROOT set in nfsroot.conf.
.TP
.BI "\-s " blocks
This option is now unused and will be ignored.
.TP
.BI \-S
Create a squashfs image file instead of a complete iso. The image
contains the nfsroot and can be fetched through various ways over the
network. For an example, see the section "FAI without NFS" in the FAI
Guide.
.TP
.BI \-V
Set the volume id of the ISO. Default id is FAI_CD. You also must
adjust the CDLABEL in /etc/fai/grub.cfg, or use -g and specify
your own grub.cfg.
.SH EXAMPLES
.br
After you've created a mirror with fai-mirror in /media/mirror, you
can create a CD using:

   # fai-cd \-m /media/mirror fai-cd.iso

If you want to create a bootable USB stick (here /dev/sdf), write the
CD image to the stick via dd(1).

   # dd if=fai-cd.iso of=/dev/sdf bs=1M


\&\fBBuilding a live ISO\fR:

You can create a live ISO using two FAI commands. First, you need to build
your own live environment, containing all software including
configuration that you like to use. Using the command "fai dirinstall"
you do an installation using the FAI config space into a directory
which will become your live system. After that you create a bootable
ISO which includes this directory tree.

Define the FAI classes:

cl="DEBIAN,BOOKWORM64,AMD64,FAIBASE,XFCE,XORG,DHCPC,DEMO,LIVEISO,LAST"

Build the live environment directory tree:

  # LC_ALL=C fai \-v dirinstall \-u xfce33 \-c $cl \\
    \-s file:///srv/fai/config /srv/xfce

Then create the live ISO:

  # fai-cd \-s500 \-MH \-d none \-g /etc/fai/grub.cfg.live \\
    \-n /srv/xfce live.iso

Hint: The FAI nfsroot is not needed when building a live ISO.

\&\fBMore advanced usage\fR:

You can build a special installation ISO for an USB stick that contains
the config space on a writeable partition instead inside the read-only
ISO. The log files of the installations will be save to this partition.
After you have created the mirror in /tmp/mirror, build the ISO using
the following two commands:

   # fai-cd -d detect:// -m /tmp/mirror fai.iso
   # mk-data-partition -c fai.iso /srv/fai/config

After that copy this ISO onto the USB stick.

It is possible to install over the network without using NFS, i.e. by
getting the nfsroot via an http request. To do so you have to create a
squashfs image using the following command:

   # fai-cd \-S squashfs.img

In addition to that you can create said image without a config space
and without a mirror. This is useful for when you want to avoid
creating a new image after modifying your config space or
updating your mirror:

   # fai-cd \-d "" \-SMeJ squashfs.img

To fetch the image via http, use the following kernel command line
option:

   root=live:http://your_server_or_IP/path/to/squashfs.img

Create the autodiscover boot image:

   # fai-cd \-JAg /etc/fai/grub.cfg.autodiscover fai-autod.iso

Create a minimalistic compressed network boot ISO image (~60MB)
without nfsroot, the partial mirror and basefiles:

   # fai-cd -BMJe fai-cd.iso

This ISO image can even be further reduced in size using the -s flag to fai-make-nfsroot(8).

Specify your own grub file:

   # fai-cd -g /srv/fai/config/my_extras/grub.cfg -m /srv/fai/mirror /srv/fai/iso/fai-cd.iso

.SH NOTES
Additional kernel command line options can be found in the man page of
dracut.cmdline(7). fai-cd needs enough disk space in TMPDIR (/tmp by
default) for creating the compressed filesystem. You may want to set
it to another directories, before calling fai-cd.

.SH SEE ALSO
.br

.BR fai\-mirror(1)

.BR mksquashfs(1)

.BR fai-make-nfsroot(8)
.SH FILES
.PD 0
.TP
.FN /etc/fai/fai.conf
The FAI configuration file.
.TP
.FN /etc/fai/grub.cfg
The default grub2 menu configuration file for fai-cd.
.SH AUTHOR
Thomas Lange <lange@cs.uni-koeln.de>