From owner-svn-src-all@FreeBSD.ORG Sun Jan 4 15:41:02 2009 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 1F5161065670; Sun, 4 Jan 2009 15:41:02 +0000 (UTC) (envelope-from danger@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 0CAF98FC19; Sun, 4 Jan 2009 15:41:02 +0000 (UTC) (envelope-from danger@FreeBSD.org) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.3/8.14.3) with ESMTP id n04Ff1Jq060754; Sun, 4 Jan 2009 15:41:01 GMT (envelope-from danger@svn.freebsd.org) Received: (from danger@localhost) by svn.freebsd.org (8.14.3/8.14.3/Submit) id n04Ff1Oh060753; Sun, 4 Jan 2009 15:41:01 GMT (envelope-from danger@svn.freebsd.org) Message-Id: <200901041541.n04Ff1Oh060753@svn.freebsd.org> From: Daniel Gerzo Date: Sun, 4 Jan 2009 15:41:01 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cc: Subject: svn commit: r186737 - head/sbin/geom/class/virstor X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 04 Jan 2009 15:41:02 -0000 Author: danger (doc committer) Date: Sun Jan 4 15:41:01 2009 New Revision: 186737 URL: http://svn.freebsd.org/changeset/base/186737 Log: - 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 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 12:18:18 2009 (r186736) +++ head/sbin/geom/class/virstor/gvirstor.8 Sun Jan 4 15:41:01 2009 (r186737) @@ -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 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 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 .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 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.