From jmt@duchess.twilley.org  Thu Oct 16 01:10:36 2003
Return-Path: <jmt@duchess.twilley.org>
Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125])
	by hub.freebsd.org (Postfix) with ESMTP id DA72816A4B3
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 16 Oct 2003 01:10:36 -0700 (PDT)
Received: from duchess.twilley.org (dsl092-188-219.sfo1.dsl.speakeasy.net [66.92.188.219])
	by mx1.FreeBSD.org (Postfix) with ESMTP id C762F43FBD
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 16 Oct 2003 01:10:35 -0700 (PDT)
	(envelope-from jmt@duchess.twilley.org)
Received: by duchess.twilley.org (Postfix, from userid 1001)
	id 9EE2D3F546; Thu, 16 Oct 2003 01:10:35 -0700 (PDT)
Message-Id: <20031016081035.9EE2D3F546@duchess.twilley.org>
Date: Thu, 16 Oct 2003 01:10:35 -0700 (PDT)
From: Jack Twilley <jmt@twilley.org>
Reply-To: Jack Twilley <jmt@twilley.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Handbook 12.4.3 Rebuilding ATA RAID1 Arrays contains errors 
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         58111
>Category:       docs
>Synopsis:       Handbook 12.4.3 Rebuilding ATA RAID1 Arrays contains errors
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Thu Oct 16 01:20:09 PDT 2003
>Closed-Date:    Sun Dec 18 18:40:58 GMT 2005
>Last-Modified:  Sun Dec 18 18:40:58 GMT 2005
>Originator:     Jack Twilley
>Release:        FreeBSD 5.1-RELEASE i386
>Organization:
self 
>Environment:
System: FreeBSD duchess.twilley.org 5.1-RELEASE FreeBSD 5.1-RELEASE #0: Mon Jun 16 07:00:17 PDT 2003 root@:/usr/obj/usr/src/sys/DUCHESS i386


	
>Description:
        Section 12.4.3 of the FreeBSD Handbook discusses rebuilding
        ATA RAID1 arrays.  The example case is of a Promise IDE RAID
        card.  I have one of these, and recently had the need to rebuild
        the RAID array.  During this process, I discovered two errors
        in the documentation:

         * step 3 is incomplete
           "Reattach the disk as a spare:" has a command to reattach 
           the disk, but no command to attach the new disk to the array
           as a spare disk.

         * step 5 is obsolete
           The documentation reports that the rebuild command hangs until
           complete.  In fact, the rebuild command returns immediately
           and the disk is rebuilt in the background.

	
>How-To-Repeat:
	
>Fix:
        Replace the old step 3 with something like this:

        3.  Reattach the disk as a spare:

		# atacontrol attach 3
		Master:  ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5
		Slave:   no device present
		# atacontrol addspare ar0 ad6
		<appropriate output here, stupidly didn't save it>

        Replace the old step 5 with something like this:

        5.  The rebuild command returns immediately.  You can check on
            the progress by issuing the following command:

	


>Release-Note:
>Audit-Trail:

From: Paul Armstrong <army@cyber.com.au>
To: freebsd-gnats-submit@FreeBSD.org, jmt@twilley.org
Cc:  
Subject: Re: docs/58111: Handbook 12.4.3 Rebuilding ATA RAID1 Arrays contains errors
Date: Tue, 20 Apr 2004 18:01:19 +1000

 I just got bitten with this too.
 Perhapse someone would care to apply the following patch?
 
 Thanks,
 Paul
 
 --- book.html	Mon Feb 23 20:33:54 2004
 +++ /tmp/book.html	Mon Apr 19 17:31:07 2004
 @@ -28726,7 +28726,7 @@
  </li>
  
  <li>
 -<p>Reattach the disk as a spare:</p>
 +<p>Reattach the disk:</p>
  
  <pre class="SCREEN">
  <samp class="PROMPT">#</samp> <kbd class="USERINPUT">atacontrol attach 3</kbd>
 @@ -28736,6 +28736,13 @@
  </li>
  
  <li>
 +<p>Attach the disk as a spare:</p>
 +<pre class="SCREEN">
 +<samp class="PROMPT">#</samp> <kbd class="USERINPUT">atacontrol addspare ar0 ad6</kbd>
 +</pre>
 +</li>
 +
 +<li>
  <p>Rebuild the array:</p>
  
  <pre class="SCREEN">
 @@ -28744,7 +28751,8 @@
  </li>
  
  <li>
 -<p>The rebuild command hangs until complete. However, it is possible to open another
 +<p>On older versions of FreeBSD, the rebuild command may hang until complete. 
 +However, it is possible to open another
  terminal (using <b class="KEYCAP">Alt</b>+<b class="KEYCAP">F<var
  class="REPLACEABLE">n</var></b>) and check on the progress by issuing the
  following command:</p>

From: "Siebrand Mazeland" <s.mazeland@xs4all.nl>
To: <freebsd-gnats-submit@FreeBSD.org>, <jmt@twilley.org>
Cc:  
Subject: Re: docs/58111: Handbook 12.4.3 Rebuilding ATA RAID1 Arrays contains errors
Date: Sun, 27 Feb 2005 23:54:02 +0100

 The submitted patch was on the HTML page. Below you find a patch to the
 source file. Please evaluate.
 
 Cheers!
 
 Index: en_US.ISO8859-1/books/handbook/disks/chapter.sgml
 ===================================================================
 RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/disks/chapter.sgml,v
 retrieving revision 1.232
 diff -u -r1.232 chapter.sgml
 --- en_US.ISO8859-1/books/handbook/disks/chapter.sgml	27 Feb 2005 12:59:47
 -0000	1.232
 +++ en_US.ISO8859-1/books/handbook/disks/chapter.sgml	27 Feb 2005 22:51:59
 -0000
 @@ -716,7 +716,7 @@
  	</step>
  
  	<step>
 -	  <para>Reattach the disk as a spare:</para>
 +	  <para>Reattach the disk:</para>
  
  	  <screen>&prompt.root; <userinput>atacontrol attach 3</userinput>
  Master:  ad6 &lt;MAXTOR 6L080J4/A93.0500&gt; ATA/ATAPI rev 5
 @@ -724,15 +724,24 @@
  	</step>
  
  	<step>
 +	  <para>Reattach the disk as a spare:</para>
 +
 +	  <screen>&prompt.root; <userinput>atacontrol addspare ar0
 ad6</userinput></screen>
 +	</step>
 +
 +	<step>
  	  <para>Rebuild the array:</para>
  
  	  <screen>&prompt.root; <userinput>atacontrol rebuild
 ar0</userinput></screen>
  	</step>
  
  	<step>
 -	  <para>The rebuild command hangs until complete.  However, it is
 possible to open another
 -	  terminal (using <keycombo action="simul"><keycap>Alt</keycap>
 <keycap>F<replaceable>n</replaceable></keycap></keycombo>)
 -          and check on the progress by issuing the following
 command:</para>
 +	  <para>On older versions of FreeBSD, the rebuild command may
 +	    hang until complete.  However, it is possible to open
 +	    another terminal (using <keycombo
 +	      action="simul"><keycap>Alt</keycap>
 <keycap>F<replaceable>n</replaceable></keycap></keycombo>)
 +	    and check on the progress by issuing the following
 +	    command:</para>
  
  	  <screen>&prompt.root; <userinput>dmesg | tail -10</userinput>
  [output removed]
 
State-Changed-From-To: open->closed 
State-Changed-By: pav 
State-Changed-When: Sun Dec 18 18:40:39 UTC 2005 
State-Changed-Why:  
I just updated The Handbook to match the reality of FreeBSD 6.0. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=58111 
>Unformatted:
