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