usr.sbin/mptutil/mptutil.8

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