From owner-svn-doc-head@FreeBSD.ORG Mon Feb 11 21:04:43 2013 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.FreeBSD.org [8.8.178.115]) by hub.freebsd.org (Postfix) with ESMTP id 66BC840F; Mon, 11 Feb 2013 21:04:43 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (wonkity.com [67.158.26.137]) by mx1.freebsd.org (Postfix) with ESMTP id 0782CE06; Mon, 11 Feb 2013 21:04:42 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.6/8.14.6) with ESMTP id r1BL4g1b028673; Mon, 11 Feb 2013 14:04:42 -0700 (MST) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.6/8.14.6/Submit) with ESMTP id r1BL4g6N028670; Mon, 11 Feb 2013 14:04:42 -0700 (MST) (envelope-from wblock@wonkity.com) Date: Mon, 11 Feb 2013 14:04:42 -0700 (MST) From: Warren Block To: Dru Lavigne Subject: Re: svn commit: r40946 - head/en_US.ISO8859-1/books/handbook/geom In-Reply-To: <201302111450.r1BEoXIR033682@svn.freebsd.org> Message-ID: References: <201302111450.r1BEoXIR033682@svn.freebsd.org> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.2.7 (wonkity.com [127.0.0.1]); Mon, 11 Feb 2013 14:04:42 -0700 (MST) Cc: svn-doc-head@freebsd.org, svn-doc-all@freebsd.org, doc-committers@freebsd.org X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 11 Feb 2013 21:04:43 -0000 On Mon, 11 Feb 2013, Dru Lavigne wrote: > Author: dru > Date: Mon Feb 11 14:50:33 2013 > New Revision: 40946 > URL: http://svnweb.freebsd.org/changeset/doc/40946 > > Log: > This patch addresses the following: > > - fixes xref tags > > - some tightening and removing of redundancy > > - fixed some confusion in glabel section > > Approved by gjb (mentor) > > Modified: > head/en_US.ISO8859-1/books/handbook/geom/chapter.xml ... Uh oh. Heading for the mirror section, which I and HRS revised recently and is still seared into my memory. Comments inline. > &prompt.root; echo "/dev/stripe/st0a /stripe ufs rw 2 2" \ > @@ -249,8 +248,8 @@ Done. > replace the failed drive without user interruption. > > Two common situations are illustrated in these examples. > - The first is creating a mirror out of two new drives and using > - it as a replacement for an existing single drive. The second > + The first creates a mirror out of two new drives and uses it > + as a replacement for an existing single drive. The second > example creates a mirror on a single new drive, copies the old > drive's data to it, then inserts the old drive into the > mirror. While this procedure is slightly more complicated, it > @@ -317,28 +316,28 @@ Done. > used to replace the old single disk. > > &man.gmirror.8; requires a kernel module, > - geom_mirror.ko, either built into the > - kernel or loaded at boot- or run-time. Manually load the > - kernel module now: > + geom_mirror.ko, either compiled into a > + custom kernel or loaded at boot- or run-time. To manually > + load the kernel module now: That last sentence was right the previous way. It's not "how to do it", it's "do this because the following instructions require it." > &prompt.root; gmirror load > > - Create the mirror with the two new drives. > + To create the mirror with the two new drives. As above, this is (was) an imperative. "Do this, or feel the sting of utter failure!" > &prompt.root; gmirror label -v gm0 /dev/ada1 /dev/ada2 > > gm0 is a user-chosen device name > assigned to the new mirror. After the mirror has been > - started, this device name will appear in the > - /dev/mirror/ directory. > + started, this device name will appear in > + /dev/mirror/. > MBR and bsdlabel partition tables can now be created on > the mirror with &man.gpart.8;. Here we show a traditional > split-filesystem layout, with partitions for > /, swap, /var, > /tmp, and /usr. A > - single / filesystem and a swap partition > - will also work. > + single / and a swap partition will also > + work. Without the "filesystem" word, it is not as clear what the / refers to; it could be read as a literal slash, or a directory, or a file. > Partitions on the mirror do not have to be the same size > as those on the existing disk, but they must be large enough > @@ -384,8 +383,8 @@ Done. > &prompt.root; newfs -U /dev/mirror/gm0s1e > &prompt.root; newfs -U /dev/mirror/gm0s1f > > - Filesystems from the original disk > - (ada0) can now be copied onto the > + Filesystems from the original > + ada0 disk can now be copied onto the > mirror with &man.dump.8; and &man.restore.8;. > > &prompt.root; mount /dev/mirror/gm0s1a /mnt > @@ -419,8 +418,8 @@ Done. > are identical, it does not matter which is selected to > boot. > > - See the > - Troubleshooting > + See the + linkend="gmirror-troubleshooting">Troubleshooting > section if there are problems booting. Powering down and > disconnecting the original ada0 disk > will allow it to be kept as an offline backup. > @@ -432,23 +431,23 @@ Done. > > Creating a Mirror with an Existing Drive > > - In this example, &os; has already been installed on a > - single disk, ada0. A new disk, > + In this example, &os; has been installed on a single > + disk, ada0. A new disk, Why remove the "already"? That's part of what this example is trying to explain, how to create a mirror when FreeBSD is already on one of two drives. > ada1, has been connected to the > system. A one-disk mirror will be created on the new disk, > - the existing system copied onto it, and then the old disk will be > - inserted into the mirror. This slightly complex procedure is > - required because &man.gmirror.8; needs to put a 512-byte block > - of metadata at the end of each disk, and the existing > - ada0 has usually had all of its space > + the existing system copied onto it, and then the old disk will > + be inserted into the mirror. This slightly complex procedure > + is required because &man.gmirror.8; needs to put a 512-byte > + block of metadata at the end of each disk, and the existing > + ada0 usually has all of its space > already allocated. I think "has usually had all of of its space already allocated" is the correct tense. > - Load the &man.gmirror.8; kernel module. > + Load the &man.gmirror.8; kernel module: It's not required that everything that is about to show an example lead up to it with a colon. It makes for staccato reading, but people seem to like that, so okay. > &prompt.root; gmirror load > > Check the media size of the original disk with > - &man.diskinfo.8;. > + &man.diskinfo.8;: > > &prompt.root; diskinfo -v ada0 | head -n3 > /dev/ada0 > @@ -461,11 +460,11 @@ Done. > size. This drive does not store any data, but is used only to > limit the size of the mirror. When &man.gmirror.8; creates > the mirror, it will restrict the capacity to the size of > - gzero.nop even if the new drive > + gzero.nop, even if the new drive > (ada1) has more space. Note that the > 1000204821504 in the second line > - should be equal to ada0's media size > - as shown by &man.diskinfo.8; above. > + should be equal to the size of ada0 > + as shown by &man.diskinfo.8;. "media size" is (was) mentioned to help the user find the right value in diskinfo(8) output. > &prompt.root; geom zero load > &prompt.root; gnop create -s 1000204821504 gzero > @@ -502,7 +501,7 @@ Done. > be explained later. > > In either case, partition tables on the primary disk > - should be copied first. It can be done by using &man.gpart.8; > + should be copied first using the &man.gpart.8; > backup and restore > subcommands. Okay. But I suggest s/using/with/. > @@ -527,8 +526,8 @@ BSD 8 > 6 freebsd-ufs 130023424 838860800 > 7 freebsd-ufs 968884224 984640881 > > - If the whole disk was used in the output of &man.gpart.8; > - show, the capacity in these partition > + If the whole disk shows as used in the output of > + gpart show, the capacity in these partition > tables must be reduced by one sector. Edit the two files, > reducing the size of both the slice and last partition by one. > These are the last numbers in each listing. > @@ -550,13 +549,13 @@ BSD 8 > disk, these two files can be used without modification. Suggestion for specifics: "If the output of gpart show shows no free space at the end of the disk, the size of both the slice and the last partition must be reduced by one sector." > Now restore the partition table into > - mirror/gm0. > + mirror/gm0: > > &prompt.root; gpart restore mirror/gm0 < table.ada0 > &prompt.root; gpart restore mirror/gm0s1 < table.ada0s1 > > - Check the partition table with the &man.gpart.8; > - show. This example has > + Check the partition table with > + gpart show. This example has > gm0s1a for /, > gm0s1d for /var, > gm0s1e for /usr, > @@ -707,8 +706,7 @@ mirror/gm0 COMPLETE ada1 (ACTIVE) > > BIOS settings may have to be changed to boot from one > of the new mirrored drives. Either mirror drive can be > - used for booting. As components of a mirror, they contain > - identical data. > + used for booting as they contain identical data. > Needs a comma after "booting", I think. > > @@ -742,10 +740,10 @@ mountroot> > Forgetting to load the > geom_mirror module in > /boot/loader.conf can cause this > - problem. To fix it, boot from a &os;-9 or later CD or USB > - stick and choose Shell at the first > - prompt. Then load the mirror module and mount the mirror > - device: > + problem. To fix it, boot from a &os; 9.0 or later > + installation media and choose Shell at > + the first prompt. Then load the mirror module and mount > + the mirror device: > > &prompt.root; gmirror load > &prompt.root; mount /dev/mirror/gm0s1a /mnt > @@ -759,14 +757,14 @@ mountroot> > > Other problems that cause error 19 > require more effort to fix. Enter > - ufs:/dev/ada0s1a at the prompt. > - Although the system should boot from > + ufs:/dev/ada0s1a at the boot loader > + prompt. Although the system should boot from > ada0, another prompt to select a > shell appears because /etc/fstab is > incorrect. Press the Enter key at the prompt. Undo the > modifications so far by reverting > /etc/fstab, mounting filesystems from > - the original disk (ada0) instead > + the original ada0 instead > of the mirror. Reboot the system and try the procedure > again. ada0 is (was) mentioned parenthetically because it was the example, not necessarily what the user will have.