os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Bring in two new chapters:

Browse source 
Audit - not hooked up to the build, but provided for when the audit framework
becomes available in the base system.

GEOM - Incomplete, only covers striping and mirroring since that is all I
have tested.  Incomplete is better than nothing in my opinion.  This one is
hooked up to the build.
This commit is contained in:
Tom Rhodes 2005-08-06 03:22:18 +00:00
parent 982ab48b5c
commit 9e1457cbcb
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=25313
7 changed files with 941 additions and 0 deletions

2
en_US.ISO8859-1/books/handbook/Makefile
View file

@ -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

15
en_US.ISO8859-1/books/handbook/audit/Makefile Normal file
View file

@ -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"

530
en_US.ISO8859-1/books/handbook/audit/chapter.sgml Normal file
View file

@ -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>

2
en_US.ISO8859-1/books/handbook/book.sgml
View file

@ -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; ]]>

1
en_US.ISO8859-1/books/handbook/chapters.ent
View file

@ -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">

15
en_US.ISO8859-1/books/handbook/geom/Makefile Normal file
View file

@ -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"

376
en_US.ISO8859-1/books/handbook/geom/chapter.sgml Normal file
View file

@ -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:
-->