diff options
author | le <le@FreeBSD.org> | 2005-11-19 20:26:52 +0000 |
---|---|---|
committer | le <le@FreeBSD.org> | 2005-11-19 20:26:52 +0000 |
commit | dccc51c176b8baa3d71d771994c7821642c186cf (patch) | |
tree | 48190ff825de1077283cf7062f9017307ed646f6 /sbin | |
parent | 7f74b7e0865d73a2acccc73cf72fb4f34ab54934 (diff) | |
download | FreeBSD-src-dccc51c176b8baa3d71d771994c7821642c186cf.zip FreeBSD-src-dccc51c176b8baa3d71d771994c7821642c186cf.tar.gz |
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
Diffstat (limited to 'sbin')
-rw-r--r-- | sbin/gvinum/Makefile | 2 | ||||
-rw-r--r-- | sbin/gvinum/gvinum.8 | 397 | ||||
-rw-r--r-- | sbin/gvinum/gvinum.c | 185 |
3 files changed, 533 insertions, 51 deletions
diff --git a/sbin/gvinum/Makefile b/sbin/gvinum/Makefile index 2e9b7c5..6d41497 100644 --- a/sbin/gvinum/Makefile +++ b/sbin/gvinum/Makefile @@ -2,7 +2,7 @@ PROG= gvinum SRCS= gvinum.c gvinum.h geom_vinum_share.c -NO_MAN= # not yet +MAN= gvinum.8 CFLAGS+= -I${.CURDIR}/../../sys diff --git a/sbin/gvinum/gvinum.8 b/sbin/gvinum/gvinum.8 new file mode 100644 index 0000000..217751c --- /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 diff --git a/sbin/gvinum/gvinum.c b/sbin/gvinum/gvinum.c index 9e2f7b6..87b7003 100644 --- a/sbin/gvinum/gvinum.c +++ b/sbin/gvinum/gvinum.c @@ -1,7 +1,11 @@ /* - * Copyright (c) 2004 Lukas Ertl + * Copyright (c) 2004 Lukas Ertl, 2005 Chris Jones * All rights reserved. * + * Portions of this software were 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: @@ -53,8 +57,10 @@ void gvinum_create(int, char **); void gvinum_help(void); void gvinum_list(int, char **); +void gvinum_move(int, char **); void gvinum_parityop(int, char **, int); void gvinum_printconfig(int, char **); +void gvinum_rename(int, char **); void gvinum_rm(int, char **); void gvinum_saveconfig(void); void gvinum_setstate(int, char **); @@ -320,75 +326,40 @@ void gvinum_help(void) { printf("COMMANDS\n" - "attach plex volume [rename]\n" - "attach subdisk plex [offset] [rename]\n" - " Attach a plex to a volume, or a subdisk to a plex.\n" - "checkparity plex [-f] [-v]\n" - " Check the parity blocks of a RAID-4 or RAID-5 plex.\n" - "concat [-f] [-n name] [-v] drives\n" - " Create a concatenated volume from the specified drives.\n" - "create [-f] description-file\n" - " Create a volume as described in description-file.\n" - "detach [-f] [plex | subdisk]\n" - " Detach a plex or subdisk from the volume or plex to" - "which it is\n" - " attached.\n" - "dumpconfig [drive ...]\n" - " List the configuration information stored on the" - " specified\n" - " drives, or all drives in the system if no drive names" - " are speci-\n" - " fied.\n" - "info [-v] [-V]\n" - " List information about volume manager state.\n" - "init [-S size] [-w] plex | subdisk\n" - " Initialize the contents of a subdisk or all the subdisks" - " of a\n" - " plex to all zeros.\n" - "label volume\n" - " Create a volume label.\n" - "l | list [-r] [-s] [-v] [-V] [volume | plex | subdisk]\n" + "checkparity [-f] plex\n" + " Check the parity blocks of a RAID-5 plex.\n" + "create description-file\n" + " Create as per description-file or open editor.\n" + "l | list [-r] [-v] [-V] [volume | plex | subdisk]\n" " List information about specified objects.\n" - "ld [-r] [-s] [-v] [-V] [volume]\n" + "ld [-r] [-v] [-V] [volume]\n" " List information about drives.\n" - "ls [-r] [-s] [-v] [-V] [subdisk]\n" + "ls [-r] [-v] [-V] [subdisk]\n" " List information about subdisks.\n" - "lp [-r] [-s] [-v] [-V] [plex]\n" + "lp [-r] [-v] [-V] [plex]\n" " List information about plexes.\n" - "lv [-r] [-s] [-v] [-V] [volume]\n" + "lv [-r] [-v] [-V] [volume]\n" " List information about volumes.\n" - "mirror [-f] [-n name] [-s] [-v] drives\n" - " Create a mirrored volume from the specified drives.\n" "move | mv -f drive object ...\n" " Move the object(s) to the specified drive.\n" - "printconfig [file]\n" - " Write a copy of the current configuration to file.\n" "quit Exit the vinum program when running in interactive mode." " Nor-\n" " mally this would be done by entering the EOF character.\n" "rename [-r] [drive | subdisk | plex | volume] newname\n" " Change the name of the specified object.\n" - "rebuildparity plex [-f] [-v] [-V]\n" - " Rebuild the parity blocks of a RAID-4 or RAID-5 plex.\n" - "resetconfig\n" - " Reset the complete vinum configuration.\n" - "rm [-f] [-r] volume | plex | subdisk\n" + "rebuildparity plex [-f]\n" + " Rebuild the parity blocks of a RAID-5 plex.\n" + "rm [-r] volume | plex | subdisk | drive\n" " Remove an object.\n" "saveconfig\n" " Save vinum configuration to disk after configuration" " failures.\n" - "setstate state [volume | plex | subdisk | drive]\n" + "setstate [-f] state [volume | plex | subdisk | drive]\n" " Set state without influencing other objects, for" " diagnostic pur-\n" " poses only.\n" - "start [-i interval] [-S size] [-w] volume | plex | subdisk\n" + "start [-S size] volume | plex | subdisk\n" " Allow the system to access the objects.\n" - "stop [-f] [volume | plex | subdisk]\n" - " Terminate access to the objects, or stop vinum if no" - " parameters\n" - " are specified.\n" - "stripe [-f] [-n name] [-v] drives\n" - " Create a striped volume from the specified drives.\n" ); return; @@ -514,6 +485,61 @@ gvinum_list(int argc, char **argv) return; } +/* Note that move is currently of form '[-r] target object [...]' */ +void +gvinum_move(int argc, char **argv) +{ + struct gctl_req *req; + const char *errstr; + char buf[20]; + int flags, i, j; + + flags = 0; + if (argc) { + optreset = 1; + optind = 1; + while ((j = getopt(argc, argv, "f")) != -1) { + switch (j) { + case 'f': + flags |= GV_FLAG_F; + break; + case '?': + default: + return; + } + } + argc -= optind; + argv += optind; + } + + switch (argc) { + case 0: + warnx("no destination or object(s) to move specified"); + return; + case 1: + warnx("no object(s) to move specified"); + return; + default: + break; + } + + req = gctl_get_handle(); + gctl_ro_param(req, "class", -1, "VINUM"); + gctl_ro_param(req, "verb", -1, "move"); + gctl_ro_param(req, "argc", sizeof(int), &argc); + gctl_ro_param(req, "flags", sizeof(int), &flags); + gctl_ro_param(req, "destination", -1, argv[0]); + for (i = 1; i < argc; i++) { + snprintf(buf, sizeof(buf), "argv%d", i); + gctl_ro_param(req, buf, -1, argv[i]); + } + errstr = gctl_issue(req); + if (errstr != NULL) + warnx("can't move object(s): %s", errstr); + gctl_free(req); + return; +} + void gvinum_printconfig(int argc, char **argv) { @@ -604,6 +630,59 @@ gvinum_parityop(int argc, char **argv, int rebuild) } void +gvinum_rename(int argc, char **argv) +{ + struct gctl_req *req; + const char *errstr; + int flags, j; + + flags = 0; + + if (argc) { + optreset = 1; + optind = 1; + while ((j = getopt(argc, argv, "r")) != -1) { + switch (j) { + case 'r': + flags |= GV_FLAG_R; + break; + case '?': + default: + return; + } + } + argc -= optind; + argv += optind; + } + + switch (argc) { + case 0: + warnx("no object to rename specified"); + return; + case 1: + warnx("no new name specified"); + return; + case 2: + break; + default: + warnx("more than one new name specified"); + return; + } + + req = gctl_get_handle(); + gctl_ro_param(req, "class", -1, "VINUM"); + gctl_ro_param(req, "verb", -1, "rename"); + gctl_ro_param(req, "flags", sizeof(int), &flags); + gctl_ro_param(req, "object", -1, argv[0]); + gctl_ro_param(req, "newname", -1, argv[1]); + errstr = gctl_issue(req); + if (errstr != NULL) + warnx("can't rename object: %s", errstr); + gctl_free(req); + return; +} + +void gvinum_rm(int argc, char **argv) { struct gctl_req *req; @@ -759,8 +838,14 @@ parseline(int argc, char **argv) gvinum_list(argc, argv); else if (!strcmp(argv[0], "lv")) gvinum_list(argc, argv); + else if (!strcmp(argv[0], "move")) + gvinum_move(argc, argv); + else if (!strcmp(argv[0], "mv")) + gvinum_move(argc, argv); else if (!strcmp(argv[0], "printconfig")) gvinum_printconfig(argc, argv); + else if (!strcmp(argv[0], "rename")) + gvinum_rename(argc, argv); else if (!strcmp(argv[0], "rm")) gvinum_rm(argc, argv); else if (!strcmp(argv[0], "saveconfig")) |