2 .\" Copyright (c) 2000,2001,2002 Søren Schmidt <sos@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd ATA device driver control program
50 .Ar type Oo Ar interleave Oc Ar disk0 ... diskN
81 utility is a control program that provides the user access and control to the
89 can cause severe system crashes and loss of data if used improperly.
91 exercise caution when using this command!
95 argument is the ATA channel device (e.g., ata0) on which to operate.
96 The following commands are supported:
97 .Bl -tag -width "rebuild"
101 Devices on the channel are probed and attached as
106 Devices on the channel are removed from the kernel,
107 and all outstanding transfers etc.\& are returned back to the system marked
112 Both devices on the channel are reset and
113 initialized to the parameters the ATA driver has stored internally.
114 Devices that have gone bad and no longer respond to the probe, or devices
115 that have physically been removed, are removed from the kernel.
116 Likewise are devices that show up during a reset, probed and attached.
130 In case the RAID has a
135 must be specified in number of sectors.
136 The RAID will be created
137 of the individual disks named
139 .Ar disk0 ... diskN .
142 Although the ATA driver allows for creating an ATA RAID on disks with any
143 controller, there are restrictions.
144 It is only possible to boot on
145 an array if it is either located on a
147 ATA RAID controller like
148 the Promise or Highpoint controllers, or if the RAID declared is of
154 the partition to boot must
155 reside on the first disk in the SPAN.
157 Delete a RAID array on a RAID capable ATA controller.
159 Add a spare disk to an existing RAID.
161 Rebuild a RAID1 array on a RAID capable ATA controller.
163 Get the status of an ATA RAID.
165 Without the mode argument, the current transfer modes of the
167 If the mode argument is given, the ATA driver
168 is asked to change the transfer mode to the one given.
170 will reject modes that are not supported by the hardware.
175 case does not matter.
177 Currently supported modes are:
178 .Cm PIO0 , PIO1 , PIO2 , PIO3 , PIO4 ,
193 The device name and manufacture/version strings are shown.
195 Show detailed info about the device on
198 Set or report timeout after which the
201 To arm the timeout the device needs at least one more request after
203 To disable spindown, set the timeout to zero.
204 No further actions are needed in this case.
206 Show info about the attached devices on the
209 Show info about all attached devices on all active controllers.
212 To get information on devices attached to a channel,
213 use the command line:
215 .Dl "atacontrol info ata0"
217 To see the devices' current access modes, use the command line:
219 .Dl "atacontrol mode ad0"
221 which results in the modes of the devices being displayed as a string
224 .Dl "current mode = UDMA100"
226 You can set the mode with
228 and a string like the above,
231 .Dl "atacontrol mode ad0 PIO4"
233 The new modes are set as soon as the
237 The atacontrol command can also be used to create purely software
238 RAID arrays in systems that do NOT have a "real" hardware RAID card
239 such as a Highpoint or Promise card.
240 A common scenario is a 1U server such as the HP DL320 G4 or G5.
241 These servers contain a SATA controller that has 2 channels that can
242 contain 2 disks per channel, but the servers are wired to only place
243 a single SATA drive on each channel.
244 These servers do have a "pseudo" RAID BIOS but it uses a proprietary
245 format that is not compatible with the ata driver, and thus their
246 RAID bios must be switched off.
247 Another common scenario would be a Promise UDMA100 controller card
248 that did not contain the Fasttrack RAID BIOS, but did contain 2
250 1 disk would be attached to one channel and the other disk would be
251 attached to the other channel.
252 It is NOT recommended to create such arrays on a primary/secondary
253 pair on a SINGLE channel since the throughput of the mirror would be
254 severely compromised, the ability to rebuild the array in the event
255 of a disk failure would be greatly complicated, and if a disk
256 controller electronics failed it could wedge the channel and take
257 both disks in the mirror offline.
258 (which would defeat the purpose of having a mirror in the first place)
260 A quick and dirty way to create such a mirrored array on a new
261 system is to boot off the FreeBSD install CD, do a minimal scratch
262 install, abort out of the post install questions, and at the command
263 line issue the command:
265 .Dl "atacontrol create RAID1 ad4 ad6"
267 then immediately issue a reboot and boot from the installation CD
268 again, and during the installation, you will now see "ar0" listed
269 as a disk to install on, and install on that instead of ad4, ad6, etc.
271 To get information about the status of a RAID array in the system
272 use the command line:
274 .Dl "atacontrol status ar0"
276 A typical output showing good health on a RAID array might be as
279 .Dl "ar0: ATA RAID1 subdisks: ad4 ad6 status: READY"
281 If a disk drive in a RAID1 array dies the system will mark the disk
282 in a DOWN state and change the array status to DEGRADED.
283 This can ALSO happen in rare instances due to a power fluctuation or
284 other event causing the system to not shutdown properly.
285 In that case the output will look like the following:
287 .Dl "ar0: ATA RAID1 subdisks: ad4 DOWN status: DEGRADED"
289 For a mirrored RAID1 system the server WILL ALLOW you to remove a
290 dead SATA disk drive (if the drive is in a hot-swap tray) without
291 freezing up the system, so you can remove the disk and while you are
292 obtaining a replacement the server can run from the active disk.
293 The only caveat is that if the active disk is ad6, the system most
294 likely will NOT be able to be rebooted since most systems only
295 support booting from the first disk drive.
297 To deactivate the DOWN disk ad6 to allow for it to be ejected, use
300 .Dl "atacontrol detach ata3"
302 then eject or remove the disk.
303 Note that this only works if the 2 disks in the mirror are on separate
304 channels (which is the standard setup for 1-U servers like the HP DL320).
305 When the new disk drive is obtained, make sure it is blank, then shut
307 At this point, if the system has a RAID array card like a Highpoint or
308 Promise controller, you may then boot it into the BIOS of the card and use
309 the manufacturers RAID array rebuild utilities to rebuild the array.
311 If the system has a pure software array and is not using a "real" ATA
312 RAID controller, then shut the system down, make sure that the disk
313 that was still working is moved to the bootable position (channel 0
314 or whatever the BIOS allows the system to boot from) and the blank disk
315 is placed in the secondary position, then boot the system into
316 single-user mode and issue the command:
318 .Dl "atacontrol addspare ar0 ad6"
319 .Dl "atacontrol rebuild ar0"
321 If the disk drive did NOT fail and the RAID array became unmirrored due
322 to a software glitch or improper shutdown, then a slightly different
323 process must be followed.
324 Begin by issuing the detach command (this shows the detach for disk ad6,
325 the primary master on channel 3):
327 .Dl "atacontrol detach ata3"
329 then reboot the system into single-user mode.
330 (don't just init the system, reboot it so that both disks get probed)
331 You will probably see TWO mirrored RAID arrays appear during the boot
332 messages, ar0 and ar1.
335 .Dl "atacontrol delete ar1"
336 .Dl "atacontrol addspare ar0 ad6"
338 Now a status command will show the array rebuilding.
340 To spin down a disk after 30 minutes run
342 .Dl "atacontrol spindown ad6 1800"
343 .Dl "dd if=/dev/ad6 of=/dev/null count=1"
345 While any IO on the disk will arm the timer, using
347 on the raw device will work in all cases, as when the disk is not
349 You can check the current setting with
351 .Dl "atacontrol spindown ad6"
353 You should not set a spindown timeout on a disk with
355 or syslog logging on it as the disk will be worn out spinning down and
362 utility first appeared in
368 utility was written by
370 .Aq sos@FreeBSD.org .
372 This manual page was written by
374 .Aq sos@FreeBSD.org .