[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