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