PERFORCE change 97964 for review

Sat May 27 12:53:07 PDT 2006

http://perforce.freebsd.org/chv.cgi?CH=97964

Change 97964 by rwatson at rwatson_sesame on 2006/05/27 19:51:38

	Update audit pipe man page:
	
	- Fix title, a number of typos.
	
	- Refactor and rewrite the section on audit pipe preselection.
	  Document the revised interfaces, but also break the ioctls out
	  into sections, document why/how this is useful, that flushing
	  after a preselection change may be desirable, etc.
	
	- Document potential future fixes/features.

Affected files ...

.. //depot/projects/trustedbsd/audit3/share/man/man4/auditpipe.4#4 edit

Differences ...

==== //depot/projects/trustedbsd/audit3/share/man/man4/auditpipe.4#4 (text+ko) ====

@@ -26,7 +26,7 @@
 .\"
 .Dd May 5, 2006
 .Os
-.Vt AUDITPIPE 4
+.Dt AUDITPIPE 4
 .Sh NAME
 .Nm auditpipe
 .Nd Pseudo-device for live audit event tracking
@@ -54,29 +54,27 @@
 .Qq tee
 of the audit event stream.
 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.
+at a time; each device instance will provide independent access to all
+records.
 .Pp
-The audit pipe device provides discreet BSM audit records; if the read buffer
+The audit pipe device provides discrete 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
+asynchronous I/O using SIGIO, and polled operation via
 .Xr select 2
 and
 .Xr poll 2 .
-.Ss Preselection
-By default, the audit pipe facility configures pipes to present records
-matched by the system-wide audit trail, configured by
-.Xr auditd 8 .
-However, the preselection mechanism for audit pipes can be configured using
-alternative criteria, including pipe-local flags and naflags settings, as
-well as auid-specific selection masks.
-.Ss Ioctls
-These properties are configured using ioctls on the open audit pipe device.
-.Bl -tag -width AUDITPIPE_DELETE_PRESELECT_AUID
+.Pp
+Applications may choose to track the global audit trail, or configure local
+preselection parameters independent of the global audit trail parameters.
+.Ss Audit Pipe Queue Ioctls
+The following ioctls retrieve and set various audit pipe record queue
+properties:
+.Bl -tag -width AUDITPIPE_GET_QLIMIT_MIN
 .It AUDITPIPE_GET_QLEN
 Query the current number of records available for reading on the pipe.
 .It AUDITPIPE_GET_QLIMIT
@@ -93,6 +91,56 @@
 .It AUDITPIPE_GET_QLIMIT_MAX
 Query the highest possible maximum number of records that may be queued for
 reading on the pipe.
+.It AUDITPIPE_FLUSH
+Flush all outstanding records on the audit pipe; useful after setting initial
+preselection properties to delete records queued during the configuration
+process which may not match the interests of the user process.
+.El
+.Ss Audit Pipe Preselection Mode Ioctls
+By default, the audit pipe facility configures pipes to present records
+matched by the system-wide audit trail, configured by
+.Xr auditd 8 .
+However, the preselection mechanism for audit pipes can be configured using
+alternative criteria, including pipe-local flags and naflags settings, as
+well as auid-specific selection masks.
+This allows applications to track events not captured in the global audit
+trail, as well as limit records presented to those of specific interest to
+the application.
+.Pp
+The following ioctls configure the preselection mode on an audit pipe:
+.Bl -tag -width AUDITPIPE_GET_PRESELECT_MODE
+.It AUDITPIPE_GET_PRESELECT_MODE
+Return the current preselect mode on the audit pipe.
+The ioctl argument should be of type
+.Vt int .
+.It AUDITPIPE_SET_PRESELECT_MODE
+Set the current preselection mode on the audit pipe.
+The ioctl argument should be of type
+.Vt int .
+.El
+.Pp
+Possible preselection mode values are:
+.Bl -tag -width AUDITPIPE_PRESELECT_MODE_TRAIL
+.It AUDITPIPE_PRESELECT_MODE_TRAIL
+Use the global audit trail preselection parameters to select records for the
+audit pipe.
+.It AUDITPIPE_PRESELECT_MODE_LOCAL
+Use local audit pipe preselection; this model is similar to the global audit
+trail configuration model, consisting of global flags and naflags paramaters,
+as well as a set of per-auid masks.
+These parameters are configured using further ioctls.
+.El
+.Pp
+After changing the audit pipe preselection mode, records selected under
+earlier preselection configuration may still be in the audit pipe queue.
+The application may flush the current record queue after changing the
+configuration to remove possibly undesired records.
+.Ss Audit Pipe Local Preselection Mode Ioctls
+The following ioctls configure the preselection paramaters used when an audit
+pipe is configured for the
+.Dv AUDITPIPE_PRESELECT_MODE_LOCAL
+preselection mode.
+.Bl -tag -width AUDITPIPE_GET_PRESELECT_NAFLAGS
 .It AUDITPIPE_GET_PRESELECT_FLAGS
 Retrieve the current default preselection flags for attributable events on
 the pipe.
@@ -135,7 +183,9 @@
 .Vt struct auditpipe_preselect .
 The auid to query is specified via the
 .Va ap_auid
-field; the mask will be returned via
+field of type
+.Vt au_id_t ;
+the mask will be returned via
 .Va ap_mask
 of type
 .Vt au_mask_t .
@@ -150,26 +200,10 @@
 Delete the current preselection mask for a specific auid on the pipe.
 Once called, events associated with the specified auid will use the default
 flags mask.
+The ioctl argument should be of type
+.Vt au_id_t .
 .It AUDITPIPE_FLUSH_PRESELECT_AUID
 Delete all auid specific preselection specifications.
-.It AUDITPIPE_GET_PRESELECT_TRAIL
-Return the current value of the preselection trail flag on the audit pipe;
-this flag indicates that the system audit trail preselection masks are to be
-used in selecting which events can be read from the audit pipe.
-If the value is 1, the trail masks are used; if the value is 0, then the
-pipe preselection masks will be used.
-The ioctl argument should be of type
-.Vt int .
-.It AUDITPIPE_SET_PRESELECT_TRAIL
-Set the current value of the preselection trail flag on the audit pipe, with
-values as described for
-.Dv AUDITPIPE_GET_PRESELECT_TRAIL.
-The ioctl argument should be of type
-.Vt int .
-.It AUDITPIPE_FLUSH
-Flush all outstanding records on the audit pipe; useful after setting initial
-preselection properties to delete records queued during the configuration
-process which may not match the interests of the user process.
 .El
 .Sh EXAMPLES
 .Xr praudit 1
@@ -184,7 +218,7 @@
 .Xr audit 8 ,
 .Xr auditd 8
 .Sh AUTHORS
-The audit pipe facility was created by
+The audit pipe facility was designed and implemented by
 .An Robert Watson Aq rwatson at FreeBSD.org .
 .Pp
 The Basic Security Module (BSM) interface to audit records and audit event
@@ -201,3 +235,15 @@
 See the
 .Xr audit 4
 manual page for information on audit-related bugs and limitations.
+.Pp
+The configurable preselection mechanism mirrors the selection model present
+for the global audit trail.
+It might be desirable to provided a more flexible selection model.
+.Pp
+The per-pipe audit event queue is fifo, with drops occuring if either the
+user thread provides in sufficient for the record on the queue head, or on
+enqueue if there is insufficient room.
+It might be desirable to support partial reads of records, which would be
+more compatible with buffered I/O as implemented in system libraries, and to
+allow applications to select which records are dropped, possibly in the style
+of preselection.
