[Fai-commit] r6229 - branches/experimental/patches
Michael Tautschnig
mt at alioth.debian.org
Sat Dec 4 18:04:20 UTC 2010
Author: mt
Date: 2010-12-04 18:04:09 +0000 (Sat, 04 Dec 2010)
New Revision: 6229
Added:
branches/experimental/patches/setup-storage_man-page-fixes
Modified:
branches/experimental/patches/series
Log:
Reworked setup-storage man page
Modified: branches/experimental/patches/series
===================================================================
--- branches/experimental/patches/series 2010-12-04 09:51:59 UTC (rev 6228)
+++ branches/experimental/patches/series 2010-12-04 18:04:09 UTC (rev 6229)
@@ -25,3 +25,4 @@
setup-storage_hardcode-63-sectors
setup-storage_no-decimal
fcopy-unchanged-uid-gid
+setup-storage_man-page-fixes
Added: branches/experimental/patches/setup-storage_man-page-fixes
===================================================================
--- branches/experimental/patches/setup-storage_man-page-fixes (rev 0)
+++ branches/experimental/patches/setup-storage_man-page-fixes 2010-12-04 18:04:09 UTC (rev 6229)
@@ -0,0 +1,461 @@
+2010-12-04 Michael Tautschnig <mt at debian.org>
+
+ * setup-storage.8: Move examples section to the front, several clarifications,
+ additional (simple) RAID example.
+Index: trunk/man/setup-storage.8
+===================================================================
+--- trunk.orig/man/setup-storage.8
++++ trunk/man/setup-storage.8
+@@ -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,7 +57,10 @@
+
+ .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
+@@ -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,207 @@
+ 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
++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,13 +437,19 @@
+ .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
+@@ -434,17 +641,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
+-.IP \(bu
+-Options may need to be appended to the disk_config line
++The disk_config ... line allows for the keywords lvm, raid, crypt, and tmpfs.
+ .IP \(bu
+-The ";" is not used anymore, the options that were given there have now been split up
++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:
++.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,
+@@ -459,140 +669,6 @@
+ 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
+@@ -612,7 +688,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
+@@ -621,7 +697,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
+ FAI is courtesy of Thomas Lange <lange at informatik.uni-koeln.de>. Michael
More information about the Fai-commit
mailing list