1 .\" Copyright (c) 2005 Chris Jones
2 .\" All rights reserved.
4 .\" This software was developed for the FreeBSD Project by Chris Jones
5 .\" thanks to the support of Google's Summer of Code program and
6 .\" mentoring by Lukas Ertl.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
17 .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .Nd Logical Volume Manager control program
42 .Bl -tag -width indent
43 .It Ic checkparity Oo Fl f Oc Ar plex
44 Check the parity blocks of a RAID-5 plex.
45 The parity check will start at the
46 beginning of the plex if the
48 flag is specified, or otherwise at the location of the parity check pointer,
49 the first location at which plex's parity is incorrect.
51 plex must be up for a parity check.
52 .It Ic create Op Ar description-file
53 Create a volume as described in
54 .Ar description-file .
57 provided, opens an editor and provides the current
59 configuration for editing.
61 Provides a synopsis of
63 commands and arguments.
64 .It Ic l | list Oo Fl rvV Oc Op Ar volume | plex | subdisk
65 .It Ic ld Oo Fl rvV Oc Op Ar drive ...
66 .It Ic ls Oo Fl rvV Oc Op Ar subdisk ...
67 .It Ic lp Oo Fl rvV Oc Op Ar plex ...
68 .It Ic lv Oo Fl rvV Oc Op Ar volume ...
69 List information about the relevant object(s).
72 flag provides recursive display, showing each object's subordinate objects in
78 flags provide progressively more detailed output.
79 .It Ic move | mv Fl f Ar drive subdisk Op Ar ...
80 Move the subdisk(s) to the specified drive.
83 flag is required, as all data on the indicated subdisk(s) will be destroyed as
85 This can currently only be done when the subdisk is
88 If the subdisk(s) form part of a RAID-5 plex, the disk(s) will need to be set
91 state and the plex will require a
93 command; if the subdisk(s) form part of a plex that is mirrored with other
94 plexes, the plex will require restarting and will sync once restarted.
96 more than one subdisk in a RAID-5 plex or subdisks from both sides of a
97 mirrored plex volume will destroy data.
98 Note that parity rebuilds and syncing
99 must be started manually after a move.
101 Write a copy of the current configuration to standard output.
105 when running in interactive mode.
106 Normally this would be done by entering the
108 .It Ic rename Oo Fl r Oc Ar drive | subdisk | plex | volume newname
109 Change the name of the specified object.
112 flag will recursively rename subordinate objects.
114 Note that device nodes will not be renamed until
117 .It Ic rebuildparity Oo Fl f Oc Ar plex
118 Rebuild the parity blocks of a RAID-5 plex.
119 The parity rebuild will start at
120 the beginning of the plex if the
122 flag is specified, or otherwise at the location of the parity check pointer.
123 All subdisks in the plex must be up for a parity check.
128 .It Ic rm Oo Fl r Oc Ar volume | plex | subdisk
129 Remove an object and, if
131 is specified, its subordinate objects.
135 configuration to disk after configuration failures.
136 .It Ic setstate Oo Fl f Oc Ar state volume | plex | subdisk | drive
137 Set state without influencing other objects, for diagnostic purposes
141 flag forces state changes regardless of whether they are legal.
143 Read configuration from all vinum drives.
144 .It Ic start Oo Fl S Ar size Oc Ar volume | plex | subdisk
145 Allow the system to access the objects.
148 flag is currently ignored.
153 utility communicates with the kernel component of the GVinum logical volume
155 It is designed either for interactive use, when started without
156 command line arguments, or to execute a single command if the command is
157 supplied on the command line.
160 maintains a command line history.
164 commands may be followed by an option.
165 .Bl -tag -width indent
170 option overrides safety checks.
171 It should be used with extreme caution.
173 option is required in order to use the
180 option applies the command recursively to subordinate objects.
186 option will also show information about the plexes and subdisks belonging to
188 It is also used by the
190 command to indicate that subordinate objects such as subdisks should be renamed
191 to match the object(s) specified and by the
193 command to delete plexes belonging to a volume and so on.
198 option provides more detailed output.
202 .Pq Dq "very verbose"
203 option provides even more detailed output than
207 .Bl -tag -width ".Ev EDITOR"
209 The name of the editor to use for editing configuration files, by
215 .Bl -tag -width ".Pa /dev/gvinum/plex"
217 directory with device nodes for
220 .It Pa /dev/gvinum/plex
221 directory containing device nodes for
224 .It Pa /dev/gvinum/sd
225 directory containing device nodes for
235 utility first appeared in
241 is based, was written by
254 documentation were added by
256 through the 2005 Google Summer
259 .An Lukas Ertl Aq le@FreeBSD.org
260 .An Chris Jones Aq soc-cjones@FreeBSD.org
264 does not rename devices in
276 command does not work.
278 Moving subdisks that are not part of a mirrored or RAID-5 volume will
280 It is perhaps a bug to permit this.
282 Plexes in which subdisks have been moved do not automatically sync or
284 This may leave data unprotected and is perhaps unwise.
288 does not yet fully implement all of the functions found in
290 Specifically, the following commands from
293 .Bl -tag -width indent
294 .It Ic attach Ar plex volume Op Cm rename
295 .It Ic attach Ar subdisk plex Oo Ar offset Oc Op Cm rename
296 Attach a plex to a volume, or a subdisk to a plex.
297 .It Ic concat Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives
298 Create a concatenated volume from the specified drives.
300 Cause the volume manager to enter the kernel debugger.
301 .It Ic debug Ar flags
303 .It Ic detach Oo Fl f Oc Op Ar plex | subdisk
304 Detach a plex or subdisk from the volume or plex to which it is
306 .It Ic dumpconfig Op Ar drive ...
307 List the configuration information stored on the specified drives, or all
308 drives in the system if no drive names are specified.
310 List information about volume manager state.
311 .It Ic label Ar volume
312 Create a volume label.
313 .It Ic mirror Oo Fl fsv Oc Oo Fl n Ar name Oc Ar drives
314 Create a mirrored volume from the specified drives.
315 .It Ic resetstats Oo Fl r Oc Op Ar volume | plex | subdisk
316 Reset statistics counters for the specified objects, or for all objects if none
318 .It Ic setdaemon Op Ar value
319 Set daemon configuration.
320 .It Ic stop Oo Fl f Oc Op Ar volume | plex | subdisk
321 Terminate access to the objects, or stop
323 if no parameters are specified.
324 .It Ic stripe Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives
325 Create a striped volume from the specified drives.