Add information on audit pipe special devices, which allow user processes

to "tee" the BSM record stream for the purposes of live monitoring,
intrusion detection, etc.  Support for audit pipes will be committed in
the near future.

Obtained from:	TrustedBSD Project

1 files changed, 35 insertions, 1 deletions

diff --git a/share/man/man4/audit.4 b/share/man/man4/audit.4
index ba438ba..5c4a6fb 100644
--- a/share/man/man4/audit.4
+++ b/share/man/man4/audit.4
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd February 2, 2006
+.Dd February 6, 2006
 .Os
 .Dt AUDIT 4
 .Sh NAME
@@ -53,6 +53,38 @@ The audit daemon,
 is responsible for configuring the kernel to perform audit, pushing
 configuration data from the various audit configuration files into the
 kernel.
+.Ss Audit Special Device
+The kernel audit facility provides a special device,
+.Pa /dev/audit ,
+which is used by
+.Xr auditd 8
+to monitor for audit events, such as requests to cycle the log, low disk
+space conditions, and requests to terminate auditing.
+This device is not intended for use by applications.
+.Ss Audit Pipe Special Devices
+The kernel audit facility also a clonable special device,
+.Pa /dev/auditpipe ,
+which allows appropriately privileged applications to gain direct access to
+the BSM audit stream without accessing audit trail files.
+As audit trail files are owned by the audit daemon until terminated, they
+are an unreliable way for applications to access live audit data; this
+special device inserts a "tee" in the audit event stream.
+This facility is appropriate for use by live monitoring tools, including
+intrusion detection.
+As the device is clonable, more than one instance of the device may be opened
+at a time; each device instance will provide access to all records.
+.Pp
+The audit pipe device provides discreet BSM audit records; if the read buffer
+passed by the application is too small to hold the next record in the
+sequence, it will be dropped.
+Unlike audit data written to the audit trail, the reliability of record
+delivery is not guaranteed.
+In particular, when an audit pipe queue fills, records will be dropped.
+Audit pipe devices are blocking by default, but support non-blocking I/O,
+asynchronous I/O using SIGIO, and support for polled operation via
+.Xr select 2
+and
+.Xr poll 2 .
 .Sh SEE ALSO
 .Xr auditreduce 1 ,
 .Xr praudit 1 ,
@@ -61,6 +93,8 @@ kernel.
 .Xr auditon 2 ,
 .Xr getaudit 2 ,
 .Xr getauid 2 ,
+.Xr poll 2 ,
+.Xr select 2 ,
 .Xr setaudit 2 ,
 .Xr setauid 2 ,
 .Xr libbsm 3 ,