[Fai-commit] r6410 - trunk/man
Michael Tautschnig
mt at alioth.debian.org
Fri Apr 15 13:19:06 UTC 2011
Author: mt
Date: 2011-04-15 13:18:55 +0000 (Fri, 15 Apr 2011)
New Revision: 6410
Modified:
trunk/man/setup-storage.8
Log:
setup-storage.8: Move examples section to the front, several clarifications, additional (simple) RAID example.
Modified: trunk/man/setup-storage.8
===================================================================
--- trunk/man/setup-storage.8 2011-04-15 13:14:02 UTC (rev 6409)
+++ trunk/man/setup-storage.8 2011-04-15 13:18:55 UTC (rev 6410)
@@ -14,11 +14,11 @@
\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. It handles all file systems supported by
+and LVM volumes plus encryption and tmpfs. It handles all file systems supported by
\fBparted\fP(8)
as well as ntfs but is flexible enough to be extended to further types as well.
Once the storage devices are prepared, an appropriate
-\fBfstab\fP(5)
+\fBfstab\fP(5) (and possibly also a \fBcrypttab\fP(5))
file is generated.
Without the
@@ -57,8 +57,11 @@
.TP
\fB\-d\fP
-Enable debugging output.
+Enable debugging output. Equivalent to environment variable
+.IR debug
+set to a non-zero value. See below for further details.
+
.TP
\fB\-h\fP
Display the synopsis and version info and exit.
@@ -93,8 +96,8 @@
.TP
.B flag_initial
This variable determines if partitions should be preserved when they
-are tagged as to be preserved. Normally set by the list of FAI flags
-(FAI_FLAGS).
+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
@@ -111,9 +114,209 @@
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.
-Furthermore, if encryption was configured, a proper
+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
+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
+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
@@ -236,14 +439,20 @@
.br
| preserve_always:([[:digit:]]+(,[[:digit:]]+)*|all)
.br
- /* preserve partitions -- always */
+ /* 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 */
+ 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 */
@@ -420,17 +629,20 @@
.SH MIGRATION FROM SETUP_HARDDISKS
The major differences to the prior configuration syntax are:
.IP \(bu
-The disk_config ... line allows for the keywords lvm and raid
+The disk_config ... line allows for the keywords lvm, raid, crypt, and tmpfs.
.IP \(bu
-Options may need to be appended to the disk_config line
+Options may need to be appended to the disk_config line.
.IP \(bu
-The ";" is not used anymore, the options that were given there have now been split up
-.IP \(bu
+The ";" is not used anymore. The options that were given there have now been
+split up:
+.RS
+.IP \-
The filesystem is now an explicit parameter; note that the order of
filesystem/mount-options is the same /etc/fstab as opposed to the previous
format of disk_config.
-.IP \(bu
+.IP \-
Any options to mkfs.xxx may be given using createopts="".
+.RE
.IP \(bu
The "preserveX" and "boot" options are one of the options now given on the
disk_config line, using preserve_reinstall, preserve_always, or preserve_lazy,
@@ -445,141 +657,7 @@
Support for LVM and RAID is completely new
.IP \(bu
Resizing partitions and filesystems is supported
-.SH EXAMPLES
-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 the 6th and the 7th partition. The disklabel is msdos which is the default
-for x86. Furthermore the 3rd partition 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
-.sp
-.nf
-.ta 6n 9n 43n 48n
-disk_config raid
-raid1 / sda1,sdd1 ext2 rw,errors=remount-ro
-raid0 - disk2.2,sdc1,sde1:spare:missing ext2 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.
-
-.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
-
-.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
-
-.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
-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 CAVEATS
.IP \(bu
Partition UUID cannot be obtained: In case a partition was previously used as
@@ -598,7 +676,7 @@
reasons why a system may fail to boot.
.IP \(bu
Crypto support requires some site-specific changes: If you use cryptsetup
-stanza, a crypttab file and key files for all luks volumes will be created
+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
@@ -607,7 +685,7 @@
This program is part of FAI (Fully Automatic Installation).
The FAI homepage is http://fai-project.org.
-Further documentation, including coding related information, is maintained
+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
More information about the Fai-commit
mailing list