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)
This commit is contained in:
Ivan Voras
parent
90886ebcc2
commit
2b67c28a09
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=186735
@ -1,5 +1,4 @@
|
||||
.\" Copyright (c) 2005 Pawel Jakub Dawidek <pjd@FreeBSD.org>
|
||||
.\" Copyright (c) 2005 Ivan Voras <ivoras@FreeBSD.org>
|
||||
.\" Copyright (c) 2006-2008 Ivan Voras <ivoras@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 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).
|
||||
.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 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).
|
||||
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@FreeBSD.org
|
||||
.An Ivan Voras Aq ivoras@FreeBSD.org
|
||||
.Pp
|
||||
Sponsored by Google Summer of Code 2006
|
||||
|
||||
Loading…
Reference in New Issue
Block a user