Date: Mon, 11 Feb 2013 14:04:42 -0700 (MST) From: Warren Block <wblock@wonkity.com> To: Dru Lavigne <dru@FreeBSD.org> Cc: svn-doc-head@freebsd.org, svn-doc-all@freebsd.org, doc-committers@freebsd.org Subject: Re: svn commit: r40946 - head/en_US.ISO8859-1/books/handbook/geom Message-ID: <alpine.BSF.2.00.1302111329300.28483@wonkity.com> In-Reply-To: <201302111450.r1BEoXIR033682@svn.freebsd.org> References: <201302111450.r1BEoXIR033682@svn.freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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; <userinput>echo "/dev/stripe/st0a /stripe ufs rw 2 2" \</userinput> > @@ -249,8 +248,8 @@ Done.</screen> > replace the failed drive without user interruption.</para> > > <para>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.</screen> > used to replace the old single disk.</para> > > <para>&man.gmirror.8; requires a kernel module, > - <filename>geom_mirror.ko</filename>, either built into the > - kernel or loaded at boot- or run-time. Manually load the > - kernel module now:</para> > + <filename>geom_mirror.ko</filename>, either compiled into a > + custom kernel or loaded at boot- or run-time. To manually > + load the kernel module now:</para> 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." > <screen>&prompt.root; <userinput>gmirror load</userinput></screen> > > - <para>Create the mirror with the two new drives.</para> > + <para>To create the mirror with the two new drives.</para> As above, this is (was) an imperative. "Do this, or feel the sting of utter failure!" > <screen>&prompt.root; <userinput>gmirror label -v gm0 /dev/ada1 /dev/ada2</userinput></screen> > > <para><devicename>gm0</devicename> is a user-chosen device name > assigned to the new mirror. After the mirror has been > - started, this device name will appear in the > - <filename>/dev/mirror/</filename> directory.</para> > + started, this device name will appear in > + <filename>/dev/mirror/</filename>.</para> > <para>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 > <filename>/</filename>, swap, <filename>/var</filename>, > <filename>/tmp</filename>, and <filename>/usr</filename>. A > - single <filename>/</filename> filesystem and a swap partition > - will also work.</para> > + single <filename>/</filename> and a swap partition will also > + work.</para> 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. > <para>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.</screen> > &prompt.root; <userinput>newfs -U /dev/mirror/gm0s1e</userinput> > &prompt.root; <userinput>newfs -U /dev/mirror/gm0s1f</userinput></screen> > > - <para>Filesystems from the original disk > - (<devicename>ada0</devicename>) can now be copied onto the > + <para>Filesystems from the original > + <devicename>ada0</devicename> disk can now be copied onto the > mirror with &man.dump.8; and &man.restore.8;.</para> > > <screen>&prompt.root; <userinput>mount /dev/mirror/gm0s1a /mnt</userinput> > @@ -419,8 +418,8 @@ Done.</screen> > are identical, it does not matter which is selected to > boot.</para> > > - <para>See the > - <link linkend="gmirror-troubleshooting">Troubleshooting</link> > + <para>See the <link > + linkend="gmirror-troubleshooting">Troubleshooting</link> > section if there are problems booting. Powering down and > disconnecting the original <devicename>ada0</devicename> disk > will allow it to be kept as an offline backup.</para> > @@ -432,23 +431,23 @@ Done.</screen> > <sect2> > <title>Creating a Mirror with an Existing Drive</title> > > - <para>In this example, &os; has already been installed on a > - single disk, <devicename>ada0</devicename>. A new disk, > + <para>In this example, &os; has been installed on a single > + disk, <devicename>ada0</devicename>. 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. > <devicename>ada1</devicename>, 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 > - <devicename>ada0</devicename> 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 > + <devicename>ada0</devicename> usually has all of its space > already allocated.</para> I think "has usually had all of of its space already allocated" is the correct tense. > - <para>Load the &man.gmirror.8; kernel module.</para> > + <para>Load the &man.gmirror.8; kernel module:</para> 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. > <screen>&prompt.root; <userinput>gmirror load</userinput></screen> > > <para>Check the media size of the original disk with > - &man.diskinfo.8;.</para> > + &man.diskinfo.8;:</para> > > <screen>&prompt.root; <userinput>diskinfo -v ada0 | head -n3</userinput> > /dev/ada0 > @@ -461,11 +460,11 @@ Done.</screen> > 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 > - <devicename>gzero.nop</devicename> even if the new drive > + <devicename>gzero.nop</devicename>, even if the new drive > (<devicename>ada1</devicename>) has more space. Note that the > <replaceable>1000204821504</replaceable> in the second line > - should be equal to <devicename>ada0</devicename>'s media size > - as shown by &man.diskinfo.8; above.</para> > + should be equal to the size of <devicename>ada0</devicename> > + as shown by &man.diskinfo.8;.</para> "media size" is (was) mentioned to help the user find the right value in diskinfo(8) output. > <screen>&prompt.root; <userinput>geom zero load</userinput> > &prompt.root; <userinput>gnop create -s 1000204821504 gzero</userinput> > @@ -502,7 +501,7 @@ Done.</screen> > be explained later.</para> > > <para>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; > <command>backup</command> and <command>restore</command> > subcommands.</para> Okay. But I suggest s/using/with/. > @@ -527,8 +526,8 @@ BSD 8 > 6 freebsd-ufs 130023424 838860800 > 7 freebsd-ufs 968884224 984640881</screen> > > - <para>If the whole disk was used in the output of &man.gpart.8; > - <command>show</command>, the capacity in these partition > + <para>If the whole disk shows as used in the output of > + <command>gpart show</command>, 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.</para> > @@ -550,13 +549,13 @@ BSD 8 > disk, these two files can be used without modification.</para> Suggestion for specifics: "If the output of <command>gpart show</command> 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." > <para>Now restore the partition table into > - <devicename>mirror/gm0</devicename>.</para> > + <devicename>mirror/gm0</devicename>:</para> > > <screen>&prompt.root; <userinput>gpart restore mirror/gm0 < table.ada0</userinput> > &prompt.root; <userinput>gpart restore mirror/gm0s1 < table.ada0s1</userinput></screen> > > - <para>Check the partition table with the &man.gpart.8; > - <command>show</command>. This example has > + <para>Check the partition table with > + <command>gpart show</command>. This example has > <devicename>gm0s1a</devicename> for <filename>/</filename>, > <devicename>gm0s1d</devicename> for <filename>/var</filename>, > <devicename>gm0s1e</devicename> for <filename>/usr</filename>, > @@ -707,8 +706,7 @@ mirror/gm0 COMPLETE ada1 (ACTIVE) > > <para>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.</para> > + used for booting as they contain identical data.</para> > </sect4> Needs a comma after "booting", I think. > <sect4> > @@ -742,10 +740,10 @@ mountroot></screen> > <para>Forgetting to load the > <filename>geom_mirror</filename> module in > <filename>/boot/loader.conf</filename> can cause this > - problem. To fix it, boot from a &os;-9 or later CD or USB > - stick and choose <literal>Shell</literal> at the first > - prompt. Then load the mirror module and mount the mirror > - device:</para> > + problem. To fix it, boot from a &os; 9.0 or later > + installation media and choose <literal>Shell</literal> at > + the first prompt. Then load the mirror module and mount > + the mirror device:</para> > > <screen>&prompt.root; <userinput>gmirror load</userinput> > &prompt.root; <userinput>mount /dev/mirror/gm0s1a /mnt</userinput></screen> > @@ -759,14 +757,14 @@ mountroot></screen> > > <para>Other problems that cause <literal>error 19</literal> > require more effort to fix. Enter > - <literal>ufs:/dev/ada0s1a</literal> at the prompt. > - Although the system should boot from > + <literal>ufs:/dev/ada0s1a</literal> at the boot loader > + prompt. Although the system should boot from > <devicename>ada0</devicename>, another prompt to select a > shell appears because <filename>/etc/fstab</filename> is > incorrect. Press the Enter key at the prompt. Undo the > modifications so far by reverting > <filename>/etc/fstab</filename>, mounting filesystems from > - the original disk (<devicename>ada0</devicename>) instead > + the original <devicename>ada0</devicename> instead > of the mirror. Reboot the system and try the procedure > again.</para> ada0 is (was) mentioned parenthetically because it was the example, not necessarily what the user will have.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.00.1302111329300.28483>