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:
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) 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
|
||||||
|
Loading…
Reference in New Issue
Block a user