380 lines
11 KiB
Groff
380 lines
11 KiB
Groff
.\"
|
|
.\" Copyright (c) 2000,2001,2002 Søren Schmidt <sos@FreeBSD.org>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd February 21, 2009
|
|
.Dt ATACONTROL 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm atacontrol
|
|
.Nd ATA device driver control program
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Aq Ar command
|
|
.Ar args
|
|
.Pp
|
|
.Nm
|
|
.Ic attach
|
|
.Ar channel
|
|
.Nm
|
|
.Ic detach
|
|
.Ar channel
|
|
.Nm
|
|
.Ic reinit
|
|
.Ar channel
|
|
.Nm
|
|
.Ic create
|
|
.Ar type Oo Ar interleave Oc Ar disk0 ... diskN
|
|
.Nm
|
|
.Ic delete
|
|
.Ar raid
|
|
.Nm
|
|
.Ic addspare
|
|
.Ar raid disk
|
|
.Nm
|
|
.Ic rebuild
|
|
.Ar raid
|
|
.Nm
|
|
.Ic status
|
|
.Ar raid
|
|
.Nm
|
|
.Ic mode
|
|
.Ar device
|
|
.Op Ar mode
|
|
.Nm
|
|
.Ic info
|
|
.Ar channel
|
|
.Nm
|
|
.Ic cap
|
|
.Ar device
|
|
.Nm
|
|
.Ic spindown
|
|
.Ar device
|
|
.Op Ar seconds
|
|
.Nm
|
|
.Ic list
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility is a control program that provides the user access and control to the
|
|
.Fx
|
|
.Xr ata 4
|
|
subsystem.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility
|
|
can cause severe system crashes and loss of data if used improperly.
|
|
Please
|
|
exercise caution when using this command!
|
|
.Pp
|
|
The
|
|
.Ar channel
|
|
argument is the ATA channel device (e.g., ata0) on which to operate.
|
|
The following commands are supported:
|
|
.Bl -tag -width ".Ic addspare"
|
|
.It Ic attach
|
|
Attach an ATA
|
|
.Ar channel .
|
|
Devices on the channel are probed and attached as
|
|
is done on boot.
|
|
.It Ic detach
|
|
Detach an ATA
|
|
.Ar channel .
|
|
Devices on the channel are removed from the kernel,
|
|
and all outstanding transfers etc.\& are returned back to the system marked
|
|
as failed.
|
|
.It Ic reinit
|
|
Reinitialize an ATA
|
|
.Ar channel .
|
|
Both devices on the channel are reset and
|
|
initialized to the parameters the ATA driver has stored internally.
|
|
Devices that have gone bad and no longer respond to the probe, or devices
|
|
that have physically been removed, are removed from the kernel.
|
|
Likewise are devices that show up during a reset, probed and attached.
|
|
.It Ic create
|
|
Create a
|
|
.Ar type
|
|
ATA RAID.
|
|
The type can be
|
|
.Cm RAID0
|
|
(stripe),
|
|
.Cm RAID1
|
|
(mirror),
|
|
.Cm RAID0+1 ,
|
|
.Cm SPAN
|
|
or
|
|
.Cm JBOD .
|
|
In case the RAID has a
|
|
.Cm RAID0
|
|
component,
|
|
the
|
|
.Ar interleave
|
|
must be specified in number of sectors.
|
|
The RAID will be created
|
|
of the individual disks named
|
|
.Bk -words
|
|
.Ar disk0 ... diskN .
|
|
.Ek
|
|
.Pp
|
|
Although the ATA driver allows for creating an ATA RAID on disks with any
|
|
controller, there are restrictions.
|
|
It is only possible to boot on
|
|
an array if it is either located on a
|
|
.Dq real
|
|
ATA RAID controller like
|
|
the Promise or Highpoint controllers, or if the RAID declared is of
|
|
.Cm RAID1
|
|
or
|
|
.Cm SPAN
|
|
type; in case of a
|
|
.Cm SPAN ,
|
|
the partition to boot must
|
|
reside on the first disk in the SPAN.
|
|
.It Ic delete
|
|
Delete a RAID array on a RAID capable ATA controller.
|
|
.It Ic addspare
|
|
Add a spare disk to an existing RAID.
|
|
.It Ic rebuild
|
|
Rebuild a RAID1 array on a RAID capable ATA controller.
|
|
.It Ic status
|
|
Get the status of an ATA RAID.
|
|
.It Ic mode
|
|
Without the
|
|
.Ar mode
|
|
argument, the current transfer mode of the
|
|
device are printed.
|
|
If the
|
|
.Ar mode
|
|
argument is given, the ATA driver
|
|
is asked to change the transfer mode to the one given.
|
|
The ATA driver
|
|
will reject modes that are not supported by the hardware.
|
|
Modes are given like
|
|
.Dq Li PIO3 ,
|
|
.Dq Li udma2 ,
|
|
.Dq Li udma100 ,
|
|
case does not matter.
|
|
.Pp
|
|
Currently supported modes are:
|
|
.Cm BIOSPIO , PIO0 , PIO1 , PIO2 , PIO3 , PIO4 , WDMA2 , UDMA2
|
|
(alias
|
|
.Cm UDMA33 ) ,
|
|
.Cm UDMA4
|
|
(alias
|
|
.Cm UDMA66 ) ,
|
|
.Cm UDMA5
|
|
(alias
|
|
.Cm UDMA100 ) ,
|
|
.Cm UDMA6
|
|
(alias
|
|
.Cm UDMA133 ) ,
|
|
.Cm SATA150 , SATA300 , USB , USB1 , USB2
|
|
and
|
|
.Cm BIOSDMA .
|
|
.It Ic cap
|
|
Show detailed info about the device on
|
|
.Ar device .
|
|
.It Ic spindown
|
|
Set or report timeout after which the
|
|
.Ar device
|
|
will be spun down.
|
|
To arm the timeout the device needs at least one more request after
|
|
setting the timeout.
|
|
To disable spindown, set the timeout to zero.
|
|
No further actions are needed in this case.
|
|
.It Ic info
|
|
Show info about the attached devices on the
|
|
.Ar channel .
|
|
The device name and manufacture/version strings are shown.
|
|
.It Ic list
|
|
Show info about all attached devices on all active controllers.
|
|
.El
|
|
.Sh EXAMPLES
|
|
To get information on devices attached to a channel,
|
|
use the command line:
|
|
.Pp
|
|
.Dl "atacontrol info ata0"
|
|
.Pp
|
|
To see the devices' current access modes, use the command line:
|
|
.Pp
|
|
.Dl "atacontrol mode ad0"
|
|
.Pp
|
|
which results in the modes of the devices being displayed as a string
|
|
like this:
|
|
.Pp
|
|
.Dl "current mode = UDMA100"
|
|
.Pp
|
|
You can set the mode with
|
|
.Nm
|
|
and a string like the above,
|
|
for example:
|
|
.Pp
|
|
.Dl "atacontrol mode ad0 PIO4"
|
|
.Pp
|
|
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.
|
|
1 disk would be attached to one channel and the other disk would be
|
|
attached to the other channel.
|
|
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
|
|
severely 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 you are
|
|
obtaining a replacement the server can run from 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 from 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 Highpoint or
|
|
Promise controller, you may then boot it into the 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
|
|
To spin down a disk after 30 minutes run
|
|
.Pp
|
|
.Dl "atacontrol spindown ad6 1800"
|
|
.Dl "dd if=/dev/ad6 of=/dev/null count=1"
|
|
.Pp
|
|
While any IO on the disk will arm the timer, using
|
|
.Xr dd 1
|
|
on the raw device will work in all cases, as when the disk is not
|
|
opened at all.
|
|
You can check the current setting with
|
|
.Pp
|
|
.Dl "atacontrol spindown ad6"
|
|
.Pp
|
|
You should not set a spindown timeout on a disk with
|
|
.Pa /
|
|
or syslog logging on it as the disk will be worn out spinning down and
|
|
up all the time.
|
|
.Sh SEE ALSO
|
|
.Xr ata 4
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility first appeared in
|
|
.Fx 4.6 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The
|
|
.Nm
|
|
utility was written by
|
|
.An S\(/oren Schmidt
|
|
.Aq sos@FreeBSD.org .
|
|
.Pp
|
|
This manual page was written by
|
|
.An S\(/oren Schmidt
|
|
.Aq sos@FreeBSD.org .
|