2926 lines
77 KiB
Groff
2926 lines
77 KiB
Groff
.\" 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.
|