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 June 25, 2008
  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 .Nm
  67 .Ic info
  68 .Ar channel
  69 .Nm
  70 .Ic cap
  71 .Ar device
  72 .Nm
  73 .Ic spindown
  74 .Ar device
  75 .Op Ar seconds
  76 .Nm
  77 .Ic list
  78 .Sh DESCRIPTION
  79 The
  80 .Nm
  81 utility is a control program that provides the user access and control to the
  82 .Fx
  83 .Xr ata 4
  84 subsystem.
  85 .Pp
  86 The
  87 .Nm
  88 utility
  89 can cause severe system crashes and loss of data if used improperly.
  90 Please
  91 exercise caution when using this command!
  92 .Pp
  93 The
  94 .Ar channel
  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"
  98 .It Ic attach
  99 Attach an ATA
 100 .Ar channel .
 101 Devices on the channel are probed and attached as
 102 is done on boot.
 103 .It Ic detach
 104 Detach an ATA
 105 .Ar channel .
 106 Devices on the channel are removed from the kernel,
 107 and all outstanding transfers etc.\& are returned back to the system marked
 108 as failed.
 109 .It Ic reinit
 110 Reinitialize an ATA
 111 .Ar channel .
 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.
 117 .It Ic create
 118 Create a
 119 .Ar type
 120 ATA RAID.
 121 The type can be
 122 .Cm RAID0
 123 (stripe),
 124 .Cm RAID1
 125 (mirror),
 126 .Cm RAID0+1 ,
 127 .Cm SPAN
 128 or
 129 .Cm JBOD .
 130 In case the RAID has a
 131 .Cm RAID0
 132 component,
 133 the
 134 .Ar interleave
 135 must be specified in number of sectors.
 136 The RAID will be created
 137 of the individual disks named
 138 .Bk -words
 139 .Ar disk0 ... diskN .
 140 .Ek
 141 .Pp
 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
 146 .Dq real
 147 ATA RAID controller like
 148 the Promise or Highpoint controllers, or if the RAID declared is of
 149 .Cm RAID1
 150 or
 151 .Cm SPAN
 152 type; in case of a
 153 .Cm SPAN ,
 154 the partition to boot must
 155 reside on the first disk in the SPAN.
 156 .It Ic delete
 157 Delete a RAID array on a RAID capable ATA controller.
 158 .It Ic addspare
 159 Add a spare disk to an existing RAID.
 160 .It Ic rebuild
 161 Rebuild a RAID1 array on a RAID capable ATA controller.
 162 .It Ic status
 163 Get the status of an ATA RAID.
 164 .It Ic mode
 165 Without the mode argument, the current transfer modes of the
 166 device are printed.
 167 If the mode argument is given, the ATA driver
 168 is asked to change the transfer mode to the one given.
 169 The ATA driver
 170 will reject modes that are not supported by the hardware.
 171 Modes are given like
 172 .Dq Li PIO3 ,
 173 .Dq Li udma2 ,
 174 .Dq Li udma100 ,
 175 case does not matter.
 176 .Pp
 177 Currently supported modes are:
 178 .Cm PIO0 , PIO1 , PIO2 , PIO3 , PIO4 ,
 179 .Cm WDMA2 ,
 180 .Cm UDMA2
 181 (alias
 182 .Cm UDMA33 ) ,
 183 .Cm UDMA4
 184 (alias
 185 .Cm UDMA66 ) ,
 186 .Cm UDMA5
 187 (alias
 188 .Cm UDMA100 )
 189 and
 190 .Cm UDMA6
 191 (alias
 192 .Cm UDMA133 ) .
 193 The device name and manufacture/version strings are shown.
 194 .It Ic cap
 195 Show detailed info about the device on
 196 .Ar device .
 197 .It Ic spindown
 198 Set or report timeout after which the
 199 .Ar device
 200 will be spun down.
 201 To arm the timeout the device needs at least one more request after
 202 setting the timeout.
 203 To disable spindown, set the timeout to zero.
 204 No further actions are needed in this case.
 205 .It Ic info
 206 Show info about the attached devices on the
 207 .Ar channel .
 208 .It Ic list
 209 Show info about all attached devices on all active controllers.
 210 .El
 211 .Sh EXAMPLES
 212 To get information on devices attached to a channel,
 213 use the command line:
 214 .Pp
 215 .Dl "atacontrol info ata0"
 216 .Pp
 217 To see the devices' current access modes, use the command line:
 218 .Pp
 219 .Dl "atacontrol mode ad0"
 220 .Pp
 221 which results in the modes of the devices being displayed as a string
 222 like this:
 223 .Pp
 224 .Dl "current mode = UDMA100"
 225 .Pp
 226 You can set the mode with
 227 .Nm
 228 and a string like the above,
 229 for example:
 230 .Pp
 231 .Dl "atacontrol mode ad0 PIO4"
 232 .Pp
 233 The new modes are set as soon as the
 234 .Nm
 235 command returns.
 236 .Pp
 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
 249 UDMA channels.
 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)
 259 .Pp
 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:
 264 .Pp
 265 .Dl "atacontrol create RAID1 ad4 ad6"
 266 .Pp
 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.
 270 .Pp
 271 To get information about the status of a RAID array in the system
 272 use the command line:
 273 .Pp
 274 .Dl "atacontrol status ar0"
 275 .Pp
 276 A typical output showing good health on a RAID array might be as
 277 follows:
 278 .Pp
 279 .Dl "ar0: ATA RAID1 subdisks: ad4 ad6 status: READY"
 280 .Pp
 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:
 286 .Pp
 287 .Dl "ar0: ATA RAID1 subdisks: ad4 DOWN status: DEGRADED"
 288 .Pp
 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.
 296 .Pp
 297 To deactivate the DOWN disk ad6 to allow for it to be ejected, use
 298 the following:
 299 .Pp
 300 .Dl "atacontrol detach ata3"
 301 .Pp
 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
 306 the system down.
 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.
 310 .Pp
 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:
 317 .Pp
 318 .Dl "atacontrol addspare ar0 ad6"
 319 .Dl "atacontrol rebuild ar0"
 320 .Pp
 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):
 326 .Pp
 327 .Dl "atacontrol detach ata3"
 328 .Pp
 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.
 333 Issue the command:
 334 .Pp
 335 .Dl "atacontrol delete ar1"
 336 .Dl "atacontrol addspare ar0 ad6"
 337 .Pp
 338 Now a status command will show the array rebuilding.
 339 .Pp
 340 To spin down a disk after 30 minutes run
 341 .Pp
 342 .Dl "atacontrol spindown ad6 1800"
 343 .Dl "dd if=/dev/ad6 of=/dev/null count=1"
 344 .Pp
 345 While any IO on the disk will arm the timer, using
 346 .Xr dd 1
 347 on the raw device will work in all cases, as when the disk is not
 348 opened at all.
 349 You can check the current setting with
 350 .Pp
 351 .Dl "atacontrol spindown ad6"
 352 .Pp
 353 You should not set a spindown timeout on a disk with
 354 .Pa /
 355 or syslog logging on it as the disk will be worn out spinning down and
 356 up all the time.
 357 .Sh SEE ALSO
 358 .Xr ata 4
 359 .Sh HISTORY
 360 The
 361 .Nm
 362 utility first appeared in
 363 .Fx 4.6 .
 364 .Sh AUTHORS
 365 .An -nosplit
 366 The
 367 .Nm
 368 utility was written by
 369 .An S\(/oren Schmidt
 370 .Aq sos@FreeBSD.org .
 371 .Pp
 372 This manual page was written by
 373 .An S\(/oren Schmidt
 374 .Aq sos@FreeBSD.org .