diff --git a/sbin/geom/class/virstor/gvirstor.8 b/sbin/geom/class/virstor/gvirstor.8 index 5807af925933..4b112094ec99 100644 --- a/sbin/geom/class/virstor/gvirstor.8 +++ b/sbin/geom/class/virstor/gvirstor.8 @@ -1,5 +1,4 @@ -.\" Copyright (c) 2005 Pawel Jakub Dawidek -.\" Copyright (c) 2005 Ivan Voras +.\" Copyright (c) 2006-2008 Ivan Voras .\" 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