diff options
| -rw-r--r-- | sbin/vinum/vinum.8 | 354 |
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 |
