Add a section on glabel(8), provide a quick example.

Reviewed by:	brueffer

en_US.ISO8859-1/books/handbook/geom/chapter.sgml

@@ -447,6 +447,132 @@ OK? <userinput>boot</userinput></screen>
       unmounted with the &man.umount.8; command, similar to any other
       disk device.</para>
   </sect1>
+
+  <sect1 id="geom-glabel">
+    <title>Labeling Disk Devices</title>
+
+    <indexterm>
+      <primary>GEOM</primary>
+    </indexterm>
+    <indexterm>
+      <primary>Disk Labels</primary>
+    </indexterm>
+
+    <para>During system initialization, the &os; kernel will create
+      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
+      <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>
+
+    <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
+      <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
+      <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 reboots.
+      By using this label as a device, the file system may always be
+      mounted regardless of what device node it is accessed
+      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>
+    </note>
+
+    <sect2>
+      <title>Label Types and Examples</title>
+
+      <para>There are two types of labels, a generic label and a
+	file system label.  The difference between the labels is
+	the auto detection associated with permanent labels, and the
+	fact that this type of label will be persistent across reboots.
+	These labels are given a special directory in
+	<filename role="directory">/dev</filename>, which will be named
+	based on their file system type.  For example,
+	<acronym>UFS</acronym>2 file system labels will be created in
+	the <filename role="directory">/dev/ufs2</filename>
+	directory.</para>
+
+      <para>A generic label will go away with the next reboot. These
+	labels will be created in the
+	<filename role="directory">/dev/label</filename> directory and
+	are perfect for experimentation.</para>
+
+<!-- XXXTR: How do you create a file system label without running newfs
+            or when there is no newfs (e.g.: cd9660)? -->
+
+      <para>Permanent labels may be placed on the file system using the
+	<command>tunefs</command> or <command>newfs</command>
+	utilities.  To create a permanent label for a
+	<acronym>UFS</acronym>2 file system without destroying any
+	data, issue the following commands:</para>
+
+      <screen>&prompt.root; <userinput>tunefs -L home /dev/da3</userinput></screen>
+
+      <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>
+      </warning>
+
+      <para>A label should now exist in
+	<filename role="directory">/dev/ufs2</filename> which may be
+	added to <filename>/etc/fstab</filename>:</para>
+
+      <programlisting>/dev/ufs2/home		/home            ufs     rw              2      2</programlisting>
+
+      <note>
+	<para>The file system must not be mounted while attempting
+	  to run <command>tunefs</command>.</para>
+      </note>
+
+      <para>Now the file system may be mounted like normal:</para>
+
+      <screen>&prompt.root; <userinput>mount /home</userinput></screen>
+
+      <para>The following command can be used to destroy the
+	label:</para>
+
+      <screen>&prompt.root; <userinput>glabel destroy home</userinput></screen>
+
+      <para>From this point on, so long as the
+	<filename>geom_label.ko</filename> kernel module is loaded at
+	boot with <filename>/boot/loader.conf</filename> or the
+	<devicename>GEOM_LABEL</devicename> kernel option is present,
+	the device node may change without any ill effect on the
+	system.</para>
+
+      <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>
+    </sect2>
+  </sect1>
+
 <!--
   <sect1 id="geom-gjournal">
     <title>UFS Journaling Through GEOM</title>
@@ -455,7 +581,7 @@ OK? <userinput>boot</userinput></screen>
       <primary>GEOM</primary>
     </indexterm>
     <indexterm>
-      <primary>Disk Mirroring</primary>
+      <primary>Journaling</primary>
     </indexterm>
 
     <para>With the release of &os;&nbsp;7.0, the long awaited feature