diff options
Diffstat (limited to 'sbin/geom/class/virstor/gvirstor.8')
-rw-r--r-- | sbin/geom/class/virstor/gvirstor.8 | 227 |
1 files changed, 227 insertions, 0 deletions
diff --git a/sbin/geom/class/virstor/gvirstor.8 b/sbin/geom/class/virstor/gvirstor.8 new file mode 100644 index 0000000..5807af9 --- /dev/null +++ b/sbin/geom/class/virstor/gvirstor.8 @@ -0,0 +1,227 @@ +.\" Copyright (c) 2005 Pawel Jakub Dawidek <pjd@FreeBSD.org> +.\" Copyright (c) 2005 Ivan Voras <ivoras@FreeBSD.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 8, 2006 +.Dt GVIRSTOR 8 +.Os +.Sh NAME +.Nm gvirstor +.Nd "provides virtual data storage geom" +.Sh SYNOPSIS +.Nm +.Cm label +.Op Fl hv +.Op Fl s Ar virsize +.Op Fl m Ar chunksize +.Ar name +.Ar prov ... +.Nm +.Cm stop +.Op Fl fv +.Ar name ... +.Nm +.Cm add +.Op Fl vh +.Ar name prov ... +.Nm +.Cm remove +.Op Fl v +.Ar name prov ... +.Nm +.Cm clear +.Op Fl v +.Ar prov ... +.Nm +.Cm dump +.Ar prov ... +.Nm +.Cm list +.Nm +.Cm status +.Nm +.Cm load +.Nm +.Cm unload +.Sh DESCRIPTION +The +.Nm +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 +.Nm +indicates an action to be performed: +.Bl -tag -width ".Cm destroy" +.It Cm label +Set up a virtual device from the given components with the specified +.Ar name . +Metadata are stored in the last sector of every component. +Argument +.Ar virsize +is the size of new virtual device, with default being 2 TiB (2097152 MiB). +Argument +.Ar chunksize +is the chunk size, with default being 4 MiB (4096 KiB). +The default is thus "-s 2097152 -m 4096". +.It Cm stop +Turn off an existing virtual device by its +.Ar name . +This command does not touch on-disk metadata. +As with other GEOM classes, stopped geoms cannot be started manually. +.It Cm add +Adds new components to existing virtual device by its +.Ar name . +The specified virstor device must exist and be active (i.e. +module loaded, device present in /dev). +.It Cm remove +Removes components from existing virtual device by its +.Ar name . +Only unallocated providers can be removed. +.It Cm clear +Clear metadata on the given providers. +.It Cm dump +Dump metadata stored on the given providers. +.It Cm list +See +.Xr geom 8 . +.It Cm status +See +.Xr geom 8 . +.It Cm load +See +.Xr geom 8 . +.It Cm unload +See +.Xr geom 8 . +.El +.Pp +Additional options: +.Bl -tag -width ".Fl f" +.It Fl f +Force the removal of the specified virtual device. +.It Fl h +Hardcode providers' names in metadata. +.It Fl v +Be more verbose. +.El +.Sh EXIT STATUS +Exit status is 0 on success, and 1 if the command fails. +.Sh 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. +.Bd -literal -offset indent +gvirstor label -v mydata /dev/ad4 /dev/ad6 +newfs /dev/virstor/mydata +.Ed +.Pp +From now on, the virtual device will be available via the +.Pa /dev/virstor/mydata +device entry. +To add a new physical device / provider to an active virstor device: +.Bd -literal -offset indent +gvirstor add mydata ad8 +.Ed +.Pp +This will add physical storage (from ad8) to +.Pa /dev/virstor/mydata +device. +To see device status information (including how much physical storage +is still available for the virtual device), use: +.Bd -literal -offset indent +gvirstor list +.Ed +.Pp +All standard +.Xr geom 8 +subcommands (e.g. "status", "help") are also supported. +.Sh SYSCTLs +.Nm +has several +.Xr sysctl 8 +tunable variables. +.Bd -literal -offset indent +.Pa int kern.geom.virstor.debug +.Ed +.Pp +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. +.Bd -literal -offset indent +.Pa int kern.geom.virstor.chunk_watermark +.Ed +.Pp +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). +.Bd -literal -offset indent +.Pa int kern.geom.virstor.component_watermark +.Ed +.Pp +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). +.Pp +All these sysctls are also available as +.Xr loader 8 +tunables. +.Sh LOG MESSAGES +.Nm +kernel module issues log messages with prefixes in standardised format, +which is useful for log message filtering and dispatching. Each message +line begins with +.Bd -literal -offset indent +.Pa GEOM_VIRSTOR[%d]: +.Ed +.Pp +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). +.Sh SEE ALSO +.Xr geom 4 , +.Xr geom 8 , +.Xr newfs 8 , +.Xr fstab 5 , +.Xr glabel 8 +.Sh HISTORY +The +.Nm +utility appeared in +.Fx 7.0 . +.Sh 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. +.Sh AUTHOR +.An Ivan Voras Aq ivoras@FreeBSD.org +Sponsored by Google Summer of Code 2006 |