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