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 attach Ar plex volume Op Cm rename
44 .It Ic attach Ar subdisk plex Oo Ar offset Oc Op Cm rename
45 Attach a plex to a volume, or a subdisk to a plex.
46 If offset is specified, the subdisk will be attached to the given offset within
48 If rename is specified, the subdisk or plex will change name according to the
49 object it attaches to.
50 .It Ic checkparity Oo Fl f Oc Ar plex
51 Check the parity blocks of a RAID-5 plex.
52 The parity check will start at the
53 beginning of the plex if the
55 flag is specified, or otherwise at the location of the parity check pointer,
56 the first location at which plex's parity is incorrect.
58 plex must be up for a parity check.
59 .It Ic concat Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives
60 Create a concatenated volume from the specified drives.
61 If no name is specified, a unique name will be set by
63 .It Ic create Oo Fl f Oc Op Ar description-file
64 Create a volume as described in
65 .Ar description-file .
68 provided, opens an editor and provides the current
70 configuration for editing.
73 flag will make gvinum ignore any errors regarding creating objects that already
75 However, in contrast to vinum, objects that are not properly named in the
77 will not be created when the
80 .It Ic detach Oo Fl f Oc Op Ar plex | subdisk
81 Detach a plex or subdisk from the volume or plex to which it is
83 .It Ic grow Ar plex device
84 Grow a plex by creating a gvinum drive and subdisk on device and attach it to
86 If required by the plex organization, it will be put into the growable state.
88 Provides a synopsis of
90 commands and arguments.
91 .It Ic l | list Oo Fl rvV Oc Op Ar volume | plex | subdisk
92 .It Ic ld Oo Fl rvV Oc Op Ar drive ...
93 .It Ic ls Oo Fl rvV Oc Op Ar subdisk ...
94 .It Ic lp Oo Fl rvV Oc Op Ar plex ...
95 .It Ic lv Oo Fl rvV Oc Op Ar volume ...
96 List information about the relevant object(s).
99 flag provides recursive display, showing each object's subordinate objects in
105 flags provide progressively more detailed output.
106 .It Ic mirror Oo Fl fsv Oc Oo Fl n Ar name Oc Ar drives
107 Create a mirrored volume from the specified drives.
108 It requires at least a multiple of 2 drives.
109 If no name is specified, a unique name will be set by gvinum.
112 flag is specified, a striped mirror will be created, and thus requires a
113 multiple of 4 drives.
114 .It Ic move | mv Fl f Ar drive subdisk Op Ar ...
115 Move the subdisk(s) to the specified drive.
118 flag is required, as all data on the indicated subdisk(s) will be destroyed as
120 This can currently only be done when the subdisk is
123 If a single subdisk is moved, and it forms a part of a RAID-5 plex, the moved
124 subdisks will need to be set to the
126 state, and the plex will require a
129 If multiple subdisk(s) is moved, and form part of a RAID-5 plex, the
130 moved disk(s) will need to be set to the
132 state and the plex will require a
135 If the subdisk(s) form part of a plex that is mirrored with other
136 plexes, the plex will require restarting and will sync once restarted.
138 more than one subdisk in a RAID-5 plex or subdisks from both sides of a
139 mirrored plex volume will destroy data.
140 Note that parity rebuilds and syncing
141 must be started manually after a move.
143 Write a copy of the current configuration to standard output.
147 when running in interactive mode.
148 Normally this would be done by entering the
150 .It Ic raid5 Oo Fl fv Oc Oo Fl s Ar stripesize Oc Oo Fl n Ar name Oc Ar drives
151 Create a RAID-5 volume from the specified drives.
152 If no name is specified, a unique name will be set by
154 This organization requires at least three drives.
155 .It Ic rename Oo Fl r Oc Ar drive | subdisk | plex | volume newname
156 Change the name of the specified object.
159 flag will recursively rename subordinate objects.
161 Note that device nodes will not be renamed until
164 .It Ic rebuildparity Oo Fl f Oc Ar plex
165 Rebuild the parity blocks of a RAID-5 plex.
166 The parity rebuild will start at
167 the beginning of the plex if the
169 flag is specified, or otherwise at the location of the parity check pointer.
170 All subdisks in the plex must be up for a parity check.
171 .It Ic resetconfig Oo Fl f Oc
175 .It Ic rm Oo Fl r Oc Ar volume | plex | subdisk
176 Remove an object and, if
178 is specified, its subordinate objects.
182 configuration to disk after configuration failures.
183 .It Ic setstate Oo Fl f Oc Ar state volume | plex | subdisk | drive
184 Set state without influencing other objects, for diagnostic purposes
188 flag forces state changes regardless of whether they are legal.
190 Read configuration from all vinum drives.
191 .It Ic start Oo Fl S Ar size Oc Ar volume | plex | subdisk
192 Allow the system to access the objects.
193 If necessary, plexes will be synced and rebuilt.
194 If a subdisk was added to a running RAID-5 or striped plex, gvinum will
195 expand into this subdisk and grow the whole RAID-5 array.
196 This can be done without unmounting your filesystem.
199 flag is currently ignored.
200 .It Ic stop Oo Fl f Oc Op Ar volume | plex | subdisk
201 Terminate access to the objects, or stop
203 if no parameters are specified.
204 .It Ic stripe Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives
205 Create a striped volume from the specified drives. If no name is specified,
206 a unique name will be set by
208 This organization requires at least two drives.
213 utility communicates with the kernel component of the GVinum logical volume
215 It is designed either for interactive use, when started without
216 command line arguments, or to execute a single command if the command is
217 supplied on the command line.
220 maintains a command line history.
224 commands may be followed by an option.
225 .Bl -tag -width indent
230 option overrides safety checks.
231 It should be used with extreme caution.
233 option is required in order to use the
240 option applies the command recursively to subordinate objects.
246 option will also show information about the plexes and subdisks belonging to
248 It is also used by the
250 command to indicate that subordinate objects such as subdisks should be renamed
251 to match the object(s) specified and by the
253 command to delete plexes belonging to a volume and so on.
258 option provides more detailed output.
262 .Pq Dq "very verbose"
263 option provides even more detailed output than
267 .Bl -tag -width ".Ev EDITOR"
269 The name of the editor to use for editing configuration files, by
275 .Bl -tag -width ".Pa /dev/gvinum/plex"
277 directory with device nodes for
282 To create a mirror on disks /dev/ada1 and /dev/ada2, create a filesystem,
283 mount, unmount and then stop
286 .Dl "gvinum mirror /dev/ada1 /dev/ada2"
287 .Dl "newfs /dev/gvinum/gvinumvolume0"
288 .Dl "mount /dev/gvinum/gvinumvolume0 /mnt"
293 To create a striped mirror on disks /dev/ada1 /dev/ada2 /dev/ada3 and
294 /dev/ada4 named "data" and create a filesystem:
296 .Dl "gvinum mirror -s -n data /dev/ada1 /dev/ada2 /dev/ada3 /dev/ada4"
297 .Dl "newfs /dev/gvinum/data"
299 To create a raid5 array on disks /dev/ada1 /dev/ada2 and /dev/ada3,
300 with stripesize 493k you can use the raid5 command:
302 .Dl "gvinum raid5 -s 493k /dev/ada1 /dev/ada2 /dev/ada3"
304 Then the volume will be created automatically.
305 Afterwards, you have to initialize the volume:
307 .Dl "gvinum start myraid5vol"
309 The initialization will start, and the states will be updated when it's
311 The list command will give you information about its progress.
313 Imagine that one of the drives fails, and the output of 'printconfig' looks
316 .Dl "drive gvinumdrive1 device /dev/ada2"
317 .Dl "drive gvinumdrive2 device /dev/???"
318 .Dl "drive gvinumdrive0 device /dev/ada1"
319 .Dl "volume myraid5vol"
320 .Dl "plex name myraid5vol.p0 org raid5 986s vol myraid5vol"
321 .Dl "sd name myraid5vol.p0.s2 drive gvinumdrive2 len 32538s driveoffset 265s"
322 .Dl "plex myraid5vol.p0 plexoffset 1972s"
323 .Dl "sd name myraid5vol.p0.s1 drive gvinumdrive1 len 32538s driveoffset 265s"
324 .Dl "plex myraid5vol.p0 plexoffset 986s"
325 .Dl "sd name myraid5vol.p0.s0 drive gvinumdrive0 len 32538s driveoffset 265s"
326 .Dl "plex myraid5vol.p0 plexoffset 0s"
328 Create a new drive with this configuration:
330 .Dl "drive gdrive4 device /dev/ada4"
332 Then move the stale subdisk to the new drive:
334 .Dl "gvinum move gdrive4 myraid5vol.p0.s2"
336 Then, initiate the rebuild:
338 .Dl "gvinum start myraid5vol.p0"
340 The plex will go up form degraded mode after the rebuild is finished.
341 The plex can still be used while the rebuild is in progress, although requests
344 Given the configuration as in the previous example, growing a RAID-5 or STRIPED
345 array is accomplished by using the grow command:
347 .Dl "gvinum grow myraid5vol.p0 /dev/ada4"
349 If everything went ok, the plex state should now be set to growable.
350 You can then start the growing with the
354 .Dl "gvinum start myraid5vol.p0"
356 As with rebuilding, you can watch the progress using the
360 For a more advanced usage and detailed explanation of gvinum, the
361 handbook is recommended.
368 utility first appeared in
374 is based, was written by
387 documentation were added by
389 through the 2005 Google Summer
391 A partial rewrite of gvinum was done by
395 through the 2007 Google Summer of Code program.
396 The documentation have been updated to reflect the new functionality.
398 .An Lukas Ertl Aq le@FreeBSD.org
399 .An Chris Jones Aq soc-cjones@FreeBSD.org
400 .An Ulf Lilleengen Aq lulf@FreeBSD.org
404 does not rename devices in
414 Moving subdisks that are not part of a mirrored or RAID-5 volume will
416 It is perhaps a bug to permit this.
418 Plexes in which subdisks have been moved do not automatically sync or
420 This may leave data unprotected and is perhaps unwise.
424 does not yet fully implement all of the functions found in
426 Specifically, the following commands from
429 .Bl -tag -width indent
431 Cause the volume manager to enter the kernel debugger.
432 .It Ic debug Ar flags
434 .It Ic dumpconfig Op Ar drive ...
435 List the configuration information stored on the specified drives, or all
436 drives in the system if no drive names are specified.
438 List information about volume manager state.
439 .It Ic label Ar volume
440 Create a volume label.
441 .It Ic resetstats Oo Fl r Oc Op Ar volume | plex | subdisk
442 Reset statistics counters for the specified objects, or for all objects if none
444 .It Ic setdaemon Op Ar value
445 Set daemon configuration.