diff options
author | ru <ru@FreeBSD.org> | 2004-07-02 21:45:06 +0000 |
---|---|---|
committer | ru <ru@FreeBSD.org> | 2004-07-02 21:45:06 +0000 |
commit | 46fddaa54b09baa407fa66a14d46c0cc3a906e60 (patch) | |
tree | 602e903272257a1c5b455a48800dcaa680741026 /sbin/vinum/vinum.8 | |
parent | 20fbd172b22ab587e9d796f4cb8664a235cebe78 (diff) | |
download | FreeBSD-src-46fddaa54b09baa407fa66a14d46c0cc3a906e60.zip FreeBSD-src-46fddaa54b09baa407fa66a14d46c0cc3a906e60.tar.gz |
Mechanically kill hard sentence breaks.
Diffstat (limited to 'sbin/vinum/vinum.8')
-rw-r--r-- | sbin/vinum/vinum.8 | 792 |
1 files changed, 532 insertions, 260 deletions
diff --git a/sbin/vinum/vinum.8 b/sbin/vinum/vinum.8 index fd8db09..157b020 100644 --- a/sbin/vinum/vinum.8 +++ b/sbin/vinum/vinum.8 @@ -173,7 +173,8 @@ Write a copy of the current configuration to .It Ic quit Exit the .Nm -utility when running in interactive mode. Normally this would be done by +utility when running in interactive mode. +Normally this would be done by entering the .Dv EOF character. @@ -271,12 +272,14 @@ utility communicates with the kernel component of the Vinum logical volume manager. It is designed either for interactive use, when started without command line arguments, or to execute a single command if the command is supplied on the -command line. In interactive mode, +command line. +In interactive mode, .Nm maintains a command line history. .Sh OPTIONS .Nm -commands may optionally be followed by an option. Any of the following options +commands may optionally be followed by an option. +Any of the following options may be specified with any command, but in some cases the options are ignored. For example, the .Ic stop @@ -290,14 +293,18 @@ options. The .Fl f .Pq Dq force -option overrides safety checks. Use with extreme care. This option is for -emergency use only. For example, the command +option overrides safety checks. +Use with extreme care. +This option is for +emergency use only. +For example, the command .Pp .Dl rm -f myvolume .Pp removes .Ar myvolume -even if it is open. Any subsequent access to the volume will almost certainly +even if it is open. +Any subsequent access to the volume will almost certainly cause a panic. .It Fl i Ar millisecs When performing the @@ -306,7 +313,8 @@ and .Ic start commands, wait .Ar millisecs -milliseconds between copying each block. This lowers the load on the system. +milliseconds between copying each block. +This lowers the load on the system. .It Fl n Ar name Use the .Fl n @@ -319,7 +327,8 @@ The .Fl r .Pq Dq recursive option is used by the list commands to display information not -only about the specified objects, but also about subordinate objects. For +only about the specified objects, but also about subordinate objects. +For example, in conjunction with the .Ic lv command, the @@ -330,7 +339,8 @@ volume. The .Fl s .Pq Dq statistics -option is used by the list commands to display statistical information. The +option is used by the list commands to display statistical information. +The .Ic mirror command also uses this option to specify that it should create striped plexes. .It Fl S Ar size @@ -374,9 +384,12 @@ commands perform the following functions: .Op Cm rename .Xc .Nm Ic attach -inserts the specified plex or subdisk in a volume or plex. In the case of a -subdisk, an offset in the plex may be specified. If it is not, the subdisk will -be attached at the first possible location. After attaching a plex to a +inserts the specified plex or subdisk in a volume or plex. +In the case of a +subdisk, an offset in the plex may be specified. +If it is not, the subdisk will +be attached at the first possible location. +After attaching a plex to a non-empty volume, .Nm reintegrates the plex. @@ -388,7 +401,8 @@ is specified, renames the object (and in the case of a plex, any subordinate subdisks) to fit in with the default .Nm -naming convention. To rename the object to any other name, use the +naming convention. +To rename the object to any other name, use the .Ic rename command. .Pp @@ -402,18 +416,21 @@ failure), it should be replaced by a subdisk of the same size only. .It In order to add further subdisks to a striped or RAID-5 plex, use the .Fl f -(force) option. This will corrupt the data in the plex. +(force) option. +This will corrupt the data in the plex. .\"No other attachment of .\"subdisks is currently allowed for striped and RAID-5 plexes. .It For concatenated plexes, the .Ar offset -parameter specifies the offset in blocks from the beginning of the plex. For +parameter specifies the offset in blocks from the beginning of the plex. +For striped and RAID-5 plexes, it specifies the offset of the first block of the subdisk: in other words, the offset is the numerical position of the subdisk -multiplied by the stripe size. For example, in a plex with stripe size 271k, +multiplied by the stripe size. +For example, in a plex with stripe size 271k, the first subdisk will have offset 0, the second offset 271k, the third 542k, -etc. This calculation ignores parity blocks in RAID-5 plexes. +etc.\& This calculation ignores parity blocks in RAID-5 plexes. .El .Pp .It Xo @@ -422,9 +439,11 @@ etc. This calculation ignores parity blocks in RAID-5 plexes. .Op Fl v .Ar plex .Xc -Check the parity blocks on the specified RAID-4 or RAID-5 plex. This operation +Check the parity blocks on the specified RAID-4 or RAID-5 plex. +This operation maintains a pointer in the plex, so it can be stopped and later restarted from -the same position if desired. In addition, this pointer is used by the +the same position if desired. +In addition, this pointer is used by the .Ic rebuildparity command, so rebuilding the parity blocks need only start at the location where the first parity problem has been detected. @@ -433,7 +452,8 @@ If the .Fl f flag is specified, .Ic checkparity -starts checking at the beginning of the plex. If the +starts checking at the beginning of the plex. +If the .Fl v flag is specified, .Ic checkparity @@ -450,26 +470,31 @@ The .Ic concat command provides a simplified alternative to the .Ic create -command for creating volumes with a single concatenated plex. The largest +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 .Ic concat -command creates an arbitrary name for the volume and its components. The name +command creates an arbitrary name for the volume and its components. +The name is composed of the text .Dq Li vinum and a small integer, for example .Dq Li vinum3 . You can override this with the .Fl n Ar name -option, which assigns the name specified to the volume. The plexes and subdisks +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 +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 +drives, the name remains. +Otherwise the drives are given names starting with the text .Dq Li vinumdrive and a small integer, for example @@ -478,7 +503,8 @@ As with the .Ic create command, the .Fl f -option can be used to specify that a previous name should be overwritten. The +option can be used to specify that a previous name should be overwritten. +The .Fl v is used to specify verbose output. .Pp @@ -493,17 +519,21 @@ command. .Ar description-file .Xc .Nm Ic create -is used to create any object. In view of the relatively complicated +is used to create any object. +In view of the relatively complicated relationship and the potential dangers involved in creating a .Nm -object, there is no interactive interface to this function. If you do not +object, there is no interactive interface to this function. +If you do not specify a file name, .Nm -starts an editor on a temporary file. If the environment variable +starts an editor on a temporary file. +If the environment variable .Ev EDITOR is set, .Nm -starts this editor. If not, it defaults to +starts this editor. +If not, it defaults to .Nm vi . See the section .Sx CONFIGURATION FILE @@ -519,31 +549,38 @@ Normally the .Ic create command will not change the names of existing .Nm -drives, in order to avoid accidentally erasing them. The correct way to dispose +drives, in order to avoid accidentally erasing them. +The correct way to dispose of no longer wanted .Nm drives is to reset the configuration with the .Ic resetconfig -command. In some cases, however, it may be necessary to create new data on +command. +In some cases, however, it may be necessary to create new data on .Nm -drives which can no longer be started. In this case, use the +drives which can no longer be started. +In this case, use the .Ic create Fl f command. .Pp .It Ic debug .Nm Ic debug , -without any arguments, is used to enter the remote kernel debugger. It is only +without any arguments, is used to enter the remote kernel debugger. +It is only activated if .Nm is built with the .Dv VINUMDEBUG -option. This option will stop the execution of the operating system until the -kernel debugger is exited. If remote debugging is set and there is no remote +option. +This option will stop the execution of the operating system until the +kernel debugger is exited. +If remote debugging is set and there is no remote connection for a kernel debugger, it will be necessary to reset the system and reboot in order to leave the debugger. .Pp .It Ic debug Ar flags -Set a bit mask of internal debugging flags. These will change without warning +Set a bit mask of internal debugging flags. +These will change without warning as the product matures; to be certain, read the header file .In sys/dev/vinumvar.h . The bit mask is composed of the following values: @@ -580,10 +617,12 @@ Print some warnings about minor problems in the implementation. .It Ic detach Oo Fl f Oc Ar subdisk .Nm Ic detach removes the specified plex or subdisk from the volume or plex to which it is -attached. If removing the object would impair the data integrity of the volume, +attached. +If removing the object would impair the data integrity of the volume, the operation will fail unless the .Fl f -option is specified. If the object is named after the object above it (for +option is specified. +If the object is named after the object above it (for example, subdisk .Li vol1.p7.s0 attached to plex @@ -597,7 +636,8 @@ If necessary, the name will be truncated in the process. .Pp .Ic detach -does not reduce the number of subdisks in a striped or RAID-5 plex. Instead, +does not reduce the number of subdisks in a striped or RAID-5 plex. +Instead, the subdisk is marked absent, and can later be replaced with the .Ic attach command. @@ -605,20 +645,25 @@ command. .It Ic dumpconfig Op Ar drive ... .Pp .Nm Ic dumpconfig -shows the configuration information stored on the specified drives. If no drive +shows the configuration information stored on the specified drives. +If no drive names are specified, .Ic dumpconfig searches all drives on the system for Vinum partitions and dumps the -information. If configuration updates are disabled, it is possible that this +information. +If configuration updates are disabled, it is possible that this information is not the same as the information returned by the .Ic list -command. This command is used primarily for maintenance and debugging. +command. +This command is used primarily for maintenance and debugging. .Pp .It Ic info .Nm Ic info displays information about .Nm -memory usage. This is intended primarily for debugging. With the +memory usage. +This is intended primarily for debugging. +With the .Fl v option, it will give detailed information about the memory areas in use. .Pp @@ -628,7 +673,9 @@ option, .Ic info displays information about the last up to 64 I/O requests handled by the .Nm -driver. This information is only collected if debug flag 8 is set. The format +driver. +This information is only collected if debug flag 8 is set. +The format looks like: .Bd -literal vinum -> info -V @@ -656,21 +703,25 @@ Time Event Buf Dev Offset Bytes SD .Pp The .Ar Buf -field always contains the address of the user buffer header. This can be used +field always contains the address of the user buffer header. +This can be used to identify the requests associated with a user request, though this is not 100% reliable: theoretically two requests in sequence could use the same buffer -header, though this is not common. The beginning of a request can be identified +header, though this is not common. +The beginning of a request can be identified by the event .Ar 1VS or .Ar 7VS . -The first example above shows the requests involved in a user request. The +The first example above shows the requests involved in a user request. +The second is a subdisk I/O request with locking. .Pp The .Ar Event field contains information related to the sequence of events in the request -chain. The digit +chain. +The digit .Ar 1 to .Ar 6 @@ -682,7 +733,8 @@ a mnemonic for the location: .Fn vinumstrategy . The device number is the .Nm -device, and offset and length are the user parameters. This is always the +device, and offset and length are the user parameters. +This is always the beginning of a request sequence. .It 2LR (launch_requests) shows the user request just prior to launching the low-level @@ -712,13 +764,15 @@ is the offset of the associated group request, where applicable. .It 3RQ (request) shows one of possibly several low-level .Nm -requests which are launched to satisfy the high-level request. This information +requests which are launched to satisfy the high-level request. +This information is also logged in .Fn launch_requests . .It 4DN (done) is called from .Fn complete_rqe , -showing the completion of a request. This completion should match a request +showing the completion of a request. +This completion should match a request launched either at stage .Ar 4DN from @@ -740,21 +794,25 @@ parity. and represents the data written to a RAID-5 parity stripe after calculating parity. .It 7VS -shows a subdisk I/O request. These requests are usually internal to +shows a subdisk I/O request. +These requests are usually internal to .Nm for operations like initialization or rebuilding plexes. .It 8LR shows the low-level operation generated for a subdisk I/O request. .It Lockwait -specifies that the process is waiting for a range lock. The parameters are the +specifies that the process is waiting for a range lock. +The parameters are the buffer header associated with the request, the plex number and the block number. For internal reasons the block number is one higher than the address of the beginning of the stripe. .It Lock -specifies that a range lock has been obtained. The parameters are the same as +specifies that a range lock has been obtained. +The parameters are the same as for the range lock. .It Unlock -specifies that a range lock has been released. The parameters are the same as +specifies that a range lock has been released. +The parameters are the same as for the range lock. .El .\" XXX @@ -766,13 +824,19 @@ for the range lock. .Ar plex | subdisk .Xc .Nm Ic init -initializes a subdisk by writing zeroes to it. You can initialize all subdisks -in a plex by specifying the plex name. This is the only way to ensure -consistent data in a plex. You must perform this initialization before using a -RAID-5 plex. It is also recommended for other new plexes. -.Nm -initializes all subdisks of a plex in parallel. Since this operation can take a -long time, it is normally performed in the background. If you want to wait for +initializes a subdisk by writing zeroes to it. +You can initialize all subdisks +in a plex by specifying the plex name. +This is the only way to ensure +consistent data in a plex. +You must perform this initialization before using a +RAID-5 plex. +It is also recommended for other new plexes. +.Nm +initializes all subdisks of a plex in parallel. +Since this operation can take a +long time, it is normally performed in the background. +If you want to wait for completion of the command, use the .Fl w (wait) option. @@ -789,7 +853,8 @@ The .Ic label command writes a .Em ufs -style volume label on a volume. It is a simple alternative to an appropriate +style volume label on a volume. +It is a simple alternative to an appropriate call to .Ic disklabel . This is needed because some @@ -848,7 +913,8 @@ This command is deprecated. .Op Ar volume .Xc .Ic list -is used to show information about the specified object. If the argument is +is used to show information about the specified object. +If the argument is omitted, information is shown about all objects known to .Nm . The @@ -860,11 +926,13 @@ The .Fl r option relates to volumes and plexes: if specified, it recursively lists information for the subdisks and (for a volume) plexes subordinate to the -objects. The commands +objects. +The commands .Ic lv , lp , ls and .Ic ld -list only volumes, plexes, subdisks and drives respectively. This is +list only volumes, plexes, subdisks and drives respectively. +This is particularly useful when used without parameters. .Pp The @@ -889,37 +957,47 @@ The .Ic mirror command provides a simplified alternative to the .Ic 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 +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 +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, .Ic mirror -builds striped plexes with a stripe size of 279 kB. The size of the subdisks in +builds striped plexes with a stripe size of 279 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. +drives which form the plex. +Again, the plexes may differ in size. .Pp Normally, the .Ic mirror -command creates an arbitrary name for the volume and its components. The name +command creates an arbitrary name for the volume and its components. +The name is composed of the text .Dq Li vinum and a small integer, for example .Dq Li vinum3 . You can override this with the .Fl n Ar name -option, which assigns the name specified to the volume. The plexes and subdisks +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 +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 +drives, the name remains. +Otherwise the drives are given names starting with the text .Dq Li vinumdrive and a small integer, for example @@ -928,7 +1006,8 @@ As with the .Ic create command, the .Fl f -option can be used to specify that a previous name should be overwritten. The +option can be used to specify that a previous name should be overwritten. +The .Fl v is used to specify verbose output. .Pp @@ -939,14 +1018,18 @@ command. .Pp .It Ic mv Fl f Ar drive object ... .It Ic move Fl f Ar drive object ... -Move all the subdisks from the specified objects onto the new drive. The -objects may be subdisks, drives or plexes. When drives or plexes are specified, +Move all the subdisks from the specified objects onto the new drive. +The +objects may be subdisks, drives or plexes. +When drives or plexes are specified, all subdisks associated with the object are moved. .Pp The .Fl f option is required for this function, since it currently does not preserve the -data in the subdisk. This functionality will be added at a later date. In this +data in the subdisk. +This functionality will be added at a later date. +In this form, however, it is suited to recovering a failed disk drive. .Pp .It Ic printconfig Op Ar file @@ -954,8 +1037,10 @@ Write a copy of the current configuration to .Ar file in a format that can be used to recreate the .Nm -configuration. Unlike the configuration saved on disk, it includes definitions -of the drives. If you omit +configuration. +Unlike the configuration saved on disk, it includes definitions +of the drives. +If you omit .Ar file , .Nm writes the list to @@ -964,7 +1049,8 @@ writes the list to .It Ic quit Exit the .Nm -utility when running in interactive mode. Normally this would be done by +utility when running in interactive mode. +Normally this would be done by entering the .Dv EOF character. @@ -974,14 +1060,16 @@ The .Ic read command scans the specified disks for .Nm -partitions containing previously created configuration information. It reads +partitions containing previously created configuration information. +It reads the configuration in order from the most recently updated to least recently updated configuration. The .Nm utility maintains an up-to-date copy of all configuration information on each disk -partition. You must specify all of the slices in a configuration as the +partition. +You must specify all of the slices in a configuration as the parameter to this command. .Pp The @@ -990,7 +1078,8 @@ command is intended to selectively load a .Nm configuration on a system which has other .Nm -partitions. If you want to start all partitions on the system, it is easier to +partitions. +If you want to start all partitions on the system, it is easier to use the .Ic start command. @@ -998,14 +1087,17 @@ command. If .Nm encounters any errors during this command, it will turn off automatic -configuration update to avoid corrupting the copies on disk. This will also +configuration update to avoid corrupting the copies on disk. +This will also happen if the configuration on disk indicates a configuration error (for -example, subdisks which do not have a valid space specification). You can turn +example, subdisks which do not have a valid space specification). +You can turn the updates on again with the .Ic setdaemon and .Ic saveconfig -commands. Reset bit 2 (numerical value 4) of the daemon options mask to +commands. +Reset bit 2 (numerical value 4) of the daemon options mask to re-enable configuration saves. .Pp .It Xo @@ -1015,9 +1107,11 @@ re-enable configuration saves. .Op Fl V .Ar plex .Xc -Rebuild the parity blocks on the specified RAID-4 or RAID-5 plex. This +Rebuild the parity blocks on the specified RAID-4 or RAID-5 plex. +This operation maintains a pointer in the plex, so it can be stopped and later -restarted from the same position if desired. In addition, this pointer is used +restarted from the same position if desired. +In addition, this pointer is used by the .Ic checkparity command, so rebuilding the parity blocks need only start at the location where @@ -1027,12 +1121,14 @@ If the .Fl f flag is specified, .Ic rebuildparity -starts rebuilding at the beginning of the plex. If the +starts rebuilding at the beginning of the plex. +If the .Fl v flag is specified, .Ic rebuildparity first checks the existing parity blocks prints information about those found to -be incorrect before rebuilding. If the +be incorrect before rebuilding. +If the .Fl V flag is specified, .Ic rebuildparity @@ -1044,7 +1140,8 @@ prints a running progress report. .Op Ar drive | subdisk | plex | volume .Ar newname .Xc -Change the name of the specified object. If the +Change the name of the specified object. +If the .Fl r option is specified, subordinate objects will be named by the default rules: plex names will be formed by appending @@ -1068,7 +1165,8 @@ The .Ic resetconfig command completely obliterates the .Nm -configuration on a system. Use this command only when you want to completely +configuration on a system. +Use this command only when you want to completely delete the configuration. .Nm will ask for confirmation; you must type in the words @@ -1086,7 +1184,8 @@ NO FUTURE Vinum configuration obliterated .Ed .Pp -As the message suggests, this is a last-ditch command. Don't use it unless you +As the message suggests, this is a last-ditch command. +Don't use it unless you have an existing configuration which you never want to see again. .Pp .It Xo @@ -1095,13 +1194,15 @@ have an existing configuration which you never want to see again. .Op Ar volume | plex | subdisk .Xc .Nm -maintains a number of statistical counters for each object. See the header file +maintains a number of statistical counters for each object. +See the header file .In sys/dev/vinumvar.h for more information. .\" XXX put it in here when it's finalized Use the .Ic resetstats -command to reset these counters. In conjunction with the +command to reset these counters. +In conjunction with the .Fl r option, .Nm @@ -1116,20 +1217,24 @@ also resets the counters of subordinate objects. .Ic rm removes an object from the .Nm -configuration. Once an object has been removed, there is no way to recover it. +configuration. +Once an object has been removed, there is no way to recover it. Normally .Nm -performs a large amount of consistency checking before removing an object. The +performs a large amount of consistency checking before removing an object. +The .Fl f option tells .Nm -to omit this checking and remove the object anyway. Use this option with great +to omit this checking and remove the object anyway. +Use this option with great care: it can result in total loss of data on a volume. .Pp Normally, .Nm refuses to remove a volume or plex if it has subordinate plexes or subdisks -respectively. You can tell +respectively. +You can tell .Nm to remove the object anyway by using the .Fl f @@ -1137,20 +1242,25 @@ option, or you can cause .Nm to remove the subordinate objects as well by using the .Fl r -(recursive) option. If you remove a volume with the +(recursive) option. +If you remove a volume with the .Fl r option, it will remove both the plexes and the subdisks which belong to the plexes. .Pp .It Ic saveconfig -Save the current configuration to disk. Normally this is not necessary, since +Save the current configuration to disk. +Normally this is not necessary, since .Nm -automatically saves any change in configuration. If an error occurs on startup, -updates will be disabled. When you reenable them with the +automatically saves any change in configuration. +If an error occurs on startup, +updates will be disabled. +When you reenable them with the .Ic setdaemon command, .Nm -does not automatically save the configuration to disk. Use this command to save +does not automatically save the configuration to disk. +Use this command to save the configuration. .\".Pp .\".It Xo @@ -1175,19 +1285,24 @@ the configuration. .Ic setdaemon sets a variable bitmask for the .Nm -daemon. This command is temporary and will be replaced. Currently, the bit mask +daemon. +This command is temporary and will be replaced. +Currently, the bit mask may contain the bits 1 (log every action to syslog) and 4 (don't update -configuration). Option bit 4 can be useful for error recovery. +configuration). +Option bit 4 can be useful for error recovery. .Pp .It Xo .Ic setstate Ar state .Op Ar volume | plex | subdisk | drive .Xc .Ic setstate -sets the state of the specified objects to the specified state. This bypasses +sets the state of the specified objects to the specified state. +This bypasses the usual consistency mechanism of .Nm -and should be used only for recovery purposes. It is possible to crash the +and should be used only for recovery purposes. +It is possible to crash the system by incorrect use of this command. .Pp .It Xo @@ -1210,7 +1325,8 @@ scans the disks known to the system for .Nm drives and then reads in the configuration as described under the .Ic read -commands. The +commands. +The .Nm drive contains a header with all information about the data stored on the drive, including the names of the other drives which are required in order to represent @@ -1219,19 +1335,24 @@ plexes and volumes. If .Nm encounters any errors during this command, it will turn off automatic -configuration update to avoid corrupting the copies on disk. This will also +configuration update to avoid corrupting the copies on disk. +This will also happen if the configuration on disk indicates a configuration error (for -example, subdisks which do not have a valid space specification). You can turn +example, subdisks which do not have a valid space specification). +You can turn the updates on again with the .Ic setdaemon and .Ic saveconfig -command. Reset bit 4 of the daemon options mask to re-enable configuration +command. +Reset bit 4 of the daemon options mask to re-enable configuration saves. .Pp If object names are specified, .Nm -starts them. Normally this operation is only of use with subdisks. The action +starts them. +Normally this operation is only of use with subdisks. +The action depends on the current state of the object: .Bl -bullet .It @@ -1253,15 +1374,18 @@ state. .It If the object is a subdisk in the .Em empty -state, the change depends on the subdisk. If it is part of a plex which is part +state, the change depends on the subdisk. +If it is part of a plex which is part of a volume which contains other plexes, .Nm places the subdisk in the .Em reviving -state and attempts to copy the data from the volume. When the operation +state and attempts to copy the data from the volume. +When the operation completes, the subdisk is set into the .Em up -state. If it is part of a plex which is part of a volume which contains no +state. +If it is part of a plex which is part of a volume which contains no other plexes, or if it is not part of a plex, .Nm brings it into the @@ -1273,7 +1397,8 @@ If the object is a subdisk in the state, .Nm continues the revive -operation offline. When the operation completes, the subdisk is set into the +operation offline. +When the operation completes, the subdisk is set into the .Em up state. .El @@ -1291,19 +1416,23 @@ checks the state of the subordinate subdisks (and plexes in the case of a volume) and starts any subdisks which can be started. .Pp To start a plex in a multi-plex volume, the data must be copied from another -plex in the volume. Since this frequently takes a long time, it is normally -done in the background. If you want to wait for this operation to complete (for +plex in the volume. +Since this frequently takes a long time, it is normally +done in the background. +If you want to wait for this operation to complete (for example, if you are performing this operation in a script), use the .Fl w option. .Pp Copying data doesn't just take a long time, it can also place a significant load -on the system. You can specify the transfer size in bytes or sectors with the +on the system. +You can specify the transfer size in bytes or sectors with the .Fl S option, and an interval (in milliseconds) to wait between copying each block with the .Fl i -option. Both of these options lessen the load on the system. +option. +Both of these options lessen the load on the system. .Pp .It Xo .Ic stop @@ -1316,14 +1445,17 @@ removes the .Nm kld and stops .Xr vinum 4 . -This can only be done if no objects are active. In particular, the +This can only be done if no objects are active. +In particular, the .Fl f -option does not override this requirement. Normally, the +option does not override this requirement. +Normally, the .Ic stop command writes the current configuration back to the drives before terminating. This will not be possible if configuration updates are disabled, so .Nm -will not stop if configuration updates are disabled. You can override this by +will not stop if configuration updates are disabled. +You can override this by specifying the .Fl f option. @@ -1341,25 +1473,31 @@ is statically configured. .Pp If object names are specified, .Ic stop -disables access to the objects. If the objects have subordinate objects, the +disables access to the objects. +If the objects have subordinate objects, the subordinate objects must either already be inactive (stopped or in error), or the .Fl r and .Fl f -options must be specified. This command does not remove the objects from the -configuration. They can be accessed again after a +options must be specified. +This command does not remove the objects from the +configuration. +They can be accessed again after a .Ic start command. .Pp By default, .Nm -does not stop active objects. For example, you cannot stop a plex which is -attached to an active volume, and you cannot stop a volume which is open. The +does not stop active objects. +For example, you cannot stop a plex which is +attached to an active volume, and you cannot stop a volume which is open. +The .Fl f option tells .Nm -to omit this checking and remove the object anyway. Use this option with great +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. .Pp @@ -1374,26 +1512,32 @@ The .Ic stripe command provides a simplified alternative to the .Ic create -command for creating volumes with a single striped plex. The size of the +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 279 kB. +specified drives. +The stripe size is fixed at 279 kB. .Pp Normally, the .Ic stripe -command creates an arbitrary name for the volume and its components. The name +command creates an arbitrary name for the volume and its components. +The name is composed of the text .Dq Li vinum and a small integer, for example .Dq Li vinum3 . You can override this with the .Fl n Ar name -option, which assigns the name specified to the volume. The plexes and subdisks +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 +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 +drives, the name remains. +Otherwise the drives are given names starting with the text .Dq Li vinumdrive and a small integer, for example @@ -1402,7 +1546,8 @@ As with the .Ic create command, the .Fl f -option can be used to specify that a previous name should be overwritten. The +option can be used to specify that a previous name should be overwritten. +The .Fl v is used to specify verbose output. .Pp @@ -1419,21 +1564,26 @@ configuration using the .Ic mirror and .Ic stripe -commands. These commands create convenient configurations for some more normal +commands. +These commands create convenient configurations for some more normal situations, but they are not as flexible as the .Ic 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, +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 +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 +of the volume. +Without the .Fl v option, these commands produce no output. .Ss Volume with a single concatenated plex @@ -1464,7 +1614,8 @@ In this case, the complete space on all four disks was used, giving a volume .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: +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 @@ -1514,7 +1665,8 @@ S vinum0.p0.s3 State: up D: vinumdrive3 Size: 414 MB 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 +size, and the last 158 MB of the volume is non-resilient. +To ensure complete reliability in such a situation, use the .Ic create command to create a volume with 988 MB. @@ -1551,7 +1703,8 @@ The .Nm utility requires that all parameters to the .Ic create -commands must be in a configuration file. Entries in the configuration file +commands must be in a configuration file. +Entries in the configuration file define volumes, plexes and subdisks, and may be in free format, except that each entry must be on a single line. .Ss Scale factors @@ -1573,7 +1726,8 @@ is used for compatibility with It stands for blocks of 512 bytes. This abbreviation is confusing, since the word .Dq block -is used in different meanings, and its use is deprecated. Use the keyword 's' +is used in different meanings, and its use is deprecated. +Use the keyword 's' instead. .El .Pp @@ -1586,7 +1740,8 @@ or The configuration file can contain the following entries: .Bl -tag -width 4n .It Ic drive Ar name devicename Op Ar options -Define a drive. The options are: +Define a drive. +The options are: .Bl -tag -width 18n .It Cm device Ar devicename Specify the device on which the drive resides. @@ -1607,8 +1762,10 @@ drive, which is maintained to automatically replace a failed drive. The .Nm utility -does not allow this drive to be used for any other purpose. In particular, it -is not possible to create subdisks on it. This functionality has not been +does not allow this drive to be used for any other purpose. +In particular, it +is not possible to create subdisks on it. +This functionality has not been completely implemented. .El .It Ic volume Ar name Op Ar options @@ -1617,7 +1774,8 @@ Define a volume with name Options are: .Bl -tag -width 18n .It Cm plex Ar plexname -Add the specified plex to the volume. If +Add the specified plex to the volume. +If .Ar plexname is specified as .Cm * , @@ -1635,30 +1793,37 @@ or .Cm prefer Ar plexname . The .Nm -utility satisfies a read request from only one of the plexes. A +utility satisfies a read request from only one of the plexes. +A .Cm round read policy specifies that each read should be performed from a different plex in .Em round-robin -fashion. A +fashion. +A .Cm prefer read policy reads from the specified plex every time. .It Cm setupstate When creating a multi-plex volume, assume that the contents of all the plexes -are consistent. This is normally not the case, so by default +are consistent. +This is normally not the case, so by default .Nm sets all plexes except the first one to the .Em faulty -state. Use the +state. +Use the .Ic start -command to first bring them to a consistent state. In the case of striped and +command to first bring them to a consistent state. +In the case of striped and concatenated plexes, however, it does not normally cause problems to leave them inconsistent: when using a volume for a file system or a swap partition, the previous contents of the disks are not of interest, so they may be ignored. If you want to take this risk, use the .Cm setupstate -keyword. It will only apply to the plexes defined immediately after the volume -in the configuration file. If you add plexes to a volume at a later time, you +keyword. +It will only apply to the plexes defined immediately after the volume +in the configuration file. +If you add plexes to a volume at a later time, you must integrate them manually with the .Ic start command. @@ -1671,11 +1836,13 @@ command with RAID-5 plexes: otherwise extreme data corruption will result if one subdisk fails. .El .It Ic plex Op Ar options -Define a plex. Unlike a volume, you do not need to specify a name for a plex. +Define a plex. +Unlike a volume, you do not need to specify a name for a plex. The options may be: .Bl -tag -width 18n .It Cm name Ar plexname -Specify the name of the plex. Note that you must use the keyword +Specify the name of the plex. +Note that you must use the keyword .Cm name when naming a plex or subdisk. .It Cm org Ar organization Op Ar stripesize @@ -1693,31 +1860,42 @@ plexes, the parameter .Ar stripesize must be specified, while for .Cm concat -it must be omitted. For type +it must be omitted. +For type .Cm striped , -it specifies the width of each stripe. For type +it specifies the width of each stripe. +For type .Cm raid5 , -it specifies the size of a group. A group is a portion of a plex which -stores the parity bits all in the same subdisk. It must be a factor of the plex size (in +it specifies the size of a group. +A group is a portion of a plex which +stores the parity bits all in the same subdisk. +It must be a factor of the plex size (in other words, the result of dividing the plex size by the stripe size must be an integer), and it must be a multiple of a disk sector (512 bytes). .Pp For optimum performance, stripes should be at least 128 kB in size: anything smaller will result in a significant increase in I/O activity due to mapping of -individual requests over multiple disks. The performance improvement due to the +individual requests over multiple disks. +The performance improvement due to the increased number of concurrent transfers caused by this mapping will not make up -for the performance drop due to the increase in latency. A good guideline for -stripe size is between 256 kB and 512 kB. Avoid powers of 2, however: they tend -to cause all superblocks to be placed on the first subdisk. The simplified +for the performance drop due to the increase in latency. +A good guideline for +stripe size is between 256 kB and 512 kB. +Avoid powers of 2, however: they tend +to cause all superblocks to be placed on the first subdisk. +The simplified commands use a stripe size of 279 kB, which shows a reasonable distribution of superblocks. .Pp A striped plex must have at least two subdisks (otherwise it is a concatenated -plex), and each must be the same size. A RAID-5 plex must have at least three -subdisks, and each must be the same size. In practice, a RAID-5 plex should +plex), and each must be the same size. +A RAID-5 plex must have at least three +subdisks, and each must be the same size. +In practice, a RAID-5 plex should have at least 5 subdisks. .It Cm volume Ar volname -Add the plex to the specified volume. If no +Add the plex to the specified volume. +If no .Cm volume keyword is specified, the plex will be added to the last volume mentioned in the configuration file. @@ -1726,28 +1904,35 @@ Add the specified subdisk to the plex at offset .Ar offset . .El .It Ic subdisk Op Ar options -Define a subdisk. Options may be: +Define a subdisk. +Options may be: .Bl -hang -width 18n .It Cm name Ar name -Specify the name of a subdisk. It is not necessary to specify a name for a +Specify the name of a subdisk. +It is not necessary to specify a name for a subdisk\(emsee .Sx OBJECT NAMING -above. Note that you must specify the keyword +above. +Note that you must specify the keyword .Cm name if you wish to name a subdisk. .It Cm plexoffset Ar offset -Specify the starting offset of the subdisk in the plex. If not specified, +Specify the starting offset of the subdisk in the plex. +If not specified, .Nm allocates the space immediately after the previous subdisk, if any, or otherwise at the beginning of the plex. .It Cm driveoffset Ar offset -Specify the starting offset of the subdisk in the drive. If not specified, +Specify the starting offset of the subdisk in the drive. +If not specified, .Nm allocates the first contiguous .Ar length bytes of free space on the drive. .It Cm length Ar length -Specify the length of the subdisk. This keyword must be specified. There is no +Specify the length of the subdisk. +This keyword must be specified. +There is no default, but the value 0 may be specified to mean .Dq "use the largest available contiguous free area on the drive" . If the drive is empty, this means that the entire drive will be used for the @@ -1756,14 +1941,17 @@ subdisk. may be shortened to .Cm len . .It Cm plex Ar plex -Specify the plex to which the subdisk belongs. By default, the subdisk belongs +Specify the plex to which the subdisk belongs. +By default, the subdisk belongs to the last plex specified. .It Cm drive Ar drive -Specify the drive on which the subdisk resides. By default, the subdisk resides +Specify the drive on which the subdisk resides. +By default, the subdisk resides on the last drive specified. .It Cm retryerrors Specify that the subdisk should not be taken down if an unrecoverable error -occurs. Normally +occurs. +Normally .Nm responds to an unrecoverable error by making the entire subdisk inaccessible. .El @@ -1821,11 +2009,14 @@ volume vol5 .Nm drives are currently .Bx -disk partitions. They must be of type +disk partitions. +They must be of type .Em vinum -in order to avoid overwriting data used for other purposes. Use +in order to avoid overwriting data used for other purposes. +Use .Nm disklabel Fl e -to edit a partition type definition. The following display shows a typical +to edit a partition type definition. +The following display shows a typical partition layout as shown by .Xr disklabel 8 : .Bd -literal @@ -1843,7 +2034,8 @@ In this example, partition .Dq Li g may be used as a .Nm -partition. Partitions +partition. +Partitions .Dq Li a , .Dq Li e and @@ -1852,7 +2044,8 @@ may be used as .Em UFS file systems or .Em ccd -partitions. Partition +partitions. +Partition .Dq Li b is a swap partition, and partition .Dq Li c @@ -1874,11 +2067,13 @@ You can override the name of this file by setting the environment variable .Ev VINUM_HISTORY to the name of the file. .Pp -Each message in the log file is preceded by a date. The default format is +Each message in the log file is preceded by a date. +The default format is .Qq Li %e %b %Y %H:%M:%S . See .Xr strftime 3 -for further details of the format string. It can be overridden by the +for further details of the format string. +It can be overridden by the environment variable .Ev VINUM_DATEFORMAT . .Sh HOW TO SET UP VINUM @@ -1886,7 +2081,8 @@ This section gives practical advice about how to implement a .Nm system. .Ss Where to put the data -The first choice you need to make is where to put the data. You need dedicated +The first choice you need to make is where to put the data. +You need dedicated disk partitions for .Nm . They should be partitions, not devices, and they should not be partition @@ -1909,11 +2105,13 @@ above. .Ss Designing volumes The way you set up .Nm -volumes depends on your intentions. There are a number of possibilities: +volumes depends on your intentions. +There are a number of possibilities: .Bl -enum .It You may want to join up a number of small disks to make a reasonable sized file -system. For example, if you had five small drives and wanted to use all the +system. +For example, if you had five small drives and wanted to use all the space for a single volume, you might write a configuration file like: .Bd -literal -offset indent drive d1 device /dev/da2e @@ -1937,13 +2135,15 @@ space. .It You want to set up .Nm -to obtain additional resilience against disk failures. You have the choice of +to obtain additional resilience against disk failures. +You have the choice of RAID-1, also called .Dq mirroring , or RAID-5, also called .Dq parity . .Pp -To set up mirroring, create multiple plexes in a volume. For example, to create +To set up mirroring, create multiple plexes in a volume. +For example, to create a mirrored volume of 2 GB, you might create the following configuration file: .Bd -literal -offset indent drive d1 device /dev/da2e @@ -1983,10 +2183,13 @@ volume raid .Ed .Pp RAID-5 plexes require at least three subdisks, one of which is used for storing -parity information and is lost for data storage. The more disks you use, the -greater the proportion of the disk storage can be used for data storage. In +parity information and is lost for data storage. +The more disks you use, the +greater the proportion of the disk storage can be used for data storage. +In this example, the total storage usage is 2.5 GB, compared to 4 GB for a mirrored -configuration. If you were to use the minimum of only three disks, you would +configuration. +If you were to use the minimum of only three disks, you would require 3 GB to store the information, for example: .Bd -literal -offset indent drive d1 device /dev/da2e @@ -2006,8 +2209,10 @@ can access the complete address space of the volume even if a drive fails. .It You want to set up .Nm -to allow more concurrent access to a file system. In many cases, access to a -file system is limited by the speed of the disk. By spreading the volume across +to allow more concurrent access to a file system. +In many cases, access to a +file system is limited by the speed of the disk. +By spreading the volume across multiple disks, you can increase the throughput in multi-access environments. This technique shows little or no performance improvement in single-access environments. @@ -2015,7 +2220,8 @@ The .Nm utility uses a technique called .Dq striping , -or sometimes RAID-0, to increase this concurrency of access. The name RAID-0 is +or sometimes RAID-0, to increase this concurrency of access. +The name RAID-0 is misleading: striping does not provide any redundancy or additional reliability. In fact, it decreases the reliability, since the failure of a single disk will render the volume useless, and the more disks you have, the more likely it is @@ -2041,8 +2247,10 @@ A striped plex must have at least two subdisks, but the increase in performance is greater if you have a larger number of disks. .It You may want to have the best of both worlds and have both resilience and -performance. This is sometimes called RAID-10 (a combination of RAID-1 and -RAID-0), though again this name is misleading. With +performance. +This is sometimes called RAID-10 (a combination of RAID-1 and +RAID-0), though again this name is misleading. +With .Nm you can do this with the following configuration file: .Bd -literal -offset indent @@ -2064,9 +2272,12 @@ volume raid setupstate .Ed .Pp Here the plexes are striped, increasing performance, and there are two of them, -increasing reliability. Note that this example shows the subdisks of the second -plex in reverse order from the first plex. This is for performance reasons and -will be discussed below. In addition, the volume specification includes the +increasing reliability. +Note that this example shows the subdisks of the second +plex in reverse order from the first plex. +This is for performance reasons and +will be discussed below. +In addition, the volume specification includes the keyword .Cm setupstate , which ensures that all plexes are @@ -2076,7 +2287,8 @@ after creation. .Ss Creating the volumes Once you have created your configuration files, start .Nm -and create the volumes. In this example, the configuration is in the file +and create the volumes. +In this example, the configuration is in the file .Pa configfile : .Bd -literal -offset 2n # vinum create -v configfile @@ -2143,7 +2355,8 @@ The .Fl v option tells .Nm -to list the file as it configures. Subsequently it lists the current +to list the file as it configures. +Subsequently it lists the current configuration in the same format as the .Ic list Fl v command. @@ -2152,8 +2365,10 @@ Once you have created the .Nm volumes, .Nm -keeps track of them in its internal configuration files. You do not need to -create them again. In particular, if you run the +keeps track of them in its internal configuration files. +You do not need to +create them again. +In particular, if you run the .Ic create command again, you will create additional objects: .Bd -literal @@ -2185,11 +2400,14 @@ As this example (this time with the .Fl f option) shows, re-running the .Ic create -has created four new plexes, each with a new subdisk. If you want to add other -volumes, create new configuration files for them. They do not need to reference +has created four new plexes, each with a new subdisk. +If you want to add other +volumes, create new configuration files for them. +They do not need to reference the drives that .Nm -already knows about. For example, to create a volume +already knows about. +For example, to create a volume .Pa raid on the four drives .Pa /dev/da1e , /dev/da2e , /dev/da3e @@ -2242,7 +2460,8 @@ S raid.p0.s3 State: empty PO: 1299 kB Size: 2048 MB .Ed .Pp Note the size of the RAID-5 plex: it is only 6 GB, although together its -components use 8 GB of disk space. This is because the equivalent of one +components use 8 GB of disk space. +This is because the equivalent of one subdisk is used for storing parity data. .Ss Restarting Vinum On rebooting the system, start @@ -2255,22 +2474,27 @@ command: .Pp This will start all the .Nm -drives in the system. If for some reason you wish to start only some of them, +drives in the system. +If for some reason you wish to start only some of them, use the .Ic read command. .Ss Performance considerations A number of misconceptions exist about how to set up a RAID array for best -performance. In particular, most systems use far too small a stripe size. The +performance. +In particular, most systems use far too small a stripe size. +The following discussion applies to all RAID systems, not just to .Nm . .Pp The .Fx block I/O system issues requests of between .5kB and 128 kB; a -typical mix is somewhere round 8 kB. You can't stop any striping system from +typical mix is somewhere round 8 kB. +You can't stop any striping system from breaking a request into two physical requests, and if you make the stripe small -enough, it can be broken into several. This will result in a significant drop +enough, it can be broken into several. +This will result in a significant drop in performance: the decrease in transfer time per disk is offset by the order of magnitude greater increase in latency. .Pp @@ -2282,7 +2506,8 @@ and 512 kB; with correct RAID implementations there is no obvious reason not to increase the size to 2 or 4 MB on a large disk. .Pp When choosing a stripe size, consider that most current UFS file systems have -cylinder groups 32 MB in size. If you have a stripe size and number of disks +cylinder groups 32 MB in size. +If you have a stripe size and number of disks both of which are a power of two, it is probable that all superblocks and inodes will be placed on the same subdisk, which will impact performance significantly. Choose an odd number instead, for example 479 kB. @@ -2294,35 +2519,51 @@ Since just about everything is cached, the time relationship between the request and its completion is not so important: the important parameter is the total time that the request keeps the disks active, the time when the disks are not available to -perform other transfers. As a result, it doesn't really matter if the transfers -are happening at the same time or different times. In practical terms, the time +perform other transfers. +As a result, it doesn't really matter if the transfers +are happening at the same time or different times. +In practical terms, the time we're looking at is the sum of the total latency (positioning time and rotational latency, or the time it takes for the data to arrive under the disk -heads) and the total transfer time. For a given transfer to disks of the same +heads) and the total transfer time. +For a given transfer to disks of the same speed, the transfer time depends only on the total size of the transfer. .Pp Consider a typical news article or web page of 24 kB, which will probably be -read in a single I/O. Take disks with a transfer rate of 6 MB/s and an average -positioning time of 8 ms, and a file system with 4 kB blocks. Since it's 24 kB, +read in a single I/O. +Take disks with a transfer rate of 6 MB/s and an average +positioning time of 8 ms, and a file system with 4 kB blocks. +Since it's 24 kB, we don't have to worry about fragments, so the file will start on a 4 kB -boundary. The number of transfers required depends on where the block starts: +boundary. +The number of transfers required depends on where the block starts: it's (S + F - 1) / S, where S is the stripe size in file system blocks, and F is the file size in file system blocks. .Bl -enum .It -Stripe size of 4 kB. You'll have 6 transfers. Total subsystem load: 48 ms +Stripe size of 4 kB. +You'll have 6 transfers. +Total subsystem load: 48 ms latency, 2 ms transfer, 50 ms total. .It -Stripe size of 8 kB. On average, you'll have 3.5 transfers. Total subsystem +Stripe size of 8 kB. +On average, you'll have 3.5 transfers. +Total subsystem load: 28 ms latency, 2 ms transfer, 30 ms total. .It -Stripe size of 16 kB. On average, you'll have 2.25 transfers. Total subsystem +Stripe size of 16 kB. +On average, you'll have 2.25 transfers. +Total subsystem load: 18 ms latency, 2 ms transfer, 20 ms total. .It -Stripe size of 256 kB. On average, you'll have 1.08 transfers. Total subsystem +Stripe size of 256 kB. +On average, you'll have 1.08 transfers. +Total subsystem load: 8.6 ms latency, 2 ms transfer, 10.6 ms total. .It -Stripe size of 4 MB. On average, you'll have 1.0009 transfers. Total subsystem +Stripe size of 4 MB. +On average, you'll have 1.0009 transfers. +Total subsystem load: 8.01 ms latency, 2 ms transfer, 10.01 ms total. .El .Pp @@ -2349,7 +2590,8 @@ chance of individual requests being on different drives. .It Concatenating UFS file systems across multiple drives can also improve performance for multiple file access, since UFS divides a file system into -cylinder groups and attempts to keep files in a single cylinder group. In +cylinder groups and attempts to keep files in a single cylinder group. +In general, it is not as effective as striping. .It Mirroring can improve multi-access performance for reads, since by default @@ -2357,7 +2599,8 @@ Mirroring can improve multi-access performance for reads, since by default issues consecutive reads to consecutive plexes. .It Mirroring decreases performance for all writes, whether multi-access or single -access, since the data must be written to both plexes. This explains the +access, since the data must be written to both plexes. +This explains the subdisk layout in the example of a mirroring configuration above: if the corresponding subdisk in each plex is on a different physical disk, the write commands can be issued in parallel, whereas if they are on the same physical @@ -2372,7 +2615,8 @@ the write, .Nm must first read the data block and the corresponding parity block, perform some calculations and write back the parity block and the data block, four times as -many transfers as for writing a striped plex. On the other hand, this is offset +many transfers as for writing a striped plex. +On the other hand, this is offset by the cost of mirroring, so writes to a volume with a single RAID-5 plex are approximately half the speed of writes to a correctly configured volume with two striped plexes. @@ -2382,7 +2626,8 @@ When the configuration changes (for example, adding or removing objects, or the change of state of one of the objects), .Nm -writes up to 128 kB of updated configuration to each drive. The larger the +writes up to 128 kB of updated configuration to each drive. +The larger the number of drives, the longer this takes. .El .Ss Creating file systems on Vinum volumes @@ -2390,11 +2635,13 @@ You do not need to run .Xr disklabel 8 before creating a file system on a .Nm -volume. Just run +volume. +Just run .Xr newfs 8 . Use the .Fl v -option to state that the device is not divided into partitions. For example, to +option to state that the device is not divided into partitions. +For example, to create a file system on volume .Pa mirror , enter the following command: @@ -2406,9 +2653,11 @@ A number of other considerations apply to configuration: .Bl -bullet .It -There is no advantage in creating multiple drives on a single disk. Each drive +There is no advantage in creating multiple drives on a single disk. +Each drive uses 131.5 kB of data for label and configuration information, and performance -will suffer when the configuration changes. Use appropriately sized subdisks instead. +will suffer when the configuration changes. +Use appropriately sized subdisks instead. .It It is possible to increase the size of a concatenated .Nm @@ -2421,34 +2670,43 @@ Vinum objects have the concept of .Em state . See .Xr vinum 4 -for more details. They are only completely accessible if their state is +for more details. +They are only completely accessible if their state is .Em up . To change an object state to .Em up , use the .Ic start -command. To change an object state to +command. +To change an object state to .Em down , use the .Ic stop -command. Normally other states are created automatically by the relationship -between objects. For example, if you add a plex to a volume, the subdisks of +command. +Normally other states are created automatically by the relationship +between objects. +For example, if you add a plex to a volume, the subdisks of the plex will be set in the .Em empty state, indicating that, though the hardware is accessible, the data on the -subdisk is invalid. As a result of this state, the plex will be set in the +subdisk is invalid. +As a result of this state, the plex will be set in the .Em faulty state. .Ss The `reviving' state In many cases, when you start a subdisk the system must copy data to the -subdisk. Depending on the size of the subdisk, this can take a long time. +subdisk. +Depending on the size of the subdisk, this can take a long time. During this time, the subdisk is set in the .Em reviving -state. On successful completion of the copy operation, it is automatically set +state. +On successful completion of the copy operation, it is automatically set to the .Em up -state. It is possible for the process performing the revive to be stopped and -restarted. The system keeps track of how far the subdisk has been revived, and +state. +It is possible for the process performing the revive to be stopped and +restarted. +The system keeps track of how far the subdisk has been revived, and when the .Ic start command is reissued, the copying continues from this point. @@ -2456,11 +2714,13 @@ command is reissued, the copying continues from this point. In order to maintain the consistency of a volume while one or more of its plexes is being revived, .Nm -writes to subdisks which have been revived up to the point of the write. It may +writes to subdisks which have been revived up to the point of the write. +It may also read from the plex if the area being read has already been revived. .Sh GOTCHAS The following points are not bugs, and they have good reasons for existing, but -they have shown to cause confusion. Each is discussed in the appropriate +they have shown to cause confusion. +Each is discussed in the appropriate section above. .Bl -enum .It @@ -2496,8 +2756,10 @@ partition. .It When you create a volume with multiple plexes, .Nm -does not automatically initialize the plexes. This means that the contents are -not known, but they are certainly not consistent. As a result, by default +does not automatically initialize the plexes. +This means that the contents are +not known, but they are certainly not consistent. +As a result, by default .Nm sets the state of all newly-created plexes except the first to .Em faulty . @@ -2507,7 +2769,8 @@ them, which causes .Nm to copy the data from a plex which is in the .Em up -state. Depending on the size of the subdisks involved, this can take a long +state. +Depending on the size of the subdisks involved, this can take a long time. .Pp In practice, people aren't too interested in what was in the plex when it was @@ -2533,18 +2796,22 @@ to ignore any possible inconsistency and set the plexes to be .It Some of the commands currently supported by .Nm -are not really needed. For reasons which I don't understand, however, I find +are not really needed. +For reasons which I don't understand, however, I find that users frequently try the .Ic label and .Ic resetconfig commands, though especially .Ic resetconfig -outputs all sort of dire warnings. Don't use these commands unless you have a +outputs all sort of dire warnings. +Don't use these commands unless you have a good reason to do so. .It -Some state transitions are not very intuitive. In fact, it's not clear whether -this is a bug or a feature. If you find that you can't start an object in some +Some state transitions are not very intuitive. +In fact, it's not clear whether +this is a bug or a feature. +If you find that you can't start an object in some strange state, such as a .Em reborn subdisk, try first to get it into @@ -2553,7 +2820,9 @@ state, with the .Ic stop or .Ic stop Fl f -commands. If that works, you should then be able to start it. If you find +commands. +If that works, you should then be able to start it. +If you find that this is the only way to get out of a position where easier methods fail, please report the situation. .It @@ -2564,17 +2833,20 @@ option, you must also build with the .Fl D Ns Dv VINUMDEBUG option, since the size of some data objects used by both components depends on -this option. If you don't do so, commands will fail with a corresponding error +this option. +If you don't do so, commands will fail with a corresponding error message. .It The .Nm Ic read -command has a particularly emetic syntax. Once it was the only way to start +command has a particularly emetic syntax. +Once it was the only way to start .Nm , but now the preferred method is with .Nm Ic start . .Nm Ic read -should be used for maintenance purposes only. Note that its syntax has changed, +should be used for maintenance purposes only. +Note that its syntax has changed, and the arguments must be disk slices, such as .Pa /dev/da0 , not partitions such as |