gvinum(8)

NAME

gvinum - Logical Volume Manager control program

SYNOPSIS

gvinum [command] [-options]

COMMANDS

checkparity [-f] plex

Check the parity blocks of a RAID-5 plex. The pari

ty 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.

create [description-file]

Create a volume as described in description-file.

If no
description-file provided, opens an editor and pro

vides the current gvinum configuration for editing.

help Provides a synopsis of gvinum commands and argu

ments.

l | list [-r] [-v] [-V] [volume | plex | subdisk]

ld [-r] [-v] [-V] [drive ...]

ls [-r] [-v] [-V] [subdisk ...]

lp [-r] [-v] [-V] [plex ...]

lv [-r] [-v] [-V] [volume ...]

List information about the relevant object(s). The

-r flag provides recursive display, showing each object's sub

ordinate
objects in proper relation. The -v and -V flags

provide progressively more detailed output.

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 the subdisk(s) form part of a RAID-5 plex, the

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 mir

rored 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 stan

dard output.

quit Exit gvinum when running in interactive mode. Nor

mally this

would be done by entering the EOF character.

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.

rm [-r] volume | plex | subdisk

Remove an object and, if -r is specified, its subor

dinate
objects.

saveconfig

Save gvinum configuration to disk after configura

tion failures.

setstate [-f] state volume | plex | subdisk | drive

Set state without influencing other objects, for di

agnostic purposes only. The -f flag forces state changes re

gardless 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. The -S flag

is currently
ignored.

DESCRIPTION

The gvinum utility communicates with the kernel component of

the GVinum
logical volume manager. It is designed either for interac

tive use, when
started without command line arguments, or to execute a sin

gle command if
the command is supplied on the command line. In interactive

mode, gvinum
maintains a command line history.

OPTIONS

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 ob

jects 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 out

put than -v.

FILES

/dev/gvinum directory with device nodes for gvinum ob

jects

/dev/gvinum/plex directory containing device nodes for

gvinum plexes

/dev/gvinum/sd directory containing device nodes for

gvinum subdisks

ENVIRONMENT

EDITOR The name of the editor to use for editing configura

tion files, by

default vi.

SEE ALSO

geom(4), geom(8)

AUTHORS

Lukas Ertl <le@freebsd.org>
Chris Jones <soc-cjones@freebsd.org>

HISTORY

The gvinum utility first appeared in FreeBSD 5.3. The vinum

utility, on
which gvinum is based, was written by Greg Lehey.

gvinum was written by Lukas Ertl. The move and rename com

mands and documentation were added by Chris Jones through the 2005 Google

Summer of
Code program.

BUGS

gvinum(8) does not rename devices in /dev/gvinum until

reloaded.

The -S initsize flag to start is ignored.

The stop command does not work.

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 automatical

ly sync or
rebuild parity. This may leave data unprotected and is per

haps unwise.

gvinum(8) does not yet fully implement all functions found

in vinum(4).
Specifically, the following commands from vinum(4) are not

supported:

attach plex volume [rename]

attach subdisk plex [offset] [rename]

Attach a plex to a volume, or a subdisk to a plex.

concat [-f] [-n name] [-v] drives

Create a concatenated volume from the specified

drives.

debug Cause the volume manager to enter the kernel debug

ger.

debug flags

Set debugging flags.

detach [-f] [plex | subdisk]

Detach a plex or subdisk from the volume or plex to

which it is
attached.

dumpconfig [drive ...]

List the configuration information stored on the

specified
drives, or all drives in the system if no drive

names are specified.

info [-v] [-V]

List information about volume manager state.

label volume

Create a volume label.

mirror [-f] [-n name] [-s] [-v] drives

Create a mirrored volume from the specified drives.

resetconfig

Reset the complete gvinum configuration.

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.

stop [-f] [volume | plex | subdisk]

Terminate access to the objects, or stop gvinum if

no parameters
are specified.

stripe [-f] [-n name] [-v] drives

Create a striped volume from the specified drives.

BSD September 1, 2005

BSD