Ups! Forgot to put "sbin" on the commit line:

Remove userland vinum(8) stuff.

1 files changed, 0 insertions, 2925 deletions

diff --git a/sbin/vinum/vinum.8 b/sbin/vinum/vinum.8
deleted file mode 100644
index f71ac23..0000000
--- a/sbin/vinum/vinum.8
+++ /dev/null
@@ -1,2925 +0,0 @@
-.\"  Hey, Emacs, edit this file in -*- nroff-fill -*- mode
-.\"-
-.\" Copyright (c) 1997, 1998
-.\"	Nan Yang Computer Services Limited.  All rights reserved.
-.\"
-.\"  This software is distributed under the so-called ``Berkeley
-.\"  License'':
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"	This product includes software developed by Nan Yang Computer
-.\"      Services Limited.
-.\" 4. Neither the name of the Company nor the names of its contributors
-.\"    may be used to endorse or promote products derived from this software
-.\"    without specific prior written permission.
-.\"
-.\" This software is provided ``as is'', and any express or implied
-.\" warranties, including, but not limited to, the implied warranties of
-.\" merchantability and fitness for a particular purpose are disclaimed.
-.\" In no event shall the company or contributors be liable for any
-.\" direct, indirect, incidental, special, exemplary, or consequential
-.\" damages (including, but not limited to, procurement of substitute
-.\" goods or services; loss of use, data, or profits; or business
-.\" interruption) however caused and on any theory of liability, whether
-.\" in contract, strict liability, or tort (including negligence or
-.\" otherwise) arising in any way out of the use of this software, even if
-.\" advised of the possibility of such damage.
-.\"
-.\" $Id: vinum.8,v 1.15 2001/05/14 01:10:37 grog Exp grog $
-.\" $FreeBSD$
-.\"
-.Dd May 5, 2003
-.Dt VINUM 8
-.Os
-.Sh NAME
-.Nm vinum
-.Nd Logical Volume Manager control program
-.Sh SYNOPSIS
-.Nm
-.Op Ar command
-.Op Fl options
-.Sh COMMANDS
-.Bl -tag -width indent
-.It Ic attach Ar plex volume Op Cm rename
-.It Xo
-.Ic attach Ar subdisk plex
-.Op Ar offset
-.Op Cm rename
-.Xc
-Attach a plex to a volume, or a subdisk to a plex.
-.It Xo
-.Ic checkparity
-.Op Fl f
-.Op Fl v
-.Ar plex
-.Xc
-Check the parity blocks of a RAID-4 or RAID-5 plex.
-.It Xo
-.Ic concat
-.Op Fl f
-.Op Fl n Ar name
-.Op Fl v
-.Ar drives
-.Xc
-Create a concatenated volume from the specified drives.
-.It Xo
-.Ic create
-.Op Fl f
-.Ar description-file
-.Xc
-Create a volume as described in
-.Ar description-file .
-.It Ic debug
-Cause the volume manager to enter the kernel debugger.
-.It Ic debug Ar flags
-Set debugging flags.
-.It Xo
-.Ic detach
-.Op Fl f
-.Op Ar plex | subdisk
-.Xc
-Detach a plex or subdisk from the volume or plex to which it is attached.
-.It Ic dumpconfig Op Ar drive ...
-List the configuration information stored on the specified drives, or all drives
-in the system if no drive names are specified.
-.It Xo
-.Ic info
-.Op Fl v
-.Op Fl V
-.Xc
-List information about volume manager state.
-.It Xo
-.Ic init
-.Op Fl S Ar size
-.Op Fl w
-.Ar plex | subdisk
-.Xc
-.\" XXX
-Initialize the contents of a subdisk or all the subdisks of a plex to all zeros.
-.It Ic label Ar volume
-Create a volume label.
-.It Xo
-.Ic l | list
-.Op Fl r
-.Op Fl s
-.Op Fl v
-.Op Fl V
-.Op Ar volume | plex | subdisk
-.Xc
-List information about specified objects.
-.It Xo
-.Ic ld
-.Op Fl r
-.Op Fl s
-.Op Fl v
-.Op Fl V
-.Op Ar drive
-.Xc
-List information about drives.
-.It Xo
-.Ic ls
-.Op Fl r
-.Op Fl s
-.Op Fl v
-.Op Fl V
-.Op Ar subdisk
-.Xc
-List information about subdisks.
-.It Xo
-.Ic lp
-.Op Fl r
-.Op Fl s
-.Op Fl v
-.Op Fl V
-.Op Ar plex
-.Xc
-List information about plexes.
-.It Xo
-.Ic lv
-.Op Fl r
-.Op Fl s
-.Op Fl v
-.Op Fl V
-.Op Ar volume
-.Xc
-List information about volumes.
-.It Xo
-.Ic mirror
-.Op Fl f
-.Op Fl n Ar name
-.Op Fl s
-.Op Fl v
-.Ar drives
-.Xc
-Create a mirrored volume from the specified drives.
-.It Xo
-.Ic move | mv
-.Fl f
-.Ar drive object ...
-.Xc
-Move the object(s) to the specified drive.
-.It Ic printconfig Op Ar file
-Write a copy of the current configuration to
-.Ar file .
-.It Ic quit
-Exit the
-.Nm
-utility when running in interactive mode.
-Normally this would be done by
-entering the
-.Dv EOF
-character.
-.It Ic read Ar disk ...
-Read the
-.Nm
-configuration from the specified disks.
-.It Xo
-.Ic rename Op Fl r
-.Op Ar drive | subdisk | plex | volume
-.Ar newname
-.Xc
-Change the name of the specified object.
-.\" XXX
-.\".It Ic replace Ar drive newdrive
-.\"Move all the subdisks from the specified drive onto the new drive.
-.It Xo
-.Ic rebuildparity
-.Op Fl f
-.Op Fl v
-.Op Fl V
-.Ar plex
-.Xc
-Rebuild the parity blocks of a RAID-4 or RAID-5 plex.
-.It Ic resetconfig
-Reset the complete
-.Nm
-configuration.
-.It Xo
-.Ic resetstats
-.Op Fl r
-.Op Ar volume | plex | subdisk
-.Xc
-Reset statistics counters for the specified objects, or for all objects if none
-are specified.
-.It Xo
-.Ic rm
-.Op Fl f
-.Op Fl r
-.Ar volume | plex | subdisk
-.Xc
-Remove an object.
-.It Ic saveconfig
-Save
-.Nm
-configuration to disk after configuration failures.
-.\" XXX
-.\".It Xo
-.\".Ic set
-.\".Op Fl f
-.\".Ar state
-.\".Ar volume | plex | subdisk | disk
-.\".Xc
-.\"Set the state of the object to
-.\".Ar state .
-.It Ic setdaemon Op Ar value
-Set daemon configuration.
-.It Xo
-.Ic setstate
-.Ar state
-.Op Ar volume | plex | subdisk | drive
-.Xc
-Set state without influencing other objects, for diagnostic purposes only.
-.It Ic start
-Read configuration from all vinum drives.
-.It Xo
-.Ic start
-.Op Fl i Ar interval
-.Op Fl S Ar size
-.Op Fl w
-.Ar volume | plex | subdisk
-.Xc
-Allow the system to access the objects.
-.It Xo
-.Ic stop
-.Op Fl f
-.Op Ar volume | plex | subdisk
-.Xc
-Terminate access to the objects, or stop
-.Nm
-if no parameters are specified.
-.It Xo
-.Ic stripe
-.Op Fl f
-.Op Fl n Ar name
-.Op Fl v
-.Ar drives
-.Xc
-Create a striped volume from the specified drives.
-.El
-.Sh DESCRIPTION
-The
-.Nm
-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,
-.Nm
-maintains a command line history.
-.Sh OPTIONS
-.Nm
-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
-command ignores the
-.Fl v
-and
-.Fl V
-options.
-.Bl -tag -width indent
-.It Fl f
-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
-.Pp
-.Dl rm -f myvolume
-.Pp
-removes
-.Ar myvolume
-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
-.Ic init
-and
-.Ic start
-commands, wait
-.Ar millisecs
-milliseconds between copying each block.
-This lowers the load on the system.
-.It Fl n Ar name
-Use the
-.Fl n
-option to specify a volume name to the simplified configuration commands
-.Ic concat , mirror
-and
-.Ic stripe .
-.It Fl r
-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
-example, in conjunction with the
-.Ic lv
-command, the
-.Fl r
-option will also show information about the plexes and subdisks belonging to the
-volume.
-.It Fl s
-The
-.Fl s
-.Pq Dq statistics
-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
-The
-.Fl S
-option specifies the transfer size for the
-.Ic init
-and
-.Ic start
-commands.
-.It Fl v
-The
-.Fl v
-.Pq Dq verbose
-option can be used to request more detailed information.
-.It Fl V
-The
-.Fl V
-.Pq Dq Very verbose
-option can be used to request more detailed information than the
-.Fl v
-option provides.
-.It Fl w
-The
-.Fl w
-.Pq Dq wait
-option tells
-.Nm
-to wait for completion of commands which normally run in the background, such as
-.Ic init .
-.El
-.Sh COMMANDS IN DETAIL
-.Nm
-commands perform the following functions:
-.Pp
-.Bl -tag -width indent -compact
-.It Ic attach Ar plex volume Op Cm rename
-.It Xo
-.Ic attach Ar subdisk plex
-.Op Ar offset
-.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
-non-empty volume,
-.Nm
-reintegrates the plex.
-.Pp
-If the keyword
-.Cm rename
-is specified,
-.Nm
-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
-.Ic rename
-command.
-.Pp
-A number of considerations apply to attaching subdisks:
-.Bl -bullet
-.It
-Subdisks can normally only be attached to concatenated plexes.
-.It
-If a striped or RAID-5 plex is missing a subdisk (for example after drive
-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.
-.\"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
-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,
-the first subdisk will have offset 0, the second offset 271k, the third 542k,
-etc.
-This calculation ignores parity blocks in RAID-5 plexes.
-.El
-.Pp
-.It Xo
-.Ic checkparity
-.Op Fl f
-.Op Fl v
-.Ar plex
-.Xc
-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
-.Ic rebuildparity
-command, so rebuilding the parity blocks need only start at the location where
-the first parity problem has been detected.
-.Pp
-If the
-.Fl f
-flag is specified,
-.Ic checkparity
-starts checking at the beginning of the plex.
-If the
-.Fl v
-flag is specified,
-.Ic checkparity
-prints a running progress report.
-.Pp
-.It Xo
-.Ic concat
-.Op Fl f
-.Op Fl n Ar name
-.Op Fl v
-.Ar drives
-.Xc
-The
-.Ic concat
-command provides a simplified alternative to the
-.Ic 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
-.Ic concat
-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
-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
-.Dq Li vinumdrive
-and a small integer, for example
-.Dq Li vinumdrive7 .
-As with the
-.Ic 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
-.Sx SIMPLIFIED CONFIGURATION
-below for some examples of this
-command.
-.Pp
-.It Xo
-.Ic create
-.Op Fl f
-.Ar description-file
-.Xc
-.Nm Ic create
-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
-specify a file name,
-.Nm
-starts an editor on a temporary file.
-If the environment variable
-.Ev EDITOR
-is set,
-.Nm
-starts this editor.
-If not, it defaults to
-.Nm vi .
-See the section
-.Sx CONFIGURATION FILE
-below for more information on the format of
-this file.
-.Pp
-Note that the
-.Nm Ic create
-function is additive: if you run it multiple times, you will create multiple
-copies of all unnamed objects.
-.Pp
-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
-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
-.Nm
-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
-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
-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
-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:
-.Bl -tag -width indent
-.It Dv DEBUG_ADDRESSES Pq No 1
-Show buffer information during requests
-.\".It Dv DEBUG_NUMOUTPUT Pq No 2
-.\"Show the value of
-.\".Va vp->v_numoutput .
-.It Dv DEBUG_RESID Pq No 4
-Go into debugger in
-.Fn complete_rqe .
-.It Dv DEBUG_LASTREQS Pq No 8
-Keep a circular buffer of last requests.
-.It Dv DEBUG_REVIVECONFLICT Pq No 16
-Print info about revive conflicts.
-.It Dv DEBUG_EOFINFO Pq No 32
-Print information about internal state when returning an
-.Dv EOF
-on a striped plex.
-.It Dv DEBUG_MEMFREE Pq No 64
-Maintain a circular list of the last memory areas freed by the memory allocator.
-.It Dv DEBUG_REMOTEGDB Pq No 256
-Go into remote
-.Nm gdb
-when the
-.Ic debug
-command is issued.
-.It Dv DEBUG_WARNINGS Pq No 512
-Print some warnings about minor problems in the implementation.
-.El
-.Pp
-.It Ic detach Oo Fl f Oc Ar plex
-.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,
-the operation will fail unless the
-.Fl f
-option is specified.
-If the object is named after the object above it (for
-example, subdisk
-.Li vol1.p7.s0
-attached to plex
-.Li vol1.p7 ) ,
-the name will be changed
-by prepending the text
-.Dq Li ex-
-(for example,
-.Li ex-vol1.p7.s0 ) .
-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,
-the subdisk is marked absent, and can later be replaced with the
-.Ic attach
-command.
-.Pp
-.It Ic dumpconfig Op Ar drive ...
-.Pp
-.Nm Ic dumpconfig
-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 is not the same as the information returned by the
-.Ic list
-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
-.Fl v
-option, it will give detailed information about the memory areas in use.
-.Pp
-With the
-.Fl V
-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
-looks like:
-.Bd -literal
-vinum -> info -V
-Flags: 0x200    1 opens
-Total of 38 blocks malloced, total memory: 16460
-Maximum allocs:       56, malloc table at 0xf0f72dbc
-
-Time             Event       Buf        Dev     Offset          Bytes   SD      SDoff   Doffset Goffset
-
-14:40:00.637758 1VS Write 0xf2361f40    91.3  0x10            16384
-14:40:00.639280 2LR Write 0xf2361f40    91.3  0x10            16384
-14:40:00.639294 3RQ Read  0xf2361f40    4.39   0x104109        8192    19      0       0       0
-14:40:00.639455 3RQ Read  0xf2361f40    4.23   0xd2109         8192    17      0       0       0
-14:40:00.639529 3RQ Read  0xf2361f40    4.15   0x6e109         8192    16      0       0       0
-14:40:00.652978 4DN Read  0xf2361f40    4.39   0x104109        8192    19      0       0       0
-14:40:00.667040 4DN Read  0xf2361f40    4.15   0x6e109         8192    16      0       0       0
-14:40:00.668556 4DN Read  0xf2361f40    4.23   0xd2109         8192    17      0       0       0
-14:40:00.669777 6RP Write 0xf2361f40    4.39   0x104109        8192    19      0       0       0
-14:40:00.685547 4DN Write 0xf2361f40    4.39   0x104109        8192    19      0       0       0
-11:11:14.975184 Lock      0xc2374210    2      0x1f8001
-11:11:15.018400 7VS Write 0xc2374210           0x7c0           32768   10
-11:11:15.018456 8LR Write 0xc2374210    13.39  0xcc0c9         32768
-11:11:15.046229 Unlock    0xc2374210    2      0x1f8001
-.Ed
-.Pp
-The
-.Ar Buf
-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
-by the event
-.Ar 1VS
-or
-.Ar 7VS .
-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
-.Ar 1
-to
-.Ar 6
-indicates the approximate sequence of events, and the two-letter abbreviation is
-a mnemonic for the location:
-.Bl -tag -width Lockwait
-.It 1VS
-(vinumstrategy) shows information about the user request on entry to
-.Fn vinumstrategy .
-The device number is the
-.Nm
-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
-.Nm
-requests in the function
-.Fn launch_requests .
-The parameters should be the same as in the
-.Ar 1VS
-information.
-.El
-.Pp
-In the following requests,
-.Ar Dev
-is the device number of the associated disk partition,
-.Ar Offset
-is the offset from the beginning of the partition,
-.Ar SD
-is the subdisk index in
-.Va vinum_conf ,
-.Ar SDoff
-is the offset from the beginning of the subdisk,
-.Ar Doffset
-is the offset of the associated data request, and
-.Ar Goffset
-is the offset of the associated group request, where applicable.
-.Bl -tag -width Lockwait
-.It 3RQ
-(request) shows one of possibly several low-level
-.Nm
-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
-launched either at stage
-.Ar 4DN
-from
-.Fn launch_requests ,
-or from
-.Fn complete_raid5_write
-at stage
-.Ar 5RD
-or
-.Ar 6RP .
-.It 5RD
-(RAID-5 data) is called from
-.Fn complete_raid5_write
-and represents the data written to a RAID-5 data stripe after calculating
-parity.
-.It 6RP
-(RAID-5 parity) is called from
-.Fn complete_raid5_write
-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
-.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
-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
-for the range lock.
-.It Unlock
-specifies that a range lock has been released.
-The parameters are the same as
-for the range lock.
-.El
-.\" XXX
-.Pp
-.It Xo
-.Ic init
-.Op Fl S Ar size
-.Op Fl w
-.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
-completion of the command, use the
-.Fl w
-(wait) option.
-.Pp
-Specify the
-.Fl S
-option if you want to write blocks of a different size from the default value of
-16 kB.
-.Nm
-prints a console message when the initialization is complete.
-.Pp
-.It Ic label Ar volume
-The
-.Ic label
-command writes a
-.Em ufs
-style volume label on a volume.
-It is a simple alternative to an appropriate
-call to
-.Ic disklabel .
-This is needed because some
-.Em ufs
-commands still read the disk to find the label instead of using the correct
-.Xr ioctl 2
-call to access it.
-.Nm
-maintains a volume label separately from the volume data, so this command is not
-needed for
-.Xr newfs 8 .
-This command is deprecated.
-.Pp
-.It Xo
-.Ic list
-.Op Fl r
-.Op Fl V
-.Op Ar volume | plex | subdisk
-.Xc
-.It Xo
-.Ic l
-.Op Fl r
-.Op Fl V
-.Op Ar volume | plex | subdisk
-.Xc
-.It Xo
-.Ic ld
-.Op Fl r
-.Op Fl s
-.Op Fl v
-.Op Fl V
-.Op Ar drive
-.Xc
-.It Xo
-.Ic ls
-.Op Fl r
-.Op Fl s
-.Op Fl v
-.Op Fl V
-.Op Ar subdisk
-.Xc
-.It Xo
-.Ic lp
-.Op Fl r
-.Op Fl s
-.Op Fl v
-.Op Fl V
-.Op Ar plex
-.Xc
-.It Xo
-.Ic lv
-.Op Fl r
-.Op Fl s
-.Op Fl v
-.Op Fl V
-.Op Ar volume
-.Xc
-.Ic list
-is used to show information about the specified object.
-If the argument is
-omitted, information is shown about all objects known to
-.Nm .
-The
-.Ic l
-command is a synonym for
-.Ic list .
-.Pp
-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
-.Ic lv , lp , ls
-and
-.Ic ld
-list only volumes, plexes, subdisks and drives respectively.
-This is
-particularly useful when used without parameters.
-.Pp
-The
-.Fl s
-option causes
-.Nm
-to output device statistics, the
-.Fl v
-(verbose) option causes some additional information to be output, and the
-.Fl V
-causes considerable additional information to be output.
-.Pp
-.It Xo
-.Ic mirror
-.Op Fl f
-.Op Fl n Ar name
-.Op Fl s
-.Op Fl v
-.Ar drives
-.Xc
-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
-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,
-.Ic mirror
-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.
-.Pp
-Normally, the
-.Ic mirror
-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
-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
-.Dq Li vinumdrive
-and a small integer, for example
-.Dq Li vinumdrive7 .
-As with the
-.Ic 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
-.Sx SIMPLIFIED CONFIGURATION
-below for some examples of this
-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,
-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
-form, however, it is suited to recovering a failed disk drive.
-.Pp
-.It Ic printconfig Op Ar file
-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
-.Ar file ,
-.Nm
-writes the list to
-.Dv stdout .
-.Pp
-.It Ic quit
-Exit the
-.Nm
-utility when running in interactive mode.
-Normally this would be done by
-entering the
-.Dv EOF
-character.
-.Pp
-.It Ic read Ar disk ...
-The
-.Ic read
-command scans the specified disks for
-.Nm
-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
-parameter to this command.
-.Pp
-The
-.Ic read
-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
-use the
-.Ic start
-command.
-.Pp
-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
-happen if the configuration on disk indicates a configuration error (for
-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
-re-enable configuration saves.
-.Pp
-.It Xo
-.Ic rebuildparity
-.Op Fl f
-.Op Fl v
-.Op Fl V
-.Ar plex
-.Xc
-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
-by the
-.Ic checkparity
-command, so rebuilding the parity blocks need only start at the location where
-the first parity problem has been detected.
-.Pp
-If the
-.Fl f
-flag is specified,
-.Ic rebuildparity
-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
-.Fl V
-flag is specified,
-.Ic rebuildparity
-prints a running progress report.
-.Pp
-.It Xo
-.Ic rename
-.Op Fl r
-.Op Ar drive | subdisk | plex | volume
-.Ar newname
-.Xc
-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
-.Li .p Ns Ar number
-to the volume name, and
-subdisk names will be formed by appending
-.Li .s Ns Ar number
-to the plex name.
-.\".Pp
-.\".It Xo
-.\".Ic replace
-.\".Ar drive newdrive
-.\"Move all the subdisks from the specified drive onto the new drive.
-.\"This will
-.\"attempt to recover those subdisks that can be recovered, and create the others
-.\"from scratch.
-.\"If the new drive lacks the space for this operation, as many
-.\"subdisks as possible will be fitted onto the drive, and the rest will be left on
-.\"the original drive.
-.Pp
-.It Ic resetconfig
-The
-.Ic resetconfig
-command completely obliterates the
-.Nm
-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
-.Li "NO FUTURE"
-exactly as shown:
-.Bd -unfilled -offset indent
-.No # Nm Ic resetconfig
-
-WARNING!  This command will completely wipe out your vinum
-configuration.  All data will be lost.  If you really want
-to do this, enter the text
-
-NO FUTURE
-.No "Enter text ->" Sy "NO FUTURE"
-Vinum configuration obliterated
-.Ed
-.Pp
-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
-.Ic resetstats
-.Op Fl r
-.Op Ar volume | plex | subdisk
-.Xc
-.Nm
-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
-.Fl r
-option,
-.Nm
-also resets the counters of subordinate objects.
-.Pp
-.It Xo
-.Ic rm
-.Op Fl f
-.Op Fl r
-.Ar volume | plex | subdisk
-.Xc
-.Ic rm
-removes an object from the
-.Nm
-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
-.Fl f
-option tells
-.Nm
-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
-.Nm
-to remove the object anyway by using the
-.Fl f
-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
-.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
-.Nm
-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
-the configuration.
-.\".Pp
-.\".It Xo
-.\".Ic set
-.\".Op Fl f
-.\".Ar state
-.\".Ar volume | plex | subdisk | disk
-.\".Xc
-.\".Ic set
-.\"sets the state of the specified object to one of the valid states (see
-.\".Sx OBJECT STATES
-.\"below).
-.\"Normally
-.\".Nm
-.\"performs a large amount of consistency checking before making the change.
-.\"The
-.\".Fl f
-.\"option tells
-.\".Nm
-.\"to omit this checking and perform the change anyway.
-.\"Use this option with great
-.\"care: it can result in total loss of data on a volume.
-.Pp
-.It Ic setdaemon Op Ar value
-.Ic setdaemon
-sets a variable bitmask for the
-.Nm
-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.
-.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
-the usual consistency mechanism of
-.Nm
-and should be used only for recovery purposes.
-It is possible to crash the
-system by incorrect use of this command.
-.Pp
-.It Xo
-.Ic start
-.Op Fl i Ar interval
-.Op Fl S Ar size
-.Op Fl w
-.Op Ar plex | subdisk
-.Xc
-.Ic start
-starts (brings into to the
-.Em up
-state) one or more
-.Nm
-objects.
-.Pp
-If no object names are specified,
-.Nm
-scans the disks known to the system for
-.Nm
-drives and then reads in the configuration as described under the
-.Ic read
-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
-plexes and volumes.
-.Pp
-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
-happen if the configuration on disk indicates a configuration error (for
-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
-saves.
-.Pp
-If object names are specified,
-.Nm
-starts them.
-Normally this operation is only of use with subdisks.
-The action
-depends on the current state of the object:
-.Bl -bullet
-.It
-If the object is already in the
-.Em up
-state,
-.Nm
-does nothing.
-.It
-If the object is a subdisk in the
-.Em down
-or
-.Em reborn
-states,
-.Nm
-changes it to the
-.Em up
-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
-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
-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
-other plexes, or if it is not part of a plex,
-.Nm
-brings it into the
-.Em up
-state immediately.
-.It
-If the object is a subdisk in the
-.Em reviving
-state,
-.Nm
-continues the revive
-operation offline.
-When the operation completes, the subdisk is set into the
-.Em up
-state.
-.El
-.Pp
-When a subdisk comes into the
-.Em up
-state,
-.Nm
-automatically checks the state of any plex and volume to which it may belong and
-changes their state where appropriate.
-.Pp
-If the object is a plex,
-.Ic start
-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
-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
-.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.
-.Pp
-.It Xo
-.Ic stop
-.Op Fl f
-.Op Ar volume | plex | subdisk
-.Xc
-If no parameters are specified,
-.Ic stop
-removes the
-.Nm
-kld and stops
-.Xr vinum 4 .
-This can only be done if no objects are active.
-In particular, the
-.Fl f
-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
-specifying the
-.Fl f
-option.
-.Pp
-The
-.Ic stop
-command can only work if
-.Nm
-has been loaded as a kld, since it is not possible to unload a statically
-configured driver.
-.Nm Ic stop
-will fail if
-.Nm
-is statically configured.
-.Pp
-If object names are specified,
-.Ic stop
-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
-.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
-.Fl f
-option tells
-.Nm
-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
-.It Xo
-.Ic stripe
-.Op Fl f
-.Op Fl n Ar name
-.Op Fl v
-.Ar drives
-.Xc
-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
-subdisks is the size of the largest contiguous space available on all the
-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
-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
-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
-.Dq Li vinumdrive
-and a small integer, for example
-.Dq Li vinumdrive7 .
-As with the
-.Ic 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
-.Sx SIMPLIFIED CONFIGURATION
-below for some examples of this
-command.
-.El
-.Sh SIMPLIFIED CONFIGURATION
-This section describes a simplified interface to
-.Nm
-configuration using the
-.Ic concat ,
-.Ic mirror
-and
-.Ic stripe
-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,
-.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       D: vinumdrive0  Size:        414 MB
-S vinum0.p0.s1          State: up       D: vinumdrive1  Size:        573 MB
-S vinum0.p0.s2          State: up       D: vinumdrive2  Size:        573 MB
-S vinum0.p0.s3          State: up       D: vinumdrive3  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 279k
-    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       D: vinumdrive0  Size:        414 MB
-S vinum0.p0.s1          State: up       D: vinumdrive1  Size:        414 MB
-S vinum0.p0.s2          State: up       D: vinumdrive2  Size:        414 MB
-S vinum0.p0.s3          State: up       D: vinumdrive3  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 vinum0.p0.s0          State: up       D: vinumdrive0  Size:        414 MB
-S vinum0.p0.s2          State: up       D: vinumdrive2  Size:        414 MB
-S vinum0.p0.s1          State: up       D: vinumdrive1  Size:        414 MB
-S vinum0.p0.s3          State: up       D: vinumdrive3  Size:        414 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
-.Ic 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 279k
-    sd name raid10.p0.s0 drive vinumdrive0 size 849825b
-    sd name raid10.p0.s1 drive vinumdrive2 size 849825b
-  plex name raid10.p1 org striped 279k
-    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:      279 kB Size:        414 MB
-S raid10.p1.s0          State: up       PO:        0  B Size:        573 MB
-S raid10.p1.s1          State: up       PO:      279 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.
-.Sh CONFIGURATION FILE
-The
-.Nm
-utility requires that all parameters to the
-.Ic create
-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
-Some configuration file parameters specify a size (lengths, stripe sizes).
-These values can be specified as bytes, or one of the following scale factors
-may be appended:
-.Bl -tag -width indent
-.It s
-specifies that the value is a number of sectors of 512 bytes.
-.It k
-specifies that the value is a number of kilobytes (1024 bytes).
-.It m
-specifies that the value is a number of megabytes (1048576 bytes).
-.It g
-specifies that the value is a number of gigabytes (1073741824 bytes).
-.It b
-is used for compatibility with
-.Tn VERITAS .
-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'
-instead.
-.El
-.Pp
-For example, the value 16777216 bytes can also be written as
-.Em 16m ,
-.Em 16384k
-or
-.Em 32768s .
-.Pp
-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:
-.Bl -tag -width 18n
-.It Cm device Ar devicename
-Specify the device on which the drive resides.
-.Ar devicename
-must be the name of a disk partition, for example
-.Pa /dev/da1e
-or
-.Pa /dev/ad3s2h ,
-and it must be of type
-.Em vinum .
-Do not use the
-.Dq Li c
-partition, which is reserved for the complete disk.
-.It Cm hotspare
-Define the drive to be a
-.Dq hot spare
-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
-completely implemented.
-.El
-.It Ic volume Ar name Op Ar options
-Define a volume with name
-.Ar name .
-Options are:
-.Bl -tag -width 18n
-.It Cm plex Ar plexname
-Add the specified plex to the volume.
-If
-.Ar plexname
-is specified as
-.Cm * ,
-.Nm
-will look for the definition of the plex as the next possible entry in the
-configuration file after the definition of the volume.
-.It Cm readpol Ar policy
-Define a
-.Em read policy
-for the volume.
-.Ar policy
-may be either
-.Cm round
-or
-.Cm prefer Ar plexname .
-The
-.Nm
-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
-.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
-.Nm
-sets all plexes except the first one to the
-.Em faulty
-state.
-Use the
-.Ic start
-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
-must integrate them manually with the
-.Ic start
-command.
-.Pp
-Note that you
-.Em must
-use the
-.Ic init
-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.
-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
-.Cm name
-when naming a plex or subdisk.
-.It Cm org Ar organization Op Ar stripesize
-Specify the organization of the plex.
-.Ar organization
-can be one of
-.Cm concat , striped
-or
-.Cm raid5 .
-For
-.Cm striped
-and
-.Cm raid5
-plexes, the parameter
-.Ar stripesize
-must be specified, while for
-.Cm concat
-it must be omitted.
-For type
-.Cm striped ,
-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
-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
-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
-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
-have at least 5 subdisks.
-.It Cm volume Ar volname
-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.
-.It Cm sd Ar sdname offset
-Add the specified subdisk to the plex at offset
-.Ar offset .
-.El
-.It Ic subdisk Op Ar options
-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
-subdisk\(emsee
-.Sx OBJECT NAMING
-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,
-.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,
-.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
-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
-subdisk.
-.Cm length
-may be shortened to
-.Cm len .
-.It Cm plex Ar plex
-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
-on the last drive specified.
-.It Cm retryerrors
-Specify that the subdisk should not be taken down if an unrecoverable error
-occurs.
-Normally
-.Nm
-responds to an unrecoverable error by making the entire subdisk inaccessible.
-.El
-.El
-.Sh EXAMPLE CONFIGURATION FILE
-.Bd -literal
-# Sample vinum configuration file
-#
-# Our drives
-drive drive1 device /dev/da1h
-drive drive2 device /dev/da2h
-drive drive3 device /dev/da3h
-drive drive4 device /dev/da4h
-drive drive5 device /dev/da5h
-drive drive6 device /dev/da6h
-# A volume with one striped plex
-volume tinyvol
- plex org striped 279k
-  sd length 64m drive drive2
-  sd length 64m drive drive4
-volume stripe
- plex org striped 279k
-  sd length 512m drive drive2
-  sd length 512m drive drive4
-# Two plexes
-volume concat
- plex org concat
-  sd length 100m drive drive2
-  sd length 50m drive drive4
- plex org concat
-  sd length 150m drive drive4
-# A volume with one striped plex and one concatenated plex
-volume strcon
- plex org striped 279k
-  sd length 100m drive drive2
-  sd length 100m drive drive4
- plex org concat
-  sd length 150m drive drive2
-  sd length 50m drive drive4
-# a volume with a RAID-5 and a striped plex
-# note that the RAID-5 volume is longer by
-# the length of one subdisk
-volume vol5
- plex org striped 491k
-  sd length 1000m drive drive2
-  sd length 1000m drive drive4
- plex org raid5 273k
-  sd length 500m drive drive1
-  sd length 500m drive drive2
-  sd length 500m drive drive3
-  sd length 500m drive drive4
-  sd length 500m drive drive5
-.Ed
-.Sh DRIVE LAYOUT CONSIDERATIONS
-.Nm
-drives are currently
-.Bx
-disk partitions.
-They must be of type
-.Em vinum
-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
-partition layout as shown by
-.Xr disklabel 8 :
-.Bd -literal
-8 partitions:
-#        size   offset    fstype   [fsize bsize bps/cpg]
-  a:    81920   344064    4.2BSD        0     0     0   # (Cyl.  240*- 297*)
-  b:   262144    81920      swap                        # (Cyl.   57*- 240*)
-  c:  4226725        0    unused        0     0         # (Cyl.    0 - 2955*)
-  e:    81920        0    4.2BSD        0     0     0   # (Cyl.    0 - 57*)
-  f:  1900000   425984    4.2BSD        0     0     0   # (Cyl.  297*- 1626*)
-  g:  1900741  2325984     vinum        0     0     0   # (Cyl. 1626*- 2955*)
-.Ed
-.Pp
-In this example, partition
-.Dq Li g
-may be used as a
-.Nm
-partition.
-Partitions
-.Dq Li a ,
-.Dq Li e
-and
-.Dq Li f
-may be used as
-.Em UFS
-file systems or
-.Em ccd
-partitions.
-Partition
-.Dq Li b
-is a swap partition, and partition
-.Dq Li c
-represents the whole disk and should not be used for any other purpose.
-.Pp
-The
-.Nm
-utility
-uses the first 265 sectors on each partition for configuration information, so
-the maximum size of a subdisk is 265 sectors smaller than the drive.
-.Sh LOG FILE
-The
-.Nm
-utility maintains a log file, by default
-.Pa /var/log/vinum_history ,
-in which it keeps track of the commands issued to
-.Nm .
-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
-.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
-environment variable
-.Ev VINUM_DATEFORMAT .
-.Sh HOW TO SET UP VINUM
-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
-disk partitions for
-.Nm .
-They should be partitions, not devices, and they should not be partition
-.Dq Li c .
-For example, good names are
-.Pa /dev/da0e
-or
-.Pa /dev/ad3s4a .
-Bad names are
-.Pa /dev/da0
-and
-.Pa /dev/da0s1 ,
-both of which represent a device, not a partition, and
-.Pa /dev/ad1c ,
-which represents a complete disk and should be of type
-.Em unused .
-See the example under
-.Sx DRIVE LAYOUT CONSIDERATIONS
-above.
-.Ss Designing volumes
-The way you set up
-.Nm
-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
-space for a single volume, you might write a configuration file like:
-.Bd -literal -offset indent
-drive d1 device /dev/da2e
-drive d2 device /dev/da3e
-drive d3 device /dev/da4e
-drive d4 device /dev/da5e
-drive d5 device /dev/da6e
-volume bigger
- plex org concat
-   sd length 0 drive d1
-   sd length 0 drive d2
-   sd length 0 drive d3
-   sd length 0 drive d4
-   sd length 0 drive d5
-.Ed
-.Pp
-In this case, you specify the length of the subdisks as 0, which means
-.Dq "use the largest area of free space that you can find on the drive" .
-If the subdisk is the only subdisk on the drive, it will use all available
-space.
-.It
-You want to set up
-.Nm
-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
-a mirrored volume of 2 GB, you might create the following configuration file:
-.Bd -literal -offset indent
-drive d1 device /dev/da2e
-drive d2 device /dev/da3e
-volume mirror
- plex org concat
-   sd length 2g drive d1
- plex org concat
-   sd length 2g drive d2
-.Ed
-.Pp
-When creating mirrored drives, it is important to ensure that the data from each
-plex is on a different physical disk so that
-.Nm
-can access the complete address space of the volume even if a drive fails.
-Note that each plex requires as much data as the complete volume: in this
-example, the volume has a size of 2 GB, but each plex (and each subdisk)
-requires 2 GB, so the total disk storage requirement is 4 GB.
-.Pp
-To set up RAID-5, create a single plex of type
-.Cm raid5 .
-For example, to create an equivalent resilient volume of 2 GB, you might use the
-following configuration file:
-.Bd -literal -offset indent
-drive d1 device /dev/da2e
-drive d2 device /dev/da3e
-drive d3 device /dev/da4e
-drive d4 device /dev/da5e
-drive d5 device /dev/da6e
-volume raid
- plex org raid5 433k
-   sd length 512m drive d1
-   sd length 512m drive d2
-   sd length 512m drive d3
-   sd length 512m drive d4
-   sd length 512m drive d5
-.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
-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
-require 3 GB to store the information, for example:
-.Bd -literal -offset indent
-drive d1 device /dev/da2e
-drive d2 device /dev/da3e
-drive d3 device /dev/da4e
-volume raid
- plex org raid5 433k
-   sd length 1g drive d1
-   sd length 1g drive d2
-   sd length 1g drive d3
-.Ed
-.Pp
-As with creating mirrored drives, it is important to ensure that the data from
-each subdisk is on a different physical disk so that
-.Nm
-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
-multiple disks, you can increase the throughput in multi-access environments.
-This technique shows little or no performance improvement in single-access
-environments.
-The
-.Nm
-utility uses a technique called
-.Dq striping ,
-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
-that one of them will fail.
-.Pp
-To implement striping, use a
-.Cm striped
-plex:
-.Bd -literal -offset indent
-drive d1 device /dev/da2e
-drive d2 device /dev/da3e
-drive d3 device /dev/da4e
-drive d4 device /dev/da5e
-volume raid
- plex org striped 433k
-   sd length 512m drive d1
-   sd length 512m drive d2
-   sd length 512m drive d3
-   sd length 512m drive d4
-.Ed
-.Pp
-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
-.Nm
-you can do this with the following configuration file:
-.Bd -literal -offset indent
-drive d1 device /dev/da2e
-drive d2 device /dev/da3e
-drive d3 device /dev/da4e
-drive d4 device /dev/da5e
-volume raid setupstate
- plex org striped 433k
-   sd length 512m drive d1
-   sd length 512m drive d2
-   sd length 512m drive d3
-   sd length 512m drive d4
- plex org striped 433k
-   sd length 512m drive d4
-   sd length 512m drive d3
-   sd length 512m drive d2
-   sd length 512m drive d1
-.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
-keyword
-.Cm setupstate ,
-which ensures that all plexes are
-.Em up
-after creation.
-.El
-.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
-.Pa configfile :
-.Bd -literal -offset 2n
-# vinum create -v configfile
-   1: drive d1 device /dev/da2e
-   2: drive d2 device /dev/da3e
-   3: volume mirror
-   4:  plex org concat
-   5:    sd length 2g drive d1
-   6:  plex org concat
-   7:    sd length 2g drive d2
-Configuration summary
-
-Drives:         2 (4 configured)
-Volumes:        1 (4 configured)
-Plexes:         2 (8 configured)
-Subdisks:       2 (16 configured)
-
-Drive d1:       Device /dev/da2e
-                Created on vinum.lemis.com at Tue Mar 23 12:30:31 1999
-                Config last updated Tue Mar 23 14:30:32 1999
-                Size:      60105216000 bytes (57320 MB)
-                Used:       2147619328 bytes (2048 MB)
-                Available: 57957596672 bytes (55272 MB)
-                State: up
-                Last error: none
-Drive d2:       Device /dev/da3e
-                Created on vinum.lemis.com at Tue Mar 23 12:30:32 1999
-                Config last updated Tue Mar 23 14:30:33 1999
-                Size:      60105216000 bytes (57320 MB)
-                Used:       2147619328 bytes (2048 MB)
-                Available: 57957596672 bytes (55272 MB)
-                State: up
-                Last error: none
-
-Volume mirror:  Size: 2147483648 bytes (2048 MB)
-                State: up
-                Flags:
-                2 plexes
-                Read policy: round robin
-
-Plex mirror.p0: Size:   2147483648 bytes (2048 MB)
-                Subdisks:        1
-                State: up
-                Organization: concat
-                Part of volume mirror
-Plex mirror.p1: Size:   2147483648 bytes (2048 MB)
-                Subdisks:        1
-                State: up
-                Organization: concat
-                Part of volume mirror
-
-Subdisk mirror.p0.s0:
-                Size:       2147483648 bytes (2048 MB)
-                State: up
-                Plex mirror.p0 at offset 0
-
-Subdisk mirror.p1.s0:
-                Size:       2147483648 bytes (2048 MB)
-                State: up
-                Plex mirror.p1 at offset 0
-.Ed
-.Pp
-The
-.Fl v
-option tells
-.Nm
-to list the file as it configures.
-Subsequently it lists the current
-configuration in the same format as the
-.Ic list Fl v
-command.
-.Ss Creating more volumes
-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
-.Ic create
-command again, you will create additional objects:
-.Bd -literal
-# vinum create sampleconfig
-Configuration summary
-
-Drives:         2 (4 configured)
-Volumes:        1 (4 configured)
-Plexes:         4 (8 configured)
-Subdisks:       4 (16 configured)
-
-D d1                    State: up       Device /dev/da2e        Avail: 53224/57320 MB (92%)
-D d2                    State: up       Device /dev/da3e        Avail: 53224/57320 MB (92%)
-
-V mirror                State: up       Plexes:       4 Size:       2048 MB
-
-P mirror.p0           C State: up       Subdisks:     1 Size:       2048 MB
-P mirror.p1           C State: up       Subdisks:     1 Size:       2048 MB
-P mirror.p2           C State: up       Subdisks:     1 Size:       2048 MB
-P mirror.p3           C State: up       Subdisks:     1 Size:       2048 MB
-
-S mirror.p0.s0          State: up       PO:        0  B Size:       2048 MB
-S mirror.p1.s0          State: up       PO:        0  B Size:       2048 MB
-S mirror.p2.s0          State: up       PO:        0  B Size:       2048 MB
-S mirror.p3.s0          State: up       PO:        0  B Size:       2048 MB
-.Ed
-.Pp
-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
-the drives that
-.Nm
-already knows about.
-For example, to create a volume
-.Pa raid
-on the four drives
-.Pa /dev/da1e , /dev/da2e , /dev/da3e
-and
-.Pa /dev/da4e ,
-you only need to mention the other two:
-.Bd -literal -offset indent
-drive d3 device /dev/da1e
-drive d4 device /dev/da4e
-volume raid
-  plex org raid5 433k
-    sd size 2g drive d1
-    sd size 2g drive d2
-    sd size 2g drive d3
-    sd size 2g drive d4
-.Ed
-.Pp
-With this configuration file, we get:
-.Bd -literal
-# vinum create newconfig
-Configuration summary
-
-Drives:         4 (4 configured)
-Volumes:        2 (4 configured)
-Plexes:         5 (8 configured)
-Subdisks:       8 (16 configured)
-
-D d1                    State: up       Device /dev/da2e        Avail: 51176/57320 MB (89%)
-D d2                    State: up       Device /dev/da3e        Avail: 53220/57320 MB (89%)
-D d3                    State: up       Device /dev/da1e        Avail: 53224/57320 MB (92%)
-D d4                    State: up       Device /dev/da4e        Avail: 53224/57320 MB (92%)
-
-V mirror                State: down     Plexes:       4 Size:       2048 MB
-V raid                  State: down     Plexes:       1 Size:       6144 MB
-
-P mirror.p0           C State: init     Subdisks:     1 Size:       2048 MB
-P mirror.p1           C State: init     Subdisks:     1 Size:       2048 MB
-P mirror.p2           C State: init     Subdisks:     1 Size:       2048 MB
-P mirror.p3           C State: init     Subdisks:     1 Size:       2048 MB
-P raid.p0            R5 State: init     Subdisks:     4 Size:       6144 MB
-
-S mirror.p0.s0          State: up       PO:        0  B Size:       2048 MB
-S mirror.p1.s0          State: up       PO:        0  B Size:       2048 MB
-S mirror.p2.s0          State: up       PO:        0  B Size:       2048 MB
-S mirror.p3.s0          State: up       PO:        0  B Size:       2048 MB
-S raid.p0.s0            State: empty    PO:        0  B Size:       2048 MB
-S raid.p0.s1            State: empty    PO:      433 kB Size:       2048 MB
-S raid.p0.s2            State: empty    PO:      866 kB Size:       2048 MB
-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
-subdisk is used for storing parity data.
-.Ss Restarting Vinum
-On rebooting the system, start
-.Nm
-with the
-.Ic start
-command:
-.Pp
-.Dl "# vinum start"
-.Pp
-This will start all the
-.Nm
-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
-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
-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
-in performance: the decrease in transfer time per disk is offset by the order of
-magnitude greater increase in latency.
-.Pp
-With modern disk sizes and the
-.Fx
-I/O system, you can expect to have a
-reasonably small number of fragmented requests with a stripe size between 256 kB
-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
-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.
-.Pp
-The easiest way to consider the impact of any transfer in a multi-access system
-is to look at it from the point of view of the potential bottleneck, the disk
-subsystem: how much total disk time does the transfer use?
-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
-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
-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,
-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:
-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
-latency, 2 ms transfer, 50 ms total.
-.It
-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
-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
-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
-load: 8.01 ms latency, 2 ms transfer, 10.01 ms total.
-.El
-.Pp
-It appears that some hardware RAID systems have problems with large stripes:
-they appear to always transfer a complete stripe to or from disk, so that a
-large stripe size will have an adverse effect on performance.
-The
-.Nm
-utility
-does not suffer from this problem: it optimizes all disk transfers and does not
-transfer unneeded data.
-.Pp
-Note that no well-known benchmark program tests true multi-access conditions
-(more than 100 concurrent users), so it is difficult to demonstrate the validity
-of these statements.
-.Pp
-Given these considerations, the following factors affect the performance of a
-.Nm
-volume:
-.Bl -bullet
-.It
-Striping improves performance for multiple access only, since it increases the
-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
-general, it is not as effective as striping.
-.It
-Mirroring can improve multi-access performance for reads, since by default
-.Nm
-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
-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
-disk, they will be performed sequentially.
-.It
-RAID-5 reads have essentially the same considerations as striped reads, unless
-the striped plex is part of a mirrored volume, in which case the performance of
-the mirrored volume will be better.
-.It
-RAID-5 writes are approximately 25% of the speed of striped writes: to perform
-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
-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.
-.It
-When the
-.Nm
-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
-number of drives, the longer this takes.
-.El
-.Ss Creating file systems on Vinum volumes
-You do not need to run
-.Xr disklabel 8
-before creating a file system on a
-.Nm
-volume.
-Just run
-.Xr newfs 8 .
-Use the
-.Fl v
-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:
-.Pp
-.Dl "# newfs -v /dev/vinum/mirror"
-.Pp
-A number of other considerations apply to
-.Nm
-configuration:
-.Bl -bullet
-.It
-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.
-.It
-It is possible to increase the size of a concatenated
-.Nm
-plex, but currently the size of striped and RAID-5 plexes cannot be increased.
-Currently the size of an existing UFS file system also cannot be increased, but
-it is planned to make both plexes and file systems extensible.
-.El
-.Sh STATE MANAGEMENT
-Vinum objects have the concept of
-.Em state .
-See
-.Xr vinum 4
-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
-.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
-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
-.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.
-During this time, the subdisk is set in the
-.Em reviving
-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
-when the
-.Ic start
-command is reissued, the copying continues from this point.
-.Pp
-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
-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
-section above.
-.Bl -enum
-.It
-.Nm
-drives are
-.Ux
-disk partitions and must have the partition type
-.Em vinum .
-This is different from ccd, which expects partitions of type
-.Em 4.2BSD .
-This behaviour of
-.Nm ccd
-is an invitation to shoot yourself in the foot: with
-.Nm ccd
-you can easily overwrite a file system.
-The
-.Nm
-utility will not permit this.
-.Pp
-For similar reasons, the
-.Nm Ic start
-command will not accept a drive on partition
-.Dq Li c .
-Partition
-.Dq Li c
-is used by the system to represent the whole disk, and must be of type
-.Em unused .
-Clearly there is a conflict here, which
-.Nm
-resolves by not using the
-.Dq Li c
-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
-.Nm
-sets the state of all newly-created plexes except the first to
-.Em faulty .
-In order to synchronize them with the first plex, you must
-.Ic start
-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
-time.
-.Pp
-In practice, people aren't too interested in what was in the plex when it was
-created, and other volume managers cheat by setting them
-.Em up
-anyway.
-The
-.Nm
-utility provides two ways to ensure that newly created plexes are
-.Em up :
-.Bl -bullet
-.It
-Create the plexes and then synchronize them with
-.Nm Ic start .
-.It
-Create the volume (not the plex) with the keyword
-.Cm setupstate ,
-which tells
-.Nm
-to ignore any possible inconsistency and set the plexes to be
-.Em up .
-.El
-.It
-Some of the commands currently supported by
-.Nm
-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
-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
-strange state, such as a
-.Em reborn
-subdisk, try first to get it into
-.Em stopped
-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
-that this is the only way to get out of a position where easier methods fail,
-please report the situation.
-.It
-If you build the kernel module with the
-.Fl D Ns Dv VINUMDEBUG
-option, you must also build
-.Nm
-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
-message.
-.It
-The
-.Nm Ic read
-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,
-and the arguments must be disk slices, such as
-.Pa /dev/da0 ,
-not partitions such as
-.Pa /dev/da0e .
-.El
-.Sh FILES
-.Bl -tag -width /dev/vinum/control -compact
-.It Pa /dev/vinum
-directory with device nodes for
-.Nm
-objects
-.It Pa /dev/vinum/control
-control device for
-.Nm
-.It Pa /dev/vinum/plex
-directory containing device nodes for
-.Nm
-plexes
-.It Pa /dev/vinum/sd
-directory containing device nodes for
-.Nm
-subdisks
-.El
-.Sh ENVIRONMENT
-.Bl -tag -width VINUM_DATEFORMAT
-.It Ev VINUM_HISTORY
-The name of the log file, by default
-.Pa /var/log/vinum_history .
-.It Ev VINUM_DATEFORMAT
-The format of dates in the log file, by default
-.Qq Li %e %b %Y %H:%M:%S .
-.It Ev EDITOR
-The name of the editor to use for editing configuration files, by default
-.Nm vi .
-.El
-.Sh SEE ALSO
-.Xr strftime 3 ,
-.Xr vinum 4 ,
-.Xr disklabel 8 ,
-.Xr newfs 8
-.Pp
-.Pa http://www.vinumvm.org/vinum/ ,
-.Pa http://www.vinumvm.org/vinum/how-to-debug.html .
-.Sh AUTHORS
-.An Greg Lehey Aq grog@lemis.com
-.Sh HISTORY
-The
-.Nm
-utility first appeared in
-.Fx 3.0 .
-The RAID-5 component of
-.Nm
-was developed for Cybernet Inc.\&
-.Pq Pa www.cybernet.com
-for its NetMAX product.
-.Sh BUGS
-.Xr vinum 4
-does not use the
-.Xr geom 4
-subsystem so
-.Xr vinum 4
-volumes cannot be used with GEOM based facilities like
-.Xr gbde 8 .
-.Pp
-.Xr vinum 4
-is unable to function on devices with a block size other than
-.Dv DEV_BSIZE
-(512), so cannot be used on swap-backed
-.Xr md 4
-devices.