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