Add a new section on graid(8). Many people helped with review and

corrections, including Allan Jude, bjk, brd, and mav.

1 files changed, 308 insertions, 0 deletions

diff --git a/en_US.ISO8859-1/books/handbook/geom/chapter.xml b/en_US.ISO8859-1/books/handbook/geom/chapter.xml
index 102f07593a..8fa6b4b1b8 100644
--- a/en_US.ISO8859-1/books/handbook/geom/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/geom/chapter.xml
@@ -824,6 +824,314 @@ mountroot&gt;</screen>
     </sect2>
   </sect1>
 
+  <sect1 id="geom-graid">
+    <sect1info>
+      <authorgroup>
+	<author>
+	  <firstname>Warren</firstname>
+	  <surname>Block</surname>
+	  <contrib>Originally contributed by </contrib>
+	</author>
+      </authorgroup>
+    </sect1info>
+    <title>Software <acronym>RAID</acronym> Devices</title>
+
+    <indexterm>
+      <primary>GEOM</primary>
+    </indexterm>
+    <indexterm>
+      <primary>Software RAID Devices</primary>
+      <secondary>Hardware-assisted RAID</secondary>
+    </indexterm>
+
+    <para>Some motherboards and expansion cards add some simple
+      hardware, usually just a <acronym>ROM</acronym>, that allows the
+      computer to boot from a <acronym>RAID</acronym> array.  After
+      booting, access to the <acronym>RAID</acronym> array is handled
+      by software running on the computer's main processor.  This
+      <quote>hardware-assisted software
+	<acronym>RAID</acronym></quote> gives <acronym>RAID</acronym>
+      arrays that are not dependent on any particular operating
+      system, and which are functional even before an operating system
+      is loaded.</para>
+
+    <para>Several levels of <acronym>RAID</acronym> are supported,
+      depending on the hardware in use.  See &man.graid.8; for a
+      complete list.</para>
+
+    <para>&man.graid.8; requires the <filename>geom_raid.ko</filename>
+      kernel module, which is included in the
+      <filename>GENERIC</filename> kernel starting with &os;&nbsp;9.1.
+      If needed, it can be loaded manually with
+      <command>graid load</command>.</para>
+
+    <sect2 id="geom-graid-creating">
+      <title>Creating an Array</title>
+
+      <para>Software <acronym>RAID</acronym> devices often have a menu
+	that can be entered by pressing special keys when the computer
+	is booting.  The menu can be used to create and delete
+	<acronym>RAID</acronym> arrays.  &man.graid.8; can also create
+	arrays directly from the command line.</para>
+
+      <para><command>graid label</command> is used to create a new
+	array.  The motherboard used for this example has an Intel
+	software <acronym>RAID</acronym> chipset, so the Intel
+	metadata format is specified.  The new array is given a label
+	of <devicename>gm0</devicename>, it is a mirror
+	(<acronym>RAID1</acronym>), and uses drives
+	<devicename>ada0</devicename> and
+	<devicename>ada1</devicename>.</para>
+
+      <caution>
+	<para>Some space on the drives will be overwritten when they
+	  are made into a new array.  Back up existing data
+	  first!</para>
+      </caution>
+
+      <screen>&prompt.root; <userinput>graid label Intel gm0 RAID1 ada0 ada1</userinput>
+GEOM_RAID: Intel-a29ea104: Array Intel-a29ea104 created.
+GEOM_RAID: Intel-a29ea104: Disk ada0 state changed from NONE to ACTIVE.
+GEOM_RAID: Intel-a29ea104: Subdisk gm0:0-ada0 state changed from NONE to ACTIVE.
+GEOM_RAID: Intel-a29ea104: Disk ada1 state changed from NONE to ACTIVE.
+GEOM_RAID: Intel-a29ea104: Subdisk gm0:1-ada1 state changed from NONE to ACTIVE.
+GEOM_RAID: Intel-a29ea104: Array started.
+GEOM_RAID: Intel-a29ea104: Volume gm0 state changed from STARTING to OPTIMAL.
+Intel-a29ea104 created
+GEOM_RAID: Intel-a29ea104: Provider raid/r0 for volume gm0 created.</screen>
+
+      <para>A status check shows the new mirror is ready for
+	use:</para>
+
+      <screen>&prompt.root; <userinput>graid status</userinput>
+   Name   Status  Components
+raid/r0  OPTIMAL  ada0 (ACTIVE (ACTIVE))
+                  ada1 (ACTIVE (ACTIVE))</screen>
+
+      <para>The array device appears in
+	<filename>/dev/raid/</filename>.  The first array is called
+	<devicename>r0</devicename>.  Additional arrays, if present,
+	will be <devicename>r1</devicename>,
+	<devicename>r2</devicename>, and so on.</para>
+
+      <para>The <acronym>BIOS</acronym> menu on some of these devices
+	can create arrays with special characters in their names.  To
+	avoid problems with those special characters, arrays are given
+	simple numbered names like <devicename>r0</devicename>.  To
+	show the actual labels, like <devicename>gm0</devicename> in
+	the example above, use &man.sysctl.8;:</para>
+
+      <screen>&prompt.root; <userinput>sysctl kern.geom.raid.name_format=1</userinput></screen>
+    </sect2>
+
+    <sect2 id="geom-graid-volumes">
+      <title>Multiple Volumes</title>
+
+      <para>Some software <acronym>RAID</acronym> devices support
+	more than one <emphasis>volume</emphasis> on an array.
+	Volumes work like partitions, allowing space on the physical
+	drives to be split and used in different ways.  For example,
+	Intel software <acronym>RAID</acronym> devices support two
+	volumes.  This example creates a 40&nbsp;G mirror for safely
+	storing the operating system, followed by a 20&nbsp;G
+	<acronym>RAID0</acronym> (stripe) volume for fast temporary
+	storage:</para>
+
+      <screen>&prompt.root; <userinput>graid label -S 40G Intel gm0 RAID1 ada0 ada1</userinput>
+&prompt.root; <userinput>graid add -S 20G gm0 RAID0</userinput></screen>
+
+      <para>Volumes appear as additional
+	<devicename>r<replaceable>X</replaceable></devicename> entries
+	in <filename>/dev/raid/</filename>.  An array with two volumes
+	will show <devicename>r0</devicename> and
+	<devicename>r1</devicename>.</para>
+
+      <para>See &man.graid.8; for the number of volumes supported by
+	different software <acronym>RAID</acronym> devices.</para>
+    </sect2>
+
+    <sect2 id="geom-graid-converting">
+      <title>Converting a Single Drive to a Mirror</title>
+
+      <para>Under certain specific conditions, it is possible to
+	convert an existing single drive to a &man.graid.8; array
+	without reformatting.  To avoid data loss during the
+	conversion, the existing drive must meet these minimum
+	requirements:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>The drive must be partitioned with the
+	    <acronym>MBR</acronym> partitioning scheme.
+	    <acronym>GPT</acronym> or other partitioning schemes with
+	    metadata at the end of the drive will be overwritten and
+	    corrupted by the &man.graid.8; metadata.</para>
+	</listitem>
+
+	<listitem>
+	  <para>There must be enough unpartitioned and unused space at
+	    the end of the drive to hold the &man.graid.8; metadata.
+	    This metadata varies in size, but the largest occupies
+	    64&nbsp;M, so at least that much free space is
+	    recommended.</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>If the drive meets these requirements, start by making a
+	full backup.  Then create a single-drive mirror with that
+	drive:</para>
+
+      <screen>&prompt.root; <userinput>graid label Intel gm0 RAID1 ada0 NONE</userinput></screen>
+
+      <para>&man.graid.8; metadata was written to the end of the drive
+	in the unused space.  A second drive can now be inserted into
+	the mirror:</para>
+
+      <screen>&prompt.root; <userinput>graid insert raid/r0 ada1</userinput></screen>
+
+      <para>Data from the original drive will immediately begin to be
+	copied to the second drive.  The mirror will operate in
+	degraded status until the copy is complete.</para>
+    </sect2>
+
+    <sect2 id="geom-graid-inserting">
+      <title>Inserting New Drives into the Array</title>
+
+      <para>Drives can be inserted into an array as replacements for
+	drives that have failed or are missing.  If there are no
+	failed or missing drives, the new drive becomes a spare.  For
+	example, inserting a new drive into a working two-drive mirror
+	results in a two-drive mirror with one spare drive, not a
+	three-drive mirror.</para>
+
+      <para>In the example mirror array, data immediately begins to be
+	copied to the newly-inserted drive.  Any existing information
+	on the new drive will be overwritten.</para>
+
+      <screen>&prompt.root; <userinput>graid insert raid/r0 ada1</userinput>
+GEOM_RAID: Intel-a29ea104: Disk ada1 state changed from NONE to ACTIVE.
+GEOM_RAID: Intel-a29ea104: Subdisk gm0:1-ada1 state changed from NONE to NEW.
+GEOM_RAID: Intel-a29ea104: Subdisk gm0:1-ada1 state changed from NEW to REBUILD.
+GEOM_RAID: Intel-a29ea104: Subdisk gm0:1-ada1 rebuild start at 0.</screen>
+    </sect2>
+
+    <sect2 id="geom-graid-removing">
+      <title>Removing Drives from the Array</title>
+
+      <para>Individual drives can be permanently removed from a
+	from an array and their metadata erased:</para>
+
+      <screen>&prompt.root; <userinput>graid remove raid/r0 ada1</userinput>
+GEOM_RAID: Intel-a29ea104: Disk ada1 state changed from ACTIVE to OFFLINE.
+GEOM_RAID: Intel-a29ea104: Subdisk gm0:1-[unknown] state changed from ACTIVE to NONE.
+GEOM_RAID: Intel-a29ea104: Volume gm0 state changed from OPTIMAL to DEGRADED.</screen>
+    </sect2>
+
+    <sect2 id="geom-graid-stopping">
+      <title>Stopping the Array</title>
+
+      <para>An array can be stopped without removing metadata from the
+	drives.  The array will be restarted when the system is
+	booted.</para>
+
+      <screen>&prompt.root; <userinput>graid stop raid/r0</userinput></screen>
+    </sect2>
+
+    <sect2 id="geom-graid-status">
+      <title>Checking Array Status</title>
+
+      <para>Array status can be checked at any time.  After a drive
+	was added to the mirror in the example above, data is being
+	copied from the original drive to the new drive:</para>
+
+      <screen>&prompt.root; <userinput>graid status</userinput>
+   Name    Status  Components
+raid/r0  DEGRADED  ada0 (ACTIVE (ACTIVE))
+                   ada1 (ACTIVE (REBUILD 28%))</screen>
+
+      <para>Some types of arrays, like <literal>RAID0</literal> or
+	<literal>CONCAT</literal>, may not be shown in the status
+	report if disks have failed.  To see these partially-failed
+	arrays, add <option>-ga</option>:</para>
+
+      <screen>&prompt.root; <userinput>graid status -ga</userinput>
+          Name  Status  Components
+Intel-e2d07d9a  BROKEN  ada6 (ACTIVE (ACTIVE))</screen>
+    </sect2>
+
+    <sect2 id="geom-graid-deleting">
+      <title>Deleting Arrays</title>
+
+      <para>Arrays are destroyed by deleting all of the volumes from
+	them.  When the last volume present is deleted, the array is
+	stopped and metadata is removed from the drives:</para>
+
+      <screen>&prompt.root; <userinput>graid delete raid/r0</userinput></screen>
+    </sect2>
+
+    <sect2 id="geom-graid-unexpected">
+      <title>Deleting Unexpected Arrays</title>
+
+      <para>Drives may unexpectedly contain &man.graid.8; metadata,
+	either from previous use or manufacturer testing.
+	&man.graid.8; will detect these drives and create an array,
+	interfering with access to the individual drive.  To remove
+	the unwanted metadata:</para>
+
+      <procedure>
+	<step>
+	  <para>Boot the system.  At the boot menu, select
+	    <literal>2</literal> for the loader prompt.  Enter:</para>
+
+	  <screen>OK <userinput>set kern.geom.raid.enable=0</userinput>
+OK <userinput>boot</userinput></screen>
+
+	  <para>The system will boot with &man.graid.8;
+	    disabled.</para>
+	</step>
+
+	<step>
+	  <para>Back up all data on the affected drive.</para>
+	</step>
+
+	<step>
+	  <para>As a workaround, &man.graid.8; array detection
+	    can be disabled by adding</para>
+
+	  <programlisting>kern.geom.raid.enable=0</programlisting>
+
+	  <para>to <filename>/boot/loader.conf</filename>.</para>
+
+	  <para>To permanently remove the &man.graid.8; metadata
+	    from the affected drive, boot a &os; installation
+	    <acronym>CD-ROM</acronym> or memory stick, and select
+	    <literal>Shell</literal>.  Use <command>status</command>
+	    to find the name of the array, typically
+	    <literal>raid/r0</literal>:</para>
+
+	  <screen>&prompt.root; <userinput>graid status</userinput>
+   Name   Status  Components
+raid/r0  OPTIMAL  ada0 (ACTIVE (ACTIVE))
+                  ada1 (ACTIVE (ACTIVE))</screen>
+
+	  <para>Delete the volume by name:</para>
+
+	  <screen>&prompt.root; <userinput>graid delete raid/r0</userinput></screen>
+
+	  <para>If there is more than one volume shown, repeat the
+	    process for each volume.  After the last array has been
+	    deleted, the volume will be destroyed.</para>
+
+	  <para>Reboot and verify data, restoring from backup if
+	    necessary.  After the metadata has been removed, the
+	    <literal>kern.geom.raid.enable=0</literal> entry in
+	    <filename>/boot/loader.conf</filename> can also be
+	    removed.</para>
+	</step>
+      </procedure>
+    </sect2>
+  </sect1>
+
   <sect1 id="geom-raid3">
     <sect1info>
       <authorgroup>