d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Several significant updates:

Browse Source 
* 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)
This commit is contained in:
Ivan Voras 2009-01-04 11:31:03 +00:00
parent 90886ebcc2
commit 2b67c28a09
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=186735
1 changed files with 105 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
sbin/geom/class/virstor/gvirstor.8
View File

@ -1,5 +1,4 @@
.\" Copyright (c) 2005 Pawel Jakub Dawidek <pjd@FreeBSD.org> .\" Copyright (c) 2006-2008 Ivan Voras <ivoras@FreeBSD.org>
.\" Copyright (c) 2005 Ivan Voras <ivoras@FreeBSD.org>
.\" All rights reserved. .\" All rights reserved.
.\" .\"
.\" Redistribution and use in source and binary forms, with or without .\" Redistribution and use in source and binary forms, with or without
@ -25,7 +24,7 @@
.\" .\"
.\" $FreeBSD$ .\" $FreeBSD$
.\" .\"
.Dd July 8, 2006 .Dd December 17, 2008
.Dt GVIRSTOR 8 .Dt GVIRSTOR 8
.Os .Os
.Sh NAME .Sh NAME
@ -69,10 +68,17 @@
.Sh DESCRIPTION .Sh DESCRIPTION
The The
.Nm .Nm
utility is used for setting up a storage device of arbitrary large size (for example, utility is used for setting up a virtual storage device of arbitrary
several TB), consisting of an arbitrary number of physical storage devices with large size
total size <= the virtual size. Data for the virtual devices will be allocated from .Pq for example, several TB ,
physical devices on demand. In short, this is the virtual storage functionality. 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 The first argument to
.Nm .Nm
indicates an action to be performed: indicates an action to be performed:
@ -82,12 +88,15 @@ Set up a virtual device from the given components with the specified
.Ar name . .Ar name .
Metadata are stored in the last sector of every component. Metadata are stored in the last sector of every component.
Argument Argument
.Ar virsize .Fl s Ar virsize
is the size of new virtual device, with default being 2 TiB (2097152 MiB). is the size of new virtual device, with default being 2 TiB
.Pq 2097152 MiB .
Argument Argument
.Ar chunksize .Fl m Ar chunksize
is the chunk size, with default being 4 MiB (4096 KiB). is the chunk size, with default being 4 MiB
The default is thus "-s 2097152 -m 4096". .Pq 4096 KiB .
The default is thus
.Qq Fl s Ar 2097152 Fl m Ar 4096 .
.It Cm stop .It Cm stop
Turn off an existing virtual device by its Turn off an existing virtual device by its
.Ar name . .Ar name .
@ -96,8 +105,10 @@ As with other GEOM classes, stopped geoms cannot be started manually.
.It Cm add .It Cm add
Adds new components to existing virtual device by its Adds new components to existing virtual device by its
.Ar name . .Ar name .
The specified virstor device must exist and be active (i.e. The specified virstor device must exist and be active
module loaded, device present in /dev). .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 .It Cm remove
Removes components from existing virtual device by its Removes components from existing virtual device by its
.Ar name . .Ar name .
@ -130,82 +141,97 @@ Hardcode providers' names in metadata.
Be more verbose. Be more verbose.
.El .El
.Sh EXIT STATUS .Sh EXIT STATUS
Exit status is 0 on success, and 1 if the command fails. The
.Nm
utility exits 0 on success, and 1 if an error occurs.
.Sh EXAMPLES .Sh EXAMPLES
The following example shows how to create a virtual device of default size 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 .Pq 2 TiB ,
backing storage. of default chunk
.Pq extent
size
.Pq 4 MiB ,
with two physical devices for backing storage.
.Bd -literal -offset indent .Bd -literal -offset indent
gvirstor label -v mydata /dev/ad4 /dev/ad6 .No gvirstor label -v Ar mydata Ar /dev/ad4 Ar /dev/ad6
newfs /dev/virstor/mydata .No newfs Ar /dev/virstor/mydata
.Ed .Ed
.Pp .Pp
From now on, the virtual device will be available via the From now on, the virtual device will be available via the
.Pa /dev/virstor/mydata .Pa /dev/virstor/mydata
device entry. device entry.
To add a new physical device / provider to an active virstor device: To add a new physical device / component to an active virstor device:
.Bd -literal -offset indent .Bd -literal -offset indent
gvirstor add mydata ad8 .No gvirstor add Ar mydata Ar ad8
.Ed .Ed
.Pp .Pp
This will add physical storage (from ad8) to This will add physical storage
.Ar ad8
to
.Pa /dev/virstor/mydata .Pa /dev/virstor/mydata
device. device.
To see device status information (including how much physical storage To see device status information
is still available for the virtual device), use: .Pq including how much physical storage is still available for the virtual device ,
use:
.Bd -literal -offset indent .Bd -literal -offset indent
gvirstor list gvirstor list
.Ed .Ed
.Pp .Pp
All standard All standard
.Xr geom 8 .Xr geom 8
subcommands (e.g. "status", "help") are also supported. subcommands
.Sh SYSCTLs .Pq e.g. Cm status , Cm help
are also supported.
.Sh SYSCTL VARIABLES
.Nm .Nm
has several has several
.Xr sysctl 8 .Xr sysctl 8
tunable variables. tunable variables.
.Bd -literal -offset indent .Bd -literal -offset indent
.Pa int kern.geom.virstor.debug .Va int kern.geom.virstor.debug
.Ed .Ed
.Pp .Pp
This sysctl controls verbosity of the kernel module, in the range This sysctl controls verbosity of the kernel module, in the range
1 to 15. Messages that are marked with higher verbosity levels than 1 to 15. Messages that are marked with higher verbosity levels than
this are supressed. Default value is 5 and it's not this are suppressed. Default value is 5 and it's not
recommented to set this tunable to less than 2, because level 1 messages recommended to set this tunable to less than 2, because level 1 messages
are error events, and level 2 messages are system warnings. are error events, and level 2 messages are system warnings.
.Bd -literal -offset indent .Bd -literal -offset indent
.Pa int kern.geom.virstor.chunk_watermark .Va int kern.geom.virstor.chunk_watermark
.Ed .Ed
.Pp .Pp
Value in this sysctl sets warning watermark level for physical chunk usage Value in this sysctl sets warning watermark level for physical chunk usage
on a single component. The warning is issued when a virstor component on a single component. The warning is issued when a virstor component
has less than this many free chunks (default 100). has less than this many free chunks
.Pq default 100 .
.Bd -literal -offset indent .Bd -literal -offset indent
.Pa int kern.geom.virstor.component_watermark .Va int kern.geom.virstor.component_watermark
.Ed .Ed
.Pp .Pp
Value in this sysctl sets warning watermark level for component usage. Value in this sysctl sets warning watermark level for component usage.
The warning is issed when there are less than this many unallocated The warning is issued when there are less than this many unallocated
components (default is 1). components
.Pq default is 1 .
.Pp .Pp
All these sysctls are also available as All these sysctls are also available as
.Xr loader 8 .Xr loader 8
tunables. tunables.
.Sh LOG MESSAGES .Sh DIAGNOSTICS
.Nm .Nm
kernel module issues log messages with prefixes in standardised format, kernel module issues log messages with prefixes in standardized format,
which is useful for log message filtering and dispatching. Each message which is useful for log message filtering and dispatching. Each message
line begins with line begins with
.Bd -literal -offset indent .Bd -literal -offset indent
.Pa GEOM_VIRSTOR[%d]: .Li GEOM_VIRSTOR[%d]:
.Ed .Ed
.Pp .Pp
The number (%d) is message verbosity / importance level, in the range The number
1 to 15. If a message filtering, dispatching or operator alert system is .Pq %d
used, it is recommended that messages with levels 1 and 2 be taken is message verbosity / importance level, in the range 1 to 15. If a
seriously (for example, to catch out-of-space conditions as set by message filtering, dispatching or operator alert system is used, it is
watermark sysctls). 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 .Sh SEE ALSO
.Xr geom 4 , .Xr geom 4 ,
.Xr geom 8 , .Xr geom 8 ,
@ -218,10 +244,40 @@ The
utility appeared in utility appeared in
.Fx 7.0 . .Fx 7.0 .
.Sh BUGS .Sh BUGS
Commands "add" and "remove" contain unavoidable critical sections Commands
which may make the virstor device unusable if a power failure (or .Cm add
other disruptive event) happens during their execution. and
It's recommended to run them when the system is quiescent. .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 .Sh AUTHOR
.An Ivan Voras Aq ivoras@FreeBSD.org .An Ivan Voras Aq ivoras@FreeBSD.org
.Pp
Sponsored by Google Summer of Code 2006 Sponsored by Google Summer of Code 2006