PERFORCE change 122850 for review

Wed Jul 4 12:17:00 UTC 2007

http://perforce.freebsd.org/chv.cgi?CH=122850

Change 122850 by lulf at 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 at FreeBSD.org
 .An Chris Jones Aq soc-cjones at FreeBSD.org
+.An Ulf Lilleengen Aq lulf at 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
