docs/117310: Additions to atacontrol man page

Thu Oct 18 20:10:01 UTC 2007

>Number:         117310
>Category:       docs
>Synopsis:       Additions to atacontrol man page
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Thu Oct 18 20:10:01 UTC 2007
>Closed-Date:
>Last-Modified:
>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 at 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:
>Unformatted:

