- grammar and language fixes
- hard sentence breaks - trim EXIT STATUS section and move it to DIAGNOSTICS as well as use .Er macro - sort SEE ALSO MFC after: 7 days
This commit is contained in:
parent
eb76156548
commit
c419baec28
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=186737
@ -29,7 +29,7 @@
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm gvirstor
|
||||
.Nd "provides virtual data storage geom"
|
||||
.Nd "control utility for virtual data storage devices"
|
||||
.Sh SYNOPSIS
|
||||
.Nm
|
||||
.Cm label
|
||||
@ -72,9 +72,10 @@ 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
|
||||
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
|
||||
@ -82,35 +83,35 @@ effectively allowing users to overcommit on storage
|
||||
The first argument to
|
||||
.Nm
|
||||
indicates an action to be performed:
|
||||
.Bl -tag -width ".Cm destroy"
|
||||
.Bl -tag -width ".Cm remove"
|
||||
.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.
|
||||
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 2 TiB
|
||||
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 4 MiB
|
||||
is the chunk size, with default being set to 4 MiB
|
||||
.Pq 4096 KiB .
|
||||
The default is thus
|
||||
The default arguments are thus
|
||||
.Qq Fl s Ar 2097152 Fl m Ar 4096 .
|
||||
.It Cm stop
|
||||
Turn off an existing virtual device by its
|
||||
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 add
|
||||
Adds new components to existing virtual device by its
|
||||
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 by its
|
||||
Removes components from existing virtual device with the given
|
||||
.Ar name .
|
||||
Only unallocated providers can be removed.
|
||||
.It Cm clear
|
||||
@ -140,10 +141,6 @@ 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 ,
|
||||
@ -165,12 +162,13 @@ To add a new physical device / component to an active virstor device:
|
||||
.No gvirstor add Ar mydata Ar ad8
|
||||
.Ed
|
||||
.Pp
|
||||
This will add physical storage
|
||||
This will add physical storage of
|
||||
.Ar ad8
|
||||
to
|
||||
.Pa /dev/virstor/mydata
|
||||
device.
|
||||
To see device status information
|
||||
.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
|
||||
@ -192,17 +190,20 @@ tunable variables.
|
||||
.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.
|
||||
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
|
||||
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
|
||||
@ -217,31 +218,33 @@ 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
|
||||
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
|
||||
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 .
|
||||
sysctls.
|
||||
.Sh SEE ALSO
|
||||
.Xr geom 4 ,
|
||||
.Xr geom 8 ,
|
||||
.Xr newfs 8 ,
|
||||
.Xr fstab 5 ,
|
||||
.Xr glabel 8
|
||||
.Xr geom 8 ,
|
||||
.Xr glabel 8 ,
|
||||
.Xr newfs 8
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Nm
|
||||
utility appeared in
|
||||
utility first appeared in
|
||||
.Fx 7.0 .
|
||||
.Sh BUGS
|
||||
Commands
|
||||
@ -251,15 +254,15 @@ and
|
||||
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.
|
||||
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'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
|
||||
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 .
|
||||
@ -267,17 +270,18 @@ alternative ways to implement virtual or resizable file systems see
|
||||
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
|
||||
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
|
||||
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 .
|
||||
.Sh AUTHOR
|
||||
.An Ivan Voras Aq ivoras@FreeBSD.org
|
||||
.Pp
|
||||
Sponsored by Google Summer of Code 2006
|
||||
Sponsored by Google Summer of Code 2006.
|
||||
|
Loading…
Reference in New Issue
Block a user