1.\" Copyright (c) 2005 Chris Jones 2.\" All rights reserved. 3.\" 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. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 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. 16.\" 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 27.\" SUCH DAMAGE. 28.\" 29.\" $FreeBSD$ 30.\" 31.Dd March 23, 2006 32.Dt GVINUM 8 33.Os 34.Sh NAME 35.Nm gvinum 36.Nd Logical Volume Manager control program 37.Sh SYNOPSIS 38.Nm 39.Op Ar command 40.Op Fl options 41.Sh COMMANDS 42.Bl -tag -width indent 43.It Ic checkparity Oo Fl f Oc Ar plex 44Check the parity blocks of a RAID-5 plex. 45The parity check will start at the 46beginning of the plex if the 47.Fl f 48flag is specified, or otherwise at the location of the parity check pointer, 49the first location at which plex's parity is incorrect. 50All subdisks in the 51plex must be up for a parity check. 52.It Ic create Op Ar description-file 53Create a volume as described in 54.Ar description-file . 55If no 56.Ar description-file 57provided, opens an editor and provides the current 58.Nm 59configuration for editing. 60.It Ic help 61Provides a synopsis of 62.Nm 63commands 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 ... 69List information about the relevant object(s). 70The 71.Fl r 72flag provides recursive display, showing each object's subordinate objects in 73proper relation. 74The 75.Fl v 76and 77.Fl V 78flags provide progressively more detailed output. 79.It Ic move | mv Fl f Ar drive subdisk Op Ar ... 80Move the subdisk(s) to the specified drive. 81The 82.Fl f 83flag is required, as all data on the indicated subdisk(s) will be destroyed as 84part of the move. 85This can currently only be done when the subdisk is 86not being accessed. 87.Pp 88If the subdisk(s) form part of a RAID-5 plex, the disk(s) will need to be set 89to the 90.Dq up 91state and the plex will require a 92.Ic rebuildparity 93command; if the subdisk(s) form part of a plex that is mirrored with other 94plexes, the plex will require restarting and will sync once restarted. 95Moving 96more than one subdisk in a RAID-5 plex or subdisks from both sides of a 97mirrored plex volume will destroy data. 98Note that parity rebuilds and syncing 99must be started manually after a move. 100.It Ic printconfig 101Write a copy of the current configuration to standard output. 102.It Ic quit 103Exit 104.Nm 105when running in interactive mode. 106Normally this would be done by entering the 107EOF character. 108.It Ic rename Oo Fl r Oc Ar drive | subdisk | plex | volume newname 109Change the name of the specified object. 110The 111.Fl r 112flag will recursively rename subordinate objects. 113.Pp 114Note that device nodes will not be renamed until 115.Nm 116is restarted. 117.It Ic rebuildparity Oo Fl f Oc Ar plex 118Rebuild the parity blocks of a RAID-5 plex. 119The parity rebuild will start at 120the beginning of the plex if the 121.Fl f 122flag is specified, or otherwise at the location of the parity check pointer. 123All subdisks in the plex must be up for a parity check. 124.It Ic resetconfig 125Reset the complete 126.Nm 127configuration. 128.It Ic rm Oo Fl r Oc Ar volume | plex | subdisk 129Remove an object and, if 130.Fl r 131is specified, its subordinate objects. 132.It Ic saveconfig 133Save 134.Nm 135configuration to disk after configuration failures. 136.It Ic setstate Oo Fl f Oc Ar state volume | plex | subdisk | drive 137Set state without influencing other objects, for diagnostic purposes 138only. 139The 140.Fl f 141flag forces state changes regardless of whether they are legal. 142.It Ic start 143Read configuration from all vinum drives. 144.It Ic start Oo Fl S Ar size Oc Ar volume | plex | subdisk 145Allow the system to access the objects. 146The 147.Fl S 148flag is currently ignored. 149.El 150.Sh DESCRIPTION 151The 152.Nm 153utility communicates with the kernel component of the GVinum logical volume 154manager. 155It is designed either for interactive use, when started without 156command line arguments, or to execute a single command if the command is 157supplied on the command line. 158In interactive mode, 159.Nm 160maintains a command line history. 161.Sh OPTIONS 162The 163.Nm 164commands may be followed by an option. 165.Bl -tag -width indent 166.It Fl f 167The 168.Fl f 169.Pq Dq force 170option overrides safety checks. 171It should be used with extreme caution. 172This 173option is required in order to use the 174.Ic move 175command. 176.It Fl r 177The 178.Fl r 179.Pq Dq recursive 180option applies the command recursively to subordinate objects. 181For example, in 182conjunction with the 183.Ic lv 184command, the 185.Fl r 186option will also show information about the plexes and subdisks belonging to 187the volume. 188It is also used by the 189.Ic rename 190command to indicate that subordinate objects such as subdisks should be renamed 191to match the object(s) specified and by the 192.Ic rm 193command to delete plexes belonging to a volume and so on. 194.It Fl v 195The 196.Fl v 197.Pq Dq verbose 198option provides more detailed output. 199.It Fl V 200The 201.Fl V 202.Pq Dq "very verbose" 203option provides even more detailed output than 204.Fl v . 205.El 206.Sh ENVIRONMENT 207.Bl -tag -width ".Ev EDITOR" 208.It Ev EDITOR 209The name of the editor to use for editing configuration files, by 210default 211.Xr vi 1 212is invoked. 213.El 214.Sh FILES 215.Bl -tag -width ".Pa /dev/gvinum/plex" 216.It Pa /dev/gvinum 217directory with device nodes for 218.Nm 219objects 220.It Pa /dev/gvinum/plex 221directory containing device nodes for 222.Nm 223plexes 224.It Pa /dev/gvinum/sd 225directory containing device nodes for 226.Nm 227subdisks 228.El 229.Sh SEE ALSO 230.Xr geom 4 , 231.Xr geom 8 232.Sh HISTORY 233The 234.Nm 235utility first appeared in 236.Fx 5.3 . 237The 238.Nm vinum 239utility, on which 240.Nm 241is based, was written by 242.An "Greg Lehey" . 243.Pp 244The 245.Nm 246utility 247was written by 248.An "Lukas Ertl" . 249The 250.Ic move 251and 252.Ic rename 253commands and 254documentation were added by 255.An "Chris Jones" 256through the 2005 Google Summer 257of Code program. 258.Sh AUTHORS 259.An Lukas Ertl Aq le@FreeBSD.org 260.An Chris Jones Aq soc-cjones@FreeBSD.org 261.Sh BUGS 262Currently, 263.Nm 264does not rename devices in 265.Pa /dev/gvinum 266until reloaded. 267.Pp 268The 269.Fl S 270initsize flag to 271.Ic start 272is ignored. 273.Pp 274The 275.Ic stop 276command does not work. 277.Pp 278Moving subdisks that are not part of a mirrored or RAID-5 volume will 279destroy data. 280It is perhaps a bug to permit this. 281.Pp 282Plexes in which subdisks have been moved do not automatically sync or 283rebuild parity. 284This may leave data unprotected and is perhaps unwise. 285.Pp 286Currently, 287.Nm 288does not yet fully implement all of the functions found in 289.Xr vinum 4 . 290Specifically, the following commands from 291.Xr vinum 4 292are not supported: 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 296Attach 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 298Create a concatenated volume from the specified drives. 299.It Ic debug 300Cause the volume manager to enter the kernel debugger. 301.It Ic debug Ar flags 302Set debugging flags. 303.It Ic detach Oo Fl f Oc Op Ar plex | subdisk 304Detach a plex or subdisk from the volume or plex to which it is 305attached. 306.It Ic dumpconfig Op Ar drive ... 307List the configuration information stored on the specified drives, or all 308drives in the system if no drive names are specified. 309.It Ic info Op Fl vV 310List information about volume manager state. 311.It Ic label Ar volume 312Create a volume label. 313.It Ic mirror Oo Fl fsv Oc Oo Fl n Ar name Oc Ar drives 314Create a mirrored volume from the specified drives. 315.It Ic resetstats Oo Fl r Oc Op Ar volume | plex | subdisk 316Reset statistics counters for the specified objects, or for all objects if none 317are specified. 318.It Ic setdaemon Op Ar value 319Set daemon configuration. 320.It Ic stop Oo Fl f Oc Op Ar volume | plex | subdisk 321Terminate access to the objects, or stop 322.Nm 323if no parameters are specified. 324.It Ic stripe Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives 325Create a striped volume from the specified drives. 326.El 327