setup-storage(8)

📦

version 6.6ubuntu1 · 4 versions

6.6ubuntu1 · ubuntu stonking (latest)
5.10.3ubuntu1 · ubuntu jammy
6.0.5ubuntu1 · debian bookworm, ubuntu noble
6.4.3ubuntu1 · debian trixie, ubuntu resolute

💾 setup-storage(8) — System Manager's Manual 💖

okay bestie, buckle up, because setup-storage from the setup-storage(8) manual is literally the girl who sets up ALL your disks for you and she does not miss. ✨

🌸 NAME 🌸

setup-storage — automatically prepare storage devices 💅

🎀 SYNOPSIS 🎀

setup-storage [-X] [-f filename] [-d] [-h] [-s] [-D disks] [-L directory]

✨ DESCRIPTION ✨

So here's the vibe: setup-storage reads your FAI disk_config files, computes the effective partition and volume sizes, and then runs all the commands needed to actually configure your storage devices. She's managing disk drives, RAID and LVM volumes, plus encryption and tmpfs too — like, a whole roster. 👑

Disks and partitions get designated like disk1.2, disk3.1, etc., so you can reference them by those names. Right now setup-storage handles these filesystems: ext2/3/4, vFAT(FAT32), msdos(FAT16), reiserFS, XFS and BTRFS — but she could easily be extended to more types as well, so don't even worry.

Once the storage devices are prepped, an appropriate fstab(5) is generated (and possibly a crypttab(5) file too). 🦋

⚠️ Real talk: without the -X parameter, setup-storage runs in test-only mode and does not execute commands — other than writing disk labels to a blank disk.

The exit code of setup-storage is 0 if all operations were performed successfully, and non-zero if an error occurs. Periodt. 💯

🌈 OPTIONS 🌈

-X — Really write the configuration to disk. Otherwise setup-storage runs in test-only mode. (This is the "okay we're for real now" button. 🔥)
-f filename — Normally setup-storage picks an appropriate configuration from $FAI/disk_config/ by choosing the class with the highest priority out of the classes that has an existing file. But if -f is given, the configuration in filename is used instead. 💖
-d — Enable debugging output. Equivalent to setting the environment variable debug to a non-zero value. More deets below, bestie.
-s — Perform a syntax check of the disk_config file only, then exit. Just a lil vibe check, no writing. ✨
-D disks — Specify the list of disk drives to be configured using setup-storage. Overrides the variable disklist. Do not forget to quote this space separated list! 🙈
-L directory — Use the specified directory instead of LOGDIR.
-h — Display the synopsis and version info and exit.
-p — Print the commands that would be executed, then exit. (Ghost-mode preview 👻)
-y — Print disk variables as a YAML file into disk_var.yml. 💜

🧚 ENVIRONMENT 🧚

setup-storage will use the following environment variables:

disklist — If option -D is not used, the disklist variable may contain a space separated list of disk drives available in the system. Their order matters, because 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.
debug — If debug is set to a non-zero value, all actions and details to track the operation of setup-storage are printed to stderr.
FAI — The location of the config space to find the disk_config directory.
classes — The list of FAI classes to determine the appropriate configuration to choose.
LOGDIR — setup-storage generates disk_var.sh, fstab, and possibly crypttab (see below) in this directory. Defaults to /tmp/fai if unset. Option -L overrides this.
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).
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.
FAI_KEEP_CRYPTKEYFILE — If this variable is set, the keyfiles for disks encryption are not deleted and will be saved into the local and remote locations of the log files. 🔐

📁 FILES 📁

If setup-storage executes successfully, an fstab(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: SWAPLIST, ROOT_PARTITION, BOOT_PARTITION (which is only set in case this resides on a disk drive), BOOT_DEVICE and PHYSICAL_BOOT_DEVICES (which contains the list of all physical devices having a bootable partition). 💖

Both BOOT_PARTITION and 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. 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. And if encryption was configured, a proper crypttab(5) file plus key files will be generated. 🎀

The output of setup-storage is also written to the log file format.log. 🌟

✨ EXAMPLES ✨

ok so setup-storage is the girl that sets up your storage devices based on a FAI disk_config file 💅 the full grammar of those files is coming right up below, but first — vibes check. The syntax is lowkey similar to how an fstab file is structured. So here's a lil pile of examples to give you the ✨intuition✨ bestie.

🌸 Simple configuration of `/dev/sda`

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

The first disk found is the one getting partitioned, no cap. FAI peeks into /proc/partitions and sets the variable disklist. The disklabel here is msdos, which is the default for x86. Let's assume /dev/sda is the first disk — then partition /dev/sda3 gets made bootable 👑
Create a primary partition /dev/sda1 with a size somewhere between 20 and 100 MiB and mount it read-write as /boot; it's formatted using ext4 filesystem.
/dev/sda2 is gonna be a swap space of 1 GiB.
/dev/sda3 should be formatted using ext4 filesystem.
Create the logical partition /dev/sda5 (because the first logical partition will always become number 5, that's just the rules) Make it at least 10% of the disk size. Use mkfs.xfs to format this partition.

🦋 Create a software RAID

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

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.
Create a RAID-1 on /dev/sda1 and /dev/sdb1, format using mkfs.ext4 and mount it as /
Create a RAID-1 on /dev/sda2 and /dev/sdd2, prepare as swap space and use it as such later on.

💜 Advanced softRAID features

disk_config raid
raid1  /    sda1,sdd1  ext4          rw,errors=remount-ro
raid0  -    disk2.2,sdc1,sde1:spare:missing ext4 default

Create a RAID-1 on /dev/sda1 and /dev/sdd1, format using mkfs.ext2 and mount it as /
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.
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.

🎀 Simple LVM example

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

Configure /dev/sda with two partitions.
The second of those, /dev/sda2, is then used in the LVM volume group my_pv.
This volume group hosts two logical volumes: _swap and _root.

🌈 LVM on software RAID

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

Configure the first and second disk identical with three partitions each.
The first partitions of each device are bundled into a RAID 1 (/dev/md0), which will be mounted at /boot.
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. 🚨 like fr fr do not skip this one bestie

🔥 Crypt example

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"

Configure /dev/sdb with 2 primary partitions, one extended partition, and 3 logical partitions.
Encrypt the swap space, /tmp, and /local00. As described in the CAVEATS section, the encryption keys will be stored in a temporary directory only.
Do not forget to install the cryptsetup package on a system using thus scheme.
The initial password for the encrypted device can also be set in the configuration file by using the syntax - luks:"secret"
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.

disk_config cryptsetup
luks   -      /dev/md1      - -

👑 Plain disk + LUKS + LVM2 example

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

🍓 tmpfs example

disk_config tmpfs
tmpfs     /tmp      RAM:20%   defaults
tmpfs     /scratch  3GiB      defaults
tmpfs     /scratch2 -         defaults

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.
Mount a tmpfs on /scratch with a maximum size of 3 GiB.
Mount a tmpfs on /scratch2, use the system default size for this tmpfs.

🧚 nfs example

disk_config nfs
nfs 11.22.33.44:/export/vm-root/HOSTNAME          /defaults

A diskless client setup. Mount the whole OS file system via NFS from an NFS server onto /.

💖 Simple BTRFS example

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

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.
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.
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.

⭐ External log device example

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

Mount an ext3 filesystem on /dev/sdb1 with an external journal on /dev/sda5
Mount an ext4 filesystem on /dev/sdb2 with an external journal on /dev/sda6
Mount an XFS filesystem on /dev/sdb3 using /dev/sda7 as the log device

🎀 Example using a GPT partition table and EFI/ESP partition

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

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.

config — the actual stanzas

config ::= disk_config lvm( <lvmoption>)*
           | disk_config raid( <raidoption>)*
           | disk_config cryptsetup( <cryptsetupoption>)*
           | disk_config tmpfs
           | disk_config end
           | disk_config disk[[:digit:]]+( <option>)*
           | disk_config [^[:space:]]+( <option>)*
           /* fully qualified device-path or short form, like sda, whereby full
            * path is assumed to be /dev/sda; may contain shell globbing such
            * as /dev/disk/by-id/scsi-* */
           | <volume>

this is the moment, bestie 🎀 every real line in your file kicks off with disk_config and then commits to a lane: lvm, raid, cryptsetup, tmpfs, end, a numbered disk like disk1, or a device path with options.

and the tea on that device path: you can write a fully qualified device-path like /dev/sda, or the short form like sda and it's assumed to be /dev/sda — and it can contain shell globbing such as /dev/disk/by-id/scsi-*. yes ma'am, globbing. it's giving flexible 💅

or it's just a <volume> and we move on 🌸

lvmoption ::= /* empty */
           | preserve_always:([^/,\s\-]+-[^/,\s\-]+(,[^/,\s\-]+-[^/,\s\-]+)*|all)
           /* preserve volumes -- always */
           | preserve_reinstall:([^/,\s\-]+-[^/,\s\-]+(,[^/,\s\-]+-[^/,\s\-]+)*|all)
           /* preserve volumes -- unless the system is installed for the first time */
           | preserve_lazy:([^/,\s\-]+-[^/,\s\-]+(,[^/,\s\-]+-[^/,\s\-]+)*|all)
           /* preserve volumes -- unless these don't exist yet */
           | always_format:([^/,\s\-]+-[^/,\s\-]+(,[^/,\s\-]+-[^/,\s\-]+)*|all)
           /* run mkfs on the volumes, even if marked as preserve */
           | resize:([^/,\s\-]+-[^/,\s\-]+(,[^/,\s\-]+-[^/,\s\-]+)*|all)
           /* attempt to resize partitions */
           | fstabkey:(device|label|uuid)
           /* when creating the fstab, the key used for defining the device
              may be the device (/dev/xxx), a label given using -L,
              the filesystem uuid, partition label (only when using GPT) or
              partition uuid */

note how the volume values here are <vg>-<lv> shaped pairs, comma-separated, or just all 👑 and <cyan>fstabkey</cyan> can be device, label or uuid — with the device being /dev/xxx, a label given using -L, the filesystem uuid, a partition label (only when using GPT), or a partition uuid. so many keys, so little time.

raidoption — same energy, raid flavored

raidoption ::= /* empty */
           | preserve_always:([[:digit:]]+(,[[:digit:]]+)*|all)
           /* preserve volumes -- always */
           | preserve_reinstall:([[:digit:]]+(,[[:digit:]]+)*|all)
           /* preserve volumes -- unless the system is installed for the first time */
           | preserve_lazy:([[:digit:]]+(,[[:digit:]]+)*|all)
           /* preserve volumes -- unless these don't exist yet */
           | always_format:([[:digit:]]+(,[[:digit:]]+)*|all)
           /* run mkfs on the volumes, even if marked as preserve */
           | fstabkey:(device|label|uuid)
           /* when creating the fstab the key used for defining the device
              may be the device (/dev/xxx), a label given using -L, or the uuid */

here the numbers are digits, comma-separated, or all ✨ and fstabkey is device, label or uuid — device /dev/xxx, a label given using -L, or the uuid. periodt.

cryptsetupoption — short but mighty

cryptsetupoption ::= /* empty */
           | randinit
           /* initialise all encrypted partitions with random data */

one single option and it's randinit, which initialises all encrypted partitions with random data. mysterious. powerful. love that for us 🔥

option ::= /* empty */
           | preserve_always:([[:digit:]]+(,[[:digit:]]+)*|all)
           /* preserve partitions -- always; the numbers refer to partition
              numbers, i.e., preserve_always:5 for /dev/sda refers to /dev/sda5,
              which may not necessarily be the 5th line of the configuration */
           | preserve_reinstall:([[:digit:]]+(,[[:digit:]]+)*|all)
           /* preserve partitions -- unless the system is installed for the
              first time. See preserve_always above for the semantics of numbers
              used for referring to partitions. */
           | preserve_lazy:([[:digit:]]+(,[[:digit:]]+)*|all)
           /* preserve partitions -- unless these don't exist yet */
           | always_format:([[:digit:]]+(,[[:digit:]]+)*|all)
           /* run mkfs on the partitions, even if marked as preserve */
           | resize:([[:digit:]]+(,[[:digit:]]+)*|all)
           /* attempt to resize partitions */
           | disklabel:(msdos|gpt|gpt-bios)
           /* write a disklabel - default is msdos */
           | bootable:[[:digit:]]+
           /* mark a partition bootable, default is / */
           | virtual
           /* do not assume the disk to be a physical device, use with xen */
           | fstabkey:(device|label|uuid|partuuid|partlabel)
           /* when creating the fstab the key used for defining the device
              may be the device (/dev/xxx), a label given using -L, or the uuid */
           | sameas:(disk[[:digit:]]+|[^[:space:]]+)
           /* Indicate that this disk will use the same scheme
              as the given device. The referenced device must be
              defined before the device using this option. Use only
              with identical hardware. */
           | align-at:([[:digit:]]+[kKMGTPiB]*)
           /* Align partitions at multiples of the given block size (unit
              defaults to MiB, if omitted). Such an alignment, e.g., 4K, might be
              important for proper performance of RAID arrays which use a
              logical block size other than the sector size of the underlying
              disks. It must, however, always be a multiple of this sector size. */

bestie the way this one has RANGE. let me point at the details bc they matter 👑

the numbers in the preserve_* / always_format / resize options are PARTITION numbers, ok? so preserve_always:5 on /dev/sda refers to /dev/sda5 — and that is not necessarily the 5th line of your configuration. do not get it twisted 😭
disklabel: takes msdos, gpt or gpt-bios, and the default is msdos
bootable: takes digits, and the default is /
virtual means don't assume the disk is a physical device, use it with xen
fstabkey: here can be device, label, uuid, partuuid or partlabel — device /dev/xxx, a label given using -L, or the uuid
sameas: says this disk uses the same scheme as the given device. caveat time: the referenced device must be defined before the device using this option, and only use it with identical hardware. no cap 🔥
align-at: aligns partitions at multiples of the given block size (unit defaults to MiB if you omit it). an alignment like 4K might be important for RAID arrays whose logical block size differs from the underlying disks' sector size — but it must always be a multiple of that sector size. non-negotiable 💅

volume — what an actual entry looks like

volume ::= <type> <mountpoint> <size> <filesystem> <mount_options> <luks_options> <fs_options>
           | vg <name> <size> <fs_options>
           /* lvm vg */
           | tmpfs <mountpoint> <tmpfs_size> <mount_options>
           /* tmpfs volume */

three shapes: the big seven-slot one, an lvm vg (vg <name> <size> <fs_options>), and a tmpfs volume (tmpfs <mountpoint> <tmpfs_size> <mount_options>). pick your fighter 🦋

type — the type slot

type ::= primary
         /* for physical disks only */
         | logical
         /* for physical disks only */
         | raw-disk
         /* for physical disks only: do not partition this disk, use it as-is */
         | m{^p=([^/,;]*).br
         /* p=<NAME> set NAME as gpt partition label, NAME may be empty */
         | raid[0156]
         /* raid level */
         | luks
         /* encrypted partition using LUKS and auto-generate a key file */
         | luks:"[^"]+"
         /* encrypted partition using LUKS and use quoted string as passphrase */
         | tmp
         /* encrypted partition for /tmp usage, will be
            recreated with a random key at each boot and
            reformatted as ext2 */
         | swap
         /* encrypted partition for swap space usage, will
            be recreated with a random key at each boot and
            reformatted as swap space */
         | [^/[:space:]]+-[^/[:space:]]+
         /* lvm logical volume: vg name and lv name*/

rundown, quickfire 🎀

primary and logical — for physical disks only
raw-disk — also physical disks only, and it means do not partition this disk, use it as-is. bold move
that m{^p=([^/,;]*).br line — p=<NAME> sets <NAME> as the gpt partition label, and <NAME> may be empty. iykyk
raid[0156] — your raid level
luks — encrypted with LUKS and it auto-generates a key file
luks:"[^"]+" — encrypted with LUKS and it uses the quoted string as the passphrase
tmp — encrypted partition for /tmp, recreated with a random key at each boot and reformatted as ext2
swap — encrypted partition for swap space, recreated with a random key at each boot and reformatted as swap space
<vg>-<lv> — an lvm logical volume: vg name and lv name, joined by a dash

mountpoint

mountpoint ::= (-|swap|/[^[:space:]]*)
               /* do not mount, mount as swap, or mount at fully qualified path */

either - (do not mount), swap, or a fully qualified path starting with /. three moods 🌈

name

name ::= [^/[:space:]]+
         /* lvm volume group name */

an lvm volume group name. no slashes, no spaces. simple, clean, iconic ✨

sizespec — numbers, but make it fashion

sizespec ::= RAM:[[:digit:]]+%|[[:digit:]]+[kKMGTP%iB]*
             /* size in kilo (KiB), mega (default, MiB), giga (GiB), tera (TiB),
              * petabytes (PiB) or percentage of disk size or RAM size; integers
              * only, no decimal numbers.
              * Use KB, MB, GB, ... for a factor of 1000 instead of 1024 as
              * multiplier */

KILO (KiB), MEGA (default, MiB), GIGA (GiB), TERA (TiB) or PETABYTES (PiB) — or a percentage of disk size, or of RAM size with RAM:. and bestie, hear me: integers only, no decimal numbers 😭💀 and if you write KB, MB, GB, ... you get a factor of 1000 instead of 1024 as multiplier. sneaky but fair.

size — the drama of ranges

size ::= <sizespec>(-(<sizespec>)?)?(:resize|:preserve_(always|reinstall|lazy))?
         /* size, possibly given as a range; physical partitions or lvm logical
          * volumes only */
         | -<sizespec>(:resize|:preserve_(always|reinstall|lazy))?
         /* size given as upper limit; physical partitions or lvm logical
          * volumes only */
         | [^,:[:space:]]+(:(spare|missing))*(,[^,:[:space:]]+(:(spare|missing))*)*
         /* devices and options for a raid or lvm vg */

three flavors 👑

a <sizespec>, possibly as a range, optionally with :resize or :preserve_always|:preserve_reinstall|:preserve_lazy — physical partitions or lvm logical volumes only
a leading - and a <sizespec>, i.e. size given as an upper limit, same optional :resize / :preserve_* suffix — again, physical partitions or lvm logical volumes only
a comma-separated list of devices, each possibly with :spare or :missing — that one's for a raid or lvm vg

tmpfs_size

tmpfs_size ::= <sizespec>
               /* tmpfs size */

it's a <sizespec>. it's the tmpfs size. that's the tweet 🐦

mount_options

mount_options ::= [^[:space:]]+

anything that isn't a space. go off 🌸

filesystem

filesystem ::= -
               | swap
               | [^[:space:]]
               /* mkfs.xxx must exist */

-, swap, or a name — and remember: mkfs.xxx must exist. if that binary isn't there, it's not happening, bestie 😭

luks_options

luks_options ::= (lukscreateopts=".*")
                 /* options to supply to cryptsetup when creating a LUKS
                  * encrypted filesystem. If no ciper (-c) is specified, then
                  * aes-xts-plain64 is used. If no key size (-s) is
                  * specified then 256 is used. */

lukscreateopts="..." gets handed straight to cryptsetup when the LUKS encrypted filesystem gets created. and the defaults, for the record: with no cipher (-c) specified, aes-xts-plain64 is used; with no key size (-s) specified, 256 is used. defaults, we love them 🫶

fs_options — the last slot

fs_options ::= (createopts=".*"|tuneopts=".*"|(pv|vg|lv|md)createopts=".*")*
               /* options to append to mkfs.xxx and to the filesystem-
                  specific tuning tool, pvcreate, vgcreate, lvcreate or mdadm */

createopts="...", tuneopts="...", or pvcreateopts="..." / vgcreateopts="..." / lvcreateopts="..." / mdcreateopts="..." — these get appended to mkfs.xxx and to the filesystem-specific tuning tool, or to pvcreate, vgcreate, lvcreate or mdadm. the little options that could ✨

💀 CAVEATS 💀

bestie this is the part where we sit down and have a serious little chat. read it. all of it. your future self says thank you 🙏

If you use software RAID or LVM in your disk config, do not forget also to add the required packages (like mdadm and lvm2) to the package config. otherwise the client literally will not be able to use these features. no packages, no raid. that's the whole tea 😭
MD devices aka software RAID will not be synced during a new installation because it would slow down the installation heavily. so setup-storage sets the sync_action of each device to frozen. the sync will start after the next reboot. it's not broken, it's just chilling until reboot 🌈
Machine does not boot because no partition is marked as bootable: if the bootable option is not specified, no partition will be marked as such. modern BIOSes don't seem to require such markers anymore, but for some systems it may still be necessary. previous versions of setup-storage by default marked the partition mounting / as bootable, but this is not a sane default for all cases. if you want to be sure no boot failures happen because of a missing bootable marker, explicitly set the bootable option. and of course, there are lots of other reasons why a system may fail to boot, so don't come for us 👑🙈
Crypto support requires some site-specific changes: if you use a cryptsetup stanza, a crypttab(5) file and key files for all luks volumes will be created (unless you used the passphrase option). the key files are left in /tmp/fai — you will want to copy these to some removable media. and to make encrypted root devices actually usable, you need to add busybox (and initramfs-tools) to your package config. pls don't lose the keys bestie 💜
for backwards compatibility or other system-specific reasons, an alignment to cylinder boundaries may be necessary. other systems might have other alignment constraints. so setup-storage sets the alignment like this: if align-at is set, align accordingly. otherwise, if any partition on the particular disk is to be preserved, default to cylinder alignment, otherwise use sector alignment. algorithm but make it aesthetic 💅
if you use a raw partition, you should add -F to the createopts, otherwise mkfs.ext4 hangs due to a warning message 😭 see man mfs.ext4 for more info on -F. an example config using a raw disk looks like this:

raw-disk / 4GB ext4 rw createopts="-F"

✨ SEE ALSO ✨

okay so before you go, bestie, here's where to find the rest of the lore 💖

this program is literally part of FAI (that's Fully Automatic Installation, obvi) — the FAI homepage is at https://fai-project.org
there's so much more documentation, including the coding-adjacent stuff, chillin' in a wiki page at https://wiki.fai-project.org/index.php/Setup-storage

like, if you want the deep lore, that wiki page is the place. go sip some tea and read it fr fr 🍓

👑 AUTHOR 👑

so who do we have to thank for this absolute icon of a program? 🫶

setup-storage was written by Michael Tautschnig <mt@debian.org>, with contributions from Christian Kern, Julien Blache <jblache@debian.org>, Kerim Güney, Thomas Lange and others ✨
and for the record, the original and primary author of FAI is Thomas Lange <lange@cs.uni-koeln.de> 🌟

legends, all of them. no cap. the way they built this whole thing so your disks just... do what you tell them?? iconic behavior 💅

okay bestie, that's the whole page!! you made it to the end, main character energy for real 🌈 this was setup-storage(8) from FAI 6, dated Feb, 2024 — so like, remember that when you're out here partitioning things in the wild 💀 go forth, run your setup, and may your partition tables always be exactly what you meant 🎀✨ byeeee 💖

📦 where this page comes from

ubuntu stonking: fai-setup-storage 6.6ubuntu1 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

setup-storage(8)

💾 setup-storage(8) — System Manager's Manual 💖

🌸 NAME 🌸

🎀 SYNOPSIS 🎀

✨ DESCRIPTION ✨

🌈 OPTIONS 🌈

🧚 ENVIRONMENT 🧚

📁 FILES 📁

✨ EXAMPLES ✨

🌸 Simple configuration of `/dev/sda`

🦋 Create a software RAID

💜 Advanced softRAID features

🎀 Simple LVM example

🌈 LVM on software RAID

🔥 Crypt example

👑 Plain disk + LUKS + LVM2 example

🍓 tmpfs example

🧚 nfs example

💖 Simple BTRFS example

⭐ External log device example

🎀 Example using a GPT partition table and EFI/ESP partition

config — the actual stanzas

lvmoption — the lvm stanza's lil menu

raidoption — same energy, raid flavored

cryptsetupoption — short but mighty

option — the disk stanza's full menu

volume — what an actual entry looks like

type — the type slot

mountpoint

name

sizespec — numbers, but make it fashion

size — the drama of ranges

tmpfs_size

mount_options

filesystem

luks_options

fs_options — the last slot

💀 CAVEATS 💀

✨ SEE ALSO ✨

👑 AUTHOR 👑

setup-storage(8)

💾 setup-storage(8) — System Manager's Manual 💖

🌸 NAME 🌸

🎀 SYNOPSIS 🎀

✨ DESCRIPTION ✨

🌈 OPTIONS 🌈

🧚 ENVIRONMENT 🧚

📁 FILES 📁

✨ EXAMPLES ✨

🌸 Simple configuration of /dev/sda

🦋 Create a software RAID

💜 Advanced softRAID features

🎀 Simple LVM example

🌈 LVM on software RAID

🔥 Crypt example

👑 Plain disk + LUKS + LVM2 example

🍓 tmpfs example

🧚 nfs example

💖 Simple BTRFS example

⭐ External log device example

🎀 Example using a GPT partition table and EFI/ESP partition

config — the actual stanzas

lvmoption — the lvm stanza's lil menu

raidoption — same energy, raid flavored

cryptsetupoption — short but mighty

option — the disk stanza's full menu

volume — what an actual entry looks like

type — the type slot

mountpoint

name

sizespec — numbers, but make it fashion

size — the drama of ranges

tmpfs_size

mount_options

filesystem

luks_options

fs_options — the last slot

💀 CAVEATS 💀

✨ SEE ALSO ✨

👑 AUTHOR 👑

🌸 Simple configuration of `/dev/sda`