Document simplified configuration commands.

1 files changed, 335 insertions, 19 deletions

diff --git a/sbin/vinum/vinum.8 b/sbin/vinum/vinum.8
index b8343f3..1637559 100644
--- a/sbin/vinum/vinum.8
+++ b/sbin/vinum/vinum.8
@@ -46,12 +46,6 @@
 .Op command
 .Op Fl options
 .Sh COMMANDS
-.Cd create Op Fl f Ar description-file
-.in +1i
-Create a volume as described in
-.Ar description-file
-.in
-.\" XXX remove this
 .Cd attach Ar plex Ar volume
 .Op Nm rename
 .Cd attach Ar subdisk Ar plex Ar [offset]
@@ -60,6 +54,22 @@ Create a volume as described in
 Attach a plex to a volume, or a subdisk to a plex.
 .in
 .\" XXX remove this
+.Nm concat
+.Op Fl f
+.Op Fl n Ar name
+.Op Fl v
+.Ar drives
+.in +1i
+Create a concatenated volume from the specified drives.
+.in
+.Cd create
+.Op Fl f
+.Ar description-file
+.in +1i
+Create a volume as described in
+.Ar description-file
+.in
+.\" XXX remove this
 .Cd debug
 .in +1i
 Cause the volume manager to enter the kernel debugger.
@@ -149,17 +159,26 @@ List information about plexes
 .in +1i
 List information about volumes
 .in
+.Cd makedev
+.in +1i
+Remake the device nodes in
+.Ar /dev/vinum .
+.in
+.Nm mirror
+.Op Fl f
+.Op Fl n Ar name
+.Op Fl s
+.Op Fl v
+.Ar drives
+.in +1i
+Create a mirrored volume from the specified drives.
+.in
 .Cd printconfig
 .Op Pa file
 .in +1i
 Write a copy of the current configuration to
 .Pa file .
 .in
-.Cd makedev
-.in +1i
-Remake the device nodes in
-.Ar /dev/vinum .
-.in
 .Cd quit
 .in +1i
 Exit the
@@ -249,6 +268,14 @@ Terminate access to the objects, or stop
 .Nm
 if no parameters are specified.
 .in
+.Nm stripe
+.Op Fl f
+.Op Fl n Ar name
+.Op Fl v
+.Ar drives
+.in +1i
+Create a striped volume from the specified drives.
+.in
 .Sh DESCRIPTION
 .Nm
 is a utility program to communicate with the \fBVinum\fP\| logical volume
@@ -289,6 +316,14 @@ removes
 .Ar myvolume
 even if it is open.  Any subsequent access to the volume will almost certainly
 cause a panic.
+.It Fl n Ar name
+Use the
+.Fl n
+option to specify a volume name to the simplified configuration commands
+.Nm concat ,
+.Nm mirror
+and
+.Nm stripe .
 .It Fl r
 The
 .Fl r
@@ -307,7 +342,9 @@ The
 .Fl s
 .if t (``statistics'')
 .if n ("statistics")
-option is used by the list commands to display statistical information.
+option is used by the list commands to display statistical information.  The
+.Nm mirror
+command also uses this flag to specify that it should create striped plexes.
 .It Fl v
 The
 .Fl v
@@ -387,6 +424,50 @@ multiplied by the stripe size.  For example, in a plex of block size 256k, the
 first subdisk will have offset 0, the second offset 256k, the third 512k, etc.
 This calculation ignores parity blocks in RAID-5 plexes.
 .El
+.It Nm concat
+.Op Fl f
+.Op Fl n Ar name
+.Op Fl v
+.Ar drives
+.br
+The
+.Nm concat
+command provides a simplified alternative to the
+.Nm create
+command for creating volumes with a single concatenated plex.  The largest
+contiguous space available on each drive is used to create the subdisks for the
+plexes.
+.Pp
+Normally, the
+.Nm concat
+command creates an arbitrary name for the volume and its components.  The name
+is composed of the text
+.Ar vinum
+and a small integer, for example
+.Ar vinum3 .
+You can override this with the
+.Fl n Ar name
+option, which assigns the name specified to the volume.  The plexes and subdisks
+are named after the volume in the default manner.
+.Pp
+There is no choice of name for the drives.  If the drives have already been
+initialized as
+.Nm
+drives, the name remains.  Otherwise the drives are given names starting with
+the text
+.Ar vinumdrive
+and a small integer, for example
+.Ar vinumdrive7 .
+As with the
+.Nm create
+command, the
+.Fl f
+option can be used to specify that a previous name should be overwritten.  The
+.Fl v
+is used to specify verbose output.
+.Pp
+See the section SIMPLIFIED CONFIGURATION below for some examples of this
+command.
 .It Nm create Op Fl f Ar description-file
 .sp
 .Nm
@@ -746,13 +827,62 @@ command removes the directory /dev/vinum and recreates it with device nodes
 which reflect the current configuration.  This command is not intended for
 general use, and is provided for emergency use only.
 .Pp
-.It Nm quit
-Exit the
-.Nm
-program when running in interactive mode.  Normally this would be done by
-entering the
-.Ar EOF
-character.
+.It Nm mirror
+.Op Fl f
+.Op Fl n Ar name
+.Op Fl s
+.Op Fl v
+.Ar drives
+.br
+The
+.Nm mirror
+command provides a simplified alternative to the
+.Nm create
+command for creating mirrored volumes.  Without any options, it creates a RAID-1
+(mirrored) volume with two concatenated plexes.  The largest contiguous space
+available on each drive is used to create the subdisks for the plexes.  The
+first plex is built from the odd-numbered drives in the list, and the second
+plex is built from the even-numbered drives.  If the drives are of different
+sizes, the plexes will be of different sizes.
+.Pp
+If the
+.Fl s
+option is provided,
+.Nm mirror
+builds striped plexes with a stripe size of 256 kB.  The size of the subdisks in
+each plex is the size of the smallest contiguous storage available on any of the
+drives which form the plex.  Again, the plexes may differ in size.
+.Pp
+Normally, the
+.Nm mirror
+command creates an arbitrary name for the volume and its components.  The name
+is composed of the text
+.Ar vinum
+and a small integer, for example
+.Ar vinum3 .
+You can override this with the
+.Fl n Ar name
+option, which assigns the name specified to the volume.  The plexes and subdisks
+are named after the volume in the default manner.
+.Pp
+There is no choice of name for the drives.  If the drives have already been
+initialized as
+.Nm
+drives, the name remains.  Otherwise the drives are given names starting with
+the text
+.Ar vinumdrive
+and a small integer, for example
+.Ar vinumdrive7 .
+As with the
+.Nm create
+command, the
+.Fl f
+option can be used to specify that a previous name should be overwritten.  The
+.Fl v
+is used to specify verbose output.
+.Pp
+See the section SIMPLIFIED CONFIGURATION below for some examples of this
+command.
 .It Nm printconfig Op Pa file
 Write a copy of the current configuration to
 .Pa file
@@ -764,6 +894,13 @@ of the drives.  If you omit
 .Nm
 writes the list to
 .Pa stdout .
+.It Nm quit
+Exit the
+.Nm
+program when running in interactive mode.  Normally this would be done by
+entering the
+.Ar EOF
+character.
 .It Nm read
 .Ar disk Op disk...
 .Pp
@@ -1073,7 +1210,186 @@ option tells
 to omit this checking and remove the object anyway.  Use this option with great
 care and understanding: used incorrectly, it can result in serious data
 corruption.
+.It Nm stripe
+.Op Fl f
+.Op Fl n Ar name
+.Op Fl v
+.Ar drives
+.br
+The
+.Nm stripe
+command provides a simplified alternative to the
+.Nm create
+command for creating volumes with a single striped plex.  The size of the
+subdisks is the size of the largest contiguous space available on all the
+specified drives.  The stripe size is fixed at 256 kB.
+.Pp
+Normally, the
+.Nm stripe
+command creates an arbitrary name for the volume and its components.  The name
+is composed of the text
+.Ar vinum
+and a small integer, for example
+.Ar vinum3 .
+You can override this with the
+.Fl n Ar name
+option, which assigns the name specified to the volume.  The plexes and subdisks
+are named after the volume in the default manner.
+.Pp
+There is no choice of name for the drives.  If the drives have already been
+initialized as
+.Nm
+drives, the name remains.  Otherwise the drives are given names starting with
+the text
+.Ar vinumdrive
+and a small integer, for example
+.Ar vinumdrive7 .
+As with the
+.Nm create
+command, the
+.Fl f
+option can be used to specify that a previous name should be overwritten.  The
+.Fl v
+is used to specify verbose output.
+.Pp
+See the section SIMPLIFIED CONFIGURATION below for some examples of this
+command.
 .El
+.Sh SIMPLIFIED CONFIGURATION
+This section describes a simplified interface to
+.Nm
+configuration using the
+.Nm concat ,
+.Nm mirror
+and
+.Nm stripe
+commands.  These commands create convenient configurations for some more normal
+situations, but they are not as flexible as the
+.Nm create
+command.
+.Pp
+See above for the description of the commands.  Here are some examples, all
+performed with the same collection of disks.  Note that the first drive,
+.Pa /dev/da1h ,
+is smaller than the others.  This has an effect on the sizes chosen for each
+kind of subdisk.
+.Pp
+The following examples all use the
+.Fl v
+option to show the commands passed to the system, and also to list the structure
+of the volume.  Without the
+.Fl v
+option, these commands produce no output.
+.Ss Volume with a single concatenated plex
+Use a volume with a single concatenated plex for the largest possible storage
+without resilience to drive failures:
+.Bd -literal
+# vinum ->  concat -v /dev/da1h /dev/da2h /dev/da3h /dev/da4h
+volume vinum0
+  plex name vinum0.p0 org concat
+drive vinumdrive0 device /dev/da1h
+    sd name vinum0.p0.s0 drive vinumdrive0 size 0
+drive vinumdrive1 device /dev/da2h
+    sd name vinum0.p0.s1 drive vinumdrive1 size 0
+drive vinumdrive2 device /dev/da3h
+    sd name vinum0.p0.s2 drive vinumdrive2 size 0
+drive vinumdrive3 device /dev/da4h
+    sd name vinum0.p0.s3 drive vinumdrive3 size 0
+V vinum0                State: up       Plexes:       1 Size:       2134 MB
+P vinum0.p0           C State: up       Subdisks:     4 Size:       2134 MB
+S vinum0.p0.s0          State: up       PO:        0  B Size:        414 MB
+S vinum0.p0.s1          State: up       PO:      414 MB Size:        573 MB
+S vinum0.p0.s2          State: up       PO:      988 MB Size:        573 MB
+S vinum0.p0.s3          State: up       PO:     1561 MB Size:        573 MB
+.Ed
+.Pp
+In this case, the complete space on all four disks was used, giving a volume
+2134 MB in size.
+.Ss Volume with a single striped plex
+A volume with a single striped plex may give better performance than a
+concatenated plex, but restrictions on striped plexes can mean that the volume
+is smaller.  It will also not be resilient to a drive failure:
+.Bd -literal
+vinum -> stripe -v /dev/da1h /dev/da2h /dev/da3h /dev/da4h
+drive vinumdrive0 device /dev/da1h
+drive vinumdrive1 device /dev/da2h
+drive vinumdrive2 device /dev/da3h
+drive vinumdrive3 device /dev/da4h
+volume vinum0
+  plex name vinum0.p0 org striped 256k
+    sd name vinum0.p0.s0 drive vinumdrive0 size 849825b
+    sd name vinum0.p0.s1 drive vinumdrive1 size 849825b
+    sd name vinum0.p0.s2 drive vinumdrive2 size 849825b
+    sd name vinum0.p0.s3 drive vinumdrive3 size 849825b
+V vinum0                State: up       Plexes:       1 Size:       1659 MB
+P vinum0.p0           S State: up       Subdisks:     4 Size:       1659 MB
+S vinum0.p0.s0          State: up       PO:        0  B Size:        414 MB
+S vinum0.p0.s1          State: up       PO:      256 kB Size:        414 MB
+S vinum0.p0.s2          State: up       PO:      512 kB Size:        414 MB
+S vinum0.p0.s3          State: up       PO:      768 kB Size:        414 MB
+.Ed
+.Pp
+In this case, the size of the subdisks has been limited to the smallest
+available disk, so the resulting volume is only 1659 MB in size.
+.Ss Mirrored volume with two concatenated plexes
+For more reliability, use a mirrored, concatenated volume:
+.Bd -literal
+vinum -> mirror -v -n mirror /dev/da1h /dev/da2h /dev/da3h /dev/da4h
+drive vinumdrive0 device /dev/da1h
+drive vinumdrive1 device /dev/da2h
+drive vinumdrive2 device /dev/da3h
+drive vinumdrive3 device /dev/da4h
+volume mirror setupstate
+  plex name mirror.p0 org concat
+    sd name mirror.p0.s0 drive vinumdrive0 size 0b
+    sd name mirror.p0.s1 drive vinumdrive2 size 0b
+  plex name mirror.p1 org concat
+    sd name mirror.p1.s0 drive vinumdrive1 size 0b
+    sd name mirror.p1.s1 drive vinumdrive3 size 0b
+V mirror                State: up       Plexes:       2 Size:       1146 MB
+P mirror.p0           C State: up       Subdisks:     2 Size:        988 MB
+P mirror.p1           C State: up       Subdisks:     2 Size:       1146 MB
+S mirror.p0.s0          State: up       PO:        0  B Size:        414 MB
+S mirror.p0.s1          State: up       PO:      414 MB Size:        573 MB
+S mirror.p1.s0          State: up       PO:        0  B Size:        573 MB
+S mirror.p1.s1          State: up       PO:      573 MB Size:        573 MB
+.Ed
+.Pp
+This example specifies the name of the volume:
+.Ar mirror .
+Since one drive is smaller than the others, the two plexes are of different
+size, and the last 158 MB of the volume is non-resilient.  To ensure complete
+reliability in such a situation, use the
+.Nm create
+command to create a volume with 988 MB.
+.Ss Mirrored volume with two striped plexes
+Alternatively, use the
+.Fl s
+option to create a mirrored volume with two striped plexes:
+.Bd -literal
+vinum -> mirror -v -n raid10 -s /dev/da1h /dev/da2h /dev/da3h /dev/da4h
+drive vinumdrive0 device /dev/da1h
+drive vinumdrive1 device /dev/da2h
+drive vinumdrive2 device /dev/da3h
+drive vinumdrive3 device /dev/da4h
+volume raid10 setupstate
+  plex name raid10.p0 org striped 256k
+    sd name raid10.p0.s0 drive vinumdrive0 size 849825b
+    sd name raid10.p0.s1 drive vinumdrive2 size 849825b
+  plex name raid10.p1 org striped 256k
+    sd name raid10.p1.s0 drive vinumdrive1 size 1173665b
+    sd name raid10.p1.s1 drive vinumdrive3 size 1173665b
+V raid10                State: up       Plexes:       2 Size:       1146 MB
+P raid10.p0           S State: up       Subdisks:     2 Size:        829 MB
+P raid10.p1           S State: up       Subdisks:     2 Size:       1146 MB
+S raid10.p0.s0          State: up       PO:        0  B Size:        414 MB
+S raid10.p0.s1          State: up       PO:      256 kB Size:        414 MB
+S raid10.p1.s0          State: up       PO:        0  B Size:        573 MB
+S raid10.p1.s1          State: up       PO:      256 kB Size:        573 MB
+.Ed
+.Pp
+In this case, the usable part of the volume is even smaller, since the first
+plex has shrunken to match the smallest drive.
 .Ss CONFIGURATION FILE
 .Nm
 requires that all parameters to the