Skip site navigation (1)Skip section navigation (2)
Date:      Tue, 18 Mar 2014 00:11:28 GMT
From:      Allan Jude <freebsd@allanjude.com>
To:        freebsd-gnats-submit@FreeBSD.org
Subject:   docs/187686: [patch] Update disks section of handbook for 9.x/10.x
Message-ID:  <201403180011.s2I0BS6u070992@cgiserv.freebsd.org>
Resent-Message-ID: <201403180020.s2I0K0rO065953@freefall.freebsd.org>

next in thread | raw e-mail | index | archive | help

>Number:         187686
>Category:       docs
>Synopsis:       [patch] Update disks section of handbook for 9.x/10.x
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          update
>Submitter-Id:   current-users
>Arrival-Date:   Tue Mar 18 00:20:00 UTC 2014
>Closed-Date:
>Last-Modified:
>Originator:     Allan Jude
>Release:        9.2-RELEASE
>Organization:
ScaleEngine Inc.
>Environment:
FreeBSD Trooper.HML3.ScaleEngine.net 9.2-RELEASE FreeBSD 9.2-RELEASE #0 r255898: Thu Sep 26 22:50:31 UTC 2013     root@bake.isc.freebsd.org:/usr/obj/usr/src/sys/GENERIC  amd64

>Description:
The disks section of the handbook is full of examples based on the FreeBSD 8.x and prior disk laying (MBR/BSD with separate partitions for / /tmp /usr /var) and the old device names (ad4 instead of ada1)

Updated the docs for all of that, and also added a lot of markup: acronym, replaceable, changed some incorrect literal to filename (for device names), etc.

Added 'mfi' to the RAID list since it is the most popular controller now

Updated the USB instructions to mention USB 3.0 and xhci

Added some missing xml:id to allow cross referencing the GELI section from the installer section etc.
>How-To-Repeat:

>Fix:
Patch Attached

Patch attached with submission follows:

Index: head/en_US.ISO8859-1/books/handbook/disks/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/handbook/disks/chapter.xml	(revision 44203)
+++ head/en_US.ISO8859-1/books/handbook/disks/chapter.xml	(working copy)
@@ -14,9 +14,9 @@
   <sect1 xml:id="disks-synopsis">
     <title>Synopsis</title>
 
-    <para>This chapter covers the use of disks in &os;.  This includes
-      memory-backed disks, network-attached disks, standard SCSI/IDE
-      storage devices, and devices using the USB interface.</para>
+    <para>This chapter covers the configuration and use of disks in &os;.  This includes
+      memory-backed disks, network-attached disks, standard <acronym>SCSI</acronym>/<acronym>IDE</acronym> and <acronym>SATA</acronym>
+      storage devices, and removable devices using the <acronym>USB</acronym> interface.</para>
 
     <para>After reading this chapter, you will know:</para>
 
@@ -23,7 +23,7 @@
     <itemizedlist>
       <listitem>
 	<para>The terminology &os; uses to describe the organization
-	  of data on a physical disk.</para>
+	  of data on a physical or logical disk.</para>
       </listitem>
 
       <listitem>
@@ -32,7 +32,7 @@
       </listitem>
 
       <listitem>
-	<para>How to configure &os; to use USB storage devices.</para>
+	<para>How to configure &os; to use <acronym>USB</acronym> storage devices.</para>
       </listitem>
 
       <listitem>
@@ -93,75 +93,76 @@
 
 	<tbody>
 	  <row>
-	    <entry>IDE hard drives</entry>
-	    <entry><literal>ad</literal> or
-	      <literal>ada</literal></entry>
+	    <entry><acronym>IDE</acronym> hard drives</entry>
+	    <entry><filename>ad</filename> or
+	      <filename>ada</filename></entry>
 	  </row>
 
 	  <row>
-	    <entry>IDE CD-ROM drives</entry>
-	    <entry><literal>acd</literal> or
-	      <literal>cd</literal></entry>
+	    <entry><acronym>IDE</acronym> CD-ROM drives</entry>
+	    <entry><filename>acd</filename> or
+	      <filename>cd</filename></entry>
 	  </row>
 
 	  <row>
-	    <entry>SATA hard drives</entry>
-	    <entry><literal>ad</literal> or
-	      <literal>ada</literal></entry>
+	    <entry><acronym>SATA</acronym> hard drives</entry>
+	    <entry><filename>ad</filename> or
+	      <filename>ada</filename></entry>
 	  </row>
 
 	  <row>
-	    <entry>SATA CD-ROM drives</entry>
-	    <entry><literal>acd</literal> or
-	      <literal>cd</literal></entry>
+	    <entry><acronym>SATA</acronym> CD-ROM drives</entry>
+	    <entry><filename>acd</filename> or
+	      <filename>cd</filename></entry>
 	  </row>
 
 	  <row>
-	    <entry>SCSI hard drives and USB Mass storage
+	    <entry><acronym>SCSI</acronym> hard drives and <acronym>USB</acronym> Mass storage
 	      devices</entry>
-	    <entry><literal>da</literal></entry>
+	    <entry><filename>da</filename></entry>
 	  </row>
 
 	  <row>
-	    <entry>SCSI CD-ROM drives</entry>
-	    <entry><literal>cd</literal></entry>
+	    <entry><acronym>SCSI</acronym> CD-ROM drives</entry>
+	    <entry><filename>cd</filename></entry>
 	  </row>
 
 	  <row>
 	    <entry>Assorted non-standard CD-ROM drives</entry>
-	    <entry><literal>mcd</literal> for Mitsumi CD-ROM and
-	      <literal>scd</literal> for Sony CD-ROM devices</entry>
+	    <entry><filename>mcd</filename> for Mitsumi CD-ROM and
+	      <filename>scd</filename> for Sony CD-ROM devices</entry>
 	  </row>
 
 	  <row>
 	    <entry>Floppy drives</entry>
-	    <entry><literal>fd</literal></entry>
+	    <entry><filename>fd</filename></entry>
 	  </row>
 
 	  <row>
-	    <entry>SCSI tape drives</entry>
-	    <entry><literal>sa</literal></entry>
+	    <entry><acronym>SCSI</acronym> tape drives</entry>
+	    <entry><filename>sa</filename></entry>
 	  </row>
 
 	  <row>
-	    <entry>IDE tape drives</entry>
-	    <entry><literal>ast</literal></entry>
+	    <entry><acronym>IDE</acronym> tape drives</entry>
+	    <entry><filename>ast</filename></entry>
 	  </row>
 
 	  <row>
 	    <entry>Flash drives</entry>
-	    <entry><literal>fla</literal> for &diskonchip; Flash
+	    <entry><filename>fla</filename> for &diskonchip; Flash
 	      device</entry>
 	  </row>
 
 	  <row>
 	    <entry>RAID drives</entry>
-	    <entry><literal>aacd</literal> for &adaptec; AdvancedRAID,
-	      <literal>mlxd</literal> and <literal>mlyd</literal>
+	    <entry><filename>aacd</filename> for &adaptec; AdvancedRAID,
+	      <filename>mlxd</filename> and <filename>mlyd</filename>
 	      for &mylex;,
-	      <literal>amrd</literal> for AMI &megaraid;,
-	      <literal>idad</literal> for Compaq Smart RAID,
-	      <literal>twed</literal> for &tm.3ware; RAID.</entry>
+	      <filename>amrd</filename> for AMI &megaraid;,
+	      <filename>idad</filename> for Compaq Smart RAID,
+	      <filename>twed</filename> for &tm.3ware; RAID,
+	      <filename>mfid</filename> for &lsilogic; &megaraid;.</entry>
 	  </row>
 	</tbody>
       </tgroup>
@@ -402,7 +403,7 @@
 
   <sect1 xml:id="usb-disks">
     <info>
-      <title>USB Storage Devices</title>
+      <title><acronym>USB</acronym> Storage Devices</title>
 
       <authorgroup>
 	<author>
@@ -420,52 +421,44 @@
       <secondary>disks</secondary>
     </indexterm>
 
-    <para>Many external storage solutions, such as hard drives, USB
+    <para>Many external storage solutions, such as hard drives, <acronym>USB</acronym>
       thumbdrives, and CD/DVD burners, use the Universal Serial Bus
-      (USB).  &os; provides support for these devices.</para>
+      (<acronym>USB</acronym>).  &os; provides support for these devices.</para>
 
     <sect2>
       <title>Configuration</title>
 
-      <para>The USB mass storage devices driver, &man.umass.4;, is
+      <para>The <acronym>USB</acronym> mass storage devices driver, &man.umass.4;, is
 	built into the <filename>GENERIC</filename> kernel and
-	provides support for USB storage devices.  For a custom
+	provides support for <acronym>USB</acronym> storage devices.  For a custom
 	kernel, be sure that the following lines are present in the
 	kernel configuration file:</para>
 
-      <programlisting>device scbus
-device da
-device pass
-device uhci
-device ohci
-device ehci
-device usb
-device umass</programlisting>
+      <programlisting>device          scbus           # SCSI bus (required for ATA/SCSI) 
+device          da              # Direct Access (disks)
+device          cd              # CD
+device          pass            # Passthrough device (direct ATA/SCSI access)
+device          uhci            # UHCI PCI->USB interface
+device          ohci            # OHCI PCI->USB interface
+device          ehci            # EHCI PCI->USB interface (USB 2.0)
+device          xhci            # XHCI PCI->USB interface (USB 3.0)
+device          usb             # USB Bus (required)
+device          umass           # Disks/Mass storage - Requires scbus and da</programlisting>
 
-      <para>Since the &man.umass.4; driver uses the SCSI subsystem to
-	access the USB storage devices, any USB device will be seen as
-	a SCSI device by the system.  Depending on the USB chipset on
+      <para>Since the &man.umass.4; driver uses the <acronym>SCSI</acronym> subsystem to
+	access the <acronym>USB</acronym> storage devices, any <acronym>USB</acronym> device will be seen as
+	a <acronym>SCSI</acronym> device by the system.  Depending on the <acronym>USB</acronym> chipset on
 	the motherboard, <literal>device uhci</literal> or
-	<literal>device ohci</literal> is used to provide USB 1.X
-	support.  Support for USB 2.0 controllers is provided by
-	<literal>device ehci</literal>.</para>
-
-      <note>
-	<para>If the USB device is a CD or DVD burner, &man.cd.4;,
-	  must be added to the kernel via the line:</para>
-
-	<programlisting>device cd</programlisting>
-
-	<para>Since the burner is seen as a SCSI drive, the driver
-	  &man.atapicam.4; should not be used in the kernel
-	  configuration.</para>
-      </note>
+	<literal>device ohci</literal> is used to provide <acronym>USB</acronym> 1.X
+	support.  Support for <acronym>USB</acronym> 2.0 controllers is provided by
+	<literal>device ehci</literal> and <acronym>USB</acronym> 3.0
+	by <filename>xhci</filename>.</para>
     </sect2>
 
     <sect2>
       <title>Testing the Configuration</title>
 
-      <para>To test the USB configuration, plug in the USB device.  In
+      <para>To test the <acronym>USB</acronym> configuration, plug in the <acronym>USB</acronym> device.  In
 	the system message buffer, &man.dmesg.8;, the drive should
 	appear as something like:</para>
 
@@ -479,8 +472,8 @@
       <para>The brand, device node (<filename>da0</filename>), and
 	other details will differ according to the device.</para>
 
-      <para>Since the USB device is seen as a SCSI one,
-	<command>camcontrol</command> can be used to list the USB
+      <para>Since the <acronym>USB</acronym> device is seen as a <acronym>SCSI</acronym> device,
+	<command>camcontrol</command> can be used to list the <acronym>USB</acronym>
 	storage devices attached to the system:</para>
 
       <screen>&prompt.root; <userinput>camcontrol devlist</userinput>
@@ -488,7 +481,7 @@
 
       <para>If the drive comes with a file system, it can be mounted.
 	Refer to <xref linkend="disks-adding"/> for
-	instructions on how to format and create partitions on the USB
+	instructions on how to format and create partitions on the <acronym>USB</acronym>
 	drive.</para>
 
       <warning>
@@ -511,24 +504,24 @@
 add path 'da*' mode 0660 group operator</programlisting>
 
       <note>
-	<para>If SCSI disks are installed in the system, change
+	<para>If <acronym>SCSI</acronym> disks are installed in the system, change
 	  the second line as follows:</para>
 
 	<programlisting>add path 'da[3-9]*' mode 0660 group operator</programlisting>
 
-	<para>This will exclude the first three SCSI disks
-	  (<filename>da0</filename> to
-	  <filename>da2</filename>)from belonging to the
+	<para>This will exclude the first three <acronym>SCSI</acronym> disks
+	  (<filename>da0</filename> through
+	  <filename>da2</filename>) from belonging to the
 	  <systemitem class="groupname">operator</systemitem>
 	  group.</para>
       </note>
 
-      <para>Next, enable the &man.devfs.rules.5; ruleset in
+      <para>Enable the &man.devfs.rules.5; ruleset in
 	<filename>/etc/rc.conf</filename>:</para>
 
       <programlisting>devfs_system_ruleset="localrules"</programlisting>
 
-      <para>Next, instruct the running kernel to allow regular users
+      <para>Instruct the running kernel to allow regular users
 	to mount file systems.  The easiest way is to add the
 	following line to
 	<filename>/etc/sysctl.conf</filename>:</para>
@@ -551,7 +544,7 @@
       <screen>&prompt.root; <userinput>mkdir /mnt/username</userinput>
 &prompt.root; <userinput>chown username:usergroup /mnt/username</userinput></screen>
 
-      <para>Suppose a USB thumbdrive is plugged in, and a device
+      <para>Suppose a <acronym>USB</acronym> thumbdrive is plugged in, and a device
 	<filename>/dev/da0s1</filename> appears.  If the device is
 	preformatted with a FAT file system, it can be mounted
 	using:</para>
@@ -646,13 +639,13 @@
       </indexterm>
 
       <para>Which tool to use to burn the CD depends on whether the
-	CD burner is ATAPI or something else.  ATAPI CD burners use
+	CD burner is <acronym>ATAPI</acronym> or something else.  <acronym>ATAPI</acronym> CD burners use
 	<command>burncd</command> which is part of the base system.
-	SCSI and USB CD burners should use <command>cdrecord</command>
+	<acronym>SCSI</acronym> and <acronym>USB</acronym> CD burners should use <command>cdrecord</command>
 	from the <package>sysutils/cdrtools</package> port.  It is
 	also possible to use <command>cdrecord</command> and other
-	tools for SCSI drives on ATAPI hardware with the
-	<link linkend="atapicam">ATAPI/CAM module</link>.</para>
+	tools for <acronym>SCSI</acronym> drives on <acronym>ATAPI</acronym> hardware with the
+	<link linkend="atapicam"><acronym>ATAPI</acronym>/<acronym>CAM</acronym> module</link>.</para>
 
       <para>For CD burning software with a graphical user
 	interface, consider <application>X-CD-Roast</application> or
@@ -661,7 +654,7 @@
 	<package>sysutils/k3b</package> ports.
 	<application>X-CD-Roast</application> and
 	<application>K3b</application> require the
-	<link linkend="atapicam">ATAPI/CAM module</link> with ATAPI
+	<link linkend="atapicam"><acronym>ATAPI</acronym>/<acronym>CAM</acronym> module</link> with <acronym>ATAPI</acronym>
 	hardware.</para>
     </sect2>
 
@@ -755,7 +748,7 @@
 	<primary>CD-ROMs</primary>
 	<secondary>burning</secondary>
       </indexterm>
-      <para>For an ATAPI CD burner, <command>burncd</command> can be
+      <para>For an <acronym>ATAPI</acronym> CD burner, <command>burncd</command> can be
 	used to burn an ISO image onto a CD.
 	<command>burncd</command> is part of the base system,
 	installed as <filename>/usr/sbin/burncd</filename>.  Usage is
@@ -774,7 +767,7 @@
     <sect2 xml:id="cdrecord">
       <title><application>cdrecord</application></title>
 
-      <para>For systems without an ATAPI CD burner,
+      <para>For systems without an <acronym>ATAPI</acronym> CD burner,
 	<command>cdrecord</command> can be used to burn CDs.
 	<command>cdrecord</command> is not part of the base system and
 	must be installed from either the
@@ -838,11 +831,11 @@
 
       <para>To duplicate an audio CD, extract the audio data from the
 	CD to a series of files, then write these files to a blank CD.
-	The process is slightly different for ATAPI and SCSI
+	The process is slightly different for <acronym>ATAPI</acronym> and <acronym>SCSI</acronym>
 	drives.</para>
 
       <procedure>
-	<title>SCSI Drives</title>
+	<title><acronym>SCSI</acronym> Drives</title>
 
 	<step>
 	  <para>Use <command>cdda2wav</command> to extract the
@@ -864,12 +857,12 @@
       </procedure>
 
       <procedure>
-	<title>ATAPI Drives</title>
+	<title><acronym>ATAPI</acronym> Drives</title>
 
 	<note>
 	  <para>With the help of the
-	    <link linkend="atapicam">ATAPI/CAM module</link>,
-	    <command>cdda2wav</command> can also be used on ATAPI
+	    <link linkend="atapicam"><acronym>ATAPI</acronym>/<acronym>CAM</acronym> module</link>,
+	    <command>cdda2wav</command> can also be used on <acronym>ATAPI</acronym>
 	    drives.  This tool is usually a better choice for most of
 	    users, as it supports jitter correction and endianness,
 	    than the method proposed below.</para>
@@ -876,7 +869,7 @@
 	</note>
 
 	<step>
-	  <para>The ATAPI CD driver makes each track available as
+	  <para>The <acronym>ATAPI</acronym> CD driver makes each track available as
 	    <filename>/dev/acddtnn</filename>,
 	    where <replaceable>d</replaceable> is the drive number,
 	    and <replaceable>nn</replaceable> is the track number
@@ -941,7 +934,7 @@
 
       <para>will generate an error about <errorname>Incorrect super
 	  block</errorname>, and will fail to mount the CD.  The CD
-	  does not use the <literal>UFS</literal> file system, so
+	  does not use the <acronym>UFS</acronym> file system, so
 	  attempts to mount it as such will fail.  Instead, tell
 	  &man.mount.8; that the file system is of type
 	  <literal>ISO9660</literal> by specifying
@@ -950,7 +943,7 @@
 	  under <filename>/mnt</filename>,
 	  use:</para>
 
-      <screen>&prompt.root; <userinput>mount -t cd9660 /dev/cd0 /mnt</userinput></screen>
+      <screen>&prompt.root; <userinput>mount -t cd9660 <replaceable>/dev/cd0</replaceable> /mnt</userinput></screen>
 
       <para>Replace <filename>/dev/cd0</filename> with the device
 	name for the CD device.  Also, <option>-t cd9660</option>
@@ -989,7 +982,7 @@
 	It can take a couple of seconds for a CD-ROM drive to realize
 	that a media is present, so be patient.</para>
 
-      <para>Sometimes, a SCSI CD-ROM may be missed because it did not
+      <para>Sometimes, a <acronym>SCSI</acronym> CD-ROM may be missed because it did not
 	have enough time to answer the bus reset.  To resolve this,
 	add the following option to the kernel configuration and
 	<link linkend="kernelconfig-building">rebuild the
@@ -997,7 +990,7 @@
 
       <programlisting>options SCSI_DELAY=15000</programlisting>
 
-      <para>This tells the SCSI bus to pause 15 seconds during boot,
+      <para>This tells the <acronym>SCSI</acronym> bus to pause 15 seconds during boot,
 	to give the CD-ROM drive every possible chance to answer the
 	bus reset.</para>
     </sect2>
@@ -1026,7 +1019,7 @@
 
     <sect2 xml:id="atapicam">
       <info>
-	<title>Using the ATAPI/CAM Driver</title>
+	<title>Using the <acronym>ATAPI</acronym>/<acronym>CAM</acronym> Driver</title>
 
 	<authorgroup>
 	  <author>
@@ -1041,11 +1034,11 @@
 
       <indexterm>
 	<primary>CD burner</primary>
-	<secondary>ATAPI/CAM driver</secondary>
+	<secondary><acronym>ATAPI</acronym>/<acronym>CAM</acronym> driver</secondary>
       </indexterm>
 
-      <para>This driver allows ATAPI devices, such as CD/DVD drives,
-	to be accessed through the SCSI subsystem, and so allows the
+      <para>This driver allows <acronym>ATAPI</acronym> devices, such as CD/DVD drives,
+	to be accessed through the <acronym>SCSI</acronym> subsystem, and so allows the
 	use of applications like <package>sysutils/cdrdao</package> or
 	&man.cdrecord.1;.</para>
 
@@ -1092,17 +1085,17 @@
       <screen>&prompt.root; <userinput>mount -t cd9660 /dev/cd0 /mnt</userinput></screen>
 
       <para>As <systemitem class="username">root</systemitem>, run the
-	following command to get the SCSI address of the
+	following command to get the <acronym>SCSI</acronym> address of the
 	burner:</para>
 
       <screen>&prompt.root; <userinput>camcontrol devlist</userinput>
 &lt;MATSHITA CDRW/DVD UJDA740 1.00&gt;   at scbus1 target 0 lun 0 (pass0,cd0)</screen>
 
-      <para>In this example, <literal>1,0,0</literal> is the SCSI
-	address to use with &man.cdrecord.1; and other SCSI
+      <para>In this example, <literal>1,0,0</literal> is the <acronym>SCSI</acronym>
+	address to use with &man.cdrecord.1; and other <acronym>SCSI</acronym>
 	applications.</para>
 
-      <para>For more information about ATAPI/CAM and SCSI system,
+      <para>For more information about <acronym>ATAPI</acronym>/<acronym>CAM</acronym> and <acronym>SCSI</acronym> system,
 	refer to &man.atapicam.4; and &man.cam.4;.</para>
     </sect2>
   </sect1>
@@ -1205,14 +1198,14 @@
 	<package>sysutils/dvd+rw-tools</package> utilities which
 	support all DVD media types.</para>
 
-      <para>These tools use the SCSI subsystem to access the devices,
-	therefore <link linkend="atapicam">ATAPI/CAM support</link>
+      <para>These tools use the <acronym>SCSI</acronym> subsystem to access the devices,
+	therefore <link linkend="atapicam"><acronym>ATAPI</acronym>/<acronym>CAM</acronym> support</link>
 	must be loaded or statically compiled into the kernel.  This
-	support is not needed if the burner uses the USB interface.
+	support is not needed if the burner uses the <acronym>USB</acronym> interface.
 	Refer to <xref linkend="usb-disks"/> for more details
-	on USB device configuration.</para>
+	on <acronym>USB</acronym> device configuration.</para>
 
-      <para>DMA access must also be enabled for ATAPI devices, by
+      <para>DMA access must also be enabled for <acronym>ATAPI</acronym> devices, by
 	adding the following line to
 	<filename>/boot/loader.conf</filename>:</para>
 
@@ -1516,8 +1509,8 @@
       <sect3>
 	<title>Configuration</title>
 
-	<para>DVD-RAM writers can use either a SCSI or ATAPI
-	  interface.  For ATAPI devices, DMA access has to be
+	<para>DVD-RAM writers can use either a <acronym>SCSI</acronym> or <acronym>ATAPI</acronym>
+	  interface.  For <acronym>ATAPI</acronym> devices, DMA access has to be
 	  enabled by adding the following line to
 	  <filename>/boot/loader.conf</filename>:</para>
 
@@ -1613,7 +1606,7 @@
 
       <step>
 	<para>The floppy is now ready to be high-level formatted with
-	  a file system.  The floppy's file system can be either UFS
+	  a file system.  The floppy's file system can be either <acronym>UFS</acronym>
 	  or FAT, where FAT is generally a better choice for
 	  floppies.</para>
 
@@ -1638,8 +1631,8 @@
       to be used in a modern system.  Modern backup systems tend to
       use off site combined with local removable disk drive
       technologies.  Still, &os; will support any tape drive that
-      uses SCSI, such as LTO and older devices such as DAT.  There is
-      limited support for SATA and USB tape drives.</para>
+      uses <acronym>SCSI</acronym>, such as LTO and older devices such as DAT.  There is
+      limited support for <acronym>SATA</acronym> and <acronym>USB</acronym> tape drives.</para>
 
     <sect2 xml:id="tapes-sa0">
       <title>Serial Access with &man.sa.4;</title>
@@ -1777,7 +1770,7 @@
     <para>Typically, a mix of backup techniques is used.  For
       example, one could create a schedule to automate a weekly, full
       system backup that is stored off-site and to supplement this
-      backup with hourly ZFS snapshots.  In addition, one could make a
+      backup with hourly <acronym>ZFS</acronym> snapshots.  In addition, one could make a
       manual backup of individual directories or files before making
       file edits or deletions.</para>
 
@@ -1857,7 +1850,7 @@
       </example>
 
       <para>This example sets <envar>RSH</envar> in order to write the
-	the backup to a tape drive on a remote system over a
+	backup to a tape drive on a remote system over a
 	<acronym>SSH</acronym> connection:</para>
 
       <example>
@@ -1896,7 +1889,7 @@
 	same directory that is being backed up.</para>
 
       <example>
-	<title>Backing Up the Current Directory With
+	<title>Backing Up the Current Directory with
 	  <command>tar</command></title>
 
       <screen>&prompt.root; <userinput>tar czvf /tmp/mybackup.tgz . </userinput></screen>
@@ -1910,7 +1903,7 @@
 	backup to restore.</para>
 
       <example>
-	<title>Restoring Up the Current Directory With
+	<title>Restoring Up the Current Directory with
 	  <command>tar</command></title>
 
       <screen>&prompt.root; <userinput>tar xzvf /tmp/mybackup.tgz</userinput></screen>
@@ -1968,7 +1961,7 @@
 	examples would be:</para>
 
       <example>
-	<title>Backing Up the Current Directory With
+	<title>Backing Up the Current Directory with
 	  <command>pax</command></title>
 
       <screen>&prompt.root; <userinput>pax -wf /tmp/mybackup.pax .</userinput></screen>
@@ -2158,7 +2151,7 @@
       <para>While &man.mdconfig.8; is useful, it takes several
 	command lines to create a file-backed file system.  &os; also
 	comes with &man.mdmfs.8; which automatically configures a
-	&man.md.4; disk using &man.mdconfig.8;, puts a UFS file system
+	&man.md.4; disk using &man.mdconfig.8;, puts a <acronym>UFS</acronym> file system
 	on it using &man.newfs.8;, and mounts it using &man.mount.8;.
 	For example, to create and mount the same file system image as
 	above, type the following:</para>
@@ -2273,11 +2266,11 @@
       <secondary>snapshots</secondary>
     </indexterm>
 
-    <para>&os; offers a feature in conjunction with
+    <para>&os; offers a feature in conjunction with <acronym>UFS</acronym>
       <link linkend="soft-updates">Soft Updates</link>: file system
       snapshots.</para>
 
-    <para>UFS snapshots allow a user to create images of specified
+    <para><acronym>UFS</acronym> snapshots allow a user to create images of specified
       file systems, and treat them as a file.  Snapshot files must be
       created in the file system that the action is performed on, and
       a user may create no more than 20 snapshots per file system.
@@ -2285,8 +2278,8 @@
       persistent across unmount and remount operations along with
       system reboots.  When a snapshot is no longer required, it can
       be removed using &man.rm.1;.  While snapshots may be removed in
-      any order, all the used space may not be acquired because
-      another snapshot will possibly claim some of the released
+      any order, all the used space may not be reclaimed because
+      another snapshot will possibly still be using some of the
       blocks.</para>
 
     <para>The un-alterable <option>snapshot</option> file flag is set
@@ -2656,7 +2649,7 @@
       systems.  No cleartext ever touches the hard drive's
       platter.</para>
 
-    <sect2>
+    <sect2 xml:id="disks-encrypting-gbde">
       <title>Disk Encryption with
 	<application>gbde</application></title>
 
@@ -2702,14 +2695,13 @@
 	    <para>Install the new drive to the system as explained in
 	      <xref linkend="disks-adding"/>.  For the purposes
 	      of this example, a new hard drive partition has been
-	      added as <filename>/dev/ad4s1c</filename> and
-	      <filename>/dev/ad0s1*</filename>
+	      added as <filename>/dev/ada1p1</filename> and
+	      <filename>/dev/ada0*</filename>
 	      represents the existing standard &os; partitions.</para>
 
-	    <screen>&prompt.root; <userinput>ls /dev/ad*</userinput>
-/dev/ad0        /dev/ad0s1b     /dev/ad0s1e     /dev/ad4s1
-/dev/ad0s1      /dev/ad0s1c     /dev/ad0s1f     /dev/ad4s1c
-/dev/ad0s1a     /dev/ad0s1d     /dev/ad4</screen>
+	    <screen>&prompt.root; <userinput>ls /dev/ada*</userinput>
+/dev/ada0	/dev/ada0p2	/dev/ada1
+/dev/ada0p1	/dev/ada0p3	/dev/ada1p1</screen>
 	  </step>
 
 	  <step>
@@ -2737,7 +2729,7 @@
 	      initialized before it can be used.  This initialization
 	      needs to be performed only once:</para>
 
-	    <screen>&prompt.root; <userinput>gbde init /dev/ad4s1c -i -L /etc/gbde/ad4s1c.lock</userinput></screen>
+	    <screen>&prompt.root; <userinput>gbde init /dev/ada1p1 -i -L /etc/gbde/ada1p1.lock</userinput></screen>
 
 	    <para>&man.gbde.8; will open the default editor, in order
 	      to set various configuration options in a template.  For
@@ -2767,7 +2759,7 @@
 	    <para><command>gbde init</command>creates a lock file for
 	      the <application>gbde</application> partition.  In this
 	      example, it is stored as
-	      <filename>/etc/gbde/ad4s1c.lock</filename>.
+	      <filename>/etc/gbde/ada1p1.lock</filename>.
 	      <application>gbde</application> lock files must end in
 	      <quote>.lock</quote> in order to be correctly detected
 	      by the <filename>/etc/rc.d/gbde</filename> start up
@@ -2791,7 +2783,7 @@
 	    <title>Attach the Encrypted Partition to the
 	      Kernel</title>
 
-	    <screen>&prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c.lock</userinput></screen>
+	    <screen>&prompt.root; <userinput>gbde attach /dev/ada1p1 -l /etc/gbde/ada1p1.lock</userinput></screen>
 
 	    <para>This command will prompt to input the passphrase
 	      that was selected during the initialization of the
@@ -2800,10 +2792,9 @@
 	      <filename>/dev</filename> as
 	      <filename>/dev/device_name.bde</filename>:</para>
 
-	    <screen>&prompt.root; <userinput>ls /dev/ad*</userinput>
-/dev/ad0        /dev/ad0s1b     /dev/ad0s1e     /dev/ad4s1
-/dev/ad0s1      /dev/ad0s1c     /dev/ad0s1f     /dev/ad4s1c
-/dev/ad0s1a     /dev/ad0s1d     /dev/ad4        /dev/ad4s1c.bde</screen>
+	    <screen>&prompt.root; <userinput>ls /dev/ada*</userinput>
+/dev/ada0	/dev/ada0p2	/dev/ada1	/dev/ada1p1.bde
+/dev/ada0p1	/dev/ada0p3	/dev/ada1p1</screen>
 	  </step>
 
 	  <step>
@@ -2815,7 +2806,7 @@
 	      &man.newfs.8;.  This example creates a UFS2 file
 	      system with soft updates enabled.</para>
 
-	    <screen>&prompt.root; <userinput>newfs -U /dev/ad4s1c.bde</userinput></screen>
+	    <screen>&prompt.root; <userinput>newfs -U /dev/ada1p1.bde</userinput></screen>
 
 	    <note>
 	      <para>&man.newfs.8; must be performed on an attached
@@ -2836,7 +2827,7 @@
 
 	    <para>Mount the encrypted file system:</para>
 
-	    <screen>&prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput></screen>
+	    <screen>&prompt.root; <userinput>mount /dev/ada1p1.bde /private</userinput></screen>
 	  </step>
 
 	  <step>
@@ -2848,12 +2839,9 @@
 
 	    <screen>&prompt.user; <userinput>df -H</userinput>
 Filesystem        Size   Used  Avail Capacity  Mounted on
-/dev/ad0s1a      1037M    72M   883M     8%    /
-/devfs            1.0K   1.0K     0B   100%    /dev
-/dev/ad0s1f       8.1G    55K   7.5G     0%    /home
-/dev/ad0s1e      1037M   1.1M   953M     0%    /tmp
-/dev/ad0s1d       6.1G   1.9G   3.7G    35%    /usr
-/dev/ad4s1c.bde   150G   4.1K   138G     0%    /private</screen>
+/dev/ada0p2       1037M    72M   883M     8%    /
+/devfs             1.0K   1.0K     0B   100%    /dev
+/dev/ada1p1.bde    150G   4.1K   138G     0%    /private</screen>
 	  </step>
 	</procedure>
       </sect3>
@@ -2872,7 +2860,7 @@
 	    <title>Attach the <command>gbde</command> Partition to the
 	      Kernel</title>
 
-	    <screen>&prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c.lock</userinput></screen>
+	    <screen>&prompt.root; <userinput>gbde attach /dev/ada1p1 -l /etc/gbde/ada1p1.lock</userinput></screen>
 
 	    <para>This command will prompt for the passphrase that was
 	      selected during initialization of the encrypted
@@ -2887,13 +2875,13 @@
 	      the file systems must be checked for errors by running
 	      &man.fsck.8; manually before mounting:</para>
 
-	    <screen>&prompt.root; <userinput>fsck -p -t ffs /dev/ad4s1c.bde</userinput></screen>
+	    <screen>&prompt.root; <userinput>fsck -p -t ffs /dev/ada1p1.bde</userinput></screen>
 	  </step>
 
 	  <step>
 	    <title>Mount the Encrypted File System</title>
 
-	    <screen>&prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput></screen>
+	    <screen>&prompt.root; <userinput>mount /dev/ada1p1.bde /private</userinput></screen>
 
 	    <para>The encrypted file system is now available for
 	      use.</para>
@@ -2915,7 +2903,7 @@
 	    &man.rc.conf.5;:</para>
 
 	  <programlisting>gbde_autoattach_all="YES"
-gbde_devices="ad4s1c"
+gbde_devices="ada1p1"
 gbde_lockdir="/etc/gbde"</programlisting>
 
 	  <para>This requires that the
@@ -2950,12 +2938,12 @@
 	  probing for devices.  To detach the encrypted device used in
 	  the example, use the following command:</para>
 
-	<screen>&prompt.root; <userinput>gbde detach /dev/ad4s1c</userinput></screen>
+	<screen>&prompt.root; <userinput>gbde detach /dev/ada1p1</userinput></screen>
 
       </sect3>
     </sect2>
 
-    <sect2>
+    <sect2 xml:id="disks-encrypting-geli">
       <info>
 	<title>Disk Encryption with <command>geli</command></title>
 
@@ -3116,11 +3104,8 @@
 
 	  <screen>&prompt.root; <userinput>df -H</userinput>
 Filesystem     Size   Used  Avail Capacity  Mounted on
-/dev/ad0s1a    248M    89M   139M    38%    /
+/dev/ada0p2    248M    89M   139M    38%    /
 /devfs         1.0K   1.0K     0B   100%    /dev
-/dev/ad0s1f    7.7G   2.3G   4.9G    32%    /usr
-/dev/ad0s1d    989M   1.5M   909M     0%    /tmp
-/dev/ad0s1e    3.9G   1.3G   2.3G    35%    /var
 /dev/da2.eli   150G   4.1K   138G     0%    /private</screen>
 	</step>
 
@@ -3198,7 +3183,7 @@
       passwords stay in physical memory, these passwords will not be
       written to disk and be cleared after a reboot.  If &os; starts
       swapping out memory pages to free space for other applications,
-      the passwords may be written to the disk platters unencrypted.
+      the passwords may be written to disk unencrypted.
       Encrypting swap space can be a solution for this
       scenario.</para>
 
@@ -3209,7 +3194,7 @@
 
     <note>
       <para>For the remainder of this section,
-	<filename>ad0s1b</filename> will be the swap
+	<filename>ada0p3</filename> will be the swap
 	partition.</para>
     </note>
 
@@ -3218,7 +3203,7 @@
       overwrite the current swap partition with random garbage,
       execute the following command:</para>
 
-    <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/ad0s1b bs=1m</userinput></screen>
+    <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/ada0p3 bs=1m</userinput></screen>
 
     <sect2>
       <title>Swap Encryption with &man.gbde.8;</title>
@@ -3228,7 +3213,7 @@
 	line:</para>
 
       <programlisting># Device		Mountpoint	FStype	Options		Dump	Pass#
-/dev/ad0s1b.bde		none		swap	sw		0	0</programlisting>
+/dev/ada0p3.bde		none		swap	sw		0	0</programlisting>
     </sect2>
 
     <sect2>
@@ -3241,11 +3226,11 @@
 	line:</para>
 
       <programlisting># Device		Mountpoint	FStype	Options		Dump	Pass#
-/dev/ad0s1b.eli		none		swap	sw		0	0</programlisting>
+/dev/ada0p3.eli		none		swap	sw		0	0</programlisting>
 
       <para>&man.geli.8; uses the <acronym>AES</acronym> algorithm
 	with a key length of 128 bit by default.  These defaults can
-	be altered by using <literal>geli_swap_flags</literal> in
+	be altered by using <varname>geli_swap_flags</varname> in
 	<filename>/etc/rc.conf</filename>.  The following line tells
 	the <filename>encswap</filename> rc.d script to create
 	&man.geli.8; swap partitions using the Blowfish algorithm with
@@ -3270,13 +3255,13 @@
 
       <screen>&prompt.user; <userinput>swapinfo</userinput>
 Device          1K-blocks     Used    Avail Capacity
-/dev/ad0s1b.bde    542720        0   542720     0%</screen>
+/dev/ada0p3.bde    542720        0   542720     0%</screen>
 
       <para>If &man.geli.8; is being used:</para>
 
       <screen>&prompt.user; <userinput>swapinfo</userinput>
 Device          1K-blocks     Used    Avail Capacity
-/dev/ad0s1b.eli    542720        0   542720     0%</screen>
+/dev/ada0p3.eli    542720        0   542720     0%</screen>
     </sect2>
   </sect1>
 
@@ -3897,9 +3882,9 @@
 	</caution>
 
 	<tip>
-	  <para>For this example, a standard UFS file system was used.
+	  <para>For this example, a standard <acronym>UFS</acronym> file system was used.
 	    To reduce the time needed for recovery, a journal-enabled
-	    UFS or ZFS file system can be used instead.</para>
+	    <acronym>UFS</acronym> or <acronym>ZFS</acronym> file system can be used instead.</para>
 	</tip>
 
 	<para>More detailed information with additional examples can
Index: head/share/xml/trademarks.ent
===================================================================
--- head/share/xml/trademarks.ent	(revision 44203)
+++ head/share/xml/trademarks.ent	(working copy)
@@ -183,6 +183,7 @@
 <!ENTITY tm-attrib.lsilogic "<para xmlns='http://docbook.org/ns/docbook'>LSI Logic, AcceleRAID, eXtremeRAID,
   MegaRAID and Mylex are trademarks or registered trademarks of LSI
   Logic Corp.</para>">
+<!ENTITY lsilogic "<trademark xmlns='http://docbook.org/ns/docbook' class='registered'>LSI Logic Corp.</trademark>">
 <!ENTITY acceleraid "<trademark xmlns='http://docbook.org/ns/docbook'>AcceleRAID</trademark>">;
 <!ENTITY megaraid "<trademark xmlns='http://docbook.org/ns/docbook' class='registered'>MegaRAID</trademark>">
 <!ENTITY mylex "<trademark xmlns='http://docbook.org/ns/docbook' class='registered'>Mylex</trademark>">


>Release-Note:
>Audit-Trail:
>Unformatted:



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201403180011.s2I0BS6u070992>