### FAI Task: setup

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Details the 'setup' task, which configures system time, defines FAI flags, and optionally starts virtual terminals and a secure shell daemon.

```APIDOC
setup::
  - Sets the system time.
  - Defines all +$FAI_FLAGS+.
  - Opens two additional virtual terminals on demand.
  - Starts a secure shell daemon on demand for remote logins.
```

--------------------------------

### PXELINUX Configuration Example

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Example content of a `pxelinux.cfg` file, specifying kernel and boot parameters for PXE booting.

```APIDOC
default fai-generated

label fai-generated
kernel vmlinuz-6.1.0-17-amd64
```

--------------------------------

### Update APT and Install FAI Quickstart

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Updates the APT package list and installs the 'fai-quickstart' package, which includes necessary FAI components and server daemons like DHCP, TFTP, and NFS. This command follows the repository setup.

```bash
# apt-get update
# aptitude install fai-quickstart
```

--------------------------------

### Run Initial FAI Setup

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Executes the FAI setup utility with verbose output. This command initiates the FAI installation and configuration process, displaying detailed logs.

```shell
# fai-setup -v
```

--------------------------------

### FAI Client PXE Boot Command

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Example command to initiate the FAI installation for a client host, specifying the configuration source and boot parameters.

```shell
$ fai-chboot -IFv -u nfs://faiserver/srv/fai/config demohost

Booting kernel vmlinuz-4.19.0-5-amd64
 append initrd=initrd.img-4.19.0-5-amd64 ip=dhcp
   FAI_FLAGS=verbose,sshd,createvt FAI_CONFIG_SRC=nfs://faiserver/srv/fai/config

demohost has 192.168.33.100 in hex C0A82164
Writing file /srv/tftp/fai/pxelinux.cfg/C0A82164 for demohost
```

--------------------------------

### FAI Installation Tasks

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Lists the predefined tasks executed sequentially during a FAI installation process. These tasks cover various stages from initial setup and configuration to software installation and final cleanup.

```APIDOC
FAI Tasks:
  confdir		# get the config space
  setup			# some initialization, start sshd on demand
  defclass		# define FAI classes
  defvar		# define variables
  action		# evaluate FAI_ACTION
  install		# Start the installation
  partition		# partition the harddisks, create file systems
  mountdisks		# mount the file systems
  extrbase		# extract the base.tar.xz
  debconf		# do the Debian debconf preseeding
  repository		# prepare access to the package repository
  updatebase		# Set up package tools and update packages
  instsoft		# install software packages
  configure		# call customization scripts
  finish		# do some cleanup, show installation statistics
  tests			# call tests if defined
  chboot		# call fai-chboot on the install server
  savelog		# save log files to local and remote location
  faiend		# reboot host, eject CD if needed
```

```APIDOC
Additional FAI Tasks (Conditional Execution):
  dirinstall 	       # install a chroot environment
  softupdate	       # only do the system configuration
  sysinfo              # print detailed system information
  inventory            # print short hardware inventory list
```

--------------------------------

### Copy Example DHCP Configuration

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Copies an example DHCP server configuration file from the fai-doc package to the system's DHCP configuration directory. This provides a template for network booting.

```shell
# cp /usr/share/doc/fai-doc/examples/etc/dhcpd.conf /etc/dhcp/
```

--------------------------------

### DHCP Server Configuration Example

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

An example configuration for a DHCP server (dhcpd.conf) tailored for FAI PXE booting. It specifies the next-server, filename for the bootloader, and network parameters.

```config
deny unknown-clients;
option dhcp-max-message-size 2048;
use-host-decl-names on;

subnet 192.168.33.0 netmask 255.255.255.0 {
   option routers 192.168.33.250;
   option domain-name "my.example";
   option domain-name-servers 192.168.33.250;
   option time-servers faiserver;
   option ntp-servers faiserver;
   server-name faiserver;
   next-server faiserver;
   filename "fai/pxelinux.0";
}
```

--------------------------------

### Start FAI Client VM with KVM

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Starts additional virtual machines that act as FAI clients. These clients are configured to boot via PXE and are assigned unique network identifiers (e.g., -u 2, -u 3) for distinct MAC addresses and disk images.

```shell
fai-kvm -Vn -u 2 pxe
```

```shell
fai-kvm -Vn -u 3 pxe
```

--------------------------------

### Create Disk Image for Ubuntu Desktop (Example 2)

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Creates a disk image named 'ubuntu.qcow2' for a Ubuntu 16.04 desktop with hostname 'foobar'. It sets the FAI_BASEFILEURL and defines a class list for the installation.

```shell
# export FAI_BASEFILEURL=https://fai-project.org/download/basefiles/
# cl=DHCPC,UBUNTU,JAMMY,JAMMY64,AMD64,XORG,LAST
# fai-diskimage -Nvu foobar -S5G -c$cl ubuntu.qcow2
```

--------------------------------

### FAI NFS Root Configuration Example

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Example command to create an NFS root for a specific FAI configuration directory, typically used for serving diskless clients.

```bash
faiserver#fai-make-nfsroot -C /etc/fai-buster
```

--------------------------------

### FAI HTTP PXE Boot Setup

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Steps to enable HTTP access for kernel and initrd transfers during PXE boot with FAI, and how to specify the HTTP URL in the fai-chboot command.

```bash
cd /var/www/html
ln -s /srv/tftp/fai
```

```bash
fai-chboot -U http://faiserver/fai -IFv .......
```

--------------------------------

### FAI Log Symlink Structure

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Example structure of FAI log directories and symlinks, showing how system information is organized on the server.

```shell
lrwxrwxrwx   1 fai fai   23 Dec  2  2013 last-sysinfo -> sysinfo-20131202_161237
drwxr-xr-x   2 fai fai 4096 Dec  2  2013 sysinfo-20131202_161237
drwxr-xr-x   2 fai fai 4096 Feb 14  2014 install-20140214_142150
drwxr-xr-x   2 fai fai 4096 Dec  2 11:47 install-20141202_113918
lrwxrwxrwx   1 fai fai   23 Dec  4 13:22 last-install -> install-20141204_131351
lrwxrwxrwx   1 fai fai   23 Dec  4 13:22 last -> install-20141204_131351
drwxr-xr-x   2 fai fai 4096 Dec  4 13:22 install-20141204_131351
```

--------------------------------

### Idempotent Scripting Example

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Illustrates how to ensure customization scripts are idempotent. Avoids simple appends to files; suggests using specific commands or functions for safe modifications.

```shell
# Incorrect: Appending directly can lead to duplicate lines
# echo "some strings" >> /etc/fstab

# Correct: Use idempotent commands or functions like ainsl or _AppendIfNoSuchLine_
```

--------------------------------

### install Command Description

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Details the `install` command's behavior, primarily using `apt-get`. It explains how to install packages, remove them by appending a hyphen, and how FAI handles misspellings and non-existent packages.

```FAIConfig
install::
  # Installs packages using `apt-get`.
  # Append '-' to package name for removal.
  # Handles misspellings and removes non-existent packages from the list.
```

--------------------------------

### Run FAI Setup for NFS Root

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Executes the 'fai-setup' command, which internally calls 'fai-make-nfsroot' to create the NFS root filesystem for client installations. It logs output to /var/log/fai/fai-setup.log.

```bash
fai-setup
```

--------------------------------

### Start FAI Server VM with KVM

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Launches the first virtual machine intended to be the FAI server. It uses the fai-kvm tool, specifying no GUI (-Vn), a disk size of 20GB (-s20), and a user/network identifier of 1 (-u 1), booting from a specified ISO image.

```shell
fai-kvm -Vn -s20 -u 1 cd faicd64-small.iso
```

--------------------------------

### FAI Task: updatebase

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Describes the 'updatebase' task, which updates base packages, package lists, and uses dpkg-divert to prevent daemons from starting during installation.

```APIDOC
updatebase::
  - Updates base packages of the new system.
  - Updates the list of available packages.
  - Uses `dpkg-divert(8)` to fake commands (diversions) to prevent daemons from starting during installation.
```

--------------------------------

### DHCP Host Entry Example

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Demonstrates the expected format of a host entry in the dhcpd.conf file after using a command like dhcp-edit to configure a client.

```shell
host demohost {
  hardware ethernet 01:02:03:AB:CD:EF;
  fixed-address demohost;
}
```

--------------------------------

### Create FAI Configuration Space

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Initializes the FAI configuration space using the fai-mk-configspace command. This command sets up example host configurations for different installation profiles.

```shell
$ fai-mk-configspace
```

--------------------------------

### FAI Task: install

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Details the 'install' task, responsible for controlling the installation sequence, calling other tasks, and managing log files.

```APIDOC
install::
  - Controls the installation sequence.
  - Emits three beeps before starting the installation.
  - Calls other tasks to perform the installation.
  - Saves output to '/tmp/fai/fai.log'.
  - Log files for troubleshooting are located in '/tmp/fai/'.
```

--------------------------------

### FAI Task: inventory

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Provides a brief description of the 'inventory' task, which prints a short list of system information.

```APIDOC
inventory::
  - Prints a short list of system information.
```

--------------------------------

### taskinst Command Description

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Details the `taskinst` command, which installs packages belonging to specified tasks using `tasksel(1)`. It also mentions the possibility of using `aptitude` for task installation.

```FAIConfig
taskinst::
  # Installs packages associated with tasks using `tasksel`.
  # Can also use `aptitude` for task installation.
```

--------------------------------

### Install QEMU Packages

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Installs essential QEMU packages required for KVM virtualization. This command needs to be executed with root privileges.

```bash
# apt-get install qemu-system-gui qemu-kvm qemu-utils
```

--------------------------------

### Monitor FAI Client Installations

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Command to monitor multiple FAI client installations using `fai-monitor` and pipe output to `fai-monitor-gui` for a graphical frontend.

```shell
$ fai-monitor | fai-monitor-gui - &
```

--------------------------------

### FAI Task: partition

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Details the 'partition' task, which uses 'setup-storage(8)' to partition disks, create file systems, and define partition variables.

```APIDOC
partition::
  - Calls `setup-storage(8)` to partition hard disks and create file systems.
  - Writes variable definitions for root and boot partitions (+$ROOT_PARTITION, $BOOT_PARTITION, $BOOT_DEVICE+) to '/tmp/fai/disk_var.sh'.
  - Creates an 'fstab' file for the new system.
```

--------------------------------

### FAI Troubleshooting: Boot Errors

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Guides on diagnosing and resolving common boot errors encountered during FAI installations, including DHCP failures and network card driver issues.

```APIDOC
Troubleshooting Boot Errors:

  PXE-E51: No DHCP or BOOTP offers received
    Indicates the install client is not receiving responses from a DHCP server.
    Action: Check network cables, verify `dhcpd(8)` daemon status and debug flags.

  Missing Network Card Driver:
    Symptoms: Install kernel fails to detect the network card (e.g., no 'Starting dhcp for interface eth0' message).
    Action:
      1. Check initrd: Use `lsinird` to verify if the kernel driver is included.
      2. Add firmware: Include 'firmware-linux-nonfree' in `/etc/fai/NFSROOT` and rebuild initrd with `fai-make-nfsroot -k`.
      3. Add driver to dracut: Modify `/srv/fai/nfsroot/etc/dracut.conf` by adding the driver to `add_drivers+=`.

  NFS Access Denied:
    Symptoms: Client boots but fails to mount the NFS root, showing 'mount.nfs: access denied by server'.
    Cause: Missing NFS permissions on the server side.
    Action:
      1. Verify exports: On the FAI server, run `$ showmount -e faiserver` to check exported directories.
      2. Debug shell: The error message indicates a drop to a dracut emergency shell, where log files can be inspected.
      3. Dracut debugging: Refer to `dracut.cmdline(7)` for early boot process debugging with dracut.
```

--------------------------------

### Create Raw Disk Image for VM (Example 1)

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Generates a raw disk image for a host named 'cloud3' with specific software packages. It requires setting the FAI_BASEFILEURL environment variable and uses fai-diskimage with various options.

```shell
# export FAI_BASEFILEURL=https://fai-project.org/download/basefiles/
# fai-diskimage -vu cloud3 -S2G -cDEBIAN,BOOKWORM64,AMD64,FAIBASE,GRUB_PC,DHCPC,DEMO,CLOUD,LAST disk.raw
```

--------------------------------

### FAI Command Line Utilities

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Collection of FAI-related command-line utilities for managing installations and client configurations. Includes commands for remote execution, log saving, and controlling client reboots.

```APIDOC
fai-chboot(8):
  Manages boot device configurations for FAI clients.
  Allows defining PXELINUX configurations to control whether an installation is performed or if the client boots from local disk.

savelog::
  Saves log files to local disk and a remote server.
  Logs are stored on the local disk and to the account +$LOGUSER+ on +$LOGSERVER+.

faiend::
  Waits for background jobs to complete and manages client reboots.
  Can automatically reboot install clients or wait for manual input after background tasks like compiling Lisp files are finished.
```

--------------------------------

### FAI Task: instsoft

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Explains the 'instsoft' task, which installs software packages using configuration files from '$FAI/package_config/'.

```APIDOC
instsoft::
  - Installs desired software packages.
  - Uses class files located in '$FAI/package_config/'.
```

--------------------------------

### FAI Task: dirinstall

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Explains the 'dirinstall' task, used for installing FAI into a directory, typically for creating chroot environments.

```APIDOC
dirinstall::
  - Installs FAI into a directory, not directly onto a local disk.
  - Primarily used for creating chroot environments.
```

--------------------------------

### SSH Login to Install Client

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Demonstrates how to log in to an install client using SSH with the root user. Requires the SSH daemon to be running on the client and the correct hostname or IP address. The default password during installation is 'fai'.

```shell
$ ssh root@demohost
Warning: Permanently added 'demohost,192.168.33.100' to the list of known hosts.
root@demohost's password: 
```

--------------------------------

### FAI Task: finish

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Explains the 'finish' task, which unmounts file systems and removes file diversions after the installation process.

```APIDOC
finish::
  - Unmounts all file systems in the newly installed system.
  - Removes file diversions using the `fai-divert` command.
```

--------------------------------

### install-norec Command Description

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Explains the `install-norec` command, which is similar to `install` but explicitly avoids installing recommended packages.

```FAIConfig
install-norec::
  # Installs packages without their recommended dependencies.
```

--------------------------------

### PACKAGES Command with Package Manager Options

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Shows how to specify additional parameters for the package manager directly within the `PACKAGES` line. The `release=<name>` option, for example, allows targeting specific distribution releases.

```FAIConfig
PACKAGES install-norec release=testing
nvidia-smi
```

--------------------------------

### Install Packages for Qemu/KVM Network

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

This snippet shows the command to install necessary packages for creating a network using the fai-kvm wrapper with Qemu/KVM. It's a prerequisite for setting up a private network for FAI server and client virtual machines.

```shell
First install some packages

----
```

--------------------------------

### aptitude-r Command Description

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Describes the `aptitude-r` command, which is equivalent to using `aptitude` with the `--with-recommends` option.

```FAIConfig
aptitude-r::
  # Same as `aptitude` with the `--with-recommends` option.
```

--------------------------------

### FAI Task: sysinfo

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Explains the 'sysinfo' task, executed when the action is 'sysinfo', which displays hardware information and mounts local disks for inspection.

```APIDOC
sysinfo::
  - Executed when the action is _sysinfo_ (no installation).
  - Shows detected hardware information.
  - Mounts local hard disks read-only to '/target/+partitionname+' or based on an 'fstab' file.
  - Stores log files on the install server.
```

--------------------------------

### FAI Log Files Overview

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Lists common log files generated by FAI during installation and their typical locations on the client and server. These logs are crucial for debugging and monitoring the installation process.

```APIDOC
FAI Log Files:

  Location on Install Client (during install): /tmp/fai/
  Location on Install Client (after reboot): /var/log/fai/
  Location on FAI Server (remote logs): ~fai/

  Common Log Files:
    FAI_CLASSES:: Contains a list of all classes defined.
    dmesg.log:: Output of the `dmesg` command, kernel ring buffer messages.
    fai.log:: The main log file with all important information.
    boot.log:: Network parameters, often defined by DHCP.
    format.log:: Output of the partition tool `setup-storage(8)`.
    scripts.log:: Output of all customization scripts.
    variables.log:: List of all shell variables available during installation.
    error.log:: Summary of common errors found in other log files.
    disk_var.sh:: Variables containing device, partition, and root info for booting.

  Post-installation hook 'savelog.LAST.sh' searches logs for errors and writes to 'error.log'. 'status.log' shows exit codes of the last executed command.
```

--------------------------------

### Process Monitoring Tools

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Tools like top(1) and pstree(1) can be used to identify processes that are running and potentially blocking an installation, especially when manual input is required.

```shell
top(1)
```

```shell
pstree(1)
```

--------------------------------

### Setup Private Network with FAI

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Configures a private network using a software bridge and tap devices associated with a specific username. This is a prerequisite for running FAI KVM virtual machines.

```shell
fai-mk-network <username>
```

--------------------------------

### FAI dirinstall Action for Chroot/Virtualization (APIDOC)

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Explains the FAI `dirinstall` action, which allows FAI installations directly into a specified target directory. This is useful for creating chroot environments or virtualization guests without traditional partitioning.

```APIDOC
FAI dirinstall Action:

Purpose:
To perform a FAI installation directly into a target directory, bypassing the standard partitioning and formatting steps. Ideal for creating chroot environments or virtualization guest systems (e.g., Xen guests).

Command Syntax:
`faiserver# fai <options> dirinstall <target-directory>`

Options:
- `-c <classes>`: Specify FAI classes to use for the installation.
- `-N`: Use this option (or `-c <classes>`) to initiate the installation without the partitioning action.

Example:
`faiserver# fai -c myclass dirinstall /mnt/mychroot`

This command installs the system defined by `myclass` into the `/mnt/mychroot` directory. The host name for the target installation can also be specified.
```

--------------------------------

### FAI Hook Execution Example

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

A sample FAI hook script for the DEFAULT class that checks if a more specific hook for the current hostname exists. If a hostname-specific hook is found, the DEFAULT hook exits to avoid redundant execution.

```shell
hookexample.DEFAULT:

#! /bin/sh

# skip DEFAULT hook if a hook for $HOSTNAME exists
scriptname=$(basename $0 .DEFAULT)
[-f $FAI/hooks/$scriptname.$HOSTNAME ] && exit
```

--------------------------------

### FAI Task: repository

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Details the 'repository' task, which prepares package repository access by configuring apt and adding repository keys.

```APIDOC
repository::
  - Prepares access to the package repository.
  - Configures apt sources.
  - Adds repository keys from files like _CLASSNAME.gpg_ in the _package_config_ directory, in a class-based manner.
```

--------------------------------

### Create FAI SquashFS Image (Shell)

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Creates a squashfs image using `fai-cd` with options to avoid partial mirrors. This image can then be served via HTTP for FAI installations without NFS.

```shell
faiserver# fai-cd -M -S squash.img
```

--------------------------------

### aptitude Command Description

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Explains the `aptitude` command, which uses the `aptitude` package manager. It's noted as a future default and can also install task packages.

```FAIConfig
aptitude::
  # Installs packages using the `aptitude` command.
  # Can also install task packages.
```

--------------------------------

### Rebooting with FAI

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Use the `faireboot` command instead of the standard reboot command for managing computer reboots during or after FAI installations. The `-s` option preserves log files on the install server if the installation is not yet finished.

```shell
faireboot
faireboot -s
```

--------------------------------

### Installing Software Packages

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

The `install_packages(8)` command installs software packages using tools like `apt-get`, `aptitude`, or `yum`. It reads configuration from `$FAI/package_config` in a class-based manner and can also install local `.deb` or `.rpm` files from `$FAI/pkgs/<CLASSNAME>` directories.

```APIDOC
Package Installation Command: install_packages(8)

Purpose: Installs software packages automatically.

Configuration Source: Reads package lists from '$FAI/package_config' based on defined classes.

Package Managers Supported: apt-get(8), aptitude(1), yum, and others.

Local Packages: Installs '.deb' or '.rpm' files found in '$FAI/pkgs/<CLASSNAME>' directories.

Dependencies: Package manager resolves dependencies automatically.

See <<packageconfig>> for configuration file format.
```

--------------------------------

### FAI Task: extrbase

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Details the 'extrbase' task, which extracts a minimal system tarball for chroot environments, supporting custom base files.

```APIDOC
extrbase::
  - Extracts a minimal system for chroot environments.
  - By default, extracts '/var/tmp/base.tar.xz'.
  - Can use files matching class names in `$FAI/basefiles/` to extract different tar files.
  - Supports fetching base files via FTP, HTTPS, or HTTP using the +FAI_BASEFILEURL+ variable.
  - The default 'base.tar.xz' is a Debian snapshot created by `debootstrap(8)`.
```

--------------------------------

### PRELOADRM and PRELOAD Commands

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Explains the use of `PRELOADRM` and `PRELOAD` commands to download files before package installation. `PRELOADRM` removes the downloaded file after installation, while `PRELOAD` leaves it.

```FAIConfig
# Download and remove after install
PRELOADRM wget(1) /path/to/archive.tar.gz

# Download and keep after install
PRELOAD wget(1) /path/to/archive.tar.gz
```

--------------------------------

### FAI Task Error Handling

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Demonstrates how to signal errors during FAI installations using the `task_error` function. Explains how error values are categorized and how they affect installation abortion based on $STOP_ON_ERROR.

```APIDOC
task_error <value> [$?_exit_code] [1_non_sh_script]

  Description:
    Signals an error value to the FAI installation process. The error value is logged and checked against the $STOP_ON_ERROR variable.

  Parameters:
    - value: The error code to report.
    - $?_exit_code (optional): If provided, the error is only set if the preceding command failed (exit code is non-zero).
    - 1_non_sh_script (optional): Use '1' as the third parameter for scripts not ending in .sh to ensure the error value is always set.

  Error Categories:
    - 1xx, 2xx: Normal or info messages
    - 3xx, 4xx: Warnings
    - 5xx, 6xx: Minor errors
    - 7xx, 8xx: Errors

  Installation Abort:
    If the reported error value is greater than $STOP_ON_ERROR (default 700), the installation will stop immediately.

  Examples:
    # Report error 123
    task_error 123

    # Report error 123 only if the previous command failed
    <some command>
    task_error 123 $?

    # Report error 123 in a non-.sh script, always setting the error
    task_error 123 1 1
```

--------------------------------

### FAI Boot Control Commands

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Commands related to controlling the FAI installation client's boot behavior and managing system reboots.

```APIDOC
fai-chboot -d <hostname>
  - Disables the PXELINUX configuration for the specified hostname.
  - Prevents the client from restarting the installation during the next boot.

FAI Flags (e.g., +$FAI_FLAGS+)
  - 'reboot': Automatically reboots the system after installation if specified.
  - '+FAI_LOGPROTO+': Variable in 'fai.conf(5)' to choose log saving methods (e.g., scp).
```

--------------------------------

### FAI Installation Boot Parameters

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Kernel boot parameters used to initiate a FAI installation. These parameters specify network configuration, root filesystem location, FAI operational flags, and the configuration source.

```shell
append initrd=initrd.img-6.1.0-17-amd64 ip=dhcp root=/srv/fai/nfsroot rootovl FAI_FLAGS=verbose,sshd,createvt FAI_CONFIG_SRC=nfs://faiserver/srv/fai/config FAI_ACTION=install
```

--------------------------------

### Create Partial Mirror for 32-bit

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Command to create a partial mirror for bootable media, specifying the architecture. This is useful for creating CDs or USB sticks for 32-bit installations.

```shell
$ fai-mirror -m800 -B -a i386 -v -cDEFAULT,DEBIAN,FAIBASE,I386 /srv/mirror-i386
```

--------------------------------

### FAI Task: debconf

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Explains the 'debconf' task, which uses 'fai-debconf(1)' to set values in the debconf preseeding database.

```APIDOC
debconf::
  - Calls `fai-debconf(1)`.
  - Sets values for the debconf preseeding database.
```

--------------------------------

### FAI CD/USB Creation with fai-cd

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Command to create a bootable FAI installation CD or USB stick. It requires a partial mirror of Debian packages and specifies the output ISO file.

```shell
fserver# fai-cd -m <partialMirrorDir> fai-cd.iso
```

--------------------------------

### FAI Task: chboot

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Details the 'chboot' task, which modifies PXE configuration on the install server to specify the PXELINUX configuration for the next network boot.

```APIDOC
chboot::
  - Changes the PXE configuration for a host on the install server.
  - Specifies which PXELINUX configuration to load on the next network boot.
```

--------------------------------

### Automating Post-installation Scripts with fai-divert

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Use fai-divert to automate installations when post-installation scripts require manual input. This command can fake configuration programs, allowing for fully automatic installations.

```shell
fai-divert -a
```

--------------------------------

### PACKAGES Command with FAI Class Conditions

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Illustrates how to control package installation based on FAI classes using boolean expressions. Packages are installed only if the specified class conditions (e.g., `XORG` is defined, `MINT` is not) are met.

```FAIConfig
PACKAGES install UBUNTU && XORG && ! MINT
ubuntu-standard
ubuntu-desktop
```

--------------------------------

### FAI Task: softupdate

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Describes the 'softupdate' task, which performs system updates via the 'fai(8)' command-line interface.

```APIDOC
softupdate::
  - Executes a softupdate within a running system using the `fai(8)` command.
  - Refer to chapter <<softupdate>> for detailed information.
```

--------------------------------

### Add FAI Project Repository (wget)

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Adds the FAI project's GPG key and repository definition using wget and echo commands for APT package management. This method is used to prepare the system to install FAI packages.

```bash
# wget -O /etc/apt/trusted.gpg.d/fai-project.gpg https://fai-project.org/download/2BF8D9FE074BCDE4.gpg
# echo "deb http://fai-project.org/download bookworm koeln" > /etc/apt/sources.list.d/fai.list
```

--------------------------------

### Build Cross-Architecture Disk Image (aarch64)

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Builds a disk image for a 64-bit ARM architecture (aarch64) on an amd64 host. This requires installing QEMU and related FAI packages, setting FAI_BASEFILEURL, and using fai-diskimage with architecture-specific classes.

```shell
# apt install qemu-system-arm qemu-user-static fai-server fai-setup-storage fai-doc qemu-utils
# fai-mk-configspace

# export FAI_BASEFILEURL=https://fai-project.org/download/basefiles/
# fai-diskimage -vu armhost -S2G -cDEFAULT,DHCPC,DEBIAN,ARM64,BUSTER_ARM64,FAIBASE,DEMO,CLOUD,LAST arm64.raw
# chown your_user_id arm64.raw
# cp /var/log/fai/armhost/last/vmlinuz* vmlinuz
```

--------------------------------

### Create Bootable Live ISO

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

This process involves two steps: first, creating a live environment using 'fai dirinstall' with the LIVEISO class, and second, generating the live ISO using 'fai-cd'.

```shell
# cl="DEBIAN,BOOKWORM64,AMD64,FAIBASE,XFCE,XORG,DHCPC,DEMO,LIVEISO,LAST"
# LC_ALL=C fai -v dirinstall -u xfce33 -c $cl \
    -s file:///srv/fai/config /srv/xfce
# fai-cd -s500 -MH -d none -g /etc/fai/grub.cfg.live \
    -n /srv/xfce live.iso
```

--------------------------------

### FAI Configuration Variables

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

References a list of variables used by FAI for configuration and customization. These variables control various aspects of the installation process, including logging, network settings, and package management.

```APIDOC
FAI Variables:
  - A comprehensive list of variables used by FAI can be found at https://wiki.fai-project.org/index.php/Variables.
  - Examples:
    - +$LOGUSER+: Specifies the user for saving logs.
    - +$LOGSERVER+: Specifies the server for saving logs (defaults to install server).
    - +$NFSROOT_ETC_HOSTS+: List of IP addresses for install clients without DNS resolving.
    - +$MAXPACKAGES+: Limits the number of packages installed at a time.
```

--------------------------------

### Debconf Preseeding

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Debconf preseeding is managed by FAI using files located in the `$FAI/debconf` directory. File names within this directory are matched against defined classes to apply specific preseeding configurations for package installation questions.

```shell
# Files in '$FAI/debconf' are used for debconf preseeding.
# If a filename matches a defined class, its content is used for preseeding.
# Example: If class 'debian' is defined, '$FAI/debconf/debian' is used.
```

--------------------------------

### FAI Task: mountdisks

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Explains the 'mountdisks' task, responsible for mounting partitions based on the generated '/tmp/fai/fstab' file relative to $FAI_ROOT.

```APIDOC
mountdisks::
  - Mounts the created partitions.
  - Uses the '/tmp/fai/fstab' file for mount point definitions.
  - Mounts are relative to +$FAI_ROOT+.
```

--------------------------------

### Conditional Package Installation Logic

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Explains how FAI supports adding logic to `PACKAGES` lines. This includes using class names with logical OR for simple conditions, or more complex boolean expressions with AND, OR, and NOT for fine-grained control.

```FAIConfig
# Old way: Install if CLASS_A OR CLASS_B is defined
PACKAGES install package-x CLASS_A CLASS_B

# New way: Install if CLASS_X is defined AND CLASS_Y is NOT defined
PACKAGES install package-y XORG && ! MINT
```

--------------------------------

### FAI Flags Configuration

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Documentation for FAI flags, which are space-separated options controlling installation behavior. Flags are typically defined in pxelinux.cfg and affect output verbosity, debugging, service startup, and shutdown procedures.

```APIDOC
FAI Flags:

verbose::
  Create verbose output during installation. Should be the first flag defined.

debug::
  Create debug output. Disables unattended installation and requires manual input for postinstall scripts. Useful for FAI developers.

sshd::
  Start the SSH daemon to enable remote root logins during installation. The default password is 'fai'.

createvt::
  Create two additional virtual terminals accessible via Alt-F2 and Alt-F3. Typing Ctrl-C in the console terminal will reboot the client. Useful for debugging.

menu::
  Enable a user menu for selecting an installation profile by reading class/*.profile files.

screen::
  Run FAI inside a 'screen' session named FAI.

tmux::
  Run FAI inside a 'tmux' session named FAI.

reboot::
  Reboot the install client automatically after installation completion.

halt::
  Halt the install client at the end of the installation instead of rebooting.

initial::
  Used by setup-storage. Preserves partitions marked with 'preserve_reinstall' unless this flag is set. Often set via 'flag_initial=1' in class/*.var files.
```

--------------------------------

### Saving Log Files

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Log files are saved to `/var/log/fai/$HOSTNAME/install/` on the new system and can be copied to an install server if `$LOGUSER` is defined. The destination can be customized using `$LOGSERVER` or the default `$SERVER` variable. Symlinks like 'last', 'last-install', and 'last-sysinfo' point to the latest log directories.

```APIDOC
Log File Management:

Default Log Directory: /var/log/fai/$HOSTNAME/install/

Remote Logging:
- Enabled if `$LOGUSER` is defined (configure in '/srv/fai/config/class/FAIBASE.var').
- Destination can be specified by `$LOGSERVER`.
- If `$LOGSERVER` is not defined, `$SERVER` is used (defined during initial installation).

Symlinks:
- 'last': Points to the log directory of the last FAI action.
- 'last-install': Points to the log directory of the last FAI installation action.
- 'last-sysinfo': Points to the log directory of the last system information gathering action.
```

--------------------------------

### FAI Task: tests

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Describes the 'tests' task, which runs test scripts found in '$FAI/tests/' and its subdirectories for each defined class.

```APIDOC
tests::
  - Calls test scripts located in '$FAI/tests/' and its subdirectories.
  - Tests are executed for every defined class.
```

--------------------------------

### Extending ISO/USB with Data Partition using mk-data-partition

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Tool to add an ext4 or exFAT partition to a FAI ISO or USB stick, labeled 'MY-DATA'. This partition is mounted at '/media/data' by FAI and can store custom .deb packages for installation.

```shell
mk-data-partition
```

--------------------------------

### Configure HTTP Access to Debian Mirror

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Sets up HTTP access to a local Debian mirror by installing Apache2 and creating a symbolic link from the web server's document root to the mirror directory. It also requires updating FAI configuration files to include the mirror's IP address.

```shell
faiserver# apt-get install apache2
faiserver# ln -s /files/scratch/debmirror /var/www/html/debmirror
```

--------------------------------

### Site Specific Customization Scripts

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

The `fai-do-scripts(1)` command executes site-specific customization scripts located in `$FAI/scripts`. These scripts can be of various types (shell, cfengine, etc.) and are run in a class-based manner to adjust system configurations after package installation.

```APIDOC
Site Script Execution Command: fai-do-scripts(1)

Purpose: Executes arbitrary scripts for site-specific system customization.

Script Location: Scripts are located in '$FAI/scripts'.

Execution Model: Scripts are executed in a class-based manner.

Script Types: Supports multiple script types (e.g., shell, cfengine).

Default Scripts: Includes examples for setting root password, user accounts, timezone, network configuration (DHCP/static IP), and GRUB setup for Debian and Rocky Linux.

See <<cscripts>> for more information.
```

--------------------------------

### unpack Command Description

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Details the `unpack` command, which downloads a package and unpacks its contents without configuring it.

```FAIConfig
unpack::
  # Downloads a package and unpacks it, but does not configure it.
```

--------------------------------

### FAI Task: configure

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Details the 'configure' task, which executes custom scripts located in '$FAI/scripts/' and its subdirectories for each defined class.

```APIDOC
configure::
  - Calls scripts located in '$FAI/scripts/' and its subdirectories.
  - Scripts are executed for every defined class.
```

--------------------------------

### Create FAI Autodiscover ISO

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Creates a bootable ISO image for FAI autodiscovery, allowing clients to find the FAI server on the network without manual DHCP configuration. The image scans the subnet for a FAI server and typically presents a menu of available installation profiles.

```shell
faiserver# fai-cd -A autodiscover.iso
```

--------------------------------

### Disk Partitioning with setup-storage

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

The `setup-storage(8)` command handles disk partitioning, file system creation, software RAID, and LVM configuration. Disk configurations are selected from `$FAI/disk_config` based on defined classes. Disks and partitions can be referenced using a `diskX.Y` notation.

```APIDOC
Disk Partitioning Tool: setup-storage(8)

Purpose: Performs disk partitioning, file system creation, software RAID, and LVM setup.

Configuration: Uses disk configuration files from '$FAI/disk_config', selected via classes.

Reference Format: Disks and partitions can be referenced as 'disk1.1', 'disk2.4', etc.

Example Format (similar to fstab):
<device> <mountpoint> <filesystemtype> <options> <dump> <pass>

See `setup-storage(8)` manual page for detailed format and examples.
```

--------------------------------

### Generate Encrypted Root Password (Shell)

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Provides an example of generating an encrypted root password hash using the `mkpasswd` command. This hash is used for the ROOTPW variable in FAI configurations.

```shell
echo "yoursecrectpassword" | mkpasswd -m yescrypt -s
```

--------------------------------

### Add Host Entry to /etc/hosts

Source: https://github.com/faiproject/fai/blob/master/doc/fai-guide.txt

Example of adding a static host entry to the /etc/hosts file, mapping an IP address to a hostname. This is often used for local DNS resolution or in conjunction with DHCP configurations.

```configuration
192.168.33.100    demohost
```