summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--sbin/vinum/vinum.8354
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
OpenPOWER on IntegriCloud