From owner-svn-src-head@FreeBSD.ORG Sun Jan 4 11:31:03 2009 Return-Path: Delivered-To: svn-src-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id D18521065672; Sun, 4 Jan 2009 11:31:03 +0000 (UTC) (envelope-from ivoras@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id BEB598FC08; Sun, 4 Jan 2009 11:31:03 +0000 (UTC) (envelope-from ivoras@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 n04BV36E056279; Sun, 4 Jan 2009 11:31:03 GMT (envelope-from ivoras@svn.freebsd.org) Received: (from ivoras@localhost) by svn.freebsd.org (8.14.3/8.14.3/Submit) id n04BV360056278; Sun, 4 Jan 2009 11:31:03 GMT (envelope-from ivoras@svn.freebsd.org) Message-Id: <200901041131.n04BV360056278@svn.freebsd.org> From: Ivan Voras Date: Sun, 4 Jan 2009 11:31:03 +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: r186735 - head/sbin/geom/class/virstor X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 04 Jan 2009 11:31:04 -0000 Author: ivoras Date: Sun Jan 4 11:31:03 2009 New Revision: 186735 URL: http://svn.freebsd.org/changeset/base/186735 Log: 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) 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 07:33:10 2009 (r186734) +++ head/sbin/geom/class/virstor/gvirstor.8 Sun Jan 4 11:31:03 2009 (r186735) @@ -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 c .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 geom .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