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