Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
AUDITPIPE(4)	       FreeBSD Kernel Interfaces Manual		  AUDITPIPE(4)

NAME
     auditpipe -- pseudo-device	for live audit event tracking

SYNOPSIS
     options AUDIT

DESCRIPTION
     While audit trail files generated with audit(4) and maintained by
     auditd(8) provide a reliable long-term store for audit log	information,
     current log files are owned by the	audit daemon until terminated making
     them somewhat unwieldy for	live monitoring	applications such as host-
     based intrusion detection.	 For example, the log may be cycled and	new
     records written to	a new file without notice to applications that may be
     accessing the file.

     The audit facility	provides an audit pipe facility	for applications
     requiring direct access to	live BSM audit data for	the purposes of	real-
     time monitoring.  Audit pipes are available via a clonable	special
     device, /dev/auditpipe, subject to	the permissions	on the device node,
     and provide a "tee" of the	audit event stream.  As	the device is clon-
     able, more	than one instance of the device	may be opened at a time; each
     device instance will provide independent access to	all records.

     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 particu-
     lar, when an audit	pipe queue fills, records will be dropped.  Audit pipe
     devices are blocking by default, but support non-blocking I/O, asynchro-
     nous I/O using SIGIO, and polled operation	via select(2) and poll(2).

     Applications may choose to	track the global audit trail, or configure
     local preselection	parameters independent of the global audit trail
     parameters.

   Audit Pipe Queue Ioctls
     The following ioctls retrieve and set various audit pipe record queue
     properties:

     AUDITPIPE_GET_QLEN		 Query the current number of records available
				 for reading on	the pipe.

     AUDITPIPE_GET_QLIMIT	 Retrieve the current maximum number of
				 records that may be queued for	reading	on the
				 pipe.

     AUDITPIPE_SET_QLIMIT	 Set the current maximum number	of records
				 that may be queued for	reading	on the pipe.
				 The new limit must fall between the queue
				 limit minimum and queue limit maximum
				 queryable using the following two ioctls.

     AUDITPIPE_GET_QLIMIT_MIN	 Query the lowest possible maximum number of
				 records that may be queued for	reading	on the
				 pipe.

     AUDITPIPE_GET_QLIMIT_MAX	 Query the highest possible maximum number of
				 records that may be queued for	reading	on the
				 pipe.

     AUDITPIPE_FLUSH		 Flush all outstanding records on the audit
				 pipe; useful after setting initial preselec-
				 tion properties to delete records queued dur-
				 ing the configuration process which may not
				 match the interests of	the user process.

     AUDITPIPE_GET_MAXAUDITDATA	 Query the maximum size	of an audit record,
				 which is a useful minimum size	for a user
				 space buffer intended to hold audit records
				 read from the audit pipe.

   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 auditd(8).  How-
     ever, 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.

     The following ioctls configure the	preselection mode on an	audit pipe:

     AUDITPIPE_GET_PRESELECT_MODE  Return the current preselect	mode on	the
				   audit pipe.	The ioctl argument should be
				   of type int.

     AUDITPIPE_SET_PRESELECT_MODE  Set the current preselection	mode on	the
				   audit pipe.	The ioctl argument should be
				   of type int.

     Possible preselection mode	values are:

     AUDITPIPE_PRESELECT_MODE_TRAIL  Use the global audit trail	preselection
				     parameters	to select records for the
				     audit pipe.

     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 parameters, as
				     well as a set of per-auid masks.  These
				     parameters	are configured using further
				     ioctls.

     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.

   Audit Pipe Local Preselection Mode Ioctls
     The following ioctls configure the	preselection parameters	used when an
     audit pipe	is configured for the AUDITPIPE_PRESELECT_MODE_LOCAL preselec-
     tion mode.

     AUDITPIPE_GET_PRESELECT_FLAGS    Retrieve the current default preselec-
				      tion flags for attributable events on
				      the pipe.	 These flags correspond	to the
				      flags field in audit_control(5).	The
				      ioctl argument should be of type u_int.

     AUDITPIPE_SET_PRESELECT_FLAGS    Set the current default preselection
				      flags for	attributable events on the
				      pipe.  These flags correspond to the
				      flags field in audit_control(5).	The
				      ioctl argument should be of type u_int.

     AUDITPIPE_GET_PRESELECT_NAFLAGS  Retrieve the current default preselec-
				      tion flags for non-attributable events
				      on the pipe.  These flags	correspond to
				      the naflags field	in audit_control(5).
				      The ioctl	argument should	be of type
				      u_int.

     AUDITPIPE_SET_PRESELECT_NAFLAGS  Set the current default preselection
				      flags for	non-attributable events	on the
				      pipe.  These flags correspond to the
				      naflags field in audit_control(5).  The
				      ioctl argument should be of type u_int.

     AUDITPIPE_GET_PRESELECT_AUID     Query the	current	preselection masks for
				      a	specific auid on the pipe.  The	ioctl
				      argument should be of type struct
				      auditpipe_ioctl_preselect.  The auid to
				      query is specified via the ap_auid field
				      of type au_id_t; the mask	will be
				      returned via ap_mask of type au_mask_t.

     AUDITPIPE_SET_PRESELECT_AUID     Set the current preselection masks for a
				      specific auid on the pipe.  Arguments
				      are identical to
				      AUDITPIPE_GET_PRESELECT_AUID, except
				      that the caller should properly initial-
				      ize the ap_mask field to hold the
				      desired preselection mask.

     AUDITPIPE_DELETE_PRESELECT_AUID  Delete the current preselection mask for
				      a	specific auid on the pipe.  Once
				      called, events associated	with the spec-
				      ified auid will use the default flags
				      mask.  The ioctl argument	should be of
				      type au_id_t.

     AUDITPIPE_FLUSH_PRESELECT_AUID   Delete all auid specific preselection
				      specifications.

EXAMPLES
     The praudit(1) utility may	be directly executed on	/dev/auditpipe to
     review the	default	audit trail.

SEE ALSO
     poll(2), select(2), audit(4), audit_control(5), audit(8), auditd(8)

HISTORY
     The OpenBSM implementation	was created by McAfee Research,	the security
     division of McAfee	Inc., under contract to	Apple Computer Inc. in 2004.
     It	was subsequently adopted by the	TrustedBSD Project as the foundation
     for the OpenBSM distribution.

     Support for kernel	audit first appeared in	FreeBSD	6.2.

AUTHORS
     The audit pipe facility was designed and implemented by Robert Watson
     <rwatson@FreeBSD.org>.

     The Basic Security	Module (BSM) interface to audit	records	and audit
     event stream format were defined by Sun Microsystems.

BUGS
     See the audit(4) manual page for information on audit-related bugs	and
     limitations.

     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.

     The per-pipe audit	event queue is fifo, with drops	occurring 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 applica-
     tions to select which records are dropped,	possibly in the	style of pres-
     election.

FreeBSD	10.1			  May 5, 2006			  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=auditpipe&sektion=4&manpath=FreeBSD+10.0-RELEASE>

home | help