Index: chapter.sgml
===================================================================
RCS file: /data/fbsd-cvs/ncvs/doc/en_US.ISO8859-1/books/handbook/audit/chapter.sgml,v
retrieving revision 1.7
diff -u -r1.7 chapter.sgml
--- chapter.sgml	4 Feb 2006 07:57:25 -0000	1.7
+++ chapter.sgml	4 Feb 2006 20:43:09 -0000
@@ -21,23 +21,23 @@
     </authorgroup>
   </chapterinfo>
 
-  <title>Kernel Event Auditing</title>
+  <title>Security Event Auditing</title>
 
   <sect1 id="audit-synopsis">
     <title>Synopsis</title>
 
     <indexterm><primary>AUDIT</primary></indexterm>
     <indexterm>
-      <primary>Kernel Event Auditing</primary>
+      <primary>Security Event Auditing</primary>
       <see>MAC</see>
     </indexterm>
 
     <para>The &os;&nbsp;7-CURRENT development branch includes
       support for Event Auditing based on the &posix;.1e draft and
-      the &sun; <acronym>BSM</acronym> implementation.  Event auditing
+      the &sun;'s published <acronym>BSM</acronym> API and file format.  Event auditing
       permits the selective logging of security-relevant system events
-      for the purposes of system analysis, system monitoring, and
-      security evaluation.  After some settling time in &os;&nbsp;7-CURRENT,
+      for the purposes of post-mortem analysis, system monitoring, and
+      intrusion detection.  After some settling time in &os;&nbsp;7-CURRENT,
       this support will be merged to &os;&nbsp;6-STABLE and appear
       in subsequent releases.</para>
 
@@ -96,7 +96,7 @@
     <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>
+      interchangeable with &solaris; and Mac OS X/Darwin operating systems.</para>
   </sect1>
 
   <sect1 id="audit-inline-glossary">
@@ -109,23 +109,48 @@
 
     <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>
+	<para><emphasis>event</emphasis>: An auditable event is
+	  an event that can be logged using the audit subsystem.  The
+	  administrator can configure which events will be audited.
+	  Examples of security-relevant events include the creation of
+	  a file, the building of a network connection, or the logging
+	  in of a user.  Events are either <quote>attributable</quote>,
+	  meaning that they can be traced back to a user
+	  authentication, or <quote>non-attributable</quote>.  Examples
+	  of non-attributable events are any events that occur before
+	  authentication has succeeded in the login process, such as
+	  failed authentication attempts.</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>
+        <para><emphasis>class</emphasis>: Events may be assigned to
+	  one or more classes, usually based on the general category
+	  of the events, such as <quote>file creation</quote>,
+	  <quote>file access</quote>, or <quote>network</quote>.  Login
+	  and logout events are assigned to the <literal>lo</literal>
+	  class.  The use of classes allows the administrator to
+	  specify high level auditing rules without having to specify
+	  whether each individual auditable operation will be logged.</para>
       </listitem>
 
       <listitem>
-	<para><emphasis>record</emphasis>: A record is a log or a note
-	  about a specific action.</para>
+	<para><emphasis>record</emphasis>: A record is a log entry
+	  describing a security event.  Records typically have a
+	  record event type, information on the subject (user) associated
+	  with the event, time information, information on any objects,
+	  such as files, and information on whether the event corresponded
+	  to a successful operation.</para>
       </listitem>
 
       <listitem>
+	<para><emphasis>trail</emphasis>: An audit trail, or log file,
+	  consists of a series of audit records describing security
+	  events.  Typically, trails are in roughly chronological
+	  order with respect to the time events completed.  Only
+	  authorized processes are allowed to commit records to the
+	  audit trail.</para>
+
+      <listitem>
 	<para><emphasis>prefix</emphasis>: A prefix is considered to
 	  be the configuration element used to toggle auditing for
 	  success and failed events.</para>
@@ -136,7 +161,7 @@
   <sect1 id="audit-install">
     <title>Installing Audit Support</title>
 
-    <para>Support for Event Auditing should have been installed with
+    <para>Support for Event Auditing is 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
@@ -190,21 +215,19 @@
 
       <listitem>
 	<para><filename>audit_user</filename> - The events to audit
-	  for individual users.  A user name does not need to appear
-	  in here.</para>
+	  for individual users.  Users not appearing here will be
+	  subject to the default configuration in the control
+	  configuration file.</para>
       </listitem>
 
       <listitem>
 	<para><filename>audit_warn</filename> - A shell script
-	  used by auditd to form warning messages.</para>
+	  used by auditd to generate warning messages in
+	  exceptional situations, such as when space for audit
+	  records is running low.</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>
 
@@ -392,15 +415,21 @@
 	  we see the following:</para>
 
 	<programlisting>dir:/var/audit
-flags:lo,ad,-all,^-fa,^-fc,^-cl
+flags:lo
 minfree:20
 naflags:lo</programlisting>
 
 	<para>The <option>dir</option> option is used to set the default
-	  directory where audit logs are stored.</para>
+	  directory where audit logs are stored.  Audit is frequently
+	  configured so that audit logs are stored on a dedicated file
+	  system, so as to prevent interference between the audit
+	  subsystem and other subsystems when file systems become full.
+	  </para>
 
 	<para>The <option>flags</option> option is used to set the
-	  system-wide defaults.  The current setting,
+	  system-wide defaults.  The current setting, <option>lo</option>
+	  configures the auditing of all &man.login.1; and &man.logout.1;
+	  actions.  A more complex example,
 	  <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 disables
@@ -426,19 +455,17 @@
 	  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>
+	  classes to be audited for non-attributed events &mdash;
+	  that is, events for which there is no authenticated user.
+	  </para>
       </sect3>
 
       <sect3 id="audit-audituser">
 	<title>The <filename>audit_user</filename> File</title>
 
 	<para>The <filename>audit_user</filename> file permits the
-	  administrator to map audit specific events directly
-	  to users.  This adds a finer-grained control mechanism
-	  for all system users.</para>
+	  administrator to determine which classes of audit events
+	  should be logged for which system users.</para>
 
 	<para>The following is the defaults currently placed in
 	  the <filename>audit_user</filename> file:</para>
@@ -462,15 +489,16 @@
   <sect1 id="audit-administration">
     <title>Event Audit Administration</title>
 
-    <para>Events from the <command>auditd</command> daemon cannot
+    <para>Events written by the kernel audit subsystem 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>
+      <command>praudit</command>; audit trails may be reduced using
+      the <command>auditreduce</command> command, which selects records
+      from an audit trail based on properties of interest, such as the
+      user, time of the event, and type of operation.</para>
 
-    <para>There are two utilities because of different requirements.
-      For example, the <command>praudit</command> utility will dump the
+    <para>For example, the <command>praudit</command> utility will dump the
       entire contents of a specified audit log in plain text.  To dump an
       audit log in its entirety, use:</para>
 
@@ -483,7 +511,7 @@
       command, where <username>trhodes</username> is the user of
       choice:</para>
 
-    <screen>&prompt.root; <userinput>auditreduce -e trhodes /var/audit/AUDITFILE</userinput></screen>
+    <screen>&prompt.root; <userinput>auditreduce -e trhodes /var/audit/AUDITFILE | praudit</userinput></screen>
 
     <para>This will select all audit records produced by the user
       <username>trhodes</username> stored in the
@@ -496,13 +524,17 @@
     <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>
+      <para>Because of log reliability requirements, audit trails
+	are written to only by the kernel, and managed only by
+	<command>auditd</command>.  Administrators should not
+	attempt to use &man.newsyslog.conf.5& or other tools to
+	directly rotate audit logs.  Instead, the <command>audit</command>
+	management tool should be used to shut down auditing,
+	reconfigure the audit system, and perform log rotation.
+	The following command causes the audit daemon to create a
+	new audit log and signal the kernel to switch to using the
+	new log.  The old log will be terminated and renamed, at
+	which point it may then be manipulated by the administrator.</para>
 
       <screen>&prompt.root; <userinput>audit -n</userinput></screen>
 
