2b67c28a09
* Better wording of sections dealing with physical storage * A new section on assumptions gvirstor has on its consumer devices (components) and its interaction with file systems * Improved markup (by hrs@) Reviewed by: hrs Approved by: gnn (mentor)
284 lines
7.7 KiB
Groff
284 lines
7.7 KiB
Groff
.\" Copyright (c) 2006-2008 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 December 17, 2008
|
|
.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 virtual storage device of arbitrary
|
|
large size
|
|
.Pq for example, several TB ,
|
|
consisting of an arbitrary number of physical storage devices with the
|
|
total size which is equal to or smaller than the virtual size. Data
|
|
for the virtual devices will be allocated from physical devices on
|
|
demand. The idea behind
|
|
.Nm
|
|
is similar to the concept of Virtual Memory in operating systems,
|
|
effectively allowing users to overcommit on storage
|
|
.Pq free file system space .
|
|
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
|
|
.Fl s Ar virsize
|
|
is the size of new virtual device, with default being 2 TiB
|
|
.Pq 2097152 MiB .
|
|
Argument
|
|
.Fl m Ar chunksize
|
|
is the chunk size, with default being 4 MiB
|
|
.Pq 4096 KiB .
|
|
The default is thus
|
|
.Qq Fl s Ar 2097152 Fl m Ar 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
|
|
.Pq i.e. module loaded, device present in Pa /dev .
|
|
This action can be safely performed while the virstor device is in use
|
|
.Pq Qo hot Qc operation
|
|
.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
|
|
The
|
|
.Nm
|
|
utility exits 0 on success, and 1 if an error occurs.
|
|
.Sh EXAMPLES
|
|
The following example shows how to create a virtual device of default size
|
|
.Pq 2 TiB ,
|
|
of default chunk
|
|
.Pq extent
|
|
size
|
|
.Pq 4 MiB ,
|
|
with two physical devices for backing storage.
|
|
.Bd -literal -offset indent
|
|
.No gvirstor label -v Ar mydata Ar /dev/ad4 Ar /dev/ad6
|
|
.No newfs Ar /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 / component to an active virstor device:
|
|
.Bd -literal -offset indent
|
|
.No gvirstor add Ar mydata Ar ad8
|
|
.Ed
|
|
.Pp
|
|
This will add physical storage
|
|
.Ar ad8
|
|
to
|
|
.Pa /dev/virstor/mydata
|
|
device.
|
|
To see device status information
|
|
.Pq 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
|
|
.Pq e.g. Cm status , Cm help
|
|
are also supported.
|
|
.Sh SYSCTL VARIABLES
|
|
.Nm
|
|
has several
|
|
.Xr sysctl 8
|
|
tunable variables.
|
|
.Bd -literal -offset indent
|
|
.Va 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 suppressed. Default value is 5 and it's not
|
|
recommended 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
|
|
.Va 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
|
|
.Pq default 100 .
|
|
.Bd -literal -offset indent
|
|
.Va int kern.geom.virstor.component_watermark
|
|
.Ed
|
|
.Pp
|
|
Value in this sysctl sets warning watermark level for component usage.
|
|
The warning is issued when there are less than this many unallocated
|
|
components
|
|
.Pq default is 1 .
|
|
.Pp
|
|
All these sysctls are also available as
|
|
.Xr loader 8
|
|
tunables.
|
|
.Sh DIAGNOSTICS
|
|
.Nm
|
|
kernel module issues log messages with prefixes in standardized format,
|
|
which is useful for log message filtering and dispatching. Each message
|
|
line begins with
|
|
.Bd -literal -offset indent
|
|
.Li GEOM_VIRSTOR[%d]:
|
|
.Ed
|
|
.Pp
|
|
The number
|
|
.Pq %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
|
|
.Pq 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
|
|
.Cm add
|
|
and
|
|
.Cm remove
|
|
contain unavoidable critical sections which may make the virstor
|
|
device unusable if a power failure
|
|
.Pq or other disruptive event
|
|
happens during their execution. It's recommended to run them when the
|
|
system is quiescent.
|
|
.Sh ASSUMPTIONS AND INTERACTION WITH FILE SYSTEMS
|
|
There are several assumptions that
|
|
.Nm
|
|
has in its operation: that the size of the virtual storage device will not
|
|
change once it's set, and that the sizes of individual physical storage
|
|
components will always remain constant during their existence. For
|
|
alternative ways to implement virtual or resizable file systems see
|
|
.Xr zfs 1M ,
|
|
.Xr gconcat 8 and
|
|
.Xr growfs 8 .
|
|
.Pp
|
|
Note that
|
|
.Nm
|
|
has nontrivial interaction with file systems which initialize a large
|
|
number of on-disk structures during newfs. If such file systems
|
|
attempt to spread their structures across the drive media
|
|
.Pq like UFS/UFS2 does ,
|
|
their efforts will be effectively foiled by sequential allocation of
|
|
chunks in
|
|
.Nm
|
|
and all their structures will be physically allocated at the start
|
|
of the first virstor component. This could have a significant impac
|
|
t on file system performance
|
|
.Pq which can in some rare cases be even positive .
|
|
.Sh AUTHOR
|
|
.An Ivan Voras Aq ivoras@FreeBSD.org
|
|
.Pp
|
|
Sponsored by Google Summer of Code 2006
|