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