[Fai-commit] r5162 - in trunk: debian man
lange at alioth.debian.org
lange at alioth.debian.org
Tue Sep 16 13:45:25 UTC 2008
Author: lange
Date: 2008-09-16 13:45:23 +0000 (Tue, 16 Sep 2008)
New Revision: 5162
Modified:
trunk/debian/changelog
trunk/man/setup-storage.8
Log:
setup-storage.8: replace mdoc macro version with man macro version
Modified: trunk/debian/changelog
===================================================================
--- trunk/debian/changelog 2008-09-16 13:37:06 UTC (rev 5161)
+++ trunk/debian/changelog 2008-09-16 13:45:23 UTC (rev 5162)
@@ -9,6 +9,7 @@
* faimond.8: minor fixes
* install_packages.8: minor fixes
* make-fai-nfsroot.8: minor fixes
+ * setup-storage.8: replace mdoc macro version with man macro version
-- Thomas Lange <lange at debian.org> Tue, 16 Sep 2008 15:36:24 +0200
Modified: trunk/man/setup-storage.8
===================================================================
--- trunk/man/setup-storage.8 2008-09-16 13:37:06 UTC (rev 5161)
+++ trunk/man/setup-storage.8 2008-09-16 13:45:23 UTC (rev 5162)
@@ -1,366 +1,438 @@
-.\" Hey, EMACS: -*- nroff -*-
-.\" .TH setup-storage 8 "05 september 2008" "FAI 3.2.9"
-.\" Please adjust this date whenever revising the manpage.
-.\"
-.\" Some roff macros, for reference:
-.\" .nh disable hyphenation
-.\" .hy enable hyphenation
-.\" .ad l left justify
-.\" .ad b justify to both left and right margins
-.\" .nf disable filling
-.\" .fi enable filling
-.\" .br insert line break
-.\" .sp <n> insert n+1 empty lines
-.\" for manpage-specific macros, see man(7)
-.Dd September 5, 2008
-.Dt SETUP-STORAGE 8 SMM
-.Os Debian/GNU Linux
-.Sh NAME
-.Nm setup-storage
-.Nd automatically prepare storage devices
-.Sh SYNOPSIS
-.Nm
-.Op Fl X
-.Op Fl f Ar filename
-.Op Fl d
-.Op Fl h
-.Sh DESCRIPTION
+.TH setup-storage 8 "September 5, 2008" "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]
+.SH DESCRIPTION
Using FAI disk_config files,
-.Nm
+\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
-.Xr parted 8
+\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
-.Xr fstab 5
+\fBfstab\fP(5)
file is generated.
-.Pp
+
Without the
-.Fl X
+\fB\-X\fP
parameter
-.Nm
+\fBsetup-storage\fP
runs in test-only mode and does not execute commands other than writing disk
labels to a blank disk.
-.Pp
+
The exit code of
-.Nm
+\fBsetup-storage\fP
is 0 if all operations were performed successfully and non-zero if an error
occurs.
-.Sh USAGE
+.SH USAGE
To enable the use of the new partioning tool setup-storage you have to
-set USE_SETUP_STORAGE=1 in the according class file in configspace (like
+set
+.IR USE_SETUP_STORAGE =1
+in the according class file in configspace (like
/srv/fai/config/class/FAIBASE.var for example).
-.Sh OPTIONS
-.Bl -tag -width Ds
-.Pp
-.It Fl X
+.SH OPTIONS
+
+.TP
+\fB\-X\fP
Really write the configuration to disk. Otherwise
-.Nm
+\fBsetup-storage\fP
runs in test-only mode.
-.Pp
-.It Fl f Ar filename
+
+.TP
+\fB\-f\fP \fIfilename\fP
Normally
-.Nm
+\fBsetup-storage\fP
selects an appropriate configuration from
-.Sm off
-.Ev FAI
+.IRFAI
/disk_config/
-.Sm on
by picking the first class from
-.Ev classes
+.IR classes
that has an existing file.
If however
-.Fl f
+\fB\-f\fP
is given the configuration in
-.Ar filename
+\fIfilename\fP
is used.
-.Pp
-.It Fl d
+
+.TP
+\fB\-d\fP
Enable debugging output.
-.Pp
-.It Fl h
+
+.TP
+\fB\-h\fP
Display the synopsis and version info and exit.
-.El
-.Sh ENVIRONMENT
-.Nm
+.SH ENVIRONMENT
+\fBsetup-storage\fP
will use the following environment variables:
-.Bl -tag -width "disklist"
-.It Ev disklist
+.TP
+.B disklist
The
-.Ev disklist
+.IR disklist
variable must contain a newline separated list of disk drives available in the
system. Their order matters as they may be referred to as disk1, etc. in
disk_config.
-.It Ev debug
+.TP
+.B debug
If
-.Ev debug
+.IR debug
is set to a non-zero value all actions and details to track the operation of
-.Nm
+\fBsetup-storage\fP
are printed to stderr.
-.It Ev FAI
+.TP
+.B FAI
The location of the config space to find the disk_config directory.
-.It Ev classes
+.TP
+.B classes
The list of FAI classes to determine the appropriate configuration to choose.
-.It Ev LOGDIR
-.Nm
+.TP
+.B LOGDIR
+\fBsetup-storage\fP
generates disk_var.sh and fstab (see below) in this directory.
-.El
-.Sh FILES
+.SH FILES
If
-.Nm
+\fBsetup-storage\fP
executes successfully an
-.Xr fstab 5
+\fBfstab\fP(5)
file matching the specified configuration is generated as
-.Sm off
-.Ev LOGDIR
+.IRLOGDIR
/fstab.
-.Sm on
Further
-.Sm off
-.Ev LOGDIR
+.IRLOGDIR
/disk_var.sh
-.Sm on
is generated and may be sourced to get the variables
-.Ev SWAPLIST, ROOT_PARTITION, BOOT_PARTITION
+.IR SWAPLIST ,
+.IR ROOT_PARTITION ,
+.IR BOOT_PARTITION
and
-.Ev BOOT_DEVICE.
+.IR BOOT_DEVICE .
The latter two will only be set in case they
reside on a disk drive.
-.Sh SYNTAX
+.SH SYNTAX
This section describes the syntax of disk_config files
-.Pp
-.Bd -literal
+
+
file ::= <lines> EOF
-.Ed
-.Pp
-.Bd -literal
+.br
+
+
lines ::= EOL
+.br
/* empty lines or whitespace only */
+.br
| <comment> EOL
+.br
| <config> EOL
-.Ed
-.Pp
-.Bd -literal
+.br
+
+
comment ::= #.*
-.Ed
-.Pp
-.Bd -literal
+.br
+
+
config ::= disk_config lvm( <lvmoption>)*
+.br
| disk_config raid( <raidoption>)*
+.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 */
+.br
| <volume>
-.Ed
-.Pp
-.Bd -literal
+.br
+
+
lvmoption ::= /* empty */
+.br
| preserve_always:[^/,\\s\\-]+-[^/,\\s\\-]+(,[^/,\\s\\-]+-[^/,\\s\\-]+)*
+.br
/* preserve partitions -- always */
+.br
| preserve_reinstall:[^/,\\s\\-]+-[^/,\\s\\-]+(,[^/,\\s\\-]+-[^/,\\s\\-]+)*
+.br
/* preserve partitions -- unless the system is installed for the
+.br
first time */
+.br
| resize:[^/,\\s\\-]+-[^/,\\s\\-]+(,[^/,\\s\\-]+-[^/,\\s\\-]+)*
+.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
*/
-.Ed
-.Pp
-.Bd -literal
+.br
+
+
raidoption ::= /* empty */
+.br
| preserve_always:[[:digit:]]+(,[[:digit:]]+)*
+.br
/* preserve partitions -- always */
+.br
| preserve_reinstall:[[:digit:]]+(,[[:digit:]]+)*
+.br
/* preserve partitions -- unless the system is installed for the
+.br
first time */
+.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
*/
-.Ed
-.Pp
-.Bd -literal
+.br
+
+
option ::= /* empty */
+.br
| preserve_always:[[:digit:]]+(,[[:digit:]]+)*
+.br
/* preserve partitions -- always */
+.br
| preserve_reinstall:[[:digit:]]+(,[[:digit:]]+)*
+.br
/* preserve partitions -- unless the system is installed for the
+.br
first time */
+.br
| resize:[[:digit:]]+(,[[:digit:]]+)*
+.br
/* attempt to resize partitions */
+.br
| disklabel:(msdos|gpt)
+.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
*/
-.Ed
-.Pp
-.Bd -literal
+.br
+
+
volume ::= <type> <mountpoint> <size> <filesystem> <mount_options> <fs_options>
+.br
| vg <name> <size>
+.br
/* lvm vg */
-.Ed
-.Pp
-.Bd -literal
+.br
+
+
type ::= primary
+.br
/* for physical disks only */
+.br
| logical
+.br
/* for physical disks only */
+.br
| raid[0156]
+.br
/* raid level */
+.br
| [^/[:space:]]+-[^/[:space:]]+
+.br
/* lvm logical volume: vg name and lv name*/
-.Ed
-.Pp
-.Bd -literal
+.br
+
+
mountpoint ::= -
+.br
/* do not mount */
+.br
| swap
+.br
/* swap space */
+.br
| /[^[:space:]]*(:encrypt)?
+.br
/* fully qualified path; if :encrypt is given the partition
+.br
* will be encrypted, the key is generated automatically */
-.Ed
-.Pp
-.Bd -literal
+.br
+
+
name ::= [^/[:space:]]+
+.br
/* lvm volume group name */
-.Ed
-.Pp
-.Bd -literal
+.br
+
+
size ::= [[:digit:]]+[kMGTP%]?(-([[:digit:]]+[kMGTP%]?)?)?(:resize)?
+.br
/* size in kilo, mega (default), giga, tera or petabytes or %,
+.br
* possibly given as a range; physical
+.br
* partitions or lvm logical volumes only; */
+.br
| -[[:digit:]]+[kMGTP%]?(:resize)?
+.br
/* size in kilo, mega (default), giga, tera or petabytes or %,
+.br
* given as upper limit; physical partitions
+.br
* or lvm logical volumes only */
+.br
| [^,:[:space:]]+(:(spare|missing))*(,[^,:[:space:]]+(:(spare|missing))*)*
+.br
/* devices and options for a raid or lvm vg */
-.Ed
-.Pp
-.Bd -literal
+.br
+
+
mount_options ::= [^[:space:]]+
-.Ed
-.Pp
-.Bd -literal
+.br
+
+
filesystem ::= -
+.br
| swap
+.br
| [^[:space:]]
+.br
/* mkfs.xxx must exist */
-.Ed
-.Pp
-.Bd -literal
+.br
+
+
fs_options ::= (createopts=".*"|tuneopts=".*")*
+.br
/* options to append to mkfs.xxx and to the filesystem-specific
+.br
* tuning tool */
-.Ed
-.Sh MIGRATION FROM SETUP_HARDDISKS
+.br
+.SH MIGRATION FROM SETUP_HARDDISKS
The major differences to the prior configuration syntax are:
-.Bl -bullet -offset indent -compact
-.It
+.IP \(bu
The disk_config ... line allows for the keywords lvm and raid
-.It
+.IP \(bu
Options may need to be appended to the disk_config line
-.It
+.IP \(bu
The ";" is not used anymore, the options that were given there have now been split up
-.Bl -dash -offset indent -compact
-.It
+.IP \(bu
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.
-.It
+.IP \(bu
Any options to mkfs.xxx may be given using createopts="".
-.It
+.IP \(bu
The "preserveX" and "boot" options are one of the options now given on the
disk_config line, using preserve_reinstall or preserve_always and bootable.
preserve_always is equivalent to the previous preserveX option, whereas
preserve_reinstall preserves the partition unless "initial" is given as one of
the FAI_FLAGS.
-.El
-.It
+.IP \(bu
Support for LVM and RAID is completely new
-.It
+.IP \(bu
Resizing partitions and filesystems is supported
-.El
-.Sh EXAMPLES
+.SH EXAMPLES
Simple configuration of /dev/hda
-.Bd -literal -offset indent -compact
+
disk_config hda preserve_always:6,7 disklabel:msdos bootable:3
+.br
primary /boot 20-100 ext3 rw
+.br
primary swap 1000 swap sw
+.br
primary / 12000 ext3 rw createopts="-b 2048"
+.br
logical /tmp 1000 ext3 rw,nosuid
+.br
logical /usr 5000 ext3 rw
+.br
logical /var 10%- ext3 rw
+.br
logical /nobackup 0- xfs rw
-.Ed
-.Bl -bullet -compact
-.It
+.br
+.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.
-.It
+.IP \(bu
Create a primary partition /dev/hda1 with a size between 20 and 100 MB and mount it
read-write as /boot; it is formatted using ext3 filesystem.
-.It
+.IP \(bu
/dev/hda2 will be a swap space of 1000 MB
-.It
+.IP \(bu
/dev/hda3 should be formatted using ext3 filesystem; when calling mkfs.ext3
the option "-b 2048" is appended.
-.It
+.IP \(bu
Create the logical partition /dev/hda5
-.It
+.IP \(bu
Make /dev/hda7 at least 10% of the disk size
-.It
+.IP \(bu
Use mkfs.xfs to format the partition 8
-.El
-.Pp
+
Create a softRAID
-.Bd -literal -offset indent -compact
+
disk_config raid
+.br
raid1 / sda1,sdd1 ext2 rw,errors=remount-ro
+.br
raid0 - disk2.2,sdc1,sde1:spare:missing ext2 default
-.Ed
-.Bl -bullet -compact
-.It
+.br
+.IP \(bu
Create a RAID-1 on /dev/sda1 and /dev/sdd1, format using mkfs.ext2 and mount
it as /
-.It
+.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.
-.El
-.Pp
+
Simple LVM example
-.Bd -literal -offset indent -compact
+
disk_config sda bootable:1
+.br
primary /boot 500 ext3 rw
+.br
primary - 4096- - -
+.br
disk_config lvm
+.br
vg my_pv sda2
+.br
my_pv-_swap swap 2048 swap sw
+.br
my_pv-_root / 2048 ext3 rw
-.Ed
-.Sh SEE ALSO
+.br
+.SH SEE ALSO
This program is part of FAI (Fully Automatic Installation).
The FAI homepage is http://www.informatik.uni-koeln.de/fai.
-.Pp
-.Nm
+
+\fBsetup-storage\fP
is still beta-software being actively developed. Further documentation,
including coding related information, is maintained
in a wiki page at http://faiwiki.informatik.uni-koeln.de/index.php/Setup-storage.
-.Sh AUTHOR
+.SH AUTHOR
FAI is courtesy of Thomas Lange <lange at informatik.uni-koeln.de>. Michael
Tautschnig <mt at debian.org> contributed the initial version of
-.Nm
+\fBsetup-storage\fP
to replace the previous setup-harddisks, with the help of Christian Kern.
More information about the Fai-commit
mailing list