.TH setup-storage 8 "Feb, 2024" "FAI 6" .SH NAME \fBsetup-storage\fP \- automatically prepare storage devices .SH SYNOPSIS .br \fBsetup-storage\fP [\fB\-X\fP] [\fB\-f\fP \fIfilename\fP] [\fB\-d\fP] [\fB\-h\fP] [\fB\-s\fP] [\fB\-D\fP \fIdisks\fP] [\fB\-L\fP \fIdirectory\fP] .SH DESCRIPTION Using FAI disk_config files, \fBsetup-storage\fP Computes effective partition and volume sizes and executes the necessary commands to configure storage devices. It manages disk drives, RAID and LVM volumes, along with encryption and tmpfs. Disks and partitions are designated by \fBdisk1.2\fP, \fBdisk3.1\fP etc. and may thus be referenced as such. Currently, setup-storage handles following filesystems: \fBext2/3/4\fP, \fBvFAT(FAT32)\fP, \fBmsdos(FAT16)\fP, \fBreiserFS\fP, \fBXFS\fP and \fBBTRFS\fP but could easily be extended to further types as well. Once the storage devices are prepared, an appropriate \fBfstab\fP(5) (and possibly also a \fBcrypttab\fP(5) file is generated. Without the \fB\-X\fP parameter \fBsetup-storage\fP runs in test-only mode and does not execute commands other than writing disk labels to a blank disk. The exit code of \fBsetup-storage\fP is 0 if all operations were performed successfully and non-zero if an error occurs. .SH OPTIONS .TP \fB\-X\fP Really write the configuration to disk. Otherwise \fBsetup-storage\fP runs in test-only mode. .TP \fB\-f\fP \fIfilename\fP Normally \fBsetup-storage\fP selects an appropriate configuration from $FAI/disk_config/ by picking the class with the highest priority from .IR classes that has an existing file. If however \fB\-f\fP is given the configuration in \fIfilename\fP is used. .TP \fB\-d\fP Enable debugging output. Equivalent to environment variable .IR debug set to a non-zero value. See below for further details. .TP \fB\-s\fP Perform syntax check of disk_config file only and exit. .TP \fB\-D\fP \fIdisks\fP Specify the list of disk drives to be configured using \fBsetup-storage\fP. Overrides the variable \fIdisklist\fP. Do not forget to quote this space separated list. .TP \fB\-L\fP \fIdirectory\fP Use the specified directory instead of .IR LOGDIR. .TP \fB\-h\fP Display the synopsis and version info and exit. .TP \fB\-p\fP Print the commands that would be executed, then exit. .TP \fB\-y\fP Print disk variables as YAML file into disk_var.yml .SH ENVIRONMENT \fBsetup-storage\fP will use the following environment variables: .TP .B disklist If option \fB\-D\fP is not used, the .IR disklist variable may contain a space separated list of disk drives available in the system. Their order matters as they may be referred to as disk1, and so on, in disk_config. If unset, fai-disk-info will be called to determine the list. .TP .B debug If .IR debug is set to a non-zero value all actions and details to track the operation of \fBsetup-storage\fP are printed to stderr. .TP .B FAI The location of the config space to find the disk_config directory. .TP .B classes The list of FAI classes to determine the appropriate configuration to choose. .TP .B LOGDIR \fBsetup-storage\fP generates disk_var.sh, fstab, and possibly crypttab (see below) in this directory. Defaults to /tmp/fai if unset. Option \fB\-L\fP overrides this. .TP .B flag_initial This variable determines if partitions should be preserved when they are tagged with preserve_reinstall (see below for details). Normally set by the list of FAI flags (FAI_FLAGS). .TP .B SS_IGNORE_VG This variable may contain a list of volume groups, that are ignored by setup-storage. The list can be comma or space separated. It's used by fai-diskimage. .SH FILES If \fBsetup-storage\fP executes successfully, an \fBfstab\fP(5) file matching the specified configuration is generated as $LOGDIR/fstab. Furthermore the file $LOGDIR/disk_var.sh is generated. This file defines the following variables, if not yet set: .IR SWAPLIST , .IR ROOT_PARTITION , .IR BOOT_PARTITION (which is only set in case this resides on a disk drive), .IR BOOT_DEVICE and .IR PHYSICAL_BOOT_DEVICES (which contains the list of all physical devices having a bootable partition). Both .IR BOOT_PARTITION and .IR BOOT_DEVICE describe the partition and disk/RAID/LVM device hosting the mount point for /boot. If /boot has no extra mount point, / is used instead. .IR PHYSICAL_BOOT_DEVICES can be used to determine where a bootloader should be installed (this is useful if / is on a LVM or RAID device). You may source $LOGDIR/disk_var.sh to get the variables set. The example config space shipped with FAI sources this file in scripts/GRUB_PC/10-setup. If encryption was configured, a proper \fBcrypttab\fP(5) file plus key files will be generated. The output of setup-storage is also written to the log file format.log. .SH EXAMPLES \fBsetup-storage\fP configures storage devices according to a FAI disk_config file. The full grammar describing the syntax of these disk_config files is given below. The syntax is similar to the structure of an fstab file. First we show a number of examples to give an intuition what these should look like. .TP 3m Simple configuration of /dev/sda .sp .nf .ta 8n +8n +7n +5n +5n +5n disk_config disk1 disklabel:msdos bootable:3 primary /boot 20-100 ext4 rw primary swap 1G swap sw primary / 12G ext4 rw,noatime logical /backup 10%- xfs rw .sp .fi .PP .IP \(bu The first disk found is going to be partitioned. FAI looks into /proc/partitions and sets the variable \fIdisklist\fP. The disklabel is msdos which is the default for x86. Let's assume /dev/sda is the first disk. Then partition /dev/sda3 is made bootable. .IP \(bu Create a primary partition /dev/sda1 with a size between 20 and 100 MiB and mount it read-write as /boot; it is formatted using ext4 filesystem. .IP \(bu /dev/sda2 will be a swap space of 1 GiB .IP \(bu /dev/sda3 should be formatted using ext4 filesystem .IP \(bu Create the logical partition /dev/sda5 (because the first logical partition will always become number 5) Make it at least 10% of the disk size. Use mkfs.xfs to format this partition. .TP 3m Create a software RAID .sp .nf .ta 10n +5n +10n +4n +4n +4n disk_config sda primary - 20G - - primary - 4G - - disk_config sdb sameas: sda disk_config raid raid1 / sda1,sdb1 ext4 rw raid1 swap sda2,sdb2 swap sw .sp .fi .PP .IP \(bu Create 2 partitions of size 20 and 4 GiB, respectively, on disks /dev/sda and /dev/sdb. No file system or fstab entry will be created. on these partitions. .IP \(bu Create a RAID-1 on /dev/sda1 and /dev/sdb1, format using mkfs.ext4 and mount it as / .IP \(bu Create a RAID-1 on /dev/sda2 and /dev/sdd2, prepare as swap space and use it as such later on. .TP 3m Advanced softRAID features .sp .nf .ta 7n 12n 23n 27n 37n disk_config raid raid1 / sda1,sdd1 ext4 rw,errors=remount-ro raid0 - disk2.2,sdc1,sde1:spare:missing ext4 default .sp .fi .PP .IP \(bu Create a RAID-1 on /dev/sda1 and /dev/sdd1, format using mkfs.ext2 and mount it as / .IP \(bu Create a RAID-0 on the second partition of the second disk, /dev/sdc1, and /dev/sde1 as a spare partition. The latter may be missing. .IP \(bu The configurations for /dev/sda, /dev/sdd, disk2, /dev/sdc, and /dev/sde are omitted in this example. These devices can be configured similar to the configuration shown in the first example. They may also already be properly set up and hence the configuration can be left out. .TP 3m Simple LVM example .sp .nf .ta 7n +7n +7n +10n +10n +10n disk_config sda bootable:1 primary /boot 500 ext4 rw primary - 4096- - - disk_config lvm vg my_pv sda2 my_pv_swap swap 2048 swap sw my_pv_root / 2048 ext4 rw .sp .fi .PP .IP \(bu Configure /dev/sda with two partitions. .IP \(bu The second of those, /dev/sda2, is then used in the LVM volume group my_pv. .IP \(bu This volume group hosts two logical volumes: _swap and _root. .TP LVM on software RAID .sp .nf .ta 12n +6n +8n +8n +8n disk_config disk1 disklabel:msdos fstabkey:uuid primary - 350 - - primary swap 2G swap sw,pri=1 primary - 0- - - disk_config disk2 sameas:disk1 disk_config raid fstabkey:uuid raid1 /boot disk1.1,disk2.1 ext4 rw,noatime,errors=remount-ro raid1 - disk1.3,disk2.3 - - disk_config lvm fstabkey:uuid vg vg_system md1 vg_system-root / 4G-50G ext4 rw,noatime vg_system-home /home 1G- ext4 rw,noatime,nosuid,nodev .sp .fi .PP .IP \(bu Configure the first and second disk identical with three partitions each. .IP \(bu The first partitions of each device are bundled into a RAID 1 (/dev/md0), which will be mounted at /boot. .IP \(bu The third partition of each device are combined as another RAID 1, but not mounted. Instead, the resulting device /dev/md1 is used to host the LVM volume group vg_system. ATTENTION! Do not forget to install the packages mdadm and lvm2 into a system using this partition scheme. Also set rd.auto when using dracut as initrd generator. .TP Crypt example .sp .nf .ta 10n 20n 30n 40n 50n disk_config /dev/sdb primary / 21750 ext4 defaults,errors=remount-ro primary /boot 250 ext4 defaults logical - 4000 - - logical - 2000 - - logical - 10- - - disk_config cryptsetup swap swap /dev/sdb5 swap defaults tmp /tmp /dev/sdb6 ext2 defaults luks /local00 /dev/sdb7 ext4 defaults,errors=remount-ro createopts="\-m 0" .sp .fi .PP .IP \(bu Configure /dev/sdb with 2 primary partitions, one extended partition, and 3 logical partitions. .IP \(bu Encrypt the swap space, /tmp, and /local00. As described in the CAVEATS section, the encryption keys will be stored in a temporary directory only. .IP \(bu Do not forget to install the cryptsetup package on a system using thus scheme. .IP \(bu The initial password for the encrypted device can also be set in the configuration file by using the syntax - luks:"secret" .IP \(bu With a working RAID+LVM configuration, an encryption layer can be added between the RAID and LVM device layers by adding the following cryptsetup configuration. In this case, the encrypted device will be called 'crypt_format_md1' and will be used as the underlying physical device (PV) in LVM. .sp .nf .ta 7n +7n +7n +7n disk_config cryptsetup luks - /dev/md1 - - .sp .fi .PP .TP Plain disk + LUKS + LVM2 example .sp .nf .ta 10n 20n 30n 40n 50n disk_config disk1 disklabel:gpt bootable:1 fstabkey:uuid align-at:1M primary - 100% - - disk_config cryptsetup luks:"passwd" - disk1.1 - - disk_config lvm fstabkey:uuid vg vg1 disk1.1 vg1-root / 30%- ext4 defaults,errors=remount-ro,noatime,rw .sp .fi .PP .TP tmpfs example .sp .nf .ta 10n 20n 30n 40n 50n disk_config tmpfs tmpfs /tmp RAM:20% defaults tmpfs /scratch 3GiB defaults tmpfs /scratch2 - defaults .sp .fi .PP .IP \(bu Mount a tmpfs on /tmp with a maximum size equal to 20% of the total amount of RAM in the machine. This is equivalent to using size=20% in the tmpfs mount options. .IP \(bu Mount a tmpfs on /scratch with a maximum size of 3 GiB. .IP \(bu Mount a tmpfs on /scratch2, use the system default size for this tmpfs. .TP nfs example .sp .nf .ta 10n 20n 30n 40n 50n disk_config nfs nfs 11.22.33.44:/export/vm-root/HOSTNAME / defaults .sp .fi .PP .IP \(bu A diskless client setup. Mount the whole OS file system via NFS from an NFS server onto /. .TP Simple BTRFS example .sp .nf .ta 10n 20n 30n 40n 50n disk_config disk1 primary /boot 500 ext4 rw primary - 2G- - - disk_config disk2 primary - 2G- - - disk_config disk3 sameas:disk2 disk_config disk4 sameas:disk2 disk_config btrfs fstabkey:uuid btrfs raid1 / disk1.2,disk2.1 noatime,subvol=@/ btrfs raid1 /home disk3.1,disk4.1 subvol=@home,noatime .sp .fi .PP .IP \(bu Four disks are used to create a BTRFS RAID. The first disk contains the boot partition, the second partition of disk one and the second disk in its entirety are used to create the / RAID. The third and fourth disks are used to create the /home RAID. .IP \(bu Note that each BTRFS RAID must contain an initial subvolume. This is necessary to use advanced BTRFS features such as snapshots. The initial subvolume name is taken from the subvol mountoption. In the above example those would be @/ and @home. Subvolume names begin with an @ by convention. .IP \(bu Every BTRFS line must begin with btrfs followed by the RAID-level of the actual data -- NOT metadata! By default metadata uses RAID1, however this can be changed using createopts. .TP External log device example .sp .nf .ta 10n 20n 30n 40n 60n disk_config /dev/sda fstabkey:uuid bootable:2 primary / 20GiB ext3 defaults primary /boot 250 ext2 defaults primary swap 4GiB swap defaults logical - 256 ext3_journal - logical - 256 ext4_journal - logical - 256 xfs_journal - disk_config /dev/sdb fstabkey:uuid primary /mnt/ext3 33% ext3:journal=/dev/sda5 defaults primary /mnt/ext4 33% ext4:journal=/dev/sda6 defaults primary /mnt/xfs 33% xfs:journal=/dev/sda7 defaults .sp .fi .PP .IP \(bu Mount an ext3 filesystem on /dev/sdb1 with an external journal on /dev/sda5 .IP \(bu Mount an ext4 filesystem on /dev/sdb2 with an external journal on /dev/sda6 .IP \(bu Mount an XFS filesystem on /dev/sdb3 using /dev/sda7 as the log device .TP Example using a GPT partition table and EFI/ESP partition .sp .nf .ta 10n 20n 30n 40n 60n disk_config disk1 disklabel:gpt fstabkey:partlabel bootable:1 p=efi /boot/efi 200 vfat rw p=root / 1G-20G ext4 rw p= /data 1G- ext4 rw .sp .fi .PP .IP \(bu Creating a ESP partition for UEFI boot is very simple. Use a GPT partition table, create a vfat partition for /boot/efi which is also bootable. That's it. A name after p= is used as the partition label. Remember that GPT does not use logical partition. Just use p= for each partition. The fstab entries will use the partition labels if defined. Otherwise it will fall back to the file system UUID or the device name. Setting fstabkey:partuuid will use the UUID of the partition (not the UUID of the file system) for the fstab entries. .SH SYNTAX This section describes the syntax of disk_config files file ::= EOF .br lines ::= EOL .br /* empty lines or whitespace only */ .br | EOL .br | EOL .br comment ::= #.* .br config ::= disk_config lvm( )* .br | disk_config raid( )* .br | disk_config cryptsetup( )* .br | disk_config tmpfs .br | disk_config end .br | disk_config disk[[:digit:]]+(