From owner-p4-projects@FreeBSD.ORG Wed Jul 4 12:17:00 2007 Return-Path: X-Original-To: p4-projects@freebsd.org Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id 4B87C16A46D; Wed, 4 Jul 2007 12:17:00 +0000 (UTC) X-Original-To: perforce@FreeBSD.org Delivered-To: perforce@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id C1C6616A468 for ; Wed, 4 Jul 2007 12:16:59 +0000 (UTC) (envelope-from lulf@FreeBSD.org) Received: from repoman.freebsd.org (repoman.freebsd.org [69.147.83.41]) by mx1.freebsd.org (Postfix) with ESMTP id B0E1013C45D for ; Wed, 4 Jul 2007 12:16:59 +0000 (UTC) (envelope-from lulf@FreeBSD.org) Received: from repoman.freebsd.org (localhost [127.0.0.1]) by repoman.freebsd.org (8.13.8/8.13.8) with ESMTP id l64CGxNa055615 for ; Wed, 4 Jul 2007 12:16:59 GMT (envelope-from lulf@FreeBSD.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.13.8/8.13.8/Submit) id l64CGxKt055612 for perforce@freebsd.org; Wed, 4 Jul 2007 12:16:59 GMT (envelope-from lulf@FreeBSD.org) Date: Wed, 4 Jul 2007 12:16:59 GMT Message-Id: <200707041216.l64CGxKt055612@repoman.freebsd.org> X-Authentication-Warning: repoman.freebsd.org: perforce set sender to lulf@FreeBSD.org using -f From: Ulf Lilleengen To: Perforce Change Reviews Cc: Subject: PERFORCE change 122850 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 04 Jul 2007 12:17:00 -0000 http://perforce.freebsd.org/chv.cgi?CH=122850 Change 122850 by lulf@lulf_carrot on 2007/07/04 12:16:27 - More on TODO. - Update the gvinum manpage. Include the added commands in the list, as well as remove them from the incomplete list. - Add an EXAMPLES section to the manpage. Affected files ... .. //depot/projects/soc2007/lulf/TODO#4 edit .. //depot/projects/soc2007/lulf/gvinum_fixup/sbin/gvinum/gvinum.8#2 edit Differences ... ==== //depot/projects/soc2007/lulf/TODO#4 (text+ko) ==== @@ -153,3 +153,5 @@ 21. Updateman-page +22. Add a raid5 command to create a raid5 array the same way that is done with +concat/mirror/stripe ==== //depot/projects/soc2007/lulf/gvinum_fixup/sbin/gvinum/gvinum.8#2 (text+ko) ==== @@ -40,6 +40,12 @@ .Op Fl options .Sh COMMANDS .Bl -tag -width indent +.It Ic attach Ar plex volume Op Cm rename +.It Ic attach Ar subdisk plex Oo Ar offset Oc Op Cm rename +Attach a plex to a volume, or a subdisk to a plex. If offset is specified, the +subdisk will be attached to the given offset within the plex. If rename is +specified, the subdisk or plex will change name according to the object it +attaches to. .It Ic checkparity Oo Fl f Oc Ar plex Check the parity blocks of a RAID-5 plex. The parity check will start at the @@ -49,6 +55,9 @@ the first location at which plex's parity is incorrect. All subdisks in the plex must be up for a parity check. +.It Ic concat Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives +Create a concatenated volume from the specified drives. If no name is specified, +a unique name will be set by gvinum. .It Ic create Op Ar description-file Create a volume as described in .Ar description-file . @@ -57,6 +66,9 @@ provided, opens an editor and provides the current .Nm configuration for editing. +.It Ic detach Oo Fl f Oc Op Ar plex | subdisk +Detach a plex or subdisk from the volume or plex to which it is +attached. .It Ic help Provides a synopsis of .Nm @@ -76,6 +88,13 @@ and .Fl V flags provide progressively more detailed output. +.It Ic mirror Oo Fl fsv Oc Oo Fl n Ar name Oc Ar drives +Create a mirrored volume from the specified drives. It requires at least a +multiple of 2 drives. If no name is specified, +a unique name will be set by gvinum. If the +.Fl s +flag is specified, a striped mirror will be created, and thus requires a +multiple of 4 drives. .It Ic move | mv Fl f Ar drive subdisk Op Ar ... Move the subdisk(s) to the specified drive. The @@ -85,8 +104,13 @@ This can currently only be done when the subdisk is not being accessed. .Pp -If the subdisk(s) form part of a RAID-5 plex, the disk(s) will need to be set -to the +If a single subdisk is moved, and it forms a part of a RAID-5 plex, the moved +subdisks will need to be set to the +.Dq stale +state, and the plex will require a +.Ic start +command; If multiple subdisk(s) is moved, and form part of a RAID-5 plex, the +moved disk(s) will need to be set to the .Dq up state and the plex will require a .Ic rebuildparity @@ -142,10 +166,19 @@ .It Ic start Read configuration from all vinum drives. .It Ic start Oo Fl S Ar size Oc Ar volume | plex | subdisk -Allow the system to access the objects. +Allow the system to access the objects. If necessary, plexes will be synced and +rebuilt. The .Fl S flag is currently ignored. +.It Ic stop Oo Fl f Oc Op Ar volume | plex | subdisk +Terminate access to the objects, or stop +.Nm +if no parameters are specified. +.It Ic stripe Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives +Create a striped volume from the specified drives. If no name is specified, +a unique name will be set by Ic gvinum. This organization requires at least two +drives. .El .Sh DESCRIPTION The @@ -226,6 +259,77 @@ .Nm subdisks .El +.Sh EXAMPLES +To create a mirror on disks /dev/ad1 and /dev/ad2, create a filesystem, mount, +unmount and then stop Ic gvinum: +.Pp +.Dl "gvinum mirror /dev/ad1 /dev/ad2" +.Dl "newfs /dev/gvinum/gvinumvolume0" +.Dl "mount /dev/gvinum/gvinumvolume0 /mnt" +.Dl "..." +.Dl "unmount /mnt" +.Dl "gvinum stop" +.Pp +To create a striped mirror on disks /dev/ad1 /dev/ad2 /dev/ad3 and /dev/ad4 +named "data" and create a filesystem: +.Pp +.Dl "gvinum mirror -s -n data /dev/ad1 /dev/ad2 /dev/ad3 /dev/ad4" +.Dl "newfs /dev/gvinum/data" +.Pp +To create a raid5 array on disks /dev/ad1 /dev/ad2 and /dev/ad3, you can +create a config file like this: +.Pp +.Dl "gvinum create" +.Pp +Then an editor will open, and you can create your configuration: +.Pp +.Dl "drive gdrive1 device /dev/ad1" +.Dl "drive gdrive2 device /dev/ad2" +.Dl "drive gdrive3 device /dev/ad3" +.Dl "volume myraid5vol" +.Dl "plex org raid5 493k" +.Dl "sd drive gdrive1" +.Dl "sd drive gdrive2" +.Dl "sd drive gdrive3" +.Pp +Afterwards, you have to initialize the volume: +.Pp +.Dl "gvinum start myraid5vol" +.Pp +The initialization will start, and the states will be updated when it's +finished. +.Pp +Imagine that one of the drives fails, and the output of 'printconfig' looks +something like this: +.Pp +.Dl "drive gdrive2 device /dev/ad2" +.Dl "drive gdrive3 device /dev/???" +.Dl "drive gdrive1 device /dev/ad1" +.Dl "volume myraid5vol" +.Dl "plex name myraid5vol.p0 org raid5 986s vol myraid5vol" +.Dl "sd name myraid5vol.p0.s2 drive gdrive3 len 32538s driveoffset 265s" +.Dl "plex myraid5vol.p0 plexoffset 1972s" +.Dl "sd name myraid5vol.p0.s1 drive gdrive2 len 32538s driveoffset 265s" +.Dl "plex myraid5vol.p0 plexoffset 986s" +.Dl "sd name myraid5vol.p0.s0 drive gdrive1 len 32538s driveoffset 265s" +.Dl "plex myraid5vol.p0 plexoffset 0s" +.Pp +Create a new drive with this configuration: +.Pp +.Dl "drive gdrive4 device /dev/ad4" +.Pp +Then move the stale subdisk to the new drive: +.Pp +.Dl "gvinum move gdrive4 myraid5vol.p0.s2" +.Pp +Then, initiate the rebuild: +.Pp +.Dl "gvinum start myraid5vol.p0" +.Pp +The plex will go up form degraded mode after the rebuild is finished. The plex +can still be used while the rebuild is in progress, although requests might be +delayed. For a more advanced usage and detailed explanation of gvinum, the +handbook is recommended. .Sh SEE ALSO .Xr geom 4 , .Xr geom 8 @@ -255,9 +359,13 @@ .An "Chris Jones" through the 2005 Google Summer of Code program. +.Ic a partial rewrite of gvinum was done by "Lukas Ertl" and "Ulf Lilleengen" +through the 2007 Google Summer of Code program. The documentation have been +updated to reflect the new functionality. .Sh AUTHORS .An Lukas Ertl Aq le@FreeBSD.org .An Chris Jones Aq soc-cjones@FreeBSD.org +.An Ulf Lilleengen Aq lulf@FreeBSD.org .Sh BUGS Currently, .Nm @@ -271,10 +379,6 @@ .Ic start is ignored. .Pp -The -.Ic stop -command does not work. -.Pp Moving subdisks that are not part of a mirrored or RAID-5 volume will destroy data. It is perhaps a bug to permit this. @@ -291,18 +395,10 @@ .Xr vinum 4 are not supported: .Bl -tag -width indent -.It Ic attach Ar plex volume Op Cm rename -.It Ic attach Ar subdisk plex Oo Ar offset Oc Op Cm rename -Attach a plex to a volume, or a subdisk to a plex. -.It Ic concat Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives -Create a concatenated volume from the specified drives. .It Ic debug Cause the volume manager to enter the kernel debugger. .It Ic debug Ar flags Set debugging flags. -.It Ic detach Oo Fl f Oc Op Ar plex | subdisk -Detach a plex or subdisk from the volume or plex to which it is -attached. .It Ic dumpconfig Op Ar drive ... List the configuration information stored on the specified drives, or all drives in the system if no drive names are specified. @@ -310,17 +406,9 @@ List information about volume manager state. .It Ic label Ar volume Create a volume label. -.It Ic mirror Oo Fl fsv Oc Oo Fl n Ar name Oc Ar drives -Create a mirrored volume from the specified drives. .It Ic resetstats Oo Fl r Oc Op Ar volume | plex | subdisk Reset statistics counters for the specified objects, or for all objects if none are specified. .It Ic setdaemon Op Ar value Set daemon configuration. -.It Ic stop Oo Fl f Oc Op Ar volume | plex | subdisk -Terminate access to the objects, or stop -.Nm -if no parameters are specified. -.It Ic stripe Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives -Create a striped volume from the specified drives. .El