GVINUM(8) FreeBSD System Manager's Manual GVINUM(8)
NAME
gvinum - Logical Volume Manager control program
DEPRECATION NOTICE
gvinum and associated geom(4) kernel support is deprecated, and may not
be available in FreeBSD 14.0 and later. Users are advised to migrate to
gconcat(8), gmirror(8), gstripe(8), graid(8), or ZFS(8). More
information is available at
https://wiki.freebsd.org/DeprecationPlan/gvinum.
SYNOPSIS
gvinum [command] [-options]
COMMANDS
attach plex volume [rename]
attach subdisk plex [offset] [rename]
Attach a plex to a volume, or a subdisk to a plex. If offset is
specified, the subdisk will be attached to the given offset
within the plex. If rename is specified, the subdisk or plex
will change name according to the object it attaches to.
checkparity [-f] plex
Check the parity blocks of a RAID-5 plex. The parity check will
start at the beginning of the plex if the -f flag is specified,
or otherwise at the location of the parity check pointer, the
first location at which plex's parity is incorrect. All subdisks
in the plex must be up for a parity check.
concat [-fv] [-n name] drives
Create a concatenated volume from the specified drives. If no
name is specified, a unique name will be set by gvinum.
create [-f] [description-file]
Create a volume as described in description-file. If no
description-file provided, opens an editor and provides the
current gvinum configuration for editing. The -f flag will make
gvinum ignore any errors regarding creating objects that already
exists. However, in contrast to vinum, objects that are not
properly named in the description-file will not be created when
the -f flag is given.
detach [-f] [plex | subdisk]
Detach a plex or subdisk from the volume or plex to which it is
attached.
grow plex device
Grow a plex by creating a gvinum drive and subdisk on device and
attach it to the plex. If required by the plex organization, it
will be put into the growable state.
help Provides a synopsis of gvinum commands and arguments.
l | list [-rvV] [volume | plex | subdisk]
ld [-rvV] [drive ...]
ls [-rvV] [subdisk ...]
lp [-rvV] [plex ...]
lv [-rvV] [volume ...]
List information about the relevant object(s). The -r flag
provides recursive display, showing each object's subordinate
objects in proper relation. The -v and -V flags provide
progressively more detailed output.
mirror [-fsv] [-n name] drives
Create a mirrored volume from the specified drives. It requires
at least a multiple of 2 drives. If no name is specified, a
unique name will be set by gvinum. If the -s flag is specified,
a striped mirror will be created, and thus requires a multiple of
4 drives.
move | mv -f drive subdisk [...]
Move the subdisk(s) to the specified drive. The -f flag is
required, as all data on the indicated subdisk(s) will be
destroyed as part of the move. This can currently only be done
when the subdisk is not being accessed.
If a single subdisk is moved, and it forms a part of a RAID-5
plex, the moved subdisks will need to be set to the "stale"
state, and the plex will require a start command. If multiple
subdisk(s) is moved, and form part of a RAID-5 plex, the moved
disk(s) will need to be set to the "up" state and the plex will
require a rebuildparity command. If the subdisk(s) form part of
a plex that is mirrored with other plexes, the plex will require
restarting and will sync once restarted. Moving more than one
subdisk in a RAID-5 plex or subdisks from both sides of a
mirrored plex volume will destroy data. Note that parity
rebuilds and syncing must be started manually after a move.
printconfig
Write a copy of the current configuration to standard output.
quit Exit gvinum when running in interactive mode. Normally this
would be done by entering the EOF character.
raid5 [-fv] [-s stripesize] [-n name] drives
Create a RAID-5 volume from the specified drives. If no name is
specified, a unique name will be set by gvinum. This
organization requires at least three drives.
rename [-r] drive | subdisk | plex | volume newname
Change the name of the specified object. The -r flag will
recursively rename subordinate objects.
Note that device nodes will not be renamed until gvinum is
restarted.
rebuildparity [-f] plex
Rebuild the parity blocks of a RAID-5 plex. The parity rebuild
will start at the beginning of the plex if the -f flag is
specified, or otherwise at the location of the parity check
pointer. All subdisks in the plex must be up for a parity check.
resetconfig [-f]
Reset the complete gvinum configuration.
rm [-r] volume | plex | subdisk
Remove an object and, if -r is specified, its subordinate
objects.
saveconfig
Save gvinum configuration to disk after configuration failures.
setstate [-f] state volume | plex | subdisk | drive
Set state without influencing other objects, for diagnostic
purposes only. The -f flag forces state changes regardless of
whether they are legal.
start Read configuration from all vinum drives.
start [-S size] volume | plex | subdisk
Allow the system to access the objects. If necessary, plexes
will be synced and rebuilt. If a subdisk was added to a running
RAID-5 or striped plex, gvinum will expand into this subdisk and
grow the whole RAID-5 array. This can be done without unmounting
your filesystem. The -S flag is currently ignored.
stop [-f] [volume | plex | subdisk]
Terminate access to the objects, or stop gvinum if no parameters
are specified.
stripe [-fv] [-n name] drives
Create a striped volume from the specified drives. If no name is
specified, a unique name will be set by gvinum. This
organization requires at least two drives.
DESCRIPTION
The gvinum utility communicates with the kernel component of the GVinum
logical volume manager. It is designed either for interactive use, when
started without command line arguments, or to execute a single command if
the command is supplied on the command line. In interactive mode, gvinum
maintains a command line history.
OPTIONS
The gvinum commands may be followed by an option.
-f The -f ("force") option overrides safety checks. It should be
used with extreme caution. This option is required in order to
use the move command.
-r The -r ("recursive") option applies the command recursively to
subordinate objects. For example, in conjunction with the lv
command, the -r option will also show information about the
plexes and subdisks belonging to the volume. It is also used by
the rename command to indicate that subordinate objects such as
subdisks should be renamed to match the object(s) specified and
by the rm command to delete plexes belonging to a volume and so
on.
-v The -v ("verbose") option provides more detailed output.
-V The -V ("very verbose") option provides even more detailed output
than -v.
ENVIRONMENT
EDITOR The name of the editor to use for editing configuration
files, by default vi(1) is invoked.
FILES
/dev/gvinum directory with device nodes for gvinum objects
EXAMPLES
To create a mirror on disks /dev/ada1 and /dev/ada2, create a filesystem,
mount, unmount and then stop gvinum:
gvinum mirror /dev/ada1 /dev/ada2
newfs /dev/gvinum/gvinumvolume0
mount /dev/gvinum/gvinumvolume0 /mnt
...
unmount /mnt
gvinum stop
To create a striped mirror on disks /dev/ada1 /dev/ada2 /dev/ada3 and
/dev/ada4 named "data" and create a filesystem:
gvinum mirror -s -n data /dev/ada1 /dev/ada2 /dev/ada3 /dev/ada4
newfs /dev/gvinum/data
To create a raid5 array on disks /dev/ada1 /dev/ada2 and /dev/ada3, with
stripesize 493k you can use the raid5 command:
gvinum raid5 -s 493k /dev/ada1 /dev/ada2 /dev/ada3
Then the volume will be created automatically. Afterwards, you have to
initialize the volume:
gvinum start myraid5vol
The initialization will start, and the states will be updated when it's
finished. The list command will give you information about its progress.
Imagine that one of the drives fails, and the output of 'printconfig'
looks something like this:
drive gvinumdrive1 device /dev/ada2
drive gvinumdrive2 device /dev/???
drive gvinumdrive0 device /dev/ada1
volume myraid5vol
plex name myraid5vol.p0 org raid5 986s vol myraid5vol
sd name myraid5vol.p0.s2 drive gvinumdrive2 len 32538s driveoffset
265s
plex myraid5vol.p0 plexoffset 1972s
sd name myraid5vol.p0.s1 drive gvinumdrive1 len 32538s driveoffset
265s
plex myraid5vol.p0 plexoffset 986s
sd name myraid5vol.p0.s0 drive gvinumdrive0 len 32538s driveoffset
265s
plex myraid5vol.p0 plexoffset 0s
Create a new drive with this configuration:
drive gdrive4 device /dev/ada4
Then move the stale subdisk to the new drive:
gvinum move gdrive4 myraid5vol.p0.s2
Then, initiate the rebuild:
gvinum start myraid5vol.p0
The plex will go up form degraded mode after the rebuild is finished.
The plex can still be used while the rebuild is in progress, although
requests might be delayed.
Given the configuration as in the previous example, growing a RAID-5 or
STRIPED array is accomplished by using the grow command:
gvinum grow myraid5vol.p0 /dev/ada4
If everything went ok, the plex state should now be set to growable. You
can then start the growing with the start command:
gvinum start myraid5vol.p0
As with rebuilding, you can watch the progress using the list command.
For a more advanced usage and detailed explanation of gvinum, the
handbook is recommended.
SEE ALSO
geom(4), geom(8)
HISTORY
The gvinum utility first appeared in FreeBSD 5.3. The vinum utility, on
which gvinum is based, was written by Greg Lehey.
The gvinum utility was written by Lukas Ertl. The move and rename
commands and documentation were added by Chris Jones through the 2005
Google Summer of Code program. A partial rewrite of gvinum was done by
Lukas Ertl and Ulf Lilleengen through the 2007 Google Summer of Code
program. The documentation have been updated to reflect the new
functionality.
AUTHORS
Lukas Ertl <le@FreeBSD.org>
Chris Jones <soc-cjones@FreeBSD.org>
Ulf Lilleengen <lulf@FreeBSD.org>
BUGS
Currently, gvinum does not rename devices in /dev/gvinum until reloaded.
The -S initsize flag to start is ignored.
Moving subdisks that are not part of a mirrored or RAID-5 volume will
destroy data. It is perhaps a bug to permit this.
Plexes in which subdisks have been moved do not automatically sync or
rebuild parity. This may leave data unprotected and is perhaps unwise.
Currently, gvinum does not yet fully implement all of the functions found
in vinum. Specifically, the following commands from vinum are not
supported:
debug Cause the volume manager to enter the kernel debugger.
debug flags
Set debugging flags.
dumpconfig [drive ...]
List the configuration information stored on the specified
drives, or all drives in the system if no drive names are
specified.
info [-vV]
List information about volume manager state.
label volume
Create a volume label.
resetstats [-r] [volume | plex | subdisk]
Reset statistics counters for the specified objects, or for all
objects if none are specified.
setdaemon [value]
Set daemon configuration.
FreeBSD 13.1-RELEASE-p6 March 28, 2021 FreeBSD 13.1-RELEASE-p6
man2web Home...