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 security
  75 .Ar device
  76 .Op Aq Ar security-command
  77 .Nm
  78 .Ic spindown
  79 .Ar device
  80 .Op Ar seconds
  81 .Nm
  82 .Ic list
  83 .Sh DESCRIPTION
  84 The
  85 .Nm
  86 utility is a control program that provides the user access and control to the
  87 .Fx
  88 .Xr ata 4
  89 subsystem.
  90 .Pp
  91 The
  92 .Nm
  93 utility
  94 can cause severe system crashes and loss of data if used improperly.
  95 Please
  96 exercise caution when using this command!
  97 .Pp
  98 The
  99 .Ar channel
 100 argument is the ATA channel device (e.g., ata0) on which to operate.
 101 The following commands are supported:
 102 .Bl -tag -width ".Ic addspare"
 103 .It Ic attach
 104 Attach an ATA
 105 .Ar channel .
 106 Devices on the channel are probed and attached as
 107 is done on boot.
 108 .It Ic detach
 109 Detach an ATA
 110 .Ar channel .
 111 Devices on the channel are removed from the kernel,
 112 and all outstanding transfers etc.\& are returned back to the system marked
 113 as failed.
 114 .It Ic reinit
 115 Reinitialize an ATA
 116 .Ar channel .
 117 Both devices on the channel are reset and
 118 initialized to the parameters the ATA driver has stored internally.
 119 Devices that have gone bad and no longer respond to the probe, or devices
 120 that have physically been removed, are removed from the kernel.
 121 Likewise are devices that show up during a reset, probed and attached.
 122 .It Ic create
 123 Create a
 124 .Ar type
 125 ATA RAID.
 126 The type can be
 127 .Cm RAID0
 128 (stripe),
 129 .Cm RAID1
 130 (mirror),
 131 .Cm RAID0+1 ,
 132 .Cm SPAN
 133 or
 134 .Cm JBOD .
 135 In case the RAID has a
 136 .Cm RAID0
 137 component,
 138 the
 139 .Ar interleave
 140 must be specified in number of sectors.
 141 The RAID will be created
 142 of the individual disks named
 143 .Bk -words
 144 .Ar disk0 ... diskN .
 145 .Ek
 146 .Pp
 147 Although the ATA driver allows for creating an ATA RAID on disks with any
 148 controller, there are restrictions.
 149 It is only possible to boot on
 150 an array if it is either located on a
 151 .Dq real
 152 ATA RAID controller like
 153 the Promise or Highpoint controllers, or if the RAID declared is of
 154 .Cm RAID1
 155 or
 156 .Cm SPAN
 157 type; in case of a
 158 .Cm SPAN ,
 159 the partition to boot must
 160 reside on the first disk in the SPAN.
 161 .It Ic delete
 162 Delete a RAID array on a RAID capable ATA controller.
 163 .It Ic addspare
 164 Add a spare disk to an existing RAID.
 165 .It Ic rebuild
 166 Rebuild a RAID1 array on a RAID capable ATA controller.
 167 .It Ic status
 168 Get the status of an ATA RAID.
 169 .It Ic mode
 170 Without the
 171 .Ar mode
 172 argument, the current transfer mode of the
 173 device are printed.
 174 If the
 175 .Ar mode
 176 argument is given, the ATA driver
 177 is asked to change the transfer mode to the one given.
 178 The ATA driver
 179 will reject modes that are not supported by the hardware.
 180 Modes are given like
 181 .Dq Li PIO3 ,
 182 .Dq Li udma2 ,
 183 .Dq Li udma100 ,
 184 case does not matter.
 185 .Pp
 186 Currently supported modes are:
 187 .Cm BIOSPIO , PIO0 , PIO1 , PIO2 , PIO3 , PIO4 , WDMA2 , UDMA2
 188 (alias
 189 .Cm UDMA33 ) ,
 190 .Cm UDMA4
 191 (alias
 192 .Cm UDMA66 ) ,
 193 .Cm UDMA5
 194 (alias
 195 .Cm UDMA100 ) ,
 196 .Cm UDMA6
 197 (alias
 198 .Cm UDMA133 ) ,
 199 .Cm SATA150 , SATA300 , USB , USB1 , USB2
 200 and
 201 .Cm BIOSDMA .
 202 .It Ic cap
 203 Show detailed info about the device on
 204 .Ar device .
 205 .It Ic security
 206 If no security command given, show details on the security status of the
 207 .Ar device .
 208 The following security commands are available:
 209 .Bl -tag -width "1234567"
 210 .It Ic freeze
 211 Freeze the security configuration of the device.
 212 Once frozen, no other security commands are accepted by the device.
 213 The device can only be unfrozen by a power cycle.
 214 An ATA Security compliant BIOS should freeze devices before booting the
 215 operating system.
 216 If your BIOS does not freeze the security configuration, you can freeze
 217 it after boot by adding an appropriate freeze command to e.g.\&
 218 .Pa /etc/rc.local .
 219 The freeze command is safe to execute on devices containing mounted
 220 filesystems.
 221 .It Ic set master
 222 Set the master password on the device and decrement the master password
 223 revision, if supported by the device.
 224 Setting the master password does not enable security.
 225 The master password serves as a fallback password to make a locked device
 226 usable again if the user password is lost.
 227 The set master command is safe to execute on devices containing
 228 mounted filesystems.
 229 .It Ic set user Bro Ic high | maximum Brc
 230 Set the user password and enable security.
 231 With security enabled, the device will be locked after power-on.
 232 In high security mode, either the user or the master password can
 233 unlock the device.
 234 In maximum security mode, only the user password can unlock the device.
 235 If the user password is lost, the master password can only be used to
 236 erase the device in order to make it usable again.
 237 The set user command is
 238 .Em not safe
 239 to execute on devices containing mounted filesystems.
 240 .It Ic unlock Bro Ic master | user Brc
 241 Unlock the device using either the master or the user password.
 242 Unlocking will make the device available for use by the system.
 243 The drive can only be unlocked by a master password if the security
 244 mode is high.  Unlocking does not disable security; after a reboot,
 245 the device will be locked again.
 246 The unlock command is safe to execute on devices containing mounted
 247 filesystems, but there is no point in doing so.
 248 .It Ic disable Bro Ic master | user Brc
 249 Disable security using either the master or the user password.
 250 By disabling security, the user password will be removed and
 251 the device will no longer be locked after power-on.  The master
 252 password is unaffected by the disable command.
 253 The disable command is safe to execute on devices containing mounted
 254 filesystems.
 255 .It Ic erase Bro Ic master | user Brc Op Ic enhanced
 256 Completely erase all blocks on the device.
 257 This will destroy all data on disk and then disable security.
 258 Erasing the device using the master password is the only way
 259 to recover a secured device in maximum security mode if the
 260 user password is lost.
 261 In normal erase mode, all addressable blocks are overwritten with zero.
 262 In enhanced erase mode, all blocks, including previously reallocated
 263 bad blocks, are overwritten with some predetermined pattern.
 264 Enhanced erase mode is not supported by all devices.
 265 Erasing a device will take a long time.
 266 Recent devices report the estimated erase time as part of the security
 267 status information.
 268 The erase command is
 269 .Em not safe
 270 to execute on devices containing mounted filesystems.
 271 .El
 272 .Pp
 273 .Em WARNING :
 274 The security commands can render a disk useless!
 275 .It Ic spindown
 276 Set or report timeout after which the
 277 .Ar device
 278 will be spun down.
 279 To arm the timeout the device needs at least one more request after
 280 setting the timeout.
 281 To disable spindown, set the timeout to zero.
 282 No further actions are needed in this case.
 283 .It Ic info
 284 Show info about the attached devices on the
 285 .Ar channel .
 286 The device name and manufacture/version strings are shown.
 287 .It Ic list
 288 Show info about all attached devices on all active controllers.
 289 .El
 290 .Sh EXAMPLES
 291 To get information on devices attached to a channel,
 292 use the command line:
 293 .Pp
 294 .Dl "atacontrol info ata0"
 295 .Pp
 296 To see the devices' current access modes, use the command line:
 297 .Pp
 298 .Dl "atacontrol mode ad0"
 299 .Pp
 300 which results in the modes of the devices being displayed as a string
 301 like this:
 302 .Pp
 303 .Dl "current mode = UDMA100"
 304 .Pp
 305 You can set the mode with
 306 .Nm
 307 and a string like the above,
 308 for example:
 309 .Pp
 310 .Dl "atacontrol mode ad0 PIO4"
 311 .Pp
 312 The new modes are set as soon as the
 313 .Nm
 314 command returns.
 315 .Pp
 316 The atacontrol command can also be used to create purely software
 317 RAID arrays in systems that do NOT have a "real" hardware RAID card
 318 such as a Highpoint or Promise card.
 319 A common scenario is a 1U server such as the HP DL320 G4 or G5.
 320 These servers contain a SATA controller that has 2 channels that can
 321 contain 2 disks per channel, but the servers are wired to only place
 322 a single SATA drive on each channel.
 323 These servers do have a "pseudo" RAID BIOS but it uses a proprietary
 324 format that is not compatible with the ata driver, and thus their
 325 RAID bios must be switched off.
 326 Another common scenario would be a Promise UDMA100 controller card
 327 that did not contain the Fasttrack RAID BIOS, but did contain 2
 328 UDMA channels.
 329 1 disk would be attached to one channel and the other disk would be
 330 attached to the other channel.
 331 It is NOT recommended to create such arrays on a primary/secondary
 332 pair on a SINGLE channel since the throughput of the mirror would be
 333 severely compromised, the ability to rebuild the array in the event
 334 of a disk failure would be greatly complicated, and if a disk
 335 controller electronics failed it could wedge the channel and take
 336 both disks in the mirror offline.
 337 (which would defeat the purpose of having a mirror in the first place)
 338 .Pp
 339 A quick and dirty way to create such a mirrored array on a new
 340 system is to boot off the FreeBSD install CD, do a minimal scratch
 341 install, abort out of the post install questions, and at the command
 342 line issue the command:
 343 .Pp
 344 .Dl "atacontrol create RAID1 ad4 ad6"
 345 .Pp
 346 then immediately issue a reboot and boot from the installation CD
 347 again, and during the installation, you will now see "ar0" listed
 348 as a disk to install on, and install on that instead of ad4, ad6, etc.
 349 .Pp
 350 To get information about the status of a RAID array in the system
 351 use the command line:
 352 .Pp
 353 .Dl "atacontrol status ar0"
 354 .Pp
 355 A typical output showing good health on a RAID array might be as
 356 follows:
 357 .Pp
 358 .Dl "ar0: ATA RAID1 subdisks: ad4 ad6 status: READY"
 359 .Pp
 360 If a disk drive in a RAID1 array dies the system will mark the disk
 361 in a DOWN state and change the array status to DEGRADED.
 362 This can ALSO happen in rare instances due to a power fluctuation or
 363 other event causing the system to not shutdown properly.
 364 In that case the output will look like the following:
 365 .Pp
 366 .Dl "ar0: ATA RAID1 subdisks: ad4 DOWN status: DEGRADED"
 367 .Pp
 368 For a mirrored RAID1 system the server WILL ALLOW you to remove a
 369 dead SATA disk drive (if the drive is in a hot-swap tray) without
 370 freezing up the system, so you can remove the disk and while you are
 371 obtaining a replacement the server can run from the active disk.
 372 The only caveat is that if the active disk is ad6, the system most
 373 likely will NOT be able to be rebooted since most systems only
 374 support booting from the first disk drive.
 375 .Pp
 376 To deactivate the DOWN disk ad6 to allow for it to be ejected, use
 377 the following:
 378 .Pp
 379 .Dl "atacontrol detach ata3"
 380 .Pp
 381 then eject or remove the disk.
 382 Note that this only works if the 2 disks in the mirror are on separate
 383 channels (which is the standard setup for 1-U servers like the HP DL320).
 384 When the new disk drive is obtained, make sure it is blank, then shut
 385 the system down.
 386 At this point, if the system has a RAID array card like a Highpoint or
 387 Promise controller, you may then boot it into the BIOS of the card and use
 388 the manufacturers RAID array rebuild utilities to rebuild the array.
 389 .Pp
 390 If the system has a pure software array and is not using a "real" ATA
 391 RAID controller, then shut the system down, make sure that the disk
 392 that was still working is moved to the bootable position (channel 0
 393 or whatever the BIOS allows the system to boot from) and the blank disk
 394 is placed in the secondary position, then boot the system into
 395 single-user mode and issue the command:
 396 .Pp
 397 .Dl "atacontrol addspare ar0 ad6"
 398 .Dl "atacontrol rebuild ar0"
 399 .Pp
 400 If the disk drive did NOT fail and the RAID array became unmirrored due
 401 to a software glitch or improper shutdown, then a slightly different
 402 process must be followed.
 403 Begin by issuing the detach command (this shows the detach for disk ad6,
 404 the primary master on channel 3):
 405 .Pp
 406 .Dl "atacontrol detach ata3"
 407 .Pp
 408 then reboot the system into single-user mode.
 409 (don't just init the system, reboot it so that both disks get probed)
 410 You will probably see TWO mirrored RAID arrays appear during the boot
 411 messages, ar0 and ar1.
 412 Issue the command:
 413 .Pp
 414 .Dl "atacontrol delete ar1"
 415 .Dl "atacontrol addspare ar0 ad6"
 416 .Pp
 417 Now a status command will show the array rebuilding.
 418 .Pp
 419 To display the security status of a disk run:
 420 .Pp
 421 .Dl "atacontrol security ad6"
 422 .Pp
 423 If the security configuration has not been frozen by the BIOS, freeze it
 424 to prevent further changes using:
 425 .Pp
 426 .Dl "atacontrol security ad6 freeze"
 427 .Pp
 428 To have the security configuration frozen as part of booting the system,
 429 add the above to
 430 .Pa /etc/rc.local
 431 or a similar facility provided by
 432 .Xr rc 8 .
 433 .Pp
 434 To use the ATA Security commands to completely wipe the disk,
 435 you can first set a user password, and then use that to erase
 436 the disk in enhanced mode.
 437 .Pp
 438 .Dl "atacontrol security ad6 set user"
 439 .Dl "atacontrol security ad6 erase user enhanced"
 440 .Pp
 441 The second command may take literally hours to complete while
 442 the disk is overwriting all blocks.
 443 Using the enhanced erase command has the advantage over a simple
 444 .Pp
 445 .Dl "dd if=/dev/zero of=/dev/ad6"
 446 .Pp
 447 in that erase will also erase blocks not directly addressable by dd due
 448 to bad block reallocations by the disk.
 449 If you are paranoid, you should do both.
 450 .Pp
 451 To spin down a disk after 30 minutes run
 452 .Pp
 453 .Dl "atacontrol spindown ad6 1800"
 454 .Dl "dd if=/dev/ad6 of=/dev/null count=1"
 455 .Pp
 456 While any IO on the disk will arm the timer, using
 457 .Xr dd 1
 458 on the raw device will work in all cases, as when the disk is not
 459 opened at all.
 460 You can check the current setting with
 461 .Pp
 462 .Dl "atacontrol spindown ad6"
 463 .Pp
 464 You should not set a spindown timeout on a disk with
 465 .Pa /
 466 or syslog logging on it as the disk will be worn out spinning down and
 467 up all the time.
 468 .Sh SEE ALSO
 469 .Xr ata 4
 470 .Sh HISTORY
 471 The
 472 .Nm
 473 utility first appeared in
 474 .Fx 4.6 .
 475 .Sh AUTHORS
 476 .An -nosplit
 477 The
 478 .Nm
 479 utility was written by
 480 .An S\(/oren Schmidt
 481 .Aq sos@FreeBSD.org .
 482 Support for ATA Security was added by
 483 .An Daniel Roethlisberger
 484 .Aq daniel@roe.ch .
 485 .Pp
 486 This manual page was written by
 487 .An S\(/oren Schmidt
 488 .Aq sos@FreeBSD.org .