mptutil.8: Remove trailing whitespace.
[dragonfly.git] / usr.sbin / mptutil / mptutil.8
CommitLineData
22b2e3c5
AP
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
2864ce40 73.Cm volume cache Ar volume
22b2e3c5
AP
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 ommitted,
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 isn't 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 BUGS
352.Pp
353The handling of spare drives appears to be unreliable.
354The
355.Xr mpt 4
356firmware manages spares via spare drive
357.Dq pools .
358There are eight pools numbered 0 through 7.
359Each spare drive can only be assigned to a single pool.
360Each volume can be backed by any combination of zero or more spare pools.
361The
362.Nm
363utility attempts to use the following algorithm for managing spares.
364Global spares are always assigned to pool 0,
365and all volumes are always backed by pool 0.
366For dedicated spares,
367.Nm
368assigns one of the remaining 7 pools to each volume and
369assigns dedicated drives to that pool.
370In practice however, it seems that assigning a drive as a spare does not
371take effect until the box has been rebooted.
372Also, the firmware renumbers the spare pool assignments after a reboot
373which undoes the effects of the algorithm above.
374Simple cases such as assigning global spares seem to work ok
375.Pq albeit requiring a reboot to take effect
376but more
377.Dq exotic
378configurations may not work reliably.
379.Pp
380Drive configuration commands result in an excessive flood of messages on the
381console.
382.Sh HISTORY
383The
384.Nm
385utility first appeared in
386.Fx 8.0 .