Date: Fri, 25 Apr 2014 14:48:47 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44662 - head/en_US.ISO8859-1/books/handbook/geom Message-ID: <201404251448.s3PEml81078560@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404251448.s3PEml81078560>