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