svn commit: r40946 - head/en_US.ISO8859-1/books/handbook/geom

Dru Lavigne dru at FreeBSD.org
Mon Feb 11 14:50:33 UTC 2013


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

Modified: head/en_US.ISO8859-1/books/handbook/geom/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/geom/chapter.xml	Mon Feb 11 13:47:43 2013	(r40945)
+++ head/en_US.ISO8859-1/books/handbook/geom/chapter.xml	Mon Feb 11 14:50:33 2013	(r40946)
@@ -35,11 +35,11 @@
       control utilities which use the framework for configuration.
       This chapter will not go into in depth discussion on how GEOM
       handles or controls I/O, the underlying subsystem, or code.
-      This information is provided through the &man.geom.4; manual
-      page and its various SEE ALSO references.  This chapter is also
-      not a definitive guide to <acronym>RAID</acronym>
-      configurations.  Only GEOM-supported <acronym>RAID</acronym>
-      classifications will be discussed.</para>
+      This information is provided in &man.geom.4; and its various
+      <literal>SEE ALSO</literal> references.  This chapter is also
+      not a definitive guide to <acronym>RAID</acronym> configurations
+      and only GEOM-supported <acronym>RAID</acronym> classifications
+      will be discussed.</para>
 
     <para>After reading this chapter, you will know:</para>
 
@@ -70,13 +70,13 @@
 
     <itemizedlist>
       <listitem>
-	<para>Understand how &os; treats disk devices
-	  (<xref linkend="disks"/>).</para>
+	<para>Understand how &os; treats <link
+	    linkend="disks">disk devices</link>.</para>
       </listitem>
 
       <listitem>
-	<para>Know how to configure and install a new &os; kernel
-	  (<xref linkend="kernelconfig"/>).</para>
+	<para>Know how to configure and install a new <link
+	    linkend="kernelconfig">&os; kernel</link>.</para>
       </listitem>
     </itemizedlist>
   </sect1>
@@ -84,12 +84,12 @@
   <sect1 id="GEOM-intro">
     <title>GEOM Introduction</title>
 
-    <para>GEOM permits access and control to classes — Master
-      Boot Records, <acronym>BSD</acronym> labels, etc — through
-      the use of providers, or the special files in
-      <filename class="directory">/dev</filename>.  Supporting various
-      software <acronym>RAID</acronym> configurations, GEOM will
-      transparently provide access to the operating system and
+    <para>GEOM permits access and control to classes, such as Master
+      Boot Records and <acronym>BSD</acronym> labels, through the use
+      of providers, or the special files in <filename
+	class="directory">/dev</filename>.  By supporting various
+      software <acronym>RAID</acronym> configurations, GEOM
+      transparently provides access to the operating system and
       operating system utilities.</para>
   </sect1>
 
@@ -117,13 +117,13 @@
       <primary>Striping</primary>
     </indexterm>
 
-    <para>Striping is a method used to combine several disk drives
-      into a single volume.  In many cases, this is done through the
-      use of hardware controllers.  The GEOM disk subsystem provides
-      software support for <acronym>RAID</acronym>0, also known as
-      disk striping.</para>
+    <para>Striping combine several disk drives into a single volume.
+      In many cases, this is done through the use of hardware
+      controllers.  The GEOM disk subsystem provides software support
+      for <acronym>RAID</acronym>0, also known as disk
+      striping.</para>
 
-    <para>In a <acronym>RAID</acronym>0 system, data are split up in
+    <para>In a <acronym>RAID</acronym>0 system, data is split into
       blocks that get written across all the drives in the array.
       Instead of having to wait on the system to write 256k to one
       disk, a <acronym>RAID</acronym>0 system can simultaneously write
@@ -168,7 +168,7 @@
 	<para>Determine the device names for the disks which will
 	  be striped, and create the new stripe device.  For example,
 	  to stripe two unused and unpartitioned
-	  <acronym>ATA</acronym> disks, for example
+	  <acronym>ATA</acronym> disks with device names of
 	  <filename>/dev/ad2</filename> and
 	  <filename>/dev/ad3</filename>:</para>
 
@@ -179,21 +179,21 @@ Done.</screen>
       </step>
 
       <step>
-	<para>Write a standard label, also known as a partition
-	  table, on the new volume and install the default
-	  bootstrap code:</para>
+	<para>Write a standard label, also known as a partition table,
+	  on the new volume and install the default bootstrap
+	  code:</para>
 
 	<screen>&prompt.root; <userinput>bsdlabel -wB /dev/stripe/st0</userinput></screen>
       </step>
 
       <step>
-	<para>This process should have created two other devices
-	  in the <filename class="directory">/dev/stripe</filename>
-	  directory in addition to the <devicename>st0</devicename>
-	  device.  Those include <devicename>st0a</devicename> and
-	  <devicename>st0c</devicename>.  At this point a file system
-	  may be created on the <devicename>st0a</devicename> device
-	  with the <command>newfs</command> utility:</para>
+	<para>This process should create two other devices in
+	  <filename class="directory">/dev/stripe</filename> in
+	  addition to <devicename>st0</devicename>.  Those include
+	  <devicename>st0a</devicename> and
+	  <devicename>st0c</devicename>.  At this point, a file system
+	  may be created on <devicename>st0a</devicename> using
+	  <command>newfs</command>:</para>
 
 	<screen>&prompt.root; <userinput>newfs -U /dev/stripe/st0a</userinput></screen>
 
@@ -209,10 +209,9 @@ Done.</screen>
 
     <para>To mount this striped file system automatically during the
       boot process, place the volume information in
-      <filename>/etc/fstab</filename> file.  For this purpose, a
-      permanent mount point, named
-      <filename class="directory">stripe</filename>, is
-      created:</para>
+      <filename>/etc/fstab</filename>.  In this example, a
+      permanent mount point, named <filename
+	class="directory">stripe</filename>, is created:</para>
 
     <screen>&prompt.root; <userinput>mkdir /stripe</userinput>
 &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>
 
       <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>
 
       <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>
 
       <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,
 	<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>
 
-      <para>Load the &man.gmirror.8; kernel module.</para>
+      <para>Load the &man.gmirror.8; 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>
+	&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>
 
       <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>
 
@@ -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>
 
       <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>
 
 	<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>
 
@@ -780,24 +778,20 @@ mountroot></screen>
     <sect2>
       <title>Recovering from Disk Failure</title>
 
-      <para>The wonderful part about disk mirroring is that an
-	individual disk can fail without causing the mirror to lose
-	any data.</para>
-
-      <para><devicename>ada0</devicename> is one of two drives making
-	up the mirror in the previous example.  If
-	<devicename>ada0</devicename> fails, the mirror will continue
-	to work, providing data from the remaining working drive,
-	<devicename>ada1</devicename>.</para>
-
-      <para>To replace the failed drive, the computer is shut down and
-	the failed drive is physically replaced with a new drive of
-	equal or greater capacity.  Manufacturers use somewhat
-	arbitrary values when rating drives in gigabytes, and the
-	only way to really be sure is to compare the total count of
-	sectors shown by <command>diskinfo -v</command>.  A drive with
-	larger capacity than the mirror will work, although the extra
-	space on the new drive will not be used.</para>
+      <para>The benefit of disk mirroring is that an individual disk
+	can fail without causing the mirror to lose any data.  In the
+	above example, if <devicename>ada0</devicename> fails, the
+	mirror will continue to work, providing data from the
+	remaining working drive, <devicename>ada1</devicename>.</para>
+
+      <para>To replace the failed drive, shut down the system and
+	physically replace the failed drive with a new drive of equal
+	or greater capacity.  Manufacturers use somewhat arbitrary
+	values when rating drives in gigabytes, and the only way to
+	really be sure is to compare the total count of sectors shown
+	by <command>diskinfo -v</command>.  A drive with larger
+	capacity than the mirror will work, although the extra space
+	on the new drive will not be used.</para>
 
       <para>After the computer is powered back up, the mirror will be
 	running in a <quote>degraded</quote> mode with only one drive.
@@ -866,18 +860,18 @@ mountroot></screen>
     </indexterm>
 
     <para><acronym>RAID</acronym>3 is a method used to combine several
-      disk drives into a single volume with a dedicated parity
-      disk.  In a <acronym>RAID</acronym>3 system, data is split up
-      into a number of bytes that are written across all the drives in
-      the array except for one disk which acts as a dedicated parity
-      disk.  This means that reading 1024KB from a
+      disk drives into a single volume with a dedicated parity disk.
+      In a <acronym>RAID</acronym>3 system, data is split up into a
+      number of bytes that are written across all the drives in the
+      array except for one disk which acts as a dedicated parity disk.
+      This means that reading 1024KB from a
       <acronym>RAID</acronym>3 implementation will access all disks in
-      the array.  Performance can be enhanced by using multiple
-      disk controllers.  The <acronym>RAID</acronym>3 array provides a
+      the array.  Performance can be enhanced by using multiple disk
+      controllers.  The <acronym>RAID</acronym>3 array provides a
       fault tolerance of 1 drive, while providing a capacity of 1 -
       1/n times the total capacity of all drives in the array, where n
       is the number of hard drives in the array.  Such a configuration
-      is mostly suitable for storing data of larger sizes, e.g.,
+      is mostly suitable for storing data of larger sizes such as
       multimedia files.</para>
 
     <para>At least 3 physical hard drives are required to build a
@@ -885,7 +879,7 @@ mountroot></screen>
       size, since I/O requests are interleaved to read or write to
       multiple disks in parallel.  Also, due to the nature of
       <acronym>RAID</acronym>3, the number of drives must be
-      equal to 3, 5, 9, 17, etc. (2^n + 1).</para>
+      equal to 3, 5, 9, 17, and so on, or 2^n + 1.</para>
 
     <sect2>
       <title>Creating a Dedicated <acronym>RAID</acronym>3
@@ -955,11 +949,7 @@ Done.</screen>
 
 	  <para>Many numbers will glide across the screen, and after a
 	    bit of time, the process will be complete.  The volume has
-	    been created and is ready to be mounted.</para>
-	</step>
-
-	<step>
-	  <para>The last step is to mount the file system:</para>
+	    been created and is ready to be mounted:</para>
 
 	  <screen>&prompt.root; <userinput>mount /dev/raid3/gr0p1 /multimedia/</userinput></screen>
 
@@ -975,16 +965,16 @@ Done.</screen>
 	<step>
 	  <para>The <filename>geom_raid3.ko</filename> module must be
 	    loaded before the array can be mounted.  To automatically
-	    load the kernel module during the system initialization,
-	    add the following line to the
-	    <filename>/boot/loader.conf</filename> file:</para>
+	    load the kernel module during system initialization, add
+	    the following line to
+	    <filename>/boot/loader.conf</filename>:</para>
 
 	  <programlisting>geom_raid3_load="YES"</programlisting>
 	</step>
 
 	<step>
-	  <para>The following volume information must be added to the
-	    <filename>/etc/fstab</filename> file in order to
+	  <para>The following volume information must be added to
+	    <filename>/etc/fstab</filename> in order to
 	    automatically mount the array's file system during
 	    the system boot process:</para>
 
@@ -998,7 +988,7 @@ Done.</screen>
     <title>GEOM Gate Network Devices</title>
 
     <para>GEOM supports the remote use of devices, such as disks,
-      CD-ROMs, files, etc. through the use of the gate utilities.
+      CD-ROMs, and files through the use of the gate utilities.
       This is similar to <acronym>NFS</acronym>.</para>
 
     <para>To begin, an exports file must be created.  This file
@@ -1010,8 +1000,8 @@ Done.</screen>
 
     <programlisting>192.168.1.0/24 RW /dev/da0s4d</programlisting>
 
-    <para>It will allow all hosts inside the private network access
-      the file system on the <devicename>da0s4d</devicename>
+    <para>This allows all hosts inside the specified private network
+      access to the file system on the <devicename>da0s4d</devicename>
       partition.</para>
 
     <para>To export this device, ensure it is not currently mounted,
@@ -1019,25 +1009,24 @@ Done.</screen>
 
     <screen>&prompt.root; <userinput>ggated</userinput></screen>
 
-    <para>Now to <command>mount</command> the device on the client
+    <para>To <command>mount</command> the device on the client
       machine, issue the following commands:</para>
 
     <screen>&prompt.root; <userinput>ggatec create -o rw 192.168.1.1 /dev/da0s4d</userinput>
 ggate0
 &prompt.root; <userinput>mount /dev/ggate0 /mnt</userinput></screen>
 
-    <para>From here on, the device may be accessed through the
-      <filename class="directory">/mnt</filename> mount point.</para>
+    <para>The device may now be accessed through the <filename
+	class="directory">/mnt</filename> mount point.</para>
 
     <note>
-      <para>It should be pointed out that this will fail if the device
-	is currently mounted on either the server machine or any other
-	machine on the network.</para>
+      <para>However, this will fail if the device is currently mounted
+	on either the server machine or any other machine on the
+	network.</para>
     </note>
 
-    <para>When the device is no longer needed, it may be safely
-      unmounted with the &man.umount.8; command, similar to any other
-      disk device.</para>
+    <para>When the device is no longer needed, unmount it with
+      &man.umount.8;, similar to any other disk device.</para>
   </sect1>
 
   <sect1 id="geom-glabel">
@@ -1050,34 +1039,32 @@ ggate0
       <primary>Disk Labels</primary>
     </indexterm>
 
-    <para>During system initialization, the &os; kernel will create
+    <para>During system initialization, the &os; kernel creates
       device nodes as devices are found.  This method of probing for
-      devices raises some issues, for instance what if a new disk
-      device is added via <acronym>USB</acronym>?  It is very likely
-      that a flash device may be handed the device name of
+      devices raises some issues.  For instance, what if a new disk
+      device is added via <acronym>USB</acronym>?  It is likely that
+      a flash device may be handed the device name of
       <devicename>da0</devicename> and the original
       <devicename>da0</devicename> shifted to
       <devicename>da1</devicename>.  This will cause issues mounting
       file systems if they are listed in
-      <filename>/etc/fstab</filename>, effectively, this may also
-      prevent the system from booting.</para>
+      <filename>/etc/fstab</filename> which may also prevent the
+      system from booting.</para>
 
-    <para>One solution to this issue is to chain the
-      <acronym>SCSI</acronym> devices in order so a new device added
-      to the <acronym>SCSI</acronym> card will be issued unused device
-      numbers.  But what about <acronym>USB</acronym> devices which
-      may replace the primary <acronym>SCSI</acronym> disk?  This
-      happens because <acronym>USB</acronym> devices are usually
-      probed before the <acronym>SCSI</acronym> card.  One solution is
-      to only insert these devices after the system has been booted.
-      Another method could be to use only a single
-      <acronym>ATA</acronym> drive and never list the
-      <acronym>SCSI</acronym> devices in
+    <para>One solution is to chain <acronym>SCSI</acronym> devices
+      in order so a new device added to the <acronym>SCSI</acronym>
+      card will be issued unused device numbers.  But what about
+      <acronym>USB</acronym> devices which may replace the primary
+      <acronym>SCSI</acronym> disk?  This happens because
+      <acronym>USB</acronym> devices are usually probed before the
+      <acronym>SCSI</acronym> card.  One solution is to only insert
+      these devices after the system has been booted.  Another method
+      is to use only a single <acronym>ATA</acronym> drive and never
+      list the <acronym>SCSI</acronym> devices in
       <filename>/etc/fstab</filename>.</para>
 
-    <para>A better solution is available.  By using the
-      <command>glabel</command> utility, an administrator or user may
-      label their disk devices and use these labels in
+    <para>A better solution is to use <command>glabel</command> to
+      label the disk devices and use the labels in
       <filename>/etc/fstab</filename>.  Because
       <command>glabel</command> stores the label in the last sector of
       a given provider, the label will remain persistent across
@@ -1086,39 +1073,33 @@ ggate0
       through.</para>
 
     <note>
-      <para>This goes without saying that a label be permanent.  The
-	<command>glabel</command> utility may be used to create both a
-	transient and permanent label.  Only the permanent label will
-	remain consistent across reboots.  See the &man.glabel.8;
-	manual page for more information on the differences between
-	labels.</para>
+      <para><command>glabel</command> can create both transient and
+	permanent labels.  Only permanent labels are consistent across
+	reboots.  Refer to &man.glabel.8; for more information on the
+	differences between labels.</para>
     </note>
 
     <sect2>
       <title>Label Types and Examples</title>
 
-      <para>There are two types of labels, a generic label and a
-	file system label.  Labels can be permanent or temporary.
-	Permanent labels can be created with the &man.tunefs.8;
-	or &man.newfs.8; commands.  They will then be created
-	in a sub-directory of
-	<filename class="directory">/dev</filename>, which will be
-	named according to their file system type.  For example,
+      <para>Permanent labels can be a generic or a file system label.
+	Permanent file system labels can be created with
+	&man.tunefs.8; or &man.newfs.8;.  These types of labels are
+	created in a sub-directory of <filename
+	  class="directory">/dev</filename>, and will be named
+	according to the file system type.  For example,
 	<acronym>UFS</acronym>2 file system labels will be created in
-	the <filename class="directory">/dev/ufs</filename> directory.
-	Permanent labels can also be created with the <command>glabel
-	label</command> command.  These are not file system specific,
-	and will be created in the
-	<filename class="directory">/dev/label</filename>
-	directory.</para>
-
-      <para>A temporary label will go away with the next reboot.
-	These labels will be created in the
-	<filename class="directory">/dev/label</filename> directory
-	and are perfect for experimentation.  A temporary label can be
-	created using the <command>glabel create</command> command.
-	For more information, please read the manual page of
-	&man.glabel.8;.</para>
+	<filename class="directory">/dev/ufs</filename>.  Generic
+	permanent labels can be created with <command>glabel
+	  label</command>.  These are not file system specific and
+	will be created in <filename
+	  class="directory">/dev/label</filename>.</para>
+
+      <para>Temporary labels are destroyed at the next reboot.  These
+	labels are created in <filename
+	  class="directory">/dev/label</filename> and are suited to
+	experimentation.  A temporary label can be created using
+	<command>glabel create</command>.</para>
 
 <!-- XXXTR: How do you create a file system label without running newfs
 	    or when there is no newfs (e.g.: cd9660)? -->
@@ -1131,14 +1112,12 @@ ggate0
 
       <warning>
 	<para>If the file system is full, this may cause data
-	  corruption; however, if the file system is full then the
-	  main goal should be removing stale files and not adding
-	  labels.</para>
+	  corruption.</para>
       </warning>
 
-      <para>A label should now exist in
-	<filename class="directory">/dev/ufs</filename> which may be
-	added to <filename>/etc/fstab</filename>:</para>
+      <para>A label should now exist in <filename
+	  class="directory">/dev/ufs</filename> which may be added
+	to <filename>/etc/fstab</filename>:</para>
 
       <programlisting>/dev/ufs/home		/home            ufs     rw              2      2</programlisting>
 
@@ -1147,7 +1126,7 @@ ggate0
 	  to run <command>tunefs</command>.</para>
       </note>
 
-      <para>Now the file system may be mounted like normal:</para>
+      <para>Now the file system may be mounted:</para>
 
       <screen>&prompt.root; <userinput>mount /home</userinput></screen>
 
@@ -1160,8 +1139,8 @@ ggate0
 
       <para>File systems may also be created with a default label
 	by using the <option>-L</option> flag with
-	<command>newfs</command>.  See the &man.newfs.8; manual page
-	for more information.</para>
+	<command>newfs</command>.  Refer to &man.newfs.8; for
+	more information.</para>
 
       <para>The following command can be used to destroy the
 	label:</para>
@@ -1185,7 +1164,7 @@ ggate0
 	  <filename class="directory">/</filename>,
 	  <filename class="directory">/var</filename>,
 	  <filename class="directory">/usr</filename> and
-	  <filename class="directory">/tmp</filename> file systems, as
+	  <filename class="directory">/tmp</filename>, as
 	  well as a swap partition.</para>
 
 	<para>Reboot the system, and at the &man.loader.8; prompt,
@@ -1207,8 +1186,8 @@ GEOM_LABEL: Label for provider /dev/ad0s
 	<para>The system will continue with multi-user boot.  After
 	  the boot completes, edit <filename>/etc/fstab</filename> and
 	  replace the conventional device names, with their respective
-	  labels.  The final <filename>/etc/fstab</filename> file will
-	  look like the following:</para>
+	  labels.  The final <filename>/etc/fstab</filename> will
+	  look like this:</para>
 
 	<programlisting># Device                Mountpoint      FStype  Options         Dump    Pass#
 /dev/label/swap         none            swap    sw              0       0
@@ -1232,24 +1211,23 @@ devfs on /dev (devfs, local)
       <para>Starting with &os; 7.2, the &man.glabel.8; class
 	supports a new label type for <acronym>UFS</acronym> file
 	systems, based on the unique file system id,
-	<literal>ufsid</literal>.  These labels may be found in the
-	<filename class="directory">/dev/ufsid</filename> directory
-	and are created automatically during system startup.  It is
-	possible to use <literal>ufsid</literal> labels to mount
-	partitions using the <filename>/etc/fstab</filename> facility.
-	Use the <command>glabel status</command> command to receive a
-	list of file systems and their corresponding
-	<literal>ufsid</literal> labels:</para>
+	<literal>ufsid</literal>.  These labels may be found in
+	<filename class="directory">/dev/ufsid</filename> and are
+	created automatically during system startup.  It is possible
+	to use <literal>ufsid</literal> labels to mount partitions
+	using <filename>/etc/fstab</filename>.  Use <command>glabel
+	  status</command> to receive a list of file systems and their
+	corresponding <literal>ufsid</literal> labels:</para>
 
       <screen>&prompt.user; <userinput>glabel status</userinput>
                   Name  Status  Components
 ufsid/486b6fc38d330916     N/A  ad4s1d
 ufsid/486b6fc16926168e     N/A  ad4s1f</screen>
 
-      <para>In the above example <devicename>ad4s1d</devicename>
-	represents the <filename class="directory">/var</filename>
-	file system, while <devicename>ad4s1f</devicename> represents
-	the <filename class="directory">/usr</filename> file system.
+      <para>In the above example, <devicename>ad4s1d</devicename>
+	represents <filename class="directory">/var</filename>,
+	while <devicename>ad4s1f</devicename> represents
+	<filename class="directory">/usr</filename>.
 	Using the <literal>ufsid</literal> values shown, these
 	partitions may now be mounted with the following entries in
 	<filename>/etc/fstab</filename>:</para>
@@ -1258,9 +1236,9 @@ ufsid/486b6fc16926168e     N/A  ad4s1f</
 /dev/ufsid/486b6fc16926168e        /usr        ufs        rw        2      2</programlisting>
 
       <para>Any partitions with <literal>ufsid</literal> labels can be
-	mounted in this way, eliminating the need to create permanent
-	labels for them manually, while still enjoying the benefits of
-	device-name independent mounting.</para>
+	mounted in this way, eliminating the need to manually create
+	permanent labels, while still enjoying the benefits of device
+	name independent mounting.</para>
     </sect2>
   </sect1>
 
@@ -1274,51 +1252,50 @@ ufsid/486b6fc16926168e     N/A  ad4s1f</
       <primary>Journaling</primary>
     </indexterm>
 
-    <para>With the release of &os; 7.0, the long awaited feature
-      of journals has been implemented.  The implementation itself is
-      provided through the <acronym>GEOM</acronym> subsystem and is
-      easily configured via the &man.gjournal.8; utility.</para>
-
-    <para>What is journaling?  Journaling capability stores a log of
-      file system transactions, i.e.: changes that make up a complete
-      disk write operation, before meta-data and file writes are
-      committed to the disk proper.  This transaction log can later
-      be replayed to redo file system transactions, preventing file
-      system inconsistencies.</para>
-
-    <para>This method is yet another mechanism to protect against data
-      loss and inconsistencies of the file system.  Unlike Soft
-      Updates which tracks and enforces meta-data updates and
-      Snapshots which is an image of the file system, an actual log is
-      stored in disk space specifically reserved for this task, and in
-      some cases may be stored on another disk entirely.</para>
+    <para>Beginning with &os; 7.0, support for UFS journals is
+      available.  The implementation is provided through the
+      <acronym>GEOM</acronym> subsystem and is configured using
+      &man.gjournal.8;.</para>
+
+    <para>Journaling stores a log of file system transactions, such as
+      changes that make up a complete disk write operation, before
+      meta-data and file writes are committed to the disk.  This
+      transaction log can later be replayed to redo file system
+      transactions, preventing file system inconsistencies.</para>
+
+    <para>This method provides another mechanism to protect against
+      data loss and inconsistencies of the file system.  Unlike Soft
+      Updates, which tracks and enforces meta-data updates, and
+      snapshots, which create an image of the file system, a log is
+      stored in disk space specifically for this task, and in
+      some cases, may be stored on another disk entirely.</para>
 
     <para>Unlike other file system journaling implementations, the
       <command>gjournal</command> method is block based and not
-      implemented as part of the file system - only as a
+      implemented as part of the file system.  It is a
       <acronym>GEOM</acronym> extension.</para>
 
     <para>To enable support for <command>gjournal</command>, the
-      &os; kernel must have the following option - which is the
-      default on &os; 7.0 and later systems:</para>
+      &os; kernel must have the following option  which is the
+      default on &os; 7.0 and later:</para>
 
     <programlisting>options	UFS_GJOURNAL</programlisting>
 
     <para>If journaled volumes need to be mounted during startup, the
-      <filename>geom_journal.ko</filename> kernel module will also
-      have to be loaded, by adding the following line in
+      <filename>geom_journal.ko</filename> kernel module needs to be
+      loaded, by adding the following line to
       <filename>/boot/loader.conf</filename>:</para>
 
     <programlisting>geom_journal_load="YES"</programlisting>
 
-    <para>Alternatively, this function can also be built into a custom
+    <para>Alternatively, this function can be built into a custom
       kernel, by adding the following line in the kernel configuration
       file:</para>
 
     <programlisting>options	GEOM_JOURNAL</programlisting>
 
     <para>Creating a journal on a free file system may now be done
-      using the following steps, considering that the
+      using the following steps.  In this example,
       <devicename>da4</devicename> is a new <acronym>SCSI</acronym>
       disk:</para>
 
@@ -1332,12 +1309,11 @@ ufsid/486b6fc16926168e     N/A  ad4s1f</
 
     <screen>&prompt.root; <userinput>newfs -O 2 -J /dev/da4.journal</userinput></screen>
 
-    <para>The previously issued command will create a
-      <acronym>UFS</acronym>2 file system on the journaled
-      device.</para>
+    <para>This command will creates a <acronym>UFS</acronym>2 file
+      system on the journaled device.</para>
 
-    <para>Effectively <command>mount</command> the device at the
-      desired point with:</para>
+    <para><command>mount</command> the device at the desired point
+      with:</para>
 
     <screen>&prompt.root; <userinput>mount /dev/da4.journal <replaceable>/mnt</replaceable></userinput></screen>
 
@@ -1351,21 +1327,21 @@ ufsid/486b6fc16926168e     N/A  ad4s1f</
 	<devicename>ad4s2.journal</devicename>.</para>
     </note>
 
-    <para>For better performance, keeping the journal on another disk
-      may be desired.  For these cases, the journal provider or
-      storage device should be listed after the device to enable
-      journaling on.  Journaling may also be enabled on current file
-      systems by using <command>tunefs</command>; however, always make
-      a backup before attempting to alter a file system.  In most
-      cases, the <command>gjournal</command> will fail if it is unable
-      to create the actual journal but this does not protect against
-      data loss incurred as a result of misusing
+    <para>For better performance, the journal may be kept on another
+      disk.  In this configuration, the journal provider or storage
+      device should be listed after the device to enable journaling
+      on.  Journaling may also be enabled on current file systems by
+      using <command>tunefs</command>.  However,
+      <emphasis>always</emphasis> make a backup before attempting to
+      alter a file system.  In most cases, <command>gjournal</command>
+      will fail if it is unable to create the journal, but this does
+      not protect against data loss incurred as a result of misusing
       <command>tunefs</command>.</para>
 
     <para>It is also possible to journal the boot disk of a &os;
-      system.  Please refer to the article <ulink
+      system.  Refer to the article <ulink
 	url="&url.articles.gjournal-desktop;">Implementing UFS
-	Journaling on a Desktop PC</ulink> for detailed instructions
-      on this task.</para>
+	Journaling on a Desktop PC</ulink> for detailed
+      instructions.</para>
   </sect1>
 </chapter>


More information about the svn-doc-all mailing list