From owner-svn-doc-head@FreeBSD.ORG Sat Aug 10 18:25:26 2013 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTP id 70C2E48D; Sat, 10 Aug 2013 18:25:26 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 4F1BA298F; Sat, 10 Aug 2013 18:25:26 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r7AIPQHg019997; Sat, 10 Aug 2013 18:25:26 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r7AIPQtg019996; Sat, 10 Aug 2013 18:25:26 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201308101825.r7AIPQtg019996@svn.freebsd.org> From: Warren Block Date: Sat, 10 Aug 2013 18:25:26 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 10 Aug 2013 18:25:26 -0000 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> + + + + + Warren + Block + Originally contributed by + + + + Software <acronym>RAID</acronym> Devices + + + GEOM + + + Software RAID Devices + Hardware-assisted RAID + + + Some motherboards and expansion cards add some simple + hardware, usually just a ROM, that allows the + computer to boot from a RAID array. After + booting, access to the RAID array is handled + by software running on the computer's main processor. This + hardware-assisted software + RAID gives RAID + arrays that are not dependent on any particular operating + system, and which are functional even before an operating system + is loaded. + + Several levels of RAID are supported, + depending on the hardware in use. See &man.graid.8; for a + complete list. + + &man.graid.8; requires the geom_raid.ko + kernel module, which is included in the + GENERIC kernel starting with &os; 9.1. + If needed, it can be loaded manually with + graid load. + + + Creating an Array + + Software RAID 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 + RAID arrays. &man.graid.8; can also create + arrays directly from the command line. + + graid label is used to create a new + array. The motherboard used for this example has an Intel + software RAID chipset, so the Intel + metadata format is specified. The new array is given a label + of gm0, it is a mirror + (RAID1), and uses drives + ada0 and + ada1. + + + Some space on the drives will be overwritten when they + are made into a new array. Back up existing data + first! + + + &prompt.root; graid label Intel gm0 RAID1 ada0 ada1 +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. + + A status check shows the new mirror is ready for + use: + + &prompt.root; graid status + Name Status Components +raid/r0 OPTIMAL ada0 (ACTIVE (ACTIVE)) + ada1 (ACTIVE (ACTIVE)) + + The array device appears in + /dev/raid/. The first array is called + r0. Additional arrays, if present, + will be r1, + r2, and so on. + + The BIOS 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 r0. To + show the actual labels, like gm0 in + the example above, use &man.sysctl.8;: + + &prompt.root; sysctl kern.geom.raid.name_format=1 + + + + Multiple Volumes + + Some software RAID devices support + more than one volume 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 RAID devices support two + volumes. This example creates a 40 G mirror for safely + storing the operating system, followed by a 20 G + RAID0 (stripe) volume for fast temporary + storage: + + &prompt.root; graid label -S 40G Intel gm0 RAID1 ada0 ada1 +&prompt.root; graid add -S 20G gm0 RAID0 + + Volumes appear as additional + rX entries + in /dev/raid/. An array with two volumes + will show r0 and + r1. + + See &man.graid.8; for the number of volumes supported by + different software RAID devices. + + + + Converting a Single Drive to a Mirror + + 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: + + + + The drive must be partitioned with the + MBR partitioning scheme. + GPT or other partitioning schemes with + metadata at the end of the drive will be overwritten and + corrupted by the &man.graid.8; metadata. + + + + 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. + + + + If the drive meets these requirements, start by making a + full backup. Then create a single-drive mirror with that + drive: + + &prompt.root; graid label Intel gm0 RAID1 ada0 NONE + + &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: + + &prompt.root; graid insert raid/r0 ada1 + + 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. + + + + Inserting New Drives into the Array + + 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. + + 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. + + &prompt.root; graid insert raid/r0 ada1 +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. + + + + Removing Drives from the Array + + Individual drives can be permanently removed from a + from an array and their metadata erased: + + &prompt.root; graid remove raid/r0 ada1 +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. + + + + Stopping the Array + + An array can be stopped without removing metadata from the + drives. The array will be restarted when the system is + booted. + + &prompt.root; graid stop raid/r0 + + + + Checking Array Status + + 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: + + &prompt.root; graid status + Name Status Components +raid/r0 DEGRADED ada0 (ACTIVE (ACTIVE)) + ada1 (ACTIVE (REBUILD 28%)) + + Some types of arrays, like RAID0 or + CONCAT, may not be shown in the status + report if disks have failed. To see these partially-failed + arrays, add : + + &prompt.root; graid status -ga + Name Status Components +Intel-e2d07d9a BROKEN ada6 (ACTIVE (ACTIVE)) + + + + Deleting Arrays + + 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: + + &prompt.root; graid delete raid/r0 + + + + Deleting Unexpected Arrays + + 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: + + + + Boot the system. At the boot menu, select + 2 for the loader prompt. Enter: + + OK set kern.geom.raid.enable=0 +OK boot + + The system will boot with &man.graid.8; + disabled. + + + + Back up all data on the affected drive. + + + + As a workaround, &man.graid.8; array detection + can be disabled by adding + + kern.geom.raid.enable=0 + + to /boot/loader.conf. + + To permanently remove the &man.graid.8; metadata + from the affected drive, boot a &os; installation + CD-ROM or memory stick, and select + Shell. Use status + to find the name of the array, typically + raid/r0: + + &prompt.root; graid status + Name Status Components +raid/r0 OPTIMAL ada0 (ACTIVE (ACTIVE)) + ada1 (ACTIVE (ACTIVE)) + + Delete the volume by name: + + &prompt.root; graid delete raid/r0 + + 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. + + Reboot and verify data, restoring from backup if + necessary. After the metadata has been removed, the + kern.geom.raid.enable=0 entry in + /boot/loader.conf can also be + removed. + + + + +