.TH setup-storage 8 "October 23, 2011" "Debian/GNU Linux"
.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 as well as RAID
and LVM volumes plus encryption and tmpfs. It handles following
filesystems: \fBext2/3/4\fP, \fBvFAT(FAT32)\fP, \fBmsdos(FAT16)\fP, \fBreiserFS\fP, \fBXFS\fP and
\fBBTRFS\fP but is flexible enough to 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
.IR disklist. 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.
.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, etc. 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 preserved_initial (see below for details). Normally set by the
list of FAI flags (FAI_FLAGS).
.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), and
.IR 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 and files/boot/grub/menu.lst/postinst.
If encryption was configured, a proper
\fBcrypttab\fP(5)
file plus keyfiles will be generated.
.SH EXAMPLES
\fBsetup-storage\fP configures storage devices according to FAI disk_config
files. 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.

.TP
Simple configuration of /dev/hda
.sp
.nf
.ta 10n 20n 30n 40n 50n
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
.sp
.fi
.PP
.IP \(bu
Preserve /dev/hda6 and /dev/hda7. The disklabel is msdos which is the default
for x86. Furthermore, partition /dev/hda3 is made bootable.
.IP \(bu
Create a primary partition /dev/hda1 with a size between 20 and 100 MiB and mount it
read-write as /boot; it is formatted using ext3 filesystem.
.IP \(bu
/dev/hda2 will be a swap space of 1000 MiB
.IP \(bu
/dev/hda3 should be formatted using ext3 filesystem; when calling mkfs.ext3
the option "\-b 2048" is appended.
.IP \(bu
Create the logical partition /dev/hda5
.IP \(bu
Make /dev/hda7 at least 10% of the disk size
.IP \(bu
Use mkfs.xfs to format the partition 8

.TP
Create a softRAID
.TS
tab(@) nospaces;
l s s s s
l l r l l.
disk_config sda
primary @ - @ 20GiB @ - @ -
primary @ - @ 4GiB @ - @ -

.T&
l s s s s.
disk_config sdb
.T&
l l r l l.
primary @ - @ 20GiB @ - @ -
primary @ - @ 4GiB @ - @ -

.T&
l s s s s.
disk_config raid
.T&
l l l l l.
raid1 @ / @ sda1,sdb1 @ ext3 @ rw
raid1 @ swap @ sda2,sdb2 @ swap @ sw
.TE
.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.
.IP \(bu
Create a RAID-1 on /dev/sda1 and /dev/sdb1, format using mkfs.ext3 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
Advanced softRAID features
.TS
tab(@) nospaces;
l s s s s
l l l l l.
disk_config raid
raid1 @ / @ sda1,sdd1 @ ext2 @ rw,errors=remount-ro
raid0 @ - @ disk2.2,sdc1,sde1:spare:missing @ ext2 @ default
.TE
.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
Simple LVM example
.sp
.nf
.ta 15n 22n 30n 40n
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
.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 18n 28n 38n 45n 55n
disk_config sda
primary -       256     -       -
primary swap    8G      swap    sw
primary -       0-      -       -

disk_config sdb
primary -       256     -       -
primary swap    8G      swap    sw
primary -       0-      -       -

disk_config raid fstabkey:uuid
raid1   /       sda1,sdb1       ext4    rw,noatime,errors=remount-ro
raid1   -       sda3,sdb3       ext4    default

disk_config lvm fstabkey:uuid
vg      vg_system       md1
vg_system-usr   /usr    8G      ext4    rw,noatime
vg_system-var   /var    16G     ext4    rw,noatime
vg_system-varlog        /var/log        8G      ext4    rw,noatime
vg_system-srv   /srv    32G     ext4    rw,noatime
vg_system-tmp   /tmp    32G     ext4    rw,noatime
.sp
.fi
.PP
.IP \(bu
Configure /dev/sda and /dev/sdb 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 /.
.IP \(bu
The third partitions 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.

.TP
Crypt example
.sp
.nf
.ta 10n 20n 30n 40n 50n
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"
.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.

.TP
tmpfs example
.sp
.nf
.ta 10n 20n 30n 40n 50n
disk_config tmpfs
tmpfs   /tmp    RAM:20% defaults
tmpfs   /scratch        3GiB    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.

.TP
Simple BTRFS example
.sp
.nf
.ta 10n 20n 30n 40n 50n
disk_config disk1
primary /boot 500 ext4 rw
primary - 2048 - -

disk_config disk2
primary - 2048 - -

disk_config disk3 sameas:disk2
disk_config disk4 sameas:disk2

disk_config btrfs
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 intial
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
.SH SYNTAX
This section describes the syntax of disk_config files


file ::= <lines> EOF
.br


lines ::= EOL
.br
          /* empty lines or whitespace only */
.br
          | <comment> EOL
.br
          | <config> EOL
.br


comment ::= #.*
.br


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


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


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


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


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


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


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


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


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


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


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


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


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


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


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

.SH CAVEATS
.IP \(bu
Machine does not boot because no partition is marked as bootable: If the
bootable option is not specified, not 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 not boot failures happen because of a missing bootable
marker, explicitly set the bootable option. Of course, there are lots of other
reasons why a system may fail to boot.
.IP \(bu
Crypto support requires some site-specific changes: If you use cryptsetup
stanza, a \fBcrypttab\fP(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. To make encrypted root devices
actually usable, you need to add busybox (and initramfs-tools) to your package
config.
.IP \(bu
For backwards compatibility or other system-specific reasons an alignment to
cylinder boundaries may be necessary. Yet other systems will have other
alignment constraints. setup-storage sets the alignment as follows: If align-at
is set, align accordingly. Otherwise, if any partition on the particular disk is
to be preserved, default to cylinder alignment. Else use sector alignment.
.SH SEE ALSO
This program is part of FAI (Fully Automatic Installation).
The FAI homepage is http://fai-project.org.

Further documentation, including coding related information, is available
in a wiki page at http://wiki.fai-project.org/index.php/Setup-storage.
.SH AUTHOR
The
\fBsetup-storage\fP
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>.