Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


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

     gvinum -- Logical Volume Manager control program

     gvinum [command] [-options]

     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 cur-
	     rent gvinum configuration for editing.  The -f flag will make gv-
	     inum ignore 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

     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	ob-
	     jects in proper relation.	The -v and -V flags provide progres-
	     sively 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
	     subdisk 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 mir-
	     rored plex	volume will destroy data.  Note	that parity rebuilds
	     and syncing must be started manually after	a move.

	     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

     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.

	     Reset the complete	gvinum configuration.

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

	     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.

     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.

     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
	     subordinate objects.  For example,	in conjunction with the	lv
	     command, the -r option will also show information about the
	     plexes and	subdisks belonging to the volume.  It is also used by
	     the rename	command	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

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

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

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

     /dev/gvinum       directory with device nodes for gvinum objects

     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
	   plex	myraid5vol.p0 plexoffset 1972s
	   sd name myraid5vol.p0.s1 drive gvinumdrive1 len 32538s driveoffset
	   plex	myraid5vol.p0 plexoffset 986s
	   sd name myraid5vol.p0.s0 drive gvinumdrive0 len 32538s driveoffset
	   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 re-
     quests 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 hand-
     book is recommended.

     geom(4), geom(8)

     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	com-
     mands 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 documentation have been updated to reflect the	new functionality.

     Lukas Ertl	<>
     Chris Jones <>
     Ulf Lilleengen <>

     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

     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 speci-

     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
	     objects if	none are specified.

     setdaemon [value]
	     Set daemon	configuration.

BSD				April 10, 2009				   BSD


Want to link to this manual page? Use this URL:

home | help