From owner-p4-projects@FreeBSD.ORG Mon Aug 29 09:13:19 2005 Return-Path: X-Original-To: p4-projects@freebsd.org Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id B30C216A428; Mon, 29 Aug 2005 09:13:18 +0000 (GMT) X-Original-To: perforce@freebsd.org Delivered-To: perforce@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 6BC2E16A41F for ; Mon, 29 Aug 2005 09:13:18 +0000 (GMT) (envelope-from soc-cjones@freebsd.org) Received: from repoman.freebsd.org (repoman.freebsd.org [216.136.204.115]) by mx1.FreeBSD.org (Postfix) with ESMTP id D4A3E43D58 for ; Mon, 29 Aug 2005 09:13:17 +0000 (GMT) (envelope-from soc-cjones@freebsd.org) Received: from repoman.freebsd.org (localhost [127.0.0.1]) by repoman.freebsd.org (8.13.1/8.13.1) with ESMTP id j7T9DH0t031911 for ; Mon, 29 Aug 2005 09:13:17 GMT (envelope-from soc-cjones@freebsd.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.13.1/8.13.1/Submit) id j7T9DHNw031908 for perforce@freebsd.org; Mon, 29 Aug 2005 09:13:17 GMT (envelope-from soc-cjones@freebsd.org) Date: Mon, 29 Aug 2005 09:13:17 GMT Message-Id: <200508290913.j7T9DHNw031908@repoman.freebsd.org> X-Authentication-Warning: repoman.freebsd.org: perforce set sender to soc-cjones@freebsd.org using -f From: soc-cjones To: Perforce Change Reviews Cc: Subject: PERFORCE change 82746 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 29 Aug 2005 09:13:19 -0000 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