Date: Sat, 10 Aug 2013 18:25:26 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42527 - head/en_US.ISO8859-1/books/handbook/geom Message-ID: <201308101825.r7AIPQtg019996@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Sat Aug 10 18:25:25 2013 New Revision: 42527 URL: http://svnweb.freebsd.org/changeset/doc/42527 Log: Add a new section on graid(8). Many people helped with review and corrections, including Allan Jude, bjk, brd, and mav. Modified: head/en_US.ISO8859-1/books/handbook/geom/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/geom/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/geom/chapter.xml Fri Aug 9 21:49:13 2013 (r42526) +++ head/en_US.ISO8859-1/books/handbook/geom/chapter.xml Sat Aug 10 18:25:25 2013 (r42527) @@ -824,6 +824,314 @@ mountroot></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; 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 G mirror for safely + storing the operating system, followed by a 20 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 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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201308101825.r7AIPQtg019996>