4f6b7519d8dc9cc041109e0db382b483c05903ff
[dragonfly.git] / 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 .