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.Dd March 28, 2021 30.Dt GVINUM 8 31.Os 32.Sh NAME 33.Nm gvinum 34.Nd Logical Volume Manager control program 35.Sh DEPRECATION NOTICE 36.Nm 37and associated 38.Xr geom 4 39kernel support is deprecated, and may not be available in 40.Fx 14.0 41and later. 42Users are advised to migrate to 43.Xr gconcat 8 , 44.Xr gmirror 8 , 45.Xr gstripe 8 , 46.Xr graid 8 , 47or 48.Xr zfs 8 . 49More information is available at 50.Pa https://wiki.freebsd.org/DeprecationPlan/gvinum . 51.Sh SYNOPSIS 52.Nm 53.Op Ar command 54.Op Fl options 55.Sh COMMANDS 56.Bl -tag -width indent 57.It Ic attach Ar plex volume Op Cm rename 58.It Ic attach Ar subdisk plex Oo Ar offset Oc Op Cm rename 59Attach a plex to a volume, or a subdisk to a plex. 60If offset is specified, the subdisk will be attached to the given offset within 61the plex. 62If rename is specified, the subdisk or plex will change name according to the 63object it attaches to. 64.It Ic checkparity Oo Fl f Oc Ar plex 65Check the parity blocks of a RAID-5 plex. 66The parity check will start at the 67beginning of the plex if the 68.Fl f 69flag is specified, or otherwise at the location of the parity check pointer, 70the first location at which plex's parity is incorrect. 71All subdisks in the 72plex must be up for a parity check. 73.It Ic concat Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives 74Create a concatenated volume from the specified drives. 75If no name is specified, a unique name will be set by 76.Ic gvinum . 77.It Ic create Oo Fl f Oc Op Ar description-file 78Create a volume as described in 79.Ar description-file . 80If no 81.Ar description-file 82provided, opens an editor and provides the current 83.Nm 84configuration for editing. 85The 86.Fl f 87flag will make gvinum ignore any errors regarding creating objects that already 88exists. 89However, in contrast to vinum, objects that are not properly named in the 90.Ar description-file 91will not be created when the 92.Fl f 93flag is given. 94.It Ic detach Oo Fl f Oc Op Ar plex | subdisk 95Detach a plex or subdisk from the volume or plex to which it is 96attached. 97.It Ic grow Ar plex device 98Grow a plex by creating a gvinum drive and subdisk on device and attach it to 99the plex. 100If required by the plex organization, it will be put into the growable state. 101.It Ic help 102Provides a synopsis of 103.Nm 104commands and arguments. 105.It Ic l | list Oo Fl rvV Oc Op Ar volume | plex | subdisk 106.It Ic ld Oo Fl rvV Oc Op Ar drive ... 107.It Ic ls Oo Fl rvV Oc Op Ar subdisk ... 108.It Ic lp Oo Fl rvV Oc Op Ar plex ... 109.It Ic lv Oo Fl rvV Oc Op Ar volume ... 110List information about the relevant object(s). 111The 112.Fl r 113flag provides recursive display, showing each object's subordinate objects in 114proper relation. 115The 116.Fl v 117and 118.Fl V 119flags provide progressively more detailed output. 120.It Ic mirror Oo Fl fsv Oc Oo Fl n Ar name Oc Ar drives 121Create a mirrored volume from the specified drives. 122It requires at least a multiple of 2 drives. 123If no name is specified, a unique name will be set by gvinum. 124If the 125.Fl s 126flag is specified, a striped mirror will be created, and thus requires a 127multiple of 4 drives. 128.It Ic move | mv Fl f Ar drive subdisk Op Ar ... 129Move the subdisk(s) to the specified drive. 130The 131.Fl f 132flag is required, as all data on the indicated subdisk(s) will be destroyed as 133part of the move. 134This can currently only be done when the subdisk is 135not being accessed. 136.Pp 137If a single subdisk is moved, and it forms a part of a RAID-5 plex, the moved 138subdisks will need to be set to the 139.Dq stale 140state, and the plex will require a 141.Ic start 142command. 143If multiple subdisk(s) is moved, and form part of a RAID-5 plex, the 144moved disk(s) will need to be set to the 145.Dq up 146state and the plex will require a 147.Ic rebuildparity 148command. 149If the subdisk(s) form part of a plex that is mirrored with other 150plexes, the plex will require restarting and will sync once restarted. 151Moving 152more than one subdisk in a RAID-5 plex or subdisks from both sides of a 153mirrored plex volume will destroy data. 154Note that parity rebuilds and syncing 155must be started manually after a move. 156.It Ic printconfig 157Write a copy of the current configuration to standard output. 158.It Ic quit 159Exit 160.Nm 161when running in interactive mode. 162Normally this would be done by entering the 163EOF character. 164.It Ic raid5 Oo Fl fv Oc Oo Fl s Ar stripesize Oc Oo Fl n Ar name Oc Ar drives 165Create a RAID-5 volume from the specified drives. 166If no name is specified, a unique name will be set by 167.Ic gvinum . 168This organization requires at least three drives. 169.It Ic rename Oo Fl r Oc Ar drive | subdisk | plex | volume newname 170Change the name of the specified object. 171The 172.Fl r 173flag will recursively rename subordinate objects. 174.Pp 175Note that device nodes will not be renamed until 176.Nm 177is restarted. 178.It Ic rebuildparity Oo Fl f Oc Ar plex 179Rebuild the parity blocks of a RAID-5 plex. 180The parity rebuild will start at 181the beginning of the plex if the 182.Fl f 183flag is specified, or otherwise at the location of the parity check pointer. 184All subdisks in the plex must be up for a parity check. 185.It Ic resetconfig Oo Fl f Oc 186Reset the complete 187.Nm 188configuration. 189.It Ic rm Oo Fl r Oc Ar volume | plex | subdisk 190Remove an object and, if 191.Fl r 192is specified, its subordinate objects. 193.It Ic saveconfig 194Save 195.Nm 196configuration to disk after configuration failures. 197.It Ic setstate Oo Fl f Oc Ar state volume | plex | subdisk | drive 198Set state without influencing other objects, for diagnostic purposes 199only. 200The 201.Fl f 202flag forces state changes regardless of whether they are legal. 203.It Ic start 204Read configuration from all vinum drives. 205.It Ic start Oo Fl S Ar size Oc Ar volume | plex | subdisk 206Allow the system to access the objects. 207If necessary, plexes will be synced and rebuilt. 208If a subdisk was added to a running RAID-5 or striped plex, gvinum will 209expand into this subdisk and grow the whole RAID-5 array. 210This can be done without unmounting your filesystem. 211The 212.Fl S 213flag is currently ignored. 214.It Ic stop Oo Fl f Oc Op Ar volume | plex | subdisk 215Terminate access to the objects, or stop 216.Nm 217if no parameters are specified. 218.It Ic stripe Oo Fl fv Oc Oo Fl n Ar name Oc Ar drives 219Create a striped volume from the specified drives. 220If no name is specified, a unique name will be set by 221.Ic gvinum . 222This organization requires at least two drives. 223.El 224.Sh DESCRIPTION 225The 226.Nm 227utility communicates with the kernel component of the GVinum logical volume 228manager. 229It is designed either for interactive use, when started without 230command line arguments, or to execute a single command if the command is 231supplied on the command line. 232In interactive mode, 233.Nm 234maintains a command line history. 235.Sh OPTIONS 236The 237.Nm 238commands may be followed by an option. 239.Bl -tag -width indent 240.It Fl f 241The 242.Fl f 243.Pq Dq force 244option overrides safety checks. 245It should be used with extreme caution. 246This 247option is required in order to use the 248.Ic move 249command. 250.It Fl r 251The 252.Fl r 253.Pq Dq recursive 254option applies the command recursively to subordinate objects. 255For example, in 256conjunction with the 257.Ic lv 258command, the 259.Fl r 260option will also show information about the plexes and subdisks belonging to 261the volume. 262It is also used by the 263.Ic rename 264command to indicate that subordinate objects such as subdisks should be renamed 265to match the object(s) specified and by the 266.Ic rm 267command to delete plexes belonging to a volume and so on. 268.It Fl v 269The 270.Fl v 271.Pq Dq verbose 272option provides more detailed output. 273.It Fl V 274The 275.Fl V 276.Pq Dq "very verbose" 277option provides even more detailed output than 278.Fl v . 279.El 280.Sh ENVIRONMENT 281.Bl -tag -width ".Ev EDITOR" 282.It Ev EDITOR 283The name of the editor to use for editing configuration files, by 284default 285.Xr vi 1 286is invoked. 287.El 288.Sh FILES 289.Bl -tag -width ".Pa /dev/gvinum/plex" 290.It Pa /dev/gvinum 291directory with device nodes for 292.Nm 293objects 294.El 295.Sh EXAMPLES 296To create a mirror on disks /dev/ada1 and /dev/ada2, create a filesystem, 297mount, unmount and then stop 298.Ic gvinum : 299.Pp 300.Dl "gvinum mirror /dev/ada1 /dev/ada2" 301.Dl "newfs /dev/gvinum/gvinumvolume0" 302.Dl "mount /dev/gvinum/gvinumvolume0 /mnt" 303.Dl "..." 304.Dl "unmount /mnt" 305.Dl "gvinum stop" 306.Pp 307To create a striped mirror on disks /dev/ada1 /dev/ada2 /dev/ada3 and 308/dev/ada4 named "data" and create a filesystem: 309.Pp 310.Dl "gvinum mirror -s -n data /dev/ada1 /dev/ada2 /dev/ada3 /dev/ada4" 311.Dl "newfs /dev/gvinum/data" 312.Pp 313To create a raid5 array on disks /dev/ada1 /dev/ada2 and /dev/ada3, 314with stripesize 493k you can use the raid5 command: 315.Pp 316.Dl "gvinum raid5 -s 493k /dev/ada1 /dev/ada2 /dev/ada3" 317.Pp 318Then the volume will be created automatically. 319Afterwards, you have to initialize the volume: 320.Pp 321.Dl "gvinum start myraid5vol" 322.Pp 323The initialization will start, and the states will be updated when it's 324finished. 325The list command will give you information about its progress. 326.Pp 327Imagine that one of the drives fails, and the output of 'printconfig' looks 328something like this: 329.Pp 330.Dl "drive gvinumdrive1 device /dev/ada2" 331.Dl "drive gvinumdrive2 device /dev/???" 332.Dl "drive gvinumdrive0 device /dev/ada1" 333.Dl "volume myraid5vol" 334.Dl "plex name myraid5vol.p0 org raid5 986s vol myraid5vol" 335.Dl "sd name myraid5vol.p0.s2 drive gvinumdrive2 len 32538s driveoffset 265s" 336.Dl "plex myraid5vol.p0 plexoffset 1972s" 337.Dl "sd name myraid5vol.p0.s1 drive gvinumdrive1 len 32538s driveoffset 265s" 338.Dl "plex myraid5vol.p0 plexoffset 986s" 339.Dl "sd name myraid5vol.p0.s0 drive gvinumdrive0 len 32538s driveoffset 265s" 340.Dl "plex myraid5vol.p0 plexoffset 0s" 341.Pp 342Create a new drive with this configuration: 343.Pp 344.Dl "drive gdrive4 device /dev/ada4" 345.Pp 346Then move the stale subdisk to the new drive: 347.Pp 348.Dl "gvinum move gdrive4 myraid5vol.p0.s2" 349.Pp 350Then, initiate the rebuild: 351.Pp 352.Dl "gvinum start myraid5vol.p0" 353.Pp 354The plex will go up form degraded mode after the rebuild is finished. 355The plex can still be used while the rebuild is in progress, although requests 356might be delayed. 357.Pp 358Given the configuration as in the previous example, growing a RAID-5 or STRIPED 359array is accomplished by using the grow command: 360.Pp 361.Dl "gvinum grow myraid5vol.p0 /dev/ada4" 362.Pp 363If everything went ok, the plex state should now be set to growable. 364You can then start the growing with the 365.Ic start 366command: 367.Pp 368.Dl "gvinum start myraid5vol.p0" 369.Pp 370As with rebuilding, you can watch the progress using the 371.Ic list 372command. 373.Pp 374For a more advanced usage and detailed explanation of gvinum, the 375handbook is recommended. 376.Sh SEE ALSO 377.Xr geom 4 , 378.Xr geom 8 379.Sh HISTORY 380The 381.Nm 382utility first appeared in 383.Fx 5.3 . 384The 385.Nm vinum 386utility, on which 387.Nm 388is based, was written by 389.An "Greg Lehey" . 390.Pp 391The 392.Nm 393utility 394was written by 395.An "Lukas Ertl" . 396The 397.Ic move 398and 399.Ic rename 400commands and 401documentation were added by 402.An "Chris Jones" 403through the 2005 Google Summer 404of Code program. 405A partial rewrite of gvinum was done by 406.An "Lukas Ertl" 407and 408.An "Ulf Lilleengen" 409through the 2007 Google Summer of Code program. 410The documentation have been updated to reflect the new functionality. 411.Sh AUTHORS 412.An Lukas Ertl Aq Mt le@FreeBSD.org 413.An Chris Jones Aq Mt soc-cjones@FreeBSD.org 414.An Ulf Lilleengen Aq Mt lulf@FreeBSD.org 415.Sh BUGS 416Currently, 417.Nm 418does not rename devices in 419.Pa /dev/gvinum 420until reloaded. 421.Pp 422The 423.Fl S 424initsize flag to 425.Ic start 426is ignored. 427.Pp 428Moving subdisks that are not part of a mirrored or RAID-5 volume will 429destroy data. 430It is perhaps a bug to permit this. 431.Pp 432Plexes in which subdisks have been moved do not automatically sync or 433rebuild parity. 434This may leave data unprotected and is perhaps unwise. 435.Pp 436Currently, 437.Nm 438does not yet fully implement all of the functions found in 439.Nm vinum . 440Specifically, the following commands from 441.Nm vinum 442are not supported: 443.Bl -tag -width indent 444.It Ic debug 445Cause the volume manager to enter the kernel debugger. 446.It Ic debug Ar flags 447Set debugging flags. 448.It Ic dumpconfig Op Ar drive ... 449List the configuration information stored on the specified drives, or all 450drives in the system if no drive names are specified. 451.It Ic info Op Fl vV 452List information about volume manager state. 453.It Ic label Ar volume 454Create a volume label. 455.It Ic resetstats Oo Fl r Oc Op Ar volume | plex | subdisk 456Reset statistics counters for the specified objects, or for all objects if none 457are specified. 458.It Ic setdaemon Op Ar value 459Set daemon configuration. 460.El 461