svn commit: r44662 - head/en_US.ISO8859-1/books/handbook/geom
Dru Lavigne
dru at FreeBSD.org
Fri Apr 25 14:48:47 UTC 2014
Author: dru
Date: Fri Apr 25 14:48:46 2014
New Revision: 44662
URL: http://svnweb.freebsd.org/changeset/doc/44662
Log:
Editorial review of mirror chapter.
Mostly fixes to acronyms, links, and "filesystems" and sentences beginning
with commands.
Sponsored by: iXsystems
Modified:
head/en_US.ISO8859-1/books/handbook/geom/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/geom/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/geom/chapter.xml Fri Apr 25 14:07:42 2014 (r44661)
+++ head/en_US.ISO8859-1/books/handbook/geom/chapter.xml Fri Apr 25 14:48:46 2014 (r44662)
@@ -295,8 +295,8 @@ Done.</screen>
</warning>
<warning>
- <para>&man.dump.8; is used in these procedures to copy file
- systems. But &man.dump.8; does not work on file systems with
+ <para>While <command>dump</command> is used in these procedures to copy file
+ systems, it does not work on file systems with
soft updates journaling. See &man.tunefs.8; for information
on detecting and disabling soft updates journaling.</para>
</warning>
@@ -307,34 +307,34 @@ Done.</screen>
<para>Many disk systems store metadata at the end of each disk.
Old metadata should be erased before reusing the disk for a
mirror. Most problems are caused by two particular types of
- leftover metadata: GPT partition tables, and old
- &man.gmirror.8; metadata from a previous mirror.</para>
+ leftover metadata: <acronym>GPT</acronym> partition tables and old
+ metadata from a previous mirror.</para>
- <para>GPT metadata can be erased with &man.gpart.8;. This
- example erases both primary and backup GPT partition tables
+ <para><acronym>GPT</acronym> metadata can be erased with <command>gpart</command>. This
+ example erases both primary and backup <acronym>GPT</acronym> partition tables
from disk <filename>ada8</filename>:</para>
<screen>&prompt.root; <userinput>gpart destroy -F ada8</userinput></screen>
- <para>&man.gmirror.8; can remove a disk from an active mirror
- and erase the metadata in one step. Here, the example disk
+ <para>A disk can be removed from an active mirror and the
+ metadata erased in one step using <command>gmirror</command>. Here, the example disk
<filename>ada8</filename> is removed from the active
mirror <filename>gm4</filename>:</para>
<screen>&prompt.root; <userinput>gmirror remove gm4 ada8</userinput></screen>
- <para>If the mirror is not running but old mirror metadata is
+ <para>If the mirror is not running, but old mirror metadata is
still on the disk, use <command>gmirror clear</command> to
remove it:</para>
<screen>&prompt.root; <userinput>gmirror clear ada8</userinput></screen>
- <para>&man.gmirror.8; stores one block of metadata at the end of
- the disk. Because GPT partition schemes also store metadata
- at the end of the disk, mirroring entire GPT disks with
- &man.gmirror.8; is not recommended. MBR partitioning is used
+ <para>When <command>gmirror</command> is used, one block of metadata is stored at the end of
+ the disk. Because <acronym>GPT</acronym> partition schemes also store metadata
+ at the end of the disk, mirroring entire <acronym>GPT</acronym> disks with
+ <command>gmirror</command> is not recommended. <acronym>MBR</acronym> partitioning is used
here because it only stores a partition table at the start of
- the disk and does not conflict with &man.gmirror.8;.</para>
+ the disk and does not conflict with <command>gmirror</command>.</para>
</sect2>
<sect2 xml:id="geom-mirror-two-new-disks">
@@ -347,8 +347,8 @@ Done.</screen>
system. A new mirror will be created on these two disks and
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
+ <para>The
+ <filename>geom_mirror.ko</filename> kernel module must either be built into the
kernel or loaded at boot- or run-time. Manually load the
kernel module now:</para>
@@ -358,17 +358,17 @@ Done.</screen>
<screen>&prompt.root; <userinput>gmirror label -v gm0 /dev/ada1 /dev/ada2</userinput></screen>
- <para><filename>gm0</filename> is a user-chosen device name
+ <para>In this example, <filename>gm0</filename> is a user-chosen device name
assigned to the new mirror. After the mirror has been
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
+ <para><acronym>MBR</acronym> and <application>bsdlabel</application> partition tables can now be created on
+ the mirror with <command>gpart</command>. This example uses a traditional
+ file system 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
+ single <filename>/</filename> file system and a swap partition
will also work.</para>
<para>Partitions on the mirror do not have to be the same size
@@ -400,14 +400,14 @@ Done.</screen>
18874370 137426928 6 freebsd-ufs (65G)
156301298 1 - free - (512B)</screen>
- <para>Make the mirror bootable by installing bootcode in the MBR
+ <para>Make the mirror bootable by installing bootcode in the <acronym>MBR</acronym>
and bsdlabel and setting the active slice:</para>
<screen>&prompt.root; <userinput>gpart bootcode -b /boot/mbr mirror/gm0</userinput>
&prompt.root; <userinput>gpart set -a active -i 1 mirror/gm0</userinput>
&prompt.root; <userinput>gpart bootcode -b /boot/boot mirror/gm0s1</userinput></screen>
- <para>Format the filesystems on the new mirror, enabling
+ <para>Format the file systems on the new mirror, enabling
soft-updates.</para>
<screen>&prompt.root; <userinput>newfs -U /dev/mirror/gm0s1a</userinput>
@@ -415,9 +415,9 @@ 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
+ <para>File systems from the original
<filename>ada0</filename> disk can now be copied onto the
- mirror with &man.dump.8; and &man.restore.8;.</para>
+ mirror with <command>dump</command> and <command>restore</command>.</para>
<screen>&prompt.root; <userinput>mount /dev/mirror/gm0s1a /mnt</userinput>
&prompt.root; <userinput>dump -C16 -b64 -0aL -f - / | (cd /mnt && restore -rf -)</userinput>
@@ -428,8 +428,8 @@ Done.</screen>
&prompt.root; <userinput>dump -C16 -b64 -0aL -f - /tmp | (cd /mnt/tmp && restore -rf -)</userinput>
&prompt.root; <userinput>dump -C16 -b64 -0aL -f - /usr | (cd /mnt/usr && restore -rf -)</userinput></screen>
- <para><filename>/mnt/etc/fstab</filename> must be edited to
- point to the new mirror filesystems:</para>
+ <para>Next, edit <filename>/mnt/etc/fstab</filename> to
+ point to the new mirror file systems:</para>
<programlisting># Device Mountpoint FStype Options Dump Pass#
/dev/mirror/gm0s1a / ufs rw 1 1
@@ -438,21 +438,21 @@ Done.</screen>
/dev/mirror/gm0s1e /tmp ufs rw 2 2
/dev/mirror/gm0s1f /usr ufs rw 2 2</programlisting>
- <para>If the &man.gmirror.8; kernel module has not been built
+ <para>If the <filename>geom_mirror.ko</filename> kernel module has not been built
into the kernel, <filename>/mnt/boot/loader.conf</filename> is
edited to load the module at boot:</para>
<programlisting>geom_mirror_load="YES"</programlisting>
<para>Reboot the system to test the new mirror and verify that
- all data has been copied. The BIOS will see the mirror as two
+ all data has been copied. The <acronym>BIOS</acronym> will see the mirror as two
individual drives rather than a mirror. Because the drives
are identical, it does not matter which is selected to
boot.</para>
- <para>See the <link
- linkend="gmirror-troubleshooting">Troubleshooting</link>
- section if there are problems booting. Powering down and
+ <para>See <xref
+ linkend="gmirror-troubleshooting"/>
+ if there are problems booting. Powering down and
disconnecting the original <filename>ada0</filename> disk
will allow it to be kept as an offline backup.</para>
@@ -469,17 +469,17 @@ Done.</screen>
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
+ is required because <command>gmirror</command> needs to put a 512-byte
block of metadata at the end of each disk, and the existing
<filename>ada0</filename> has usually had all of its space
already allocated.</para>
- <para>Load the &man.gmirror.8; kernel module:</para>
+ <para>Load the <filename>geom_mirror.ko</filename> kernel module:</para>
<screen>&prompt.root; <userinput>gmirror load</userinput></screen>
<para>Check the media size of the original disk with
- &man.diskinfo.8;:</para>
+ <command>diskinfo</command>:</para>
<screen>&prompt.root; <userinput>diskinfo -v ada0 | head -n3</userinput>
/dev/ada0
@@ -488,39 +488,37 @@ Done.</screen>
<para>Create a mirror on the new disk. To make certain that the
mirror capacity is not any larger than the original drive,
- &man.gnop.8; is used to create a fake drive of the exact same
+ <command>gnop</command> is used to create a fake drive of the exact same
size. This drive does not store any data, but is used only to
- limit the size of the mirror. When &man.gmirror.8; creates
+ limit the size of the mirror. When <command>gmirror</command> creates
the mirror, it will restrict the capacity to the size of
<filename>gzero.nop</filename>, even if the new drive
(<filename>ada1</filename>) has more space. Note that the
<replaceable>1000204821504</replaceable> in the second line
should be equal to <filename>ada0</filename>'s media size
- as shown by &man.diskinfo.8; above.</para>
+ as shown by <command>diskinfo</command> above.</para>
<screen>&prompt.root; <userinput>geom zero load</userinput>
&prompt.root; <userinput>gnop create -s 1000204821504 gzero</userinput>
&prompt.root; <userinput>gmirror label -v gm0 gzero.nop ada1</userinput>
&prompt.root; <userinput>gmirror forget gm0</userinput></screen>
- <para><filename>gzero.nop</filename> does not store any
- data, so the mirror does not see it as connected. The mirror
+ <para>Since <filename>gzero.nop</filename> does not store any
+ data, the mirror does not see it as connected. The mirror
is told to <quote>forget</quote> unconnected components,
removing references to <filename>gzero.nop</filename>.
The result is a mirror device containing only a single disk,
<filename>ada1</filename>.</para>
<para>After creating <filename>gm0</filename>, view the
- partition table on <filename>ada0</filename>.</para>
-
- <para>This output is from a 1 TB drive. If there is some
+ partition table on <filename>ada0</filename>. This output is from a 1 TB drive. If there is some
unallocated space at the end of the drive, the contents may be
copied directly from <filename>ada0</filename> to the new
mirror.</para>
<para>However, if the output shows that all of the space on the
- disk is allocated like the following listing, there is no
- space available for the 512-byte &man.gmirror.8; metadata at
+ disk is allocated, like in the following listing, there is no
+ space available for the 512-byte mirror metadata at
the end of the disk.</para>
<screen>&prompt.root; <userinput>gpart show ada0</userinput>
@@ -533,9 +531,8 @@ Done.</screen>
be explained later.</para>
<para>In either case, partition tables on the primary disk
- should be copied first with the &man.gpart.8;
- <command>backup</command> and <command>restore</command>
- subcommands.</para>
+ should be first copied using <command>gpart backup</command>
+ and <command>gpart restore</command>.</para>
<screen>&prompt.root; <userinput>gpart backup ada0 > table.ada0</userinput>
&prompt.root; <userinput>gpart backup ada0s1 > table.ada0s1</userinput></screen>
@@ -615,7 +612,7 @@ BSD 8
<para>Both the slice and the last partition should have some
free space at the end of each disk.</para>
- <para>Create filesystems on these new partitions. The
+ <para>Create file systems on these new partitions. The
number of partitions will vary, matching the partitions on the
original disk, <filename>ada0</filename>.</para>
@@ -625,7 +622,7 @@ BSD 8
&prompt.root; <userinput>newfs -U /dev/mirror/gm0s1f</userinput>
&prompt.root; <userinput>newfs -U /dev/mirror/gm0s1g</userinput></screen>
- <para>Make the mirror bootable by installing bootcode in the MBR
+ <para>Make the mirror bootable by installing bootcode in the <acronym>MBR</acronym>
and bsdlabel and setting the active slice:</para>
<screen>&prompt.root; <userinput>gpart bootcode -b /boot/mbr mirror/gm0</userinput>
@@ -650,15 +647,15 @@ BSD 8
/dev/mirror/gm0s1f /data1 ufs rw 2 2
/dev/mirror/gm0s1g /data2 ufs rw 2 2</programlisting>
- <para>If the &man.gmirror.8; kernel module has not been built
+ <para>If the <filename>geom_mirror.ko</filename> kernel module has not been built
into the kernel, edit <filename>/boot/loader.conf</filename>
to load it:</para>
<programlisting>geom_mirror_load="YES"</programlisting>
- <para>Filesystems from the original disk can now be copied onto
- the mirror with &man.dump.8; and &man.restore.8;. Note that
- it may take some time to create a snapshot for each filesystem
+ <para>File systems from the original disk can now be copied onto
+ the mirror with <command>dump</command> and <command>restore</command>. Note that
+ it may take some time to create a snapshot for each file system
dumped with <command>dump -L</command>.</para>
<screen>&prompt.root; <userinput>mount /dev/mirror/gm0s1a /mnt</userinput>
@@ -676,9 +673,9 @@ BSD 8
<filename>ada1</filename>. If everything is working, the
system will boot from <filename>mirror/gm0</filename>,
which now contains the same data as
- <filename>ada0</filename> had previously. See the
- <link linkend="gmirror-troubleshooting">Troubleshooting</link>
- section if there are problems booting.</para>
+ <filename>ada0</filename> had previously. See
+ <xref linkend="gmirror-troubleshooting"/>
+ if there are problems booting.</para>
<para>At this point, the mirror still consists of only the
single <filename>ada1</filename> disk.</para>
@@ -694,9 +691,9 @@ BSD 8
<filename>mirror/gm0</filename> has the same contents as
<filename>ada0</filename> before adding
<filename>ada0</filename> to the mirror. If there is
- something wrong with the contents copied by &man.dump.8; and
- &man.restore.8;, revert <filename>/etc/fstab</filename> to
- mount the filesystems on <filename>ada0</filename>,
+ something wrong with the contents copied by <command>dump</command> and
+ <command>restore</command>, revert <filename>/etc/fstab</filename> to
+ mount the file systems on <filename>ada0</filename>,
reboot, and try the whole procedure again.</para>
</important>
@@ -704,8 +701,8 @@ BSD 8
GEOM_MIRROR: Device gm0: rebuilding provider ada0</screen>
<para>Synchronization between the two disks will start
- immediately. &man.gmirror.8; <command>status</command>
- shows the progress.</para>
+ immediately. Use <command>gmirror status</command>
+ to view the progress.</para>
<screen>&prompt.root; <userinput>gmirror status</userinput>
Name Status Components
@@ -720,7 +717,7 @@ mirror/gm0 DEGRADED ada1 (ACTIVE)
mirror/gm0 COMPLETE ada1 (ACTIVE)
ada0 (ACTIVE)</screen>
- <para><filename>mirror/gm0</filename> now consists of
+ <para>The mirror, <filename>mirror/gm0</filename>, now consists of
the two disks <filename>ada0</filename> and
<filename>ada1</filename>, and the contents are
automatically synchronized with each other. In use,
@@ -731,21 +728,12 @@ mirror/gm0 COMPLETE ada1 (ACTIVE)
<sect2 xml:id="gmirror-troubleshooting">
<title>Troubleshooting</title>
- <sect3>
- <title>Problems with Booting</title>
-
- <sect4>
- <title>BIOS Settings</title>
-
- <para>BIOS settings may have to be changed to boot from one
+ <para>If the system no longer boots, <acronym>BIOS</acronym>
+ settings may have to be changed to boot from one
of the new mirrored drives. Either mirror drive can be
used for booting, as they contain identical data.</para>
- </sect4>
- <sect4>
- <title>Boot Problems</title>
-
- <para>If the boot stopped with this message, something is
+ <para>If the boot stops with this message, something is
wrong with the mirror device:</para>
<screen>Mounting from ufs:/dev/mirror/gm0s1a failed with error 19.
@@ -771,7 +759,7 @@ Manual root filesystem specification:
mountroot></screen>
<para>Forgetting to load the
- <filename>geom_mirror</filename> module in
+ <filename>geom_mirror.ko</filename> module in
<filename>/boot/loader.conf</filename> can cause this
problem. To fix it, boot from a &os; 9.0 or later
installation media and choose <literal>Shell</literal> at
@@ -788,15 +776,15 @@ mountroot></screen>
<para>Save the file and reboot.</para>
- <para>Other problems that cause <literal>error 19</literal>
- require more effort to fix. Enter
- <literal>ufs:/dev/ada0s1a</literal> at the boot loader
- prompt. Although the system should boot from
+ <para>Other problems that cause <errorname>error 19</errorname>
+ require more effort to fix. Although the system should boot from
<filename>ada0</filename>, 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
+ shell will appear if <filename>/etc/fstab</filename> is
+ incorrect. Enter
+ <literal>ufs:/dev/ada0s1a</literal> at the boot loader
+ prompt and press <keycap>Enter</keycap>. Undo the
+ edits in
+ <filename>/etc/fstab</filename> then mount the file systems from
the original disk (<filename>ada0</filename>) instead
of the mirror. Reboot the system and try the procedure
again.</para>
@@ -804,8 +792,6 @@ mountroot></screen>
<screen>Enter full pathname of shell or RETURN for /bin/sh:
&prompt.root; <userinput>cp /etc/fstab.orig /etc/fstab</userinput>
&prompt.root; <userinput>reboot</userinput></screen>
- </sect4>
- </sect3>
</sect2>
<sect2>
@@ -833,9 +819,8 @@ mountroot></screen>
<screen>&prompt.root; <userinput>gmirror forget gm0</userinput></screen>
- <para>Any old metadata should be
- <link linkend="geom-mirror-metadata">cleared from the
- replacement disk</link>. Then the disk,
+ <para>Any old metadata should be cleared from the replacement disk using the instructions in
+ <xref linkend="geom-mirror-metadata"/>. Then the disk,
<filename>ada4</filename> for this example, is inserted into
the mirror:</para>
More information about the svn-doc-head
mailing list