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

FreeBSD Manual Pages


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

     gvirstor -- provides virtual data storage geom

     gvirstor label [-hv] [-s virsize] [-m chunksize] name prov	...
     gvirstor stop [-fv] name ...
     gvirstor add [-vh]	name prov ...
     gvirstor remove [-v] name prov ...
     gvirstor clear [-v] prov ...
     gvirstor dump prov	...
     gvirstor list
     gvirstor status
     gvirstor load
     gvirstor unload

     The gvirstor utility is used for setting up a storage device of arbitrary
     large size	(for example, several TB), consisting of an arbitrary number
     of	physical storage devices with total size <= the	virtual	size. Data for
     the virtual devices will be allocated from	physical devices on demand. In
     short, this is the	virtual	storage	functionality.	The first argument to
     gvirstor indicates	an action to be	performed:

     label    Set up a virtual device from the given components	with the spec-
	      ified name.  Metadata are	stored in the last sector of every
	      component.  Argument virsize is the size of new virtual device,
	      with default being 2 TiB (2097152	MiB).  Argument	chunksize is
	      the chunk	size, with default being 4 MiB (4096 KiB).  The	de-
	      fault is thus "-s	2097152	-m 4096".

     stop     Turn off an existing virtual device by its name.	This command
	      does not touch on-disk metadata.	As with	other GEOM classes,
	      stopped geoms cannot be started manually.

     add      Adds new components to existing virtual device by	its name.  The
	      specified	virstor	device must exist and be active	(i.e.  module
	      loaded, device present in	/dev).

     remove   Removes components from existing virtual device by its name.
	      Only unallocated providers can be	removed.

     clear    Clear metadata on	the given providers.

     dump     Dump metadata stored on the given	providers.

     list     See geom(8).

     status   See geom(8).

     load     See geom(8).

     unload   See geom(8).

     Additional	options:

     -f	 Force the removal of the specified virtual device.

     -h	 Hardcode providers' names in metadata.

     -v	 Be more verbose.

     Exit status is 0 on success, and 1	if the command fails.

     The following example shows how to	create a virtual device	of default
     size (2 TiB), of default chunk (extent) size (4 MiB), with	two physical
     devices for backing storage.

	   gvirstor label -v mydata /dev/ad4 /dev/ad6
	   newfs /dev/virstor/mydata

     From now on, the virtual device will be available via the
     /dev/virstor/mydata device	entry.	To add a new physical device /
     provider to an active virstor device:

	   gvirstor add	mydata ad8

     This will add physical storage (from ad8) to /dev/virstor/mydata device.
     To	see device status information (including how much physical storage is
     still available for the virtual device), use:

	   gvirstor list

     All standard geom(8) subcommands (e.g. "status", "help") are also sup-

     gvirstor has several sysctl(8) tunable variables.

	   int kern.geom.virstor.debug

     This sysctl controls verbosity of the kernel module, in the range 1 to
     15. Messages that are marked with higher verbosity	levels than this are
     supressed.	Default	value is 5 and it's not	recommented to set this	tun-
     able to less than 2, because level	1 messages are error events, and level
     2 messages	are system warnings.

	   int kern.geom.virstor.chunk_watermark

     Value in this sysctl sets warning watermark level for physical chunk us-
     age on a single component.	The warning is issued when a virstor component
     has less than this	many free chunks (default 100).

	   int kern.geom.virstor.component_watermark

     Value in this sysctl sets warning watermark level for component usage.
     The warning is issed when there are less than this	many unallocated com-
     ponents (default is 1).

     All these sysctls are also	available as loader(8) tunables.

     gvirstor kernel module issues log messages	with prefixes in standardised
     format, which is useful for log message filtering and dispatching.	Each
     message line begins with


     The number	(%d) is	message	verbosity / importance level, in the range 1
     to	15. If a message filtering, dispatching	or operator alert system is
     used, it is recommended that messages with	levels 1 and 2 be taken	seri-
     ously (for	example, to catch out-of-space conditions as set by watermark

     geom(4), geom(8), newfs(8), fstab(5), glabel(8)

     The gvirstor utility appeared in FreeBSD 7.0.

     Commands "add" and	"remove" contain unavoidable critical sections which
     may make the virstor device unusable if a power failure (or other disrup-
     tive event) happens during	their execution.  It's recommended to run them
     when the system is	quiescent.

     Ivan Voras	<> Sponsored by Google Summer	of Code	2006

BSD				 July 8, 2006				   BSD


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

home | help