e4b0a90e77
Rather then combining hardlink creation for the geom(8) binary with shared library build, move libraries to src/lib/geom so they are built and installed normally. Create a common Makefile.classes which is included by both lib/geom/Makefile and sbin/geom/Makefile so the symlink and libraries stay in sync. The relocation of libraries allows libraries to be build for 32-bit compat. This also reduces the number of non-standard builds in the system. This commit is not sufficent to run a 32-bit /sbin/geom on a 64-bit system out of the box as it will look in the wrong place for libraries unless GEOM_LIBRARY_PATH is set appropriatly in the environment. Reviewed by: bdrewery Sponsored by: DARPA, AFRL Differential Revision: https://reviews.freebsd.org/D15360
300 lines
7.9 KiB
Groff
300 lines
7.9 KiB
Groff
.\" Copyright (c) 2006-2011 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 October 1, 2013
|
|
.Dt GVIRSTOR 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm gvirstor
|
|
.Nd "control utility for virtual data storage devices"
|
|
.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 destroy
|
|
.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 concept is also known as "thin provisioning" in virtualization
|
|
environments, only here it is implemented on the level of physical storage
|
|
devices.
|
|
.Pp
|
|
The first argument to
|
|
.Nm
|
|
indicates an action to be performed:
|
|
.Bl -tag -width ".Cm remove"
|
|
.It Cm label
|
|
Set up a virtual device from the given components with the specified
|
|
.Ar name .
|
|
Metadata is stored in the last sector of every component.
|
|
Argument
|
|
.Fl s Ar virsize
|
|
is the size of new virtual device, with default being set to 2 TiB
|
|
.Pq 2097152 MiB .
|
|
Argument
|
|
.Fl m Ar chunksize
|
|
is the chunk size, with default being set to 4 MiB
|
|
.Pq 4096 KiB .
|
|
The default arguments are thus
|
|
.Qq Fl s Ar 2097152 Fl m Ar 4096 .
|
|
.It Cm stop
|
|
Turn off an existing virtual device with the given
|
|
.Ar name .
|
|
This command does not touch on-disk metadata.
|
|
As with other GEOM classes, stopped geoms cannot be started manually.
|
|
.It Cm destroy
|
|
Same as
|
|
.Cm stop.
|
|
.It Cm add
|
|
Adds new components to existing virtual device with the given
|
|
.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 with the given
|
|
.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 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/ada4 Ar /dev/ada6
|
|
.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 ada8
|
|
.Ed
|
|
.Pp
|
|
This will add physical storage of
|
|
.Ar ada8
|
|
to
|
|
.Pa /dev/virstor/mydata
|
|
device.
|
|
.Pp
|
|
To see the 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 is 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
|
|
.Ex -std
|
|
.Pp
|
|
.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 fstab 5 ,
|
|
.Xr geom 8 ,
|
|
.Xr glabel 8 ,
|
|
.Xr newfs 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility first appeared in
|
|
.Fx 7.0 .
|
|
.Sh AUTHORS
|
|
.An Ivan Voras Aq Mt ivoras@FreeBSD.org
|
|
.Pp
|
|
Sponsored by Google Summer of Code 2006.
|
|
.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 is 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 is 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 impact on file system performance
|
|
.Pq which can in some rare cases be even positive .
|