7 files changed, 941 insertions, 0 deletions

diff --git a/en_US.ISO8859-1/books/handbook/Makefile b/en_US.ISO8859-1/books/handbook/Makefile
index b0dca1956f..c46632ff39 100644
--- a/en_US.ISO8859-1/books/handbook/Makefile
+++ b/en_US.ISO8859-1/books/handbook/Makefile
@@ -150,6 +150,7 @@ IMAGES_LIB+= callouts/10.png
 #
 
 # SGML content
+SRCS+= audit/chapter.sgml
 SRCS+= book.sgml
 SRCS+= colophon.sgml
 SRCS+= freebsd-glossary.sgml
@@ -163,6 +164,7 @@ SRCS+= desktop/chapter.sgml
 SRCS+= disks/chapter.sgml
 SRCS+= eresources/chapter.sgml
 SRCS+= firewalls/chapter.sgml
+SRCS+= geom/chapter.sgml
 SRCS+= install/chapter.sgml
 SRCS+= introduction/chapter.sgml
 SRCS+= kernelconfig/chapter.sgml
diff --git a/en_US.ISO8859-1/books/handbook/audit/Makefile b/en_US.ISO8859-1/books/handbook/audit/Makefile
new file mode 100644
index 0000000000..84cb9b04ee
--- /dev/null
+++ b/en_US.ISO8859-1/books/handbook/audit/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	audit/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/en_US.ISO8859-1/books/handbook/audit/chapter.sgml b/en_US.ISO8859-1/books/handbook/audit/chapter.sgml
new file mode 100644
index 0000000000..8e2db85afe
--- /dev/null
+++ b/en_US.ISO8859-1/books/handbook/audit/chapter.sgml
@@ -0,0 +1,530 @@
+<!--
+     The FreeBSD Documentation Project
+     $FreeBSD$
+-->
+
+<!--
+This version of the document assumes that the Audit system needs to be 
+installed as part of the trustedbsd/audit project. When/if audit becomes
+part of FreeBSD proper, then these sections should be removed, or at least
+reworded. The sections in question are marked with 'PROTOTYPE' labels in
+commentary.
+-->
+
+<!-- Need more documenation on praudit, audtreduce, etc.  Plus more info
+on the triggers from the kernel (log rotation, out of space, etc).
+And the /dev/audit special file if we choose to support that.  Could use
+some coverage of integrating MAC with Event auditing and perhaps discussion
+on how some companies or organizations handle auditing and auditing
+requirements. -->
+
+<chapter id="audit">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+	<firstname>Tom</firstname>
+	<surname>Rhodes</surname>
+	<contrib>Written by </contrib>
+      </author>
+    </authorgroup>
+  </chapterinfo>
+
+  <title>Kernel Event Auditing</title>
+
+  <sect1 id="audit-synopsis">
+    <title>Synopsis</title>
+
+    <indexterm><primary>AUDIT</primary></indexterm>
+    <indexterm>
+      <primary>Kernel Event Auditing</primary>
+      <see>MAC</see>
+    </indexterm>
+
+    <para>The &os;&nbsp;6.0 operating system release has included
+      support for Event Auditing based on the &posix;.1e draft and
+      the &sun; <acronym>BSM</acronym> implementation.  Event auditing
+      permits the selective logging of security-relevant system events
+      for the purposes of system analysis, system monitoring, and
+      security evaluation.</para>
+
+    <para>This chapter will focus mainly on the installation and
+      configuration of Event Auditing.  Explanation of audit policies,
+      and an example configuration will be provided for the
+      convenience of the reader.</para>
+
+    <para>After reading this chapter, you will know:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>What Event Auditing is and how it works.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to configure Event Auditing on &os; for users
+	  and processes.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Understand &unix; and &os; basics
+	  (<xref linkend="basics">).</para>
+      </listitem>
+
+      <listitem>
+	<para>Be familiar with the basics of kernel
+	  configuration/compilation
+	  (<xref linkend="kernelconfig">).</para>
+      </listitem>
+
+      <listitem>
+	<para>Have some familiarity with security and how it
+	  pertains to &os; (<xref linkend="security">).</para>
+      </listitem>
+    </itemizedlist>
+
+    <warning>
+      <para>Event auditing can generate a great deal of log file
+	data, exceeding gigabytes a week in some configurations.  An administrator
+	should read this chapter in its entirety to avoid possible
+	self inflicted <acronym>DoS</acronym> attacks due to improper
+	configuration.</para>
+    </warning>
+
+    <para>The implementation of Event Auditing in &os; is similar to
+      that of the &sun; Basic Security Module, or <acronym>BSM</acronym>
+      library.  Thus, the configuration is almost completely
+      interchangeable with &solaris; and Darwin operating systems.</para>
+  </sect1>
+
+  <sect1 id="audit-inline-glossary">
+    <title>Key Terms - Words to Know</title>
+
+    <para>Before reading this chapter, a few key terms must be
+      explained.  This is intended to clear up any confusion that
+      may occur and to avoid the abrupt introduction of new terms
+      and information.</para>
+
+    <itemizedlist>
+      <listitem>
+        <para><emphasis>class</emphasis>: A class specifies the category
+	  different actions the system are placed in.  For example,
+	  use of &man.login.1; could be placed in a class.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>event</emphasis>: An event could be considered
+	  an action taken on the system.  Creating a file would be
+	  an event.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>record</emphasis>: A record is a log or a note
+	  about a specific action.</para>
+      </listitem>
+
+      <listitem>
+	<para><emphasis>prefix</emphasis>: A prefix is considered to
+	  be the configuration element used to toggle auditing for
+	  success and failed events.</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="audit-install">
+    <title>Installing Audit Support</title>
+
+    <para>Support for Event Auditing should have been installed with
+      the normal <maketarget>installworld</maketarget> process.  An
+      administrator may confirm this by viewing the contents
+      of <filename role="directory">/etc/security.</filename>  Files
+      beginning with the word <emphasis>audit</emphasis> should be present.
+      For example, <filename>audit_event</filename>.</para>
+
+    <para>In-kernel support for the framework must also exist.  This
+      may be done by adding the following lines to the local kernel
+      configuration file:</para>
+
+    <programlisting>options	AUDIT</programlisting>
+
+    <para>Rebuild and reinstall
+      the kernel via the normal process explained in
+      <xref linkend="kernelconfig">.</para>
+
+    <para>Once completed, enable the audit daemon by adding the
+      following line to &man.rc.conf.5;:</para>
+
+    <programlisting>auditd_enable="YES"</programlisting>
+
+    <para>Functionality not provided by the default may be added
+      here with the <option>auditd_flags</option> option.</para>
+  </sect1>
+
+  <sect1 id="audit-config">
+    <title>Audit Configuration</title>
+
+    <para>By default, all configuration is done within the realm of
+      <filename role="directory">/etc/security</filename> and the
+      files contained within.  The following files must be present
+      before the audit daemon is started:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para><filename>audit_class</filename> - Contains the
+	  definitions of the audit classes.</para>
+      </listitem>
+
+      <listitem>
+	<para><filename>audit_control</filename> - Controls aspects
+	  of the audit subsystem, such as default audit classes,
+	  minimum disk space to leave on the audit log volume,
+	  etc.</para>
+      </listitem>
+
+      <listitem>
+	<para><filename>audit_event</filename> - Defines the kernel
+	  audit events.  These map, mostly, to system calls.</para>
+      </listitem>
+
+      <listitem>
+	<para><filename>audit_user</filename> - The events to audit
+	  for individual users.  A user name does not need to appear
+	  in here.</para>
+      </listitem>
+
+      <listitem>
+	<para><filename>audit_warn</filename> - A shell script
+	  used by auditd to form warning messages.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>If these files do not exist, for whatever reason, they can
+      be installed easily by issuing the following commands:</para>
+
+    <screen>&prompt.root; <userinput>cd /usr/src/contrib/bsm/etc &amp;&amp; make install</userinput></screen>
+
+    <sect2>
+      <title>Audit File Syntax</title>
+
+      <para>The configuration file syntax is rather arcane, albeit easy
+	to work with.  One thing an administrator must be leery about
+	is overriding system defaults.  This could create potential
+	openings for audit data to not be collected properly.</para>
+
+      <para>The audit subsystem will accept both the short name and
+	long name with regards to configuration syntax.  A syntax
+	map has been included below.</para>
+
+      <para>The following list contains all supported audit
+	classes:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para><option>all</option> - <literal>all</literal> - All
+	    audit flags set.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>ad</option> - <literal>administrative</literal>
+	    - Administrative actions performed on the system as a
+	    whole.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>ap</option> - <literal>application</literal> -
+	    Application defined action.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>cl</option> - <literal>file_close</literal> -
+	    Audit calls to the <function>close</function> system
+	    call.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>ex</option> - <literal>exec</literal> - Audit
+	    program or utility execution.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>fa</option> - <literal>file_attr_acc</literal>
+	    - Audit the access of object attributes such as
+	    &man.stat.1;, &man.pathconf.2; and similar events.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>fc</option> - <literal>file_creation</literal>
+	    - Audit events where a file is created as a result.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>fd</option> - <literal>file_deletion</literal>
+	    - Audit events where file deletion occurrs.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>fm</option> - <literal>file_attr_mod</literal>
+	    - Audit events where file attribute modification occurs,
+	    such as &man.chown.8;, &man.chflags.1;, &man.flock.2;,
+	    etc.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>fr</option> - <literal>file_read</literal>
+	    - Audit events in which data is read, files are opened for
+	    reading, etc.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>fw</option> - <literal>file_write</literal> -
+	    Audit events in which data is written, files are written
+	    or modified, etc.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>io</option> - <literal>ioctl</literal> - Audit
+	    use of the &man.ioctl.2; system call.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>ip</option> - <literal>ipc</literal> - Audit
+	    System V <acronym>IPC</acronym> operations.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>lo</option> - <literal>login_logout</literal> -
+	    Audit &man.login.1; and &man.logout.1; events occurring
+	    on the system.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>na</option> - <literal>non_attrib</literal> -
+	    Audit non-attributable events.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>no</option> - <literal>no_class</literal> -
+	    Null class used to disable event auditing.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>nt</option> - <literal>network</literal> -
+	    Audit events related to network actions, such as
+	    &man.connect.2; and &man.accept.2;.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>ot</option> - <literal>other</literal> -
+	    Audit miscellaneous events.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>pc</option> - <literal>process</literal> -
+	    Audit process operations, such as &man.exec.3; and
+	    &man.exit.3;.</para>
+	</listitem>
+
+	<listitem>
+	  <para><option>tf</option> - <literal>tfm</literal> -
+	    I HAVE NO CLUE!</para>
+	</listitem>
+      </itemizedlist>
+
+      <para>Following is a list of all supported audit prefixes:</para>
+
+      <itemizedlist>
+	<listitem>
+	  <para><literal>none</literal> - Audit both the success
+	    or failure of an event.  For example, just listing a
+	    class will result in the auditing of both success and
+	    failure.</para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>+</literal> - Audit successful events
+	    only.</para>
+	</listitem>
+
+	<listitem>
+	  <para><literal>-</literal> - Audit failed events
+	    only.</para>
+	</listitem>
+      </itemizedlist>
+
+      <warning>
+	<para>Using the <option>all</option> class with either the
+	  positive or negative prefix can generate a large amount
+	  of data at an extremely rapid rate.</para>
+      </warning>
+
+      <para>Extra prefixes used to modify the default configuration
+	values:</para>
+<!-- XXX: Perhaps a variable listing here. -->
+      <itemizedlist>
+	<listitem>
+	  <para>^- - Disable auditing of failed events.</para>
+	</listitem>
+
+	<listitem>
+	  <para>^+ - Enable auditing of successful events.</para>
+	</listitem>
+
+	<listitem>
+	  <para>^ - Disable auditing of both successful and failed
+	    events.</para>
+	</listitem>
+      </itemizedlist>
+    </sect2>
+
+    <sect2>
+      <title>Configuration Files</title>
+
+      <para>Configuration is set in only two files, the first being
+        <filename>audit_control</filename> and
+	<filename>audit_user</filename> being the second.  The first
+	is system-wide, controlling every aspect of event auditing
+	in the system.  The latter may be used for fine grained user
+	auditing.</para>
+
+      <sect3 id="audit-auditcontrol">
+        <title>The <filename>audit_control</filename> File</title>
+
+	<para>The <filename>audit_control</filename> contains some basic
+	  defaults that the administrator may wish to modify.  Perhaps
+	  even set some new ones.  Viewing the contents of this file,
+	  we see the following:</para>
+
+	<programlisting>dir:/var/audit
+flags:lo,ad,-all,^-fa,^-fc,^-cl
+minfree:20
+naflags:lo</programlisting>
+
+	<para>The <option>dir</option> is used to set the default
+	  directory where audit logs are stored.</para>
+
+	<para>The <option>flags</option> is used to set the system-wide
+	  defaults.  The current setting,
+	  <option>lo,ad,-all,^-fa,^-fc,^-cl</option> audits all system
+	  &man.login.1; and &man.logout.1; actions, all administrator
+	  actions, all failed events in the system, and finally disable
+	  auditing of failed attempts for <option>fa</option>,
+	  <option>fc</option>, and <option>cl</option>.  Even though
+	  the <option>-all</option> turned on the auditing of all
+	  failed attempts, the <option>^-</option> prefix will override
+	  that for the latter options.</para>
+
+	<para>Notice that the previous paragraph shows the file is
+	  read from left to right.  As such, values further on the
+	  right side may override a previous value specified to
+	  its left.</para>
+
+	<para>The <option>minfree</option> option defines the minimum
+	  percentage of free space for audit file systems.  This
+	  relates to the file system where audit logs are stored.
+	  For example, if the <option>dir</option> specifies
+	  <filename role="directory">/var/audit</filename> and
+	  <option>minfree</option> is set to twenty (20), warning
+	  messages will be generated when the
+	  <filename role="directory">/var</filename> file system grows
+	  to eighty (80) percent full.</para>
+
+	<para>The <option>naflags</option> option specifies audit
+	  flags to be considered non attributable; i.e.: classes of
+	  events which cannot be attributed to a specific user
+	  on the system.  This can be overridden with the
+	  <filename>audit_user</filename> configuration file.</para>
+      </sect3>
+
+      <sect3 id="audit-audituser">
+	<title>The <filename>audit_user</filename> File</title>
+
+	<para>The <filename>audit_user</filename> permits the
+	  administrator to map audit specific events to directly
+	  to users.  This adds a finer-grained control mechanism
+	  for all system users.</para>
+
+	<para>The following is the defaults currently placed in
+	  the <filename>audit_user</filename> file:</para>
+
+	<programlisting>root:lo:no
+audit:fc:no</programlisting>
+
+	<para>Notice how the default is to audit all cases of
+	  <command>login</command>/<command>logout</command>
+	  and disable auditing of all other actions for
+	  <username>root</username>.  This configuration
+	  also audits all file creation and disables all
+	  other auditing for the <username>audit</username>
+	  user.  While event auditing does not require a special
+	  user exist, some configurations, specifically environments
+	  making use of <acronym>MAC</acronym> may require it.</para>
+      </sect3>
+    </sect2>
+  </sect1>
+
+  <sect1 id="audit-administration">
+    <title>Event Audit Administration</title>
+
+    <para>Events from the <command>auditd</command> daemon cannot
+      be altered or read in plain text.  Data is stored and accessed
+      in a method similar to that of &man.ktrace.1; and &man.kdump.1,
+      that is, they may only be viewed by dumping them using the
+      <command>praudit</command> or <command>auditreduce</command>
+      utilities.</para>
+
+    <para>There are two utilities because of different requirements.
+      For example, the <command>praudit</command> will dump the entire
+      contents of a specified audit log in plain text.  To dump an
+      audit log in its entirety, use:</para>
+
+    <screen>&prompt.root; <userinput>praudit /var/audit/AUDITFILE</userinput></screen>
+
+    <para>Where <replaceable>AUDITFILE</replaceable> is the audit log
+      of viewing choice.  Since audit logs may contain enormous
+      amounts of data, an administrator may prefer to select records
+      for specific users.  This is made possible with the following
+      command, where <username>trhodes</username> is the user of
+      choice:</para>
+
+    <screen>&prompt.root; <userinput>auditreduce -e trhodes /var/audit/AUDITFILE</userinput></screen>
+
+    <para>This will select all audit records produced by the user
+      <username>trhodes</username> stored in the
+      <replaceable>AUDITFILE</replaceable> file.
+
+    <para>There are several other options available for reading audit
+      records, see the aforementioned command's manual pages for
+      a more in depth explination.</para>
+
+    <sect2>
+      <title>Rotating Audit Log Files</title>
+
+      <para>Manually rotating audit log files will cause great
+	havoc within the system.  Therefore, adding a line to
+	&man.newsyslog.conf.5; will provide no usefulness.  So how
+	are the logs to be rotated?  Sending the appropriate flag
+	to the <command>audit</command> utility will shut down
+	event auditing and safely rotate.  The following command
+	should handle everything for an administrator:</para>
+
+      <screen>&prompt.root; <userinput>audit -n</userinput></screen>
+
+      <warning>
+	<para>If the <command>auditd</command> daemon is not currently
+	  running, the previous command will fail and an error message
+	  will be produced.</para>
+      </warning>
+
+      <para>Adding the following line to
+	<filename>/etc/crontab</filename> will force the rotation
+	every twelve hours from &man.cron.8;:</para>
+
+      <programlisting>*     */12       *       *       *       root    /usr/sbin/audit -n</programlisting>
+
+      <para>Remember to reinstall the <filename>crontab</filename>
+        file.  Otherwise the rotation will never occur.</para>
+    </sect2>
+  </sect1>
+</chapter>
diff --git a/en_US.ISO8859-1/books/handbook/book.sgml b/en_US.ISO8859-1/books/handbook/book.sgml
index 069a8afe5d..407d0425fb 100644
--- a/en_US.ISO8859-1/books/handbook/book.sgml
+++ b/en_US.ISO8859-1/books/handbook/book.sgml
@@ -25,6 +25,7 @@
 <!ENTITY % chap.security "IGNORE">
 <!ENTITY % chap.printing "IGNORE">
 <!ENTITY % chap.disks "IGNORE">
+<!ENTITY % chap.geom "IGNORE">
 <!ENTITY % chap.vinum "IGNORE">
 <!ENTITY % chap.x11 "IGNORE">
 <!ENTITY % chap.l10n "IGNORE">
@@ -259,6 +260,7 @@
     <![ %chap.security;                 [ &chap.security;             ]]>
     <![ %chap.mac;			[ &chap.mac;		      ]]>
     <![ %chap.disks;                    [ &chap.disks;                ]]>
+    <![ %chap.geom;			[ &chap.geom;		      ]]>
     <![ %chap.vinum;                    [ &chap.vinum;                ]]>
     <![ %chap.l10n;                     [ &chap.l10n;                 ]]>
     <![ %chap.cutting-edge;             [ &chap.cutting-edge;         ]]>
diff --git a/en_US.ISO8859-1/books/handbook/chapters.ent b/en_US.ISO8859-1/books/handbook/chapters.ent
index 6585365fd0..9d94f16bb8 100644
--- a/en_US.ISO8859-1/books/handbook/chapters.ent
+++ b/en_US.ISO8859-1/books/handbook/chapters.ent
@@ -32,6 +32,7 @@
 <!ENTITY chap.security			SYSTEM "security/chapter.sgml">
 <!ENTITY chap.mac			SYSTEM "mac/chapter.sgml">
 <!ENTITY chap.disks			SYSTEM "disks/chapter.sgml">
+<!ENTITY chap.geom			SYSTEM "geom/chapter.sgml">
 <!ENTITY chap.vinum			SYSTEM "vinum/chapter.sgml">
 <!ENTITY chap.l10n			SYSTEM "l10n/chapter.sgml">
 <!ENTITY chap.cutting-edge		SYSTEM "cutting-edge/chapter.sgml">
diff --git a/en_US.ISO8859-1/books/handbook/geom/Makefile b/en_US.ISO8859-1/books/handbook/geom/Makefile
new file mode 100644
index 0000000000..59e5759cdc
--- /dev/null
+++ b/en_US.ISO8859-1/books/handbook/geom/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= 	geom/chapter.sgml
+
+VPATH=		..
+
+MASTERDOC=	${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= 	${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/en_US.ISO8859-1/books/handbook/geom/chapter.sgml b/en_US.ISO8859-1/books/handbook/geom/chapter.sgml
new file mode 100644
index 0000000000..202a2ff7e9
--- /dev/null
+++ b/en_US.ISO8859-1/books/handbook/geom/chapter.sgml
@@ -0,0 +1,376 @@
+<!--
+     The FreeBSD Documentation Project
+     $FreeBSD$
+
+-->
+
+<chapter id="GEOM">
+  <chapterinfo>
+    <authorgroup>
+      <author>
+	<firstname>Tom</firstname>
+	<surname>Rhodes</surname>
+	<contrib>Written by </contrib>
+      </author>
+    </authorgroup>
+  </chapterinfo>
+
+  <title>GEOM: Modular Disk Transformation Framework</title>
+
+  <sect1 id="GEOM-synopsis">
+    <title>Synopsis</title>
+
+    <indexterm>
+      <primary>GEOM</primary>
+    </indexterm>
+    <indexterm>
+      <primary>GEOM Disk Framework</primary>
+      <see>GEOM</see>
+    </indexterm>
+
+    <para>This chapter covers the use of disks under the new GEOM
+      framework in &os;.  This includes the major
+      <acronym>RAID</acronym> 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>
+
+    <para>After reading this chapter, you will know:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>What type of <acronym>RAID</acronym> support is available
+	  through GEOM.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to use the base base utilities to configure, maintain
+	  and manipulate the various <acronym>RAID</acronym>
+	  levels.</para>
+      </listitem>
+
+      <listitem>
+        <para>How to mirror, stripe, encrypt, and remotely connect disk
+	  devices through GEOM.</para>
+      </listitem>
+
+      <listitem>
+	<para>How to troubleshoot disks attached to the GEOM
+	  framework.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>Before reading this chapter, you should:</para>
+
+    <itemizedlist>
+      <listitem>
+	<para>Understand how &os; treats disk devices
+	  (<xref linkend="disks">).</para>
+      <listitem>
+	<para>Know how to configure and install a new &os; kernel
+	  (<xref linkend="kernelconfig">).</para>
+      </listitem>
+    </itemizedlist>
+  </sect1>
+
+  <sect1 id="GEOM-intro">
+    <title>GEOM Introduction</title>
+
+    <para>GEOM permits access and control to classes &mdash; Master Boot
+      Records, <acronym>BSD</acronym> labels, etc &mdash; through the
+      use of providers, or the special files in
+      <filename role="directory">/dev</filename>.  Supporting various
+      software <acronym>RAID</acronym> configurations, GEOM will
+      transparently provide access to the operating system and
+      operating system utilities.</para>
+  </sect1>
+
+  <sect1 id="GEOM-striping">
+    <title>RAID0 - Striping</title>
+
+    <indexterm>
+      <primary>GEOM</primary>
+    </indexterm>
+    <indexterm>
+      <primary>Stripping</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 supporting all variants of disks,
+      <acronym>SCSI</acronym>, <acronym>SATA</acronym>,
+      and <acronym>ATA</acronym>.  The GEOM disk subsystem provides
+      software support for <acronym>RAID</acronym>1, also known as
+      disk striping.</para>
+
+    <para>Some cases have this volume, comprised of several disks, as a
+      separate file system for backups, data storage for users;
+      however, in other cases still, this volume may hold the root, or
+      <filename role="directory">/</filename> partition and the system
+      will boot from it.  Both will be described herein.</para>
+
+    <para>To stripe several <acronym>ATA</acronym> disks, of the same
+      size of course, load the <filename>geom_stripe</filename>
+      module:</para>
+
+    <screen>&prompt.root; <userinput>kldload geom_stripe.ko</userinput></screen>
+
+    <para>The module should now be loaded and visible from the output of
+      <command>kldstat</command>.  Now to combine the disks.  Ensure
+      that a mount point exists, if this volume will become a root
+      partition then temporarily use
+      <filename role="directory">/mnt</filename>.  Otherwise, for the
+      purpose of our examples, this volume will reside at the
+      <filename role="directory">/home</filename> mount point.  This
+      process may be complicated if users already exist on the system.
+      If so, assume the volume will reside on
+      <filename role="directory">/data</filename>.</para>
+
+    <para>Begin by selecting the disks which will be striped.  Our
+      scenario has two unused, unpartitioned <acronym>ATA</acronym>
+      disks: <filename>/dev/ad2</filename> and
+      <filename>/dev/ad3</filename>.  The module has been loaded and
+      our disks selected, we will now create the stripe device:</para>
+
+    <screen>&prompt.root; <userinput>gstripe label -v st0 /dev/ad2 /dev/ad3</userinput></screen>
+
+    <para>A message should be returned explaining that meta data has
+      been stored on the devices.  The file system must now be created
+      on the device.  If this volume is to be used for system
+      initialization, the following command must be issued before the
+      file system is created:</para>
+
+    <screen>&prompt.root; <userinput>fdisk -vBI /dev/stripe/st0</userinput></screen>
+
+    <para>Create a partition table on the new volume:</para>
+
+    <screen>&prompt.root; <userinput>bsdlabel -wB /dev/stripe/st0</userinput></screen>
+
+    <para>This process should have created two other devices in the
+      <filename role="directory">/dev/stripe</filename> directory in
+      addition to the <filename>st0</filename> device.  Those include
+      <filename>st0a</filename> and <filename>st0c</filename>.  Next a
+      file system must be created on the device using
+      <command>newfs</command>:</para>
+
+    <screen>&prompt.root; <userinput>newfs -U /dev/stripe/st0a</userinput></screen>
+
+    <para>Many numbers will glide across the screen, and after a few
+      seconds, the process will be complete.  The volume has been
+      created and is ready to be hung from its <command>mount</command>
+      point:</para>
+
+    <screen>&prompt.root; <userinput>mount /dev/stripe/st0a /home</userinput></screen>
+
+    <para>Place the volume information in
+      <filename>/etc/fstab</filename> file:</para>
+
+    <screen>&prompt.root; <userinput>echo "/dev/stripe/st0a /home ufs rw 2 2" \</userinput>
+    <userinput>&gt;&gt; /etc/fstab</userinput></screen>
+
+    <para>And load the module during system initialization:</para>
+
+    <screen>&prompt.root; <userinput>echo 'geom_stripe_load="YES" &gt;&gt; /boot/loader.conf</userinput></screen>
+
+    <para>From here on, all users will have their data stored on the
+      striped volume comprised of the disks concatenated in the
+      beginning.</para>
+  </sect1>
+
+  <sect1 id="GEOM-mirror">
+    <title>RAID1 - Mirroring</title>
+
+    <indexterm>
+      <primary>GEOM</primary>
+    </indexterm>
+    <indexterm>
+      <primary>Disk Mirroring</primary>
+    </indexterm>
+
+    <para>Mirroring is a technology used by many corporations and home
+      users to back up data without interruption.  When a mirror exists,
+      it simply means that diskB replicates diskA.  Or, perhaps diskC+D
+      replicates diskA+B.  Regardless of the disk configuration, the
+      important aspect isthat information on one disk or partition is
+      being replicated.  Later, that information could be more easily
+      restored, backed up without causing service or access
+      interruption, and even be physically stored in a data
+      safe.</para>
+
+    <para>To begin, ensure the system has two disk drives of equal size,
+      this exorcise assumes they are direct access (&man.da.4;)
+      <acronym>SCSI</acronym> disks.</para>
+
+    <para>Begin by installing &os; on the first disk with only two
+      partitions.  One should be a swap partition, double the
+      <acronym>RAM</acronym> size and all remaining space devoted to
+      the root (<filename role="directory">/</filename> file system.
+      It is possible to have separate partitions for other mount points;
+      however, this will increase the difficulty level ten fold due to
+      manual alteration of the &man.bsdlabel.8; and &man.fdisk.8;
+      settings.</para>
+
+    <para>Reboot and wait for the system to fully initialize.  Once this
+      process has completed, log in as the <username>root</username>
+      user.</para>
+
+    <para>Create the <filename>/dev/mirror/gm</filename> device and link
+      it with <filename>/dev/da1</filename>:</para>
+
+    <screen>&prompt.root; <userinput>gmirror label -vnb round-robin gm0 /dev/da1</userinput></screen>
+
+    <note>
+      <para>This command should have created the
+	<filename>gm0</filename>, <filename>gm0s1</filename>,
+	<filename>gm0s1a</filename>, and <filename>gm0s1c</filename>
+	device nodes under the
+	<filename role="directory">/dev/mirror</filename>
+	directory.</para>
+    </note>
+
+    <para>Initialize GEOM, this will load the
+      <filename>/boot/kernel/geom_mirror.ko</filename> kernel
+      module:</para>
+
+    <screen>&prompt.root; <userinput>geom load</userinput></screen>
+
+    <para>Install generic <command>fdisk</command> label and boot code
+      to newly created <filename>gm0</filename> device:</para>
+
+    <screen>&prompt.root; <userinput>fdisk -vBI /dev/mirror/gm0</userinput></screen>
+
+    <para>Now install generic <command>bsdlabel</command>
+      information:</para>
+
+    <screen>&prompt.root; <userinput>bsdlabel -wB /dev/mirror/gm0s1</userinput></screen>
+
+    <note>
+      <para>If multiple slices and partitions exist, the flags for the
+	previous two commands will require alteration.  They must match
+	the slice and partition size of the other disk.</para>
+    </note>
+
+    <para>Use the &man.newfs.8; utility to create a default file
+      system on the <filename>gm0s1a</filename> device node:</para>
+
+    <screen>&prompt.root; <userinput>newfs -U /dev/mirror/gm0s1a</userinput></screen>
+
+    <para>This should have caused for the system to spit out some
+      information and a bunch of numbers.  This is good, examine the
+      screen for any error messages and mount the device to the
+      <filename role="directory">/mnt</filename> mount point:</para>
+
+    <screen>&prompt.root <userinput>mount /dev/mirror/gm0s1a /mnt</userinput></screen>
+
+    <para>Now move all data from the boot disk over to this new file
+      system.  This example uses the &man.dump.8; and &man.restore.8;
+      commands; however, &man.dd.1; would also work with this scenario.
+      We skip using &man.tar.1; because it will not copy over the boot
+      code.  Thus, failure would be guarenteed.</para>
+
+    <screen>&prompt.root; <userinput>dump -L -0 -f- / |(cd /mnt && restore -r -v -f-)</userinput></screen>
+
+    <para>This must be done for each file system.  Simply place the
+      appropriate file system in correct location when running the
+      aforementioned command.</para>
+
+    <para>Now edit the replicated <filename>/mnt/etc/fstab</filename>
+      file and remove or comment out the swap file.  Change the other
+      file system information to use the new disk.  See the following
+      example:</para>
+
+    <programlisting># Device                Mountpoint      FStype  Options         Dump    Pass#
+#/dev/da0s2b             none            swap    sw              0       0
+/dev/mirror/gm0sa1       /               ufs     rw              1       1</programlisting>
+
+    <para>Now create a <filename>boot.conf</filename> file on both the
+      current and new root partitions.  This file will
+      <quote>help</quote> the system <acronym>BIOS</acronym>
+      boot the correct drive:</para>
+
+    <screen>&prompt.root; <userinput>echo "1:da(1,a)/boot/loader" &gt; /boot.config</userinput></screen>
+
+    <screen>&prompt.root; <userinput>echo "1:da(1,a)/boot/loader" &gt; /mnt/boot.config</userinput></screen>
+
+    <note>
+      <para>We have placed it on both root partitions to ensure proper
+        boot up.  If for some reason the system cannot read from the
+	new root partition, a failsafe is available.</para>
+    </note>
+
+    <para>Now add the following line to
+      <filename>/boot/loader.conf:</filename></para>
+
+    <screen>&prompt.root; <userinput>echo 'geom_mirror_load="YES"' &gt;&gt; /boot/loader.conf</userinput></screen>
+
+    <para>This will instruct &man.loader.8; utility to load the
+      <filename>geom_mirror.ko</filename> during system
+      initialization.</para>
+
+    <para>Reboot the system:</para>
+
+    <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
+
+    <para>If all has gone well, the system should have booted from the
+      <filename>gm0s1a</filename> device and a <command>login</command>
+      prompt should be waiting.  If something went wrong, see review
+      the forthcoming troubleshooting section.  Now add the
+      <filename>da0</filename> disk to <filename>gm0</filename>
+      device:</para>
+
+    <screen>&prompt.root; <userinput>gmirror configure -a gm0</userinput>
+    <userinput>gmirror insert gm0 /dev/da0</userinput></screen>
+
+    <para>The <option>-a</option> flag tells &man.gmirror.8; to use
+      automatic synchronization, i.e.: mirror the disk writes
+      automatically.  The manual page explains how to rebuild and
+      replace disks, although it uses <filename>data</filename>
+      in place of <filename>gm0</filename>.</para>
+
+    <sect2>
+      <title>Troubleshooting</title>
+
+      <sect3>
+	<title>System refuses to boot</title>
+
+	<para>If the system boots up to a prompt similar to:</para>
+
+	<programlisting>ffs_mountroot: can't find rootvp
+Root mount failed: 6
+mountroot></programlisting>
+
+	<para>Reboot the machine using the power or reset button.  At
+	  the boot menu, select option six (6).  This will drop the
+	  system to a &man.loader.8; prompt.  Load the kernel module
+	  manually:</para>
+
+	<screen>OK? <userinput>load geom_mirror.ko</userinput>
+	OK? <userinput>boot</userinput></screen>
+
+	<para>If this works then for whatever reason the module was not
+	  being loaded properly.  Place:</para>
+
+	<programlisting>options	GEOM_MIRROR</programlisting>
+
+	<para>In the kernel configuration file, rebuild and reinstall.
+	  That should remedy this issue.</para>
+      </sect3>
+    </sect2>
+  </sect1>
+</chapter>
+
+<!--
+     Local Variables:
+     mode: sgml
+     sgml-declaration: "../chapter.decl"
+     sgml-indent-data: t
+     sgml-omittag: nil
+     sgml-always-quote-attributes: t
+     sgml-parent-document: ("../book.sgml" "part" "chapter")
+     End:
+-->