Finally bring in what was produced during Google SoC 2005:

Add functions to rename objects and to move a subdisk from one drive
to another.

Add manual page (finally).

Bring up-to-date the online help.

Obtained from:  Chris Jones <chris.jones@ualberta.ca>
Sponsored by:   Google Summer of Code 2005
MFC in:         1 week

1 files changed, 397 insertions, 0 deletions

diff --git a/sbin/gvinum/gvinum.8 b/sbin/gvinum/gvinum.8
new file mode 100644
index 000000000000..217751cdc69d
--- /dev/null
+++ b/sbin/gvinum/gvinum.8
@@ -0,0 +1,397 @@
+.\"  Copyright (c) 2005 Chris Jones
+.\"  All rights reserved.
+.\" 
+.\" This software was developed for the FreeBSD Project by Chris Jones
+.\" thanks to the support of Google's Summer of Code program and
+.\" mentoring by Lukas Ertl.
+.\" 
+.\" Redistribution and use in source and binary forms, with or without       
+.\" modification, are permitted provided that the following conditions    
+.\" are met:    
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\" 
+.\" $FreeBSD$
+.\"
+.Dd September 1, 2005
+.Dt GVINUM 8
+.Os
+.Sh NAME
+.Nm gvinum
+.Nd Logical Volume Manager control program
+.Sh SYNOPSIS
+.Nm
+.Op Ar command
+.Op Fl options
+.Sh COMMANDS
+.Bl -tag -width indent
+.It Xo
+.Ic checkparity
+.Op Fl f
+.Ar plex
+.Xc 
+Check the parity blocks of a RAID-5 plex.  The parity check will start at the
+beginning of the plex if the 
+.Fl 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.
+.It Xo
+.Ic create
+.Op Ar description-file
+.Xc
+Create a volume as described in
+.Ar description-file .
+If no
+.Ar description-file 
+provided, opens an editor and provides the current 
+.Nm
+configuration for editing.
+.It Xo
+.Ic help
+.Xc
+Provides a synopsis of 
+.Nm 
+commands and arguments.
+.It Xo
+.Ic l | list
+.Op Fl r
+.Op Fl v
+.Op Fl V
+.Op Ar volume | plex | subdisk
+.Xc
+.It Xo
+.Ic ld
+.Op Fl r
+.Op Fl v
+.Op Fl V
+.Op Ar drive ...
+.Xc
+.It Xo
+.Ic ls
+.Op Fl r
+.Op Fl v
+.Op Fl V
+.Op Ar subdisk ...
+.Xc
+.It Xo
+.Ic lp
+.Op Fl r
+.Op Fl v
+.Op Fl V
+.Op Ar plex ...
+.Xc
+.It Xo
+.Ic lv
+.Op Fl r
+.Op Fl v
+.Op Fl V
+.Op Ar volume ...
+.Xc
+List information about the relevant object(s).  The
+.Fl r
+flag provides recursive display, showing each object's subordinate objects in
+proper relation.  The 
+.Fl v
+and 
+.Fl V
+flags provide progressively more detailed output.
+.It Xo
+.Ic move | mv
+.Fl f
+.Ar drive subdisk 
+.Op Ar ...
+.Xc
+Move the subdisk(s) to the specified drive.  The 
+.Fl 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.
+.Pp
+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 
+.Ic 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.
+.It Xo
+.Ic printconfig
+.Xc
+Write a copy of the current configuration to standard output.
+.It Xo
+.Ic quit
+.Xc
+Exit 
+.Nm
+when running in interactive mode.  Normally this would be done by entering the
+EOF character.
+.It Xo
+.Ic rename
+.Op Fl r
+.Ar drive | subdisk | plex | volume
+.Ar newname
+.Xc
+Change the name of the specified object.  The 
+.Fl r
+flag will recursively rename subordinate objects.
+.Pp
+Note that device nodes will not be renamed until 
+.Nm
+is restarted.
+.It Xo
+.Ic rebuildparity
+.Op Fl f
+.Ar plex
+.Xc
+Rebuild the parity blocks of a RAID-5 plex.  The parity rebuild will start at
+the beginning of the plex if the 
+.Fl 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.
+.It Xo
+.Ic rm
+.Op Fl r
+.Ar volume | plex | subdisk
+.Xc
+Remove an object and, if 
+.Fl r
+is specified, its subordinate objects.
+.It Xo
+.Ic saveconfig
+.Xc
+Save 
+.Nm
+configuration to disk after configuration failures.
+.It Xo
+.Ic setstate
+.Op Fl f
+.Ar state
+.Ar volume | plex | subdisk | drive
+.Xc
+Set state without influencing other objects, for diagnostic purposes 
+only.  The 
+.Fl f
+flag forces state changes regardless of whether they are legal.
+.It Xo
+.Ic start
+.Xc 
+Read configuration from all vinum drives.
+.It Xo
+.Ic start
+.Op Fl S Ar size
+.Ar volume | plex | subdisk
+.Xc
+Allow the system to access the objects.  The
+.Fl S
+flag is currently ignored.
+.El
+.Sh DESCRIPTION
+The
+.Nm
+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, 
+.Nm
+maintains a command line history.
+.Sh OPTIONS
+.Nm
+commands may be followed by an option.
+.Bl -tag -width indent
+.It Fl f
+The
+.Fl f
+.Pq Dq force
+option overrides safety checks.  It should be used with extreme caution.  This
+option is required in order to use the 
+.Ic move
+command.
+.It Fl r
+The 
+.Fl r
+.Pq Dq recursive
+option applies the command recursively to subordinate objects.  For example, in
+conjunction with the
+.Ic lv
+command, the 
+.Fl r
+option will also show information about the plexes and subdisks belonging to
+the volume.  It is also used by the 
+.Ic rename
+command to indicate that subordinate objects such as subdisks should be renamed
+to match the object(s) specified and by the 
+.Ic rm
+command to delete plexes belonging to a volume and so on.
+.It Fl v
+The
+.Fl v
+.Pq Dq verbose
+option provides more detailed output.
+.It Fl V
+The
+.Fl V
+.Pq Dq very verbose
+option provides even more detailed output than
+.Fl v .
+.El
+.Sh FILES
+.Bl -tag -width /dev/gvinum/plex
+.It Pa /dev/gvinum
+directory with device nodes for
+.Nm
+objects
+.It Pa /dev/gvinum/plex
+directory containing device nodes for
+.Nm
+plexes
+.It Pa /dev/gvinum/sd
+directory containing device nodes for
+.Nm
+subdisks
+.El
+.Sh ENVIRONMENT
+.Bl -tag -width EDITOR
+.It Ev EDITOR
+The name of the editor to use for editing configuration files, by 
+default
+.Nm vi .
+.El
+.Sh SEE ALSO
+.Xr geom 4 ,
+.Xr geom 8
+.Pp
+.Sh AUTHORS
+.An Lukas Ertl Aq le@freebsd.org
+.An Chris Jones Aq soc-cjones@freebsd.org
+.Sh HISTORY
+The
+.Nm
+utility first appeared in 
+.Fx 5.3 .  The 
+.Nm vinum 
+utility, on which
+.Nm 
+is based, was written by Greg Lehey.
+.Pp
+.Nm 
+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.
+.Sh BUGS
+.Xr gvinum 8 does not rename devices in
+.Pa /dev/gvinum 
+until reloaded.
+.Pp
+The 
+.Fl S
+initsize flag to 
+.Ic start
+is ignored.
+.Pp
+The 
+.Ic stop
+command does not work.
+.Pp
+Moving subdisks that are not part of a mirrored or RAID-5 volume will 
+destroy data.  It is perhaps a bug to permit this.  
+.Pp
+Plexes in which subdisks have been moved do not automatically sync or 
+rebuild parity.  This may leave data unprotected and is perhaps unwise.
+.Pp
+.Xr gvinum 8 does not yet fully implement all functions found in  
+.Xr vinum 4 .  Specifically, the following commands from 
+.Xr vinum 4 are not supported:
+.Bl -tag -width indent
+.It Ic attach Ar plex volume Op Cm rename
+.It Xo
+.Ic attach Ar subdisk plex
+.Op Ar offset
+.Op Cm rename
+.Xc
+Attach a plex to a volume, or a subdisk to a plex.
+.It Xo
+.Ic concat
+.Op Fl f
+.Op Fl n Ar name
+.Op Fl v
+.Ar drives
+.Xc
+Create a concatenated volume from the specified drives.
+.It Ic debug
+Cause the volume manager to enter the kernel debugger.
+.It Ic debug Ar flags
+Set debugging flags.
+.It Xo
+.Ic detach
+.Op Fl f
+.Op Ar plex | subdisk
+.Xc
+Detach a plex or subdisk from the volume or plex to which it is 
+attached.
+.It Ic dumpconfig Op Ar drive ...
+List the configuration information stored on the specified drives, or all
+drives in the system if no drive names are specified.
+.It Xo
+.Ic info
+.Op Fl v
+.Op Fl V
+.Xc
+List information about volume manager state.
+.It Ic label Ar volume
+Create a volume label.
+.It Xo
+.Ic mirror
+.Op Fl f
+.Op Fl n Ar name
+.Op Fl s
+.Op Fl v
+.Ar drives
+.Xc
+Create a mirrored volume from the specified drives.
+.It Ic resetconfig
+Reset the complete
+.Nm
+configuration.
+.It Xo
+.Ic resetstats
+.Op Fl r
+.Op Ar volume | plex | subdisk
+.Xc
+Reset statistics counters for the specified objects, or for all objects if none
+are specified.
+.It Ic setdaemon Op Ar value
+Set daemon configuration.
+.It Xo
+.Ic stop
+.Op Fl f
+.Op Ar volume | plex | subdisk
+.Xc
+Terminate access to the objects, or stop
+.Nm
+if no parameters are specified.
+.It Xo
+.Ic stripe
+.Op Fl f
+.Op Fl n Ar name
+.Op Fl v
+.Ar drives
+.Xc
+Create a striped volume from the specified drives.
+.El