From tedm@mail.ipinc.net  Thu Oct 18 20:03:20 2007
Return-Path: <tedm@mail.ipinc.net>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id CFC1216A417
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 18 Oct 2007 20:03:20 +0000 (UTC)
	(envelope-from tedm@mail.ipinc.net)
Received: from mail.ipinc.net (mail.ipinc.net [65.75.192.11])
	by mx1.freebsd.org (Postfix) with ESMTP id ADBAB13C461
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 18 Oct 2007 20:03:20 +0000 (UTC)
	(envelope-from tedm@mail.ipinc.net)
Received: from mail.ipinc.net (localhost.ipinc.net [127.0.0.1])
	by mail.ipinc.net (8.13.8/8.13.8) with ESMTP id l9IJmhie035753
	for <FreeBSD-gnats-submit@freebsd.org>; Thu, 18 Oct 2007 12:48:44 -0700 (PDT)
	(envelope-from tedm@mail.ipinc.net)
Received: (from root@localhost)
	by mail.ipinc.net (8.13.8/8.13.8/Submit) id l9IJmhEd035751;
	Thu, 18 Oct 2007 12:48:43 -0700 (PDT)
	(envelope-from tedm)
Message-Id: <200710181948.l9IJmhEd035751@mail.ipinc.net>
Date: Thu, 18 Oct 2007 12:48:43 -0700 (PDT)
From: Ted Mittelstaedt <tedm@ipinc.net>
Reply-To: Ted Mittelstaedt <tedm@ipinc.net>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Additions to atacontrol man page
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         117310
>Category:       docs
>Synopsis:       [patch] Additions to atacontrol man page
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    remko
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Thu Oct 18 20:10:01 UTC 2007
>Closed-Date:    Sun Dec 02 09:11:31 UTC 2007
>Last-Modified:  Sun Dec 02 09:11:31 UTC 2007
>Originator:     Ted Mittelstaedt
>Release:        FreeBSD 6.2-RELEASE amd64
>Organization:
Internet Partners, Inc.
>Environment:
System: FreeBSD mail.ipinc.net 6.2-RELEASE FreeBSD 6.2-RELEASE #0: Thu Oct 4 15:03:21 PDT 2007 tedm@mail.ipinc.net:/usr/src/sys/amd64/compile/MAIL amd64


	
>Description:
	
 Expanded EXAMPLES section for man page
>How-To-Repeat:
	
>Fix:

	

Diff of additions to manpage in /usr/share/man/man8



--- atacontrol.8.original	Thu Oct 18 10:57:18 2007
+++ atacontrol.8	Thu Oct 18 12:37:44 2007
@@ -221,6 +221,105 @@
 The new modes are set as soon as the
 .Nm
 command returns.
+.Pp
+The atacontrol command can also be used to create purely software
+RAID arrays in systems that do NOT have a "real" hardware RAID card
+such as a Highpoint or Promise card.  A common scenario is a 1U
+server such as the HP DL320 G4 or G5.  These servers contain a SATA
+controller that has 2 channels that can contain 2 disks per channel,
+but the servers are wired to only place a single SATA drive on each
+channel.  These servers do have a "pseudo" RAID BIOS but it uses
+a proprietary format that is not compatible with the ata driver, and
+thus their RAID bios must be switched off.  Another common scenario
+would be a Promise UDMA100 
+controller card that did not contain the Fasttrack RAID BIOS, but
+did contain 2 UDMA channels. One channel would be put on 1 disk
+and the other channel on the other disk.  It is NOT recommended to
+create such arrays on a Primary/Secondary pair on a SINGLE channel
+since the throughput of the mirror would be severley compromised,
+the ability to rebuild the array in the event of a disk failure
+would be greatly complicated, and if a disk controller electronics
+failed it could wedge the channel and take both disks in the
+mirror offline. (which would defeat the purpose of having a mirror
+in the first place)
+.Pp
+A quick and dirty way to create such a mirrored array on a new
+system is to boot off the FreeBSD install CD, do a minimal scratch
+install, abort out of the post install questions, and at the command
+line issue the command:
+.Pp
+.Dl "atacontrol create RAID1 ad4 ad6"
+.Pp
+then immediately issue a reboot and boot from the installation CD
+again, and during the installation, you will now see "ar0" listed
+as a disk to install on, and install on that instead of ad4, ad6, etc.
+.Pp
+To get information about the status of a RAID array in the system
+use the command line:
+.Pp
+.Dl "atacontrol status ar0"
+.Pp
+A typical output showing good health on a RAID array might be as
+follows:
+.Pp
+.Dl "ar0: ATA RAID1 subdisks: ad4 ad6 status: READY"
+.Pp
+If a disk drive in a RAID1 array dies the system will mark the disk
+in a DOWN state and change the array status to DEGRADED.  This can
+ALSO happen in rare instances due to a power fluctuation or other event
+causing the system to not shutdown properly.  In that case the output
+will look like the following:
+.Pp
+.Dl "ar0: ATA RAID1 subdisks: ad4 DOWN status: DEGRADED"
+.Pp
+For a mirrored RAID1 system the server WILL ALLOW you to remove a
+dead SATA disk drive (if the drive is in a hot-swap tray) without
+freezing up the system, so you can remove the disk and while your
+obtaining a replacement the server can run off of the active disk.
+The only caveat is that if the active disk is ad6, the system most
+likely will NOT be able to be rebooted since most systems only
+support booting off of the first disk drive.
+.Pp
+To deactivate the DOWN disk ad6 to allow for it to be ejected, use
+the following:
+.Pp
+.Dl "atacontrol detach ata3"
+.Pp
+then eject or remove the disk. Note that this only works if the 2 disks
+in the mirror are on separate channels (which is the standard setup for
+1-U servers like the HP DL320)  When the new disk drive is obtained,
+make sure it is blank, then shut the system down.  At this point, if
+the system has a RAID array card like a Hipoint or Promise controller,
+you may then boot it into BIOS of the card and use the manufacturers
+RAID array rebuild utilities to rebuild the array.
+.Pp
+If the system has a pure software array and is not using a "real" ATA
+RAID controller, then shut the system down, make sure that the disk
+that was still working is moved to the bootable position (channel 0
+or whatever the BIOS allows the system to boot from) and the blank disk
+is placed in the secondary position, then boot the system into 
+single-user mode and issue the command:
+.Pp
+.Dl "atacontrol addspare ar0 ad6"
+.Dl "atacontrol rebuild ar0"
+.Pp
+If the disk drive did NOT fail and the RAID array became unmirrored due
+to a software glitch or improper shutdown, then a slightly different
+process must be followed.  Begin by issuing the detach command (this
+shows the detach for disk ad6, the primary master on channel 3):
+.Pp
+.Dl "atacontrol detach ata3"
+.Pp
+then reboot the system into single-user mode.  (don't just init the system,
+reboot it so that both disks get probed)  You will probably see TWO mirrored
+RAID arrays appear during the boot messages, ar0 and ar1.  Issue the
+command:
+.Pp
+.Dl "atacontrol delete ar1"
+.Dl "atacontrol addspare ar0 ad6"
+.Pp
+Now a status command will show the array rebuilding.
+.Pp
 .Sh SEE ALSO
 .Xr ata 4
 .Sh HISTORY

>Release-Note:
>Audit-Trail:
State-Changed-From-To: open->patched 
State-Changed-By: remko 
State-Changed-When: Wed Nov 28 21:37:56 UTC 2007 
State-Changed-Why:  
Updated in -current. 


Responsible-Changed-From-To: freebsd-doc->remko 
Responsible-Changed-By: remko 
Responsible-Changed-When: Wed Nov 28 21:37:56 UTC 2007 
Responsible-Changed-Why:  
Updated in -current. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=117310 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/117310: commit references a PR
Date: Wed, 28 Nov 2007 21:37:32 +0000 (UTC)

 remko       2007-11-28 21:37:26 UTC
 
   FreeBSD src repository
 
   Modified files:
     sbin/atacontrol      atacontrol.8 
   Log:
   Expand the EXAMPLES section for atacontrol.8
   
   PR:             docs/117310
   Submitted by:   Ted Mittelstaedt <tedm at ipinc dot net>
                   with minor modifications by me.
   
   Revision  Changes    Path
   1.29      +105 -1    src/sbin/atacontrol/atacontrol.8
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/117310: commit references a PR
Date: Sun,  2 Dec 2007 08:49:28 +0000 (UTC)

 remko       2007-12-02 08:49:24 UTC
 
   FreeBSD src repository
 
   Modified files:        (Branch: RELENG_7)
     sbin/atacontrol      atacontrol.8 
   Log:
   MFC rev 1.29 atacontrol.8
   
     Expand the EXAMPLES section for atacontrol.8
   
     PR:             docs/117310
     Submitted by:   Ted Mittelstaedt <tedm at ipinc dot net>
                     with minor modifications by me.
   
   Approved by:    re (hrs)
   
   Revision  Changes    Path
   1.28.2.1  +105 -1    src/sbin/atacontrol/atacontrol.8
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/117310: commit references a PR
Date: Sun,  2 Dec 2007 09:01:23 +0000 (UTC)

 remko       2007-12-02 09:01:18 UTC
 
   FreeBSD src repository
 
   Modified files:        (Branch: RELENG_6)
     sbin/atacontrol      atacontrol.8 
   Log:
   MFC rev 1.29 atacontrol.8
   
     Expand the EXAMPLES section for atacontrol.8
   
     PR:             docs/117310
     Submitted by:   Ted Mittelstaedt <tedm at ipinc dot net>
                     with minor modifications by me.
   
   Approved by:    re (hrs)
   
   Revision  Changes    Path
   1.26.2.3  +105 -1    src/sbin/atacontrol/atacontrol.8
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/117310: commit references a PR
Date: Sun,  2 Dec 2007 09:09:48 +0000 (UTC)

 remko       2007-12-02 09:09:44 UTC
 
   FreeBSD src repository
 
   Modified files:        (Branch: RELENG_6_3)
     sbin/atacontrol      atacontrol.8 
   Log:
   MFC rev 1.29 atacontrol.8
   
     Expand the EXAMPLES section for atacontrol.8
   
     PR:             docs/117310
     Submitted by:   Ted Mittelstaedt <tedm at ipinc dot net>
                     with minor modifications by me.
   
   Approved by:    re (hrs)
   
   Revision      Changes    Path
   1.26.2.2.6.1  +105 -1    src/sbin/atacontrol/atacontrol.8
 _______________________________________________
 cvs-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/cvs-all
 To unsubscribe, send any mail to "cvs-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: patched->closed 
State-Changed-By: remko 
State-Changed-When: Sun Dec 2 09:11:30 UTC 2007 
State-Changed-Why:  
Committed. Thanks! 

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