Bring documentation up to date

svn path=/head/; revision=51604

sbin/ccdconfig/ccdconfig.8

@@ -145,13 +145,67 @@ The component devices need to name partitions of type
 as shown by
 .Xr disklabel 8 ).
 .Sh EXAMPLE
-The following command, executed from the command line, would configure ccd0
-with 4 components (/dev/da2e, /dev/da3e, /dev/da4e, /dev/da5e), and an
-interleave factor of 32 blocks.
-.Bd -unfilled -offset indent
-# ccdconfig ccd0 32 0 /dev/da2e /dev/da3e /dev/da4e /dev/da5e
+.Pp
+A number of ccdconfig examples are shown below.  The arguments passed
+to ccdconfig are exactly the same as you might place in the
+.Pa /etc/ccd.conf 
+configuration file.  The first example creates a 4-disk stripe out of
+four scsi disk partitions.  The stripe uses a 64 sector interleave.
+The second example is an example of a complex stripe/mirror combination.
+It reads as a two disk stripe of da2e and da3e which is mirrored
+to a two disk stripe of da4e and da5e.  The last example is a simple
+mirror.  /dev/da2e is mirrored with /dev/da4e and assigned to ccd0.
+.Pp
+.Bd -unfilled -offset
+# ccdconfig ccd0 64 none /dev/da2e /dev/da3e /dev/da4e /dev/da5e
+# ccdconfig ccd0 128 CCDF_MIRROR /dev/da2e /dev/da3e /dev/da4e /dev/da5e
+# ccdconfig ccd0 128 CCDF_MIRROR /dev/da2e /dev/da4e
 .Ed
 .Pp
+When you create a new ccd disk you generally want to
+.Nm disklabel
+it before doing anything else.  Once you create the initial label you can 
+edit it, adding additional partitions.  The label itself takes up the first
+16 sectors of the ccd disk.  If all you are doing is creating filesystems
+with newfs, you do not have to worry about this as newfs will skip the
+label area.  However, if you intend to
+.Nm dd
+to or from a ccd partition it is usually a good idea to construct the
+partition such that it does not overlap the label area.  For example, if
+you have A ccd disk with 10000 sectors you might create a 'd' partition
+with offset 16 and size 9984.
+.Pp
+.Bd -unfilled -offset
+# disklabel -r -w ccd0c auto
+# disklabel -e ccd0c
+.Ed
+.Pp
+The disklabeling of a ccd disk is usually a one-time affair.  Unlike other
+devices, ccd currently requires that you specify partition 'c' when
+running disklabel.  If you reboot the machine and reconfigure the ccd disk,
+the disklabel you
+had created before will still be there and not require reinitialization.
+Beware that changing any ccd parameters: interleave, flags, or the
+device list making up the ccd disk, will usually destroy any prior
+data on that ccd disk.  If this occurs it is usually a good idea to
+reinitialize the label before [re]constructing your ccd disk.
+.Pp
+.Sh RECOVERY
+.Pp
+An error on a ccd disk is usually unrecoverable unless you are using the 
+mirroring option.  But mirroring has its own perils:  It assumes that
+both copies of the data at any given sector are the same.  This holds true
+until a write error occurs or until you replace either side of the mirror.
+.Nm Ccd
+uses a poor-man's mirroring implementation.  It works well enough that if
+you begin to get disk errors you should be able to backup the ccd disk,
+replace the broken hardware, and then regenerate the ccd disk.  If you need
+more then this you should look into external hardware RAID SCSI boxes,
+RAID controllers such as the
+.Nm dpt
+controller, or software RAID systems such as
+.Nm vinum .
+.Pp
 .Sh FILES
 .Bl -tag -width /etc/ccd.conf -compact
 .It Pa /etc/ccd.conf
@@ -160,6 +214,7 @@ default ccd configuration file
 .Sh SEE ALSO
 .Xr ccd 4 ,
 .Xr rc 8
+.Xr vinum 8
 .Sh HISTORY
 The
 .Nm