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 January 6, 2012
  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 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 Oo Ar value Oc Op ...
 371 If no
 372 .Ar setting
 373 arguments are 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 One or more
 381 .Ar setting
 382 arguments may be given.
 383 Some settings take an additional
 384 .Ar value
 385 argument as noted below.
 386 The valid settings are:
 387 .Bl -tag -width indent
 388 .It Cm enable
 389 Enable caching for both read and write I/O operations.
 390 .It Cm disable
 391 Disable caching for both read and write I/O operations.
 392 .It Cm reads
 393 Enable caching only for read I/O operations.
 394 .It Cm writes
 395 Enable caching only for write I/O operations.
 396 .It Cm write-back
 397 Use write-back policy for cached writes.
 398 .It Cm write-through
 399 Use write-through policy for cached writes.
 400 .It Cm read-ahead Ar value
 401 Set the read ahead policy for cached reads.
 402 The
 403 .Ar value
 404 argument can be set to either
 405 .Dq none ,
 406 .Dq adaptive ,
 407 or
 408 .Dq always .
 409 .It Cm bad-bbu-write-cache Ar value
 410 Control the behavior of I/O write caching if the battery is dead or
 411 missing.
 412 The
 413 .Ar value
 414 argument can be set to either
 415 .Dq disable
 416 or
 417 .Dq enable .
 418 In general this setting should be left disabled to avoid data loss when
 419 the system loses power.
 420 .It Cm write-cache Ar value
 421 Control the write caches on the physical drives backing
 422 .Ar volume .
 423 The
 424 .Ar value
 425 argument can be set to either
 426 .Dq disable ,
 427 .Dq enable ,
 428 or
 429 .Dq default .
 430 .Pp
 431 In general this setting should be left disabled to avoid data loss when the
 432 physical drives lose power.
 433 The battery backup of the RAID controller does not save data in the write
 434 caches of the physical drives.
 435 .El
 436 .It Cm name Ar volume Ar name
 437 Sets the name of
 438 .Ar volume
 439 to
 440 .Ar name .
 441 .It Cm volume progress Ar volume
 442 Report the current progress and estimated completion time of volume operations
 443 such as consistency checks and initializations.
 444 .El
 445 .Pp
 446 The configuration commands include:
 447 .Bl -tag -width indent
 448 .It Cm clear
 449 Delete the entire configuration including all volumes, arrays, and spares.
 450 .It Xo Cm create Ar type
 451 .Op Fl v
 452 .Op Fl s Ar stripe_size
 453 .Ar drive Ns Op \&, Ns Ar drive Ns Op ",..."
 454 .Op Ar drive Ns Op \&, Ns Ar drive Ns Op ",..."
 455 .Xc
 456 Create a new volume.
 457 The
 458 .Ar type
 459 specifies the type of volume to create.
 460 Currently supported types include:
 461 .Bl -tag -width indent
 462 .It Cm jbod
 463 Creates a RAID0 volume for each drive specified.
 464 Each drive must be specified as a separate argument.
 465 .It Cm raid0
 466 Creates one RAID0 volume spanning the drives listed in the single drive list.
 467 .It Cm raid1
 468 Creates one RAID1 volume spanning the drives listed in the single drive list.
 469 .It Cm raid5
 470 Creates one RAID5 volume spanning the drives listed in the single drive list.
 471 .It Cm raid6
 472 Creates one RAID6 volume spanning the drives listed in the single drive list.
 473 .It Cm raid10
 474 Creates one RAID10 volume spanning multiple RAID1 arrays.
 475 The drives for each RAID1 array are specified as a single drive list.
 476 .It Cm raid50
 477 Creates one RAID50 volume spanning multiple RAID5 arrays.
 478 The drives for each RAID5 array are specified as a single drive list.
 479 .It Cm raid60
 480 Creates one RAID60 volume spanning multiple RAID6 arrays.
 481 The drives for each RAID6 array are specified as a single drive list.
 482 .It Cm concat
 483 Creates a single volume by concatenating all of the drives in the single drive
 484 list.
 485 .El
 486 .Pp
 487 .Sy Note:
 488 Not all volume types are supported by all controllers.
 489 .Pp
 490 If the
 491 .Fl v
 492 flag is specified after
 493 .Ar type ,
 494 then more verbose output will be enabled.
 495 Currently this just provides notification as drives are added to arrays and
 496 arrays to volumes when building the configuration.
 497 .Pp
 498 The
 499 .Fl s
 500 .Ar stripe_size
 501 parameter allows the stripe size of the array to be set.
 502 By default a stripe size of 64K is used.
 503 Valid values are 512 through 1M, though the MFI firmware may reject some
 504 values.
 505 .It Cm delete Ar volume
 506 Delete the volume
 507 .Ar volume .
 508 .It Cm add Ar drive Op Ar volume
 509 Mark
 510 .Ar drive
 511 as a hot spare.
 512 .Ar Drive
 513 must be in the unconfigured good state.
 514 If
 515 .Ar volume
 516 is specified,
 517 then the hot spare will be dedicated to arrays backing that volume.
 518 Otherwise,
 519 .Ar drive
 520 will be used as a global hot spare backing all arrays for this controller.
 521 Note that
 522 .Ar drive
 523 must be as large as the smallest drive in all of the arrays it is going to
 524 back.
 525 .It Cm remove Ar drive
 526 Remove the hot spare
 527 .Ar drive
 528 from service.
 529 It will be placed in the unconfigured good state.
 530 .El
 531 .Pp
 532 The controller management commands include:
 533 .Bl -tag -width indent
 534 .It Cm patrol Ar command Op Ar interval Op Ar start
 535 Set the patrol read operation mode.
 536 The
 537 .Ar command
 538 argument can be one of the following values:
 539 .Bl -tag -width indent
 540 .It Cm disable
 541 Disable patrol reads.
 542 .It Cm auto
 543 Enable periodic patrol reads initiated by the firmware.
 544 The optional
 545 .Ar interval
 546 argument specifies the interval in seconds between patrol reads.
 547 If patrol reads should be run continuously,
 548 then
 549 .Ar interval
 550 should consist of the word
 551 .Dq continuously .
 552 The optional
 553 .Ar start
 554 argument specifies a non-negative, relative start time for the next patrol read.
 555 If an interval or start time is not specified,
 556 then the existing setting will be used.
 557 .It Cm manual
 558 Enable manual patrol reads that are only initiated by the user.
 559 .El
 560 .It Cm start patrol
 561 Start a patrol read operation.
 562 .It Cm stop patrol
 563 Stop a currently running patrol read operation.
 564 .It Cm flash Ar file
 565 Updates the flash on the controller with the firmware stored in
 566 .Ar file .
 567 A reboot is required for the new firmware to take effect.
 568 .El
 569 .Sh EXAMPLES
 570 Configure the cache for volume mfid0 to cache only writes:
 571 .Pp
 572 .Dl Nm Cm cache mfid0 writes
 573 .Dl Nm Cm cache mfid0 write-back
 574 .Pp
 575 Create a RAID5 array spanning the first four disks in the second enclosure:
 576 .Pp
 577 .Dl Nm Cm create raid5 e1:s0,e1:s1,e1:s2,e1:s4
 578 .Pp
 579 Configure the first three disks on a controller as JBOD:
 580 .Pp
 581 .Dl Nm Cm create jbod 0 1 2
 582 .Pp
 583 Create a RAID10 volume that spans two arrays each of which contains two disks
 584 from two different enclosures:
 585 .Pp
 586 .Dl Nm Cm create raid10 e1:s0,e1:s1 e2:s0,e2:s1
 587 .Pp
 588 Add drive with the device ID of 4 as a global hot spare:
 589 .Pp
 590 .Dl Nm Cm add 4
 591 .Pp
 592 Add the drive in slot 2 in the main chassis as a hot spare for volume mfid0:
 593 .Pp
 594 .Dl Nm Cm add s2 mfid0
 595 .Pp
 596 Configure the adapter to run periodic patrol reads once a week with the first
 597 patrol read starting in 5 minutes:
 598 .Pp
 599 .Dl Nm Cm patrol auto 604800 300
 600 .Sh SEE ALSO
 601 .Xr mfi 4
 602 .Sh HISTORY
 603 The
 604 .Nm
 605 utility first appeared in
 606 .Fx 8.0 .