Date: Mon, 29 Aug 2005 09:13:17 GMT From: soc-cjones <soc-cjones@FreeBSD.org> To: Perforce Change Reviews <perforce@freebsd.org> Subject: PERFORCE change 82746 for review Message-ID: <200508290913.j7T9DHNw031908@repoman.freebsd.org>
next in thread | raw e-mail | index | archive | help
http://perforce.freebsd.org/chv.cgi?CH=82746 Change 82746 by soc-cjones@soc-cjones_ishtar on 2005/08/29 09:12:16 Sync man page's view of arguments with reality, and describe commands. Affected files ... .. //depot/projects/soc2005/gvinum/src/sbin/gvinum/gvinum.8#5 edit Differences ... ==== //depot/projects/soc2005/gvinum/src/sbin/gvinum/gvinum.8#5 (text+ko) ==== @@ -41,55 +41,95 @@ .It Xo .Ic checkparity .Op Fl f -.Op Fl v .Ar plex .Xc -Check the parity blocks of a RAID-5 plex. +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 Fl f -.Ar description-file +.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 -List information about specified objects. .It Xo .Ic ld -.Op Ar drive +.Op Fl r +.Op Fl v +.Op Fl V +.Op Ar drive ... .Xc -List information about drive(s). .It Xo .Ic ls -.Op Ar subdisk +.Op Fl r +.Op Fl v +.Op Fl V +.Op Ar subdisk ... .Xc -List information about subdisk(s). .It Xo .Ic lp -.Op Ar plex +.Op Fl r +.Op Fl v +.Op Fl V +.Op Ar plex ... .Xc -List information about plex(es). .It Xo .Ic lv -.Op Ar volume +.Op Fl r +.Op Fl v +.Op Fl V +.Op Ar volume ... .Xc -List information about volume(s). +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 mv .Fl f -.Ar drive subdisk ... +.Ar drive subdisk +.Op Ar ... .Xc -Move the subdisk(s) to the specified drive. +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. +.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 -.Op Ar file .Xc -Write a copy of the current configuration to standard output or to -.Ar file -if specified. +Write a copy of the current configuration to standard output. .It Xo .Ic quit .Xc @@ -103,19 +143,31 @@ .Ar drive | subdisk | plex | volume .Ar newname .Xc -Change the name of the specified object. +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. +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 f .Op Fl r .Ar volume | plex | subdisk .Xc -Remove an object. +Remove an object and, if +.Fl r +is specified, its subordinate objects. .It Xo .Ic saveconfig .Xc @@ -124,11 +176,14 @@ 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. +only. The +.Fl f +flag forces state changes regardless of whether they are legal. .It Xo .Ic start .Xc @@ -153,7 +208,40 @@ .Sh OPTIONS .Nm commands may be followed by an option. -TODO +.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 @@ -204,7 +292,10 @@ until reloaded. .Pp Moving subdisks that are not part of a mirrored or RAID-5 volume will -destroy data. +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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200508290913.j7T9DHNw031908>