[dragonfly.git] / usr.sbin / mptutil / mptutil.8

.\"
.\" Copyright (c) 2008 Yahoo!, Inc.
.\" All rights reserved.
.\" Written by: John Baldwin <jhb@FreeBSD.org>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the author nor the names of any co-contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/usr.sbin/mptutil/mptutil.8,v 1.2 2009/08/17 06:15:44 scottl Exp $
.\"
.Dd August 16, 2009
.Dt MPTUTIL 8
.Os
.Sh NAME
.Nm mptutil
.Nd Utility for managing LSI Fusion-MPT controllers
.Sh SYNOPSIS
.Nm
.Cm version
.Nm
.Op Fl u Ar unit
.Cm show adapter
.Nm
.Op Fl u Ar unit
.Cm show config
.Nm
.Op Fl u Ar unit
.Cm show drives
.Nm
.Op Fl u Ar unit
.Cm show events
.Nm
.Op Fl u Ar unit
.Cm show volumes
.Nm
.Op Fl u Ar unit
.Cm fail Ar drive
.Nm
.Op Fl u Ar unit
.Cm online Ar drive
.Nm
.Op Fl u Ar unit
.Cm offline Ar drive
.Nm
.Op Fl u Ar unit
.Cm name Ar volume Ar name
.Nm
.Op Fl u Ar unit
.Cm volume status Ar volume
.Nm
.Op Fl u Ar unit
.Cm volume cache Ar volume
.Ar enable|disable
.Nm
.Op Fl u Ar unit
.Cm clear
.Nm
.Op Fl u Ar unit
.Cm create Ar type
.Op Fl q
.Op Fl v
.Op Fl s Ar stripe_size
.Ar drive Ns Op \&, Ns Ar drive Ns Op ",..."
.Nm
.Op Fl u Ar unit
.Cm delete Ar volume
.Nm
.Op Fl u Ar unit
.Cm add Ar drive Op Ar volume
.Nm
.Op Fl u Ar unit
.Cm remove Ar drive
.Sh DESCRIPTION
The
.Nm
utility can be used to display or modify various parameters on LSI
Fusion-MPT controllers.
Each invocation of
.Nm
consists of zero or more global options followed by a command.
Commands may support additional optional or required arguments after the
command.
.Pp
Currently one global option is supported:
.Bl -tag -width indent
.It Fl u Ar unit
.Ar unit
specifies the unit of the controller to work with.
If no unit is specified,
then unit 0 is used.
.El
.Pp
Volumes may be specified in two forms.
First,
a volume may be identified by its location as
.Sm off
.Op Ar xx Ns \&:
.Ar yy
.Sm on
where
.Ar xx
is the bus ID and
.Ar yy
is the target ID.
If the bus ID is ommitted,
the volume is assumed to be on bus 0.
Second,
on the volume may be specified by the corresponding
.Em daX
device,
such as
.Em da0 .
.Pp
The
.Xr mpt 4
controller divides drives up into two categories.
Configured drives belong to a RAID volume either as a member drive or as a hot
spare.
Each configured drive is assigned a unique device ID such as 0 or 1 that is
show in
.Cm show config ,
and in the first column of
.Cm show drives .
Any drive not associated with a RAID volume as either a member or a hot spare
is a standalone drive.
Standalone drives are visible to the operating system as SCSI disk devices.
As a result, drives may be specified in three forms.
First,
a configured drive may be identified by its device ID.
Second,
any drive may be identified by its location as
.Sm off
.Ar xx Ns \&:
.Ar yy
.Sm on
where
.Ar xx
is the bus ID and
.Ar yy
is the target ID for each drive as displayed in
.Cm show drives .
Note that unlike volumes,
a drive location always requires the bus ID to avoid confusion with device IDs.
Third,
a standalone drive that is not part of a volume may be identified by its
corresponding
.Em daX
device as displayed in
.Cm show drives .
.Pp
The
.Nm
utility supports several different groups of commands.
The first group of commands provide information about the controller,
the volumes it manages, and the drives it controls.
The second group of commands are used to manage the physical drives
attached to the controller.
The third group of commands are used to manage the logical volumes
managed by the controller.
The fourth group of commands are used to manage the drive configuration for
the controller.
.Pp
The informational commands include:
.Bl -tag -width indent
.It Cm version
Displays the version of
.Nm .
.It Cm show adapter
Displays information about the RAID controller such as the model number.
.It Cm show config
Displays the volume and drive configuration for the controller.
Each volume is listed along with the physical drives that the volume spans.
If any hot spare drives are configured, then they are listed as well.
.It Cm show drives
Lists all of the physical drives attached to the controller.
.It Cm show events
Display all the entries from the controller's event log.
Due to lack of documentation this command isn't very useful currently and
just dumps each log entry in hex.
.It Cm show volumes
Lists all of the logical volumes managed by the controller.
.El
.Pp
The physical drive management commands include:
.Bl -tag -width indent
.It Cm fail Ar drive
Mark
.Ar drive
as
.Dq failed requested .
Note that this state is different from the
.Dq failed
state that is used when the firmware fails a drive.
.Ar Drive
must be a configured drive.
.It Cm online Ar drive
Mark
.Ar drive
as an online drive.
.Ar Drive
must be part a configured drive in either the
.Dq offline
or
.Dq failed requested
states.
.It Cm offline Ar drive
Mark
.Ar drive
as offline.
.Ar Drive
must be a configured, online drive.
.El
.Pp
The logical volume management commands include:
.Bl -tag -width indent
.It Cm name Ar volume Ar name
Sets the name of
.Ar volume
to
.Ar name .
.It Cm volume cache Ar volume Ar enable|disable
Enables or disables the drive write cache for the member drives of
.Ar volume .
.It Cm volume status Ar volume
Display more detailed status about a single volume including the current
progress of a rebuild operation if one is being performed.
.El
.Pp
The configuration commands include:
.Bl -tag -width indent
.It Cm clear
Delete the entire configuration including all volumes and spares.
All drives will become standalone drives.
.It Xo Cm create Ar type
.Op Fl q
.Op Fl v
.Op Fl s Ar stripe_size
.Ar drive Ns Op \&, Ns Ar drive Ns Op ",..."
.Xc
Create a new volume.
The
.Ar type
specifies the type of volume to create.
Currently supported types include:
.Bl -tag -width indent
.It Cm raid0
Creates one RAID0 volume spanning the drives listed in the single drive list.
.It Cm raid1
Creates one RAID1 volume spanning the drives listed in the single drive list.
.It Cm raid1e
Creates one RAID1E volume spanning the drives listed in the single drive list.
.El
.Pp
.Sy Note:
Not all volume types are supported by all controllers.
.Pp
If the
.Fl q
flag is specified after
.Ar type ,
then a
.Dq quick
initialization of the volume will be done.
This is useful when the drives do not contain any existing data that need
to be preserved.
.Pp
If the
.Fl v
flag is specified after
.Ar type ,
then more verbose output will be enabled.
Currently this just provides notification as drives are added to volumes
when building the configuration.
.Pp
The
.Fl s
.Ar stripe_size
parameter allows the stripe size of the array to be set.
By default a stripe size of 64K is used.
The list of valid values for a given
.Ar type
are listed in the output of
.Cm show adapter .
.It Cm delete Ar volume
Delete the volume
.Ar volume .
Member drives will become standalone drives.
.It Cm add Ar drive Op Ar volume
Mark
.Ar drive
as a hot spare.
.Ar Drive
must not be a member of a volume.
If
.Ar volume
is specified,
then the hot spare will be dedicated to that volume.
Otherwise,
.Ar drive
will be used as a global hot spare backing all volumes for this controller.
Note that
.Ar drive
must be as large as the smallest drive in all of the volumes it is going to
back.
.It Cm remove Ar drive
Remove the hot spare
.Ar drive
from service.
It will become a standalone drive.
.El
.Sh EXAMPLES
Mark the drive at bus 0 target 4 as offline:
.Pp
.Dl Nm Cm offline 0:4
.Pp
Create a RAID1 array from the two standalone drives
.Va da1
and
.Va da2 :
.Pp
.Dl Nm Cm create raid1 da1,da2
.Pp
Mark standalone drive
.Va da3
as a global hot spare:
.Pp
.Dl Nm Cm add da3
.Sh SEE ALSO
.Xr mpt 4
.Sh BUGS
.Pp
The handling of spare drives appears to be unreliable.
The
.Xr mpt 4
firmware manages spares via spare drive
.Dq pools .
There are eight pools numbered 0 through 7.
Each spare drive can only be assigned to a single pool.
Each volume can be backed by any combination of zero or more spare pools.
The
.Nm
utility attempts to use the following algorithm for managing spares.
Global spares are always assigned to pool 0,
and all volumes are always backed by pool 0.
For dedicated spares,
.Nm
assigns one of the remaining 7 pools to each volume and
assigns dedicated drives to that pool.
In practice however, it seems that assigning a drive as a spare does not
take effect until the box has been rebooted.
Also, the firmware renumbers the spare pool assignments after a reboot
which undoes the effects of the algorithm above.
Simple cases such as assigning global spares seem to work ok
.Pq albeit requiring a reboot to take effect
but more
.Dq exotic
configurations may not work reliably.
.Pp
Drive configuration commands result in an excessive flood of messages on the
console.
.Sh HISTORY
The
.Nm
utility first appeared in
.Fx 8.0 .
Commit	Line	Data
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
	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 .