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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
GVIRSTOR(8)             FreeBSD 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
                  specified 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 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 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

     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
     tunable 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
     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.

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

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

FreeBSD 11.0-PRERELEASE          July 8, 2006          FreeBSD 11.0-PRERELEASE


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

home | help