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

NAME
     gvirstor -- provides virtual data storage geom

SYNOPSIS
     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

DESCRIPTION
     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  speci-
	      fied name.  Metadata are stored in the last sector of every compo-
	      nent.   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 default 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
     Exit status is 0 on success, and 1 if the command fails.

EXAMPLES
     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-
     ported.

SYSCTLs
     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  su-
     pressed. Default value is 5 and it's not recommented to set this tunable to
     less  than  2,  because level 1 messages are error events, and level 2 mes-
     sages are system warnings.

	   int kern.geom.virstor.chunk_watermark

     Value in this sysctl sets warning watermark level for physical chunk  usage
     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  components
     (default is 1).

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

LOG MESSAGES
     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

	   GEOM_VIRSTOR[%d]:

     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 seriously (for
     example, to catch out-of-space conditions as set by watermark sysctls).

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

HISTORY
     The gvirstor utility appeared in FreeBSD 7.0.

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

AUTHOR
     Ivan Voras <ivoras@FreeBSD.org> Sponsored by Google Summer of Code 2006

FreeBSD 7.0			  July 8, 2006			     GVIRSTOR(8)
home | help