1.\" 2.\" Copyright (c) 2008 Yahoo!, Inc. 3.\" All rights reserved. 4.\" Written by: John Baldwin <jhb@FreeBSD.org> 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the author nor the names of any co-contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd August 16, 2009 33.Dt MPTUTIL 8 34.Os 35.Sh NAME 36.Nm mptutil 37.Nd Utility for managing LSI Fusion-MPT controllers 38.Sh SYNOPSIS 39.Nm 40.Cm version 41.Nm 42.Op Fl u Ar unit 43.Cm show adapter 44.Nm 45.Op Fl u Ar unit 46.Cm show config 47.Nm 48.Op Fl u Ar unit 49.Cm show drives 50.Nm 51.Op Fl u Ar unit 52.Cm show events 53.Nm 54.Op Fl u Ar unit 55.Cm show volumes 56.Nm 57.Op Fl u Ar unit 58.Cm fail Ar drive 59.Nm 60.Op Fl u Ar unit 61.Cm online Ar drive 62.Nm 63.Op Fl u Ar unit 64.Cm offline Ar drive 65.Nm 66.Op Fl u Ar unit 67.Cm name Ar volume Ar name 68.Nm 69.Op Fl u Ar unit 70.Cm volume status Ar volume 71.Nm 72.Op Fl u Ar unit 73.Cm volume cache Ar volume 74.Ar enable|disable 75.Nm 76.Op Fl u Ar unit 77.Cm clear 78.Nm 79.Op Fl u Ar unit 80.Cm create Ar type 81.Op Fl q 82.Op Fl v 83.Op Fl s Ar stripe_size 84.Ar drive Ns Op \&, Ns Ar drive Ns Op ",..." 85.Nm 86.Op Fl u Ar unit 87.Cm delete Ar volume 88.Nm 89.Op Fl u Ar unit 90.Cm add Ar drive Op Ar volume 91.Nm 92.Op Fl u Ar unit 93.Cm remove Ar drive 94.Sh DESCRIPTION 95The 96.Nm 97utility can be used to display or modify various parameters on LSI 98Fusion-MPT controllers. 99Each invocation of 100.Nm 101consists of zero or more global options followed by a command. 102Commands may support additional optional or required arguments after the 103command. 104.Pp 105Currently one global option is supported: 106.Bl -tag -width indent 107.It Fl u Ar unit 108.Ar unit 109specifies the unit of the controller to work with. 110If no unit is specified, 111then unit 0 is used. 112.El 113.Pp 114Volumes may be specified in two forms. 115First, 116a volume may be identified by its location as 117.Sm off 118.Op Ar xx Ns \&: 119.Ar yy 120.Sm on 121where 122.Ar xx 123is the bus ID and 124.Ar yy 125is the target ID. 126If the bus ID is omitted, 127the volume is assumed to be on bus 0. 128Second, 129on the volume may be specified by the corresponding 130.Em daX 131device, 132such as 133.Em da0 . 134.Pp 135The 136.Xr mpt 4 137controller divides drives up into two categories. 138Configured drives belong to a RAID volume either as a member drive or as a hot 139spare. 140Each configured drive is assigned a unique device ID such as 0 or 1 that is 141show in 142.Cm show config , 143and in the first column of 144.Cm show drives . 145Any drive not associated with a RAID volume as either a member or a hot spare 146is a standalone drive. 147Standalone drives are visible to the operating system as SCSI disk devices. 148As a result, drives may be specified in three forms. 149First, 150a configured drive may be identified by its device ID. 151Second, 152any drive may be identified by its location as 153.Sm off 154.Ar xx Ns \&: 155.Ar yy 156.Sm on 157where 158.Ar xx 159is the bus ID and 160.Ar yy 161is the target ID for each drive as displayed in 162.Cm show drives . 163Note that unlike volumes, 164a drive location always requires the bus ID to avoid confusion with device IDs. 165Third, 166a standalone drive that is not part of a volume may be identified by its 167corresponding 168.Em daX 169device as displayed in 170.Cm show drives . 171.Pp 172The 173.Nm 174utility supports several different groups of commands. 175The first group of commands provide information about the controller, 176the volumes it manages, and the drives it controls. 177The second group of commands are used to manage the physical drives 178attached to the controller. 179The third group of commands are used to manage the logical volumes 180managed by the controller. 181The fourth group of commands are used to manage the drive configuration for 182the controller. 183.Pp 184The informational commands include: 185.Bl -tag -width indent 186.It Cm version 187Displays the version of 188.Nm . 189.It Cm show adapter 190Displays information about the RAID controller such as the model number. 191.It Cm show config 192Displays the volume and drive configuration for the controller. 193Each volume is listed along with the physical drives that the volume spans. 194If any hot spare drives are configured, then they are listed as well. 195.It Cm show drives 196Lists all of the physical drives attached to the controller. 197.It Cm show events 198Display all the entries from the controller's event log. 199Due to lack of documentation this command is not very useful currently and 200just dumps each log entry in hex. 201.It Cm show volumes 202Lists all of the logical volumes managed by the controller. 203.El 204.Pp 205The physical drive management commands include: 206.Bl -tag -width indent 207.It Cm fail Ar drive 208Mark 209.Ar drive 210as 211.Dq failed requested . 212Note that this state is different from the 213.Dq failed 214state that is used when the firmware fails a drive. 215.Ar Drive 216must be a configured drive. 217.It Cm online Ar drive 218Mark 219.Ar drive 220as an online drive. 221.Ar Drive 222must be part a configured drive in either the 223.Dq offline 224or 225.Dq failed requested 226states. 227.It Cm offline Ar drive 228Mark 229.Ar drive 230as offline. 231.Ar Drive 232must be a configured, online drive. 233.El 234.Pp 235The logical volume management commands include: 236.Bl -tag -width indent 237.It Cm name Ar volume Ar name 238Sets the name of 239.Ar volume 240to 241.Ar name . 242.It Cm volume cache Ar volume Ar enable|disable 243Enables or disables the drive write cache for the member drives of 244.Ar volume . 245.It Cm volume status Ar volume 246Display more detailed status about a single volume including the current 247progress of a rebuild operation if one is being performed. 248.El 249.Pp 250The configuration commands include: 251.Bl -tag -width indent 252.It Cm clear 253Delete the entire configuration including all volumes and spares. 254All drives will become standalone drives. 255.It Xo Cm create Ar type 256.Op Fl q 257.Op Fl v 258.Op Fl s Ar stripe_size 259.Ar drive Ns Op \&, Ns Ar drive Ns Op ",..." 260.Xc 261Create a new volume. 262The 263.Ar type 264specifies the type of volume to create. 265Currently supported types include: 266.Bl -tag -width indent 267.It Cm raid0 268Creates one RAID0 volume spanning the drives listed in the single drive list. 269.It Cm raid1 270Creates one RAID1 volume spanning the drives listed in the single drive list. 271.It Cm raid1e 272Creates one RAID1E volume spanning the drives listed in the single drive list. 273.El 274.Pp 275.Sy Note: 276Not all volume types are supported by all controllers. 277.Pp 278If the 279.Fl q 280flag is specified after 281.Ar type , 282then a 283.Dq quick 284initialization of the volume will be done. 285This is useful when the drives do not contain any existing data that need 286to be preserved. 287.Pp 288If the 289.Fl v 290flag is specified after 291.Ar type , 292then more verbose output will be enabled. 293Currently this just provides notification as drives are added to volumes 294when building the configuration. 295.Pp 296The 297.Fl s 298.Ar stripe_size 299parameter allows the stripe size of the array to be set. 300By default a stripe size of 64K is used. 301The list of valid values for a given 302.Ar type 303are listed in the output of 304.Cm show adapter . 305.It Cm delete Ar volume 306Delete the volume 307.Ar volume . 308Member drives will become standalone drives. 309.It Cm add Ar drive Op Ar volume 310Mark 311.Ar drive 312as a hot spare. 313.Ar Drive 314must not be a member of a volume. 315If 316.Ar volume 317is specified, 318then the hot spare will be dedicated to that volume. 319Otherwise, 320.Ar drive 321will be used as a global hot spare backing all volumes for this controller. 322Note that 323.Ar drive 324must be as large as the smallest drive in all of the volumes it is going to 325back. 326.It Cm remove Ar drive 327Remove the hot spare 328.Ar drive 329from service. 330It will become a standalone drive. 331.El 332.Sh EXAMPLES 333Mark the drive at bus 0 target 4 as offline: 334.Pp 335.Dl Nm Cm offline 0:4 336.Pp 337Create a RAID1 array from the two standalone drives 338.Va da1 339and 340.Va da2 : 341.Pp 342.Dl Nm Cm create raid1 da1,da2 343.Pp 344Mark standalone drive 345.Va da3 346as a global hot spare: 347.Pp 348.Dl Nm Cm add da3 349.Sh SEE ALSO 350.Xr mpt 4 351.Sh HISTORY 352The 353.Nm 354utility first appeared in 355.Fx 8.0 . 356.Sh BUGS 357The handling of spare drives appears to be unreliable. 358The 359.Xr mpt 4 360firmware manages spares via spare drive 361.Dq pools . 362There are eight pools numbered 0 through 7. 363Each spare drive can only be assigned to a single pool. 364Each volume can be backed by any combination of zero or more spare pools. 365The 366.Nm 367utility attempts to use the following algorithm for managing spares. 368Global spares are always assigned to pool 0, 369and all volumes are always backed by pool 0. 370For dedicated spares, 371.Nm 372assigns one of the remaining 7 pools to each volume and 373assigns dedicated drives to that pool. 374In practice however, it seems that assigning a drive as a spare does not 375take effect until the box has been rebooted. 376Also, the firmware renumbers the spare pool assignments after a reboot 377which undoes the effects of the algorithm above. 378Simple cases such as assigning global spares seem to work ok 379.Pq albeit requiring a reboot to take effect 380but more 381.Dq exotic 382configurations may not work reliably. 383.Pp 384Drive configuration commands result in an excessive flood of messages on the 385console. 386.Pp 387The mpt version 1 API that is used by 388.Nm 389and 390.Xr mpt 4 391does not support volumes above two terabytes. 392This is a limitation of the API. 393If you are using this adapter with volumes larger than two terabytes, use the adapter in JBOD mode. 394Utilize 395.Xr geom 8 , 396.Xr zfs 8 , 397or another software volume manager to work around this limitation. 398