sbin/atacontrol/atacontrol.8

   1 .\"
   2 .\" Copyright (c) 2000,2001,2002 Søren Schmidt <sos@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   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.
  13 .\"
  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
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd October 9, 2011
  29 .Dt ATACONTROL 8
  30 .Os
  31 .Sh NAME
  32 .Nm atacontrol
  33 .Nd ATA device driver control program
  34 .Pp
  35 This utility was
  36 .Em deprecated
  37 in
  38 .Fx 9.0 .
  39 See
  40 .Sx NOTES .
  41 .Sh SYNOPSIS
  42 .Nm
  43 .Aq Ar command
  44 .Ar args
  45 .Pp
  46 .Nm
  47 .Ic attach
  48 .Ar channel
  49 .Nm
  50 .Ic detach
  51 .Ar channel
  52 .Nm
  53 .Ic reinit
  54 .Ar channel
  55 .Nm
  56 .Ic create
  57 .Ar type Oo Ar interleave Oc Ar disk0 ... diskN
  58 .Nm
  59 .Ic delete
  60 .Ar raid
  61 .Nm
  62 .Ic addspare
  63 .Ar raid disk
  64 .Nm
  65 .Ic rebuild
  66 .Ar raid
  67 .Nm
  68 .Ic status
  69 .Ar raid
  70 .Nm
  71 .Ic mode
  72 .Ar device
  73 .Op Ar mode
  74 .Nm
  75 .Ic info
  76 .Ar channel
  77 .Nm
  78 .Ic cap
  79 .Ar device
  80 .Nm
  81 .Ic spindown
  82 .Ar device
  83 .Op Ar seconds
  84 .Nm
  85 .Ic list
  86 .Sh DESCRIPTION
  87 The
  88 .Nm
  89 utility is a control program that provides the user access and control to the
  90 .Fx
  91 .Xr ata 4
  92 subsystem.
  93 .Pp
  94 The
  95 .Nm
  96 utility
  97 can cause severe system crashes and loss of data if used improperly.
  98 Please
  99 exercise caution when using this command!
 100 .Pp
 101 The
 102 .Ar channel
 103 argument is the ATA channel device (e.g., ata0) on which to operate.
 104 The following commands are supported:
 105 .Bl -tag -width ".Ic addspare"
 106 .It Ic attach
 107 Attach an ATA
 108 .Ar channel .
 109 Devices on the channel are probed and attached as
 110 is done on boot.
 111 .It Ic detach
 112 Detach an ATA
 113 .Ar channel .
 114 Devices on the channel are removed from the kernel,
 115 and all outstanding transfers etc.\& are returned back to the system marked
 116 as failed.
 117 .It Ic reinit
 118 Reinitialize an ATA
 119 .Ar channel .
 120 Both devices on the channel are reset and
 121 initialized to the parameters the ATA driver has stored internally.
 122 Devices that have gone bad and no longer respond to the probe, or devices
 123 that have physically been removed, are removed from the kernel.
 124 Likewise are devices that show up during a reset, probed and attached.
 125 .It Ic create
 126 Create a
 127 .Ar type
 128 ATA RAID.
 129 The type can be
 130 .Cm RAID0
 131 (stripe),
 132 .Cm RAID1
 133 (mirror),
 134 .Cm RAID0+1 ,
 135 .Cm SPAN
 136 or
 137 .Cm JBOD .
 138 In case the RAID has a
 139 .Cm RAID0
 140 component,
 141 the
 142 .Ar interleave
 143 must be specified in number of sectors.
 144 The RAID will be created
 145 of the individual disks named
 146 .Bk -words
 147 .Ar disk0 ... diskN .
 148 .Ek
 149 .Pp
 150 Although the ATA driver allows for creating an ATA RAID on disks with any
 151 controller, there are restrictions.
 152 It is only possible to boot on
 153 an array if it is either located on a
 154 .Dq real
 155 ATA RAID controller like
 156 the Promise or Highpoint controllers, or if the RAID declared is of
 157 .Cm RAID1
 158 or
 159 .Cm SPAN
 160 type; in case of a
 161 .Cm SPAN ,
 162 the partition to boot must
 163 reside on the first disk in the SPAN.
 164 .It Ic delete
 165 Delete a RAID array on a RAID capable ATA controller.
 166 .It Ic addspare
 167 Add a spare disk to an existing RAID.
 168 .It Ic rebuild
 169 Rebuild a RAID1 array on a RAID capable ATA controller.
 170 .It Ic status
 171 Get the status of an ATA RAID.
 172 .It Ic mode
 173 Without the
 174 .Ar mode
 175 argument, the current transfer mode of the
 176 device are printed.
 177 If the
 178 .Ar mode
 179 argument is given, the ATA driver
 180 is asked to change the transfer mode to the one given.
 181 The ATA driver
 182 will reject modes that are not supported by the hardware.
 183 Modes are given like
 184 .Dq Li PIO3 ,
 185 .Dq Li udma2 ,
 186 .Dq Li udma100 ,
 187 case does not matter.
 188 .Pp
 189 Currently supported modes are:
 190 .Cm BIOSPIO , PIO0 , PIO1 , PIO2 , PIO3 , PIO4 , WDMA2 , UDMA2
 191 (alias
 192 .Cm UDMA33 ) ,
 193 .Cm UDMA4
 194 (alias
 195 .Cm UDMA66 ) ,
 196 .Cm UDMA5
 197 (alias
 198 .Cm UDMA100 ) ,
 199 .Cm UDMA6
 200 (alias
 201 .Cm UDMA133 ) ,
 202 .Cm SATA150 , SATA300 , USB , USB1 , USB2
 203 and
 204 .Cm BIOSDMA .
 205 .It Ic cap
 206 Show detailed info about the device on
 207 .Ar device .
 208 .It Ic spindown
 209 Set or report timeout after which the
 210 .Ar device
 211 will be spun down.
 212 To arm the timeout the device needs at least one more request after
 213 setting the timeout.
 214 To disable spindown, set the timeout to zero.
 215 No further actions are needed in this case.
 216 .It Ic info
 217 Show info about the attached devices on the
 218 .Ar channel .
 219 The device name and manufacture/version strings are shown.
 220 .It Ic list
 221 Show info about all attached devices on all active controllers.
 222 .El
 223 .Sh EXAMPLES
 224 To get information on devices attached to a channel,
 225 use the command line:
 226 .Pp
 227 .Dl "atacontrol info ata0"
 228 .Pp
 229 To see the devices' current access modes, use the command line:
 230 .Pp
 231 .Dl "atacontrol mode ad0"
 232 .Pp
 233 which results in the modes of the devices being displayed as a string
 234 like this:
 235 .Pp
 236 .Dl "current mode = UDMA100"
 237 .Pp
 238 You can set the mode with
 239 .Nm
 240 and a string like the above,
 241 for example:
 242 .Pp
 243 .Dl "atacontrol mode ad0 PIO4"
 244 .Pp
 245 The new modes are set as soon as the
 246 .Nm
 247 command returns.
 248 .Pp
 249 The atacontrol command can also be used to create purely software
 250 RAID arrays in systems that do NOT have a "real" hardware RAID card
 251 such as a Highpoint or Promise card.
 252 A common scenario is a 1U server such as the HP DL320 G4 or G5.
 253 These servers contain a SATA controller that has 2 channels that can
 254 contain 2 disks per channel, but the servers are wired to only place
 255 a single SATA drive on each channel.
 256 These servers do have a "pseudo" RAID BIOS but it uses a proprietary
 257 format that is not compatible with the ata driver, and thus their
 258 RAID bios must be switched off.
 259 Another common scenario would be a Promise UDMA100 controller card
 260 that did not contain the Fasttrack RAID BIOS, but did contain 2
 261 UDMA channels.
 262 1 disk would be attached to one channel and the other disk would be
 263 attached to the other channel.
 264 It is NOT recommended to create such arrays on a primary/secondary
 265 pair on a SINGLE channel since the throughput of the mirror would be
 266 severely compromised, the ability to rebuild the array in the event
 267 of a disk failure would be greatly complicated, and if a disk
 268 controller electronics failed it could wedge the channel and take
 269 both disks in the mirror offline.
 270 (which would defeat the purpose of having a mirror in the first place)
 271 .Pp
 272 A quick and dirty way to create such a mirrored array on a new
 273 system is to boot off the FreeBSD install CD, do a minimal scratch
 274 install, abort out of the post install questions, and at the command
 275 line issue the command:
 276 .Pp
 277 .Dl "atacontrol create RAID1 ad4 ad6"
 278 .Pp
 279 then immediately issue a reboot and boot from the installation CD
 280 again, and during the installation, you will now see "ar0" listed
 281 as a disk to install on, and install on that instead of ad4, ad6, etc.
 282 .Pp
 283 To get information about the status of a RAID array in the system
 284 use the command line:
 285 .Pp
 286 .Dl "atacontrol status ar0"
 287 .Pp
 288 A typical output showing good health on a RAID array might be as
 289 follows:
 290 .Pp
 291 .Dl "ar0: ATA RAID1 subdisks: ad4 ad6 status: READY"
 292 .Pp
 293 If a disk drive in a RAID1 array dies the system will mark the disk
 294 in a DOWN state and change the array status to DEGRADED.
 295 This can ALSO happen in rare instances due to a power fluctuation or
 296 other event causing the system to not shutdown properly.
 297 In that case the output will look like the following:
 298 .Pp
 299 .Dl "ar0: ATA RAID1 subdisks: ad4 DOWN status: DEGRADED"
 300 .Pp
 301 For a mirrored RAID1 system the server WILL ALLOW you to remove a
 302 dead SATA disk drive (if the drive is in a hot-swap tray) without
 303 freezing up the system, so you can remove the disk and while you are
 304 obtaining a replacement the server can run from the active disk.
 305 The only caveat is that if the active disk is ad6, the system most
 306 likely will NOT be able to be rebooted since most systems only
 307 support booting from the first disk drive.
 308 .Pp
 309 To deactivate the DOWN disk ad6 to allow for it to be ejected, use
 310 the following:
 311 .Pp
 312 .Dl "atacontrol detach ata3"
 313 .Pp
 314 then eject or remove the disk.
 315 Note that this only works if the 2 disks in the mirror are on separate
 316 channels (which is the standard setup for 1-U servers like the HP DL320).
 317 When the new disk drive is obtained, make sure it is blank, then shut
 318 the system down.
 319 At this point, if the system has a RAID array card like a Highpoint or
 320 Promise controller, you may then boot it into the BIOS of the card and use
 321 the manufacturers RAID array rebuild utilities to rebuild the array.
 322 .Pp
 323 If the system has a pure software array and is not using a "real" ATA
 324 RAID controller, then shut the system down, make sure that the disk
 325 that was still working is moved to the bootable position (channel 0
 326 or whatever the BIOS allows the system to boot from) and the blank disk
 327 is placed in the secondary position, then boot the system into
 328 single-user mode and issue the command:
 329 .Pp
 330 .Dl "atacontrol addspare ar0 ad6"
 331 .Dl "atacontrol rebuild ar0"
 332 .Pp
 333 If the disk drive did NOT fail and the RAID array became unmirrored due
 334 to a software glitch or improper shutdown, then a slightly different
 335 process must be followed.
 336 Begin by issuing the detach command (this shows the detach for disk ad6,
 337 the primary master on channel 3):
 338 .Pp
 339 .Dl "atacontrol detach ata3"
 340 .Pp
 341 then reboot the system into single-user mode.
 342 (don't just init the system, reboot it so that both disks get probed)
 343 You will probably see TWO mirrored RAID arrays appear during the boot
 344 messages, ar0 and ar1.
 345 Issue the command:
 346 .Pp
 347 .Dl "atacontrol delete ar1"
 348 .Dl "atacontrol addspare ar0 ad6"
 349 .Pp
 350 Now a status command will show the array rebuilding.
 351 .Pp
 352 To spin down a disk after 30 minutes run
 353 .Pp
 354 .Dl "atacontrol spindown ad6 1800"
 355 .Dl "dd if=/dev/ad6 of=/dev/null count=1"
 356 .Pp
 357 While any IO on the disk will arm the timer, using
 358 .Xr dd 1
 359 on the raw device will work in all cases, as when the disk is not
 360 opened at all.
 361 You can check the current setting with
 362 .Pp
 363 .Dl "atacontrol spindown ad6"
 364 .Pp
 365 You should not set a spindown timeout on a disk with
 366 .Pa /
 367 or syslog logging on it as the disk will be worn out spinning down and
 368 up all the time.
 369 .Sh SEE ALSO
 370 .Xr ata 4 ,
 371 .Xr cam 4 ,
 372 .Xr camcontrol 8
 373 .Sh HISTORY
 374 The
 375 .Nm
 376 utility first appeared in
 377 .Fx 4.6 .
 378 .Pp
 379 .Nm
 380 was deprecated in
 381 .Fx 9.0 .
 382 .Sh AUTHORS
 383 .An -nosplit
 384 The
 385 .Nm
 386 utility was written by
 387 .An S\(/oren Schmidt
 388 .Aq sos@FreeBSD.org .
 389 .Pp
 390 This manual page was written by
 391 .An S\(/oren Schmidt
 392 .Aq sos@FreeBSD.org .
 393 .Sh NOTES
 394 The
 395 .Nm
 396 utility was deprecated in
 397 .Fx 9.0 .
 398 When
 399 .Bd -ragged -offset indent
 400 .Cd "options ATA_CAM"
 401 .Ed
 402 .Pp
 403 is compiled into the kernel, then
 404 .Xr camcontrol 8
 405 must be used instead.