svn commit: r186735 - head/sbin/geom/class/virstor
Ivan Voras
ivoras at FreeBSD.org
Sun Jan 4 03:31:04 PST 2009
Author: ivoras
Date: Sun Jan 4 11:31:03 2009
New Revision: 186735
URL: http://svn.freebsd.org/changeset/base/186735
Log:
Several significant updates:
* 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)
Modified:
head/sbin/geom/class/virstor/gvirstor.8
Modified: head/sbin/geom/class/virstor/gvirstor.8
==============================================================================
--- head/sbin/geom/class/virstor/gvirstor.8 Sun Jan 4 07:33:10 2009 (r186734)
+++ head/sbin/geom/class/virstor/gvirstor.8 Sun Jan 4 11:31:03 2009 (r186735)
@@ -1,5 +1,4 @@
-.\" Copyright (c) 2005 Pawel Jakub Dawidek <pjd at FreeBSD.org>
-.\" Copyright (c) 2005 Ivan Voras <ivoras at FreeBSD.org>
+.\" Copyright (c) 2006-2008 Ivan Voras <ivoras at FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
@@ -25,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd July 8, 2006
+.Dd December 17, 2008
.Dt GVIRSTOR 8
.Os
.Sh NAME
@@ -69,10 +68,17 @@
.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.
+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:
@@ -82,12 +88,15 @@ Set up a virtual device from the given c
.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).
+.Fl s Ar virsize
+is the size of new virtual device, with default being 2 TiB
+.Pq 2097152 MiB .
Argument
-.Ar chunksize
-is the chunk size, with default being 4 MiB (4096 KiB).
-The default is thus "-s 2097152 -m 4096".
+.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 .
@@ -96,8 +105,10 @@ As with other GEOM classes, stopped geom
.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).
+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 .
@@ -130,82 +141,97 @@ Hardcode providers' names in metadata.
Be more verbose.
.El
.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
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.
+.Pq 2 TiB ,
+of default chunk
+.Pq extent
+size
+.Pq 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
+.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 / provider to an active virstor device:
+To add a new physical device / component to an active virstor device:
.Bd -literal -offset indent
-gvirstor add mydata ad8
+.No gvirstor add Ar mydata Ar ad8
.Ed
.Pp
-This will add physical storage (from ad8) to
+This will add physical storage
+.Ar 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:
+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 (e.g. "status", "help") are also supported.
-.Sh SYSCTLs
+subcommands
+.Pq e.g. Cm status , Cm help
+are also supported.
+.Sh SYSCTL VARIABLES
.Nm
-has several
+has several
.Xr sysctl 8
tunable variables.
.Bd -literal -offset indent
-.Pa int kern.geom.virstor.debug
+.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 supressed. Default value is 5 and it's not
-recommented to set this tunable to less than 2, because level 1 messages
+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
-.Pa int kern.geom.virstor.chunk_watermark
+.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 (default 100).
+has less than this many free chunks
+.Pq default 100 .
.Bd -literal -offset indent
-.Pa int kern.geom.virstor.component_watermark
+.Va 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).
+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 LOG MESSAGES
+.Sh DIAGNOSTICS
.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
line begins with
.Bd -literal -offset indent
-.Pa GEOM_VIRSTOR[%d]:
+.Li 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).
+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 ,
@@ -218,10 +244,40 @@ The
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.
+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 at FreeBSD.org
+.An Ivan Voras Aq ivoras at FreeBSD.org
+.Pp
Sponsored by Google Summer of Code 2006
More information about the svn-src-all
mailing list