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.9 2011/09/02 16:00:51 jhb Exp $
  29 .\"
  30 .Dd April 1, 2013
  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 Oo Ar value Oc Op ...
 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 foreign scan
 144 .Nm
 145 .Op Fl u Ar unit
 146 .Cm foreign drives
 147 .Nm
 148 .Op Fl u Ar unit
 149 .Cm foreign clear Op Ar config
 150 .Nm
 151 .Op Fl u Ar unit
 152 .Cm foreign display Op Ar config
 153 .Nm
 154 .Op Fl u Ar unit
 155 .Cm foreign preview Op Ar config
 156 .Nm
 157 .Op Fl u Ar unit
 158 .Cm foreign import Op Ar config
 159 .Nm
 160 .Op Fl u Ar unit
 161 .Cm flash Ar file
 162 .Sh DESCRIPTION
 163 The
 164 .Nm
 165 utility can be used to display or modify various parameters on LSI
 166 MegaRAID SAS RAID controllers.
 167 Each invocation of
 168 .Nm
 169 consists of zero or more global options followed by a command.
 170 Commands may support additional optional or required arguments after the
 171 command.
 172 .Pp
 173 Currently one global option is supported:
 174 .Bl -tag -width indent
 175 .It Fl u Ar unit
 176 .Ar unit
 177 specifies the unit of the controller to work with.
 178 If no unit is specified,
 179 then unit 0 is used.
 180 .El
 181 .Pp
 182 Various commands accept either or both of the two options:
 183 .Bl -tag -width indent
 184 .It Fl d
 185 Print numeric device IDs as drive identifier.
 186 This is the default.
 187 Useful in combination with
 188 .Fl e
 189 to print both, numeric device IDs and enclosure:slot information.
 190 .It Fl e
 191 Print drive identifiers in enclosure:slot form.
 192 See next paragraph on format details in context of input rather than
 193 output.
 194 .El
 195 .Pp
 196 Drives may be specified in two forms.
 197 First,
 198 a drive may be identified by its device ID.
 199 The device ID for configured drives can be found in
 200 .Cm show config .
 201 Second,
 202 a drive may be identified by its location as
 203 .Sm off
 204 .Op E Ar xx Ns \&:
 205 .Li S Ns Ar yy
 206 .Sm on
 207 where
 208 .Ar xx
 209 is the enclosure
 210 and
 211 .Ar yy
 212 is the slot for each drive as displayed in
 213 .Cm show drives .
 214 .Pp
 215 Volumes may be specified in two forms.
 216 First,
 217 a volume may be identified by its target ID.
 218 Second,
 219 on the volume may be specified by the corresponding
 220 .Em mfidX
 221 device,
 222 such as
 223 .Em mfid0 .
 224 .Pp
 225 The
 226 .Nm
 227 utility supports several different groups of commands.
 228 The first group of commands provide information about the controller,
 229 the volumes it manages, and the drives it controls.
 230 The second group of commands are used to manage the physical drives
 231 attached to the controller.
 232 The third group of commands are used to manage the logical volumes
 233 managed by the controller.
 234 The fourth group of commands are used to manage the drive configuration for
 235 the controller.
 236 The fifth group of commands are used to manage controller-wide operations.
 237 .Pp
 238 The informational commands include:
 239 .Bl -tag -width indent
 240 .It Cm version
 241 Displays the version of
 242 .Nm .
 243 .It Cm show adapter
 244 Displays information about the RAID controller such as the model number.
 245 .It Cm show battery
 246 Displays information about the battery from the battery backup unit.
 247 .It Cm show config
 248 Displays the volume and drive configuration for the controller.
 249 Each array is listed along with the physical drives the array is built from.
 250 Each volume is listed along with the arrays that the volume spans.
 251 If any hot spare drives are configured, then they are listed as well.
 252 .It Cm show drives
 253 Lists all of the physical drives attached to the controller.
 254 .It Xo Cm show events
 255 .Op Fl c Ar class
 256 .Op Fl l Ar locale
 257 .Op Fl n Ar count
 258 .Op Fl v
 259 .Op Ar start Op Ar stop
 260 .Xc
 261 Display entries from the controller's event log.
 262 The controller maintains a circular buffer of events.
 263 Each event is tagged with a class and locale.
 264 .Pp
 265 The
 266 .Ar class
 267 parameter limits the output to entries at the specified class or higher.
 268 The default class is
 269 .Dq warn .
 270 The available classes from lowest priority to highest are:
 271 .Bl -tag -width indent
 272 .It Cm debug
 273 Debug messages.
 274 .It Cm progress
 275 Periodic progress updates for long-running operations such as background
 276 initializations, array rebuilds, or patrol reads.
 277 .It Cm info
 278 Informational messages such as drive insertions and volume creations.
 279 .It Cm warn
 280 Indicates that some component may be close to failing.
 281 .It Cm crit
 282 A component has failed, but no data is lost.
 283 For example, a volume becoming degraded due to a drive failure.
 284 .It Cm fatal
 285 A component has failed resulting in data loss.
 286 .It Cm dead
 287 The controller itself has died.
 288 .El
 289 .Pp
 290 The
 291 .Ar locale
 292 parameter limits the output to entries for the specified part of the controller.
 293 The default locale is
 294 .Dq all .
 295 The available locales are
 296 .Dq volume ,
 297 .Dq drive ,
 298 .Dq enclosure ,
 299 .Dq battery ,
 300 .Dq sas ,
 301 .Dq controller ,
 302 .Dq config ,
 303 .Dq cluster ,
 304 and
 305 .Dq all .
 306 .Pp
 307 The
 308 .Ar count
 309 parameter is a debugging aid that specifies the number of events to fetch from
 310 the controller for each low-level request.
 311 The default is 15 events.
 312 .Pp
 313 By default, matching event log entries from the previous shutdown up to the
 314 present are displayed.  This range can be adjusted via the
 315 .Ar start
 316 and
 317 .Ar stop
 318 parameters.
 319 Each of these parameters can either be specified as a log entry number or as
 320 one of the following aliases:
 321 .Bl -tag -width indent
 322 .It Cm newest
 323 The newest entry in the event log.
 324 .It Cm oldest
 325 The oldest entry in the event log.
 326 .It Cm clear
 327 The first entry since the event log was cleared.
 328 .It Cm shutdown
 329 The entry in the event log corresponding to the last time the controller was
 330 cleanly shut down.
 331 .It Cm boot
 332 The entry in the event log corresponding to the most recent boot.
 333 .El
 334 .It Cm show firmware
 335 Lists all of the firmware images present on the controller.
 336 .It Cm show logstate
 337 Display the various sequence numbers associated with the event log.
 338 .It Cm show patrol
 339 Display the status of the controller's patrol read operation.
 340 .It Cm show progress
 341 Report the current progress and estimated completion time for active
 342 operations on all volumes and drives.
 343 .It Cm show volumes
 344 Lists all of the logical volumes managed by the controller.
 345 .El
 346 .Pp
 347 The physical drive management commands include:
 348 .Bl -tag -width indent
 349 .It Cm fail Ar drive
 350 Mark
 351 .Ar drive
 352 as failed.
 353 .Ar Drive
 354 must be an online drive that is part of an array.
 355 .It Cm good Ar drive
 356 Mark
 357 .Ar drive
 358 as an unconfigured good drive.
 359 .Ar Drive
 360 must not be part of an existing array.
 361 .It Cm rebuild Ar drive
 362 Mark a failed
 363 .Ar drive
 364 that is still part of an array as a good drive suitable for a rebuild.
 365 The firmware should kick off an array rebuild on its own if a failed drive
 366 is marked as a rebuild drive.
 367 .It Cm drive progress Ar drive
 368 Report the current progress and estimated completion time of drive operations
 369 such as rebuilds or patrol reads.
 370 .It Cm drive clear Ar drive Brq "start | stop"
 371 Start or stop the writing of all 0x00 characters to a drive.
 372 .It Cm start rebuild Ar drive
 373 Manually start a rebuild on
 374 .Ar drive .
 375 .It Cm abort rebuild Ar drive
 376 Abort an in-progress rebuild operation on
 377 .Ar drive .
 378 It can be resumed with the
 379 .Cm start rebuild
 380 command.
 381 .It Cm locate Ar drive Brq "on | off"
 382 Change the state of the external LED associated with
 383 .Ar drive .
 384 .El
 385 .Pp
 386 The logical volume management commands include:
 387 .Bl -tag -width indent
 388 .It Cm cache Ar volume Op Ar setting Oo Ar value Oc Op ...
 389 If no
 390 .Ar setting
 391 arguments are supplied, then the current cache policy for
 392 .Ar volume
 393 is displayed;
 394 otherwise,
 395 the cache policy for
 396 .Ar volume
 397 is modified.
 398 One or more
 399 .Ar setting
 400 arguments may be given.
 401 Some settings take an additional
 402 .Ar value
 403 argument as noted below.
 404 The valid settings are:
 405 .Bl -tag -width indent
 406 .It Cm enable
 407 Enable caching for both read and write I/O operations.
 408 .It Cm disable
 409 Disable caching for both read and write I/O operations.
 410 .It Cm reads
 411 Enable caching only for read I/O operations.
 412 .It Cm writes
 413 Enable caching only for write I/O operations.
 414 .It Cm write-back
 415 Use write-back policy for cached writes.
 416 .It Cm write-through
 417 Use write-through policy for cached writes.
 418 .It Cm read-ahead Ar value
 419 Set the read ahead policy for cached reads.
 420 The
 421 .Ar value
 422 argument can be set to either
 423 .Dq none ,
 424 .Dq adaptive ,
 425 or
 426 .Dq always .
 427 .It Cm bad-bbu-write-cache Ar value
 428 Control the behavior of I/O write caching if the battery is dead or
 429 missing.
 430 The
 431 .Ar value
 432 argument can be set to either
 433 .Dq disable
 434 or
 435 .Dq enable .
 436 In general this setting should be left disabled to avoid data loss when
 437 the system loses power.
 438 .It Cm write-cache Ar value
 439 Control the write caches on the physical drives backing
 440 .Ar volume .
 441 The
 442 .Ar value
 443 argument can be set to either
 444 .Dq disable ,
 445 .Dq enable ,
 446 or
 447 .Dq default .
 448 .Pp
 449 In general this setting should be left disabled to avoid data loss when the
 450 physical drives lose power.
 451 The battery backup of the RAID controller does not save data in the write
 452 caches of the physical drives.
 453 .El
 454 .It Cm name Ar volume Ar name
 455 Sets the name of
 456 .Ar volume
 457 to
 458 .Ar name .
 459 .It Cm volume progress Ar volume
 460 Report the current progress and estimated completion time of volume operations
 461 such as consistency checks and initializations.
 462 .El
 463 .Pp
 464 The configuration commands include:
 465 .Bl -tag -width indent
 466 .It Cm clear
 467 Delete the entire configuration including all volumes, arrays, and spares.
 468 .It Xo Cm create Ar type
 469 .Op Fl v
 470 .Op Fl s Ar stripe_size
 471 .Ar drive Ns Op \&, Ns Ar drive Ns Op ",..."
 472 .Op Ar drive Ns Op \&, Ns Ar drive Ns Op ",..."
 473 .Xc
 474 Create a new volume.
 475 The
 476 .Ar type
 477 specifies the type of volume to create.
 478 Currently supported types include:
 479 .Bl -tag -width indent
 480 .It Cm jbod
 481 Creates a RAID0 volume for each drive specified.
 482 Each drive must be specified as a separate argument.
 483 .It Cm raid0
 484 Creates one RAID0 volume spanning the drives listed in the single drive list.
 485 .It Cm raid1
 486 Creates one RAID1 volume spanning the drives listed in the single drive list.
 487 .It Cm raid5
 488 Creates one RAID5 volume spanning the drives listed in the single drive list.
 489 .It Cm raid6
 490 Creates one RAID6 volume spanning the drives listed in the single drive list.
 491 .It Cm raid10
 492 Creates one RAID10 volume spanning multiple RAID1 arrays.
 493 The drives for each RAID1 array are specified as a single drive list.
 494 .It Cm raid50
 495 Creates one RAID50 volume spanning multiple RAID5 arrays.
 496 The drives for each RAID5 array are specified as a single drive list.
 497 .It Cm raid60
 498 Creates one RAID60 volume spanning multiple RAID6 arrays.
 499 The drives for each RAID6 array are specified as a single drive list.
 500 .It Cm concat
 501 Creates a single volume by concatenating all of the drives in the single drive
 502 list.
 503 .El
 504 .Pp
 505 .Sy Note:
 506 Not all volume types are supported by all controllers.
 507 .Pp
 508 If the
 509 .Fl v
 510 flag is specified after
 511 .Ar type ,
 512 then more verbose output will be enabled.
 513 Currently this just provides notification as drives are added to arrays and
 514 arrays to volumes when building the configuration.
 515 .Pp
 516 The
 517 .Fl s
 518 .Ar stripe_size
 519 parameter allows the stripe size of the array to be set.
 520 By default a stripe size of 64K is used.
 521 Valid values are 512 through 1M, though the MFI firmware may reject some
 522 values.
 523 .It Cm delete Ar volume
 524 Delete the volume
 525 .Ar volume .
 526 .It Cm add Ar drive Op Ar volume
 527 Mark
 528 .Ar drive
 529 as a hot spare.
 530 .Ar Drive
 531 must be in the unconfigured good state.
 532 If
 533 .Ar volume
 534 is specified,
 535 then the hot spare will be dedicated to arrays backing that volume.
 536 Otherwise,
 537 .Ar drive
 538 will be used as a global hot spare backing all arrays for this controller.
 539 Note that
 540 .Ar drive
 541 must be as large as the smallest drive in all of the arrays it is going to
 542 back.
 543 .It Cm remove Ar drive
 544 Remove the hot spare
 545 .Ar drive
 546 from service.
 547 It will be placed in the unconfigured good state.
 548 .El
 549 .Pp
 550 The controller management commands include:
 551 .Bl -tag -width indent
 552 .It Cm patrol Ar command Op Ar interval Op Ar start
 553 Set the patrol read operation mode.
 554 The
 555 .Ar command
 556 argument can be one of the following values:
 557 .Bl -tag -width indent
 558 .It Cm disable
 559 Disable patrol reads.
 560 .It Cm auto
 561 Enable periodic patrol reads initiated by the firmware.
 562 The optional
 563 .Ar interval
 564 argument specifies the interval in seconds between patrol reads.
 565 If patrol reads should be run continuously,
 566 then
 567 .Ar interval
 568 should consist of the word
 569 .Dq continuously .
 570 The optional
 571 .Ar start
 572 argument specifies a non-negative, relative start time for the next patrol read.
 573 If an interval or start time is not specified,
 574 then the existing setting will be used.
 575 .It Cm manual
 576 Enable manual patrol reads that are only initiated by the user.
 577 .El
 578 .It Cm start patrol
 579 Start a patrol read operation.
 580 .It Cm stop patrol
 581 Stop a currently running patrol read operation.
 582 .It Cm foreign scan
 583 Scan for foreign configurations and display the number found.
 584 The
 585 .Ar config
 586 argument for the commands below takes the form of a number from 0 to
 587 the total configurations found.
 588 .It Cm foreign drives
 589 Scan for drives flagged as foreign and display them.
 590 .It Cm foreign clear Op config
 591 Clear the specified foreign
 592 .Ar config
 593 or all if no
 594 .Ar config
 595 argument is provided.
 596 .It Cm foreign display Op config
 597 Display the specified foreign
 598 .Ar config
 599 or all if no
 600 .Ar config
 601 argument is provided.
 602 .It Cm foreign preview Op config
 603 Preview the specified foreign
 604 .Ar config
 605 after import or all if no
 606 .Ar config
 607 argument is provided.
 608 .It Cm foreign import Op config
 609 Import the specified foreign
 610 .Ar config
 611 or all if no
 612 .Ar config
 613 argument is provided.
 614 .It Cm flash Ar file
 615 Updates the flash on the controller with the firmware stored in
 616 .Ar file .
 617 A reboot is required for the new firmware to take effect.
 618 .El
 619 .Sh EXAMPLES
 620 Configure the cache for volume mfid0 to cache only writes:
 621 .Pp
 622 .Dl Nm Cm cache mfid0 writes
 623 .Dl Nm Cm cache mfid0 write-back
 624 .Pp
 625 Create a RAID5 array spanning the first four disks in the second enclosure:
 626 .Pp
 627 .Dl Nm Cm create raid5 e1:s0,e1:s1,e1:s2,e1:s4
 628 .Pp
 629 Configure the first three disks on a controller as JBOD:
 630 .Pp
 631 .Dl Nm Cm create jbod 0 1 2
 632 .Pp
 633 Create a RAID10 volume that spans two arrays each of which contains two disks
 634 from two different enclosures:
 635 .Pp
 636 .Dl Nm Cm create raid10 e1:s0,e1:s1 e2:s0,e2:s1
 637 .Pp
 638 Add drive with the device ID of 4 as a global hot spare:
 639 .Pp
 640 .Dl Nm Cm add 4
 641 .Pp
 642 Add the drive in slot 2 in the main chassis as a hot spare for volume mfid0:
 643 .Pp
 644 .Dl Nm Cm add s2 mfid0
 645 .Pp
 646 Configure the adapter to run periodic patrol reads once a week with the first
 647 patrol read starting in 5 minutes:
 648 .Pp
 649 .Dl Nm Cm patrol auto 604800 300
 650 .Sh SEE ALSO
 651 .Xr mfi 4
 652 .Sh HISTORY
 653 The
 654 .Nm
 655 utility first appeared in
 656 .Fx 8.0 .