setup-storage(8) | System Manager's Manual | setup-storage(8) |
setup-storage - automatically prepare storage devices
setup-storage [-X] [-f filename] [-d] [-h] [-s] [-D disks] [-L directory]
Using FAI disk_config files, setup-storage computes effective partition and volume sizes and executes the necessary commands to configure storage devices. It manages disk drives as well as RAID and LVM volumes plus encryption and tmpfs. It handles following filesystems: ext2/3/4, vFAT(FAT32), msdos(FAT16), reiserFS, XFS and BTRFS but is flexible enough to be extended to further types as well. Once the storage devices are prepared, an appropriate fstab(5) (and possibly also a crypttab(5) file is generated.
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.
setup-storage will use the following environment variables:
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), and BOOT_DEVICE. The latter two describe the partition and disk/RAID/LVM device hosting the mount point for /boot. If /boot has no extra mount point, / is used instead. 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 crypttab(5) file plus key files will be generated.
setup-storage configures storage devices according to a FAI disk_config file. The full grammar describing the syntax of these disk_config files is given below. First we show a number of examples to give an intuition what these should look like.
disk_config hda preserve_always:6,7 disklabel:msdos bootable:3 primary /boot 20-100 ext3 rw primary swap 1000 swap sw primary / 12000 ext3 rw createopts="-b 2048" logical /tmp 1000 ext3 rw,nosuid logical /usr 5000 ext3 rw logical /var 10%- ext3 rw logical /nobackup 0- xfs rw
disk_config sda | ||||
primary | - | 20GiB | - | - |
primary | - | 4GiB | - | - |
disk_config sdb | ||||
primary | - | 20GiB | - | - |
primary | - | 4GiB | - | - |
disk_config raid | ||||
raid1 | / | sda1,sdb1 | ext3 | rw |
raid1 | swap | sda2,sdb2 | swap | sw |
disk_config raid | ||||
raid1 | / | sda1,sdd1 | ext2 | rw,errors=remount-ro |
raid0 | - | disk2.2,sdc1,sde1:spare:missing | ext2 | default |
disk_config sda bootable:1 primary /boot 500 ext3 rw primary - 4096- - - disk_config lvm vg my_pv sda2 my_pv-_swap swap 2048 swap sw my_pv-_root / 2048 ext3 rw
disk_config disk1 primary - 350 - - primary swap 2G swap sw,pri=1 primary - 0- - - disk_config sdb 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 / 8G ext4 rw,noatime vg_system-var /var 20G ext4 rw,noatime vg_system-home /home 10G ext4 rw,noatime,nosuid,nodev vg_system-tmp /tmp 30G ext4 rw,noatime,nosuid,nodev
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.
disk_config /dev/sdb primary / 21750 ext3 defaults,errors=remount-ro primary /boot 250 ext3 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 ext3 defaults,errors=remount-ro createopts="-m 0"
disk_config cryptsetup luks - /dev/md1 - -
disk_config tmpfs tmpfs /tmp RAM:20% defaults tmpfs /scratch 3GiB defaults
disk_config nfs nfs 11.22.33.44:/export/vm-root/HOSTNAME / defaults
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
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
disk_config disk1 disklabel:gpt fstabkey:uuid bootable:1 primary /boot/efi 200 vfat rw primary / 1G- ext4 rw
This section describes the syntax of disk_config files
file ::= <lines> EOF
lines ::= EOL
/* empty lines or whitespace only */
| <comment> EOL
| <config> EOL
comment ::= #.*
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 hda, whereby full
* path is assumed to be /dev/hda; may contain shell globbing such
* as /dev/disk/by-id/scsi-* */
| <volume>
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, or the uuid
*/
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
*/
cryptsetupoption ::= /* empty */
| randinit
/* initialise all encrypted partitions with random data */
option ::= /* empty */
| preserve_always:([[:digit:]]+(,[[:digit:]]+)*|all)
/* preserve partitions -- always; the numbers refer to partition
numbers, i.e., preserve_always:5 for /dev/hda refers to /dev/hda5,
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)
/* 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.
*/
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 */
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 */
| 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*/
mountpoint ::= (-|swap|/[^[:space:]]*)
/* do not mount, mount as swap, or mount at fully qualified path */
name ::= [^/[:space:]]+
/* lvm volume group name */
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 */
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 */
tmpfs_size ::= <sizespec>
/* tmpfs size */
mount_options ::= [^[:space:]]+
filesystem ::= -
| swap
| [^[:space:]]
/* mkfs.xxx must exist */
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. */
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 */
This program is part of FAI (Fully Automatic Installation). The FAI homepage is https://fai-project.org.
Further documentation, including coding related information, is available in a wiki page at https://wiki.fai-project.org/index.php/Setup-storage.
The setup-storage program was written by Michael Tautschnig <mt@debian.org>, with contributions from Christian Kern, Julien Blache <jblache@debian.org> and others.
The original and primary author of FAI is Thomas Lange <lange@informatik.uni-koeln.de>.
September 18, 2017 | Debian GNU/Linux |