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