home | help 
GVINUM(8)		     System Manager's Manual		       GVINUM(8)

NAME
     gvinum -- Logical Volume Manager control program

SYNOPSIS
     gvinum [command] [-options]

COMMANDS
     attach plex volume [rename]

     attach subdisk plex [offset] [rename]
	     Attach  a	plex  to a volume, or a subdisk to a plex.  If offset is
	     specified, the subdisk will be attached to the given offset  within
	     the  plex.  If rename is specified, the subdisk or plex will change
	     name according to the object it attaches to.

     checkparity [-f] plex
	     Check the parity blocks of a RAID-5 plex.	The  parity  check  will
	     start  at the beginning of the plex if the -f flag is specified, or
	     otherwise at the location of the parity check  pointer,  the  first
	     location  at which plex's parity is incorrect.  All subdisks in the
	     plex must be up for a parity check.

     concat [-fv] [-n name] drives
	     Create a concatenated volume from the specified drives.  If no name
	     is specified, a unique name will be set by gvinum.

     create [-f] [description-file]
	     Create  a	volume	as  described  in   description-file.	 If   no
	     description-file provided, opens an editor and provides the current
	     gvinum configuration for editing.	The -f flag will make gvinum ig-
	     nore  any	errors	regarding  creating objects that already exists.
	     However, in contrast to vinum, objects that are not properly  named
	     in  the  description-file	will  not be created when the -f flag is
	     given.

     detach [-f] [plex | subdisk]
	     Detach a plex or subdisk from the volume or plex to which it is at-
	     tached.

     grow plex device
	     Grow a plex by creating a gvinum drive and subdisk  on  device  and
	     attach  it  to  the plex.	If required by the plex organization, it
	     will be put into the growable state.

     help    Provides a synopsis of gvinum commands and arguments.

     l | list [-rvV] [volume | plex | subdisk]

     ld [-rvV] [drive ...]

     ls [-rvV] [subdisk ...]

     lp [-rvV] [plex ...]

     lv [-rvV] [volume ...]
	     List information about the relevant object(s).  The  -r  flag  pro-
	     vides  recursive display, showing each object's subordinate objects
	     in proper relation.  The -v and -V flags provide progressively more
	     detailed output.

     mirror [-fsv] [-n name] drives
	     Create a mirrored volume from the specified drives.  It requires at
	     least a multiple of 2 drives.  If no name is  specified,  a  unique
	     name will be set by gvinum.  If the -s flag is specified, a striped
	     mirror will be created, and thus requires a multiple of 4 drives.

     move | mv -f drive subdisk [...]
	     Move  the	subdisk(s)  to	the specified drive.  The -f flag is re-
	     quired, as all data on the indicated subdisk(s) will  be  destroyed
	     as part of the move.  This can currently only be done when the sub-
	     disk is not being accessed.

	     If a single subdisk is moved, and it forms a part of a RAID-5 plex,
	     the  moved  subdisks  will need to be set to the "stale" state, and
	     the plex will require a start command.  If multiple  subdisk(s)  is
	     moved,  and form part of a RAID-5 plex, the moved disk(s) will need
	     to  be  set  to  the  "up"  state	and  the  plex	will  require  a
	     rebuildparity  command.  If the subdisk(s) form part of a plex that
	     is mirrored with other plexes, the plex will require restarting and
	     will sync once restarted.	Moving more than one subdisk in a RAID-5
	     plex or subdisks from both sides of a mirrored plex volume will de-
	     stroy data.  Note that parity rebuilds and syncing must be  started
	     manually after a move.

     printconfig
	     Write a copy of the current configuration to standard output.

     quit    Exit  gvinum when running in interactive mode.  Normally this would
	     be done by entering the EOF character.

     raid5 [-fv] [-s stripesize] [-n name] drives
	     Create a RAID-5 volume from the specified drives.	If  no	name  is
	     specified,a  unique  name	will be set by gvinum. This organization
	     requires at least three drives.

     rename [-r] drive | subdisk | plex | volume newname
	     Change the name of the specified object.  The -r flag  will  recur-
	     sively rename subordinate objects.

	     Note  that  device  nodes	will  not  be  renamed	until  gvinum is
	     restarted.

     rebuildparity [-f] plex
	     Rebuild the parity blocks of a RAID-5  plex.   The  parity  rebuild
	     will  start  at  the beginning of the plex if the -f flag is speci-
	     fied, or otherwise at the location of  the  parity  check	pointer.
	     All subdisks in the plex must be up for a parity check.

     resetconfig
	     Reset the complete gvinum configuration.

     rm [-r] volume | plex | subdisk
	     Remove an object and, if -r is specified, its subordinate objects.

     saveconfig
	     Save gvinum configuration to disk after configuration failures.

     setstate [-f] state volume | plex | subdisk | drive
	     Set  state  without  influencing other objects, for diagnostic pur-
	     poses only.  The -f flag forces state changes regardless of whether
	     they are legal.

     start   Read configuration from all vinum drives.

     start [-S size] volume | plex | subdisk
	     Allow the system to access the objects.  If necessary, plexes  will
	     be  synced and rebuilt.  If a subdisk was added to a running RAID-5
	     or striped plex, gvinum will expand into this subdisk and grow  the
	     whole  RAID-5  array.   This  can	be  done without unmounting your
	     filesystem.  The -S flag is currently ignored.

     stop [-f] [volume | plex | subdisk]
	     Terminate access to the objects, or stop gvinum  if  no  parameters
	     are specified.

     stripe [-fv] [-n name] drives
	     Create  a	striped  volume from the specified drives. If no name is
	     specified, a unique name will be set by Ic gvinum.  This  organiza-
	     tion requires at least two drives.

DESCRIPTION
     The  gvinum  utility  communicates  with the kernel component of the GVinum
     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,  gvinum
     maintains a command line history.

OPTIONS
     The gvinum commands may be followed by an option.

     -f      The -f ("force") option overrides safety checks.  It should be used
	     with  extreme caution.  This option is required in order to use the
	     move command.

     -r      The -r ("recursive") option applies the command recursively to sub-
	     ordinate objects.	For example, in conjunction with the lv command,
	     the -r option will also show information about the plexes and  sub-
	     disks  belonging to the volume.  It is also used by the rename com-
	     mand to indicate that subordinate objects such as	subdisks  should
	     be  renamed  to match the object(s) specified and by the rm command
	     to delete plexes belonging to a volume and so on.

     -v      The -v ("verbose") option provides more detailed output.

     -V      The -V ("very verbose") option provides even more	detailed  output
	     than -v.

ENVIRONMENT
     EDITOR  The  name	of the editor to use for editing configuration files, by
	     default vi(1) is invoked.

FILES
     /dev/gvinum       directory with device nodes for gvinum objects

EXAMPLES
     To create a mirror on disks /dev/ad1 and  /dev/ad2,  create  a  filesystem,
     mount, unmount and then stop Ic gvinum:

	   gvinum mirror /dev/ad1 /dev/ad2
	   newfs /dev/gvinum/gvinumvolume0
	   mount /dev/gvinum/gvinumvolume0 /mnt
	   ...
	   unmount /mnt
	   gvinum stop

     To create a striped mirror on disks /dev/ad1 /dev/ad2 /dev/ad3 and /dev/ad4
     named "data" and create a filesystem:

	   gvinum mirror -s -n data /dev/ad1 /dev/ad2 /dev/ad3 /dev/ad4
	   newfs /dev/gvinum/data

     To  create  a  raid5  array  on  disks /dev/ad1 /dev/ad2 and /dev/ad3, with
     stripesize 493k you can use the raid5 command:

	   gvinum raid5 -s 493k /dev/ad1 /dev/ad2 /dev/ad3

     Then the volume will be created automatically.   Afterwards,  you	have  to
     initialize the volume:

	   gvinum start myraid5vol

     The  initialization  will	start,	and the states will be updated when it's
     finished.	The list command will give you information about its progress.

     Imagine that one of the drives fails, and the output of 'printconfig' looks
     something like this:

	   drive gvinumdrive1 device /dev/ad2
	   drive gvinumdrive2 device /dev/???
	   drive gvinumdrive0 device /dev/ad1
	   volume myraid5vol
	   plex name myraid5vol.p0 org raid5 986s vol myraid5vol
	   sd name myraid5vol.p0.s2 drive gvinumdrive2	len  32538s  driveoffset
	   265s
	   plex myraid5vol.p0 plexoffset 1972s
	   sd  name  myraid5vol.p0.s1  drive gvinumdrive1 len 32538s driveoffset
	   265s
	   plex myraid5vol.p0 plexoffset 986s
	   sd name myraid5vol.p0.s0 drive gvinumdrive0	len  32538s  driveoffset
	   265s
	   plex myraid5vol.p0 plexoffset 0s

     Create a new drive with this configuration:

	   drive gdrive4 device /dev/ad4

     Then move the stale subdisk to the new drive:

	   gvinum move gdrive4 myraid5vol.p0.s2

     Then, initiate the rebuild:

	   gvinum start myraid5vol.p0

     The  plex will go up form degraded mode after the rebuild is finished.  The
     plex can still be used while the rebuild is in progress, although	requests
     might be delayed.

     Given  the  configuration	as  in the previous example, growing a RAID-5 or
     STRIPED array is accomplished by using the grow command:

	   gvinum grow myraid5vol.p0 /dev/ad4

     If everything went ok, the plex state should now be set to  growable.   You
     can then start the growing with the start command:

	   gvinum start myraid5vol.p0

     As with rebuilding, you can watch the progress using the list command.

     For  a more advanced usage and detailed explanation of gvinum, the handbook
     is recommended.

SEE ALSO
     geom(4), geom(8)

HISTORY
     The gvinum utility first appeared in FreeBSD 5.3.	The  vinum  utility,  on
     which gvinum is based, was written by Greg Lehey.

     The gvinum utility was written by Lukas Ertl.  The move and rename commands
     and  documentation were added by Chris Jones through the 2005 Google Summer
     of Code program.  a partial rewrite of gvinum was done by	Lukas  Ertl  and
     Ulf  Lilleengen  through the 2007 Google Summer of Code program.  The docu-
     mentation have been updated to reflect the new functionality.

AUTHORS
     Lukas Ertl <le@FreeBSD.org>
     Chris Jones <soc-cjones@FreeBSD.org>
     Ulf Lilleengen <lulf@FreeBSD.org>

BUGS
     Currently, gvinum does not rename devices in /dev/gvinum until reloaded.

     The -S initsize flag to start is ignored.

     Moving subdisks that are not part of a mirrored or RAID-5 volume  will  de-
     stroy data.  It is perhaps a bug to permit this.

     Plexes  in  which subdisks have been moved do not automatically sync or re-
     build parity.  This may leave data unprotected and is perhaps unwise.

     Currently, gvinum does not yet fully implement all of the	functions  found
     in  vinum(4).   Specifically,  the following commands from vinum(4) are not
     supported:

     debug   Cause the volume manager to enter the kernel debugger.

     debug flags
	     Set debugging flags.

     dumpconfig [drive ...]
	     List the configuration information stored on the specified  drives,
	     or all drives in the system if no drive names are specified.

     info [-vV]
	     List information about volume manager state.

     label volume
	     Create a volume label.

     resetstats [-r] [volume | plex | subdisk]
	     Reset statistics counters for the specified objects, or for all ob-
	     jects if none are specified.

     setdaemon [value]
	     Set daemon configuration.

FreeBSD 8.0			 April 10, 2009 		       GVINUM(8)
home | help