usr.sbin/mfiutil/mfiutil.8

   1 .\" Copyright (c) 2008, 2009 Yahoo!, Inc.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. The names of the authors may not be used to endorse or promote
  13 .\"    products derived from this software without specific prior written
  14 .\"    permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD: src/usr.sbin/mfiutil/mfiutil.8,v 1.8 2011/06/20 21:28:50 bz Exp $
  29 .\"
  30 .Dd August 1, 2011
  31 .Dt MFIUTIL 8
  32 .Os
  33 .Sh NAME
  34 .Nm mfiutil
  35 .Nd Utility for managing LSI MegaRAID SAS controllers
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Cm version
  39 .Nm
  40 .Op Fl u Ar unit
  41 .Cm show adapter
  42 .Nm
  43 .Op Fl u Ar unit
  44 .Cm show battery
  45 .Nm
  46 .Op Fl d
  47 .Op Fl e
  48 .Op Fl u Ar unit
  49 .Cm show config
  50 .Nm
  51 .Op Fl u Ar unit
  52 .Cm show drives
  53 .Nm
  54 .Op Fl u Ar unit
  55 .Cm show events
  56 .Op Fl c Ar class
  57 .Op Fl l Ar locale
  58 .Op Fl n Ar count
  59 .Op Fl v
  60 .Op Ar start Op Ar stop
  61 .Nm
  62 .Op Fl u Ar unit
  63 .Cm show firmware
  64 .Nm
  65 .Op Fl u Ar unit
  66 .Cm show logstate
  67 .Nm
  68 .Op Fl d
  69 .Op Fl e
  70 .Op Fl u Ar unit
  71 .Cm show patrol
  72 .Nm
  73 .Op Fl d
  74 .Op Fl e
  75 .Op Fl u Ar unit
  76 .Cm show progress
  77 .Nm
  78 .Op Fl u Ar unit
  79 .Cm show volumes
  80 .Nm
  81 .Op Fl u Ar unit
  82 .Cm fail Ar drive
  83 .Nm
  84 .Op Fl u Ar unit
  85 .Cm good Ar drive
  86 .Nm
  87 .Op Fl u Ar unit
  88 .Cm rebuild Ar drive
  89 .Nm
  90 .Op Fl u Ar unit
  91 .Cm drive progress Ar drive
  92 .Nm
  93 .Op Fl u Ar unit
  94 .Cm drive clear Ar drive Brq "start | stop"
  95 .Nm
  96 .Op Fl u Ar unit
  97 .Cm start rebuild Ar drive
  98 .Nm
  99 .Op Fl u Ar unit
 100 .Cm abort rebuild Ar drive
 101 .Nm
 102 .Op Fl u Ar unit
 103 .Cm locate Ar drive Brq "on | off"
 104 .Nm
 105 .Op Fl u Ar unit
 106 .Cm cache Ar volume Op Ar setting Op Ar value
 107 .Nm
 108 .Op Fl u Ar unit
 109 .Cm name Ar volume Ar name
 110 .Nm
 111 .Op Fl u Ar unit
 112 .Cm volume progress Ar volume
 113 .Nm
 114 .Op Fl u Ar unit
 115 .Cm clear
 116 .Nm
 117 .Op Fl u Ar unit
 118 .Cm create Ar type
 119 .Op Fl v
 120 .Op Fl s Ar stripe_size
 121 .Ar drive Ns Op \&, Ns Ar drive Ns Op ",..."
 122 .Op Ar drive Ns Op \&, Ns Ar drive Ns Op ",..."
 123 .Nm
 124 .Op Fl u Ar unit
 125 .Cm delete Ar volume
 126 .Nm
 127 .Op Fl u Ar unit
 128 .Cm add Ar drive Op Ar volume
 129 .Nm
 130 .Op Fl u Ar unit
 131 .Cm remove Ar drive
 132 .Nm
 133 .Op Fl u Ar unit
 134 .Cm start patrol
 135 .Nm
 136 .Op Fl u Ar unit
 137 .Cm stop patrol
 138 .Nm
 139 .Op Fl u Ar unit
 140 .Cm patrol Ar command Op Ar interval Op Ar start
 141 .Nm
 142 .Op Fl u Ar unit
 143 .Cm flash Ar file
 144 .Sh DESCRIPTION
 145 The
 146 .Nm
 147 utility can be used to display or modify various parameters on LSI
 148 MegaRAID SAS RAID controllers.
 149 Each invocation of
 150 .Nm
 151 consists of zero or more global options followed by a command.
 152 Commands may support additional optional or required arguments after the
 153 command.
 154 .Pp
 155 Currently one global option is supported:
 156 .Bl -tag -width indent
 157 .It Fl u Ar unit
 158 .Ar unit
 159 specifies the unit of the controller to work with.
 160 If no unit is specified,
 161 then unit 0 is used.
 162 .El
 163 .Pp
 164 Various commands accept either or both of the two options:
 165 .Bl -tag -width indent
 166 .It Fl d
 167 Print numeric device IDs as drive identifier.
 168 This is the default.
 169 Useful in combination with
 170 .Fl e
 171 to print both, numeric device IDs and enclosure:slot information.
 172 .It Fl e
 173 Print drive identifiers in enclosure:slot form.
 174 See next paragraph on format details in context of input rather than
 175 output.
 176 .El
 177 .Pp
 178 Drives may be specified in two forms.
 179 First,
 180 a drive may be identified by its device ID.
 181 The device ID for configured drives can be found in
 182 .Cm show config .
 183 Second,
 184 a drive may be identified by its location as
 185 .Sm off
 186 .Op E Ar xx Ns \&:
 187 .Li S Ns Ar yy
 188 .Sm on
 189 where
 190 .Ar xx
 191 is the enclosure
 192 and
 193 .Ar yy
 194 is the slot for each drive as displayed in
 195 .Cm show drives .
 196 .Pp
 197 Volumes may be specified in two forms.
 198 First,
 199 a volume may be identified by its target ID.
 200 Second,
 201 on the volume may be specified by the corresponding
 202 .Em mfidX
 203 device,
 204 such as
 205 .Em mfid0 .
 206 .Pp
 207 The
 208 .Nm
 209 utility supports several different groups of commands.
 210 The first group of commands provide information about the controller,
 211 the volumes it manages, and the drives it controls.
 212 The second group of commands are used to manage the physical drives
 213 attached to the controller.
 214 The third group of commands are used to manage the logical volumes
 215 managed by the controller.
 216 The fourth group of commands are used to manage the drive configuration for
 217 the controller.
 218 The fifth group of commands are used to manage controller-wide operations.
 219 .Pp
 220 The informational commands include:
 221 .Bl -tag -width indent
 222 .It Cm version
 223 Displays the version of
 224 .Nm .
 225 .It Cm show adapter
 226 Displays information about the RAID controller such as the model number.
 227 .It Cm show battery
 228 Displays information about the battery from the battery backup unit.
 229 .It Cm show config
 230 Displays the volume and drive configuration for the controller.
 231 Each array is listed along with the physical drives the array is built from.
 232 Each volume is listed along with the arrays that the volume spans.
 233 If any hot spare drives are configured, then they are listed as well.
 234 .It Cm show drives
 235 Lists all of the physical drives attached to the controller.
 236 .It Xo Cm show events
 237 .Op Fl c Ar class
 238 .Op Fl l Ar locale
 239 .Op Fl n Ar count
 240 .Op Fl v
 241 .Op Ar start Op Ar stop
 242 .Xc
 243 Display entries from the controller's event log.
 244 The controller maintains a circular buffer of events.
 245 Each event is tagged with a class and locale.
 246 .Pp
 247 The
 248 .Ar class
 249 parameter limits the output to entries at the specified class or higher.
 250 The default class is
 251 .Dq warn .
 252 The available classes from lowest priority to highest are:
 253 .Bl -tag -width -indent
 254 .It Cm debug
 255 Debug messages.
 256 .It Cm progress
 257 Periodic progress updates for long-running operations such as background
 258 initializations, array rebuilds, or patrol reads.
 259 .It Cm info
 260 Informational messages such as drive insertions and volume creations.
 261 .It Cm warn
 262 Indicates that some component may be close to failing.
 263 .It Cm crit
 264 A component has failed, but no data is lost.
 265 For example, a volume becoming degraded due to a drive failure.
 266 .It Cm fatal
 267 A component has failed resulting in data loss.
 268 .It Cm dead
 269 The controller itself has died.
 270 .El
 271 .Pp
 272 The
 273 .Ar locale
 274 parameter limits the output to entries for the specified part of the controller.
 275 The default locale is
 276 .Dq all .
 277 The available locales are
 278 .Dq volume ,
 279 .Dq drive ,
 280 .Dq enclosure ,
 281 .Dq battery ,
 282 .Dq sas ,
 283 .Dq controller ,
 284 .Dq config ,
 285 .Dq cluster ,
 286 and
 287 .Dq all .
 288 .Pp
 289 The
 290 .Ar count
 291 parameter is a debugging aid that specifies the number of events to fetch from
 292 the controller for each low-level request.
 293 The default is 15 events.
 294 .Pp
 295 By default, matching event log entries from the previous shutdown up to the
 296 present are displayed.  This range can be adjusted via the
 297 .Ar start
 298 and
 299 .Ar stop
 300 parameters.
 301 Each of these parameters can either be specified as a log entry number or as
 302 one of the following aliases:
 303 .Bl -tag -width -indent
 304 .It Cm newest
 305 The newest entry in the event log.
 306 .It Cm oldest
 307 The oldest entry in the event log.
 308 .It Cm clear
 309 The first entry since the event log was cleared.
 310 .It Cm shutdown
 311 The entry in the event log corresponding to the last time the controller was
 312 cleanly shut down.
 313 .It Cm boot
 314 The entry in the event log corresponding to the most recent boot.
 315 .El
 316 .It Cm show firmware
 317 Lists all of the firmware images present on the controller.
 318 .It Cm show logstate
 319 Display the various sequence numbers associated with the event log.
 320 .It Cm show patrol
 321 Display the status of the controller's patrol read operation.
 322 .It Cm show progress
 323 Report the current progress and estimated completion time for active
 324 operations on all volumes and drives.
 325 .It Cm show volumes
 326 Lists all of the logical volumes managed by the controller.
 327 .El
 328 .Pp
 329 The physical drive management commands include:
 330 .Bl -tag -width indent
 331 .It Cm fail Ar drive
 332 Mark
 333 .Ar drive
 334 as failed.
 335 .Ar Drive
 336 must be an online drive that is part of an array.
 337 .It Cm good Ar drive
 338 Mark
 339 .Ar drive
 340 as an unconfigured good drive.
 341 .Ar Drive
 342 must not be part of an existing array.
 343 .It Cm rebuild Ar drive
 344 Mark a failed
 345 .Ar drive
 346 that is still part of an array as a good drive suitable for a rebuild.
 347 The firmware should kick off an array rebuild on its own if a failed drive
 348 is marked as a rebuild drive.
 349 .It Cm drive progress Ar drive
 350 Report the current progress and estimated completion time of drive operations
 351 such as rebuilds or patrol reads.
 352 .It Cm drive clear Ar drive Brq "start | stop"
 353 Start or stop the writing of all 0x00 characters to a drive.
 354 .It Cm start rebuild Ar drive
 355 Manually start a rebuild on
 356 .Ar drive .
 357 .It Cm abort rebuild Ar drive
 358 Abort an in-progress rebuild operation on
 359 .Ar drive .
 360 It can be resumed with the
 361 .Cm start rebuild
 362 command.
 363 .It Cm locate Ar drive Brq "on | off"
 364 Change the state of the external LED associated with
 365 .Ar drive .
 366 .El
 367 .Pp
 368 The logical volume management commands include:
 369 .Bl -tag -width indent
 370 .It Cm cache Ar volume Op Ar setting Op Ar value
 371 If no
 372 .Ar setting
 373 argument is supplied, then the current cache policy for
 374 .Ar volume
 375 is displayed;
 376 otherwise,
 377 the cache policy for
 378 .Ar volume
 379 is modified.
 380 The optional
 381 .Ar setting
 382 argument can be one of the following values:
 383 .Bl -tag -width indent
 384 .It Cm enable
 385 Enable caching for both read and write I/O operations.
 386 .It Cm disable
 387 Disable caching for both read and write I/O operations.
 388 .It Cm reads
 389 Enable caching only for read I/O operations.
 390 .It Cm writes
 391 Enable caching only for write I/O operations.
 392 .It Cm write-back
 393 Use write-back policy for cached writes.
 394 .It Cm write-through
 395 Use write-through policy for cached writes.
 396 .It Cm read-ahead Ar value
 397 Set the read ahead policy for cached reads.
 398 The
 399 .Ar value
 400 argument can be set to either
 401 .Dq none ,
 402 .Dq adaptive ,
 403 or
 404 .Dq always .
 405 .It Cm bad-bbu-write-cache Ar value
 406 Control the behavior of I/O write caching if the battery is dead or
 407 missing.
 408 The
 409 .Ar value
 410 argument can be set to either
 411 .Dq disable
 412 or
 413 .Dq enable .
 414 In general this setting should be left disabled to avoid data loss when
 415 the system loses power.
 416 .It Cm write-cache Ar value
 417 Control the write caches on the physical drives backing
 418 .Ar volume .
 419 The
 420 .Ar value
 421 argument can be set to either
 422 .Dq disable ,
 423 .Dq enable ,
 424 or
 425 .Dq default .
 426 .Pp
 427 In general this setting should be left disabled to avoid data loss when the
 428 physical drives lose power.
 429 The battery backup of the RAID controller does not save data in the write
 430 caches of the physical drives.
 431 .El
 432 .It Cm name Ar volume Ar name
 433 Sets the name of
 434 .Ar volume
 435 to
 436 .Ar name .
 437 .It Cm volume progress Ar volume
 438 Report the current progress and estimated completion time of volume operations
 439 such as consistency checks and initializations.
 440 .El
 441 .Pp
 442 The configuration commands include:
 443 .Bl -tag -width indent
 444 .It Cm clear
 445 Delete the entire configuration including all volumes, arrays, and spares.
 446 .It Xo Cm create Ar type
 447 .Op Fl v
 448 .Op Fl s Ar stripe_size
 449 .Ar drive Ns Op \&, Ns Ar drive Ns Op ",..."
 450 .Op Ar drive Ns Op \&, Ns Ar drive Ns Op ",..."
 451 .Xc
 452 Create a new volume.
 453 The
 454 .Ar type
 455 specifies the type of volume to create.
 456 Currently supported types include:
 457 .Bl -tag -width indent
 458 .It Cm jbod
 459 Creates a RAID0 volume for each drive specified.
 460 Each drive must be specified as a separate argument.
 461 .It Cm raid0
 462 Creates one RAID0 volume spanning the drives listed in the single drive list.
 463 .It Cm raid1
 464 Creates one RAID1 volume spanning the drives listed in the single drive list.
 465 .It Cm raid5
 466 Creates one RAID5 volume spanning the drives listed in the single drive list.
 467 .It Cm raid6
 468 Creates one RAID6 volume spanning the drives listed in the single drive list.
 469 .It Cm raid10
 470 Creates one RAID10 volume spanning multiple RAID1 arrays.
 471 The drives for each RAID1 array are specified as a single drive list.
 472 .It Cm raid50
 473 Creates one RAID50 volume spanning multiple RAID5 arrays.
 474 The drives for each RAID5 array are specified as a single drive list.
 475 .It Cm raid60
 476 Creates one RAID60 volume spanning multiple RAID6 arrays.
 477 The drives for each RAID6 array are specified as a single drive list.
 478 .It Cm concat
 479 Creates a single volume by concatenating all of the drives in the single drive
 480 list.
 481 .El
 482 .Pp
 483 .Sy Note:
 484 Not all volume types are supported by all controllers.
 485 .Pp
 486 If the
 487 .Fl v
 488 flag is specified after
 489 .Ar type ,
 490 then more verbose output will be enabled.
 491 Currently this just provides notification as drives are added to arrays and
 492 arrays to volumes when building the configuration.
 493 .Pp
 494 The
 495 .Fl s
 496 .Ar stripe_size
 497 parameter allows the stripe size of the array to be set.
 498 By default a stripe size of 64K is used.
 499 Valid values are 512 through 1M, though the MFI firmware may reject some
 500 values.
 501 .It Cm delete Ar volume
 502 Delete the volume
 503 .Ar volume .
 504 .It Cm add Ar drive Op Ar volume
 505 Mark
 506 .Ar drive
 507 as a hot spare.
 508 .Ar Drive
 509 must be in the unconfigured good state.
 510 If
 511 .Ar volume
 512 is specified,
 513 then the hot spare will be dedicated to arrays backing that volume.
 514 Otherwise,
 515 .Ar drive
 516 will be used as a global hot spare backing all arrays for this controller.
 517 Note that
 518 .Ar drive
 519 must be as large as the smallest drive in all of the arrays it is going to
 520 back.
 521 .It Cm remove Ar drive
 522 Remove the hot spare
 523 .Ar drive
 524 from service.
 525 It will be placed in the unconfigured good state.
 526 .El
 527 .Pp
 528 The controller management commands include:
 529 .Bl -tag -width indent
 530 .It Cm patrol Ar command Op Ar interval Op Ar start
 531 Set the patrol read operation mode.
 532 The
 533 .Ar command
 534 argument can be one of the following values:
 535 .Bl -tag -width indent
 536 .It Cm disable
 537 Disable patrol reads.
 538 .It Cm auto
 539 Enable periodic patrol reads initiated by the firmware.
 540 The optional
 541 .Ar interval
 542 argument specifies the interval in seconds between patrol reads.
 543 If patrol reads should be run continuously,
 544 then
 545 .Ar interval
 546 should consist of the word
 547 .Dq continuously .
 548 The optional
 549 .Ar start
 550 argument specifies a non-negative, relative start time for the next patrol read.
 551 If an interval or start time is not specified,
 552 then the existing setting will be used.
 553 .It Cm manual
 554 Enable manual patrol reads that are only initiated by the user.
 555 .El
 556 .It Cm start patrol
 557 Start a patrol read operation.
 558 .It Cm stop patrol
 559 Stop a currently running patrol read operation.
 560 .It Cm flash Ar file
 561 Updates the flash on the controller with the firmware stored in
 562 .Ar file .
 563 A reboot is required for the new firmware to take effect.
 564 .El
 565 .Sh EXAMPLES
 566 Configure the cache for volume mfid0 to cache only writes:
 567 .Pp
 568 .Dl Nm Cm cache mfid0 writes
 569 .Dl Nm Cm cache mfid0 write-back
 570 .Pp
 571 Create a RAID5 array spanning the first four disks in the second enclosure:
 572 .Pp
 573 .Dl Nm Cm create raid5 e1:s0,e1:s1,e1:s2,e1:s4
 574 .Pp
 575 Configure the first three disks on a controller as JBOD:
 576 .Pp
 577 .Dl Nm Cm create jbod 0 1 2
 578 .Pp
 579 Create a RAID10 volume that spans two arrays each of which contains two disks
 580 from two different enclosures:
 581 .Pp
 582 .Dl Nm Cm create raid10 e1:s0,e1:s1 e2:s0,e2:s1
 583 .Pp
 584 Add drive with the device ID of 4 as a global hot spare:
 585 .Pp
 586 .Dl Nm Cm add 4
 587 .Pp
 588 Add the drive in slot 2 in the main chassis as a hot spare for volume mfid0:
 589 .Pp
 590 .Dl Nm Cm add s2 mfid0
 591 .Pp
 592 Configure the adapter to run periodic patrol reads once a week with the first
 593 patrol read starting in 5 minutes:
 594 .Pp
 595 .Dl Nm Cm patrol auto 604800 300
 596 .Sh SEE ALSO
 597 .Xr mfi 4
 598 .Sh HISTORY
 599 The
 600 .Nm
 601 utility first appeared in
 602 .Fx 8.0 .